revise

name	revise
description	Route a requested track change according to lifecycle state, revise an approved active baseline with resumable journaling, or propose a successor for completed or archived work. Use for the revise command or user-requested scope/plan changes.

Cadre Revise

Read .cadre/workflow.md, the full target track, its dependencies, all tracks that depend on it, relevant repository files, and applicable patterns. Read each artifact before editing; never propose a revision from guessed contents.

At every required clarification or approval boundary, show a concise impact summary or focused diff. Inspect the active host policy before calling workflow_elicit: if the task context reports approval policy never, including Codex Full Access, skip the form and ask the same short question once in chat. Otherwise prefer workflow_elicit, using clarification for at most three questions and approval bound to the exact revision proposal checkpoint. Treat only an approved result as approval. If it returns fallback_required, or immediately returns declined while the task explicitly reports policy never, ask the same short question once in chat; the latter is policy rejection, not a human decline. Never request secrets or retry the form.

Call project_status first and use its embedded structured validation; do not repeat state_validate at command entry. If the Cadre MCP is unavailable, stop without modifying the track.

Route by current status

• drafting-spec: follow the track specification procedure and resume its journal. The content is not yet an approved baseline, so do not create a revision artifact or increment a revision.
• drafting-plan: if the approved specification changes, perform the semantic revision procedure below and remain drafting-plan; if only the unapproved plan changes, resume the track planning procedure without a revision artifact.
• planned: perform the semantic revision and remain planned.
• in_progress: perform the semantic revision at a safe task boundary. Remain in_progress when all approved dependencies are complete; move to planned if an approved dependency is incomplete.
• ready_for_review: distinguish a defect against the approved specification from a changed desired outcome. Route a defect through review. For a scope, requirement, or acceptance change, perform the semantic revision, invalidate review readiness, append delivery and manual-verification work, and move to in_progress, or planned if an approved dependency is incomplete.
• completed or archived: do not mutate or reopen the track. Present a successor feature or bug track proposal that references the immutable source track and follow track only after approval.

Semantic revision procedure

Expected human decision count is one when the requested change and partial-work disposition can be presented together. A separate preliminary decision is justified only when active work cannot be made safe or fully assessed without first choosing whether to complete, preserve, or revert it.

1. Reconcile state.json.operation, any execution journal, managed worktrees, workers, the working tree, and recent commits before drafting. Resume a matching revise operation from its first incomplete artifact. Observe a safe quiescent boundary before changing an active execution graph; do not stop workers, integrate work, or clean worktrees before the authorization envelope permits the exact disposition. Finish or reconcile any other recorded operation first; never replace it.
2. Restate the requested change and identify specification, acceptance, plan, learning seed/phase history, review readiness, and state consequences. Inspect active and dirty task work. When it overlaps the requested change, include its exact disposition—complete, preserve as superseded, or additive revert—in the combined revision proposal rather than creating a separate approval when that disposition can be safely assessed in advance.
3. Apply the workflow clarification gate. Ask when materially different interpretations remain for the desired outcome, scope, acceptance criteria, compatibility, dependency changes, treatment of completed or partial work, or whether dependent tracks should change now. Do not infer permission to invalidate approved work.
4. Trace transitive dependent tracks. For each, classify impact as none, reseed-only, plan change, spec change, or invalidated work, with evidence. If evidence cannot resolve a material impact, ask before choosing a classification.
5. Call template_get_many once for track/revision and track/revise-operation, and retain the versioned bundle. Render revisions/revision-<ts>.md and draft exact diffs for every affected artifact. Record source and target status, the base commit, affected phases/tasks, completed and partial-work disposition, review impact, dependency impact, and verification work. Preserve completed tasks and commit markers; append or explicitly supersede work rather than erasing provenance.
6. Increment the track revision exactly once. Increment the specification revision only if spec.md changes and the plan revision only if plan.md changes; keep the revision values in state.json, spec.md, plan.md, and the marked Pattern Seed consistent. Preserve completed task provenance, update explicit regular phase/task dependencies, and restore derived manual-verification barriers. When the plan changes, call execution_graph_validate_draft with the complete proposed plan Markdown and the intended post-approval target status; do not validate the stale canonical plan or create a temporary project copy. A changed plan graph uses a new execution ID; never reuse a completed or superseded execution journal.
7. Present the target revision, partial-work disposition, quiescence actions, all cascading dependent-track changes, validation evidence, lifecycle transitions, expected commits, generated index updates, and provenance bookkeeping together. Wait for one explicit approval. Partial approval narrows the change set and requires a fresh impact assessment, transition calculation, and proposal.