Phase readiness contract
The phase readiness contract makes phase completion an explicit, auditable decision instead of an impression. A KBD phase adopts a versioned, content-digested exit contract before execution; the Plan→Execute gate refuses to dispatch work against a phase that has no valid adopted contract; and a terminal evaluator closes the phase only when every adopted scenario has valid PASS evidence bound to the current run and the adopted contract digest.
This page documents the shipped behavior, installation, a practical example, and the exact limits of what is enforced.
The planning contract
A phase contract is a JSON document at
.kbd-orchestrator/phases/<phase>/adopted-contract.json declaring:
- Identity — project, run, and phase IDs the contract is bound to.
- Goal and functional scope — what the phase must deliver, plus explicit exclusions.
- Scenario matrix — the acceptance surface. Every scenario names a production entry point, its real collaborators, an observable oracle, and at least one negative control, plus the task that owns it.
- Budgets — declared ceilings for time, tool calls, repair attempts, and an
absolute no-progress limit. Token budgets may be
UNKNOWN; the declared fallback (time + tool-call bounds) governs in that case. - Verification packet — the post-implementation integration commands, expected effects, receipts, and stop conditions.
Contracts are adopted through the canonical writer,
shared/scripts/kbd-contract-adopt.sh, which records the adoption as an
immutable canonical decision (visible in prometheus kbd audit) keyed to the
contract's SHA-256 digest. Material changes require a new adoption that
supersedes the previous one (--supersedes), so the full lineage stays in
history. Re-adopting byte-identical content is an idempotent no-op
(ALREADY-ADOPTED); history is never rewritten.
The readiness gate
shared/scripts/kbd-phase-readiness-check.sh is the read-only checker. It
verifies, in order:
- an adoption decision exists and is unambiguous for the contract path,
- the contract identity matches the current project/run/phase,
- the recorded digest still matches the recomputed digest (a drifted contract
is
REJECT-STALE, exit 4 — fix by re-adopting, never by editing history), - every scenario's owning task exists in the phase
tasks.json, - contract quality: the scenario matrix has real production entries, oracles, and negative controls; budgets are declared with a token fallback; a verification packet exists.
The checker exits 0 READY only when all of these hold (2 BLOCKED,
3 REJECT-IDENTITY, 5 MALFORMED otherwise). The Plan→Execute stage gate in
skills/process/kbd-process-orchestrator/shared/lib/stage-gate.sh runs this
same validation and refuses dispatch when it fails — and it refuses to dispatch
any phase that is already closed.
Execution flow
- Create and activate the phase; write its goals.
- Author the contract and adopt it with the canonical writer.
- Confirm
READYwith the checker. - Execute the phase's tasks. Implementation completes before verification: the boundary packet runs once, after production changes are coherent.
- Collect scenario evidence keyed to the adopted contract digest and current run.
Evidence-bound closure
Closure has one authority: the typed canonical runtime (issue #192).
prometheus kbd phase close records a phase disposition bound to project,
run, phase, the bound contract digest and the evidence digest, and a PASS
moves the phase to complete in the same event. Every reader — the terminal
evaluator, the Plan→Execute gate, Reflect, child-exit and next-phase — reads
prometheus kbd phase disposition, which reports one token:
UNBOUND, OPEN, CLOSED, REFUSED_BLOCKED or REFUSED_FAIL. Decision
summary text is never interpreted as closure, so a recorded string cannot fake
or hide one.
Adoption binds the phase (prometheus kbd phase bind-contract) and writes a
byte-exact snapshot phases/<id>/adopted/<digest>.json (its sha256 is the
digest). From then on the runtime refuses phase transition --status complete|cancelled for that phase: it closes only through a PASS disposition.
shared/scripts/kbd-phase-close-eval.sh is the terminal evaluator. It reads
the required scenarios and budget ceilings from the bound snapshot, never
from the mutable working contract, and records through phase close:
- every bound scenario must have PASS evidence (an entry id
SorS-<sub>); evidence entries for scenarios outside the bound contract are reported asignored-unadoptedand change nothing; - evidence must name the current project, run and bound digest;
- source freshness is recomputed at evaluation time;
- budget accounting must be present and within the bound ceilings (below).
A PASS prints CLOSED. Re-running with byte-identical evidence is
ALREADY-CLOSED and appends nothing; different evidence after closure exits 6
(CLOSED-DIFFERENT-IDENTITY) because a closed phase is immutable. Unmet or
unverifiable criteria record REFUSED_FAIL (exit 3) or REFUSED_BLOCKED
(exit 2); the phase stays open. If the canonical writer rejects the write, the
evaluator prints WRITER-FAILED and exits 5 on both the PASS and the refusal
paths — it never claims a disposition it did not record.
Closing is not continuing
A closed phase starts no successor on its own. /kbd-next-phase refuses a
bound phase that is not CLOSED (exit 2) and refuses a CLOSED one without an
operator-signed start-successor manifest (exit 4, nothing written). With
the manifest, one runtime event defines and activates exactly the named
successor; a rerun reports ALREADY-STARTED. While a closed phase awaits its
successor, the runtime admits activation only of an ancestor (so child-exit
works) or the authorized successor. Reflection text becomes goals.md
proposals for the successor, never adopted scope.
Scope amendments need signed operator authority
Changing a bound contract is a material amendment. kbd-contract-adopt.sh
needs --supersedes <decision> --amendment <manifest> --signature <sig>, and
the runtime verifies the signature with ssh-keygen -Y verify under the
namespace prometheus-kbd-scope-amendment against
~/.config/prometheus/kbd-scope-allowed-signers (no flag or environment
override; a missing file fails closed). The manifest names the project, run,
phase, previous and new digests and the exact scenario diff; each manifest is
single-use. Only scenarios the amendment adds or modifies need fresh
evidence; unchanged scenarios may carry evidence (scenarioDigest plus
carriedFrom). Memory, reviewer findings, imported contracts and fields such
as "approved": true have no path into this check.
shared/scripts/kbd-scope-authority-template.sh amend-contract|start-successor
prints the canonical manifest from canonical state and the exact signing
command. It never signs. See shared/config/kbd-scope-allowed-signers.example.
Budget accounting and the missing-accounting rule
The evidence packet must carry a budgetConsumption header naming its source
and classing each value as measured, estimate, or unknown. The evaluator
compares self-reported cumulative consumption against the bound snapshot's
ceilings (base budgets plus extensions; the latest resultingCeilings wins):
- exceeded →
BLOCKED (budget-exceeded); - unknown or missing on an enforceable dimension (time, tool calls,
repairs) →
BLOCKED (budget-unmeasured); tokens may stayunknownunder the declared fallback; - at ceiling → work already complete closes, labelled
budget-note=budget-exhausted; a ceiling never substitutes for evidence; - missing header →
BLOCKED (budget-consumption-missing).
The runtime keeps a high-water mark per dimension: a later disposition that
reports less is refused (budget-regressed), so counters never reset across
refusals, amendments or restarts. Budget extensions are part of the
digest-bound contract, so adding one to a bound contract is a signed
amendment.
Installation
The checker, adoption writer, evaluator, and gate ship in both distribution
payloads (dist/plugins/{claude,codex}/prometheus-skill-pack):
node scripts/install.js --scope user # per-user install
node scripts/generate-skill-system-distribution.js --check # payload consistency
Set HOME/XDG_DATA_HOME to isolate a scratch install. The installed payload
carries identical file digests to the source tree for these scripts.
A practical example
# 1. adopt the phase contract (canonical, digest-bound)
bash shared/scripts/kbd-contract-adopt.sh \
.kbd-orchestrator/phases/my-phase/adopted-contract.json
# → ADOPTED path=… sha256=… planRevision=… decision=contract-adoption-…
# 2. confirm readiness before Plan→Execute
bash shared/scripts/kbd-phase-readiness-check.sh --phase my-phase \
--phase-dir .kbd-orchestrator/phases/my-phase
# → READY phase=my-phase contract=… digest=… planRevision=…
# 3. execute the phase's tasks (implementation first), collect evidence
# 4. close with an evidence packet including budgetConsumption
bash shared/scripts/kbd-phase-close-eval.sh --phase my-phase \
--evidence-file evidence.json
# → CLOSED phase=my-phase verdict=PASS evidence=sha256:… entries=N
# a byte-identical replay → ALREADY-CLOSED (zero new records)
# 5. continue only with operator authority
bash shared/scripts/kbd-scope-authority-template.sh start-successor \
--phase my-phase --successor my-next-phase --title "My next phase" \
--reason "operator approves the next scope" > successor.json
ssh-keygen -Y sign -f ~/.ssh/id_ed25519_sk -n prometheus-kbd-scope-amendment successor.json
bash skills/process/kbd-process-orchestrator/skills/kbd-next-phase/scripts/kbd-next-phase.sh \
--authorize-successor successor.json --signature successor.json.sig
If evidence.json omitted budgetConsumption, step 4 would instead print
BLOCKED … reason=budget-consumption-missing and record a refusal.
Limits and disclosures
Read these before relying on the mechanism:
- Where enforcement lives. The runtime enforces the closure invariants for
every caller of
prometheus kbd: a bound phase cannot be completed byphase transition, a closed phase cannot be re-opened, re-activated or given new work, and a successor or amendment needs a verified signature. The evaluator's scenario and budget analysis is still a shell convention invoked through the skill flow. Nothing here intercepts arbitrary tools or edits outsideprometheus kbd(host enforcement is #185). - What a signature proves. Any key whose private half a local agent can use
unattended records intent, not human approval. Use a FIDO (
sk-*) key or a passphrase the agent cannot supply; the allowed-signers file itself is readable and writable by local processes. - Disclosed test seams.
KBD_READINESS_STATUS_FILE,KBD_PHASE_DISPOSITION_FILE,--status-file,--disposition-fileand--decision-sinkoverride where state is read and dispositions are written. They exist for fixtures and are visible in every receipt that uses them; a decision sink can never close a phase. - Legacy phases. Phases that were never bound keep their previous
behaviour, including direct
phase transition --status complete. Journals written before typed closure replay unchanged; olderprometheusbinaries cannot read journals that contain the new events, so upgrade the CLI, control plane and both packs together. - Self-reported accounting. Budget consumption values are agent-authored self-reports, not independent telemetry and not tamper-proof. The budget predicate proves only the declared-limit comparison and the refuse/admit behavior.
- Demonstration scope. The installed-payload lifecycle was demonstrated on a scratch install (readiness READY → gate pass → CLOSED with sourced accounting → missing-accounting BLOCKED → bound replay ALREADY-CLOSED). That qualifies the installed shell workflow as demonstrated; host-side automatic enforcement (#185) and the broader #184 successor scope remain open future work.
- Local-only validation. All checks run locally. Hosted CI output is never acceptance evidence.
Evidence and history
The candidate qualification for this feature, including the full scenario
receipts (RC-01–RC-07), boundary results, and reconciliation records, is
preserved at
docs/releases/1.12.2-candidate-qualification.md
in the repository. Issue #184
remains open for the separately scoped successor corpus.