@acrasie/dev-flow 0.0.0-stage → 1.0.1

package/docs/adr/0022-use-one-root-bun-workspace.md

@@ -0,0 +1,41 @@
+# ADR 0022: Use One Root Bun Workspace
+
+## Status
+
+Accepted.
+
+## Context
+
+Repository-wide quality tools and Husky execute from the Git root, while the publishable
+plugin currently owns a separate Bun installation and lockfile. Adding an independent
+root installation would duplicate dependency resolution, cache state, and frozen-lock
+validation.
+
+Placing repository tooling inside the plugin package would invert ownership and require
+commands to reach outside the package boundary.
+
+## Decision
+
+Convert the private root package into the Bun workspace owner with
+`workspaces: ["plugins/*"]` and one committed root `bun.lock`.
+
+The root package owns repository-level quality dependencies and orchestration scripts,
+including Husky, Oxfmt, Oxlint, and the staged-file adapter. The plugin workspace remains
+self-contained in its manifest and declares its build, test, release, and product-facing
+development dependencies.
+
+Install the repository once from the root with `bun install --frozen-lockfile`. Remove
+the nested plugin lockfile after verifying identical or intentionally updated resolved
+versions.
+
+Publishing continues from `plugins/codex-dev-flow`; the private root package is never
+packed or published.
+
+## Consequences
+
+- Local development and CI use one install and one dependency graph.
+- Repository tools have the same scope as their owning package.
+- Workspace isolation helps expose undeclared plugin dependencies.
+- Release scripts and documentation must stop assuming a nested lockfile or plugin-local
+  install.
+- Lockfile migration requires reviewing resolved-version and platform-binary changes.

package/docs/adr/0024-make-gate-a-minimal-plan-approval.md

@@ -0,0 +1,74 @@
+# ADR 0024: Make GATE a Minimal Plan Approval
+
+## Status
+
+Accepted and implemented in TaskState V4.
+
+## Context
+
+SHAPE already proves that the canonical change contract is complete, evidence-backed,
+fresh, internally consistent, and executable. Re-running discovery, planning, or model
+review in GATE would duplicate SHAPE, add latency, and weaken phase ownership.
+
+The V3 lifecycle also uses one generic approval mechanism for both pre-BUILD plan
+authorization and post-ASSURE completion approval. This makes GATE broader than its
+product purpose: let the user validate and authorize the implementation plan before
+workspace mutation begins.
+
+## Decision
+
+GATE is one short pre-BUILD user decision over the exact current canonical contract.
+Quick and Plan, and every risk level, use the same interaction. Risk and policy affect
+the contract and its required controls, not the length or number of GATE prompts.
+
+Before presenting a decision, GATE runs one deterministic preflight that proves:
+
+- the current `contract_complete` receipt is valid;
+- the recomputed canonical digest matches the stored contract digest;
+- every acceptance criterion has validation coverage;
+- referenced SHAPE evidence is fresh; and
+- no Decision Escalation remains open.
+
+The preflight performs no model call, network access, repository discovery, or
+subprocess execution. Failure returns to the exact owner: stale evidence to Discovery,
+an invalid contract or digest to Planning, an open product decision to INTAKE, and
+malformed state to a typed block. It never resets SHAPE.
+
+On success, GATE renders a deterministic card of at most five lines containing the
+objective, task/criterion/validation counts, risk and control count, a short display
+form of the contract digest, and these actions:
+
+- `approuver` / `approve`;
+- `modifier: <instruction>` / `change: <instruction>`;
+- `rejeter` / `reject`.
+
+Empty, ambiguous, or continuation-like answers are rejected. `voir` / `view` is a
+read-only action that renders the full canonical contract and leaves the task in GATE.
+No model interprets a GATE answer.
+
+Approval authorizes the complete local implementation contract, not one task at a time.
+It never authorizes commit, push, pull request, merge, publication, or release. The
+approval is a compact `PlanApprovalReceipt` bound to user actor, timestamp, task and
+artifact identity, full contract digest, state revision, and state fingerprint. Raw
+conversation text is not persisted.
+
+`change_requested` returns to SHAPE Planning with the structured, redacted instruction.
+SHAPE decides whether a product-impacting change needs a Decision Escalation to INTAKE.
+`rejected` ends the task as `cancelled`. All three decisions enter bounded history, but
+only `approved` creates an active authorization.
+
+Any canonical contract digest change invalidates approval. Unrelated progress does not.
+Approval has no arbitrary wall-clock expiry; SHAPE evidence freshness remains the
+validity boundary. Non-interactive execution stops in `awaiting_approval` and cannot
+use a configuration, policy, or CLI bypass.
+
+## Consequences
+
+- Nominal GATE cost is one local preflight, one card, one user decision, and one state
+  transition.
+- Approval semantics become exact and auditable without storing user prose.
+- `ApprovalGate`, `pendingGate`, and completion approval are removed in V4.
+- TaskState V3 gate-type and materiality rules are replaced in V4 by one full-digest
+  plan approval.
+- Metrics may record only allowlisted preflight outcomes, decision kinds, approval
+  reuse, and targeted returns; they contain no objective, instruction, digest, or path.

