feat: add product continuity contracts

CHANGELOG.md

@@ -27,11 +27,23 @@ All notable changes follow Keep a Changelog and Semantic Versioning.
   exact post-merge closure with an executable delivery-record contract.
 - Coordinator-enforced remote attendance, one readback-authorized effect retry,
   changing-blocker replacement, and database-swap state-restore recovery.
+- Source manifests, stable product invariants and decision cards, canonical
+  specification assessment/promotion/diff, approved impact manifests, and
+  item-level new-behavior versus preservation evidence.
+- One internal Codex worker adapter with immutable profile and invocation
+  contracts, durable admission/launch/settlement state, recursive instruction
+  freezing, and strict provider-event settlement.
+- A source-qualified Node.js 24, Next.js 16, and React 19.2 web-recipe decision
+  for the Wave 4B greenfield path.
 
 ### Changed
 
 - Dependabot preserves the qualified Node type and TypeScript major boundaries;
   incompatible major upgrades require an intentional toolchain qualification.
+- Executable JSON Schemas are generated from runtime contract inputs and checked
+  for exact drift in the native gate.
+- New baseline qualifications and runs require task-packet version 2 with exact
+  continuity authority; version 1 remains byte-stable for in-flight resume.
 
 ### Deprecated
 
@@ -66,6 +78,13 @@ All notable changes follow Keep a Changelog and Semantic Versioning.
 - Bound task, configuration, authority, context, instruction, and declared
   command-control inputs cannot overlap candidate output scope or be rewritten
   into a validated commit.
+- Legacy context manifests retain their exact bytes; new runs freeze Codex
+  instruction override precedence, reject instruction-path drift, and keep
+  effective instructions outside candidate write scope. Semantic authority
+  rejects duplicate IDs, unbound oracle commands, future-dated approvals, and
+  attestations that do not bind the complete canonical item. Conflicting worker
+  terminal events fail closed; review evidence and worker settlement commit
+  atomically, while blocked planning assessments return truthful failures.
 - Writer exclusion now uses a crash-released SQLite transaction instead of a
   stale-directory protocol; cancellation is polled by the exact foreground
   owner, persisted PIDs are never signalling authority, and delayed exits clear
@@ -75,6 +94,17 @@ All notable changes follow Keep a Changelog and Semantic Versioning.
 - OCI verification safely aliases comma-bearing bind paths, and restoring an
   older state backup quarantines newer unreferenced worktrees with durable
   recovery evidence rather than deleting them.
+- Planning promotion now rebinds approval to the proposal's current canonical
+  bytes; task semantics and selected scenarios must match approved impact, and
+  inactive impact exceptions grant no authority.
+- Candidate publication and mutating-worker settlement are atomic, review
+  attempts use their exact per-candidate generation, and worker profile digests
+  bind the prompt-template bytes actually used by the adapter.
+- Product outcomes now carry stable IDs that impact manifests must resolve;
+  single-blueprint proposals are valid, duplicate source identities block, and
+  expired effect authority cannot strand readback or truthful closure.
+- Worker exit evidence and active-process clearing now commit atomically, so a
+  controller crash after process exit leaves a safely reconcilable invocation.
 
 ### Security
 

README.md

@@ -12,6 +12,13 @@ CI/review observation, human merge, and truthful closure. The CLI is `millctl`,
 published eventually as `@davidahmann/mill` to avoid collision with the existing
 `mill` command and npm package.
 
+Wave 4A adds source-backed planning contracts, stable product invariants,
+approved per-slice impact, scenario-specific semantic evidence, and durable
+worker admission. Its planning commands are deliberately read-only: today an
+operator supplies the structured proposal, while Wave 4B will coordinate the
+qualified planner and transactionally apply the first Node.js 24/Next.js 16 web
+recipe.
+
 Mill's v1 boundary is deliberately narrow:
 
 - local and attended;
@@ -125,17 +132,19 @@ processes receive neither GitHub credentials nor mutation tools. Mill journals
 intent before push and PR creation, uses an expected-old-head lease, and reads
 GitHub back before claiming an effect. An uncertain outcome becomes
 `effect_unknown`; `pr reconcile` is read-only and must classify it before any
