@acrasie/dev-flow 0.0.0-stage → 1.0.1

package/docs/adr/0030-unify-product-domain-and-technical-design-interviews.md

@@ -0,0 +1,240 @@
+# ADR 0030: Unify Product, Domain, and Technical Design Interviews
+
+## Status
+
+Implemented in TaskState V6 with ADR 0031.
+
+## Context
+
+Current INTAKE captures an adaptive brief and current SHAPE discovers repository facts,
+but the workflow has no durable domain-modeling discipline and no ordinary interview for
+material technical choices. ADR 0026 proposed a dependency-directed technical interview,
+yet kept the dependency graph inside SHAPE and did not model terminology, business rules,
+scenarios, documentation promotion, or a shared question boundary.
+
+Useful design-interview practices include sharpening ambiguous language, confronting
+claims with code and documentation, probing rules with edge cases, discovering facts
+instead of asking the user, and traversing decisions by prerequisite. Copying an external
+workflow would be wrong for Dev Flow: its lifecycle requires one active resumable
+question, strict phase authority, deterministic state validation, read-only shaping,
+digest-bound approval, and selective invalidation.
+
+TaskState V5 shipped in v0.3.1 with the native BUILD boundary. ADR 0031 now requires a
+V6 schema break for ASSURE. This target lands in the same coherent V6 transition so
+SHAPE and the canonical Change Contract are rewritten once. Earlier local task state
+fails explicitly; runtime provides no migration or dual-schema compatibility.
+
+## Decision
+
+### Use one lifecycle-bound semantic protocol
+
+Add internal `design-decisions` skill. It is not an autonomous brainstorming command.
+The parent Dev Flow skill supplies typed state, phase ownership, evidence, and current
+frontier; the parent alone persists results.
+
+The protocol:
+
+- detects material ambiguity and decisions;
+- proposes domain scenarios and technical alternatives;
+- ranks the currently unblocked frontier;
+- emits at most one active question;
+- normalizes explicit answers into typed records; and
+- declares semantic coverage when no material uncertainty remains.
+
+The protocol does not require a second routine model call. Initial INTAKE evaluation
+returns Product Baseline progress, domain deltas, frontier analysis, and an optional
+question together. SHAPE Discovery returns evidence, technical decision candidates,
+frontier analysis, and an optional question together. A dedicated reevaluation occurs
+only after an answer, material invalidation, or new evidence.
+
+### Share orchestration, preserve authority
+
+TaskState gains transversal `design` state containing one active question and one typed,
+acyclic dependency graph. Payloads remain in their owning records:
+
+- INTAKE owns `ProductBaseline`, terminology, business rules, domain scenarios, and
+  business-context boundaries needed by the task;
+- SHAPE owns repository evidence and material technical decisions;
+- the canonical Change Contract owns approved implementation and documentation work.
+
+Question variants are `product`, `terminology`, `domain_rule`, and `technical`. Product
+and domain questions run in `intaking` or `awaiting_intake_decision`; technical questions
+run in new `awaiting_shape_decision`. Exactly one question may be active across the task.
+Every question persists its owner, prerequisites, prior role, direct consequences,
+recommendation data where applicable, and selection reason before display.
+
+The full unblocked frontier remains internal. A model scores impact, irreversibility,
+risk, uncertainty, and branches unlocked with bounded reasons. Runtime rejects blocked
+or authority-invalid candidates, then applies stable deterministic tie-breaking. Resume
+re-renders the exact selected question without another model call unless a dependency
+changed.
+
+### Replace Intake Brief with a stable Product Baseline
+
+`ProductBaseline` has five mandatory task-bounded dimensions:
+
+1. objective;
+2. affected users and product value;
+3. scope and boundaries;
+4. observable success and validator; and
+5. product risks and determining constraints.
+
+Each dimension has value or justified `not_applicable`, provenance, status, and graph
+dependencies. Missing and unknown are not complete. Explicit request content can resolve
+dimensions without redundant prompts.
+
+INTAKE performs targeted documentary discovery of applicable guidance, an approved
+Project Engineering Profile, domain documents, ADRs, and directly relevant contracts.
+It does not scan implementation generally. A question is required only when a product
+or domain answer can change observable behavior, actors or permissions, an invariant or
+exception, a bounded-context boundary, data meaning, success, scope, risk, or
+compatibility.
+
+When viable interpretations exist, questions present two or three non-dominated choices,
+one recommendation, confidence, consequences, and free-form input. If choices would
+invent unknown business meaning, use a targeted open elicitation question. A material
+normalization of free-form input requires targeted confirmation; editorial rewriting
+does not.
+
+### Model domain knowledge as three separate registries
+
+The design state owns task-local candidate records:
+
+- `DomainGlossaryDelta`: canonical contextual term, definition, accepted aliases,
+  rejected or deprecated terms with reasons, related terms, optional examples and
+  non-examples, provenance, status, and dependencies. It contains no implementation
+  detail.
+- `DomainRule`: context, linked terms, actors, conditions, outcome or invariant,
+  exceptions and limits, provenance, status, dependencies, and child `DomainScenario`
+  records. Scenarios describe starting situation, action/event, expected or forbidden
+  result, and nominal, boundary, exception, or contradiction angle.
+- `DecisionCandidate`: durable decision context, forces, viable and excluded
+  alternatives, evidence, recommendation, confidence, explicit selection,
+  consequences, ADR qualification, dependencies, status, and proposed destination.
+
+Domain modeling activates by default only when a material trigger exists. It is bounded
+to current task. Adjacent observations without material dependency do not enter the
+graph or silently widen scope.
+
+A domain rule becomes resolved through adaptive stress testing: positive behavior,
+material boundary or counter-example, and confrontation with available evidence. A
+trivial explicit rule may close without another user question when one strong source
+proves it. A contradiction cannot close silently. Existing domain documentation is the
+product baseline; code and tests prove current behavior, not desired behavior. The user
+may explicitly change the baseline, producing dependent domain and technical deltas.
+
+### Interview material technical decisions inside SHAPE
+
+`TechnicalDecision` replaces the narrow Decision Escalation record. It stores
+materiality reason, prerequisites, evidence, viable and excluded options,
+recommendation, confidence, consequences, selection, status, and exact resume role.
+
+Architecture boundaries, major frameworks or dependencies, data or migration,
+cross-service contracts, security/privacy, compatibility, concurrency, material
+performance/cost/operations/rollback, and approved profile exceptions are material.
+Repository-conforming reversible implementation details remain agent-owned.
+
+Discovery obtains facts before questions. Planning cannot inspect the repository; a new
+fact creates one targeted Discovery Target and a new material choice creates one
+Technical Decision. Evidence proving product infeasibility creates a linked INTAKE
+question rather than duplicating product authority inside SHAPE.
+
+### Make invalidation and completion deterministic
+
+The task-level graph contains typed identities and dependencies only; registry payloads
+are never copied into it. Runtime validates acyclicity, allowed ownership edges, one
+active question, frontier eligibility, and transitive invalidation. Changing one answer
+invalidates only dependent decisions, evidence, criteria, tasks, validations, risks, and
+projections.
+
+One response may resolve several explicitly answered nodes as one atomic transaction.
+A material inferred normalization requires confirmation. Partial application is
+forbidden. “Choose for me”, silence, deferral, or a request to advance never resolves a
+material decision. User may answer, reduce scope so the branch disappears, or cancel.
+
+Interview completion requires both a semantic declaration of no material uncertainty
+and deterministic proof: all required nodes resolved, no active contradiction or stale
+dependency, current evidence/profile, and an explicit disposition for every durable
+domain delta. Planning may reopen only a targeted branch. No question cap, periodic
+checkpoint, estimated-cost gate, or duplicate SHAPE approval exists.
+
+### Approve before projecting domain knowledge
+
+Resolved domain records use this lifecycle:
+
+```text
+proposed -> resolved -> approved -> projected
+               \-> invalidated
+```
+
+Before GATE, all records remain structured task state. Each durable delta must have one
+disposition: `project`, `already_documented`, `task_local`, or `policy_forbidden`, with
+proof or reason. Material rules trace to acceptance criteria; observable scenarios are
+validation candidates. Decision Candidates become ADR work only when all four gates
+hold: durable beyond the task, materially costly to reverse, real trade-off among viable
+alternatives, and surprising without recorded rationale.
+
+GATE includes deltas and dispositions in the canonical contract digest. BUILD applies
+approved documentation work through targeted semantic patches, never whole-file
+regeneration. ASSURE verifies allowed paths, fingerprints, expected identities and
+links, preservation of unrelated human content, and semantic fidelity. Successfully
+projected repository documents become durable authority; task state retains references,
+fingerprints, and receipts.
+
+Destination resolution follows policy/configuration, approved Project Engineering
+Profile, detected repository convention, then portable defaults. If no setup exists,
+Dev Flow recommends `$dev-flow init` once but does not block unless policy or an
+irreducible destination conflict requires it. Portable defaults are
+`docs/domain/glossary.md`, `docs/domain/rules.md`, and `docs/adr/`, with context-specific
+subdirectories and `docs/domain/context-map.md` when needed.
+
+Project INIT gains adaptive `domain_documentation` profile data for context mode,
+document paths, ADR location/format, language, identities, and link conventions. It
+discovers existing conventions first and asks only unresolved durable choices.
+
+### Bound persistence, failures, visuals, and testing
+
+Add routing stage `design`. Its route is resolved once from the immutable run snapshot
+and reused by fused INTAKE/domain evaluations and SHAPE technical-decision evaluations.
+Effort scales with risk, ambiguity, and dependency-graph depth. Discovery keeps its
+separate fact-finding route; a short prompt never justifies silently substituting a less
+capable design route. Routing identity and bounded usage counters persist without
+decision content.
+
+Persist normalized records, source references, exact active question, invalidations,
+and compact selection reasons—never transcript, hidden reasoning, raw prompts, large
+code excerpts, credentials, or external payloads. Stable IDs and enums use English;
+questions use the user's dominant language; projections follow repository language.
+
+Use the cheapest visual that materially resolves a decision: ASCII, Mermaid, isolated
+HTML/CSS, then Excalidraw or generated image. Full graph is shown only on request or
+when complexity makes it necessary. No fake progress percentage is derived from a
+frontier that may grow.
+
+Invalid semantic output receives deterministic syntax repair when meaning is unchanged,
+otherwise one targeted retry. Second failure preserves previous state and creates a
+typed block. Testing combines deterministic schema/DAG/frontier/transition/invalidation
+tests, contractual fixtures, and versioned model evals for materiality, question quality,
+scenario quality, recommendation quality, and non-invention.
+
+### Deliver as one coherent V6 contract
+
+Implementation may proceed in verified internal layers, but public activation is
+atomic across runtime, state schema, skills, normative contracts, projections, tests,
+and distribution. TaskState advances to V6 jointly with ADR 0031. No compatibility path
+or migration is provided for earlier local task state; legacy state fails with a clear
+diagnostic. Obsolete structures and branches are removed rather than retained behind
+compatibility code.
+
+## Consequences
+
+- INTAKE becomes a task-bounded product and domain design boundary rather than a brief
+  field collector.
+- SHAPE gains explicit user ownership for material technical choices without asking for
+  discoverable facts.
+- Domain terminology, rules, scenarios, technical decisions, acceptance criteria, and
+  documentation share traceable dependencies without sharing payload ownership.
+- Stronger state and eval requirements increase implementation size, but prevent
+  invisible assumptions, lossy resume, and uncontrolled documentation writes.
+- The existing target in ADR 0026 is superseded. Current runtime remains authoritative
+  until this target lands atomically.