package/docs/adr/0025-end-the-lifecycle-after-assure.md

@@ -0,0 +1,55 @@
+# ADR 0025: End the Lifecycle After ASSURE
+
+## Status
+
+Superseded by ADR 0031. Historical TaskState V4 decision retained for context.
+
+## Context
+
+V3 HANDOFF distinguishes local completion from external Git or GitHub delivery, stores
+remaining actions and provider receipts, and reconciles retries. In the intended Codex
+product flow, conversation resume and external actions already belong to the parent
+Codex interaction. Keeping those concerns inside dev-flow duplicates native behavior
+and adds statuses, policy, metrics, and failure paths after implementation is already
+verified.
+
+## Decision
+
+TaskState V4 has five public macro-phases:
+
+```text
+INTAKE -> SHAPE -> GATE -> BUILD -> ASSURE -> finished
+```
+
+ASSURE persists a compact verification receipt containing criterion coverage, executed
+validation identities and results, freshness fingerprint, and timestamp. Successful
+ASSURE transitions directly to the single success terminal `finished`. Parent Codex,
+not a dev-flow phase, renders the conversational completion response.
+
+HANDOFF and its public/internal contract are removed, including `handing_off`,
+`ready_for_handoff`, `finished_local`, `remainingActions`, handoff intent and
+reconciliation receipts, HANDOFF capsule/events/guards, handoff configuration, and
+handoff metrics.
+
+Commit, push, pull request, merge, publication, and release occur outside the dev-flow
+lifecycle through native Codex behavior and native confirmations. A combined request
+such as “implement, commit, and open a pull request” is split implicitly: dev-flow owns
+implementation through verified `finished`; parent Codex may then execute requested
+external actions. TaskState does not persist those external actions.
+
+No GATE approval authorizes an external action. Removing HANDOFF therefore does not
+weaken the confirmation boundary for Git, GitHub, registry, or release operations.
+
+V4 is an explicit schema break. V1, V2, and V3 task states fail with a typed incompatible
+schema error. The runtime does not guess how an old completion approval or partial
+handoff maps to the five-phase lifecycle.
+
+## Consequences
+
+- Verified implementation has one unambiguous success terminal.
+- Resume and metrics no longer model external delivery state.
+- Native Codex remains responsible for external-action authorization, retries, and
+  conversational summaries.
+- TaskState V3 HANDOFF delivery state is removed rather than migrated into V4.
+- The state schema, registry, projections, skills, configuration, benchmark protocol,
+  documentation, generated bundle, and deterministic tests must change atomically.

package/docs/adr/0026-keep-intake-product-stable-and-interview-shape-by-dependency.md