-retry. Exact readback proving absence authorizes one retry; a second absent
-outcome blocks. Required checks pass only when every latest exact-head result is
-successful. A configured `github_required` reviewer may complete a current-head
-`APPROVED` or `COMMENTED` review, but any current-head actionable finding still
-blocks, including a severity-tagged top-level review body. Mill stops at
-`awaiting_human`; draft readiness is not closure authority and Mill never
-changes it or merges. Finalization verifies the recorded merger against
-`allowedMergerLogins`. Because GitHub does not expose an authoritative
-distinction between a one-commit squash and rebase, the provable policy is
-`linear_tree_preserving`; Mill never guesses a specific linear method from its
-allowlist.
+retry. Expired impact authority blocks a new remote mutation but does not block
+readback, observation, or truthful finalization of an already attempted effect.
+Exact readback proving absence authorizes one retry only while current mutation
+authority remains valid; a second absent outcome blocks. Required checks pass
+only when every latest exact-head result is successful. A configured
+`github_required` reviewer may complete a current-head `APPROVED` or `COMMENTED`
+review, but any current-head actionable finding still blocks, including a
+severity-tagged top-level review body. Mill stops at `awaiting_human`; draft
+readiness is not closure authority and Mill never changes it or merges.
+Finalization verifies the recorded merger against `allowedMergerLogins`. Because
+GitHub does not expose an authoritative distinction between a one-commit squash
+and rebase, the provable policy is `linear_tree_preserving`; Mill never guesses
+a specific linear method from its allowlist.
 
 Use `--json` before the command for the stable machine-readable envelope.
 `--json --version` is machine-readable; help is human-only and combining it with
@@ -163,28 +172,32 @@ exact-candidate evidence is accepted. Each verifier command has a unique
 Mill-owned container name, and Mill force-removes that exact container under a
 fresh cleanup deadline before accepting evidence. Mill ignores operator Codex
 configuration, disables host skill search, and ignores ambient execution rules
-for builder/reviewer invocations; repository-local `AGENTS.md` instructions
-still apply. Provider usage is measured when Codex reports it, while currency
-cost is reported as unavailable rather than estimated. Completion events in the
-redacted support bundle preserve that source-qualified token evidence for the
-initial build, retries, repairs, and review.
+for builder/reviewer invocations; repository-local `AGENTS.override.md` or
+`AGENTS.md` instructions still apply. Provider usage is measured when Codex
+reports it, while currency cost is reported as unavailable rather than
+estimated. Completion events in the redacted support bundle preserve that
+source-qualified token evidence for the initial build, retries, repairs, and
+review.
 
 The builder can read the non-sensitive tracked files in its disposable worktree;
 `contextPaths` are frozen, read-only priority inputs, not a filesystem read ACL.
-They, `mill.yaml`, the active task, authority files, repository instructions,
-and each selected command's declared `controlPaths` cannot overlap task output
-scope or enter the candidate. `controlPaths` name the scripts, tests, manifests,
-or other repository files that define the selected command's acceptance oracle.
-Qualification therefore rejects tracked symlinks and any tracked path matched by
-`sensitivePaths`. Keep secrets and other excluded material untracked and outside
-the repository.
+They, `mill.yaml`, the active task, authority files, the frozen effective
+repository-instruction set, and each selected command's declared `controlPaths`
+cannot overlap task output scope or enter the candidate. `controlPaths` name the
+scripts, tests, manifests, or other repository files that define the selected
+command's acceptance oracle. Qualification therefore rejects tracked symlinks
+and any tracked path matched by `sensitivePaths`. Keep secrets and other
+excluded material untracked and outside the repository.
 
 ## Status
 
 Not published. Local attended delivery and the bounded draft-PR lifecycle are
-implemented and covered by fake-provider and packed-package canaries. The first
-attended disposable real-GitHub canary, hostile-host containment, release, and
-generalized stack-compatibility claims remain pending their explicit gates.
+implemented, and the first disposable real-Codex/GitHub canary was human-merged,
+verified on resulting main, and truthfully finalized. Product-continuity and
+worker-admission contracts are implemented. Transactional recipe application,
+retrofit, the founder `start` coordinator, stronger hostile-host containment,
+genesis release, and generalized stack-compatibility claims remain pending their
+explicit gates.
 
 ## License
 

