@acrasie/dev-flow 0.0.0-stage → 1.0.1

package/docs/adr/0001-hybrid-portable-workflow.md

@@ -0,0 +1,23 @@
+# ADR 0001: Use a Hybrid Portable Workflow
+
+## Status
+
+Accepted.
+
+## Context
+
+The workflow must replace Superpowers for Codex while remaining portable across repositories and avoiding parallel write conflicts. Prompt-only workflows do not provide reliable state or policy enforcement. A monolithic command-line state machine would be too rigid for varied codebases.
+
+## Decision
+
+Publish `codex-dev-flow` as a Codex plugin with a single public `$dev-flow` skill. Internal skills own reasoning. Versioned scripts own deterministic operations: command parsing, configuration resolution, policy enforcement, state validation, fingerprints, and durable artifact handling.
+
+The plugin reads repository guidance first, then inspects manifests, CI, and existing tests. It does not require an `AGENTS.md`, but repository guidance wins when present.
+
+## Consequences
+
+- One primary workflow avoids duplicated lifecycle rules.
+- Scripts make safety-critical behavior testable and reproducible.
+- Skills remain adaptable to repository-specific architecture.
+- The plugin must keep schemas, scripts, and skill instructions compatible.
+- The plugin cannot infer or grant Git or GitHub permissions.

package/docs/adr/0002-share-an-invalidable-context-capsule.md

@@ -0,0 +1,55 @@
+# ADR 0002: Share an Invalidable Context Capsule Across Lifecycle Phases
+
+## Status
+
+Accepted.
+
+## Context
+
+Discovery, planning, execution, review, and verification can repeatedly inspect and
+restate the same repository facts. This consumes quota and tokens without adding
+assurance. Reusing unconstrained summaries would reduce cost but could also propagate
+stale or unsupported claims across phases.
+
+Codex Dev Flow optimizes quota and token consumption subject to two hard constraints:
+reliability and absence of false success.
+
+## Decision
+
+Each durable Dev Flow task owns one compact Context Capsule. Lifecycle phases consume
+the capsule and enrich it instead of independently reconstructing all prior context.
+
+The capsule carries structured references to:
+
+- objective, approved scope, mode, and risk;
+- relevant files and symbols;
+- effective constraints and policy;
+- acceptance criteria and validation commands;
+- decisions and evidence already obtained;
+- Git, configuration, policy, and artifact fingerprints.
+
+Every material claim records provenance and freshness inputs. Fingerprint changes
+invalidate affected sections, not necessarily the whole capsule. A phase must reinspect
+invalid, missing, or insufficient context before relying on it. It may never interpret
+stale context as proof.
+
+The capsule is a compact workflow projection, not a second owner for detailed evidence,
+architecture decisions, or approved scope. Versioned change records and ADRs retain
+those responsibilities.
+
+## Consequences
+
+- Repeated repository reading and prompt restatement decrease.
+- Resume can reconstruct less conversational context.
+- Phase contracts must declare capsule fields consumed and produced.
+- Capsule schema, provenance, fingerprints, invalidation, and compaction require
+  deterministic code and tests.
+- Selective invalidation is more complex than a single opaque summary.
+- Missing assurance data blocks or triggers reinspection; it never permits degraded
+  success.
+
+## Follow-up Decisions
+
+- Define exact schema and storage projection with durable state work in P1.
+- Define invalidation matrix for each fingerprint and phase contract.
+- Define token and cache-hit metrics before dogfooding.

package/docs/adr/0004-scale-assurance-lanes-by-applicable-risk.md

@@ -0,0 +1,36 @@
+# ADR 0004: Scale Assurance Lanes by Applicable Risk
+
+## Status
+
+Accepted.
+
+## Context
+
+Repeating full repository discovery during review and running every specialist review
+lane for every change wastes quota. Removing independent review from Critical changes,
+however, would weaken assurance and could hide false success.
+
+## Decision
+
+ASSURE consumes a compact Diff Capsule derived from approved criteria, applicable risks,
+changed surfaces, dependency impact, and fresh validation evidence.
+
+Standard runs one structured review over changed and impacted surfaces. Critical keeps
+independent read-only review, but activates specialist lanes according to applicable
+risk. A lane may be omitted only with a structured, evidence-backed non-applicability
+decision. Ambiguous applicability activates the lane.
+
+Findings retain deterministic fingerprints. A resolved finding is not reconsidered
+unless its affected code or supporting assumptions changed. Verification reuses fresh
+evidence and reruns missing, invalidated, or globally mandatory checks.
+
+Known deterministic failures block expensive reviewer calls until corrected.
+
+## Consequences
+
+- Review tokens track changed risk surface more closely than repository size.
+- Critical independence remains while irrelevant specialist work decreases.
+- Risk-to-lane rules and non-applicability evidence become testable policy.
+- Incorrectly classifying a lane as irrelevant is a new risk; ambiguity therefore fails
+  toward review, not omission.
+- Diff and evidence invalidation must share fingerprints with Context Capsule state.

