create-issflow 1.2.1 → 1.5.0

package/README.md

@@ -25,9 +25,9 @@ Flags:
 The portable kit (every tool) in `<project>/.claude/`:
 
 - `agents/` — planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer
-- `commands/` — `/overview` `/propose` `/phase` `/ui-audit` `/qa-audit` `/security-audit` `/change-request` `/replan` `/quick` `/synthesize` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
-- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design
-- `hooks/` — session-start · pre-compact · subagent-stop
+- `commands/` — `/overview` `/propose` `/phase` `/sprint` `/ui-audit` `/qa-audit` `/security-audit` `/release` `/uat` `/change-request` `/replan` `/quick` `/synthesize` `/runbook` `/store-wisdom` `/log-issue` `/log-decision` `/unstuck`
+- `skills/` — caveman · grill-me · karpathy-guidelines · ux-design · security · code-standards
+- `hooks/` — session-start · context-guard · pre-compact · subagent-stop
 - `istartsoft-flow/METHODOLOGY.md` — the full methodology (single source of truth)
 
 Plus a root `AGENTS.md` (the open standard) and the per-tool adapter:

package/bin/cli.js

@@ -211,9 +211,9 @@ function agentsMd() {
     '## Roles — `.claude/agents/`', '',
     'planner · researcher · implementer · test-author · debugger · e2e-runner · synthesizer', '',
     '## Procedures — `.claude/commands/` (run as `/name`)', '',
-    '/overview · /propose · /phase · /ui-audit · /qa-audit · /security-audit ·',
-    '/change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom · /log-issue ·',
-    '/log-decision · /unstuck', '',
+    '/overview · /propose · /phase · /sprint · /ui-audit · /qa-audit · /security-audit · /release ·',
+    '/uat · /change-request · /replan · /quick · /synthesize · /runbook · /store-wisdom ·',
+    '/log-issue · /log-decision · /unstuck', '',
     '## Skills — `.claude/skills/` (loaded on demand)', '',
     'caveman · grill-me · karpathy-guidelines · ux-design · security (Secure SDLC) · code-standards', '',
     '## Autonomy', '',
@@ -230,7 +230,8 @@ function agentsMd() {
     'change · 9 UI conforms to the `ux-design` cookbook + wireframe frame · 10 no-rationalization ·',
     '11 Secure SDLC: threat-model → secure coding → SAST/SCA/secrets each phase → pentest',
     'gate + security review before deploy (`security` skill) · 12 code-standards gate:',
-    'lint/format clean + naming per language idiom + declared architecture (`code-standards`).', '',
+    'lint/format clean + naming per language idiom + declared architecture (`code-standards`) ·',
+    '13 PLAN-APPROVAL gate: no phase/sprint starts until `docs/PLAN.md` is human-approved.', '',
     '## Your stack', '',
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
@@ -265,9 +266,15 @@ function flowConfig() {
         + 'Some 1M-context models report their id WITHOUT a [1m] tag, so auto-detect '
         + 'assumes 200000 and may false-gate around 156k — if you run a 1M model, set '
         + 'window:1000000 here by hand. warnPct = soft non-blocking nudge; gatePct = hard '
-        + 'block on NEW build work (Edit/Write-to-source/feature Task). Checkpoint paths '
-        + '(docs/**, STATE/ISSUES/snapshots), the synthesizer subagent, and all Bash are '
-        + 'never blocked.',
+        + 'block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths '
+        + '(docs/**, STATE/ISSUES/snapshots) and all Bash are never blocked; Task '
+        + 'delegation is never gated (a subagent isolates noise and shrinks context).',
+    },
+    sprint: {
+      defaultCapacity: 8,
+      _note: 'Sprint layer (/sprint). defaultCapacity = points committed to the FIRST '
+        + 'sprint before any velocity history exists; later sprints size to the rolling '
+        + 'completed-velocity average. Optional — /sprint falls back to 8 if absent.',
     },
   }, null, 2) + '\n';
 }
