refactor(workflow): make execution plans authoritative

README.md

@@ -4,7 +4,7 @@ CodeOps is a specification-first engineering system for building complex softwar
 
 It is designed for work where an unstated assumption can become a correctness defect: programming languages and compilers, financial systems, protocols, distributed services, security-sensitive applications, developer tools, and substantial web applications.
 
-> **Release status:** `0.4.0` is the stable release of the current CodeOps workflow surface. Core workflows, deterministic state, project tracking, domain lenses, Codex-native routing, opt-in delegated technical design, strict scope control with user-owned exploration, and a non-negotiable source-documentation gate are present. A retained Claude 3.12.0 requirements-stage ambiguity benchmark passes; it is not a claim of complete product parity. A real complex-project milestone remains the 1.0 release gate.
+> **Release status:** `0.4.0` is the stable release of the current CodeOps workflow surface. Core workflows, Markdown-authoritative progress, project tracking, domain lenses, Codex-native routing, opt-in delegated technical design, strict scope control with user-owned exploration, and a non-negotiable source-documentation gate are present. A retained Claude 3.12.0 requirements-stage ambiguity benchmark passes; it is not a claim of complete product parity. A real complex-project milestone remains the 1.0 release gate.
 
 ## The workflow
 
@@ -16,7 +16,7 @@ Intent or existing system
   → specification ambiguity closure
   → execution plan
   → plan ambiguity closure
-  → readiness proof
+  → direct artifact readiness checks
   → specification tests
   → implementation
   → verification and independent review
@@ -40,11 +40,10 @@ The port begins from the proven CodeOps workflow set:
 - safe artifact upgrades and migration; and
 - CodeOps project setup.
 
-Codex-native traceability, readiness proofs, recovery, agent routing, and outcome evaluation are governed by the [port program](plans/codex-port/00-index.md).
-
-Readiness commands are target-scoped: skills resolve the exact graph node and matching lifecycle
-gate, while dependency closure supplies diagnostics without implicitly advancing sibling work.
-Schema-1 graphs remain compatible and can be atomically upgraded to schema 2.
+Requirements own agreed behavior; plan metadata declares RD mapping; and each
+`99-execution-plan.md` owns its task progress. Roadmaps and status summaries are derived. The
+minimal lifecycle and the rest of the Codex-native workflow are governed by the
+[port program](plans/codex-port/00-index.md).
 
 The retained [evaluation evidence](docs/evaluation.md) currently passes compiler, financial, and multi-tenant web ambiguity benchmarks against Claude CodeOps 3.12.0.
 For a first project, follow the [complex-project quick start](docs/tutorial.md).

_shared/layout-convention.md

@@ -85,9 +85,10 @@ they intentionally share the full-set or full-plan scope baseline.
 - **RD ids reset per feature.** Within `codeops/features/billing/requirements/` the ids run
   `RD-01, RD-02, …` independently of every other feature. (In flat layout there is one global
   RD sequence, as before.)
-- **Cross-feature references are feature-qualified.** A plan's `00-index.md` declares
-  `> **Implements**: billing/RD-01` (feature-qualified) in nested layout, or `> **Implements**:
-  RD-01` in flat layout. The roadmap matcher reads this line.
+- **Cross-feature references are feature-qualified.** A plan's `00-index.md` declares one or more
+  requirements on a single line, for example `> **Implements**: billing/RD-01, billing/RD-02` in
+  nested layout or `> **Implements**: RD-01, RD-02` in flat layout. The roadmap matcher and plan
+  status parser read this line.
 - **Tasks use a separate per-feature sequence** `T-01, T-02, …`, so a task id never collides
   with an RD id in the same feature. See the task-lane spec for the lightweight task model.
 

_shared/scope-expansion-control.md

@@ -88,11 +88,11 @@ valid appended event determines current state. Never edit, delete, or reorder an
 
 Accepted proposals also maintain dependency-oriented authority links:
 
-| SE ID | Derived artifact or graph target | Relation or kind | Current state | Evidence source |
+| SE ID | Derived artifact | Relation or kind | Current state | Evidence source |
 |---|---|---|---|---|