@@ -0,0 +1,151 @@
+# ADR 0026: Keep INTAKE Product-Stable and Interview SHAPE by Dependency
+
+## Status
+
+Superseded as target design by
+[ADR 0030](0030-unify-product-domain-and-technical-design-interviews.md). Current runtime
+behavior introduced before ADR 0030 remains documented by ADRs 0006, 0009, and 0010
+until the replacement target lands atomically.
+
+## Context
+
+INTAKE and SHAPE already separate product intent from repository discovery, but current
+SHAPE primarily asks only the Quick/Plan choice and escalated product decisions. A
+complex change can still contain material technical alternatives whose consequences
+should be chosen explicitly rather than inferred during Planning or BUILD.
+
+A fixed questionnaire is also wrong. Facts available from repositories, tools, or
+official documentation should be discovered, while decisions remain user-owned. Asking
+several questions together hides dependencies and makes answers ambiguous. Conversely,
+an arbitrary question cap can leave a material branch unresolved.
+
+INTAKE needs a stronger stability rule without becoming a mandatory five-prompt form.
+Five product dimensions must be resolved, but explicit input should not be asked again.
+SHAPE needs a dependency-directed interview with exact resume semantics and no periodic
+interaction that exists only to report progress or estimated cost.
+
+## Decision
+
+### INTAKE owns a stable product baseline
+
+INTAKE resolves five mandatory dimensions:
+
+1. objective;
+2. affected users and product value;
+3. scope and boundaries;
+4. observable success and its validator; and
+5. product risks and determining constraints.
+
+These are five completeness dimensions, not five mandatory prompts. Input already
+stated explicitly satisfies its dimension. Questions remain adaptive, one at a time,
+and include two or three viable options, an evidence-based recommendation, and a
+free-form path.
+
+The Product Brief becomes stable when every dimension is resolved. A dedicated
+confirmation is shown only when the brief contains a material interpretation,
+normalized free-form decision, or resolved contradiction. Otherwise explicit request
+and answers are sufficient; the final GATE approval still covers the complete contract.
+
+SHAPE never mutates INTAKE. Fresh technical evidence may reopen only the affected
+product decision. Product intent remains authoritative while a compatible technical
+alternative exists. A contradiction is resolved by source:
+
+- stale evidence returns to targeted Discovery;
+- an incompatible technical choice with a viable alternative invalidates that SHAPE
+  choice;
+- proven infeasibility or materially different product outcomes reopen the dependent
+  INTAKE decision; and
+- only the transitive dependency closure is invalidated.
+
+### SHAPE interviews only material technical decisions
+
+SHAPE looks up facts before asking. It may inspect repositories, configured service
+roots, safe command results, and primary external documentation. Missing factual
+evidence creates a Discovery Target. User-provided information that cannot be verified
+is retained as `user_asserted` provenance and cannot silently become technical proof.
+
+A user question is required only for a material technical decision. Deterministic
+triggers include architecture boundaries, framework/runtime or major dependency,
+schema/data migration, cross-service contract, security/privacy, compatibility,
+concurrency, material performance/cost/operations, and an exception to an approved
+project profile. The model may add another material decision only with an explicit
+impact reason.
+
+Reversible details already implied by repository conventions remain agent-owned. The
+user cannot delegate a material decision with “choose for me”; selecting the recommended
+option explicitly is a valid decision.
+
+SHAPE maintains an acyclic decision graph. It resolves the highest-impact unblocked root
+before dependent branches. Discovery and interview are interleaved so eliminated
+branches are not explored:
+
+```text
+Discovery -> technical decision -> targeted Discovery -> technical decision -> ...
+```
+
+Each visible interaction contains exactly one question. The runtime may normalize other
+unambiguous decisions volunteered in the same answer and skip their future questions.
+The full graph stays internal; the question shows only its parent context, evidence,
+recommendation, confidence, viable options, and direct consequences. More than three
+feasible options are reduced to two or three non-dominated choices; excluded choices
+remain viewable and free-form input remains available.
+
+There is no hard question cap and no periodic five-question checkpoint. State persists
+silently after each answer. A warning appears only when a real context or quota boundary
+threatens continuation. User revisions invalidate only dependent decisions, evidence,
+and contract sections.
+
+### Stable question state and completion
+
+A new `awaiting_shape_decision` status belongs to SHAPE. It persists one exact active
+question, its evidence and dependencies, and the exact prior role
+`discovering|planning`. `awaiting_profile_choice` remains separate because Quick/Plan
+controls preparation depth rather than technical design.
+
+Quick/Plan is chosen after the main material technical branches are resolved and before
+Planning. Planning may still create a targeted Discovery Target or Technical Decision
+when a new material dependency appears.
+
+SHAPE completion is hybrid. The model declares no material uncertainty remains;
+deterministic runtime requires a valid decision DAG, no open required decision, current
+evidence, current applicable project profile, complete criterion/task/validation
+coverage, and resolved risks. An open mandatory branch cannot be bypassed by a request
+to advance.
+
+SHAPE then renders one compact synthesis of decisions, architecture, exceptions, risks,
+and validation. The existing five-line GATE card follows in the same interaction. GATE
+approval is the single final confirmation of shared understanding and authorization to
+BUILD; SHAPE adds no duplicate confirmation.
+
+### Adaptive visual evidence
+
+Visuals use the least expensive representation that can resolve the decision:
+
+- ASCII for simple flows, trees, and rough wireframes;
+- Mermaid for architecture, state, sequence, and dependency diagrams;
+- isolated HTML/CSS for material UI layout or interaction decisions; and
+- Excalidraw or generated images only when explicitly requested or higher fidelity is
+  necessary.
+
+Two or three visual variants may appear inside one question when comparison is
+material. HTML/CSS prototypes and executable spikes live in isolated temporary task
+space, never product source. They are not promoted before GATE. Safe inspection,
+non-mutating checks, and temporary experiments are allowed; installs, migrations,
+external effects, and product writes are not.
+
+Product-visible UX decisions remain INTAKE-owned. Component structure, layout
+implementation, responsive mechanics, and frontend architecture remain SHAPE-owned.
+
+## Consequences
+
+- INTAKE becomes stable without imposing redundant prompts on explicit requests.
+- Complex technical work can be interviewed deeply without asking repository facts or
+  overwhelming the user with multiple simultaneous questions.
+- The decision DAG provides deterministic question order, selective invalidation, and
+  exact resume.
+- Long interviews persist compact normalized decisions, active question, provenance,
+  recommendations, and invalidations—not transcript or hidden reasoning.
+- The new status and records extend unreleased TaskState V4 before publication rather
+  than creating an immediate V5 break.
+- Current runtime behavior remains authoritative until the lifecycle contract, schema,
+  state machine, skills, and tests implement this ADR atomically.

