create-issflow 1.10.1 → 1.12.0

package/template/.issflow/commands/overview.md

@@ -81,14 +81,30 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 — 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
+- **Auth checklist** (if any login/user): provider · session vs token · social/LINE link · roles — must be answered or explicit `n/a`
+- **Surfaces** — default `web-responsive` if unset; also pwa / line-oa / mobile-app as needed
 - **Architecture** — the pattern (Feature-Based by default) + the folder layout
-- **UX direction** — design system / tokens + the wireframe baseline (the frame)
+- **UX direction** — see STEP 5c Direction Picker when UI is in scope
 - **Data & integrations** — core data model + external services + their limits
-- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED)
+- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED) — recommend AUTO for PM-mode builds
 - **Estimation config** — unit · rate card · currency · contingency (if quoting)
+- **Timezone** — for delivery ETA dates (default `Asia/Bangkok` when project language is th)
 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.)
 
+### Direction Picker (when UI is in scope)
+
+5c. If the product has UI (default yes unless OVERVIEW says none):
+1. Copy `.issflow/templates/design/picker.html` → `docs/design/picker.html`.
+2. Fill placeholders only (names, swatches, fonts, blurbs, anti-patterns). Prefer
+   `ui-ux-pro-max` `--design-system` output; if Python 3 is missing, use the three
+   fallback presets in the template footer (Calm SaaS / Bold Commerce / Trust Fintech).
+   **Do not freehand redesign the HTML/CSS chrome.**
+3. SHOW me the picker path and STOP for choice (A/B/C).
+4. On choice: write `docs/design/DIRECTION.md` + `docs/design/tokens.css` from templates;
+   set STATE `design-direction: locked <id> <date>`; HISTORY line.
+5. Internal skip: only if UI truly out of scope — set `design-direction: n/a`.
+
 ### Plan
 
 6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
@@ -96,19 +112,33 @@ proceeds to the planner. (This is the planning confirmation gate.)
    - Start with Phase 0 (infra setup) only if infra is self-managed; with
      managed infra, Phase 0 is N/A and the plan starts at Phase 1.
    - End with a final code phase that contains the deploy task block.
+   - Tag each phase `size: S|M|L|XL` and `lane: lite|full` (lite only when no new
+     primary UI and not final/security-sensitive).
 
-7. Create docs/STATE.md:
+7. Create docs/STATE.md (keep ≤ ~25 lines at top; include delivery board):
 ```
-
 # STATE
 
 phase: 0 (pending)
 plan: PENDING
+design-direction: locked <id> <date> | PENDING | n/a
 design: PENDING
 architecture: PENDING
+surfaces: web-responsive
+timezone: Asia/Bangkok
+delivery:
+  package: bootstrap
+  agent_eta: none
+  phase_etas: []
+  status: WAITING_ON_HUMAN
+  waiting_for: plan approve
+  waiting_since: <ISO-date>
+  stale_after: <ISO-date+24h>
+  eta_paused: true
+  next_human_action: approve PLAN.md
+  slip_reason: none
 completed: project bootstrapped — design research done, double grill done
 blocker: none
-
 ```
 (For internal non-quoted work you may set `design: n/a` and `architecture: n/a`
 instead of PENDING so rule 15 does not block `/phase`.)
@@ -130,10 +160,17 @@ instead of PENDING so rule 15 does not block `/phase`.)
 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.**
+    **Plan-Ready checklist** (must pass before you ask me to approve):
+    - Every phase has testable acceptance (no vague “make it good”)
+    - No TBD on auth / money / PII / primary surfaces
+    - If UI in scope: `design-direction` locked (or n/a) and screen IDs listed or stubbed
+    - Phase dependencies clear; size + lane tags present
+    - Open risks listed — material open questions block approve
+
+    - SHOW me PLAN.md + Plan-Ready result. **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;
+      2. set `plan: approved <YYYY-MM-DD>` in docs/STATE.md; clear waiting_for / set delivery status AGENT_ACTIVE when build starts;
       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.
