codex-workflow-v2 2.0.0-alpha.7 → 2.0.0-alpha.7.2

package/docs/alpha7.1-implementation-brief.md

@@ -0,0 +1,268 @@
+# codex-workflow-v2 2.0.0-alpha.7.1 implementation brief
+
+## Status and authority
+
+This document is the single source of truth for the local `2.0.0-alpha.7.1`
+release candidate. It was authorized in the current Codex task on 2026-08-14.
+Workflow V2 must not be used to organize or authorize this development work.
+
+The candidate is based on the published tag `v2.0.0-alpha.7` at commit
+`b7ce0b5e14791e8177c104a2344dfb46f459696f` and is developed in the standalone
+repository `/Users/home-pc/htdocs/codex-workflow-v2` on the isolated branch
+`codex/workflow-v2-alpha7-1`.
+
+No tag, push, or npm publication is authorized. The `signal_v4` repository,
+its external Workflow state, and its Milestone 3 state are read-only evidence
+and must not be changed.
+
+## Problem statement
+
+Alpha.7 adds a bounded Milestone autonomy contract, but its guarded remediation
+state machine is not internally consistent after a strict Step review failure
+causes Project Knowledge refresh, Task Knowledge rebind, and delegated
+reauthorization.
+
+The production-shaped failure is:
+
+1. A guarded Step fails two strict reviews and records two ordinary remediation
+   events.
+2. The Step's commits make Project Knowledge stale.
+3. Project Knowledge is reconciled and approved, then the Task Plan is rebound
+   and reauthorized under a new Plan hash.
+4. The Task remains runnable and the failed Step remains the remediation target,
+   but `next` no longer advertises `task corrective-decision` because the gate is
+   derived only for `needs_fix`.
+5. `recordStepCorrectiveDecision` also accepts only `needs_fix` or a narrowly
+   defined `blocked` unverified-review posture, so the advertised and executable
+   transitions can diverge.
+
+This creates a lifecycle deadlock and previously encouraged signal-specific
+rescue patches. Alpha.7.1 must fix the generic transition semantics. It must not
+hard-code repository names, Task IDs, Step IDs, revisions, commits, Plan hashes,
+or package-upgrade rescue identities.
+
+The real-agent E2E exposed a second autonomy deadlock. A normal Task that adds a
+new test can cause the repository scanner to add that file as a supporting
+Knowledge source. The Milestone autonomy contract currently permits only
+content-hash-only atomic refresh, so the new source forces another human approval
+even when its exact path, category, authority, and reason were declared in the
+authorized Task Plan. Alpha.7.1 must distinguish such Plan-bounded supporting
+source additions from unplanned source-set or authority changes.
+
+## User outcomes
+
+1. A Milestone coordinator can execute a bounded Milestone autonomously without
+   asking for repeated human approvals covered by the Milestone autonomy
+   contract.
+2. A guarded Step gets at most two ordinary remediation attempts, then exactly
+   one independently audited corrective attempt when `continue-fix` is chosen.
+3. Project Knowledge refresh, Task Knowledge rebind, and delegated
+   reauthorization preserve the remediation posture rather than losing or
+   bypassing it.
+4. `next` always recommends a transition that the corresponding command can
+   execute from the same immutable state, subject only to the evidence explicitly
+   named by that recommendation.
+5. A third failed guarded remediation reaches a hard stop. Only split or stop
+   escalation is permitted; a fourth run is impossible.
+6. Discovery quality is checked, but ordinary human incompleteness and
+   non-blocking unknowns do not require the user to pre-plan agent behavior.
+7. A Task may add a supporting Knowledge source declared by its already
+   authorized Plan without creating another human gate; undeclared additions,
+   canonical-source additions, removals, authority/category changes, gaps, and
+   conflicts still fail closed.
+
+## Required state-machine semantics
+
+### R1 — generic corrective posture
+
+Derive the corrective posture from the current guarded Step, current Plan Risk
+Audit, remediation history, and corrective-decision history. Do not infer it
+solely from `Task.status`.
+
+The derivation must work when the same failed guarded Step is represented in any
+legitimate post-failure/post-refresh status produced by the Workflow, including
+`needs_fix`, post-rebind `ready`, post-authorization `ready`, and the existing
+blocked/unverified strict-review retry posture.
+
+### R2 — `next`/command consistency
+
+If a guarded Step has two failed remediation events and no decision for attempt
+3, `next` must advertise `task corrective-decision` before `task run` regardless
+of a content-only Knowledge refresh, Plan rebind, or delegated reauthorization.
+
+When `next` advertises `task corrective-decision`,
+`recordStepCorrectiveDecision` must accept the same Task/Step state with the
+recommended revision, Plan Risk Audit, actor/lease posture, and independent
+auditor evidence.
+
+### R3 — Plan rebind continuity
+
+Knowledge rebind may create a new Plan hash. Historical remediation events remain
+immutable. A corrective decision is bound to the current Plan hash and the exact
+covered remediation event IDs. Rebind must not reset attempt counts or permit a
+third ordinary attempt.
+
+### R4 — bounded recovery
+
+- Attempts 1 and 2 are ordinary.
+- Attempt 3 requires an independent corrective decision.
+- `continue-fix` enables exactly the third corrective attempt.
+- `replan-required` requires an actual new Plan posture before execution.
+- `split-required` and `stop-escalate` block execution.
+- After a third failed remediation event, `next` must expose a stable hard-stop
+  action and must not throw while merely reporting status.
+- A fourth `task run` and a fourth `continue-fix` decision are prohibited.
+
+### R5 — priority ordering
+
+Pending strict review for an already recorded completion commit outranks
+Knowledge refresh. After that review is terminal, required Project Knowledge
+refresh and Task Knowledge rebind remain mandatory. Once current knowledge and
+authorization are restored, an outstanding corrective decision outranks another
+run. C1 claim/handoff constraints remain authoritative and must not be bypassed.
+
+### R6 — Milestone autonomy
+
+The alpha.7 Milestone autonomy contract remains bounded by its immutable semantic
+scope, delegate, expiry, policy hash, and allowed transitions. It may cover
+Milestone execution/final acceptance, Task execution/final acceptance, and
+content-only Project Knowledge approval. Semantic scope changes still require
+new human authority. Alpha.7.1 must not broaden these permissions.
+
+### R7 — Plan-bounded supporting-source refresh
+
+The user explicitly authorized this bounded delegated-approval expansion in the
+current Codex task after the real-agent E2E exposed the supporting-source
+deadlock. The authorization is limited to the complete fail-closed predicate
+below.
+
+The atomic delegated `task context-refresh` transition may accept a newly
+discovered Knowledge source only when all of the following are true:
+
+- the active Task belongs to the Milestone named by the autonomy grant;
+- the current authorized Task Plan declares `knowledgeImpact: create` and an
+  exact `knowledgeTargets` entry for the new path and category;
+- the scanner classifies that exact path and category as `supporting`;
+- no previously approved source is removed;
+- no existing source changes category or authority;
+- no unplanned source is added;
+- gaps and conflicts are unchanged and no new conflict exists.
+
+The transition remains atomic: reconcile, approve the exact safe candidate,
+rebind Task Knowledge, and supersede execution authorization together. It must
+not permit standalone Project Memory approval, canonical-source creation,
+wildcard/directory targets, or mutation beyond the Task's current Plan and the
+existing Milestone autonomy policy. `next` must expose this delegated refresh
+only when the complete predicate is satisfied and otherwise report the concrete
+unsafe differences.
+
+## Required tests
+
+### Deterministic replay (release-blocking)
+
+Add a production-shaped regression using opaque, non-hard-coded Step IDs. It must
+replay the complete sequence:
+
+1. Milestone autonomy and delegated Task authorization.
+2. Guarded Step completion and strict-review failure 1.
+3. Ordinary remediation, completion, and strict-review failure 2.
+4. Project Knowledge staleness, content-only reconcile/approval, Task Knowledge
+   rebind, refreshed Plan Risk Audit, and delegated reauthorization.
+5. `next -> task corrective-decision` and successful recording by an auditor
+   distinct from the latest strict reviewer.
+6. Corrective attempt 3 and successful strict review, followed by Task completion.
+7. A sibling replay where attempt 3 fails and proves stable hard-stop reporting,
+   rejection of a fourth run, and rejection of `continue-fix` for attempt 4.
+
+The replay must assert state, sidecar bindings, attempt ordinals, Plan hashes,
+returned actions, and absence of repository-specific rescue logic.
+
+Add a sibling deterministic replay for R7. It must prove that one exact
+Plan-declared supporting test source can be accepted through atomic delegated
+context refresh, while an undeclared source, a canonical addition, a removal,
+and an authority/category change remain ineligible and cannot mutate state.
+
+### Existing suites (release-blocking)
+
+`npm run validate`, `npm run release:check`, `npm run pack:check`,
+`npm run smoke:downstream`, and `npm run plugin:check` must pass sequentially
+under the repository's supported Node version. Parallel build/clean scripts are
+not valid evidence because they race on shared output directories.
+
+### Real-agent isolated E2E (release-blocking)
+
+Create `test-runs/2.0.0-alpha.7.1/project` as a disposable repository inside the
+standalone project. Use the sibling `codex-home`, `workflow-state`, `plugin-root`,
+`npm-cache`, and `evidence` directories for complete isolation. Install the
+candidate from a local `npm pack` tarball, not the public registry. The globally
+installed Codex Workflow plugin remains disabled; the real agent loads only the
+candidate gateway from the isolated plugin root.
+
+Run a real Delegate agent through:
+
+`initial Discovery -> Milestone -> bounded Milestone autonomy -> Tasks -> strict
+review/remediation and Knowledge refresh -> merge/handback -> Milestone validate
+-> delegated final accept`.
+
+The Milestone must be small enough to finish but contain at least three Tasks:
+
+1. A bounded safe-contract implementation Task that adds a Plan-declared
+   supporting test source and exercises the R7 atomic refresh path.
+2. A guarded persistence/documentation Task that causes content drift and two
+   deterministic strict-review failures before a bounded corrective success,
+   exercising reconcile, rebind, and reauthorization.
+3. A composition/acceptance Task that closes the Milestone.
+
+The initial Discovery prompt should imitate a real product-owner request: desired
+outcome, examples and constraints are present, while implementation details,
+exact Step decomposition, retry mechanics, and some non-blocking design choices
+are deliberately omitted. The agent must discover and resolve what it can,
+record non-blocking unknowns honestly, and proceed without asking the user to
+predict its implementation behavior. The signal_v4 M3 Discovery may be used as
+read-only style evidence, but its domain and identifiers must not be copied into
+the candidate logic.
+
+E2E acceptance requires the Milestone to reach final acceptance, all Tasks to be
+terminal, repository state clean, no active or stale writer leases, no action
+requiring human approval inside the granted semantic scope, and an evidence log
+that identifies every command/action and final entity status without secrets.
+The run must include at least one new supporting test source admitted through the
+R7 atomic delegated context-refresh path; manually approving that source is not
+acceptable passing evidence.
+
+## Ownership and integration
+
+- Main coordinator: owns this Brief, integration, local tarball, isolated E2E,
+  final evidence, and all decisions that cross file ownership.
+- State-machine implementer: owns production changes in `src/` and directly
+  related contracts/reference documentation. Must not edit E2E evidence.
+- E2E/test owner: owns deterministic regression tests, fixtures, and isolated E2E
+  harness documentation/scripts. Must not change production semantics without a
+  written finding to the coordinator.
+- Independent auditor: starts only after implementation and E2E evidence are
+  complete; reviews Brief-to-diff traceability, test validity, release artifacts,
+  and residual risks without editing implementation files.
+
+All contributors share the worktree, must preserve concurrent edits, and must not
+revert changes they did not create.
+
+## Stop-loss and release gate
+
+All local iterations retain version `2.0.0-alpha.7.1`; individual failures do not
+create alpha.7.2/alpha.7.3 versions. No publication occurs until deterministic
+replay, the real-agent Milestone, and independent audit all pass.
+
+If real-agent execution cannot be completed because Codex cannot be launched with
+the required isolation or cannot exercise a deterministic failure seam, that is
+a release blocker, not permission to substitute a mocked test.
+
+## Deliverables
+
+1. This Brief.
+2. Generic source diff and reference documentation.
+3. Deterministic replay and all package validation evidence.
+4. Local alpha.7.1 tarball identity and downstream installation evidence.
+5. Real-agent E2E evidence through Milestone final acceptance.
+6. Independent audit with every finding resolved or explicitly accepted by the
+   user.
+7. Remaining risks and a release recommendation. No tag, push, or publish.