create-issflow 1.10.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,10 +152,23 @@ 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'));
+  writeFile('.cursor/rules/issflow-gates.mdc', [
+    '---', 'description: iStartSoftFlow gates — STATE delivery + plan lock', 'alwaysApply: true', '---', '',
+    'Before any source Edit/Write:',
+    '1. Read `docs/STATE.md` — respect `delivery:` (ETA · WAITING · SLIP · DONE).',
+    '2. If PLAN approval is PENDING → do not edit source (rule 13).',
+    '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 → checkpoint with `/synthesize` (keep delivery:); use only reset capabilities the host exposes.',
+    '',
+    'Talk to the human as PM/SA. Subagents never address the user.',
+    '',
+  ].join('\n'));
   copyTemplateCommands('.cursor/commands');
   writeFile('.cursor/hooks.json', JSON.stringify({
     version: 1,
@@ -164,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); verify hooks.json against cursor.com/docs/hooks — the schema evolves.');
+  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() {
@@ -230,15 +243,21 @@ 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',
@@ -265,22 +284,25 @@ function flowConfig() {
   return JSON.stringify({
     context: {
       window: 0,
-      warnPct: 60,
-      gatePct: 78,
+      warnPct: 55,
+      gatePct: 70,
+      injectMaxLines: 25,
       _note: 'Context-budget watchdog (.issflow/hooks/context-guard.js, PreToolUse hook). '
         + 'window 0 = auto-detect from the model id (200000 for standard models). '
-        + '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 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).',
+        + 'warnPct soft nudge; gatePct hard block on NEW source Edit/Write. Prefer '
+        + '/synthesize + /clear (keep delivery:) 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. Waiting-on-human pauses ETA; '
+        + 'after staleAfterHours → 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 absent.',
+      _note: 'Sprint layer (/sprint). defaultCapacity = points for first sprint.',
     },
   }, null, 2) + '\n';
 }
@@ -331,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.10.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,12 +12,15 @@ 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 |
 | `istartsoft-flow/` | METHODOLOGY.md — every hard rule lives here once |
-| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / automation |
+| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / design picker · platforms |
+| `models/` | MODEL-MATRIX.md — cross-host model guidance (aliases stay haiku/sonnet/opus) |
+| `routing/` | Advisory model router (fail-closed) |
+| `scripts/` | Portable helpers (e.g. token-lint.js) |
 
 ## Claude Code only
 
@@ -34,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:
 ```
@@ -79,7 +84,7 @@ token unambiguously. Do not put prose containing the word `approved` after a
 
 ## Sprint 1: <name>  [goal: <one-line user-visible increment>]   ← sprint headers optional; group a few phases
 
-## Phase 1: <name>  [5 pts]  [status: pending]
+## Phase 1: <name>  [5 pts]  [size: S|M|L|XL]  [lane: lite|full]  [status: pending]
 
 - slice: <what works end-to-end after this phase>
 - rationale: <why this slice, why now — the user / business value (from the PRD)>
@@ -88,11 +93,16 @@ token unambiguously. Do not put prose containing the word `approved` after a
 - acceptance (sharp, testable):
   - GIVEN <state> WHEN <action with concrete input> THEN <exact observable output>
   - edge/negative: <input> -> <expected handling>
+  - (UI) task check: primary user completes the job without guessing
 - impl notes: <constraints, gotchas, patterns to follow — so the implementer needs no extra digging>
 - qa focus: <what the tests must especially probe — abuse / edge cases>
 - external: <service name, or “none”>
   …
 
+Plan-Ready (orchestrator checks before human approve): every phase has testable
+acceptance · no TBD on auth/money/PII/primary surfaces · size+lane set · UI phases
+reference screen IDs or locked direction · dependencies clear.
+
 ## Phase N: <name — final code phase>  [status: pending]
 
 - slice: <what works + app is deployed and reachable>

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

@@ -17,14 +17,19 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
 ## Standard tasks (every phase — do all, in order)
 
 1. STATE.md — rewrite, do not append. Keep ONLY:
-   - current phase + status
+   - current phase + status + stage
    - 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.
+   sign-off record, hard rule 13), the `sprint:` line if present, **and the entire
+   `delivery:` block** (agent_eta / status / waiting_* / slip) — load-bearing for
+   finish-date honesty. Also preserve `design-direction:`, `design:`, `architecture:`,
+   `surfaces:`, `timezone:` when present.
+   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.
@@ -35,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:
 ```
@@ -62,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.
@@ -76,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/change-request.md

@@ -38,12 +38,18 @@ Also classify commercial lane:
   `/support` or `/quick` — not a billable CR unless the client expands scope.
 - **Billable CR** → continue below.
 
+**No full grill-me.** If the change hits surfaces / auth / UX / architecture:
+ask **1–3 mini questions** (brief-back with recommended answers), then continue.
+Deep design re-lock happens later via `/design` if rule 15 reopens.
+
 ## STEP 2 — IMPACT ANALYSIS
 Determine:
 - phases affected — **done phases are frozen** (their cost is already spent and
   counts); new / changed phases; cut phases (credit back the un-started effort).
 - knock-on effects — architecture, **UX pack**, **security (re-threat-model?)**,
-  tests, timeline. If UX or arch artifacts change, those gates re-open (rule 15).
+  tests, timeline, **design-direction / tokens**. If UX or arch artifacts change,
+  those gates re-open (rule 15). If direction must change, reset
+  `design-direction:` to PENDING (re-picker).
 - dispatch `researcher` (DESIGN or IMPL) if the change needs grounding in facts.
 
 ## STEP 3 — RE-ESTIMATE (the DELTA only)
@@ -52,10 +58,12 @@ Determine:
   estimate memo or chat-recorded answers.
 - If rate / contingency is missing → **ASK once** (same rule as `/propose`). Never
   invent a kit default rate; never commit personal rates into public kit files.
+- Report **two deltas** in chat: scope_effort Δ (axis A, drives money) and
+  agent_delivery Δ (axis B, calendar when AI may work). Price uses A only.
 - added effort × rate = added cost; cut effort = credit.
 - **net cost Δ** + **new total** vs the approved baseline — as a range.
 - Show rate math **in chat to the human only**.
-- **timeline Δ**. State what stays the SAME so the client sees the price is fair.
+- **timeline Δ** (B agent_delivery + human-gate buffer + new `demo_by`). Refresh STATE `delivery:` if mid-build. State what stays the SAME so the client sees the price is fair.
 
 ### CLIENT-DOC RULE
 Anything the client sees (CR summary, updated PROPOSAL.md / proposal.html) shows

package/template/.issflow/commands/design.md

@@ -1,5 +1,5 @@
 ---
-description: Post-proposal DESIGN + ARCHITECTURE gates — produce UX pack and architecture note, stop for human approve before /phase (hard rule 15).
+description: Post-proposal DESIGN + ARCHITECTURE gates — upgrade locked direction into UX pack + architecture, stop for human approve before /phase (hard rule 15).
 argument-hint: [optional: "ux" | "arch" | "both" · "dry-run"]
 ---
 
@@ -14,44 +14,59 @@ DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, outline what you'd writ
 and STOP. Write nothing.
 
 ## PRE-FLIGHT
-- Read `docs/OVERVIEW.md`, `docs/PLAN.md`, `docs/PROPOSAL.md` (if any), `docs/STATE.md`.
+- Read `docs/OVERVIEW.md`, `docs/PLAN.md`, `docs/PROPOSAL.md` (if any), `docs/STATE.md`,
+  `docs/design/DIRECTION.md`, `docs/design/tokens.css`.
 - PLAN must be approved (rule 13). If a proposal exists for quoted work, it should
   be signed off first (`/propose`) — otherwise warn and confirm they want design
   gates without a commercial proposal (internal projects may skip `/propose` and
   still run `/design`, or skip rule 15 entirely when STATE has `design: n/a` and
   `architecture: n/a` set deliberately for non-quoted work).
+- **Direction:** if UI in scope and `design-direction` is not locked → STOP; run
+  overview Direction Picker first. If locked → **do not** re-run `ui-ux-pro-max`
+  restyle unless the human explicitly asks to change look (then re-approve).
 
 Target: `$ARGUMENTS` → `ux` | `arch` | `both` (default **both**).
 
+## Design scale (pick one; say it out loud)
+
+| Scale | When | Artifact depth |
+|-------|------|----------------|
+| Spike | Feasibility only | Short answer — no UX-PACK |
+| Bounded | Small change to existing UI | Short design in chat or thin UX-PACK + approve |
+| Architectural | New product / subsystem / auth boundary / multi-surface | Full UX-PACK(s) + ARCHITECTURE |
+
 ## STEP 1 — UX PACK (if ux|both)
-1. Apply `ui-ux-pro-max` (visual direction): run the kit engine
-   `.issflow/skills/ui-ux-pro-max/scripts/search.py --design-system` from
-   OVERVIEW product + industry. Fold into UX-PACK tokens — do not create a
-   parallel `design-system/` SoT. If Python 3 is missing, ask me to install it
-   (do not install tools yourself).
-2. Apply `ux-design` skill (authoring mode): wireframe baseline + cookbook direction.
-   Catalogue output must still pass the cookbook (tokens, a11y, no emoji icons).
-3. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
-4. Fill flows, screen inventory, tokens/frame, a11y notes from OVERVIEW + PLAN.
-5. SHOW me UX-PACK.md. **STOP for approval.**
-6. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
+1. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
+2. Fold **locked** DIRECTION + tokens — do not invent a second palette.
+3. Apply `ux-design` skill (authoring): wireframe baseline + cookbook. Screen inventory
+   must use stable IDs from propose appendix when present.
+4. Per primary screen: goal, primary CTA, empty/loading/error, <SM and ≥MD notes.
+5. If `surfaces` includes more than web: add `docs/design/<surface>/` notes (PWA /
+   line-oa / mobile packs — see templates under `.issflow/templates/design/platforms/`).
+6. Update `docs/design/inventory.md` — reuse only listed components.
+7. SHOW me UX-PACK.md. **STOP for approval.**
+8. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
    in STATE.md; HISTORY line `design v<n> approved`.
-7. On change request: revise and re-show; header stays PENDING.
+9. On change request: revise and re-show; header stays PENDING.
+10. Quoted + UI: after approve, **regenerate** `docs/proposal.html` screen sheets from
+    the same screen IDs + tokens so the PDF matches what will be built.
 
 ## STEP 2 — ARCHITECTURE (if arch|both)
 1. Dispatch `researcher` (DESIGN) only if open unknowns remain; else use OVERVIEW.
 2. Scaffold or update `docs/ARCHITECTURE.md` from
    `.issflow/templates/ARCHITECTURE-template.md`.
-3. Apply `code-standards` architecture guidance; security trust boundaries via
+3. Include **Auth decision record** when users/login exist (provider, session model,
+   identity linking, roles) — grill briefly if still open.
+4. Apply `code-standards` architecture guidance; security trust boundaries via
    `security` skill when relevant.
-4. SHOW me ARCHITECTURE.md. **STOP for approval.**
-5. On approve: stamp header; set `architecture: approved <date>` in STATE.md;
+5. SHOW me ARCHITECTURE.md. **STOP for approval.**
+6. On approve: stamp header; set `architecture: approved <date>` in STATE.md;
    HISTORY line `architecture v<n> approved`. Optionally `/log-decision` for
    material pattern choices.
-6. On change request: revise and re-show.
+7. On change request: revise and re-show.
 
 ## STEP 3 — HANDOFF
 When both required gates are approved (or N/A for internal skip):
 - Tell me `/phase` is unblocked for rule 15.
-- Reminder: frontend phases still run the `ux-design` CLOSE check (rule 9);
-  architecture drift still needs `/log-decision` (rule 8).
+- Reminder: frontend phases still run the `ux-design` CLOSE check (rule 9) + task
+  check; architecture drift still needs `/log-decision` (rule 8).

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

@@ -4,7 +4,13 @@ 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. 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; 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.
 
 Target doc: $ARGUMENTS  (default: the single `docs/features/*/FEATURE.md` whose
 `> Status:` reads `approved, pending` — zero or multiple candidates -> STOP and list them.)
@@ -28,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.
 
 ---
 
@@ -51,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
@@ -86,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)
 
@@ -99,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`.
 
@@ -130,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)
 
@@ -169,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,
@@ -179,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