@@ -144,7 +181,9 @@ instead of PENDING so rule 15 does not block `/phase`.)
 
 Optional next steps (client / quoted work):
 1. `/propose` — proposal + estimate (asks rate in chat; client docs stay totals-only).
+   Screen appendix MUST use locked `docs/design/tokens.css` + screen IDs.
 2. `/design` — UX pack + architecture approve gates (hard rule 15) before `/phase`.
+   Upgrade existing frames — do not re-roll direction if locked.
 
 Internal or personal projects may skip `/propose` and set `design: n/a` /
 `architecture: n/a` in STATE, then go to `/phase`.

package/template/.issflow/commands/phase.md

@@ -1,15 +1,21 @@
 ---
-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 · "dry-run" to preview what the phase would do]
+description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Supports --lite. ETA + stuck/SLIP reporting required.
+argument-hint: [phase number · "lite" · "dry-run"]
 ---
 
 
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself.
+use native isolated workers when available; otherwise use sequential role passes
+per METHODOLOGY → Host capabilities and continuity.
+Speak to the human as **PM** (status / ETA / blockers).
 
 Note: subagents cannot talk to the user. Only YOU can.
 
-Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
+Target phase: $ARGUMENTS (default: next ready phase in the approved plan,
+reconciled with execution state; do not rely on stale status in a hashed plan).
+LANE: if args contain `lite` OR PLAN phase has `lane: lite` → LITE mode.
+  LITE forbidden when: final phase · new primary UI flow · auth/money/PII surface.
+  LITE still requires ETA + DoD + (if any UI touch) task check happy path.
 
 ---
 
@@ -24,7 +30,9 @@ run, commit, deploy nothing. (METHODOLOGY → Dry-run.)
 
 ## 0. PRE-FLIGHT
 
-a. PLAN-APPROVAL CHECK (hard rule 13): Read the docs/PLAN.md `> Approval:` header.
+a. PLAN-APPROVAL CHECK: apply METHODOLOGY → Plan-scoped approvals first: verify
+   ACTIVE-PLAN, exact revision/digest and allowed paths when present. A legacy
+   docs/PLAN.md `> Approval:` header is fallback only, never an override.
    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.