@@ -290,6 +297,13 @@ function main() {
     writeFile(rel, fs.readFileSync(src, 'utf8'));
   }
 
+  // 1b. integrity: confirm the methodology resolved on disk (load-bearing sentinel).
+  const methPath = path.join(CWD, '.claude', 'istartsoft-flow', 'METHODOLOGY.md');
+  const SENTINEL = 'ISTARTSOFTFLOW-AGENTS-SENTINEL-v2.0';
+  if (!DRY && (!fs.existsSync(methPath) || !fs.readFileSync(methPath, 'utf8').includes(SENTINEL))) {
+    warnings.push(`integrity: ${SENTINEL} not found in installed METHODOLOGY.md — the kit may be incomplete; re-run create-issflow (or npm run build from source).`);
+  }
+
   // 2. AGENTS.md — the open-standard entry point.
   writeFile('AGENTS.md', agentsMd());
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.claude/agents/e2e-runner.md

@@ -1,5 +1,6 @@
 ---
 name: e2e-runner
+description: Writes and runs functional browser E2E (your declared E2E runner, e.g. Playwright) BLIND — reads the acceptance spec, OVERVIEW (stack), docs/ENDPOINTS.md, and the E2E runner config, never the implementation. Writes a trace to docs/research/e2e-<phase-slug>.md; returns a terse summary.
 tools: Read, Grep, Glob, Write, Bash
 model: opus
 ---

package/template/.claude/agents/planner.md

@@ -43,6 +43,12 @@ window. If a phase feels big, split it.
   money, or PII), add a `security:` note: threat-model it (STRIDE) and fold abuse
   cases into the acceptance criteria as negative cases; set the ASVS level (default
   L2). This is the design stage of the Secure SDLC (`security` skill).
+- SPRINT-READY (so the optional `/sprint` layer needs no rework): give every phase a
+  relative effort estimate `[N pts]` (Fibonacci 1/2/3/5/8) in its header, and group
+  consecutive phases under `## Sprint <n>: <name>  [goal: <one-line increment>]`
+  headers — each sprint a coherent, demoable theme of a few phases. If you cannot
+  size a sprint yet, still tag the points; `/sprint plan` will do the grouping from
+  the points + capacity. A phase that feels `>8 pts` is too big — split it.
 
 LAST PHASE RULE — the final code phase (the highest-numbered phase you write)
 MUST contain a deployment task block:
@@ -61,11 +67,19 @@ docs/PLAN.md format:
 
 # Plan: <project>
 <!-- infra: managed (Phase 0 N/A) | self-managed (Phase 0 below) -->
+> Approval: PENDING  (hard rule 13 — PLAN-APPROVAL gate; no phase/sprint runs until a human signs this off via the `/overview` gate)
+
+Keep the header VALUE a single leading token — `PENDING` here, later
+`approved <date> v<n>` — so the gate readers (`/phase`, `/sprint`) match the first
+token unambiguously. Do not put prose containing the word `approved` after a
+`PENDING` value, or a substring check could false-pass the gate.
 
 ## Phase 0: infra setup  [status: pending]   ← omit entirely if infra is managed
 
 
-## Phase 1: <name>  [status: pending]
+## Sprint 1: <name>  [goal: <one-line user-visible increment>]   ← sprint headers optional; group a few phases
+
+## Phase 1: <name>  [5 pts]  [status: pending]
 
 - slice: <what works end-to-end after this phase>
 - rationale: <why this slice, why now — the user / business value (from the PRD)>
