codex-workflow-v2 2.0.0-beta.1 → 2.0.0-beta.11

package/docs/problem-briefs/01-pre-implementation-integrity.md

@@ -0,0 +1,478 @@
+---
+brief_id: WF2-P01
+problem: "Mechanically infeasible Task Plans can reach execution authorization"
+status: approved
+owner: null
+created_at: 2026-08-23
+approved_at: 2026-08-24
+implemented_at: null
+revision: 5
+---
+
+# Brief — P01-A Bounded Mechanical Plan Feasibility
+
+## 0. Evidence and scope
+
+The bounded mechanical problem is **confirmed**. The broader claim that bad Briefs or semantic
+decomposition are a primary cause of repeated fix/review cycles is only partially supported and is
+not part of P01-A.
+
+Confirmed baseline behavior at the pinned pre-candidate revision:
+
+- Task Plan validation checks shape, requirement coverage, Step identifiers, non-empty declared
+  checks and outputs, write declarations, and Step dependency cycles.
+- It does not generally prove that a literal npm script or an exact repository path referenced by a
+  supported Plan form exists at the planning base.
+- Task execution authorization does not contain a mechanical-feasibility result.
+- `TaskState.baseCommit` is `null` until `task start`; therefore it cannot bind a pre-authorization
+  verdict.
+- Current corrective authority already exposes `continue-fix`, `replan-required`,
+  `split-required`, and `stop-escalate`. It has no `implementation-defect`, `plan-defect`,
+  `brief-decomposition-defect`, or `reslice-plan` decision.
+
+The P01-A candidate on `codex/p04-task-dependencies` now adds the bounded evaluator and event
+binding described below. These baseline gaps are retained here as problem evidence, not as claims
+about the candidate implementation. The brief remains `approved` until the combined P04-A/P01-A
+candidate is merged/installed and implementation acceptance is recorded.
+
+The Signal pre-M3 replay additionally showed that a narrow check can pass while a project-reference
+build or architecture check fails. That supports earlier verification, but does not make semantic
+Brief/decomposition admission mechanically decidable. See
+[the replay journal](evidence/signal-v4-pre-m3-replay.md#obs-012--a-narrow-task-check-can-pass-while-the-project-reference-build-or-architecture-contract-fails).
+
+P01-A implements only:
+
+```text
+current Task Plan
+-> deterministic supported analyzers
+-> evidence bound to the planning-base HEAD
+-> authorization guard and exact diagnostics
+```
+
+Discovery materialization admission, semantic ownership/output mapping, causal defect taxonomy, and
+return from Task execution to decomposition authority are deferred to P01-B or another brief.
+
+## 1. Problem
+
+Workflow can authorize a Plan when current repository state and the Plan's own bounded write
+contract already prove that a supported command or exact output target cannot exist when needed.
+The failure is then discovered only after implementation starts.
+
+P01-A prevents only **proven mechanical contradictions**. It does not claim that a mechanically
+clear Plan is semantically sufficient or will produce correct code.
+
+## 2. Required invariants
+
+### INV-1 — Proven mechanical contradiction blocks authorization
+
+An execution authorization cannot be issued when a versioned supported analyzer proves that the
+current Plan cannot satisfy its own command/path precondition within the allowed prior work.
+
+### INV-2 — Unknown is not a negative verdict
+
+Unsupported command syntax, natural-language ambiguity, or a path that a permitted Step may create
+is reported as `unverified`. Core must not convert it into either feasibility proof or mechanical
+failure.
+
+### INV-3 — The verdict binds to the exact evaluation source
+
+Before Task start, the authoritative source binding is:
+
+```text
+baseBranch
+evaluatedHead = rev-parse(baseBranch)
+```
+
+`Task.baseCommit` is not used at that phase because current Core assigns it only during
+`task start`. Start requires the selected base commit to equal the authorized `evaluatedHead`.
+
+For a corrective Plan after Task start, evaluation uses the current committed Task workspace/branch
+HEAD together with the recorded `baseCommit`. It does not switch back to the moving base branch.
+
+### INV-4 — Relevant change invalidates the verdict
+
+A changed Brief hash, Plan hash, selected pre-execution source, analyzer-set version, or other Task
+field consumed by an analyzer requires reevaluation and fresh execution authorization. An unrelated
+Task revision alone is not a freshness signal. A predecessor merge that advances the Task base
+branch before start invalidates an older result. After start, unrelated base-branch movement and
+ordinary Workflow-owned Step commits do not invalidate a verdict whose evaluated commit remains in
+the authorized Task history.
+
+### INV-5 — Existing decisions remain canonical
+
+P01-A does not add corrective-decision values. A pre-authorization contradiction rejects
+authorization and routes to Plan replacement. The same contradiction discovered after execution
+uses existing `replan-required`. Unknown classification uses `stop-escalate`; ordinary code defects
+remain on the existing `continue-fix` route.
+
+### INV-6 — Analysis is bounded and read-only
+
+The preflight never executes arbitrary Plan commands, starts infrastructure, calls providers,
+applies migrations, or mutates the checkout.
+
+### INV-7 — Authorization and evidence are one authority change
+
+A successful execution authorization stores the exact feasibility payload in the appended
+authorization event. There is no independent feasibility credential or sidecar lifecycle that can
+drift from Task state.
+
+## 3. P01-A solution
+
+### A. Boundary
+
+The evaluator runs against the current Plan before `task authorize`. Repository `next` may expose
+the same deterministic report for diagnostics. The mutating authorization path must recompute or
+verify the report against fresh state; it cannot trust an older `next` response.
+
+No new user-visible lifecycle stage is introduced.
+
+### B. Initial supported analyzer set
+
+The first implementation supports only explicitly documented grammars:
+
+1. **Literal root npm script** — a check exactly matching the supported `npm run <literal-name>`
+   grammar refers to a script present in the root `package.json` at `evaluatedHead`.
+2. **Provably impossible npm script** — if the script is absent and neither the current Step nor a
+   completed/declared predecessor before that check may write the root `package.json`, the Plan is
+   blocked. Permission to write the manifest makes the result `unverified`, not automatically
+   feasible, unless a future structured contract explicitly declares the script creation.
+3. **Exact-path output** — an `expectedOutputs[]` entry recognized by an exact documented
+   repository-relative-path grammar is either present at `evaluatedHead` or writable by the
+   responsible Step. An absent path outside that Step's `allowedWrites` is blocked.
+4. **Exact-path predecessor** — a missing exact path may be treated as available to a consumer only
+   when a declared predecessor owns that exact output path and is allowed to write it. Prose,
+   directory overlap, or ordinal is insufficient.
+
+All other command forms and semantic claims are `unverified`. Adding an analyzer later requires a
+new stable analyzer ID/version and regression fixtures; it must not silently change an existing
+analyzer's meaning.
+
+The revision-4 frozen grammar is exact:
+
+```text
+wf2.root-npm-script@1
+  raw check = ^npm run ([A-Za-z0-9][A-Za-z0-9:_-]*)$
+
+wf2.exact-output-path@1
+  raw expected output = path:<repository-relative POSIX path>
+
+wf2.exact-predecessor-path@1
+  same exact path + transitive declared Step dependency + predecessor write permission
+```
+
+The structured path contains no empty, `.` or `..` segment or glob token; every segment matches
+`[A-Za-z0-9._-]+`. Bare path-like prose is not recognized. `npm test`, arguments, flags, quoting,
+environment prefixes, shell operators, alternate package managers, and surrounding whitespace are
+not recognized. The evaluator reuses the current `allowedWrites` matcher only after an exact
+structured path has been decoded; it never infers a path from prose.
+
+Analyzer order is the fixed order above. Findings are canonicalized by Step ID, analyzer ID, raw
+subject, and result. The analyzer-set hash is SHA-256 over canonical JSON containing the exact
+analyzer IDs and versions.
+
+P01-A does not attempt to map every acceptance item to behavioral proof. That requires the
+structured evidence relation and semantic authority owned by P02/P01-B.
+
+### C. Exact evidence contract
+
+Extend the existing execution `AuthorizationEvent` with an optional payload equivalent to:
+
+```text
+MechanicalFeasibilityEvidence {
+  schemaVersion
+  taskId
+  evaluatedTaskRevision
+  briefHash
+  planHash
+  sourceKind: pre-start-base | corrective-task-workspace
+  sourceBranch
+  evaluatedHead
+  baseCommit?
+  analyzerSetHash
+  analyzers[] {
+    analyzerId
+    analyzerVersion
+  }
+  findings[] {
+    analyzerId
+    result: pass | blocked | unverified
+    stepId
+    subject
+    evidence
+    reasonCode
+  }
+  decision: clear | blocked
+}
+```
+
+`clear` means only “no supported analyzer proved infeasibility”; it is not a semantic feasibility
+claim. The canonical payload hash is stored in the event's existing `evidenceHash`, and
+`evaluatedHead` is stored in its existing `headCommit`. The event, payload, hash, and transition to
+`ready` are written atomically with Task state.
+
+The payload is optional in the persisted TypeScript/JSON contract only for execution
+authorizations written before P01-A. Every new authorization writes it. Existing already-ready or
+in-progress legacy Tasks retain the earlier Brief/Plan hash freshness rule because Core has no safe
+transition that can retroactively move them back through authorization without inventing human
+authority. Their bounded residual risk remains covered by beta.11 Plan-integrity recovery. Any
+new Plan, Knowledge rebind/context refresh, or corrective authorization writes current P01-A
+evidence.
+
+Blocked authorization writes no approved event. Its error and `next` diagnostics return the same
+bounded findings without inventing a durable approval.
+
+### D. Freshness
+
+Core selects the source for each new evaluation deterministically:
+
+```text
+Task.baseCommit is null
+-> sourceKind = pre-start-base
+-> sourceBranch = Task.baseBranch
+
+Task.baseCommit is present
+-> sourceKind = corrective-task-workspace
+-> sourceBranch = Task.taskBranch/current owned workspace branch
+-> include recorded baseCommit
+```
+
+During the mutating authorization transition, Core builds the payload from fresh values:
+
+```text
+current briefHash / planHash
+current selected source kind / branch / HEAD / baseCommit
+current analyzerSetHash
+current values of any other Task fields consumed by a supported analyzer
+```
+
+Those values become the approved event binding only if the decision is `clear` and the Task write
+commits. Later direct entries compare current authority with that stored binding according to the
+phase rules below.
+
+`evaluatedTaskRevision` is retained for audit and diagnostics; it is not compared blindly with the
+current revision because unrelated Task transitions must not invalidate mechanical evidence.
+
+Direct-entry freshness then depends on phase:
+
+```text
+before task start
+-> current baseBranch HEAD must equal evaluatedHead
+
+after task start, for a pre-start-base event
+-> Task.baseCommit must equal evaluatedHead
+-> evaluatedHead must remain an ancestor of current Task HEAD
+
+after task start, for a corrective-task-workspace event
+-> recorded baseCommit must still match
+-> evaluatedHead must remain an ancestor of current Task HEAD
+```
+
+A pre-start `task start` cannot authorize one commit and branch from another. Successful start seals
+that binding as `Task.baseCommit`; the event does not become stale merely because the phase changes.
+Workflow-owned Step commits may advance Task HEAD while preserving ancestry. A Plan replacement,
+history rewrite that removes `evaluatedHead`, explicit source rebinding, or mismatched `baseCommit`
+requires reevaluation and fresh authorization. P04-A supplies predecessor dependency authority;
+P01-A observes its effect on the pre-start base HEAD rather than duplicating the dependency graph.
+
+### E. Routing
+
+Before execution:
+
+```text
+blocked mechanical finding
+-> reject task authorization
+-> retain/supersede Plan according to current Plan update rules
+-> return exact task plan-set/corrective-replan route
+```
+
+After execution has started:
+
+```text
+proven mechanical Plan contradiction
+-> existing replan-required decision
+-> current corrective-replan path
+-> rerun P01-A
+-> fresh authorization
+```
+
+P01-A does not introduce causal labels into the corrective-decision union. A stable reason code may
+identify `mechanical-plan-infeasibility` inside evidence, but authority remains
+`replan-required`. If the repair would change Task scope or decomposition, P01-A stops; it does not
+silently map the condition to `split-required` because that decision has terminal replacement
+semantics.
+
+### F. Diagnostics
+
+`next` and authorization failures expose, without credentials:
+
+```text
+analyzer ID/version
+binding HEAD and Plan hash
+Step and subject
+pass / blocked / unverified
+concrete repository or Plan evidence
+required existing route
+```
+
+Unsupported syntax must be distinguishable from a proved missing prerequisite.
+
+## 4. Validation
+
+### 4.1 Contract and freshness tests
+
+- exact supported npm script at the evaluated HEAD is clear;
+- missing script outside all responsible manifest write bounds blocks;
+- missing script with a permitted manifest-writing Step is `unverified`, not pass;
+- absent exact output path outside `allowedWrites` blocks;
+- exact predecessor-owned path is accepted only with a declared dependency and exact write/output
+  match;
+- prose output and unsupported commands remain `unverified`;
+- analyzer IDs, versions, ordering, canonical payload, and hash are deterministic;
+- Plan, Brief, pre-start source HEAD, source ancestry/baseCommit, analyzer-set, or another
+  analyzer-consumed field change invalidates the event;
+- an unrelated Task revision does not invalidate the event;
+- a P04 predecessor merge before start invalidates authorization through base-HEAD drift;
+- unrelated base-branch movement and ordinary descendant Step commits after start do not invalidate
+  the event;
+- a history rewrite that removes `evaluatedHead` from Task ancestry fails closed;
+- evidence payload, event hash, and Task `ready` transition cannot partially commit.
+
+### 4.2 Routing tests
+
+- a pre-authorization block returns to current Plan replacement without consuming an implementation
+  attempt;
+- a late proved Plan contradiction uses `replan-required`;
+- an ordinary implementation defect remains `continue-fix`;
+- a scope/decomposition ambiguity does not get mislabeled as `split-required` by P01-A;
+- unknown classification returns `stop-escalate` where current policy requires a decision.
+
+### 4.3 Synthetic E2E
+
+1. Reject a missing npm script that no responsible Step may create before implementation starts.
+2. Report `unverified`, without a false pass, when the current Plan permits a predecessor to edit
+   the manifest but does not structurally declare script creation.
+3. Authorize a valid low-risk Plan without an extra semantic agent review.
+4. Advance the base branch after pre-start authorization and prove that claim/start is rejected
+   until fresh evaluation and authorization.
+5. Advance the base branch and add an authorized descendant Step commit after Task start; neither
+   makes the event falsely stale.
+6. Rewrite Task history so that `evaluatedHead` is no longer an ancestor and prove execution fails
+   closed.
+7. Discover a genuine mechanical contradiction after execution and route through current
+   corrective replan.
+
+### 4.4 Replay controls
+
+Before fail-closed enforcement, evaluate a version-pinned corpus containing:
+
+- successful single- and multi-Step Plans;
+- ordinary implementation remediations;
+- known missing-script/path contradictions;
+- unsupported command forms.
+
+Record earliest detection, finding classification, false blockers, and transitions avoided.
+Unverified findings are measured separately and are not counted as passes.
+
+Revision-4 replay evidence is recorded in
+[the P01-A corpus journal](evidence/p01-mechanical-feasibility-corpus.md). The pinned corpus produced
+three exact supported contradictions, zero false blockers among successful controls, and preserved
+unsupported shell/prose and semantic coverage claims as `unverified`.
+
+## 5. Design approval gate
+
+P01-A is recommended after P04-A. It may move from `hypothesis` to `approved` only when:
+
+1. The supported command/path grammars and canonicalization fixtures are explicit.
+2. Each analyzer has a stable ID/version and cannot execute the Plan.
+3. The authorization payload, hash reuse, atomic write, and diagnostics are accepted as the exact
+   evidence contract.
+4. Freshness uses exact base-branch HEAD before start and source ancestry plus `baseCommit` after
+   start, without invalidating ordinary descendant Step commits.
+5. Existing corrective decisions and transitions cover every P01-A route without a new decision
+   enum.
+6. Corpus replay shows that proven blockers are real contradictions and unsupported cases remain
+   unverified.
+
+## 6. Implementation acceptance
+
+P01-A may move from `approved` to `implemented` only when:
+
+1. Every declared contract, freshness, routing, E2E, and atomicity test passes.
+2. Proven supported contradictions block authorization and direct execution entry points.
+3. Selected source or Plan authority drift requires fresh evaluation and authorization without
+   treating unrelated post-start base movement or descendant Step commits as stale.
+4. Low-risk valid Plans gain no mandatory semantic review or lifecycle stage.
+5. Unsupported analysis never becomes an invented pass or failure.
+6. Current correction/replan behavior remains compatible for ordinary implementation defects.
+7. No new credential, feasibility sidecar lifecycle, Contract Registry, Context Graph, or
+   decomposition state machine is introduced.
+
+## 7. Dependencies and conflicts
+
+- P04-A should land first so predecessor satisfaction and the base-HEAD invalidation scenario are
+  canonical.
+- P02 owns output-to-verification semantics and Step usefulness; P01-A does not infer them.
+- P03 may project the current feasibility binding but cannot recompute or approve it.
+- P05/P04-B owns replacement after `split-required`.
+- P01-A must not repurpose `split-required` as a generic decomposition label.
+
+## 8. Deferred P01-B questions
+
+P01-A intentionally leaves these unresolved:
+
+- What durable authority represents Task boundary, ownership, prerequisite, and verification
+  allocation before materialization?
+- How is semantic acceptance-to-evidence mapping represented without duplicating P02?
+- Does decomposition repair mutate Discovery, materialize replacement Tasks, or require a distinct
+  transition?
+- Is a causal defect class metadata on existing decisions, or is a new decision model actually
+  necessary?
+- How are implementation-attempt counters distinguished from Plan/decomposition repair?
+
+P01-B remains `NO-GO` until those questions have concrete contracts and fresh replay evidence.
+
+## 9. Non-goals
+
+- Discovery/decomposition semantic admission;
+- semantic proof that checks establish behavior;
+- Step usefulness and reslicing;
+- Task dependency storage or scheduling;
+- structural replacement topology;
+- executing arbitrary Plan commands;
+- requiring the full repository suite for every Step;
+- proving future implementation correctness.
+
+## 10. Decision log
+
+- 2026-08-23 — Revision 1 created as `hypothesis`.
+- 2026-08-24 — Revision 2 narrowed arbitrary pre-execution validation to supported deterministic
+  analyzers and recorded Signal replay evidence.
+- 2026-08-24 — Revision 3 split the implementable P01-A mechanical boundary from deferred P01-B
+  semantic decomposition work.
+- 2026-08-24 — Feasibility binding changed from unavailable pre-start `Task.baseCommit` to an exact
+  phase-aware source: `baseBranch` HEAD before start and Task-workspace HEAD plus `baseCommit` after
+  start. Post-start freshness uses commit ancestry, so predecessor/base drift invalidates pre-start
+  authorization without treating authorized Step commits as stale.
+- 2026-08-24 — Mechanical evidence was placed inside the existing execution authorization event;
+  new corrective decision values and a separate evidence lifecycle were rejected.
+- 2026-08-24 — P01-A designated `GO after P04-A`; P01-B remains `NO-GO`.
+- 2026-08-24 — Revision 4 froze three analyzer IDs/versions, exact literal npm and `path:`
+  grammars, canonical ordering/hash rules, and the conservative unsupported boundary.
+- 2026-08-24 — The version-pinned corpus replay found three real supported contradictions, zero
+  false blockers among successful controls, and kept unsupported shell/prose and Signal semantic
+  coverage claims `unverified`.
+- 2026-08-24 — Design review accepted the existing execution authorization event as the sole
+  feasibility authority, phase-aware HEAD/ancestry freshness, current corrective decisions, and
+  atomic Task-state write. Status moved from `hypothesis` to `approved`; implementation has not
+  started at this decision boundary.
+- 2026-08-24 — Revision 5 records the combined-branch implementation candidate: three read-only
+  analyzers, deterministic evidence/hash binding, pre-lease claim and execution-entry freshness,
+  `next` diagnostics, and legacy beta.11 compatibility. The document remains `approved` pending
+  merge/install and final implementation acceptance.
+- 2026-08-24 — Candidate validation passed typecheck, plugin/schema validation, 12/12 focused
+  P01-A tests, 4/4 beta.11 late-recovery compatibility tests, and the full combined 318/318 suite.
+  This is review/merge evidence, not an `implemented` status change.
+- 2026-08-24 — Final source review closed a start-time TOCTOU window by comparing the authorized
+  base commit again inside local branch creation before Git mutation. The new negative witness and
+  the complete affected P01/P04/Task lifecycle selection passed 13/13 and 84/84 respectively;
+  the exact final candidate then passed the full 319/319 suite.