package/docs/adr/0031-make-assure-the-success-boundary.md

@@ -0,0 +1,205 @@
+# ADR 0031: Make ASSURE the Success Boundary
+
+Supersedes ADR 0025.
+
+## Status
+
+Implemented in TaskState V6.
+
+## Context
+
+Before TaskState V6, public lifecycle presented five macro-phases followed by `finished`:
+
+```text
+INTAKE -> SHAPE -> GATE -> BUILD -> ASSURE -> finished
+```
+
+`finished` is not a phase, but persisting it as a sixth visible lifecycle node duplicates
+the success already proved by a valid Assurance Receipt. ASSURE also spreads its work
+across `reviewing`, `resolving_assure`, and `verifying`, even though review, correction,
+and verification are operations inside one user-facing phase. Re-running fresh BUILD
+checks in ASSURE wastes tokens and time when no later write invalidated them.
+
+## Decision
+
+The public lifecycle has exactly five phases and ends in ASSURE:
+
+```text
+INTAKE -> SHAPE -> GATE -> BUILD -> ASSURE
+```
+
+- Remove persisted `finished`. A valid current Assurance Receipt derives successful
+  completion; status and receipt cannot disagree.
+- Replace `reviewing`, `resolving_assure`, and `verifying` with one internal `assuring`
+  status. Review, correction, and checks are operations, not states.
+- Every acceptance criterion receives during SHAPE an expected outcome, verifier kind
+  (`command`, `model-inspection`, or `user-observation`), and evidence requirement.
+- Checks executed during BUILD count when their command identity, result, and workspace
+  fingerprint remain current. A later relevant write invalidates their evidence.
+- ASSURE runs only missing or invalidated checks. Deterministic checks run before any
+  required model review.
+- Deterministic policy, never unconstrained agent choice, triggers model review from
+  verifier requirements, applicable risk, out-of-scope diff, or insufficient
+  deterministic evidence.
+- Combine triggered model concerns into one bounded review call. Use separate specialist
+  passes only when policy explicitly requires expertise or isolation.
+- Do not impose a global ASSURE correction budget. Track stable `issue_id` identities;
+  after two failed corrections for the same stable issue, invoke `debug-root-cause`.
+  Use `blocked` only for an external dependency and `failed` only for a demonstrated
+  irreparable outcome.
+- Persist only a compact structured evidence index in TaskState: evidence identity,
+  covered subjects, verifier kind and identity, result, observed fingerprint, detail
+  reference, and digest. Keep command output and explanatory prose in the logical
+  artifact or logs. The Assurance Receipt summarizes the evidence index.
+- Use `user-observation` only when proof cannot be automated. Batch all outstanding
+  human observations into one request and persist the explicit answer as evidence; a
+  model cannot substitute for the user.
+- A policy-triggered model review uses one independent read-only reviewer with a fresh,
+  bounded capsule containing only triggered criteria, risks, diff, and evidence. The
+  implementing parent owns corrections; full conversation history is excluded.
+- Keep the Assurance Receipt minimal: task identity, contract digest, verified
+  snapshot fingerprint, evidence-index digest, completion time, and receipt digest.
+  Runtime proves exact coverage before emission; the receipt does not duplicate
+  criteria, checks, or evidence references.
+- Evidence freshness is conservative and hybrid. Scoped fingerprints are allowed only
+  for a scope declared deterministically by SHAPE or policy; all other evidence uses the
+  global workspace fingerprint. The final receipt always binds the complete snapshot.
+- Completing ASSURE appends `assure.completed` without changing status from `assuring`.
+  A valid receipt makes that state terminal and immutable. Render the public boundary as
+  `[DEV FLOW · ASSURE ✓]`; do not introduce an `assured` or other success status.
+- After success, return a bounded user summary: result, major changes, validation/review
+  performed, and material limits. Link to detailed evidence instead of repeating the
+  complete criterion-to-evidence map.
+- Metrics and benchmark use derived outcome `success` when the receipt is valid. They do
+  not retain `finished` as an outcome alias; explicit irreparable termination remains
+  outcome `failed`.
+- Atomically checkpoint the compact evidence index after every costly operation: command
+  check, model review, or human observation. Resume reuses each still-fresh checkpoint;
+  it does not wait until ASSURE completion or write redundant per-criterion checkpoints.
+- Deduplicate deterministic work by stable check identity. Execute the minimal set of
+  checks covering all criteria plus repository/policy-mandatory global checks; one
+  evidence record may cover multiple subjects.
+- Independent review returns a bounded structure only: verdict per subject and findings
+  containing stable `issue_id`, severity, location, evidence, and required correction.
+  It does not restate the plan, diff, or conversational history.
+- Deterministic policy classifies blocking findings. Acceptance violations, correctness
+  regressions, security issues, and applicable-risk violations block completion. Style
+  or preference without an approved requirement is non-blocking and is not corrected
+  automatically; the reviewer cannot redefine this threshold.
+- Before model review, classify out-of-scope diff deterministically. Correct an accidental
+  local reversible change natively; send a material contract change through SHAPE and
+  GATE; invoke review only when classification remains ambiguous.
+- Execute deterministic checks through a policy/SHAPE-declared dependency DAG ordered by
+  cost and signal. Run cheap prerequisites first; a failure skips its dependants and
+  model review until corrected instead of spending work on knowingly stale inputs.
+- Apply the same declared-scope invalidation to review evidence. A correction invalidates
+  overlapping review subjects; a globally fingerprinted review reruns after any write.
+  Unrelated scoped review evidence remains reusable.
+- An approved acceptance criterion cannot become `not_applicable` inside ASSURE. A change
+  in applicability returns through SHAPE and GATE. Only a predeclared conditional check
+  may resolve `not_applicable`, with deterministic evidence for its condition.
+- If the batched human-observation request receives no answer, persist the exact pending
+  request and enter `blocked` with resume target `assuring`. Resume re-renders it without
+  model work or rerunning still-fresh checks.
+- A negative human observation creates a stable issue. Correct it locally when possible,
+  then request only invalidated observations again. User refusal or an unmet external
+  dependency blocks; green automated checks cannot override explicit negative evidence.
+- Remove the routed `verify-change` model skill. SHAPE defines evidence requirements,
+  the parent executes deterministic commands, and runtime computes exact coverage and
+  emits the receipt. The only ASSURE model call is policy-triggered independent review;
+  no final model synthesizer restates deterministic evidence.
+- Retain the `review-change` skill and `review` route, but reduce them to one consolidated,
+  structured, policy-triggered read-only review. Remove review lanes and the arbitrary
+  three-cycle cap; repeated stable issues follow the shared root-cause rule.
+- ASSURE completion is an immutable historical success for its verified snapshot. Later
+  workspace changes neither reopen the task nor invalidate its receipt; further changes
+  require a new task and contract.
+- An unplanned BUILD command counts toward required coverage only when runtime can match
+  its normalized identity and observed result exactly to a compatible predeclared
+  evidence requirement. Otherwise it remains supplemental evidence and cannot replace
+  required proof.
+- Complete ASSURE in one atomic transaction: validate exact coverage, freeze the evidence
+  index, create the receipt, and append `assure.completed`. No persisted state may expose
+  an event without its receipt or a receipt without its event.
+- Before GATE, SHAPE projects acceptance criteria, applicable risks, and mandatory global
+  checks into one coverage graph bound to the approved contract. ASSURE cannot invent a
+  late requirement; a material policy change invalidates approval and returns through
+  SHAPE and GATE.
+- At completion, runtime deterministically selects the canonical current passing evidence
+  subset that covers the graph. The receipt binds this compact `completion index`;
+  supplemental observations remain referenced outside the receipt.
+- SHAPE compiles the coverage graph before GATE into a canonical deduplicated operation
+  set and stable evidence preferences. ASSURE executes missing operations and applies
+  those preferences; it runs no exact or heuristic set-cover solver at completion.
+- Checks in one dependency-DAG layer may run concurrently only when declared read-only
+  and concurrency-safe. Policy bounds concurrency; all other checks run sequentially.
+- Do not inject full command output into model context. Passing checks return structured
+  identity/result only; failures return the shortest decisive excerpt plus a reference
+  to the complete log.
+- Each operation declares a deterministic success predicate before GATE: exit code plus
+  any required output, artifact, or threshold assertion. Warnings block only when policy
+  explicitly classifies them; neither exit code alone nor free model interpretation is
+  universally sufficient.
+- Normalize check identity from executable, argv, logical working directory, allowlisted
+  environment, and relevant configuration/tool-version fingerprints. Exclude secrets,
+  absolute local paths, volatile values, raw shell strings, and human display names from
+  canonical identity.
+- Route independent review to the least-cost model qualified for applicable risk. Allow
+  one escalation only when its structured output is invalid or confidence falls below a
+  policy threshold; the implementing agent cannot freely select a larger model.
+- Build review context deterministically from triggered subjects: related hunks or
+  symbols, direct dependencies, and summarized evidence. Never send the full diff merely
+  because slicing exceeds budget. If the bounded capsule remains too large, use only the
+  specialist passes prescribed by policy; never truncate arbitrarily.
+- Snapshot before GATE the policy ceilings for review input, output, and call count.
+  Material policy changes invalidate approval; transient model/service failure remains
+  safely resumable inside ASSURE.
+- Advance TaskState from V5 to V6 and fail older state explicitly. Do not add runtime
+  migration or dual-schema compatibility for removed ASSURE/success statuses.
+- Implement ADR 0030 and this decision in one TaskState V6 schema transition because
+  both reshape SHAPE and the canonical Change Contract. Deliver independently verifiable
+  lots inside that change rather than causing two schema breaks and duplicate rewrites.
+- Represent coverage compactly as stable `subjects`, `operations`, and `covers` lists,
+  with operation ordering in separate `dependsOn` edges. Persist identifiers and
+  deterministic contracts, not a repeated nested tree or narrative verification plan.
+- Replace `verificationRequirements` with digest-bound `assuranceContract`, containing
+  the compact coverage graph, canonical operations, activation/success predicates,
+  budgets, and relevant policy snapshots.
+- Make the canonical Change Contract the sole owner of `assuranceContract`. Repository
+  documentation is a derived projection; TaskState/runtime uses the canonical structure
+  and digest without maintaining a second narrative or independently editable copy.
+- Precompile any diff-dependent review as a conditional operation before GATE. ASSURE
+  evaluates its deterministic activation predicate; activating it does not invent or
+  expand an approved requirement.
+- Keep terminal computation closed and non-configurable: `cancelled` and `failed` are
+  terminal, as is `assuring` with the atomically paired valid receipt and completion
+  event. Do not add a generic conditional-terminal engine.
+- Render completed work publicly as `ASSURE ✓` with derived result `success`. Keep raw
+  internal status `assuring` only in diagnostic JSON, not user-facing lifecycle copy.
+- Verify the optimization contract with committed scenarios: zero false success in the
+  fault-injection suite; zero ASSURE model calls without a review trigger; one normal
+  consolidated review and at most one qualifying escalation; no rerun of current checks;
+  and enforced input/output token ceilings.
+- Against the captured current baseline, require zero ASSURE model tokens on no-review
+  scenarios and at least 40% lower review input tokens on each review scenario, not only
+  as a favorable aggregate average.
+- In CI, compare deterministic serialized capsules and call counts on fixtures. In a
+  controlled benchmark, record actual model-reported token usage for the same scenario
+  identities. Link both reports; do not make CI depend on live model calls or accept an
+  uncorrelated rough estimate as proof.
+- Fault-injection coverage must reject success for stale evidence, missing subjects,
+  failed checks, false activation/success predicates, material scope drift, malformed
+  review output, negative human observation, and interrupted completion transactions.
+- Risk and correctness controls remain mandatory, but no model review runs without a
+  policy-backed need.
+
+## Consequences
+
+- Workflow success has one source of truth: current complete evidence represented by the
+  Assurance Receipt.
+- Users see ASSURE complete rather than a misleading extra phase.
+- ASSURE resume needs operation/evidence progress rather than multiple orchestration
+  statuses.
+- Benchmark eligibility, metrics, terminal handling, schemas, projections, skills, and
+  tests must derive success from the receipt.
+- Removing accepted statuses requires the explicit TaskState V6 schema break.