-| `SE-001` | Requirement, specification, test, task, implementation evidence, verification, or roadmap item | `authorizes` or `invalidates` | Current, stale, or superseded | Durable artifact or traceability evidence |
+| `SE-001` | Requirement, specification, test, task, implementation evidence, verification, or roadmap item | `authorizes` or `invalidates` | Current, stale, or superseded | Durable artifact evidence |
 
-Implementation linkage belongs in traceability records or other artifact evidence and never in source comments.
+Implementation linkage belongs in plan or other artifact evidence and never in source comments.
 Recompute the proposal table's current state from the latest valid event; the event log
 remains authoritative history.
 

docs/concepts.md

@@ -2,28 +2,29 @@
 
 ## Recursive ambiguity closure
 
-CodeOps does not ask one round of questions and call the result a specification. Requirements, component specifications, testing strategies, and execution plans each receive their own ambiguity pass. A later discovery can reopen an earlier gate and invalidate downstream readiness.
+CodeOps does not ask one round of questions and call the result a specification. Requirements, component specifications, testing strategies, and execution plans each receive their own ambiguity pass. A later discovery can reopen an earlier gate and block affected downstream tasks.
 
 ## Material ambiguity
 
 An ambiguity is material when plausible answers can change behavior, semantics, data integrity, security, financial results, contracts, persistence, concurrency, recovery, compatibility, performance obligations, tests, architecture, operations, scope, or ordering. Material choices require explicit resolution or an approved, risk-recorded deferral.
 
 ## Durable artifacts
 
-Markdown owns human-readable requirements, decisions, specifications, tests, and plans. `traceability.json` owns stable typed relationships and state. Roadmaps are derived views. Conversations are useful context but never durable workflow state.
+Markdown owns requirements, decisions, specifications, tests, plans, and progress. Requirements
+documents own agreed behavior and acceptance criteria. A plan's `00-index.md` declares the RD or
+RDs it implements. Its `99-execution-plan.md` is the only mutable task-progress authority.
+Roadmaps and status output are derived views. Git supplies history and recovery.
 
 ## Readiness
 
-The deterministic state tool validates identifiers, paths, relationships, status, and coverage shape. Semantic review validates truth, completeness, consistency, feasibility, and risk. Both must pass.
+Readiness is checked directly from artifacts: required documents exist, material ambiguities are
+closed, specification tests precede implementation, and critical/major findings are resolved.
+Semantic review validates truth, completeness, consistency, feasibility, and risk.
 
-Readiness is target-scoped. A workflow selects one canonical node or group and one gate profile;
-the engine computes its dependency closure and shortest blocker paths. Closure is read context,
-not permission to edit or advance siblings. Feature and release nodes are explicit aggregates,
-and a release contains only declared members.
-
-Schema 2 binds semantic sources to normalized revisions and stores relationship snapshots.
-Changing upstream meaning therefore makes affected downstream claims stale. Legal lifecycle
-changes are atomic compare-and-swap transitions with recovery evidence.
+A plan has four derived states: `Ready`, `Executing`, `Done`, and `Blocked`. Tasks use `[ ]` for
+not started, `[~]` for implemented with verification pending, `[x]` for verified, and `[!]` for
+blocked with a visible reason. Resume selects the first `[~]` task, otherwise the first `[ ]`.
+Only a passing verification permits `[~]` to become `[x]`.
 
 ## Delegated technical design
 
@@ -60,7 +61,9 @@ inside scope that the user already kept, but it cannot choose `Keep` or activate
 
 ## Project tracking
 
-Tracking combines lifecycle—discovery through archive—with readiness, task progress, verification, findings, blockers, dependencies, and deferrals. A new thread can reconstruct the next safe action from repository and Git evidence.
+Tracking combines lifecycle—discovery through archive—with derived plan progress, findings,
+blockers, dependencies, and deferrals. A new thread reconstructs the next safe action from the
+execution plan and Git evidence.
 
 ## Agents
 

docs/migration.md

@@ -10,20 +10,28 @@ Run the setup skill in dry-run mode first. Review all source-relative-link warni
 
 Project instructions belong in `AGENTS.md` for Codex. Do not mechanically copy global Claude instructions or model-routing blocks. Preserve repository commands and conventions that remain true, then express routing and quality policy in `codeops/codeops.json` or `.codex/config.toml`.
 
-## Traceability adoption and schema upgrade
+## Legacy workflow-state artifacts
 