@@ -90,4 +104,5 @@ docs/PLAN.md format:
 
 ```
 Order phases by dependency. Phase 0 first IF infra is self-managed; otherwise
-start at Phase 1. Stop. Do not implement.
+start at Phase 1. Always write the `> Approval: PENDING` header — the plan is unapproved
+until the `/overview` PLAN-APPROVAL gate stamps it (hard rule 13). Stop. Do not implement.

package/template/.claude/agents/synthesizer.md

@@ -21,6 +21,9 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
    - what was just completed (1-3 bullets)
    - the immediate next action
    - any open blocker
+   PRESERVE verbatim (never blank on rewrite): the `plan:` line (the PLAN-APPROVAL
+   sign-off record, hard rule 13) and the `sprint:` line (active-sprint marker) if
+   present — load-bearing gate/standup state, not transient progress.
    Target: under 25 lines.
 
 2. ISSUES.md — dedup + compress:

package/template/.claude/agents/test-author.md

@@ -31,8 +31,12 @@ peek at, your blindness is STRUCTURAL, not honor-system.
 
 ## TWO SUITES — write BOTH
 
-1. MOCK suite — fast, no external dependency. Mocks ONLY the external boundary.
-   No mocks on the external boundary. Code/API-level — not browser E2E.
+1. MOCK suite — fast, no external dependency. Mocks ONLY the external boundary
+   (the network / 3rd-party seam). Code/API-level — not browser E2E.
+2. REAL API suite — the SAME tests with no mocks, hitting the real external
+   boundary. The phase gate runs against THIS suite (rules 5–6); a green mock
+   suite alone can never close a phase. Mock vs real is a fixture/env FLAG on the
+   same test (see Test placement), not a duplicated file.
 
 ## Test placement (regression layout)
 

package/template/.claude/commands/change-request.md

@@ -1,6 +1,6 @@
 ---
 description: Handle a mid-project requirement change — assess impact, re-estimate effort + cost, log the change order, then update the plan + proposal. Run whenever scope changes after the proposal is approved.
-argument-hint: [the requested change]
+argument-hint: [the requested change · "dry-run" to preview impact without logging]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -8,6 +8,11 @@ Caveman ULTRA mode. You are the ORCHESTRATOR.
 A change request is a COMMERCIAL event, not just a re-plan: changing scope changes
 cost and timeline. Handle it transparently and fairly. Change: $ARGUMENTS
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the impact analysis +
+re-estimate but EXECUTE NOTHING — print the ACTION PLAN (cost/scope/timeline delta,
+files you'd touch) and STOP. No change order is logged, no plan/proposal is edited.
+(METHODOLOGY → Dry-run.)
+
 ## PRE-FLIGHT
 Read `docs/PROPOSAL.md` (the approved baseline), `docs/PLAN.md`, `docs/STATE.md`,
 and `docs/CHANGES.md` (create if missing). No approved proposal yet -> you're still
@@ -44,7 +49,10 @@ gate — always interactive).
 - **Approved** -> set CR status `approved`; bump PROPOSAL.md to a new version (vN+1)
   with the delta folded in; re-render `docs/proposal.html` from it (same template +
   language); then dispatch `/replan` to apply the phase changes to PLAN.md (done
-  phases stay frozen). Update STATE.md.
+  phases stay frozen). Update STATE.md. NOTE: `/replan` reverts PLAN.md to
+  `> Approval: PENDING` and re-runs the PLAN-APPROVAL gate (hard rule 13) — the
+  commercial CR sign-off is SEPARATE from the plan sign-off, so `/phase` and
+  `/sprint` stay blocked until you also re-approve the revised plan.
 - **Rejected** -> set CR status `rejected`; PLAN + PROPOSAL unchanged.
 
 ## STEP 6 — RECORD

package/template/.claude/commands/log-issue.md

@@ -12,7 +12,7 @@ Canonical format:
 
 ### <short error title — searchable, literal error keywords>
 
-- [x] open      (or “- [x] resolved”)
+- [ ] open      (or “- [x] resolved” once fixed)
 - symptom: <what was observed>
 - root cause: <the REAL underlying cause>
 - solution: <exact fix, or “pending”>
@@ -23,6 +23,8 @@ Rules:
 - title must contain literal error keywords -> grep finds it.
 - root cause is the real cause, not "the line threw an error".
 - always fill "failed attempts" — stops repeated dead ends.
+- open issues use the empty box `- [ ]`; resolved are checked `- [x] resolved`
+  (the SessionStart hook surfaces every `- [ ]` as open — keep the box empty until fixed).
 - open issues go at the TOP; resolved below; archived oldest at bottom.
 
 Confirm the entry back in 2 lines.

package/template/.claude/commands/overview.md

@@ -75,6 +75,20 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 
 ---
 
+### Foundations sign-off (confirm BEFORE planning)
+
+5b. Before the `planner` runs, present the FOUNDATIONS for explicit human confirmation
+— the whole plan is built on these, so lock them first. Show a concise summary and
+STOP for sign-off (planning always asks, both modes):
+- **Tech stack** — language · framework · infra · auth · datastore · test + E2E runner
+- **Architecture** — the pattern (Feature-Based by default) + the folder layout
+- **UX direction** — design system / tokens + the wireframe baseline (the frame)
+- **Data & integrations** — core data model + external services + their limits
+- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED)
+- **Estimation config** — unit · rate card · currency · contingency (if quoting)
+On any "change X" → revise OVERVIEW.md and re-confirm. Only a signed-off foundation
+proceeds to the planner. (This is the planning confirmation gate.)
+
 ### Plan
 
 6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
@@ -89,6 +103,7 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 # STATE
 
 phase: 0 (pending)
+plan: PENDING
 completed: project bootstrapped — design research done, double grill done
 blocker: none
 
@@ -97,17 +112,31 @@ blocker: none
 
 9. Create empty docs/HISTORY.md.
 
-
-11. Create docs/ENDPOINTS.md:
+10. Create docs/ENDPOINTS.md:
  ```
  # Endpoints — <project name>
  > Maintained by implementer. Updated each phase.
  > Base URL: (populated after deployment phase)
  ```
 
-Then stop and show me PLAN.md for approval before any phase starts. Planning ends
-with a human sign-off in both modes; AUTO only governs the development loop that
-runs AFTER the plan is approved.
+---
+
+### PLAN-APPROVAL gate (hard rule 13 — always interactive, both modes)
+
+11. The plan is the contract the whole AUTO dev loop builds against, so it ends with a
+    human sign-off — the planning twin of the `/propose` commercial gate.
+
+    - SHOW me PLAN.md (and note any open risks the planner flagged). **STOP for approval.**
+    - On **approval**: record the sign-off in three places —
+      1. stamp the PLAN.md header `> Approval: approved <YYYY-MM-DD> v1`;
+      2. set `plan: approved <YYYY-MM-DD>` in docs/STATE.md;
+      3. append `<YYYY-MM-DD> plan v1 approved` to docs/HISTORY.md (date-first, to
+         match the other HISTORY lines).
+      Only now may `/phase` / `/sprint` run.
+    - On **rejection / change**: revise (re-run the `planner`, or `/replan`), bump the
+      version, and re-show. The header stays `PENDING` until I approve.
+
+    AUTO governs the development loop that runs AFTER this gate, never the gate itself.
 
 Optional next step (client / quoted work only): run `/propose` to turn this
 OVERVIEW + PLAN into a proposal + estimate for sign-off before building. Internal or

package/template/.claude/commands/phase.md

@@ -1,8 +1,9 @@
 ---
 description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
-argument-hint: [phase number]
+argument-hint: [phase number · "dry-run" to preview what the phase would do]
 ---
 
+
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
 you do NOT implement or debug yourself.
 
@@ -12,14 +13,28 @@ Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
 
 ---
 
+## DRY-RUN CHECK (first — before PRE-FLIGHT)
+
+If `$ARGUMENTS` contains `dry-run` or `--dry-run`: do the full analysis but EXECUTE
+NOTHING. Print the ACTION PLAN — files you'd create/change · agents you'd dispatch ·
+tests/gates you'd run · deploy target · cost/scope/risk impact — then STOP. Write,
+run, commit, deploy nothing. (METHODOLOGY → Dry-run.)
+
+---
+
 ## 0. PRE-FLIGHT
 
-a. INFRA CHECK (phases > 0): Read the declared infra in docs/OVERVIEW.md.
+a. PLAN-APPROVAL CHECK (hard rule 13): Read the docs/PLAN.md `> Approval:` header.
+   Still `PENDING` (or no header) -> STOP. The plan is not signed off; no phase may
+   start. Route me to the `/overview` PLAN-APPROVAL gate (or `/replan` then re-approve).
+   Approved -> continue.
+
+b. INFRA CHECK (phases > 0): Read the declared infra in docs/OVERVIEW.md.
    - Managed infra -> confirm it is reachable; no provisioning step is needed.
    - Self-managed infra -> confirm Phase 0 (infra) ran and is healthy.
    Surface infra + auth status before any work. Blocked infra -> STOP.
 
-b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
+c. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
    - No phase in progress, requested is next pending -> START at step 1.
    - Same phase in-progress -> RESUME from STATE.md "next action".
    - Different phase in-progress -> STOP. Tell me which phase is open.
@@ -27,7 +42,7 @@ b. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
      phase in PLAN order. GUIDED: STOP, warn, proceed only if I confirm.
    - Phase not in PLAN.md -> STOP. Suggest /overview or /replan.
 
-c. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
+d. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
 
@@ -181,6 +196,12 @@ SECURITY GATE (rule 11 — Secure SDLC build stage):
 
 Mark phase `done` in docs/PLAN.md.
 
+SPRINT STANDUP (if a sprint is active — STATE.md shows `sprint: <n> (active)`):
+fire the `/sprint standup` tick — append the one-line standup to
+docs/sprints/sprint-<n>.md and update the burndown (rule: SPRINT-STANDUP ritual).
+If all the sprint's committed phases are now done/blocked, recommend `/sprint review`
+(or, under `/sprint run`, the driver proceeds to review automatically).
+
 ARCHITECTURE SELF-CHECK: did this phase add/remove/rename an agent, hook, or
 command, or change a workflow rule? YES -> run `/log-decision`. NO -> state why not.
 
@@ -221,10 +242,12 @@ After each step, update docs/STATE.md:
 ```
 
 phase: <n> (in progress)