WORKFLOW.md

@@ -7,7 +7,9 @@ bookkeeping, closure, tests, or docs into micro-PRs.
 1. Foundation and static inspection.
 2. One manual local slice to an exact reviewed commit.
 3. Exact commit to draft PR, reconciliation, and closure.
-4. PRD intelligence, one greenfield recipe, retrofit, and founder golden path.
+4. Product continuity, one greenfield web recipe, retrofit, and founder golden
+   path. Wave 4A establishes the read-only contracts and durable worker
+   boundary; Wave 4B applies them transactionally.
 5. Audits, clean-room qualification, genesis distribution, and public alpha.
 
 For each wave:
@@ -24,6 +26,16 @@ For each wave:
 8. A human may mark the draft ready; David, the configured merger, merges it.
    Observe the resulting main commit and checks.
 
+Before a Wave 4 implementation task can execute, freeze the source manifest,
+approved product contract, stable outcome and invariants, selected scenarios,
+material decisions, and exact impact approval. Each impact must resolve to its
+approved outcome. Each required acceptance, invariant, and scenario ID must
+resolve to executed command evidence, an unexpired human attestation, or a
+blocking unsupported disposition. Expiration removes authority for new effects;
+it does not prevent readback or closure of an effect already attempted. A
+current candidate may add future oracles, but those changed oracles do not
+independently certify that same candidate.
+
 Current Factory skills are optional maintainer-side bootstrap tools. Their
 prompts, profiles, artifacts, or state are not Mill runtime or product
 dependencies. Native repository commands remain sufficient and authoritative.

architecture/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # Mill architecture
 
-Status: approved v1 decision Last updated: 2026-09-01
+Status: approved v1 decision Last updated: 2026-09-02
 
 ## Form
 
@@ -50,22 +50,54 @@ The builder never receives forge/deployment authority. The shipper cannot create
 or amend the candidate commit. Product/oracle changes invalidate the candidate.
 Provider state is authoritative for external effects.
 
+Wave 4A adds two fail-closed seams without adding another harness. Read-only
+planning commands assess an operator-supplied PRD, disclosed source manifest,
+and structured proposal; they return blockers, semantic differences, canonical
+bytes, and exact approval digests without writing files, running repository
+commands, or invoking a model. Live research and proposal generation remain an
+explicit later coordinator step, not an implied crawler. Approved product
+contracts carry stable outcome, acceptance, invariant, decision, and scenario
+IDs. Each material task binds one approved outcome and an exact human-approved
+impact manifest, and validation reports new-behavior and preservation evidence
+separately. Scenario and invariant evidence must execute their own approved
+command or carry an unexpired human attestation with an exact kind, stable ID,
+and content-digest claim for that item; an acceptance claim or generic passing
+command cannot certify another semantic item. Task-packet version 1 remains a
+byte-stable, resume-only legacy shape for in-flight runs. Every new run uses
+version 2, which requires the impact manifest and exact product-to-task semantic
+graph.
+
+Codex remains the only worker implementation behind an internal `WorkerAdapter`.
+Before every builder, repair, or reviewer process starts, Mill records an
+immutable redacted invocation envelope containing the task, context epoch,
+candidate when applicable, role profile, prompt-template digest, allowed scope,
+deadline, and output budget. Launch intent is durable before spawn. Exactly one
+terminal provider event settles an invocation, and reviewers must emit exactly
+one structured result. Candidate publication is atomic with its mutating-worker
+settlement, and review-result publication is atomic with its reviewer
+settlement, so a crash cannot consume an attempt without preserving the
+corresponding result. Process exit is journaled against the invocation in the
+same transaction that clears its active-process binding. A possibly started
+mutating invocation becomes uncertain and is reconciled from candidate, process,
+and worktree state instead of being blindly replayed.
+
 The GitHub adapter is isolated behind the delivery coordinator. Planning reads
 the live delegated actor, repository node identity, clone URL, fork status and
 default branch, then binds them with the candidate commit/tree, task/config,
 branch, required checks, review policy, allowed merge methods, approval expiry,
 and intended effects. Only `pr open` mutates. Its effect journal records intent
 and call start before each push or PR request, caps each effect at two attempts,
 and makes ambiguous results enter `effect_unknown`. Reconciliation performs
