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

package/docs/problem-briefs/02-minimal-step-integrity.md

@@ -0,0 +1,411 @@
+---
+brief_id: WF2-P02
+problem: "STEP is not a safe and useful independently verifiable increment"
+status: hypothesis
+owner: null
+created_at: 2026-08-23
+approved_at: null
+implemented_at: null
+revision: 4
+---
+
+# Brief — Minimal Step Integrity
+
+## 0. Evidence status
+
+The semantic enforcement gap is **partially confirmed**. The original data-model proposal is not
+accepted.
+
+Workflow already represents:
+
+```text
+Step.expectedOutputs[]  -> candidate postconditions
+Step.checks[]           -> executable verification
+Step.dependencies[]     -> explicit Step prerequisites
+```
+
+Current validation requires these fields, rejects missing/self dependencies and cycles, and blocks
+execution until declared dependencies are complete. Therefore P02 must not add duplicate
+`postcondition`, `verification`, or `dependencies[]` fields.
+
+The remaining problem is semantic:
+
+- non-empty `expectedOutputs[]` are not proven to describe a useful valid Task state;
+- non-empty `checks[]` are not traced to the outputs they prove;
+- Workflow does not determine whether a future Step is required to make the current Step safe or
+  meaningful;
+- a Plan can still be sliced by implementation activity rather than independently valid outcomes.
+
+Two implementation contracts are currently absent:
+
+- `expectedOutputs[]` and `checks[]` are independent arrays, so Core cannot prove which evidence is
+  intended to establish which output;
+- semantic usefulness and future-Step independence have no declared authority on the low-risk path.
+
+P02 is therefore `NO-GO` until the contract and authority proposed below pass the required replay.
+
+The Signal pre-M3 replay supplied supporting examples:
+
+- compatible-root lookup was initially treated as a reference lookup, although a hit must terminate
+  formalization without another content read, extraction, or evidence write;
+- inbox existence was initially treated as terminal completion, although a retryable failure must
+  allow the same event to succeed later;
+- a narrow check set passed while project-reference build and architecture checks still failed.
+
+See
+[OBS-008 through OBS-012](evidence/signal-v4-pre-m3-replay.md#obs-008--finding-a-compatible-root-record-must-short-circuit-extraction-and-persistence).
+
+The replay did not exercise Workflow-materialized Steps or separate Planner/Worker/Reviewer roles,
+so it does not by itself prove that historical Step slicing caused the observed M3 failures.
+
+## 1. Problem
+
+A Step must be a useful transition between valid Task states, not merely one activity in the
+Implementer's preferred sequence.
+
+Invalid example:
+
+```text
+STEP-001 create half of an internal mechanism
+STEP-002 create the other half
+STEP-003 connect both halves
+STEP-004 first prove observable behavior
+```
+
+Earlier Steps are not independently useful if their correctness can only be established after
+STEP-003 or STEP-004.
+
+Minimal rule:
+
+> A Step is the smallest independently verifiable transition from one valid Task state to another
+> valid Task state.
+
+A valid Task may contain one Step when smaller boundaries would be artificial.
+
+## 2. Existing contract interpretation
+
+P02 standardizes the semantics of current fields:
+
+### `expectedOutputs[]`
+
+Each entry is an externally reviewable postcondition: a fact that becomes true when the Step
+completes.
+
+Activity-only descriptions are insufficient:
+
+```text
+bad:  "add repository class"
+good: "duplicate delivery returns the previously committed result without creating new evidence"
+```
+
+### `checks[]`
+
+Checks are executable evidence for the declared outputs. At Plan validation time, each output must
+map to at least one check or to a named review assertion governed by the current guarded-review
+policy.
+
+This is target semantics, not a claim about the current schema. The existing independent arrays
+cannot represent that relation exactly, and Core must not infer it from text similarity or array
+position.
+
+Command existence and semantic adequacy are separate:
+
+- P01 proves supported mechanical feasibility;
+- P02 proves that the planned evidence is capable of demonstrating the Step postcondition;
+- execution proves whether the implementation actually satisfies it.
+
+### `dependencies[]`
+
+Dependencies contain only real Step prerequisites. Ordinal is identity, presentation, and scheduler
+tie-break information; it does not establish correctness.
+
+Workflow already validates and enforces these edges. P02 changes their semantic admission rule, not
+their storage or execution model.
+
+## 3. Required invariants
+
+### INV-1 — Every Step declares a valid-state transition
+
+`expectedOutputs[]` state what is observably true after completion. Implementation activities alone
+do not satisfy the contract.
+
+### INV-2 — Every output has boundary-time verification
+
+At least one declared check or applicable guarded-review assertion can prove each expected output
+without unfinished future work.
+
+### INV-3 — A future Step cannot complete the current Step
+
+If Step B is required to make Step A correct, safe, meaningful, or verifiable, A is not a valid
+boundary. The Plan must merge or reslice the Steps.
+
+### INV-4 — Completed Step state is safe
+
+Required repository checks pass, the Step-specific verification passes, the postconditions hold,
+and the repository remains within the authorized write and architecture boundaries.
+
+### INV-5 — Dependencies are causal
+
+For every `B dependsOn A`, B must require a postcondition established by A. Lower ordinal alone is
+not evidence.
+
+### INV-6 — Risk policy controls Review cost
+
+Guarded/high-risk Steps require the existing strict Step Review. Low-risk Steps may become canonical
+through Workflow-owned commit plus successful checks under current policy. P02 does not add
+mandatory strict Review to every Step.
+
+### INV-7 — Invalid slicing is not an implementation defect
+
+An invalid Step boundary routes to Plan reslicing. If repair changes Task scope, ownership,
+requirement allocation, or Task decomposition, deferred P01-B or current scope/replacement authority
+must route it; P01-A does not.
+
+## 4. Required design contract before implementation
+
+### 4.1 Minimal output-to-evidence relation
+
+Keep the existing `expectedOutputs[]` and `checks[]` as canonical content and add only the missing
+relation to each `PlanStepInput`:
+
+```text
+verificationMap[] {
+  outputIndex
+  evidenceRefs[] =
+    { kind: check, checkIndex }
+    | { kind: plan-risk-proof, failureMode }
+}
+```
+
+Rules:
+
+- every output index appears exactly once;
+- every check index and output index resolves inside the same Step;
+- a `plan-risk-proof` reference resolves to one unique proof obligation for that Step and is allowed
+  only when current guarded-risk policy requires the Plan Risk Audit;
+- reordering or changing outputs, checks, proof obligations, or Steps changes the Plan/audit binding;
+- Core validates referential completeness and timing, but does not claim semantic adequacy from the
+  mapping alone;
+- no duplicate postcondition, check command, dependency, or new Step authority object is added.
+
+Index-based references are intentional because the arrays are part of the canonical Plan hash. If
+implementation selects stable entry IDs instead, the brief must first define their uniqueness,
+hashing, and compatibility semantics; it may not mix both representations.
+
+### 4.2 Semantic authority
+
+The Planner authors the output and mapping. Authority is risk-dependent:
+
+- for a low-risk Plan, existing human/delegated Task execution authorization accepts the semantic
+  claim; Core performs only structural and temporal validation and no extra agent Review is added;
+- for a guarded Plan, the existing independent Plan Risk Auditor must assess useful-state,
+  boundary-time evidence, future-Step independence, and causal dependency claims in its current
+  Plan-bound audit;
+- at completion, current checks and existing strict Step Review policy verify the implementation;
+- if no permitted authority can decide the semantic claim, the result is `stop-escalate`, never a
+  Core-invented pass.
+
+The exact Plan Risk Audit schema must be extended only as needed to carry the unique referenced
+proof obligations. A second semantic-audit sidecar or mandatory Review for every low-risk Step is
+not permitted.
+
+### 4.3 Current-state routing
+
+P02 does not add `reslice-plan` or `brief-decomposition-defect` to the current decision union.
+
+```text
+invalid candidate before authorization
+-> reject Plan/authorization
+-> existing task plan-set route with a replacement Plan
+
+invalid slicing discovered after execution starts, same Task boundary
+-> existing replan-required
+-> current corrective-replan route
+
+repair requires Task boundary change
+-> existing split-required only when current corrective authority proves it
+-> P04-A blocks materialization until P05/P04-B owns replacement topology
+
+semantic authority cannot decide
+-> existing stop-escalate
+```
+
+These routes do not consume an ordinary implementation retry merely because a new Plan is required.
+Exact attempt-accounting changes, if any are needed, belong to the current corrective authority or
+deferred P01-B; P02 must not create a parallel counter.
+
+### 4.4 Plan integrity predicate
+
+P02 adds a semantic predicate at the existing Plan validation/authorization boundary:
+
+```text
+STEP_VALID =
+  expected_outputs_describe_valid_state
+  AND every_output_has_verification
+  AND verification_available_at_step_boundary
+  AND no_future_step_required_for_correctness
+  AND dependencies_have_causal_justification
+```
+
+This predicate may require semantic Planner/Reviewer evidence for guarded Plans. Core must not claim
+that arbitrary natural-language usefulness is mechanically decidable.
+
+Core can decide the structural terms mechanically. The semantic terms require the authority in
+section 4.2. The predicate is not implementation-ready until replay shows that this authority can
+apply it consistently without turning every low-risk Plan into a review stage.
+
+### 4.5 Legacy Plan policy
+
+Historical Plan/Task state may lack `verificationMap`.
+
+- terminal historical Tasks remain readable with the map represented as legacy/unknown;
+- a Plan already execution-authorized before P02 installation may complete under the recorded
+  legacy authority, with diagnostics stating that P02 semantic mapping was not enforced;
+- every new Plan, replacement Plan, or corrective replan written after P02 installation requires a
+  complete map;
+- absence is never inferred from text, silently persisted as an empty map, or accepted on a new
+  authorization;
+- a legacy Plan that returns to planning/replan posture must adopt the new contract before it can be
+  authorized again;
+- legacy decoding preserves the historical Plan hash; migration does not rewrite old authority in
+  place.
+
+This bounded grandfathering avoids stranding an already authorized `ready` or in-progress Task,
+which current normal `task plan-set` routing cannot necessarily rewrite. It is a compatibility
+exception, not evidence that the historical Step was semantically valid.
+
+## 5. Validation
+
+### 5.1 Contract and semantic tests
+
+- empty `expectedOutputs[]` remains invalid;
+- empty `checks[]` remains invalid;
+- every expected output must map to verification;
+- missing/self/cyclic dependencies remain invalid;
+- a dependency without a causal postcondition relationship is rejected by semantic validation;
+- a future Step required for current correctness rejects the candidate Plan before authorization or
+  produces existing `replan-required` after execution starts;
+- one atomic Step remains valid;
+- unsupported semantic classification returns `stop-escalate`, not an invented result.
+- terminal and already-authorized legacy Plans remain readable under the explicit compatibility
+  policy;
+- a new or replanned Task cannot omit `verificationMap`.
+
+### 5.2 Synthetic E2E
+
+1. Activity slices `schema -> storage -> runtime -> integration` are rejected when early Steps have
+   no safe independently verified outcome.
+2. A backward-compatible schema Step with a real migration check is accepted when it leaves a valid
+   deployable state.
+3. Compatible-root reuse is accepted only when the Step output explicitly requires short-circuiting
+   extraction and persistence.
+4. Retry-to-success persistence is accepted only when the Step output distinguishes inbox identity,
+   attempt evidence, and terminal completion.
+5. Two independent Steps with empty dependencies remain semantically independent even if the
+   scheduler runs them sequentially.
+6. A real dependency blocks execution until the predecessor is canonical.
+7. A valid Step with defective code follows the current `continue-fix` implementation remediation.
+
+### 5.3 Historical replay
+
+Before enforcement, replay:
+
+- successful single-Step Tasks;
+- successful multi-Step Tasks;
+- guarded Tasks;
+- ordinary implementation remediation;
+- Tasks where integration defects appeared only after later Steps.
+
+For each historical Step record:
+
+```text
+expected output reconstructable?
+verification available at boundary?
+future Step required for correctness?
+real causal dependencies
+proposed verdict
+false positive / false negative
+```
+
+Historical absence of explicit semantic wording is not itself proof of a bad Step. Replay must
+reconstruct the actual behavior and evidence.
+
+The brief remains a hypothesis until replay demonstrates that invalid activity slicing is detected
+without systematically rejecting useful historical Steps.
+
+## 6. Dependencies and conflicts
+
+- P01-A owns mechanical feasibility only. Deferred P01-B or current corrective authority must own
+  any Task/decomposition routing and attempt-accounting change.
+- P02 owns only Step semantic integrity and reslicing.
+- P03 may project current Step/dependency facts but does not evaluate Step validity.
+- P04 owns Task-level dependencies; Step dependencies do not create Task edges.
+- P05/P04-B is required to continue when semantic reslicing proves that the Task boundary itself
+  must split; P04-A intentionally blocks that replacement.
+- Mandatory strict Review for all Steps is explicitly rejected because it would conflict with P01's
+  low-risk happy path and current risk-based review policy.
+
+## 7. Design approval gate
+
+P02 remains `NO-GO`. It may move from `hypothesis` to `approved` only when:
+
+1. One exact `verificationMap` representation is accepted and its Plan/audit hashing is specified.
+2. Low-risk semantic authority is the existing execution authorization, without a new mandatory
+   reviewer.
+3. Guarded semantic authority reuses the current Plan Risk Audit and its unique proof references.
+4. Pre-authorization rejection, `replan-required`, `split-required`, and `stop-escalate` cover the
+   complete routing table without new decision values.
+5. Fresh and historical role-separated replay demonstrates actual invalid activity slicing and no
+   systematic rejection of useful Steps.
+6. P04-A and P01-A boundaries are stable enough that P02 does not duplicate Task dependency or
+   mechanical-feasibility authority.
+7. The bounded legacy policy is accepted and does not rewrite historical Plan hashes.
+
+## 8. Implementation acceptance
+
+P02 may move from `approved` to `implemented` only when:
+
+1. Existing `expectedOutputs[]`, `checks[]`, and `dependencies[]` are reused.
+2. Every expected output has boundary-time verification.
+3. Activity-only Steps are rejected or resliced.
+4. A future Step cannot be required to make a completed Step correct.
+5. Ordinal has no dependency semantics.
+6. Declared dependencies remain executable and cycle-safe.
+7. Low-risk Steps gain no mandatory strict Review.
+8. Guarded Steps continue to use current strict Step Review.
+9. Plan reslicing does not consume an ordinary implementation-fix attempt unless current corrective
+   policy independently requires it.
+10. Historical replay shows no systematic false blockers.
+11. No new Step authority, credential, registry, lifecycle stage, branch model, or parallel
+    scheduler is introduced.
+12. New/replanned Tasks require `verificationMap`, while grandfathered authorized Tasks remain
+    readable and diagnosable without fabricated mappings.
+
+## 9. Non-goals
+
+- new Step fields duplicating the current contract;
+- mechanical proof of arbitrary natural-language usefulness;
+- Candidate Task admission;
+- Task-level dependencies;
+- replacement rewiring;
+- mandatory Review of every low-risk Step;
+- separate worktree or branch per Step;
+- parallel execution.
+
+## 10. Decision log
+
+- 2026-08-23 — Revision 1 created as `hypothesis`.
+- 2026-08-23 — Revision 2 constrained the proposal to minimal Step semantic integrity.
+- 2026-08-24 — Existing `expectedOutputs[]`, `checks[]`, and `dependencies[]` recognized as the
+  canonical storage model; duplicate proposed fields removed.
+- 2026-08-24 — Strict Review limited to current guarded-risk policy instead of every Step.
+- 2026-08-24 — Signal replay evidence recorded as supporting semantic examples, not a completed
+  Workflow Step replay.
+- 2026-08-24 — Revision 4 added the minimal output-to-evidence relation, assigned low-risk and
+  guarded semantic authority, and replaced invented `reslice-plan`/`brief-decomposition-defect`
+  outcomes with current transition routes.
+- 2026-08-24 — Legacy Plans are grandfathered only when already authorized; every new or replanned
+  Plan must use the relation without rewriting historical hashes.
+- 2026-08-24 — P02 remains `NO-GO` until fresh/historical replay validates the causal Step
+  hypothesis and the proposed semantic authority.
+- 2026-08-24 — Status intentionally remains `hypothesis`.