+plan: approved <date>          ← carry forward; never drop the rule-13 sign-off record
 tdd: <true|false>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>
 
 ```
-Keep STATE.md small — overwrite, do not append.
+Keep STATE.md small — overwrite, do not append. Preserve the `plan:` line on every
+overwrite (the PLAN-APPROVAL record, hard rule 13); do not blank it.

package/template/.claude/commands/propose.md

@@ -1,6 +1,6 @@
 ---
 description: Turn approved requirements + tech stack into a client proposal — scope, phase breakdown, effort + cost estimate, timeline, assumptions, and a sign-off gate. Run after /overview, before building.
-argument-hint: [optional: rate / budget / constraints]
+argument-hint: [optional: rate / budget / constraints · "dry-run" to preview]
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR.
@@ -9,10 +9,20 @@ Purpose: produce `docs/PROPOSAL.md` — WHAT we build, in what phases, how long,
 much, and on what assumptions — for the client to approve BEFORE any build starts.
 A proposal is a commercial gate: always interactive (both AUTO and GUIDED).
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (scope, phase breakdown, rough estimate)
+and STOP. No PROPOSAL.md / proposal.html is written. (METHODOLOGY → Dry-run.)
+
 ## PRE-FLIGHT
 Read `docs/OVERVIEW.md` (scope, stack, success criteria) and `docs/PRD.md` if
 present (else the PRD in your BMAD/iSSM). No OVERVIEW -> run `/overview` first.
 
+PLAN-APPROVAL CHECK (hard rule 13): the proposal prices the *approved* phases, so
+the plan is signed off first (lifecycle: plan → proposal). If `docs/PLAN.md` exists
+and its `> Approval:` header still reads `PENDING` (or is missing), STOP and route me
+to the `/overview` PLAN-APPROVAL gate before quoting — pricing an unapproved plan
+re-prices on every revision.
+
 ## STEP 1 — SCOPE
 List the deliverables (features / epics) from OVERVIEW / PRD. Mark each
 **in-scope** or **out-of-scope** explicitly — naming out-of-scope items now is what
@@ -57,12 +67,13 @@ change-orders re-price against.
 ## Sign-off     — approved by: ___  date: ___  version: v1
 ```
 2. RENDER a client-facing `docs/proposal.html` from `.claude/templates/proposal.html`:
-   copy it, replace every `{{PLACEHOLDER}}`, and LOCALISE all labels + content to the
-   declared language (natural Thai for Thai projects; keep tech terms in English).
-   Fill `{{COMPANY}}` / `{{LOGO}}` from the ISSUING company's brand declared in
-   OVERVIEW (or ask once) — the template is white-label, never hardcode the kit's
-   name. It is print-ready (Save as PDF). Keep PROPOSAL.md and proposal.html in sync —
-   the markdown is the source, the HTML is the deliverable you send the client.
+   copy it, replace every `{{PLACEHOLDER}}`, and fill the CONTENT in the declared
+   language (the section labels are already bilingual TH / EN). It must fit ONE A4
+   page — be terse (≈ 3–6 phase rows, ≈ 4 assumptions, short scope items); trim before
+   it spills to a second page. Fill `{{COMPANY}}` / `{{COMPANY_TAGLINE}}` / `{{LOGO}}`
+   from the ISSUING company's brand declared in OVERVIEW (or ask once) — white-label,
+   never hardcode the kit's name. Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep
+   PROPOSAL.md (source) and proposal.html (deliverable) in sync.
 
 ## STEP 6 — SIGN-OFF GATE
 Show me the proposal. **STOP for approval** (commercial gate — always interactive).