package/docs/adr/0027-add-agentic-project-init-and-versioned-engineering-profiles.md

@@ -0,0 +1,147 @@
+# ADR 0027: Add Agentic Project INIT and Versioned Engineering Profiles
+
+## Status
+
+Accepted and implemented for Project INIT and profile transactions. Ordinary SHAPE
+profile consumption and domain-documentation integration remain pending ADR 0030.
+
+## Context
+
+Material technical questions should not recur on every task when a project already has
+approved architecture and development conventions. Existing repository files prove many
+facts, but implicit conventions can be inconsistent or incomplete. The standalone
+`npx codex-dev-flow init` configures plugin operation through a deterministic terminal
+wizard; it cannot perform model-assisted repository discovery and a dependency-aware
+architecture interview.
+
+Projects may also span several repositories. Shared topology and contracts must be
+portable, while absolute filesystem paths and personal preferences must remain local.
+Any persisted profile must distinguish stable decisions from volatile task evidence,
+detect drift, and never overwrite team conventions without explicit validation.
+
+## Decision
+
+### Add a separate agentic command
+
+The plugin adds `$dev-flow init`. It is distinct from the existing standalone
+`npx codex-dev-flow init` configuration wizard.
+
+`$dev-flow init` discovers before asking. It reads applicable guidance, manifests,
+configuration, architecture sources, tests, contracts, and representative code. It asks
+only missing, contradictory, or material decisions, exactly one at a time, using the
+recommendation and dependency rules now refined by ADR 0030. There is no hard question cap or
+periodic progress checkpoint.
+
+The command is adaptive. Every project uses a common core covering stack, source
+structure, architectural boundaries, dependency direction, naming, error handling, and
+quality/testing. Discovery or user input activates applicable modules for frontend,
+APIs, data, security, concurrency, performance, compatibility, migrations,
+observability, deployment, rollback, and operations. Non-applicable domains are not
+asked.
+
+Greenfield repositories are supported. With no code to inspect, INIT interviews the
+applicable decisions and produces only profile and optional diagram artifacts. It never
+scaffolds product code.
+
+Long interviews persist gitignored `.codex/project-init/state.yaml` containing compact
+normalized decisions, stale keys, exact active question, status, and candidate digest.
+It contains no transcript or hidden reasoning. Resume restores same question unless
+dependency evidence changed.
+
+### Persist shared and local profiles separately
+
+The canonical shared profile is `.codex/dev-flow.project.yaml`. It is versioned and
+schema-validated. It stores only durable knowledge:
+
+- logical project and service identities;
+- supported stack/runtime choices;
+- architecture, boundaries, and dependency rules;
+- stable API/data/security/operations conventions when applicable;
+- source layout, naming, error, testing, and quality conventions;
+- decision provenance and durable source fingerprints;
+- references to optional diagram projections; and
+- content revision, digest, and `ProfileApprovalReceipt`.
+
+The local overlay `.codex/dev-flow.project.local.yaml` is gitignored. It stores
+non-contractual personal preferences and maps logical service identities to absolute
+local paths. It cannot weaken repository policy or the shared profile.
+
+The authority order is:
+
+```text
+system instructions and repository policy
+-> INTAKE product decisions
+-> explicitly approved task exception
+-> shared engineering profile
+-> non-contractual local preferences
+-> agent defaults
+```
+
+A lower layer cannot weaken a higher layer. Repository observations, task-local file
+facts, command results, and other volatile evidence stay in ShapeState rather than
+inflating the project profile.
+
+### Model multi-service topology without portable-path leaks
+
+Each repository owns its own engineering profile. A root profile may describe logical
+service topology, responsibilities, inter-service dependencies, and contracts, and may
+reference profiles owned by other repositories. Local overlays map those service IDs to
+available filesystem roots.
+
+Discovery first inspects cheap guidance, manifests, contracts, and structure across
+declared accessible services. It reads implementation deeply only when a live decision
+can change the profile or current task. An inaccessible service statement is retained
+as `user_asserted`, never fabricated as verified evidence.
+
+INIT does not modify a profile owned by another repository without a separate explicit
+profile transaction and validation for that owner. Absolute paths never enter shared
+profiles.
+
+### Reconcile profile drift transactionally
+
+Profile decisions are authoritative defaults, not unbreakable rules. If fresh evidence
+contradicts a profile, runtime identifies the affected dependency closure and interviews
+only stale decisions. Facts are refreshed through Discovery; user-owned conventions are
+never rewritten automatically.
+
+Answers accumulate in a local proposed profile. No shared file is changed after each
+question. At the end, INIT renders an adaptive human summary of changed decisions,
+topology, exceptions, sources, and any useful Mermaid projection. The exact canonical
+YAML remains available through `view`.
+
+Profile validation is distinct from task GATE because it affects future tasks. Approval
+creates a compact `ProfileApprovalReceipt` bound to user actor, timestamp, profile
+identity, revision, and exact content digest. The receipt is outside the content digest
+to avoid a digest cycle. One atomic write publishes profile and projections only after
+that validation.
+
+If the user rejects a global update, the shared profile remains byte-for-byte unchanged.
+The mismatch and any explicitly approved task-local exception remain local. Future tasks
+redetect drift from fingerprints. A task may proceed through a local exception unless
+repository policy forbids it.
+
+When no profile exists, ordinary `$dev-flow <objective>` remains usable. SHAPE discovers
+only task-relevant conventions. Durable decisions are accumulated silently and offered
+once as a proposed profile transaction before final SHAPE synthesis; promotion is never
+automatic or asked after every answer.
+
+### Project diagrams are projections
+
+The YAML profile remains canonical. Non-trivial architecture may produce a deterministic
+Mermaid document referenced by profile. Simple projects do not receive mandatory
+diagrams. A diagram never becomes a second authority; manual drift requires explicit
+reconciliation.
+
+## Consequences
+
+- Approved conventions are discovered once and reused without repeated SHAPE questions.
+- Shared architecture stays portable across machines and multi-repository workspaces.
+- Local paths and preferences remain private and non-contractual.
+- Profile drift becomes selective, reviewable, and user-authoritative rather than a
+  full reinitialization or silent overwrite.
+- `$dev-flow init` uses strict profile schemas, deterministic digest/receipt logic, safe
+  multi-root discovery, atomic authority publication, and negative path/privacy tests.
+- The existing `npx codex-dev-flow init` remains compatible and keeps its current purpose.
+- Project INIT/profile behavior is normative in the Project Engineering Profile contract.
+  Ordinary task SHAPE profile consumption remains governed by current lifecycle until
+  ADR 0030 implementation lands.

