# Runtime Governance This directory is the machine-readable governance layer for Blueprint's AI runtime. The purpose is to move recurring operating requirements out of prompts and role-file prose into durable registries, schemas, validators, generators, and state-machine tooling. ## Ownership Model - `registries/`: canonical runtime policy data. - `schemas/`: structural contracts for registry and summary data. - `validators/`: executable checks that prove registries, docs, generated surfaces, and implementation agree. - `generators/`: scripts that produce operator-facing surfaces from registries. Authority principle: > AI may propose. Runtime may enforce. Validators may verify. Only canonical > transition engines may mutate authority state. In practice: - AI roles may recommend chunk status, approval, and next actions. - Runtime services and dispatchers may enforce registered actions. - Validators may verify policy, schema, docs, and runtime-surface consistency. - Lifecycle authority state must be mutated by canonical transition tooling, not by prompt-only instructions, stale summaries, or ad hoc manual edits. ## Enforcement Classes Every runtime policy should be classified as one of: - `Enforced`: backed by executable validation, generated output, schema, state-machine tooling, hook, or test. - `Advisory`: guidance only; useful to humans and AI but not a hard gate. - `Pending Enforcement`: accepted as required policy, but enforcement still needs implementation. Mandatory runtime behavior must not live only in chat history, short-term model context, role-file instructions, or untested Markdown. ## Carry-Forward Debt Unresolved runtime/governance debt is tracked in: ```sh ai/governance/registries/carry-forward-debt.yaml ai/governance/validators/validate-carry-forward-debt.sh ``` This registry preserves significant unresolved `Bad`/`Ugly`, runtime anomaly, validation gap, operator UX, reconciliation, and governance enforcement issues across chunk boundaries. It is the durable source for carried debt; final summaries may mention debt, but summaries are not the registry. Open `blocking` debt fails governance validation. Open `pending_enforcement` debt is machine-visible as pending enforcement. Open `advisory` debt remains visible without blocking when the current chunk scope is otherwise satisfied. Ready validation also checks chunk projection: when final governance sections reference unresolved debt or `Pending Enforcement`, the chunk must include a `## Carry Forward` projection from the canonical registry. ## Runtime Event Semantics Runtime/operator event classes are owned by: ```sh ai/governance/registries/runtime-event-semantics.yaml ai/governance/validators/validate-runtime-event-semantics.sh ``` The registry defines which events may request operator replies, approvals, or freeform data. Non-actionable, stale, or Codex-internal context must not render as an operator question. Telegram and other mobile surfaces should use the registry-backed semantics before showing reply instructions. ## Run Paths And Notification Scheduling Canonical orchestration paths, phase graphs, notification schedules, event emission rules, and Codex/local-agent permission classes are owned by: ```sh ai/governance/registries/run-paths.yaml ai/governance/validators/validate-run-paths.sh ``` The registry defines finite paths such as `implement_chunk`, `qa_only`, `repair_validation_failure`, `ready_transition`, `approval_boundary`, `close_commit`, `blocked_manual_decision`, `stale_artifact_cleanup`, and `runtime_note_delivery`. Notification delivery should be derived from run-path events and `runtime-event-semantics.yaml`, not from orchestration memory. The intended flow is: ```text run path selected -> phase executed -> canonical event emitted -> notification policy consumes event -> daemon/bridge delivers operator message -> delivery receipt or timeline event recorded ``` The run-path registry keeps a compatibility projection of local-agent permission buckets. The canonical permission policy is `runtime-permissions.yaml`. ## Runtime Permissions Trusted local runtime permission policy is owned by: ```sh ai/governance/registries/runtime-permissions.yaml ai/governance/validators/validate-runtime-permissions.sh --json ``` The registry distinguishes Codex host sandbox approval from Blueprint governance approval. Codex sandbox settings control host execution. Blueprint governance controls lifecycle authority, close/commit, dispatcher execution, operator approval, and authority-state mutation. Trusted local operations include repo inspection, scoped repo-local edits, runtime tests, governance validators, doctor/scorecard queries, Runtime API requests, and shell-wrapper tests. They should not depend on repeated Codex approval prompts in the trusted devcontainer/runtime. Blueprint approval boundaries remain explicit for close/commit, lifecycle authority mutation, dispatcher-owned execution, and registered daemon git actions. Operator approval remains required for external side effects such as pushes, package installs, external network access, secrets/env mutation, database mutation, destructive deletes, screenshot capture, and runtime-impact service restarts. The current enforced slice validates registry structure, docs/wrapper paths, trusted Codex launch policy, operation bucket consistency, forbidden operation semantics, authority-boundary classification, and the run-path compatibility projection. Runtime path execution and platform permission integration remain `Pending Enforcement` and must not be claimed as fully implemented. ## TypeScript Runtime Foundation The TypeScript runtime foundation lives under: ```sh ai/runtime/ ``` The runtime direction is: ```text AI reasoning -> deterministic TypeScript runtime -> validators -> daemon/dispatcher execution -> canonical registries/schemas/state ``` This foundation currently owns typed registry loading, shared runtime types, pure classification helpers, notification render-model preparation, a read-only CLI, migrated governance validator modules, and `node ai/runtime/dist/cli.js validate --tier fast|chunk|full`. Existing shell tools remain authoritative for side effects until focused migration chunks replace them with typed adapters and tests. Chunk 000102 adds the first local-only Runtime API daemon: ```sh ai/runtime/start-daemon.sh ai/runtime/status.sh --json ai/runtime/request.sh --method runtime.health ai/runtime/stop-daemon.sh ``` The daemon uses a Unix socket JSON-line transport under `.tmp/runtime-api/` and is supervised as a local trusted runtime service. Its initial methods are read-only/runtime-inspection oriented. Approval-boundary and authority-state mutations remain with the approved-action dispatcher, operator daemon, runtime-supervisor, and lifecycle transition tooling. Shell wrapper compatibility is incremental. Read-only shell/operator helpers may delegate to Runtime API methods and keep deterministic local fallbacks. Mutation wrappers must remain guarded and fail closed until their authority model is explicitly migrated. Runtime Core now also owns read-only operator-question and approved-action classification where migrated. That includes actionable versus stale approval state, consumed/executed audit records, and approval summaries. It does not execute approved actions or mutate lifecycle authority state; dispatcher and trusted-daemon boundaries remain canonical. Runtime Core also owns migrated read-only notification and Telegram render semantics where practical. It may classify event actionability, prepare transport-neutral notification models, prepare compact Telegram render models, summarize the command surface, and read latest run details. Telegram bridge transport, long polling, message sending, operator answers, approval creation, and dispatcher/daemon execution remain outside Runtime Core authority. Runtime Core now also owns migrated read-only scorecard and doctor aggregation where practical. It may summarize trusted runtime services, pending work, approval/actionability state, governance status, and carry-forward debt through Runtime API methods. Low-level process and shell probes remain adapter-backed, and recovery/execution actions remain with their guarded owners. Runtime Core also owns read-only dispatcher, operator-daemon, runtime-supervisor, Runtime API daemon, trusted-execution, and missing-action integration projections. These projections normalize status visibility only: approved-action execution remains dispatcher-owned, trusted local execution remains operator-daemon-owned, and service restarts remain supervisor-owned. `cfd-0001` failed-then-consumed dispatcher evidence remains visible without claiming close/commit idempotency is fixed. Runtime Core now owns read-only run-path scheduling semantics where practical. `run-paths.yaml` defines scheduler states, trigger types, phase classes, scheduled loops, duplicate-prevention rules, and bounded-autonomy stop conditions. Runtime API scheduling methods expose deterministic planning and health summaries only; they do not execute run-path phases or cross approval/dispatcher/daemon/supervisor boundaries. Runtime Core also owns a read-only runtime path harness for deterministic dry-run and fixture flow assertions. The harness proves scheduling, validation, notification rendering, and authority-boundary expectations without mutating lifecycle state, dispatching approved actions, running daemon actions, restarting services, or executing `close_commit`. Shell entrypoints are now classified as Runtime Core facades, bootstrap/ recovery tools, compatibility-only probes, or guarded authority owners. `ai/standards/shell-entrypoint-cutover.md` is the canonical cutover guidance. New governance/runtime logic should be implemented in Runtime Core first, with shell wrappers kept thin where practical. Runtime Core now owns the migrated pure validator logic for schemas, carry-forward debt, runtime event semantics, run paths, runtime permissions, and aggregate `governance-core` validation. Existing validator shell entrypoints remain stable compatibility wrappers. Runtime Core also owns the migrated read-only lifecycle/chunk validation logic for Ready-for-Human-Review evidence, lifecycle transition validation, role separation, QA verdict consistency, carry-forward projection, stale `Next` detection, and validation evidence checks. Lifecycle mutation remains guarded by `ai/chunks/transition.sh` and close/commit remains dispatcher-owned. Shell-heavy checks for generated surfaces and command projections remain in the MJS compatibility layer until their process behavior is migrated safely. ## Current Transition State The YAML registries added in chunk 000088 are the target governance source of truth. Some existing runtime surfaces still have an enforced compatibility registry, such as `ai/tools/telegram/command-registry.tsv`. Until the generator/validator migration completes, those existing enforced surfaces remain active and must not be weakened. Later chunks will validate and then generate compatibility projections from the YAML registries. ## Validators Chunk 000089 introduced the first executable governance checks: ```sh node ai/runtime/dist/cli.js governance validate --mode schemas --json node ai/runtime/dist/cli.js governance validate --json node ai/runtime/dist/cli.js validation-matrix --dry-run --json node ai/runtime/dist/cli.js governance validate --mode runtime-permissions --json ai/chunks/validate-ready-for-review.sh ``` The current checks are intentionally focused: - schema and YAML parse validation. - registry-to-schema validation where a matching schema exists. - Telegram TSV compatibility projection checks. - implementation and docs path checks. - dispatcher, daemon, and supervisor action registration checks. - validation-matrix dry-run for changed files. - advisory Ready-for-Human-Review gate checks. - runtime event/actionability semantic checks. - run-path graph, notification schedule, and local-agent permission checks. - runtime permission policy, trusted local operation, and Codex launch policy checks. Known `Pending Enforcement` items are reported by the validators and doctor rather than hidden in prose. The next governance chunks should reduce those items by generating help/docs and enforcing lifecycle transitions. ## Generators Chunk 000090 makes the operator command registry generate the normal operator-facing command surfaces: ```sh ai/governance/generators/generate-telegram-help.sh --write ai/governance/generators/generate-command-docs.sh --write ai/governance/generators/generate-runtime-command-table.sh --write ai/governance/validators/validate-generated-help.sh ai/governance/validators/validate-registry-doc-consistency.sh ``` Generated artifacts: - `ai/tools/telegram/generated-help.txt` - `ai/governance/generated/operator-command-table.md` - `ai/governance/generated/runtime-command-table.md` `operator-commands.yaml` owns command metadata. The existing Telegram TSV registry remains the live dispatch compatibility projection until a later chunk migrates dispatch itself, but `/help` and command docs must be generated and validated from YAML. ## Chunk Lifecycle Tooling Chunk 000091 adds the first executable lifecycle transition surface: ```sh ai/chunks/validate-transition.sh --to "Ready for Human Review" ai/chunks/transition.sh --to "Ready for Human Review" --dry-run ai/chunks/transition.sh --to "Ready for Human Review" ``` `ai/governance/registries/chunk-lifecycle.yaml` defines legal states, transitions, and Ready-for-Human-Review requirements. The transition helper validates the registry, chunk evidence, governance state, and final-summary sections before mutating a chunk status. It also reports the close/commit approval side effect as structured state so approval expectations are no longer implicit chat memory. Lifecycle role separation is part of the governance contract: - Developer owns implementation evidence and Developer pass history. - QA owns independent PASS/BLOCKED evidence. - Orchestrator owns transition coordination, approval-boundary reporting, and next action. `Ready for Human Review` is an orchestrated lifecycle state. It requires QA PASS evidence or explicit human/operator QA override plus transition-tool evidence. Developer-only validation is not sufficient. Chunk 000098 makes the role split validator-visible for Ready transitions: Developer evidence must include `Role: Developer`, QA review must include `Role: QA`, and handoff must include `Role: Orchestrator`. Lifecycle validators reject missing or ambiguous role-authority evidence. Automatic creation of the Ready-for-Human-Review close/commit approval remains reported as `Pending Enforcement` until a later chunk wires that side effect into the transition command or dispatcher policy. ## Runtime Governance Skills Chunk 000092 adds repo-native skills under `ai/skills/` for recurring runtime governance reviews: - runtime governance review. - close/commit lifecycle. - drift root-cause analysis. - approval flow review. - operator surface review. - QA contract review. Skills are advisory workflow guides. They must point to registries, validators, and trusted runtime commands as authority; they must not introduce new prose-only policy.