create-issflow 1.11.1 → 1.12.0

package/bin/cli.js

@@ -22,7 +22,7 @@ const toolArg = (argv.find(a => a.startsWith('--tool=')) || '').split('=')[1];
 
 const TOOLS = {
   claude: 'Claude Code (Anthropic) — full: subagents, lifecycle hooks, skills',
-  codex:  'OpenAI Codex CLI — AGENTS.md native; subagents/skills as readable files',
+  codex:  'OpenAI Codex — AGENTS.md; use native tools only when available',
   cursor: 'Cursor — .cursor/rules + commands + hooks; kit stays in .issflow/ (no .claude/)',
   gemini: 'Google Gemini CLI — GEMINI.md pointer; commands/skills as readable files',
   aider:  'Aider — .aider.conf.yml loads the methodology as conventions',
@@ -124,7 +124,7 @@ function adapterClaude() {
   if (conflicts > c0) warnings.push('claude: you already keep a CLAUDE.md — ours was written as CLAUDE.md.issflow-new. Add a line `@AGENTS.md` to your CLAUDE.md so the methodology auto-loads.');
   materializeClaudeMirror();
   const HOOKS = {
-    SessionStart: [{ matcher: 'startup|clear|compact', hooks: [{ type: 'command', command: 'node .issflow/hooks/session-start.js' }] }],
+    SessionStart: [{ matcher: 'startup|resume|clear|compact', hooks: [{ type: 'command', command: 'node .issflow/hooks/session-start.js' }] }],
     PreToolUse:   [{ matcher: '*',                     hooks: [{ type: 'command', command: 'node .issflow/hooks/context-guard.js' }] },
                    { matcher: 'Edit|Write|MultiEdit|NotebookEdit', hooks: [{ type: 'command', command: 'node .issflow/hooks/plan-gate.js' }] }],
     PreCompact:   [{ matcher: 'auto|manual',           hooks: [{ type: 'command', command: 'node .issflow/hooks/pre-compact.js' }] }],
@@ -144,7 +144,7 @@ function adapterClaude() {
 }
 
 function adapterCodex() {
-  warnings.push('codex: AGENTS.md is read natively. Lifecycle hooks unsupported (rituals model-run); subagents in .issflow/agents/ are read as reference, not isolated contexts.');
+  warnings.push('codex: this installer configures AGENTS.md, not lifecycle hooks or subagent registration. Detect native delegation in the current host; otherwise run roles serially. Run checkpoint and verification commands explicitly.');
 }
 
 function adapterCursor() {
@@ -152,7 +152,7 @@ function adapterCursor() {
     '---', 'description: iStartSoftFlow workflow — always apply', 'alwaysApply: true', '---', '',
     'Run the **iStartSoftFlow** workflow. The full, single-source methodology is',
     '`.issflow/istartsoft-flow/METHODOLOGY.md` — read it before acting. Roles live in',
-    '`.issflow/agents/` (Cursor reads them natively); procedures in `.cursor/commands/`',
+    '`.issflow/agents/` (role references, not registered native agents); procedures in `.cursor/commands/`',
     '(mirror of `.issflow/commands/`). Caveman ULTRA mode; apply the `karpathy-guidelines`',
     'and `ux-design` skills. See `AGENTS.md` for the role/command/skill map.', '',
   ].join('\n'));
@@ -164,7 +164,7 @@ function adapterCursor() {
     '3. Past `agent_eta` while AGENT_ACTIVE → report SLIP; do not silent-continue.',
     '4. WAITING_ON_HUMAN / WAITING_STALE → do not pretend the agent is still building.',
     '5. UI work: locked `design-direction` / `docs/design/tokens.css` — no freehand palette.',
-    '6. Near context gate → `/synthesize` (keep delivery:) + `/clear`, prefer over compact.',
+    '6. Near context gate → checkpoint with `/synthesize` (keep delivery:); use only reset capabilities the host exposes.',
     '',
     'Talk to the human as PM/SA. Subagents never address the user.',
     '',
@@ -177,7 +177,7 @@ function adapterCursor() {
       subagentStop: [{ command: 'node .issflow/hooks/subagent-stop.js' }],
     },
   }, null, 2) + '\n');
-  warnings.push('cursor: PreCompact has no Cursor equivalent (snapshot ritual degrades to model-run); plan-gate/context-guard are Claude-strongest — Cursor relies on issflow-gates.mdc + Tier A sessionStart. Verify hooks.json against cursor.com/docs/hooks.');
+  warnings.push('cursor: only sessionStart and subagentStop hooks are configured here; no edit/stop approval enforcement. Verify host hook support. Run checkpoint and verification commands explicitly; role files do not register subagents.');
 }
 
 function adapterGemini() {
@@ -243,28 +243,25 @@ function agentsMd() {
     'caveman · grill-me · karpathy-guidelines · ux-design · ui-ux-pro-max · security ·',
     'code-standards · support-triage', '',
     '## Autonomy', '',
-    'Planning (`/overview` grill + plan approval) always asks — that input is cheap.',
+    'Use existing approval for the same scope; ask only for missing approval or material changes.',
     '**AUTO (default)** governs the DEV loop: follow the plan, decide + log + continue,',
     'do NOT stop to ask. Hard-stops only: security · irreversible/outbound actions · a',
     'contradictory spec. Blockers are parked + reported at the phase boundary, not',
     'mid-flow. **GUIDED** asks at each fork in dev too. Declare the mode in',
-    '`docs/OVERVIEW.md`. See METHODOLOGY → Autonomy.', '',
+    '`docs/OVERVIEW.md`. See METHODOLOGY → Autonomy.',
+    'Optional durable task state: `.issflow/runtime/workflow.js` (see `.issflow/runtime/README.md`).',
+    'This local state helper does not execute agents or schedule future sessions.', '',
     '## Hard-rule index (full text in METHODOLOGY.md)', '',
     '1–12 as in METHODOLOGY · 13 PLAN-APPROVAL · 14 UNDERSTAND-FIRST ·',
     '15 DESIGN + ARCHITECTURE gates (after proposal, before `/phase`; internal may n/a).', '',
+    '## Host capability', '',
+    'See `.issflow/runtime/HOSTS.md` for actual adapter enforcement and fallbacks.',
+    'Cursor gate rules are model-run guidance, not lifecycle enforcement.',
+    'Model guidance: `.issflow/models/MODEL-MATRIX.md`; delivery ETA: `docs/STATE.md`.', '',
     '## Your stack', '',
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
     'stack* and hardcodes none.', '',
-    '## Host capability (enforcement)', '',
-    '| Host | Hooks | Notes |',
-    '|------|-------|-------|',
-    '| Claude Code | Full (SessionStart · PreToolUse · PreCompact · Stop) | Strongest plan-gate + context-guard |',
-    '| Cursor | sessionStart + subagentStop + `.cursor/rules` | Partial — model-run gates via `issflow-gates.mdc` |',
-    '| Codex / Gemini / Aider | model-run rituals | Run SESSION-OPEN Tier A by hand |',
-    '',
-    'You talk as **PM/SA**. Subagents never chat with you. Delivery ETA lives in',
-    '`docs/STATE.md` (`delivery:`). See `.issflow/models/MODEL-MATRIX.md` for model tips.', '',
   ].join('\n');
 }
 