package/docs/adr/0006-make-intake-adaptive-user-authoritative-and-token-efficient.md

@@ -0,0 +1,76 @@
+# ADR 0006: Make Intake Adaptive, User-Authoritative, and Token-Efficient
+
+## Status
+
+Accepted for current runtime. Replacement target is recorded by ADR 0030; ADR 0026 is
+superseded as target design.
+
+## Context
+
+INTAKE must establish enough shared understanding to classify a request safely before
+SHAPE explores the repository. A fixed questionnaire wastes tokens on already explicit
+requests. Letting the model silently fill gaps is cheaper in the short term but removes
+user control and can create expensive rework later. Moving full technical discovery into
+INTAKE would duplicate SHAPE and spend quota before mode and risk are confirmed.
+
+The workflow therefore needs an interview that can be relentless about unresolved
+decisions without becoming exhaustive about irrelevant context.
+
+## Decision
+
+INTAKE uses a two-level interview boundary:
+
+- INTAKE resolves product intent, an observable success signal, determining constraints,
+  mode/risk, and only the scope boundaries needed to classify the request.
+- SHAPE resolves repository and implementation uncertainty, then turns the success
+  signal into testable acceptance criteria and an executable contract.
+
+The interview is adaptive. A sufficiently explicit request may require zero questions.
+Every generated question must identify the unresolved decision and the lifecycle outputs
+its answer can change. Questions without determining impact are forbidden.
+
+Questions are generated lazily, one at a time. Each question has two or three mutually
+exclusive choices, one clearly justified recommendation, and a free-form answer path.
+The user must answer or cancel. Silence, “decide for me”, or a request to advance cannot
+bypass an unresolved question. Recommendations reduce interaction cost but never become
+decisions without an explicit answer.
+
+The model owns semantic sufficiency and question wording. Deterministic runtime checks
+own structure, active-question uniqueness, required answers, contradictions,
+deduplication, redaction, and the exit guard. One model evaluation per user response
+integrates the answer, resolves every explicit decision it contains, evaluates
+completeness, and emits at most the next question. A second model is not called merely
+to verify the first.
+
+INTAKE inspects only cheap entry context: repository guidance, Dev Flow configuration
+and policy, primary manifests, workspace/Git identity, and explicitly cited documents.
+Deeper code, dependency, test, and architecture exploration belongs to SHAPE.
+
+INTAKE persists a compact Intake Brief and one active Decision Question, never the full
+conversation. SHAPE consumes this structured projection and source references rather
+than the interview transcript. If a later phase discovers missing objective, success,
+determining-constraint, or mode/risk context, the workflow returns to INTAKE and
+selectively invalidates dependent outputs.
+
+Standard and Critical move automatically to SHAPE when semantic and deterministic
+completeness checks pass. An explicit “move on” request is refused while context is
+incomplete. Answering INTAKE questions is not implementation Approval; BUILD remains
+guarded by the canonical GATE contract. Quick may bypass SHAPE only when its existing
+bounded-scope guard also proves the request is already executable and verifiable without
+a design decision.
+
+After five distinct questions, INTAKE presents a compact checkpoint of resolved and
+remaining decisions. This is a control point, not a hard question limit.
+
+## Consequences
+
+- Clear requests pay near-zero interview overhead.
+- Ambiguous requests spend tokens only on decisions capable of changing outcome, risk,
+  mode, or downstream work.
+- The user remains the authority for every human decision.
+- Resume can re-present the exact active question without replaying the conversation.
+- SHAPE receives smaller, more stable context and can detect ownership violations.
+- A hybrid question engine and new persisted fields require schema, state-machine,
+  migration, validation, and crash/resume tests.
+- Model sufficiency can still be wrong; deterministic guards, downstream reopening, and
+  benchmark feedback expose that risk without a routine second model call.

package/docs/adr/0007-collect-opt-in-local-benchmark-feedback.md