-Legacy Markdown artifacts and schema-1 graphs remain readable. Upgrade graphs with a deterministic
-preview and explicit resolutions:
+Re-run `setup-codeops` on the existing project. It automatically detects legacy graphs before its
+normal already-configured no-op. Use `--dry-run` for preview only, or `--yes` for an unattended
+apply followed by verification. The same one-shot engine can also be invoked directly:
 
 ```bash
-python3 /path/to/plugin/scripts/codeops_state.py traceability-upgrade --root . \
-  --feature my-feature --preview upgrade.json
-python3 /path/to/plugin/scripts/codeops_state.py traceability-upgrade --root . \
-  --feature my-feature --preview upgrade.json --resolutions resolutions.json --apply
-python3 /path/to/plugin/scripts/codeops_state.py validate --root .
+python3 /path/to/plugin/scripts/codeops_plan_migrate.py ./codeops
+python3 /path/to/plugin/scripts/codeops_plan_migrate.py ./codeops --apply
 ```
 
-Review the preview; resolve every classified ambiguity or explicitly omit the link. Apply is
-atomic, creates a protected backup, and reports recovery-required state instead of guessing after
-an interrupted write. Do not mark legacy work ready until every active node has valid links,
-current source revisions and snapshots, and semantic review passes.
+The migrator preserves checklist progress, adds or normalizes each plan's single
+`> **Implements**:` declaration, creates a minimal index for roadmap-linked lightweight plans,
+validates the four task markers, and deletes active and archived feature `traceability.json`
+files. It prefers existing declarations and roadmap links, then consumes the legacy graph once
+to recover plan-local requirements before deleting it. Explicit index metadata and a
+single-plan/single-RD feature are conservative fallbacks. Archived features without a graph are
+outside this bounded conversion. Any missing or ambiguous mapping blocks the entire apply without
+changing files. Apply requires a clean Git working tree.
+
+For blocked legacy work that does not already use `[!]`, first use `upgrade-plan` to record a
+visible reason. Do not migrate graph state into another state platform.
+
+After apply, run `python3 /path/to/plugin/scripts/codeops_plan.py --root . --json`, then the
+repository's normal verification. Git history is the rollback and recovery mechanism.

docs/troubleshooting.md

@@ -12,28 +12,23 @@ Start a new Codex thread after installation or update. Confirm the installed cac
 
 Open `/hooks`. Non-managed plugin hooks are skipped until their exact definitions are reviewed and trusted. A hook change invalidates its prior trust hash.
 
-## Readiness says no traceability graph exists
+## Plan status reports missing metadata
 
-Run `setup-codeops`, then create or migrate a feature and its `traceability.json`. A newly scaffolded empty portfolio is configured but cannot be implementation-ready.
+Confirm the plan contains `00-index.md`, `99-execution-plan.md`, and one
+`> **Implements**:` line with at least one RD, tracker (`T-*`), or plan-local requirement (`REQ-*`)
+target. Only RD targets contribute to the derived requirements summary. An empty portfolio is
+configured but has no plan status to report.
 
 ## A sibling blocks or advances unexpectedly
 
-Confirm the command includes both `--target` and `--gate`. The reported closure may name sibling
-or upstream context, but only the selected target may transition. Roadmap sync repairs derived
-rows; it must not mutate authoritative graph state.
+Confirm each plan declares only the RDs it implements and each task appears once in its execution
+plan. Roadmap sync repairs derived rows; it must not mutate requirements or task checkboxes.
 
-## Upgrade or transition requires recovery
+## A task is stuck after interruption
 
-Do not delete the journal, backup, or lock metadata. Create a recovery request with the recorded
-operation ID and an explicit `roll-forward` or `rollback` action, then run:
-
-```bash
-python3 /path/to/plugin/scripts/codeops_state.py transition-recover --root . \
-  --request recovery-request.json
-```
-
-Inspect the durable images before choosing the action. A second apply is safe only after recovery
-completes.
+Read `99-execution-plan.md`. Resume the first `[~]` task and re-run its verification; otherwise
+start the first `[ ]` task. For `[!]`, resolve the visible blocker before restoring the appropriate
+task marker. Use Git history to inspect or recover interrupted edits.
 
 ## Generated agents are missing or stale