cycle

Worktree preflight — in a linked git worktree the synced tooling tree scripts/.claude-skills/ is absent — it is gitignored, so git worktree add does not populate it, and every command below that uses it dies on a bare MODULE_NOT_FOUND. Run npm run skills:hydrate first. If this repo defines no such script, references/worktree-preflight.md holds the entry to add — ask the user first, since it edits their package.json.

Usage

Usage: /cycle <task-description>          — Full chain from scratch
Usage: /cycle plan <plan-file>            — Skip /plan only; still audits the plan, then the implementation gate
Usage: /cycle code <plan-file>            — Skip to code-audit-then-ship (plan accepted, code written)
Usage: /cycle remediate <plan-file> --from persona-test <report.md> [--persona-url <url>]  — Fix triaged P0/P1s against an accepted plan; focused audit; rerun affected journeys only
Usage: /cycle remediate <plan-file> --from audit <result.json>   — Same, sourcing HIGH findings from an audit result
Usage: /cycle <plan-file> --no-persona    — Skip persona-test step
Usage: /cycle <plan-file> --persona-url <url> — Explicit persona-test target (local dev server, no PERSONA_TEST_APP_URL needed)
Usage: /cycle <plan-file> --no-uxlock     — Skip ux-lock step (no UI changes)
Usage: /cycle <plan-file> --no-ship       — Stop after audit; don't commit or push
Usage: /cycle <plan-file> --max-rounds N  — Pass through to /audit-plan and /audit-code
Usage: /cycle --autonomous <plan-file>    — Opt-in: autonomously implement + audit each §11 cluster (default still pauses for the human; Step 7/ship is NEVER autonomous — see Step 7)
Usage: /cycle code <plan-file> --cluster <ID> [--baseline-ref <sha>]  — Resume one declared cluster (human clustered path)
Usage: /cycle --autonomous <plan-file> --authorize-stale-reaudit      — Resume a halted autonomous run; re-process stale clusters

Feature Cycle Orchestrator

This skill's last line is an end marker naming the skill between em-dashes, after the Reference files table. If that last line is not in your context (context compaction keeps only the start of a skill), re-read .claude/skills/cycle/SKILL.md in full before continuing — the later steps still apply.

Chains the existing atomic skills into one workflow so you don't have to remember which to invoke when. Each step is a delegation to the underlying skill — this orchestrator just sequences + waits.

This skill does NOT duplicate logic from the atomic skills. If you want fine control over a single step, invoke that step's skill directly (/audit-code, /audit-plan, etc.). Use /cycle when you want the golden-path workflow without thinking about it.

<!-- host-contract: no-dispatch; preserves=step-order,step3-pause,skip-flags,blocked-propagation -->

On a host with no skill-to-skill dispatch, delegate INLINE. Claude Code can invoke /audit-code as a command; VS Code Copilot reads the same .claude/skills/ tree but has no documented mechanism for one skill to invoke another. Where a step below says "invoke /x", such a host instead opens .claude/skills/x/SKILL.md and follows it in place, then returns here and continues with the next step.

Pass the delegated skill its arguments explicitly — the plan path, the sub-command, the flags. /cycle already holds those values, so this is orchestrator-supplied input (rule 0 of references/input-acquisition.md), not inference — omitting them deadlocks an inline cycle (→ references/orchestration-rationale.md §No-dispatch — read when the reason is questioned).

Four invariants survive the fallback, and a run that breaks one is not a /cycle run:

1. Step order — the sequence below is unchanged; inlining is a change of mechanism, never of order.
2. The Step 3 pause — a default (non---autonomous) cycle still stops at the implementation gate. Inlining must not silently turn a paused cycle into an autonomous one.
3. Skip flags — --no-persona, --no-uxlock, --no-ship are honoured identically.
4. Blocked propagation — a [BLOCKED], AUDIT_NOT_RUN or non-converged result from an inlined skill reaches the Step 8 summary. It must not be swallowed by the skill that ran inline.

What inlining is NOT: it is not a subagent and gets no fresh context, so a long inlined skill consumes the parent conversation's budget. Say which steps ran inline in the Step 8 summary, so a reader can tell a dispatched run from an inlined one rather than assuming.

---

Step 0 — Parse Input