@@ -356,10 +353,15 @@ function main() {
   const gi = path.join(CWD, '.gitignore');
   if (fs.existsSync(gi)) {
     const txt = fs.readFileSync(gi, 'utf8');
-    if (/^\.issflow\/\*\s*$/m.test(txt) && !txt.includes('!.issflow/agents/')) {
-      const block = '\n# iStartSoftFlow workflow — track as project config\n!.issflow/agents/\n!.issflow/commands/\n!.issflow/skills/\n!.issflow/hooks/\n!.issflow/istartsoft-flow/\n';
-      log('  + .gitignore: un-ignore .issflow workflow dirs');
-      if (!DRY) fs.appendFileSync(gi, block);
+    if (/^\.issflow\/\*\s*$/m.test(txt)) {
+      const tracked = ['agents', 'commands', 'skills', 'hooks', 'runtime', 'routing', 'models', 'scripts', 'templates', 'istartsoft-flow'];
+      const lines = new Set(txt.split(/\r?\n/).map(line => line.trim()));
+      const missing = tracked.map(dir => `!.issflow/${dir}/`).filter(line => !lines.has(line));
+      if (missing.length) {
+        const block = '\n# iStartSoftFlow workflow — track as project config\n' + missing.join('\n') + '\n';
+        log('  + .gitignore: un-ignore missing .issflow workflow dirs');
+        if (!DRY) fs.appendFileSync(gi, block);
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.11.1",
+  "version": "1.12.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/.issflow/README.md

@@ -12,7 +12,7 @@ This directory is the **portable workflow kit** (tool-agnostic). Every
 
 | Path | What |
 |------|------|
-| `agents/` | Fresh-context workers (planner, researcher, implementer, …) |
+| `agents/` | Role definitions (isolated workers only where the host supports them) |
 | `commands/` | Procedures — Default: `/overview` `/feature` `/quick`; Advanced: `/propose` `/design` `/support` … |
 | `skills/` | On-demand cookbooks (ux-design, ui-ux-pro-max, security, support-triage, …) |
 | `hooks/` | Lifecycle enforcement scripts |
@@ -37,3 +37,6 @@ Do **not** duplicate METHODOLOGY rules into other files (anti-drift).
 Do **not** put personal rate cards in this kit.
 
 Installer: `npx create-issflow` (omit `--tool` = all adapters).
+
+Local task checkpoints: [runtime/README.md](runtime/README.md).
+Host capabilities and smoke checks: [runtime/HOSTS.md](runtime/HOSTS.md).

package/template/.issflow/agents/planner.md

@@ -7,7 +7,10 @@ model: inherit
 
 You are the PLANNER. Caveman ULTRA mode.
 
-Job: convert FINDINGS + OVERVIEW.md into an ordered phase plan. You only write docs/PLAN.md.
+Job: convert FINDINGS + OVERVIEW.md into an ordered phase plan. Write only the
+assigned plan artifact: `docs/plans/PLAN-<id>.md` for new scoped work, or
+`docs/PLAN.md` for a deliberate legacy workflow. Follow Plan-scoped approvals;
+never mutate an approved revision for execution progress or self-approve it.
 
 Hard rules:
 - PHASE 0 = INFRA, and it is CONDITIONAL on the infra declared in OVERVIEW.md:
@@ -60,7 +63,9 @@ MUST contain a deployment task block:
 
 ```
 This is non-negotiable. Deployment is always in the last phase, never a separate
-phase of its own, and never omitted.
+phase of its own, and never omitted. This plans deployment; it does not authorize
+execution. Explicit release authorization and required checks must precede deploy.
+Until then, record deployment pending in execution state, never invent success.
 
 docs/PLAN.md format:
 ```

package/template/.issflow/agents/synthesizer.md

@@ -26,7 +26,10 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
    `delivery:` block** (agent_eta / status / waiting_* / slip) — load-bearing for
    finish-date honesty. Also preserve `design-direction:`, `design:`, `architecture:`,
    `surfaces:`, `timezone:` when present.
-   Target: under ~30 lines including delivery.
+   Preserve all active and parked lane checkpoints, approval digests, branch/base,
+   evidence paths/results, attempt counts and remaining budgets, or verified links
+   to their durable execution records. Never reset counters or erase blocked lanes.
+   Target: under ~30 lines including delivery; correctness beats this size target.
 
 2. ISSUES.md — dedup + compress:
    - merge duplicate / near-duplicate issues.
@@ -37,14 +40,17 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
 3. docs/.snapshots/ — delete precompact snapshots older than the newest 3.
 
 4. Append a single dated line to docs/HISTORY.md:
-   `YYYY-MM-DD phase <n> done - <one line>`
+   `YYYY-MM-DD phase <n> <verified status> - <one line>`
+   Use done only when all required gates and deployment obligations are verified.
 
 ---
 
 ## Final-phase extended pass
 
 The orchestrator will tell you when this is the final phase (no further pending
-phases remain in PLAN.md). When told, ALSO do:
+phases remain in the reconciled execution state). When told, ALSO do:
+Never infer completion from being the last phase. If required gates or deployment
+remain pending/blocked, describe that actual status instead of the done template.
 
 5. Update docs/OVERVIEW.md — append a "## Final state" section:
 ```
@@ -64,7 +70,8 @@ vs the original estimate (PROPOSAL.md v1 total → final total after approved CR
 This is the client closeout — the one-page record of the whole engagement.
 6. Update README.md (the project-level README, not the iStartSoftFlow README) — if a
 project README exists at the repo root, update or append:
-- Current status: "Production — deployed at <URL>"
+- Current status: verified implementation/release status. Use "Production — deployed
+  at <URL>" only with observed successful deployment evidence; never invent a URL.
 - Brief description of what was built (from OVERVIEW.md summary)
 - Link to docs/ENDPOINTS.md for the API surface
 If no project README exists, note this in the return and skip.
@@ -78,6 +85,6 @@ SYNTHESIZED
 - ISSUES.md: <old> -> <new>, merged <k>, archived <m>
 - snapshots pruned: <count>
 - final pass: <yes — OVERVIEW.md + README.md updated | no>
-- safe to /clear: yes
+- safe to reset context: <yes only if all checkpoints are durable | no — reason>
 
 ```

package/template/.issflow/commands/feature.md

@@ -4,10 +4,11 @@ argument-hint: [path to Feature doc, e.g. docs/features/<slug>/FEATURE.md · "dr
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself. Speak PM-style (ETA / stage / WAITING /
-DONE). Subagents cannot talk to the user; only YOU can.
+use native isolated workers when available; otherwise use sequential role passes
+per METHODOLOGY → Host capabilities and continuity. Only YOU report to the user.
+Speak PM-style (ETA / stage / WAITING / DONE).
 
-Before build slices: set STATE `delivery:` agent_eta from phase sizes; heartbeat
+Before build slices: set STATE `delivery:` agent_eta from phase sizes; update
 stage lines; on human gates set WAITING_ON_HUMAN + waiting_since + stale_after.
 UI work must respect `docs/design/tokens.css` + inventory when present.
 
@@ -33,7 +34,8 @@ Target doc: $ARGUMENTS  (default: the single `docs/features/*/FEATURE.md` whose
 HEADLESS DETECT: env `ISSFLOW_HEADLESS=1` (set by the CI workflow / Docker runner)
 means NO human is available this run. Every hard-stop below then degrades to:
 write the blocker to `docs/features/<slug>/BLOCKED.md` + mark the gate `parked`
-+ EXIT cleanly with a report. Never guess through a hard-stop.
++ return this lane as blocked with a report. A goal driver may continue independent
+approved units; a standalone feature run exits. Never guess through a hard-stop.
 
 ---
 
@@ -56,12 +58,16 @@ b. APPROVAL GATE (the ONE human gate at entry): the Feature doc must carry a hea
    ```
    Missing/PENDING -> HARD-STOP: a human approves the DOC, not the run (need a doc?
    `/feature new <name>` scaffolds `.issflow/templates/FEATURE-template.md`). Doc approval
-   is the rule-13 sign-off *scoped to this doc only* — the mini-plan it produces
-   inherits approval as long as it stays inside the doc's stated scope.
+   confirms intake *scoped to this doc only*. Also apply METHODOLOGY → Plan-scoped
+   approvals: verify the active plan revision/digest and file boundaries before
+   implementation. A feature header does not override a missing or invalid plan
+   approval. Routine breakdown within the approved plan needs no new confirmation.
 
 c. WORKSPACE: slug = kebab-case of the doc's title. Ensure
    `docs/features/<slug>/FEATURE.md` (move the doc there if given elsewhere).
-   Write `docs/features/<slug>/GATES.md` — the gate checklist, all unchecked:
+   On a new run, write `docs/features/<slug>/GATES.md`, all unchecked. On resume,
+   reconcile the existing checklist with actual diff/test evidence, approval,
+   and saved attempts; do not erase progress or trust stale checkmarks:
    ```
    # GATES — <slug>
    - [ ] spec-complete
@@ -91,9 +97,10 @@ d. STATE + BRANCH: `docs/STATE.md` gets `feature: <slug> (active)`. Work on
 
 Dispatch `researcher` (IMPL mode) scoped to the doc: which modules/files the
 feature touches, which dependencies + versions are involved, what the doc leaves
-unstated. Fill every gap with the most reasonable interpretation and log each one
-under `## Assumptions` in FEATURE.md (AUTO decision protocol — decide + log +
-continue). Check gate `spec-complete`.
+unstated. Resolve routine details within approved scope and record assumptions
+in execution notes (not an approval-hashed artifact). Material requirement gaps
+require approval. Continue without re-confirming routine choices. Check gate
+`spec-complete` only when the specification is sufficient.
 
 ## 2. ADVERSARIAL DOC-REVIEW (before planning)
 
@@ -104,7 +111,8 @@ Dispatch TWO reviewers in parallel, each told to ATTACK the doc, not summarize i
   data store, money, PII)? If yes, threat-model it now (`security` skill) and fold
   abuse cases into the acceptance criteria as negative cases.
 
-Merge findings into FEATURE.md `## Acceptance criteria` (positive + negative).
+Record findings and derived test cases in execution notes. Do not silently
+rewrite approved acceptance criteria; material changes require renewed approval.
 Internally CONTRADICTORY spec -> HARD-STOP (methodology hard-stop 3). Merely
 incomplete -> fill + log. Check gate `adversarial-doc-review`.
 
@@ -135,13 +143,16 @@ For each slice in `docs/features/<slug>/PLAN.md`, in order:
   implementation) -> GREEN (`implementer`) -> e2e (`e2e-runner`) when the slice has
   a user-facing flow. Non-TDD slice: IMPLEMENT -> TEST.
 - Debug circuit breaker: WARN at 2, cap 3, `/unstuck` once per slice; still stuck
-  -> park the slice (BLOCKED in the feature PLAN) + continue to the next
+  -> park the slice (BLOCKED in execution state) + continue to the next
   independent slice. Blockers batch-report at the end, never mid-flow.
 - Rule 11 (secure coding + SAST/SCA/secrets) and rule 12 (lint/format/naming/
   architecture) apply per slice as in `/phase`.
 - `implementer` updates `docs/ENDPOINTS.md` as surfaces land.
 
 All slices done + full feature suite green -> check gate `build-green`.
+If required slices remain blocked, keep this gate unchecked. Independent review,
+documentation, and test-plan preparation may continue, but delivery and done status
+remain blocked. Checkpoint evidence, attempts, and next actions after each step.
 
 ## 6. REVIEW & HARDEN (adversarial + self-review)
 
@@ -174,7 +185,7 @@ a. Documentation update: `docs/ENDPOINTS.md` final pass; README/docs deltas the
 b. Token stamp — append to FEATURE.md:
    ```
    ## Token stamp
-   context: ~<pct>% of window · subagents: <n> · slices: <n> · debug rounds: <n>
+   context: <observed value or unavailable> · subagents: <actual n> · slices: <n> · debug rounds: <n>
    ```
    Check gate `token-stamp`.
 c. Summary — append to FEATURE.md `## Summary`: what shipped, assumptions made,
@@ -184,11 +195,15 @@ d. Memory update — append wisdom candidates (resolved issues, reusable finding
    to `docs/WISDOM-QUEUE.md`. The QUEUE is local + automatic; pushing to the
    shared KB stays human (`/store-wisdom` reads the queue). Check gate `memory-queued`.
 
-Then: STATE.md -> `feature: <slug> (done)`.
+Only when every required gate is verified: STATE.md -> `feature: <slug> (done)`.
+Otherwise preserve parked/pending status and report exactly what remains unverified.
 
 ## 9. DELIVERY
 
-Commit the feature branch (clear message per slice or one squashed commit).
+Only deliver after required gates pass. Commit the feature branch only when
+allowed by the user's scope (clear message per slice or one squashed commit).
+A no-commit/no-push instruction overrides delivery defaults. An Automation header
+must reflect actual human consent, never an agent-authored permission upgrade.
 Then by the doc's `> Automation:` header:
 - `none` (default) -> STOP here. Show the human: branch name, summary, TEST-PLAN
   path. Push is theirs (methodology hard-stop 1).

package/template/.issflow/commands/goal.md

@@ -38,25 +38,34 @@ and STOPS. `/goal set` always stops at the confirmation gate anyway.
 
 LOOP — repeat until a stop condition:
 1. PICK the next actionable unit, in this order:
-   a. an in-progress unit in STATE (finish what is started)
+   a. an in-progress, unblocked unit in STATE (finish what is started)
    b. an APPROVED, pending `docs/features/*/FEATURE.md` that advances the goal
    c. the next pending PLAN phase that advances the goal (plan must be approved — rule 13)
    d. an open ISSUES.md item inside the goal's scope (route `/quick` or `/feature`)
-   Nothing actionable -> report + stop.
+   Select only units with verified dependencies and applicable plan approval.
+   Skip parked units and their dependents; do not re-pick them without new evidence.
+   Nothing actionable -> report + checkpoint + stop.
 2. ROUTE it through the lane-routing table (`/feature` · `/phase` · `/quick`).
    The lane runs with ALL its own gates — the goal layer never bypasses one.
-3. TICK: append one line under the goal (`- [x] <unit> — <lane> — <result>`),
-   decrement budget, update STATE (`goal: G<n> (active — <units left>)`).
+3. TICK: record status + evidence under the goal. Use `[x]` only for verified done;
+   record blocked/pending/not-run explicitly. Each attempted unit consumes budget,
+   including a parked unit. Persist remaining budget and retry counts; resuming
+   the same run does not reset them. Update STATE with the exact next action.
 4. CHECK "Done when". Met -> mark `[done]`, STATE `goal: G<n> (done)`, final
    report (units shipped · parked blockers · budget used). Not met -> loop.
 
-STOP conditions (whichever first): Done-when met · budget spent · a lane
-hard-stop (surface it; headless: `BLOCKED.md` + clean exit) · nothing actionable.
+STOP conditions (whichever first): verified Done-when met · budget spent ·
+no independent approved unit actionable · a run-wide safety/approval blocker.
+A lane hard-stop parks that unit and its dependents; record its blocker (headless:
+`BLOCKED.md`), then continue independent authorized units within budget.
+On resume, reconcile checkpoints, approvals, and the worktree per the methodology.
+A blocked required unit prevents claiming the goal complete.
 Every stop produces ONE consolidated report — never a silent end.
 
 ## /goal status · /goal done <id> · /goal drop <id>
 
-Show goals + progress ticks · force-close (human says it's done) · abandon
+Show goals + progress ticks · administratively close (record the human request,
+not fabricated passing evidence) · abandon
 (log why). Both edits keep the history lines — GOALS.md is append-style memory.
 
 ---
@@ -65,7 +74,7 @@ Show goals + progress ticks · force-close (human says it's done) · abandon
 
 `/goal run` is one pass: it works until done/blocked/budget. To keep pressure on
 a long goal, re-fire the pass on a schedule — host-level, not kit-level:
-- **Claude Code web/desktop**: `/loop 30m /goal run` — the host's interval loop
+- **Claude hosts with a verified `/loop` capability**: `/loop 30m /goal run` — the host's interval loop
   re-invokes the pass; the goal layer supplies the state + finish line that a
   bare interval loop lacks (it stops itself when Done-when is met).
 - **CI (headless)**: `create-issflow --ci` also installs

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

@@ -5,12 +5,14 @@ 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. Speak to the human as **PM** (status /
-ETA / blockers) — not as a pair-programming developer.
+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.
@@ -28,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.
@@ -46,35 +50,45 @@ 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:
-   - Set `status: AGENT_ACTIVE`, `eta_paused: false`, clear waiting_for if resuming.
+   - 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.
+     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 → STOP
-     for `/replan` or human — do not keep guessing.
+   - 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; CLOSE = regression + lint + secrets (and UI task
-   check if UI touched). Full path otherwise.
+   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.
 
 
 ---
@@ -84,8 +98,9 @@ f. LITE shortcuts (when LITE): skip dedicated researcher if unknowns are none;
 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.
-After each major stage change, rewrite STATE `stage:` + one-line progress (heartbeat).
+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
@@ -156,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)
 
@@ -168,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).
@@ -193,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
@@ -219,7 +237,8 @@ REGRESSION GATE (before closing — Feature 3):
 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: no raw hex / off-grid spacing — prefer `node scripts/token-lint.js` when present.
+- 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
@@ -235,9 +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).
 
-DELIVERY UPDATE: set this phase's `phase_etas` entry done; refresh next phase
-`agent_eta` or set `delivery.status: DONE` if package complete. Clear waiting_*.
-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
@@ -270,18 +293,25 @@ 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)
@@ -299,4 +329,4 @@ delivery:                      ← preserve + update; never drop
 ```
 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 (+24h), eta_paused: true, next_human_action (one sentence).
+stale_after (configured `delivery.staleAfterHours`, default 24h), eta_paused: true, next_human_action (one sentence).

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

@@ -25,17 +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.