@@ -42,27 +50,57 @@ a2. DESIGN + ARCHITECTURE GATES (hard rule 15): Read `docs/STATE.md` for `design
 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.
+   Surface infra + auth status before any work. After bounded readiness retries,
+   blocked infra parks this phase; return control to a goal/sprint driver for
+   independent approved work. Never treat an unavailable service as tested.
 
 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.
+   - Same phase in-progress -> reconcile worktree, approval, and checkpoint
+     evidence before resuming STATE.md "next action"; retain retry counters.
+   - Different phase in-progress -> finish it first unless parked and the driver
+     selected this independently approved phase; preserve both checkpoints.
    - Out of dependency order -> AUTO: ignore the request and run the next pending
      phase in PLAN order. GUIDED: STOP, warn, proceed only if I confirm.
    - Phase not in PLAN.md -> STOP. Suggest /overview or /replan.
 
-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.
+d. FINAL PHASE CHECK: Reconcile the approved plan with execution state. Is this
+   the last planned phase? Record IS_FINAL_PHASE=true/false; earlier parked units
+   still block package completion even when this is the final phase.
+
+e. DELIVERY / ETA BOARD (required before RESEARCH):
+   Update `docs/STATE.md` `delivery:` block:
+   - First inspect any existing wait: while its gate remains unresolved, retain
+     WAITING_ON_HUMAN (or WAITING_STALE after `stale_after`), surface the next
+     human action, and park this unit. Resume AGENT_ACTIVE only when the gate is
+     resolved and execution actually starts; then clear resolved waiting fields.
+   - Set `agent_eta` and `phase_etas` using `flow-config.json` → `delivery.phaseHours`
+     by phase size (S/M/L/XL) and project timezone. Preserve the previous ETA
+     before recalculating so an overdue estimate is reported as SLIP, not hidden.
+   - Stage line: `stage: RESEARCH | next: … | blocker: none`
+   - Assumption budget: max `assumptionBudgetPerPhase` (default 3). Exceed → park
+     this unit for `/replan` or human; independent approved driver work may continue.
+   - If status was WAITING_ON_HUMAN and `stale_after` passed → set `WAITING_STALE`,
+     tell the human `next_human_action`, do not pretend AI is still building.
+   - If wall-clock past `agent_eta` while AGENT_ACTIVE → **SLIP**: report reason +
+     new ETA or BLOCKED. Never silently continue past ETA.
+
+f. LITE shortcuts (when LITE): skip dedicated researcher if unknowns are none;
+   skip browser E2E if no UI. Keep every applicable CLOSE gate, including regression,
+   endpoint coverage, lint, secrets, and UI task checks. LITE never waives approval,
+   evidence, retry, or security requirements. Full path otherwise.
 
 
 ---
 
 ## 1. RESEARCH + TDD APPLICABILITY
 
-Dispatch `researcher` in IMPL mode scoped to this phase.
+If LITE and no open unknowns: skip researcher; note "lite: research skipped" in STATE.
+Else dispatch `researcher` in IMPL mode scoped to this phase.
 Returns terse summary + path. Read the file only if needed.
-Unknowns block the phase -> re-dispatch narrowed. No guessing.
+Unknowns block the phase -> re-dispatch narrowed within the methodology retry
+budget, then park if unresolved. No guessing or unbounded research.
+After each major stage change, rewrite STATE `stage:` + one-line progress.
 
 SECURE SDLC (design): if this phase touches a TRUST BOUNDARY (auth, untrusted input,
 data store, money, PII), threat-model it now (`security` skill) and fold the abuse
@@ -114,13 +152,13 @@ NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
 
 ## 3c. TEST (e2e) — FRONTEND phases only
 
-If this phase ships UI: dispatch `e2e-runner` (BLIND) to write + run browser E2E
-for the slice using the declared E2E runner (it brings the test stack up/down
-itself). Then run the `ux-design` cookbook + wireframe check on the new UI
-(hard rule 9): the UI must match the wireframe frame and pass the cookbook
-(tokens, a11y/WCAG AA, states, breakpoints). A `ux-design` BLOCK is a GATE FAIL.
-Do not re-run `ui-ux-pro-max` `--design-system` here — the look is locked in the
-approved UX pack.
+If this phase ships UI:
+- FULL: dispatch `e2e-runner` (BLIND) for browser E2E of the slice.
+- LITE with UI touch: skip full E2E only if a **task check** still proves the
+  primary user job (scripted or manual-recorded happy path) — never skip both.
+- Always run the `ux-design` cookbook + wireframe check (hard rule 9). Tokens must
+  come from `docs/design/tokens.css` — raw hex/spacing in components = BLOCK.
+  Do not re-run `ui-ux-pro-max` `--design-system` here — look is locked.
 Non-frontend phase -> skip §3c.
 
 PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
@@ -133,8 +171,9 @@ PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
 
 Dispatch `implementer` (legacy mode) with phase spec + research summary.
 Returns STUCK -> go to ESCALATE.
-If IS_FINAL_PHASE: phase spec includes the deploy task; confirm the return
-includes "deployed URL" before proceeding.
+If IS_FINAL_PHASE: prepare the deploy task, but do not deploy without explicit
+release authorization. Record deployment as pending approval when not authorized;
+never require a fabricated deployed URL to advance local verification.
 
 ## 3N. TEST (blind)
 
@@ -145,7 +184,8 @@ spec — never reads the logic. (e2e-runner only if frontend.)
 
 ## GATE (both paths)
 
-PHASE GATE = current-phase REAL API suite passes AND (if frontend) E2E passes AND
+PHASE GATE = current-phase REAL API suite passes AND (if frontend: E2E passes
+OR the permitted LITE task check has recorded passing evidence) AND
 (if frontend) the `ux-design` cookbook + wireframe check passes AND the
 accumulated mock regression corpus stays green AND every docs/ENDPOINTS.md
 entry has a regression test (checked at CLOSE).
@@ -170,10 +210,11 @@ Dispatch `debugger` (isolated context) on the specific failure.
   (it is token-expensive); re-dispatch `debugger` with the findings, budget 3.
   STILL STUCK (or already spent this phase's unstuck): log the issue (root cause +
   every failed hypothesis) to ISSUES.md,
-  mark the slice `BLOCKED` in PLAN, and move to the next INDEPENDENT slice/phase.
-  Add it to the batched end-of-run report. HARD-STOP (pause for me) ONLY if no
-  independent work remains, or the blocker is on the hard-stop list
-  (security / irreversible / contradictory spec).
+  mark the slice `BLOCKED` in execution state without rewriting the approved plan,
+  then return to the goal/sprint driver for the next INDEPENDENT approved unit.
+  A standalone phase reports the blocker rather than starting unrelated work.
+  Hard stops park affected work and dependents; do not bypass them or halt safe
+  independent driver work. Retain attempt counts across resume.
 
 **GUIDED:**
   FIRST STUCK: STOP. Present the problem, 3 failed hypotheses, the debugger's
@@ -193,6 +234,13 @@ REGRESSION GATE (before closing — Feature 3):
 - IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
+UI TASK CHECK (if this phase touched UI — required even in LITE):
+- Happy path: primary user can complete the phase's user-visible job without guessing.
+- Viewport: primary breakpoint (≥MD) + <SM if mobile is primary.
+- Tokens: run `node .issflow/scripts/token-lint.js` to check unlisted hex/RGB colors.
+  Review semantic token usage and spacing separately; the script does not verify those.
+- Fail → FIX; do not close.
+
 CODE-STANDARDS GATE (rule 12): the formatter + linter are clean (the language's
 standard tool); names follow the language's own idiom; the code conforms to the
 declared architecture (Feature-Based by default). Lint/format errors or idiom
@@ -206,7 +254,13 @@ SECURITY GATE (rule 11 — Secure SDLC build stage):
 - Open HIGH/CRITICAL findings BLOCK the close -> route to FIX. Deploying to prod
   with open high/critical findings is a hard-stop (human sign-off).
 
-Mark phase `done` in docs/PLAN.md.
+Record phase `done` in execution state only if all required gates passed. Do not
+edit approval-hashed plan content for progress; pending deployment remains pending
+and prevents declaring a deployment-inclusive phase complete.
+DELIVERY UPDATE: only after all required gates pass, set this phase's
+`phase_etas` entry done; refresh the next ready phase's `agent_eta`. Set
+`delivery.status: DONE` only if the package is complete. Otherwise preserve
+WAITING/BLOCKED and its next action; clear only resolved waiting fields.
 
 SPRINT STANDUP (if a sprint is active — STATE.md shows `sprint: <n> (active)`):
 fire the `/sprint standup` tick — append the one-line standup to
@@ -239,27 +293,40 @@ IF IS_FINAL_PHASE — FINAL CLOSE sequence:
      - Full endpoint catalogue: docs/ENDPOINTS.md
      - Project history: docs/HISTORY.md
      ```