@@ -0,0 +1,82 @@
+# ADR 0007: Collect Opt-In Local Benchmark Feedback
+
+## Status
+
+Accepted.
+
+## Context
+
+Codex Dev Flow is valuable only when its reliability and avoided rework justify its
+orchestration cost. Running equivalent tasks with multiple models or comparing Dev Flow
+against an additional vanilla Codex execution would multiply token usage and defeat that
+goal. Automatic production telemetry would also create privacy, consent, and operational
+costs disproportionate to early local dogfooding.
+
+The maintainer still needs structured evidence about user satisfaction, contract
+conformance, perceived plugin value, and common deviations.
+
+## Decision
+
+New runs may opt into local benchmark feedback with the public invocation flag:
+
+```text
+$dev-flow --benchmark <objective>
+```
+
+The flag is disabled by default, accepted only when creating a task, persisted with that
+task, retained automatically across resume, and exposed by status. It never triggers a
+second task, another model, an A/B comparison, or an upload.
+
+After `finished` or `failed`, Dev Flow offers three deterministic
+questions without a model call:
+
+1. satisfaction from 1 to 5;
+2. conformance to the expressed need: yes, partially, or no;
+3. Dev Flow value: useful, neutral, or counterproductive.
+
+Each question permits an optional free-form clarification, followed by an optional
+general comment. The lifecycle result is already final: feedback cannot change task
+status or evidence. No questionnaire is offered for `blocked` or `cancelled`.
+
+A benchmark record is written atomically only after all three required answers exist.
+Closing the session before completion creates no benchmark record and contributes no
+benchmark data.
+
+Deterministic deviation checks compare:
+
+- Quick and Plan against current canonical Change Contract and Plan Approval Receipt.
+
+They record structured facts such as unexpected file additions/deletions, unplanned
+surfaces, uncovered criteria, skipped or failed checks, and unapproved scope changes. A
+new file is a deviation only when the authoritative contract did not
+permit it.
+
+Completed records live under:
+
+```text
+.codex/benchmarks/<task-id>.json
+```
+
+The directory is gitignored and excluded from product-diff analysis. Records contain
+allowlisted metadata, questionnaire answers, deterministic deviation signals, task and
+artifact references, plugin/policy versions, duration, and token/call metrics when
+available. They contain no prompt, transcript, code, diff, secret, or automatic upload.
+
+The deterministic command below summarizes completed records without a model:
+
+```bash
+npx codex-dev-flow benchmark summary
+```
+
+## Consequences
+
+- Maintainer can dogfood one real task and retain comparable feedback without paying for
+  duplicate executions.
+- Non-response is intentionally absent rather than treated as negative or positive
+  evidence.
+- Public flag and record format become compatibility surfaces requiring parser, schema,
+  state, privacy, and migration tests.
+- User comments remain local but still require length bounds and deterministic secret
+  redaction before persistence.
+- Benchmark collection stays outside the five lifecycle phases and cannot weaken truthful
+  terminality.

package/docs/adr/0008-automate-maintainer-releases-with-an-interactive-bun-workflow.md