package/template/.claude/commands/quick.md

@@ -1,12 +1,16 @@
 ---
 description: Make a small, obvious change directly — no agent chain, no phase overhead.
-argument-hint: [what to change]
+argument-hint: [what to change · "dry-run" to preview the edit]
 ---
 
 Caveman ULTRA mode. Apply `karpathy-guidelines` skill.
 
 Purpose: skip the orchestration tax for a 5-line fix.
 
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, describe the exact edit
+you'd make (file · lines · the change) and the regression you'd run, then STOP —
+change nothing. (METHODOLOGY → Dry-run.)
+
 Use `/quick` when ALL hold:
 - change is small (under 30 lines) and obvious
 - no new vertical slice
@@ -14,7 +18,7 @@ Use `/quick` when ALL hold:
 - not mid-phase
 
 If any fail -> STOP, tell me, recommend `/phase`.
-(Hard rule 11: never route phase-worthy work through `/quick` to dodge the RED gate.)
+(Hard rule 10: never route phase-worthy work through `/quick` to dodge the RED gate.)
 
 Steps:
 1. grep docs/ISSUES.md for anything related.

package/template/.claude/commands/release.md

@@ -0,0 +1,55 @@
+---
+description: Pre-production release pipeline — after all build phases, run the full automated gauntlet (full regression: functional / integration / e2e · all audits: UI / QA / security / code · smoke test), then hand off to manual UAT, drive the defect loop to green, produce a sign-off document, and promote to production. The automated SDLC backbone; production deploy is a human-signed hard-stop.
+argument-hint: [optional: target env · "dry-run" to preview the pipeline without running it]
+---
+
+Caveman ULTRA mode. You are the ORCHESTRATOR.
+
+Run this AFTER every build `/phase` is done (the candidate is on staging/preview).
+AUTO runs all AUTOMATED stages without stopping; it STOPS only at the human gates —
+UAT execution, sign-off, and the production promote (security/irreversible hard-stops).
+Record progress in STATE.md so a resumed session continues mid-pipeline.
+
+DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, do the full analysis but
+EXECUTE NOTHING — print the ACTION PLAN (stages, audits, deploy target, risk impact)
+and STOP. Nothing is run, signed, or promoted. (METHODOLOGY → Dry-run.)
+
+## STAGE 1 — FULL REGRESSION (auto)
+Run the whole REAL corpus end-to-end: **functional + integration + e2e**
+(`scripts/regression.sh --real`, then the declared E2E runner via `e2e-runner`).
+Any red → `debugger` (cap 3) → fix → re-run. Must be 100% green to proceed.
+
+## STAGE 2 — AUTO AUDITS (auto)
+Run every whole-product audit and fold results together:
+- `/ui-audit` · `/qa-audit` · `/security-audit`
+- **code cleaning**: lint + format (the language's standard tool) must be clean
+- **code optimization**: a pass for dead code, obvious N+1 / perf, bundle bloat
+Collect every BLOCKER / HIGH / CRITICAL. Open blocker → fix → re-audit. (Security
+fixes surface for sign-off — security is an autonomy hard-stop.)
+
+## STAGE 3 — SMOKE TEST (auto)
+Deploy the candidate to staging/preview; run the **smoke suite**: app boots, health
+endpoint 200, the critical happy paths load, no console/server errors. Fail → STOP, fix.
+
+## STAGE 4 — UAT HANDOFF (human)
+Dispatch `/uat`: generate the all-case scenario document, hand it to the testers, and
+WAIT. Capture their pasted results into `docs/UAT-<date>.md`. (UAT is a human gate.)
+
+## STAGE 5 — UAT DEFECT LOOP
+For each issue/bug reported: log to `docs/ISSUES.md` (repro from the scenario), fix
+(`implementer`/`debugger`), re-run STAGE 1–3 for the touched area, then resubmit ONLY
+the failed scenarios via `/uat`. Loop until ALL scenarios PASS.
+
+## STAGE 6 — SIGN-OFF (human)
+Produce `docs/SIGNOFF-<date>.md`: scope delivered · test + audit results summary · UAT
+pass confirmation · known limitations · the approver/date line. **STOP for human
+sign-off** — a release gate, always interactive in both modes.
+
+## STAGE 7 — PROMOTE TO PRODUCTION (hard-stop)
+On a SIGNED sign-off only: deploy to production, smoke-test prod (health 200), update
+`docs/ENDPOINTS.md` base URL, tag the release. HISTORY line: `released v<n> (<date>)`.
+
+## STAGE 8 — GO-LIVE & SUPPORT
+Enter after-go-live support (hypercare): watch for incidents, keep the issue log live.
+New scope → `/change-request` (impact + re-price + sign-off). The project is live; the
+loop continues through change requests.

package/template/.claude/commands/replan.md

@@ -54,12 +54,18 @@ commercial impact (split/merge/reorder, a discovered technical re-slice).
    - A MERGE -> consolidate the merged phases' regression tests.
    - A REORDER -> keep the tests as-is (contracts are phase-independent).
    Do NOT touch phase-local `tests/phase-<n>/` here beyond renumbering dirs.
-   After reconciling, run `scripts/regression.sh --real` to confirm the
-   reconciled corpus still passes against live services. A failure -> surface it
-   and stop before approval.
-
-6. SHOW ME the revised phase list + the regression-corpus changes, and STOP for
-   approval.
+   After reconciling, re-run the regression corpus to confirm it still passes:
+   `--real` ONLY if at least one phase is done (live services exist); on a pre-build
+   replan (no done phase, managed infra not yet wired) run the mock corpus instead,
+   or skip with a noted reason. A failure -> surface it and stop before approval.
+
+6. PLAN-APPROVAL gate (hard rule 13). A re-plan reshapes UNBUILT scope, so it reverts
+   the plan to unapproved: set the PLAN.md `> Approval:` header back to `PENDING`, SHOW
+   ME the revised phase list + the regression-corpus changes, and STOP for approval.
+   On approval: re-stamp the header `approved <date> v<n+1>`, update STATE.md `plan:`,
+   and append `<date> plan v<n+1> approved (replan)` to docs/HISTORY.md (date-first,
+   matching the other HISTORY lines). `/phase` and `/sprint` stay blocked until this
+   re-stamp.
 
 7. ARCHITECTURE SELF-CHECK: re-planning is not normally a kit-architecture
    change. Only run /log-decision if the workflow itself changed (rare).