package/docs/adr/0028-make-public-documentation-user-first-and-current.md

@@ -0,0 +1,65 @@
+# ADR 0028: Make Public Documentation User-First and Current
+
+## Status
+
+Accepted and implemented.
+
+## Context
+
+The repository root README and packaged plugin README served different audiences and had
+drifted. The root explained installation while the packaged README opened with lifecycle
+internals. Neither gave one complete path from installation through Project INIT to a
+first verified task. Public pages also mixed available behavior with accepted target
+design, and completed plans plus superseded ADRs remained in the published package.
+
+Project INIT introduced another naming collision: `$dev-flow init` performs agentic
+project discovery and interview, while `npx codex-dev-flow init` runs a deterministic
+plugin Configuration wizard. A user-first explanation must distinguish them without a
+breaking command rename.
+
+## Decision
+
+Public documentation uses four layers:
+
+```text
+README -> practical guide -> normative contracts -> decision records
+```
+
+- Root and packaged README files lead with value, requirements, installation, Project
+  INIT, a first task, current commands, generated files, configuration, and safety.
+- `docs/getting-started.md` owns the end-to-end walkthrough, resume paths, and common
+  failures.
+- Normative contracts own exact lifecycle, schema, authority, privacy, and transaction
+  rules. README prose links to those rules instead of reproducing all internals.
+- ADRs explain durable trade-offs. Clearly labeled target documents may describe
+  unimplemented design, but README files describe only behavior users can invoke now.
+
+The two README files share tested user-journey invariants but need not be byte-identical.
+The root may add repository development and quality sections. Relative links adapt to
+each location.
+
+Canonical interface names are:
+
+- **Project INIT** for agentic `$dev-flow init`; and
+- **Configuration wizard** for deterministic `npx codex-dev-flow init`.
+
+README diagrams use portable ASCII. The practical guide may use Mermaid for relationships
+that benefit from a rendered graph. Generated screenshots and binary diagrams are not
+required.
+
+Documentation that is fully superseded, describes completed delivery sequencing, or is
+an obsolete implementation plan may be removed after all current references and package
+manifests are updated. Documents that still define runtime behavior remain until their
+replacement is implemented atomically.
+
+## Consequences
+
+- New users can install the plugin, initialize a project, and start a task without first
+  learning TaskState internals.
+- npm package, marketplace, and repository entry points teach the same workflow.
+- Current capability and future target remain visibly separate.
+- Command-name compatibility is preserved while the two INIT concepts become explicit.
+- README alignment and relative links become automated distribution checks.
+- Removing dead history reduces package noise but intentionally trades exhaustive local
+  design archaeology for current, authoritative documentation; Git history remains the
+  archive.