package/docs/artifacts.md

@@ -0,0 +1,47 @@
+# Dev Flow Artifact Contract
+
+## Canonical owner
+
+Persisted `ShapeState.contract` is sole logical owner of implementation contract. It
+contains artifact identity/revision, Intake and Discovery receipt references, selected
+profile, risk, scope, applicable non-goals, stable criteria, ordered tasks, validation
+coverage, applicable risks/controls, dependency nodes, and canonical digest.
+
+Quick and Plan share same schema:
+
+- **Quick:** compact valid contract in state; minimum may be one criterion, one task, one
+  validation. No Markdown required.
+- **Plan:** detailed contract plus one deterministic Markdown projection. Non-goals and
+  atomic dependencies required. Implementation Guide allowed only with evidence-linked
+  material trigger.
+
+## Projection
+
+Parent renders Plan projection at safe repository-relative path, default
+`docs/dev-flow/YYYY-MM-DD-<slug>.md`.
+
+1. Render `Proposed` from canonical state.
+2. Persist content fingerprint and logical contract digest.
+3. GATE approves logical digest.
+4. Mark projection `Approved` without changing logical content.
+5. Manual drift blocks overwrite/import and returns to Planning.
+6. Integrating material edit creates new digest and invalidates Approval.
+
+Projection is never second source of truth.
+
+## Ownership and invalidation
+
+- Discovery/Planning skills remain read-only; parent alone persists state/projection.
+- Dependency DAG links decisions, sources, evidence, criteria, tasks, risks, validation,
+  guides, and projection.
+- Change invalidates only transitive dependency closure. Shape is never reset wholesale.
+- Resume reconciles fingerprints and continues first unproved targeted action.
+- Approval binds gate, actor evidence, state revision/fingerprint, artifact identity, and
+  digest—not pathname or boolean.
+- Benchmark authority is canonical Shape contract for both Quick and Plan.
+
+## Legacy layouts
+
+Earlier `spec.md`, `plan.md`, `risk-and-rollback.md`, and `verification.md` layouts remain
+repository choices only. They are non-canonical and cannot replace persisted contract
+identity/digest.