-authoritative branch/marker/PR readback without mutation. Exact absence permits
-one retry; a second absent outcome blocks for human disposition. The same
-recorded PR number, node identity, marker, branch, base, open-draft state, and
-observed head are invariant whether an ambiguous repair push is absent or
-landed. A retry performs that check again from a fresh readback immediately
-before recording call start and invoking Git. GitHub API collections are
-paginated under one deadline and output budget. Tokens remain behind the
-operator-owned `gh` and Git credential-helper boundary and are not passed to
-Codex or stored in state.
+authoritative branch/marker/PR readback without mutation. Expiration blocks new
+mutation authority but never prevents readback or truthful lifecycle closure for
+an already attempted effect. Exact absence permits one retry; a second absent
+outcome blocks for human disposition. The same recorded PR number, node
+identity, marker, branch, base, open-draft state, and observed head are
+invariant whether an ambiguous repair push is absent or landed. A retry performs
+that check again from a fresh readback immediately before recording call start
+and invoking Git. GitHub API collections are paginated under one deadline and
+output budget. Tokens remain behind the operator-owned `gh` and Git
+credential-helper boundary and are not passed to Codex or stored in state.
 
 One stable delivery key and branch identify the PR across the single allowed
 repair. A new candidate gets new validation, review, approval, and push-effect
@@ -90,14 +122,17 @@ and credentials. Codex invocations ignore operator configuration and execution
 rules and disable host skill search to prevent globally installed workflows from
 silently changing task behavior or token use. They still use the operator-owned
 authentication home and honor repository-local instructions, so this is input
-control rather than host containment. `contextPaths` select frozen priority
-read-only context rather than limiting filesystem reads. The active task,
-`mill.yaml`, authority files, repository instructions, and selected-command
-`controlPaths` form the immutable oracle closure and cannot overlap candidate
-output scope. Build qualification rejects tracked symlinks and configured
-sensitive paths, Git replacement refs, and graft metadata before creating the
-worktree; lifecycle Git commands also disable replacement objects. Secrets must
-remain untracked and outside the repository.
+control rather than host containment. Mill freezes the effective per-directory
+`AGENTS.override.md` or `AGENTS.md` choice and re-enumerates the complete path
+set before every later worker wake; changed bytes, additions, removals, or
+precedence changes invalidate the context epoch. `contextPaths` select frozen
+priority read-only context rather than limiting filesystem reads. The active
+task, `mill.yaml`, authority files, repository instructions, and
+selected-command `controlPaths` form the immutable oracle closure and cannot
+overlap candidate output scope. Build qualification rejects tracked symlinks and
+configured sensitive paths, Git replacement refs, and graft metadata before
+creating the worktree; lifecycle Git commands also disable replacement objects.
+Secrets must remain untracked and outside the repository.
 
 Baseline qualification is part of build authority, not static inspection. The
 runtime enforces the repository trust ceiling before OCI discovery or command
@@ -136,13 +171,21 @@ allowing writes. There is no background daemon or implicit retry.
 - product, scenario, blueprint, and JIT compilers;
 - static repository scanner and transactional bootstrap/retrofit engine;
 - frozen context compiler and Codex adapter;
+- immutable worker profile, admission, launch, and settlement journal;
 - SQLite control plane and append-only run events;
 - worktree/process runner and command policy;
 - native verifier and scenario runner;
 - exact-candidate local reviewer and bounded repair coordinator;
 - GitHub shipper, effect journal, readback, and closure;
 - audits and qualification/release commands.
 
+The first qualified greenfield recipe is a Node.js 24 TypeScript web modular
+monolith using Next.js 16 App Router and the React 19.2 family. It is
+deliberately one recipe, not a generalized stack claim. Wave 4B must freeze
+exact dependency and OCI identities, generate native
+lint/type/unit/integration/browser/build gates, and prove the repository works
+without Mill before applying it.
+
 ## Identity and authority
 
 Product truth and native commands come from the canonical Git revision.