@@ -0,0 +1,121 @@
+# ADR 0008: Automate Maintainer Releases with an Interactive Bun Workflow
+
+## Status
+
+Accepted.
+
+## Context
+
+Releasing Codex Dev Flow currently requires the maintainer to remember unrelated Git,
+plugin-cache, npm-registry, and Codex marketplace commands. Some commands depend on
+machine-specific absolute paths, and the Codex plugin and npm package have different
+publication mechanisms. This makes an otherwise routine release error-prone and leaves
+partial-release recovery implicit.
+
+The maintainer needs a self-service release flow with one memorable command, explicit
+authority before irreversible actions, deterministic recommendations, and no model call.
+
+## Decision
+
+The repository will expose this command from its root:
+
+```bash
+bun run release
+```
+
+A private root `package.json` delegates to a TypeScript release program in the plugin
+package. The program runs with Bun and uses `@clack/prompts`. V1 guarantees macOS
+support, avoids shell-specific implementation, is expected to work on Linux, and does
+not claim tested Windows support. The repository migrates from `package-lock.json` to a
+single committed `bun.lock`.
+
+The first prompt selects one release target:
+
+- Codex plugin;
+- npm package;
+- Codex plugin and npm package, selected by default.
+
+The next prompt selects publication or read-only preview. Preview performs discovery,
+version recommendation, preflight checks, and summary generation without modifying the
+workspace or any remote system.
+
+V1 publishes stable versions only. A deterministic Conventional Commits analysis
+recommends the version increment:
+
+- `fix:` recommends patch;
+- `feat:` recommends minor;
+- `!` or `BREAKING CHANGE:` recommends major;
+- unclassified commits recommend patch.
+
+The maintainer may choose patch, minor, major, or a greater unpublished custom stable
+version. For a plugin-only release, the semantic base remains unchanged and only the
+Codex cachebuster changes. For an npm-only release, only the package semantic version
+changes. A combined release gives both artifacts the same semantic base and adds the
+cachebuster only to the plugin manifest.
+
+Release identities are target-specific:
+
+```text
+combined:    v0.2.0
+npm only:    npm-v0.2.0
+plugin only: plugin-v0.2.0-codex.20260728...
+```
+
+The corresponding commit uses `chore(release): <release-identity>`. The Git tag is
+annotated and follows the local Git signing configuration.
+
+Before changing files, the program requires a clean `main`, fetches `origin/main`, and
+fast-forwards when safe. It refuses local commits, divergence, conflicts, or another
+branch. It never resets, rebases, or merges automatically.
+
+All applicable validation is mandatory and has no force-publish bypass:
+
+- frozen Bun dependency installation;
+- typecheck, deterministic build, and tests;
+- plugin manifest validation;
+- npm package-content dry run;
+- target-version availability;
+- GitHub and npm authentication;
+- expected clean or allowlisted generated-file state.
+
+The release commit may contain only the plugin manifest, affected package metadata,
+`bun.lock` when required, and the deterministic distribution bundle. Any other generated
+change blocks the release.
+
+Authentication is checked before mutation. The program never reads, prompts for, logs,
+or stores credentials. Missing authentication produces an exact corrective command and
+requires the maintainer to rerun the release. OTP handling remains inside `bun publish`.
+
+The program generates GitHub release notes before publication, displays a non-editable
+preview, and lets the maintainer accept or abort. The final Clack confirmation defaults
+to `No` and summarizes target, versions, tag, files, checks, publication order, and
+planned local installation.
+
+Before the first successful push, cancellation, `Ctrl+C`, or failure restores the exact
+original bytes and removes only local commit or tag objects created by the program. Once
+an external publication succeeds, the program never attempts automatic rollback.
+
+Publication order is:
+
+1. push the release commit and tag;
+2. publish the npm package with `bun publish` when applicable;
+3. create the GitHub Release from the previewed notes;
+4. optionally refresh marketplace `acrazie`, reinstall `codex-dev-flow`, and remind the
+   maintainer to start a new Codex thread.
+
+Git and registry state form the recovery record. A later `bun run release` detects a
+partial release and offers the single missing idempotent action instead of creating a
+new version. No local state file or secret is required.
+
+## Consequences
+
+- Routine release operation becomes one short command with maintainer-controlled
+  decisions and no model dependency.
+- Plugin and npm releases may remain independent without ambiguous Git tags.
+- Strict preflight and generated-file allowlists reduce accidental publication.
+- Git, npm, and GitHub cannot form one atomic transaction, so explicit partial-release
+  detection and resume behavior are required.
+- Root release orchestration, Bun lockfile migration, subprocess isolation, cancellation,
+  and recovery paths require dedicated deterministic tests.
+- V1 intentionally excludes prereleases, editable release notes, Windows guarantees, and
+  validation bypasses.

package/docs/adr/0009-separate-intake-decisions-from-shape-discovery.md