A prerequisite that does not resolve is a stop, not a mid-flow death. /cycle spends real money on /plan before it ever reaches an audit step, so resolve the audit prerequisites HERE — the helper scripts, and a GPT route (OPENAI_API_KEY or an active Azure profile). If one is absent, the ladder in references/prerequisite-ladder.md (the one /audit-code follows) decides what happens: hydrate and retry, run the labelled adversarial-agent substitute, or report AUDIT_NOT_RUN and stop. Whichever rung applies, say so before generating the plan rather than after paying for it, and carry the same AUDIT_DEGRADED / AUDIT_NOT_RUN label into Step 6's handoff to /ship so a degraded run cannot reach a commit looking clean.

Input shape	Mode
/cycle <task description> (no file path)	FULL — generate plan, audit it, wait for impl, audit code, ship
/cycle plan <plan-file>	SKIP_PLAN — plan exists; skip Step 1 only. Audit it (Step 2), then the Step 3 implementation gate (pause, or implement under --autonomous), audit code, ship
/cycle code <plan-file>	SKIP_TO_CODE — plan accepted + impl exist; skip Steps 1–3; audit code, validate UX, ship
/cycle remediate <plan-file> --from <persona-test|audit> <report>	REMEDIATE — plan accepted; skip Steps 1–2; triage the report, focused fixes, focused audit, rerun affected journeys, ship — see Step R
/cycle <plan-file> (no plan/code keyword)	AUTO — detect by checking if any new code exists since plan was written

/audit-plan is never skipped by inference. Only the explicit code or remediate keyword skips it — typing it is the operator's declaration that the plan is accepted. /cycle does not auto-detect "already accepted and unchanged" (no record identifies the approved plan content) → references/remediate-mode.md §"The accepted-plan skip" — read when asked to skip /audit-plan by inference.

Optional flags:

• --no-persona — skip /persona-test (use when no live URL or backend-only)
• --persona-url <url> — explicit persona-test target. Use this for a repo that only sets PERSONA_TEST_APP_URL for CI/PR-preview but runs a normal local dev server otherwise (Step 5 would silently skip without it — see Step 5).
• --no-uxlock — skip /ux-lock (use when no UI changes shipped)
• --no-ship — stop after audit; don't commit or push
• --max-rounds N — pass through to /audit-plan and /audit-code
• --autonomous (alias --implement) — opt-in: autonomously implement + audit each §11 cluster, or the whole plan as one unit when it has no §11 block (Step 3 table). It does not complete Step 7 — a fully autonomous run still stops at the Step 7 blocked-handoff card; only the human's /ship completes it.
• --cluster <ID> — implement/audit a single declared cluster (human resume path).
• --baseline-ref <sha> — audit baseline for a resume where no clusterStartRef was captured (work already committed).
• --authorize-stale-reaudit — resume a halted autonomous run by re-processing exactly the stale clusters.
• --no-cluster — ignore any §11 block; fall back to the single-audit path.
• --from persona-test <report.md> | --from audit <result.json> — REMEDIATE only, required: the findings source. --include-p2 widens the persona triage to P2.

§11 detection: parse the target plan for an ## 11. Execution Clustering block. If present (and not --no-cluster), set hasClustering and parse the clusters + each cluster's derived file scope. This activates the clustered-execution path (Step 0.7 preflight + Step 3 branch). Absent → the classic linear flow below, unchanged.

Show kickoff card:

═══════════════════════════════════════
  /cycle — [MODE]
  Steps: plan → audit-plan → audit-code → persona-test → ux-lock → ship
  Skipped: --no-persona, --no-uxlock
═══════════════════════════════════════