-  Tell me the project is complete and ready to use.
+  Use the PROJECT COMPLETE / READY TO USE wording only if every required unit,
+  check, and authorized deployment is actually complete. Otherwise report local
+  implementation verified, pending release/approval, blocked, or not run, with
+  evidence. Include only observed URLs and never include secret auth values.
 
 ELSE (not final phase):
 
   Run `/synthesize`.
-  Tell me phase done + the next phase. Recommend `/clear` then `/phase` next.
+  Report phase result + next approved phase. Under `/goal run` or `/sprint run`,
+  checkpoint and return to the driver to continue without routine confirmation.
+  A standalone `/phase` ends here; use a context reset only if the host supports it.
 
 ---
 
 ## STATE CHECKPOINTING
 
-After each step, update docs/STATE.md:
+After each step, checkpoint per METHODOLOGY → Execution contract (including
+approval digest, branch/base, evidence, attempts and remaining budget). Update
+docs/STATE.md without losing other lanes:
 ```
 
 phase: <n> (in progress)
 plan: approved <date>          ← carry forward; never drop the rule-13 sign-off record
 tdd: <true|false>
+stage: <RESEARCH|SCAFFOLD|RED|GREEN|TEST|FIX|CLOSE>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>
+delivery:                      ← preserve + update; never drop
+  agent_eta: <date>
+  status: AGENT_ACTIVE | WAITING_ON_HUMAN | WAITING_STALE | BLOCKED | SLIP | DONE
+  …
 
 ```