package/docs/baselines/2026-07-18-p0-lifecycle.json

@@ -0,0 +1,142 @@
+{
+  "schemaVersion": 1,
+  "baselineId": "p0-taskstate-v6-contract-fixture",
+  "capturedAt": "2026-08-13T00:00:00.000Z",
+  "contractVersion": "P0",
+  "source": "contract_fixture",
+  "limitations": [
+    "contract_fixture_not_runtime",
+    "token_telemetry_unavailable",
+    "latency_telemetry_unavailable"
+  ],
+  "samples": [
+    {
+      "schemaVersion": 1,
+      "sampleIdHash": "26a1300d0c21109a930e6fde3448083cb271de41faa51b47ad82a9133c946274",
+      "preparationProfile": "quick",
+      "source": "contract_fixture",
+      "statuses": [
+        "new",
+        "intaking",
+        "discovering",
+        "awaiting_profile_choice",
+        "planning",
+        "awaiting_approval",
+        "executing",
+        "assuring"
+      ],
+      "phases": [
+        "INTAKE",
+        "SHAPE",
+        "GATE",
+        "BUILD",
+        "ASSURE"
+      ],
+      "transitions": 7,
+      "gates": 1,
+      "blocks": 0,
+      "resumes": 0,
+      "checksRun": 1,
+      "evidenceReused": 0,
+      "reviewCalls": 0,
+      "reviewEscalations": 0,
+      "correctionCycles": 0,
+      "outcome": "success",
+      "terminalStatus": "assuring",
+      "falseSuccessDetections": 0,
+      "falseSuccessDetectionSource": "contract_tests",
+      "tokenUsage": {
+        "availability": "unavailable"
+      },
+      "latency": {
+        "availability": "unavailable"
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "sampleIdHash": "5016ee2afad0fa54c71fa8cf4dbb57afb85ea238cb68911db0e4f5875b99156c",
+      "preparationProfile": "plan",
+      "source": "contract_fixture",
+      "statuses": [
+        "new",
+        "intaking",
+        "discovering",
+        "awaiting_profile_choice",
+        "planning",
+        "awaiting_approval",
+        "executing",
+        "assuring"
+      ],
+      "phases": [
+        "INTAKE",
+        "SHAPE",
+        "GATE",
+        "BUILD",
+        "ASSURE"
+      ],
+      "transitions": 7,
+      "gates": 1,
+      "blocks": 0,
+      "resumes": 0,
+      "checksRun": 1,
+      "evidenceReused": 0,
+      "reviewCalls": 1,
+      "reviewEscalations": 0,
+      "correctionCycles": 0,
+      "outcome": "success",
+      "terminalStatus": "assuring",
+      "falseSuccessDetections": 0,
+      "falseSuccessDetectionSource": "contract_tests",
+      "tokenUsage": {
+        "availability": "unavailable"
+      },
+      "latency": {
+        "availability": "unavailable"
+      }
+    },
+    {
+      "schemaVersion": 1,
+      "sampleIdHash": "29192bd73047a146815ae66c3cad750165c10ff53551d222462a2380001b8ce2",
+      "preparationProfile": "plan",
+      "source": "contract_fixture",
+      "statuses": [
+        "new",
+        "intaking",
+        "discovering",
+        "awaiting_profile_choice",
+        "planning",
+        "awaiting_approval",
+        "executing",
+        "blocked",
+        "executing",
+        "assuring"
+      ],
+      "phases": [
+        "INTAKE",
+        "SHAPE",
+        "GATE",
+        "BUILD",
+        "ASSURE"
+      ],
+      "transitions": 9,
+      "gates": 1,
+      "blocks": 1,
+      "resumes": 1,
+      "checksRun": 1,
+      "evidenceReused": 1,
+      "reviewCalls": 1,
+      "reviewEscalations": 0,
+      "correctionCycles": 0,
+      "outcome": "success",
+      "terminalStatus": "assuring",
+      "falseSuccessDetections": 0,
+      "falseSuccessDetectionSource": "contract_tests",
+      "tokenUsage": {
+        "availability": "unavailable"
+      },
+      "latency": {
+        "availability": "unavailable"
+      }
+    }
+  ]
+}