(REMEDIATE's card reads Steps: triage → fix → focused audit-code → rerun journeys → ux-lock → ship and Skipped: plan, audit-plan (plan declared accepted by the remediate keyword).)

---

Step 0.5 — Cross-plan coordination check (nudge, not a gate)

Whenever a target plan file already exists (SKIP_PLAN/SKIP_TO_CODE/REMEDIATE/AUTO modes — anything but a fresh FULL run, where the plan doesn't exist yet), run it before implementation or shipping proceeds:

node scripts/check-plan-status.mjs --check-deps "$PLAN"

This reads the plan's own - **Depends on**: <path> lines (plan/SKILL.md Phase 7) — the structured form of a "wait for Cluster X to land first" coordination note — against each referenced plan's current Status: line. Exit is always 0 and the output goes to stderr only, so it never blocks the run; a printed unmet line means a declared ordering dependency has not landed yet. Read it and decide by hand whether to proceed, hold, or sequence with whoever owns the other plan — this only makes the note visible, it cannot know whether proceeding anyway is actually safe. → references/orchestration-rationale.md §Step 0.5 — read when the check's purpose is questioned.

---

Step 0.7 — Clustering preflight (when hasClustering; fail-closed)

Validate the §11 block before any execution — /cycle code <plan> reaches here without having passed /audit-plan, so this is the execution-time safety net (the second of two validation layers). Check:

• partition — every §7b implementation phase in exactly one cluster; none omitted/duplicated; close-out outside the phase set;
• contiguous ascending cluster ranges (grammar rule 1);
• every fix-gate value in {yes, final, none}; Coupling: present on each cluster;
• trailing Final gate line present;
• derived scope (member Files: + tagged Additional files:) is non-empty and fully intent-tagged, validated per cluster against that cluster's gateStatus in the state record, NOT the global /cycle mode: a pending/absent cluster uses pre-implementation expectations ((modify)/(delete) resolve on disk; (create) has a resolvable parent dir, no collision, no sensitive-path); an audited/gate-clear/stale cluster uses post-implementation expectations ((create)/(delete) already done — no false collision on resume).

On any failure: stop, present the defect, offer (1) correct the plan or (2) --no-cluster fallback to the single-audit path. Never silently proceed with a malformed block.

---

Step 1 — Plan (FULL mode only)

Invoke /plan <task description>. The unified /plan skill auto-detects scope (backend / frontend / full-stack) and produces one consolidated plan document at docs/plans/<descriptive-name>.md.

On failure: surface the error and abort. Don't proceed to audit.

---

Step 2 — Audit Plan

Invoke /audit-plan <plan-file>. Iteratively refines the plan with GPT + Gemini final gate. Max 3 rounds; rigor-pressure stop.

On verdict:

• APPROVE (Gemini) → proceed to Step 3
• CONCERNS after Gemini round 2 (cap) → present to user, ask: "Plan has remaining concerns from final review. Proceed to implementation anyway, fix the plan first, or stop?"
• REJECT → present to user, recommend stopping the cycle to revise

---

Step 3 — Implementation gate (branches on mode)

Decision table (one source of truth — the bullets below elaborate). The gate is a pure function of three inputs: the parsed mode, whether the plan carries a §11 block (hasClustering), and the --autonomous flag. Only SKIP_TO_CODE means the human already implemented, so only it bypasses the gate (straight to Step 4 audit). SKIP_PLAN skips Step 1 alone — its plan has been audited in Step 2 but not implemented, so it meets this gate exactly like FULL. REMEDIATE never reaches this step; its own remediation gate is Step R.

Mode	hasClustering	--autonomous	Action
FULL / SKIP_PLAN (plan generated/audited, not yet implemented)	no	no	Pause for the human (card below)
FULL / SKIP_PLAN	no	yes	Degenerate single-cluster autonomous (whole plan as one unit)
FULL / SKIP_PLAN	yes	no	Pause + print cluster guidance; resume --cluster <ID>
FULL / SKIP_PLAN	yes	yes	Step 3C clustered autonomous loop
SKIP_TO_CODE (already implemented)	any	any	Empty-diff guard first (below); then no gate — go to Step 4 audit (per-cluster if --cluster, else union diff)

• No §11 block + default (no --autonomous) → /cycle pauses here for the human to implement; output the "paused at implementation gate" card below.
• No §11 block + --autonomous → degenerate single-cluster autonomous path (do NOT silently fall back to the pause — that contradicts the explicit --autonomous). A plan below the §7b Gate-1 / §11 threshold is small + cohesive by construction, so treat its entire implementation as ONE implicit cluster and run the Step 3C loop over it: implement → /audit-code over the union diff → fix-gate to convergence → the mandatory consolidated Gemini gate (Step 3C.2) → close-out → ship. Print one line up front so it's never silent: plan below the §11 threshold — implementing inline as a single unit (no clustering). The same within-cluster auto-fix authorization applies; a fix needing files outside the plan's declared §7/§7b scope still stops for confirmation.
• §11 block + default (no --autonomous) → still pauses, but prints the cluster plan as implementation guidance and instructs the operator to implement only the next cluster, then resume with /cycle code <plan> --cluster <ID> (the --cluster arg is required on every human resume — /cycle does not auto-divine the next cluster). On resume, Step 4 runs the per-cluster audit (see Step 3C). If the operator implemented several clusters at once (per-cluster isolation impossible), /cycle says so and falls back to a single union-diff audit.
• §11 block + --autonomous → enter Step 3C (the implement-and-audit cluster loop). This is the explicit authorization that relaxes the "never auto-fix" hard rule, scoped to within-cluster fixes.
• SKIP_TO_CODE empty-implementation guard (do this BEFORE auditing). code assumes the human already implemented — but an approved-but-unimplemented plan (e.g. resumed straight after /audit-plan, zero commits since) yields an empty implementation diff, and auditing nothing returns a misleading green. So before Step 4, compute the diff base (the plan's commit, or --baseline-ref, else the dirty-aware base /audit-code uses) and check it's non-empty. POSIX shell only (Git Bash on Windows), not PowerShell:

  BASE=$([ -n "$(git status --porcelain)" ] && echo HEAD || echo HEAD~1)   # or the plan commit / --baseline-ref
  [ -z "$(git diff "$BASE" --name-only)$(git ls-files --others --exclude-standard)" ] && echo EMPTY
  

  If empty → do NOT audit a no-op. Tell the operator the plan looks unimplemented and offer the fork, naming the EXACT command for each side (adding --autonomous to a code run does nothing): (1) re-run as /cycle plan <plan-file> --autonomous (let /cycle implement it), or (2) implement manually then re-run /cycle code <plan-file> unchanged. → references/orchestration-rationale.md §Step 3 — read when the guard or the fork is questioned.

═══════════════════════════════════════
  /cycle paused at implementation gate
  Plan: docs/plans/<name>.md
  Resume with: /cycle code docs/plans/<name>.md
═══════════════════════════════════════

---

Step 3C — Clustered execution (when hasClustering)

Cluster execution state — .audit/cycle-cluster-state.json

Durable, gitignored, lock-guarded (lock-acquire failure → stop, no racy overwrite); one record per cluster with gateStatus: pending|audited|gate-clear|stale. A gate-clear cluster flips to stale if any derivedScope file hash or its scopeHash changes. → references/clustered-execution.md §Cluster execution state — read before the first read or write of this file in a session.

Loop (autonomous)

State-driven + resumable: read state first, skip gate-clear clusters. For each remaining cluster in declared order:

1. Implement the cluster's member-file phases.

2. Budget: no runtime splitting in v1 — invoke /audit-code on the cluster's derived scope and let its internal map-reduce handle large diffs. /cycle only enforces never merge across a declared boundary.

   • Optional author-tier observation (telemetry only; it does NOT change which model runs) → references/clustered-execution.md §Optional author-tier — read when the cluster carries an author-tier: hint.

3. Audit envelope: capture clusterStartRef (vcs.gitCommitSha) when implementation begins, write the cluster's derived scope one-path-per-line to a scope file, then run the two commands below. On a resume with no recorded clusterStartRef, require --baseline-ref <sha> or fall back to union-diff — never default the base to HEAD (empty diff = silent skip). Round policy is /audit-code's own cap — no new policy here.

   --files is the ONLY flag that scopes the audit. --changed is the R2+ impact set for reopen detection and --diff is hunk evidence; neither bounds what the model reads. Do NOT hand-compute the change set or hand-apply the admission rules: cycle-cluster-scope.mjs does that in code. → references/clustered-execution.md §Why --files — read when the scope flags are questioned.

<!-- cycle:cluster-audit-command -->

# 1. Deterministic half, in code. Resolves the base to an immutable OID, builds
#    the reconciliation set (status-aware: deletes and BOTH rename operands),
#    filters to on-disk paths for the allowlist, runs the admission pre-flight,
#    writes the patch. EXITS NON-ZERO on an out-of-scope edit, an unadmittable
#    path, or a comma-unsafe path — when it does, STOP and show its stderr.
node scripts/cycle-cluster-scope.mjs --base "$CLUSTER_START" --scope-file "$SCOPE_FILE" --out-dir .audit --cluster "$ID" --json > "$SCOPE_JSON"

# 2. Audit using ONLY values that call produced. Read them with node, not jq —
#    node is guaranteed here; jq is not, and is absent from check-deps.mjs.
FILES=$(node -p "require('./$SCOPE_JSON').filesCsv")
PATCH=$(node -p "require('./$SCOPE_JSON').diffPath")
INFRA=$(node -p "require('./$SCOPE_JSON').allowInfraScopeRequired ? '--allow-infra-scope' : ''")

node scripts/openai-audit.mjs code "$PLAN" --scope diff --files "$FILES" --changed "$FILES" --diff "$PATCH" $INFRA
#   --files   : THE scoping flag — an allowlist; makes --scope a no-op
#   --changed : R2+ reopen/impact detection only — does NOT scope
#   --diff    : hunk evidence — centres every round's read windows on the change
#               (R2+ also annotates); does NOT scope; must be a real file

<!-- /cycle:cluster-audit-command -->

The script returns two sets (reconciliation set vs on-disk allowlist) — use them as returned → references/clustered-execution.md §Two sets — read when they look inconsistent.

A deletion-only cluster has an empty allowlist and reports emptyAllowlist: true. That is correct — there is no code to read. Route it to the consolidated Gemini gate over the union diff, where the deletion IS visible; do not record a vacuous per-cluster pass. 4. Fix-gate: fix-gate: yes → reach /audit-code convergence (HIGH==0 && MEDIUM<=2 && quickFix==0) over this cluster's IN-CLUSTER findings (see 4a) before the next cluster; none skips; final defers to the consolidated gate. Within-cluster fixing is authorized; a fix needing files outside the cluster's scope → stop for confirmation (mark any touched gate-clear cluster stale). Persistent non-convergence → hand back with a summary.

• 3a. clusterStartRef is validated ON USE, not just captured. Run git merge-base --is-ancestor <clusterStartRef> HEAD before it becomes a diff base. On a non-ancestor (a concurrent session moved HEAD), halt and report rather than demoting to the dirty-aware default, which would quietly widen the range you asked for. → references/clustered-execution.md §3a — read when the base check is questioned.

• 4a. The gate scores IN-CLUSTER findings only — otherwise no cluster but the last can ever pass (→ references/clustered-execution.md §4a — read when in-cluster scoring is challenged). Classify every finding by the cluster owning its cited file — the derived scopes are already computed, so this is mechanical, not a judgement call:

  Cited file is in…	Class	Effect on THIS gate
  this cluster's derived scope	in-cluster	gates — fix it, pre-existing or not
  a later cluster's derived scope	deferred-declared	does not gate; must be zero at the final gate
  an earlier cluster's derived scope	regression	gates — that cluster is now stale; go to step 5
  no cluster's derived scope	out-of-scope	unchanged: fail closed per step 3

  Three properties stop this becoming an escape hatch, and all three are load-bearing: (1) deferral is bounded — deferred-declared means "owned by a LATER cluster", and the final cluster has none, so the bucket is empty there by construction and every deferred completeness finding must be satisfied before Step 3C.2; (2) "pre-existing" is still not a defer reason — these buckets are about plan SCHEDULE, never authorship, so AGENTS.md's impact test applies unchanged to anything in-cluster; (3) the classification is derived, never argued — a finding cannot be talked into a friendlier bucket. Every deferred-declared finding is listed in the cluster's hand-back summary with the cluster that owns it — a deferral nobody can see is indistinguishable from a dismissal.

• Convergence test scope — run the BROADEST suite, not unit-only (load-bearing for destructive clusters). When "iterate to green" runs the project's tests at the cluster boundary, use the widest command the repo defines (test:all / test:integration / test:e2e — fall back to plain test / the full node --test), never test:unit alone (→ references/clustered-execution.md §Why the broadest test suite — read when a unit-only green is proposed). A cluster is "green" only when the integration tier passes; a test:unit-only green on a destructive cluster is a false-green and does not clear the fix-gate. 4.5. Finalize outcomes (deterministic capture — WS1): once the cluster's audit has converged AND its findings are triaged (the adjudication ledger carries terminal accepted/dismissed/severity_adjusted outcomes), call once per converged audit:

node scripts/cross-skill.mjs finalize-outcomes --run-id "$CLOUD_RUN_ID" --ledger "$FINAL_LEDGER_JSON" --result "$FINAL_ROUND_RESULT_JSON"

The run-id is the audit's _cloudRunId (on the --out JSON); → references/clustered-execution.md §4.5 — read when asked what it captures. Cloud-off → it no-ops with a hint; an unknown run-id is a hard error. Skip only when the audit produced no cloud run (cloud off). 5. After the loop: if any gate-clear cluster went stale, halt + summarize; resume only with --authorize-stale-reaudit, which re-processes exactly the stale clusters (their out-of-scope reconciliation ignores files owned by other clusters, since later clusters legitimately committed since the old baseline). No autonomous loop-back.

Step 3C.1 — Close-out execution (autonomous)

The loop only iterates §7b phases, so the plan's unclustered close-out (e.g. npm run skills:regenerate + npm run skills:check, build/codegen) would never run. After the last cluster clears and before the consolidated gate, parse and execute the plan's close-out step(s), surfacing failures. (Human path leaves close-out to the operator.)

Step 3C.2 — Consolidated Gemini gate (closed loop, mandatory)

First, the deferrals come due. Step 4a lets a cluster defer a finding that belongs to a later cluster; this is where that debt is settled, because there is no later cluster left. Before invoking the reviewer, re-check every deferred-declared finding accumulated across the run: each must now be satisfied (the file exists, the migration ran, the phase landed). Any that remain are the plan's own §7b work, unimplemented — halt and summarize rather than asking Gemini to bless an incomplete change set. This check is what makes 4a a deferral instead of a dismissal, so it is not optional and not Gemini's job.

After all clusters (+ close-out), run one Gemini review over the union diff — mandatory regardless of per-cluster GPT convergence, and a closed loop driven by the result's code-computed gateDisposition (not the verdict word): approve → done; approve_with_debt → done, capture the non-blocking findings with node scripts/debt-auto-capture.mjs --final-review .audit/$SID-gemini-result.json; blocked → deliberate, apply fixes scoped to the union diff (the per-cluster out-of-scope stop does NOT apply here — no active cluster; touched gate-clear clusters are flagged stale for the next run), re-run as round 2 with --round 2 --prior .audit/$SID-gemini-result.json (the round-1 --out). Max 2 consolidated rounds — a hard cap enforced by gemini-review.mjs, which refuses --round 3. A round-2 blocked is handed back to the user with its named blocking items (a concrete design/correctness defect: fix it, then escalate — see gemini-gate.md); implementation-completeness nits ("specify the store step", parameter placement) are non-blocking by definition and close as debt, since the classic /audit-code path (Step 4) already verified the code against the real implementation. Exit on approve/approve_with_debt, the capped stop, or explicit handback. Never replaced by GPT rebuttal.

Between consolidated rounds, apply gemini-gate.md's Step 7.1 deliberation protocol exactly — this closed loop is the SAME one, not a second one. For each CONCERNS/REJECT finding decide ACCEPT / PARTIAL / CHALLENGE (a CHALLENGE must cite evidence); fix the accepted findings; then rebuild the transcript before re-running Gemini, passing --summary describing what round 1 decided per finding — fixed, or challenged-and-why; without it round 2 re-raises the same findings. → references/clustered-execution.md §3C.2 round 2 — read when round 2 repeats round 1.

Invocation: build the transcript the way /audit-code does (changed_files=union file set, accumulated per-cluster findings as the rounds[] trail), then node scripts/gemini-review.mjs review <target> <transcript.json> --out … — reuse /audit-code's transcript path, no new gate machinery. Pass one --ledger <path> per cluster (.audit/$CLUSTER_SID-ledger.json each) — build-audit-transcript.mjs's --ledger flag is repeatable (mirroring --result); one ledger alone drops the other clusters' resolutions (→ references/clustered-execution.md §3C.2 one --ledger — read when a cluster's resolutions are missing). Concrete transcript shape + the no-GEMINI_API_KEY degradation ladder (Opus fallback → independent adversarial agent over the union diff → only-then skip) are in references/gemini-gate.md (the same contract /audit-code's Step 7 follows) — when no provider key is present, run the independent-agent substitute rather than skipping the mandatory gate. Generated .claude/skills/** copies are byte-verified by skills:check, not re-reviewed. Then continue to Step 5 (Step 7 still ends even a fully autonomous run in the blocked handoff).

---

Step R — Remediation (REMEDIATE mode only)

For narrow defects found after a ship, against a plan already accepted: replaying the whole chain re-plans, re-audits the plan and audits the whole dirty tree. REMEDIATE runs instead, in order, and nothing else:

1. R1 load the governing plan — no /plan, no /audit-plan; Step 0.5 still runs.
2. R2 triage the --from report into a fix list (persona P0/P1, or audit HIGH, by default) and record it in the plan's ## Implementation Log.
3. R3 implement — pauses for the human by default; implements only under --autonomous. Capture the base before the first edit.
4. R4 focused /audit-code — --files pinned to the fix files + the plan via scripts/cycle-cluster-scope.mjs, which exits non-zero on any edit outside that set. Never a whole-dirty-tree diff. Caps unchanged: 6 audit rounds, 2 final-review rounds.
5. R5 rerun only the affected persona journey(s), exercising the stateful lifecycle (act → reload → verify persisted → follow-on action → verify).
6. R6 update the plan's log with per-finding outcomes, Step 6 /ux-lock, then Step 7's blocked /ship handoff — never autonomous.

The commands, triage table, resume card, rerun verdicts and summary card are in references/remediate-mode.md — read it before R2.

---

Step 4 — Audit Code (classic path — no §11 block)

Invoke /audit-code <plan-file> (default --scope=diff). Multi-pass parallel GPT audit with R2+ ledger suppression and Gemini final review. Max 6 rounds; quality threshold HIGH==0 && MEDIUM<=2 && quickFix==0.

On verdict:

• CONVERGED → proceed to Step 5
• INCOMPLETE (passes timed out) → present to user, offer: continue with partial / re-run with higher timeout / stop
• Persistent HIGH findings after R6 → present to user with finding list, recommend fix-then-retry rather than ship

Solo author-model control needs no /cycle action → references/orchestration-rationale.md §Step 4 — read when asked whether /cycle triggers it.

---

Step 5 — Persona Test (if scope ⊇ frontend, AND not --no-persona)

Detect whether persona-test is applicable:

• Skip if plan scope is backend only
• Skip if --no-persona flag passed
• Resolve the target URL in the same order /persona-test itself uses (Phase 0b): --persona-url flag → PERSONA_TEST_APP_URL env → (in --autonomous mode, where there's no human to ask) a running local dev server if one is detectable, else skip (→ references/orchestration-rationale.md §Step 5 — read when tempted to resolve from the env var alone). If no target resolves by any of these, do not skip silently — print Step 5 skipped — persona-test has no target (PERSONA_TEST_APP_URL unset; pass --persona-url <url> to run it) in the Step 8 summary so the gap is visible rather than assumed-away.

Step 5.0 — Deploy-topology gate (GREEN ≠ REALIZED #7)

Before driving the browser, resolve whether persona-test can actually GATE here — call the seam, don't re-decide in prose (the decision is a tested function):

node scripts/cross-skill.mjs preview-gate --format human

Act on the directive:

• [HALT] (previewGateMode: pre_merge_required) — a preview env exists and MUST gate. Run persona-test against the preview --url and halt before merge/ship until it passes; do not let Step 7 ship on a failed/again-skipped persona run.
• [WARN] (post_merge_warning — deploy-from-main / no preview) — surface the warning prominently: persona-test here is POST-HOC and cannot prevent prod exposure; its P0/P1 findings are fast-follow, NOT a gate. Proceed, but say so in the Step 8 summary.
• [OK] (not_applicable, default) — silent; proceed normally.

Invoke /persona-test <persona> <url> — drives a browser as a registered persona, collects P0–P3 findings.

On verdict:

• 0 P0 findings AND OVERALL is Ready for users → proceed to Step 6
• 0 P0 findings AND OVERALL is Needs work because of authWallUntested (persona-test hit a login wall with no auth bootstrap configured — the remedy is /persona-test's auth-bootstrap setup, not a /cycle step) → this is not a clean pass; it means the run never reached the app's primary authenticated surfaces. Surface this explicitly in the Step 8 summary (don't silently read "0 P0" as "proceed") and proceed only as a WARN, same posture as the [WARN] deploy-topology case above.
• ≥1 P0 finding → present to user, recommend fix before ship; offer to feed findings back into a new /audit-code round (under [HALT], a P0 blocks ship until fixed)

---

Step 6 — UX Lock (if any new fixes shipped, AND not --no-uxlock)

For each HIGH finding fixed in Step 4, AND each P0/P1 fixed in Step 5, invoke /ux-lock to generate a Playwright spec that locks the fix.

Skip if no fixes were applied OR --no-uxlock flag passed OR backend-only scope.

---

Step 7 — Ship (unless --no-ship)

/ship cannot actually be invoked from here — by design, every time. /ship's frontmatter carries disable-model-invocation: true, which refuses ANY programmatic call, including one made from inside /cycle's own orchestration; --autonomous does NOT authorize shipping. → references/orchestration-rationale.md §Step 7 — read when asked to ship from /cycle.

So Step 7 always ends in a blocked handoff, never an "Invoke /ship." Show this card and stop — name the plan path so the human never has to go hunting for it (a bare /ship with no argument is a second manual step, not a resume command):

═══════════════════════════════════════
  /cycle blocked at Step 7 (ship)
  /ship requires explicit user invocation — it cannot be called
  programmatically, even from /cycle's own orchestration.
  Resume with: /ship docs/plans/<name>.md
═══════════════════════════════════════

---

Step 8 — Cycle Summary

═══════════════════════════════════════
  /cycle complete — <PLAN-NAME>
  Plan:        docs/plans/<name>.md
  Audit-plan:  3 rounds, APPROVE
  Clusters:    A in-cluster H:0 (2 deferred→C); B in-cluster H:0 (autonomous)  ← only if hasClustering
  Audit-code:  4 rounds, CONVERGED, H:0 M:1 L:2                 ← classic path (no §11)
  Final gate:  Gemini APPROVE over union diff                  ← only if hasClustering
  Persona:    0 P0, 1 P1 (deferred)
  UX-lock:    2 specs generated
  Ship:       BLOCKED — run: /ship docs/plans/<name>.md
  Total time: 18m
  Total cost: ~$1.40
═══════════════════════════════════════

The Ship: line is BLOCKED unless the user already ran /ship themselves in this same turn — Step 7 can never invoke it (see Step 7's note), so "commit abc1234 pushed to main" is only correct after the human has actually typed /ship docs/plans/<name>.md and it completed. Never print a commit sha here on the assumption that Step 7 "ran" — it didn't.

If any step was skipped, note why. If any step exited non-success, surface as a warning at the top. For clustered runs, show the per-cluster gate result and the preflight outcome.

---

Hard rules

• Never auto-fix between steps without user confirmation — except in --autonomous mode, where the opt-in flag authorizes within-cluster fixes scoped to the active cluster's derived file set (summaries still surfaced; cross-cluster fixes and persistent non-convergence still hand back).
• Never skip /audit-plan unless explicitly in SKIP_TO_CODE or REMEDIATE mode. SKIP_PLAN skips /plan, not /audit-plan. Never infer "already accepted" — there is no mechanical record of which plan content was approved (Step 0).
• Never skip /audit-code unless explicitly in SKIP_TO_SHIP mode (not currently exposed; reserved). REMEDIATE focuses it; it never skips it.
• Default is human-orchestrated — /cycle pauses at the implementation gate (Step 3); only the opt-in --autonomous flag implements code, and it never activates silently.
• /cycle reads the §11 block; it never authors or merges clusters — it may split-equivalent (defer oversized diffs to /audit-code's map-reduce) but never merges across a declared boundary. Clustering is the plan's job.
• The consolidated Gemini gate is mandatory after clustered execution, regardless of per-cluster convergence — and Step 3C.2's deferral re-check runs before it, so no deferred-declared finding survives the run.
• A per-cluster fix-gate scores IN-CLUSTER findings only (Step 4a). Scoring the whole plan against one cluster's diff makes every gate but the last unpassable; deferral is bounded to later-cluster scopes and settled at 3C.2. Never widen it to "pre-existing" — that is authorship, not schedule.
• Cost cap awareness: estimate total cost upfront from input size and surface it in the kickoff card. A typical full cycle costs $1–3; autonomous clustered runs cost more (one audit per cluster + the final gate).

---

Reference files

This skill's canonical flow is above. The files below cover specialised situations — read them only when the trigger applies.

File	Summary	Read when
references/input-acquisition.md	Where a skill's arguments come from on any host, and what to do when there are none.	The no-dispatch fallback — passing an inlined skill its plan path, sub-command and flags as orchestrator-supplied input (rule 0).
references/prerequisite-ladder.md	Step 0 prerequisite ladder — absent helper bundle or auditor route, and reporting a run that did not happen.	Step 0 — an audit prerequisite did not resolve (helper scripts missing, no GPT route), OR about to report a run that degraded or did not happen.
references/verification-discipline.md	Verification discipline — pinned citations, figure provenance, two-direction proof, attribution, consumer-side checks.	Reporting a degraded or substituted run — §7's coverage rule, which the prerequisite ladder's census rows cite.
references/gemini-gate.md	Step 7 Gemini independent review protocol — transcript, verdict handling, re-review loop.	Autonomous mode's consolidated Gemini gate — building the transcript, OR no GEMINI_API_KEY and the degradation ladder decides the substitute.
references/remediate-mode.md	REMEDIATE mode — fix triaged post-ship findings against an accepted plan without replaying the full cycle.	The mode is REMEDIATE (Step R), OR the user asks to skip /audit-plan because the plan is already accepted.
references/clustered-execution.md	Step 3C detail — cluster-state schema, author-tier hint, scope-flag incident, 4a measurement, round-2 rationale.	Step 3C — first read/write of .audit/cycle-cluster-state.json, an author-tier: hint, OR a cluster's scope, class or gate is contested.
references/orchestration-rationale.md	Why /cycle's linear steps are shaped as they are — inline dispatch, plan deps, empty-diff guard, persona URL, ship.	A linear step's rule (Steps 0–7, outside 3C) is questioned or looks safe to skip.
references/worktree-preflight.md	Worktree preflight remedy — the skills:hydrate npm script to add when a linked worktree lacks the tooling tree.	A command dies with MODULE_NOT_FOUND in a linked worktree AND this repo has no skills:hydrate script.

— end of /cycle —