-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.
+Keep STATE.md small — overwrite, do not append. Preserve `plan:` and `delivery:`
+on every overwrite. When entering WAITING_ON_HUMAN: set waiting_for, waiting_since,
+stale_after (configured `delivery.staleAfterHours`, default 24h), eta_paused: true, next_human_action (one sentence).

package/template/.issflow/commands/propose.md

@@ -24,6 +24,11 @@ and its `> Approval:` header still reads `PENDING` (or is missing), STOP and rou
 to the `/overview` PLAN-APPROVAL gate before quoting — pricing an unapproved plan
 re-prices on every revision.
 
+DIRECTION CHECK (UI in scope): STATE `design-direction:` must be `locked …` (or
+explicit `n/a` if no UI). Still PENDING → STOP and run overview STEP 5c Direction
+Picker first. Screen appendix must use `docs/design/tokens.css` colors — never invent
+a parallel palette.
+
 ## 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
@@ -32,9 +37,15 @@ prevents silent scope creep (and grounds change-order re-pricing later).
 ## STEP 2 — PHASE BREAKDOWN (internal)
 Derive the vertical-slice phases (or read `docs/PLAN.md` if it exists). Size each:
 - complexity: **S | M | L | XL**
-- effort: an ideal-days RANGE (e.g. 2–3d), + story points if your team uses them
+- **scope_effort** (axis A): ideal-days RANGE for commercial value (human-equivalent)
+- **agent_delivery** (axis B): agent-active hours/days from `flow-config.json` →
+  `delivery.phaseHours` (S/M/L/XL) — wall-clock when AI may work, **excluding**
+  waiting-on-human gates
 - risk / unknowns: what could move the estimate
 
+Show **both axes in chat to the human** every time. Client price uses **A only**.
+Client timeline may show B as “AI-assisted delivery (if approvals are timely)”.
+
 Keep this sizing for the **chat math**. Do **not** dump every PLAN phase onto the
 client table — collapse into packages in STEP 5.
 
@@ -109,9 +120,12 @@ production is up within the scope on this quote. **Never** construction wording
 ## Scope        — in-scope: … | out-of-scope: …
 ## Packages     — table: package | cost
                 — or package | estimated | billed | cost  (only if hours columns requested)
-## Total        — <low>–<high>   ← totals only; no “incl. X% contingency”
-## Timeline     — <estimate>, dependency order
-## Assumptions  — …
+## Delivery clocks (internal + chat; client page may show demo dates only)
+                — per package: scope_effort (A · pricing) | agent_delivery (B · agent-active)
+                  | demo_by (calendar, assuming human gates ≤ staleAfterHours)
+## Total        — <low>–<high>   ← totals only from A; no “incl. X% contingency”
+## Timeline     — demo_by per package + dependency order (B pauses while waiting on humans)
+## Assumptions  — … (if human gates slower than SLA, demo_by slips — not an agent hang)
 ## Exclusions   — … (hosting/database: client pays provider, if that was the answer)
 ## Payment      — software delivery events + the asked split (if any)
 ## Screens      — docs/proposal.html pages 2–N (or “none — no UI in scope”)
@@ -149,14 +163,18 @@ production is up within the scope on this quote. **Never** construction wording
    **Screen appendix (required when UI is in scope)** — same `docs/proposal.html`,
    not a second signable file. After page 1's page-break, emit `.sheet.screens`
    into `{{SCREEN_SHEETS}}`:
-   - Build frames from **PLAN + OVERVIEW** modules/capabilities (empty chrome is
-     fine). Do **not** wait for UX-PACK (that gate is after sign-off).
+   - Build frames from **PLAN + OVERVIEW** with stable **screen IDs** (`S-01`…).
+   - Apply locked **token colors** from `docs/design/tokens.css` into the template
+     CSS variables / inline token slots — same direction the build will use.
    - Cover **every** in-scope module and capability — not a 4–8 frame sampler.
    - Group sheets by package; module bar on each sheet; numbered short captions
      under frames.
-   - Label: not pixel-binding. Sign on page 1 only. **No emoji as icons.**
+   - Label: structure-binding via screen IDs; visuals follow locked direction (still
+     not pixel-perfect). Sign on page 1 only. **No emoji as icons.**
    - Use the template's desk/phone/sidebar/card/table CSS. Do not invent a
      parallel stylesheet.
+   - Per package row (internal + chat): `scope_effort` · `agent_delivery` ·
+     `demo_by` (calendar date assuming human gates answer within staleAfterHours).
 
    Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep PROPOSAL.md and proposal.html
    in sync.

package/template/.issflow/commands/quick.md

@@ -25,15 +25,27 @@ Steps:
    understand it · file(s) you'll touch · blast radius — and WAIT for my confirm.
    One cheap turn beats redoing a misunderstood edit. (Already confirmed in this
    conversation? say so and proceed — don't re-ask the same understanding.)
-1. grep docs/ISSUES.md for anything related.
+1. Verify applicable plan revision/digest and allowed paths per METHODOLOGY →
+   Plan-scoped approvals; intake confirmation alone cannot override that gate.
+   grep docs/ISSUES.md for anything related.
+1b. If the change touches UI: read `docs/design/tokens.css` + inventory when present.
+    Use semantic tokens only — no raw hex/spacing literals in components.
 2. Make the change. Smallest diff that works.
 3. Run it — lint/typecheck/smoke. Show me result.
 4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). No corpus in this
    repo? run the project's own test suite instead (or the touched area's tests).
-   A break BLOCKS the `/quick` — surface it to me and stop. No agent chain is added.
-5. Error you cannot fix in 2 tries -> STOP. Recommend `/phase`.
+   A break blocks completion, not the first repair attempt: fix within the approved
+   scope and rerun the failed check plus regression, using the two-try budget below.
+   No agent chain is added.
+5. Error you cannot fix in 2 tries -> park this unit with failed hypotheses,
+   evidence, and the next action. Recommend `/phase`; do not expand scope or
+   reset the budget automatically. Under an approved goal, return the blocker
+   to its driver so independent units can continue.
 6. Change revealed a bug -> `/log-issue`.
 7. ARCHITECTURE SELF-CHECK: touched an agent, hook, command, or workflow rule?
    YES -> `/log-decision`.
 
-No STATE.md rewrite, no synthesize, no /clear needed.
+No full STATE.md rewrite, synthesize, or /clear needed. If interrupted or blocked,
+leave a minimal checkpoint (scope, diff, tests, attempts, next action) per the
+methodology Execution contract; preserve existing state. Report done only after
+required checks pass, otherwise blocked/not run with evidence.

package/template/.issflow/commands/sprint.md

@@ -50,7 +50,9 @@ velocity table). Create `docs/sprints/` if absent. STATE.md carries the active s
 =====================================================================
 ## §1 — SPRINT PLANNING  (ceremony)
 