@@ -0,0 +1,200 @@
+# ADR 0009: Separate Intake Decisions from Shape Discovery
+
+## Status
+
+Accepted for current runtime. Replacement target is recorded by ADR 0030; ADR 0026 is
+superseded as target design.
+
+## Context
+
+Adaptive INTAKE now owns product intent, observable success, determining constraints,
+and risk before SHAPE performs deeper repository discovery. Without a stronger
+downstream boundary, SHAPE can duplicate the interview, silently choose among outcomes
+that need human authority, or send an unstructured ambiguity back to INTAKE and force
+the same technical investigation to run twice.
+
+The boundary cannot depend only on whether a choice first appears technical. Repository
+discovery can reveal alternatives whose effects change user experience, cost, delivery
+time, scope, or the observable definition of success.
+
+## Decision
+
+Phase ownership follows decision impact:
+
+- INTAKE owns every unresolved choice that can change product intent, user experience,
+  cost, delivery time, scope, determining constraints, risk, or observable success.
+- SHAPE owns repository discovery and purely technical uncertainty that does not change
+  those product outcomes.
+- SHAPE never silently resolves a product-impacting technical choice. It suspends
+  shaping and requests an explicit INTAKE decision.
+- SHAPE does not repeat an INTAKE decision unless fresh evidence invalidates it.
+
+The SHAPE-to-INTAKE return uses a rich, structured Decision Escalation rather than a
+plain missing-context signal. It contains:
+
+- a stable decision key;
+- technical evidence and provenance;
+- the product impact;
+- two or three feasible, mutually exclusive options;
+- an evidence-backed recommendation;
+- the SHAPE sections that may depend on the answer.
+
+INTAKE validates this escalation and presents the explicit Decision Question. It does
+not repeat the underlying repository discovery merely to reconstruct options. The user
+remains the authority for the answer; a recommendation is not a decision.
+
+SHAPE invalidation is always selective. Opening an escalation suspends
+`contract_complete` and marks only the declared dependent sections as unreliable.
+Fresh, independent discovery evidence and contract sections remain reusable. After the
+INTAKE answer, the workflow invalidates the transitive dependency closure of the
+decision and resumes targeted discovery or planning.
+
+SHAPE is never reset wholesale. If dependency impact is ambiguous, the workflow widens
+targeted discovery to resolve that ambiguity or blocks with the unresolved dependency;
+it does not discard unrelated evidence. This rule prevents already-paid repository
+reasoning from being repeated solely because one product decision changed.
+
+Selective invalidation uses an explicit persisted dependency graph. Decisions, source
+fingerprints, discovery evidence, and contract sections have stable identities. Every
+derived discovery item and contract section declares `dependsOn` references to the
+items required for its validity. The runtime validates that references exist, rejects
+cycles, and computes the transitive dependency closure when a root changes.
+
+The model proposes dependency links while shaping because it owns their semantic
+meaning. The deterministic runtime owns structural validation and invalidation. It
+never reconstructs the graph by asking a model to reread all SHAPE output during
+resume.
+
+SHAPE discovery is adaptive and targeted, not a fixed repository checklist. It starts
+from the Intake Brief, structured decisions, transferred technical unknowns, and fresh
+reusable evidence. Each discovery target has a stable key, a precise technical question,
+its possible material impact, candidate sources, a result with provenance, and explicit
+dependencies.
+
+Discovery widens only when fresh evidence exposes an uncertainty capable of changing
+scope, risk, acceptance criteria, implementation plan, validation, or the preparation
+profile recommendation. SHAPE stops
+exploring when no material technical uncertainty remains and every required contract
+section has sufficient fresh supporting evidence.
+
+SHAPE retains two strictly separated roles over one shared structured state:
+
+- Discovery may read the repository and resolve Discovery Targets into fresh,
+  provenance-bound evidence. It does not author the canonical implementation plan.
+- Planning may project the canonical contract from fresh evidence. It does not read the
+  repository or silently supplement missing evidence.
+
+After Discovery proves `discovery_sufficient`, the workflow obtains the explicit Quick
+or Plan preparation choice before Planning starts. This is a SHAPE projection choice,
+not a product decision. Planning uses the selected profile without repeating Discovery.
+
+When Planning lacks evidence, it creates a new Discovery Target and yields to Discovery.
+After that target is resolved, Planning resumes from shared state. The transfer is
+structured and dependency-linked, never a prose summary that causes either role to
+repeat the other's work.
+
+The nominal SHAPE path uses one Discovery reasoning session, one profile choice, and one
+Planning reasoning session. One Discovery session may resolve multiple related targets.
+There is no routine semantic re-review call: deterministic runtime verifies structure,
+freshness, coverage, and dependencies. Additional reasoning is allowed only for a new
+material Discovery Target or an invalidated evidence closure, and receives only the
+relevant state subset. Planning never rereads repository sources.
+
+SHAPE uses configurable soft budgets for reasoning calls, estimated tokens, and context.
+Defaults must come from benchmark evidence rather than arbitrary hard-coded counts. When
+a budget approaches exhaustion, the workflow persists all current evidence and displays
+a compact checkpoint offering explicit continuation, scope reduction through INTAKE, or
+cancellation. It never discards SHAPE work or silently spends beyond the budget.
+
+`ShapeState` is the aggregate root for `discoveryTargets`, `evidence`,
+`sourceFingerprints`, `decisionEscalations`, `preparationProfile`, `contract`,
+`dependencyGraph`, and semantic `evaluatorReceipts`. Its primary progression is:
+
+`discovering -> awaiting_profile_choice -> planning -> awaiting_approval`
+
+Planning returns to `discovering` only through a material Discovery Target. Discovery or
+Planning enters `awaiting_intake_decision` only through a Decision Escalation. Required
+events include `discovery.target_recorded`, `discovery.evidence_recorded`,
+`discovery.completed`, `profile.choice_requested`, `profile.choice_recorded`,
+`contract.projected`, and `evidence.invalidated`.
+
+For the Plan profile, Planning first completes the canonical contract and the parent
+workflow renders a Markdown projection marked `Proposed`. GATE presents that projection
+with the canonical digest. Approval binds logical contract content; changing projection
+status to `Approved` does not alter that content.
+
+The projection has its own fingerprint. A manual file edit never silently overwrites
+canonical state and is never silently discarded. It returns to Planning with an
+explicit reconciliation choice: integrate the edit into the canonical contract or
+regenerate the projection. Any integrated material change requires a new Gate digest
+and Approval.
+
+SHAPE completion uses two hybrid proofs:
+
+- `discovery_sufficient`: the Discovery model declares that no material technical
+  uncertainty remains; deterministic checks require every target to be resolved or
+  escalated, every supporting item to be fresh and provenance-bound, and no relevant
+  invalidation to remain open.
+- `contract_complete`: the Planning model declares the contract implementable;
+  deterministic checks require the profile- and policy-applicable contract sections,
+  valid acyclic
+  dependencies, criterion-to-task coverage, task-to-criterion coverage, and a
+  verification method for every criterion. Risk or policy additionally requires threat
+  and rollback records when applicable.
+
+Exiting SHAPE requires both proofs. A second model does not re-evaluate another model's
+semantic judgment merely for confirmation; deterministic runtime owns structural
+verification.
+
+A Decision Escalation moves the task to a distinct `awaiting_intake_decision` state
+rather than overloading `awaiting_mode_confirmation`. The state persists the escalation
+identity, active Decision Question, prior SHAPE substate, affected dependency roots, and
+freshness references for retained evidence.
+
+After an explicit answer, INTAKE integrates the decision and recomputes classification
+or routing only when their declared dependencies are affected. Runtime invalidates the
+decision's dependency closure. The task resumes `discovering` when required evidence is
+missing; otherwise it resumes `planning`. It does not rerun initial INTAKE.
+
+Freshness is tracked per evidence source rather than through one repository-wide Git
+invalidation. Tracked files use blob identities; untracked files and configuration use
+content digests; command evidence binds the command, relevant inputs, and observed
+result; external evidence uses a stable identity plus policy-defined observation time
+or TTL.
+
+Resume checks only sources referenced by live evidence. A changed source invalidates
+its transitive dependency closure and creates a targeted refresh Discovery Target.
+Unchanged source evidence is reused without another model read. A broad Git change
+alone is not sufficient reason to invalidate unrelated SHAPE work.
+
+## Consequences
+
+- INTAKE and SHAPE have an effect-based ownership boundary that also covers choices
+  discovered late.
+- Technical evidence crosses the boundary without transferring ownership of the human
+  decision to SHAPE.
+- Selective invalidation requires explicit dependency links between decisions,
+  discovery evidence, and contract sections.
+- Resume reuses fingerprint-valid independent evidence and spends tokens only on the
+  invalidated dependency closure.
+- Persisted dependency metadata grows with the contract, but makes invalidation
+  deterministic and auditable.
+- Small changes inspect few surfaces; complex changes widen only through recorded
+  material reasons.
+- Discovery and Planning can be tested and routed independently without paying for
+  duplicate repository reads.
+- Planning may require multiple resumable passes, but each additional pass must be
+  justified by a new or invalidated Discovery Target.
+- The common path pays for two SHAPE reasoning sessions rather than repeated discovery,
+  planning, and model-verification passes.
+- Budget exhaustion is resumable and user-authoritative rather than a lossy hard stop.
+- Semantic sufficiency remains model-owned while structural completion and coverage are
+  deterministic and testable.
+- The lifecycle gains an internal INTAKE state whose name reflects late product
+  decisions rather than mode confirmation.
+- Crash/resume can re-present the exact escalated question and return to the correct
+  SHAPE role.
+- Source-granular fingerprints cost more metadata but prevent unrelated Git changes
+  from causing expensive rediscovery.
+- Persisted state and schemas need a resumable Decision Escalation linked to the active
+  Decision Question.