# Runtime Tooling Governance

This standard owns cross-cutting governance for operator-visible runtime
tooling. Keep detailed behavior in the specialized standards:

- top-level runtime operating procedure:
  `ai/standards/runtime-sop.md`

- operator questions and approval validity:
  `ai/standards/operator-questions.md`
- run summaries and Telegram notifications:
  `ai/standards/operator-notifications.md`
- trusted daemon execution:
  `ai/standards/trusted-operator-daemon.md`
- local/dev runtime ownership:
  `ai/standards/local-dev-runtime.md`

Use this file for the rules that must stay consistent across those areas.
Machine-readable target registries live under `ai/governance/registries/`.
During the migration, registry-backed validators and generators are introduced
incrementally; do not treat target registry prose as enforced until a validator,
generated artifact, schema, or test backs it.

## Close/Commit Approval Semantics

When the operator says "complete and commit", "close and commit", "commit
this", or equivalent orchestration-completion wording after a standard run,
Codex must create exactly one fresh `close_commit` approval request for the
current reviewed state.

The approval request may be answered through Telegram or through the local
console/operator-question path. Whichever valid answer arrives first may
authorize execution.

Approval authorizes deterministic dispatcher execution. It does not authorize
direct Codex continuation, raw Git commands, Codex platform escalation, tmux
pane scraping, or hidden auto-continue behavior.

Execution must happen only through:

- `ai/tools/approved-action-dispatcher`
- trusted daemon registered actions delegated by the dispatcher

The close/commit path must reject:

- stale approvals.
- denied approvals.
- duplicate or late approvals.
- already-executed approvals.
- approvals whose target chunks/files cannot be reconstructed exactly.
- approvals whose git, validation, runtime, or target state changed after the
  question was created.

Do not reuse previous close/commit approvals. If state changed or a previous
approval was not executed in the same valid lifecycle, request a fresh
operator-question approval.

Before execution, run the dispatcher dry-run or equivalent validation for the
accepted question. The dry-run must make the action, target chunks/files, git
state, validation state, approval source, and stale/blocking reasons visible.

## Operator-Facing Docs/Help Synchronization

When changing operator-visible runtime behavior, the same change must update
the relevant operator-facing references in the same chunk.

This applies to changes in:

- daemon actions.
- dispatcher actions.
- Telegram commands or answer formatting.
- operator-question behavior.
- runtime helpers.
- doctor or scorecard fields.
- action timeline behavior.
- CLI/runtime tooling.
- operator-facing workflows.
- status, help, or recovery output.

Update the applicable surfaces:

- helper `--help`, status, or usage text.
- tool README files.
- canonical standards.
- operator guidance and workflow handoffs.
- Telegram `/help`, `/details`, `/pending`, `/timeline`, or summary text when
  applicable.
- tests or fixtures that assert operator-visible output.

If no operator-facing update is needed, the chunk notes and QA review must say
why. Do not leave changed runtime behavior discoverable only through source
code or implementer memory.

Telegram command surfaces must use Runtime Core/API validation as the canonical
operator-surface check. The TSV may remain only as a transport compatibility
projection and must be checked through the Runtime API. Run:

```sh
node ai/runtime/dist/cli.js telegram operator-surface --json
```

for any chunk that touches Telegram commands, timeline output, operator
questions, runtime notifications, dispatcher approvals, or operator-facing
runtime SOPs.

The target cross-surface command registry is
`ai/governance/registries/operator-commands.yaml`. Until generated help/docs
are migrated to it, the TSV remains the enforced Telegram compatibility
projection and must stay aligned with the target registry.

## QA Enforcement

QA must block runtime/tooling changes when operator-visible behavior changed but
help, docs, status output, or Telegram/operator references were not updated.

Examples:

- A Telegram command is added but Telegram help or command docs are stale.
- A dispatcher action changes but dispatcher docs, standards, or dry-run output
  are stale.
- A daemon behavior changes but README/status/recovery docs are stale.
- A scorecard field changes but runtime docs or tests still describe the old
  field.
- A close/commit flow changes but approval semantics still imply Codex wakeup,
  raw Git, or Codex platform escalation.
- Telegram `/help`, command handlers, command registry, README, and SOP
  references disagree.

QA evidence should include either representative output or a concrete
not-applicable rationale for every operator-visible runtime change.