-Pre: `docs/PLAN.md` exists AND its `> Approval:` header reads `approved …` (the
+Pre: verify the active plan revision/digest and allowed paths per METHODOLOGY →
+Plan-scoped approvals. For legacy plans only, `docs/PLAN.md` exists AND its
+`> Approval:` header reads `approved …` (the
 PLAN-APPROVAL gate, hard rule 13). Still `PENDING` / missing → STOP, route to the
 `/overview` plan-approval gate. A sprint only SLICES an already-signed-off plan.
 
@@ -58,7 +60,7 @@ a. **Estimate (one-time, lazy).** Every pending PLAN phase needs a points estima
    (Fibonacci `1 2 3 5 8`, relative effort from the phase `slice` + `acceptance`
    size; a phase that feels `>8` is too big — note it for `/replan` to split). If the
    planner already wrote `[N pts]` tags, reuse them; otherwise assign now and write
-   them back into PLAN.md next to each phase header.
+   them into the sprint artifact, leaving the approved plan unchanged.
 
 b. **Capacity.** Read `docs/sprints/VELOCITY.md`.
    - Have history → capacity = rolling-average completed velocity (last ≤3 sprints).
@@ -73,7 +75,8 @@ c. **Commit.** Walk the PLAN in dependency order, pull pending phases into this
 
 d. **Write** `docs/sprints/sprint-<n>.md` from the template below; set
    `status: active`; seed the burndown tick 0 = total committed points. Group the
-   committed phases under a `## Sprint <n>` header in PLAN.md if not already grouped.
+   committed phases in the sprint artifact, referencing the immutable approved
+   plan revision. Do not add sprint headers to approval-hashed PLAN content.
    Update STATE.md: `sprint: <n> (active)`.
 
 AUTO: auto-commit the computed backlog, log the goal + points + capacity, continue.
@@ -136,7 +139,8 @@ Inspect-and-adapt on the PROCESS, not the product. Write the `## Retro` block:
 - **estimate accuracy** — committed vs completed points; note phases that blew their
   estimate so the next sprint's poker is calibrated.
 
-AUTO: auto-apply the routed actions (log/replan) and continue. GUIDED: list actions,
+AUTO: auto-apply in-scope logging/process actions and continue. A replan is a
+proposal requiring the plan gate, not permission to change approved scope. GUIDED: list actions,
 confirm before applying.
 
 =====================================================================
@@ -156,11 +160,13 @@ d. Update STATE.md: clear the active sprint (or set the next one if `/sprint run
 =====================================================================
 ## §RUN — AUTO END-TO-END DRIVER  (the headline: "do all the process automatically")
 
-`/sprint run [n]` drives one full sprint — or, if you keep going, every remaining
-sprint until the PLAN is exhausted — with NO human stop except a hard-stop:
+`/sprint run [n]` drives the requested approved sprint scope. Continue across
+sprints only when that scope was authorized. Establish finite unit/retry budgets
+before execution using the methodology Execution contract; preserve them on resume.
+Routine phase and ceremony boundaries need no new confirmation:
 
 ```
-loop while pending phases remain in PLAN.md:
+loop while approved, dependency-ready units remain and run budget permits:
   1. §1 PLANNING            → commit the next sprint from PLAN + velocity
   2. for each committed phase, in dependency order:
        run /phase <p>       → the full build loop (its own gates + circuit breaker)
@@ -170,11 +176,14 @@ loop while pending phases remain in PLAN.md:
   3. §3 REVIEW              → demo + boundary audits (fix blockers, re-audit)
   4. §4 RETRO               → routed actions, applied
   5. §5 CLOSE              → velocity + carry-forward + HISTORY
-  6. /synthesize → suggest /clear  (token reset at the sprint boundary, like a phase)
-  AUTO: start the next sprint automatically.  GUIDED: stop, report, wait.
-HARD-STOP at any point: deploy/irreversible/outbound action, security-sensitive
-change, contradictory spec, or debug budget spent with no independent slice left →
-pause, surface the consolidated report, hand to the human.
+  6. /synthesize → checkpoint evidence, attempts, remaining budget and next action
+     (reset context only with a supported host mechanism; preserve resume state)
+  AUTO: start the next sprint only within the authorized run scope and budget.
+  GUIDED: stop, report, wait.
+HARD-STOP: park the affected action and its dependents; continue only safe,
+independently approved work. Stop the run for exhausted budget, a run-wide blocker,
+or no actionable units. Never recycle a blocked phase into the next sprint without
+new evidence or a resolved prerequisite. Report partial completion truthfully.
 ```
 
 When the last PLAN phase is `accepted`, the build is sprint-complete → recommend

package/template/.issflow/commands/synthesize.md

@@ -6,21 +6,25 @@ Caveman ULTRA mode.
 
 Trigger: end of a phase, or any time STATE.md / ISSUES.md feel bloated.
 
-Dispatch the `synthesizer` subagent.
+Dispatch the `synthesizer` subagent when supported; otherwise run its checklist
+sequentially per METHODOLOGY → Host capabilities and continuity. Preserve every
+active/parked lane checkpoint, evidence record, approval digest, and retry budget.
 
 For a normal phase: it rewrites STATE.md, dedups ISSUES.md, prunes snapshots,
 appends to HISTORY.md.
 
 For the FINAL phase (no further pending phases): also pass the signal
 "FINAL PHASE" so the synthesizer runs the extended pass — updating OVERVIEW.md
-and README.md to reflect the completed project state.
+and README.md to reflect the verified project state, including any pending
+deployment or blocked work. Last phase does not imply completed project.
 
-To determine if this is the final phase: read docs/PLAN.md. If no phases remain
-with status "pending" after the current one, it is the final phase.
+To determine if this is the final phase, reconcile the approved plan with execution
+state. Do not edit approval-hashed plan content to track completion.
 
-When synthesizer returns "safe to /clear: yes", tell me:
+When synthesizer confirms durable checkpoints are safe for a context reset, report:
 - before/after line counts
 - whether the final-pass ran
-- that I can now run /clear (or proceed to the endpoint summary if final phase)
+- next action; under a goal/sprint driver, return control and continue approved work
+- reset only if the host supports it and it is needed; otherwise use the checkpoint
 
 If it returns anything unsafe, show me what and stop.

package/template/.issflow/flow-config.json

@@ -1,12 +1,19 @@
 {
   "context": {
     "window": 1000000,
-    "warnPct": 60,
-    "gatePct": 78,
-    "_note": "window = this session's real context window. THIS repo runs Opus 4.8 [1m] but the transcript records model id as 'claude-opus-4-8' (no [1m] tag), so auto-detect (window:0) would wrongly assume 200000 and false-gate around 156k. Set it explicitly here. Kit template default stays 200000 — override per your model. warnPct = soft non-blocking nudge. gatePct = hard PreToolUse block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths (docs/**, STATE/ISSUES/snapshots) and all Bash (git) are never blocked; Task delegation is never gated (a subagent isolates noise and shrinks orchestrator context)."
+    "warnPct": 55,
+    "gatePct": 70,
+    "injectMaxLines": 25,
+    "_note": "window = session context. Template default for new installs should be 200000 unless overridden. warnPct soft nudge; gatePct hard block on NEW source Edit/Write. Prefer /synthesize + /clear (handoff) over compact near gate. Checkpoint docs/** never gated."
+  },
+  "delivery": {
+    "staleAfterHours": 24,
+    "phaseHours": { "S": 2, "M": 4, "L": 8, "XL": 16 },
+    "assumptionBudgetPerPhase": 3,
+    "_note": "Agent-active ETA uses phaseHours by size tag. Waiting-on-human pauses ETA; after staleAfterHours status becomes WAITING_STALE."
   },
   "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 this block is absent."
+    "_note": "Sprint layer (/sprint). defaultCapacity = points for first sprint before velocity exists."
   }
 }

package/template/.issflow/hooks/pre-compact.js

@@ -18,12 +18,16 @@ const stamp = `${d.getFullYear()}${p2(d.getMonth() + 1)}${p2(d.getDate())}-${p2(
 const snap = path.join('docs/.snapshots', `precompact-${stamp}.md`);
 
 const state = read('docs/STATE.md');
+const workflow = read('docs/WORKFLOW.json');
 const body = [
   `# Pre-compact snapshot ${stamp}`, '',
   '## Git',
   sh('git status --short').replace(/\n+$/, ''),
   sh('git diff --stat').replace(/\n+$/, ''),
   '',
+  '## Durable workflow checkpoint',
+  workflow === null ? '(no docs/WORKFLOW.json)' : 'Resume from docs/WORKFLOW.json; reconcile running tasks before retrying. This snapshot is not an approval or a replacement checkpoint.',
+  '',
   '## STATE.md at compact time',
   state !== null ? state.replace(/\n$/, '') : '(no STATE.md)',
   '',