package/docs/adr/0029-make-build-a-native-execution-boundary.md

@@ -0,0 +1,51 @@
+# ADR 0029: Make BUILD a native execution boundary
+
+## Status
+
+Accepted and implemented in TaskState V5.
+
+## Context
+
+Codex already chooses effective edit order, tools, local corrections, and useful
+implementation-time checks. A separate `execute-change` skill repeated that native
+behavior through atomic-task orchestration, checkpoints, validation after every task,
+fingerprints, and a BUILD correction loop. This increased context and state complexity
+without adding a product decision or final correctness proof. ASSURE already owns fresh
+review and criterion-linked verification.
+
+Users still need an explicit lifecycle boundary between approved planning and assurance,
+plus visible phase changes. Codex does not expose a documented plugin API for a custom
+dynamic footer item, so Dev Flow cannot promise a permanent native status-line field.
+
+## Decision
+
+Keep BUILD as one public macro-phase with one internal status: `executing`.
+
+- Announce `[DEV FLOW · GATE → BUILD]` and `[DEV FLOW · BUILD → ASSURE]` only at phase
+  transitions.
+- Before first write or resume, require a current Plan Approval Receipt bound to the exact
+  canonical contract digest.
+- Let native Codex implement the complete approved plan. Dev Flow adds no BUILD-specific
+  skill, model route, orchestration, task checkpoint, progress tracker, validation
+  requirement, fingerprint, or persisted output.
+- Continue local technical corrections natively. Material scope, product behavior,
+  approved architecture, or risk changes stop writes and return through SHAPE then GATE.
+- Transition automatically from `executing` to the applicable ASSURE review or
+  verification lane.
+- Reserve `debug-root-cause` for repeated stable ASSURE failures.
+
+Remove `validating` and `resolving_build`. This changes accepted persisted statuses, so
+TaskState advances from V4 to V5. Older task state fails explicitly; no ambiguous
+migration guesses whether implementation or BUILD validation had completed.
+
+## Consequences
+
+- BUILD prompt and runtime surface become smaller.
+- Worktree diff is implementation truth; ASSURE derives its Diff Capsule from current
+  state rather than consuming a BUILD summary.
+- Formal validation moves entirely to ASSURE. Native Codex may still run useful checks
+  while implementing.
+- Resume remains safe through exact approval/digest reconciliation without BUILD
+  checkpoints.
+- Plugin UI remains honest: phase transitions are visible in conversation, but no custom
+  persistent Codex footer is claimed.