create-issflow 1.11.1 → 1.12.0

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/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)',
   '',

package/template/.issflow/hooks/session-start.js

@@ -16,7 +16,8 @@ const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ig
 
 let cfg = {};
 try { cfg = JSON.parse(read('.issflow/flow-config.json') || '{}'); } catch (_) {}
-const maxStateLines = (cfg.context && cfg.context.injectMaxLines) || 25;
+const configuredLines = cfg.context && cfg.context.injectMaxLines;
+const maxStateLines = Number.isInteger(configuredLines) ? Math.max(1, Math.min(100, configuredLines)) : 25;
 const staleHours = (cfg.delivery && cfg.delivery.staleAfterHours) || 24;
 
 // Resume/compact: keep inject tiny (Pattern 1 — skip heavy bodies)
@@ -42,7 +43,7 @@ if (!state) {
 } else {
   emit('## STATE (read first)');
   const lines = state.replace(/\n$/, '').split('\n');
-  for (const l of lines.slice(0, maxStateLines)) emit(l);
+  for (const l of lines.slice(0, maxStateLines)) emit(l.slice(0, 500));
   if (lines.length > maxStateLines) emit(`… (+${lines.length - maxStateLines} more)`);
 
   // Delivery / WAITING_STALE nudge
@@ -66,6 +67,30 @@ if (!state) {
 }
 emit('');
 
+// Durable workflow state is advisory: never auto-retry a running task after interruption.
+const workflowFile = 'docs/WORKFLOW.json';
+if (exists(workflowFile)) {
+  emit('## Autonomous workflow checkpoint');
+  try {
+    const workflow = require('../runtime/workflow.js');
+    const summary = workflow.status(workflowFile);
+    emit(JSON.stringify({ state: summary.state, revision: summary.revision,
+      budget: summary.budget, spent: summary.spent, remaining: summary.remaining,
+      runnable: summary.runnable.slice(0, 10), totalTasks: summary.tasks.length }));
+    const unfinished = summary.tasks.filter(task => task.state !== 'done');
+    for (const task of unfinished.slice(0, 10)) {
+      emit(JSON.stringify({ id: task.id, state: task.state, attempts: task.attempts,
+        reason: task.reason.slice(0, 160), blockers: task.blockers.slice(0, 3) }));
+    }
+    emit(`Read ${workflowFile} for full task/evidence details (${unfinished.length} unfinished).`);
+    emit('Reconcile running work and its evidence before retrying; resume only within existing approval and budget.');
+  } catch (error) {
+    emit('Workflow checkpoint unreadable: ' + error.message + '. Preserve it; do not silently reset progress.');
+  }
+  emit('');
+}
+
+
 if (!leanResume) {
   const issues = read('docs/ISSUES.md');
   let openCount = 0;
@@ -87,8 +112,8 @@ emit('## RULES');
 emit('- PM-mode: report ETA/stage/DONE|BLOCKED|WAITING|SLIP|HANDOFF — do not pair as junior dev.');
 emit('- Plan PENDING → no source edits (rule 13). Design-direction locked before UI propose.');
 emit('- Past agent_eta while AGENT_ACTIVE → SLIP report. Waiting human → eta_paused.');
-emit('- Assumption budget per phase (flow-config). End phase: /synthesize (keep delivery:) → /clear.');
-emit('- Prefer clear+handoff over compact near context gate.');
+emit('- Assumption budget per phase (flow-config). End phase: checkpoint with /synthesize (keep delivery:); use only supported host reset tools.');
+emit('- Prefer a supported reset plus saved handoff near the context gate.');
 emit('=== END Tier-A ===');
 
 process.stdout.write(out.join('\n') + '\n');

package/template/.issflow/istartsoft-flow/METHODOLOGY.md

@@ -35,8 +35,10 @@
 Caveman ULTRA mode always on. Apply the `karpathy-guidelines` skill (engineering
 discipline) on every coding and debugging task. Apply the `ux-design` skill (the UX
 cookbook + wireframe baseline) on every UI-facing task. When **authoring** a new
-visual direction (`/design`, or no approved UX-PACK yet), apply `ui-ux-pro-max`
-first and fold the look into the UX pack — do not re-roll styles at phase CLOSE.
+visual direction (the overview Direction Picker, or an explicitly approved
+direction change), apply `ui-ux-pro-max` first and fold the look into locked
+tokens + UX pack. A missing UX-PACK does not unlock an approved direction;
+never re-roll styles at phase CLOSE.
 Apply the `security` skill (the Secure SDLC cookbook) at design (threat model),
 while coding (secure coding), and before any deploy. Apply the `code-standards`
 skill (naming per the language's own idiom + the declared architecture) on every
@@ -72,7 +74,8 @@ approval JSON is not cryptographic proof of the human approver. Require protecte
 branches, required CI checks, and an actual human GitHub PR review for merge.
 No tool can treat a self-edited approval file as owner authorization.
 
-**Recovery:** If approval metadata is missing or malformed, stop implementation.
+**Recovery:** If approval metadata is missing or malformed, stop implementation
+for that plan and its dependents; independent, separately approved work may continue.
 A human should inspect the plan, restore the correct pointer and approval record,
 then rerun verification. Never bypass the gate by editing `STATE.md` or disabling
 checks. A scoped feature lane does not inherit approval from another plan.
@@ -91,7 +94,8 @@ metadata and any required disclosures.
 
 `design-research -> grill (×2) -> plan -> implement -> test -> deploy`, one
 VERTICAL SLICE per phase. Implement AND test a phase before the next. The last
-phase always includes deployment.
+phase always includes deployment preparation; deployment itself requires the
+release authorization and checks below.
 
 A phase runs in one of two orders, chosen at RESEARCH time by the TDD
 APPLICABILITY check (see Procedures → `phase`):
@@ -256,7 +260,8 @@ Three layers make "hands-off" real — each uses the mechanism suited to its job
    model-run rituals.
 3. **No-human-at-the-keyboard → a headless runner.** `ISSFLOW_HEADLESS=1` tells the
    lane no human is present: every hard-stop degrades to a `BLOCKED.md` report +
-   clean exit — never a guess. Two shipped runners (`create-issflow --ci|--docker`,
+   lane return/exit — never a guess; an enclosing goal can still run independent
+   approved units. Two shipped runners (`create-issflow --ci|--docker`,
    sources in `.issflow/templates/automation/`):
    - **GitHub Actions** — label an issue `feature:approved` (or dispatch with a doc
      path); the workflow runs the lane on an ephemeral runner.
@@ -272,12 +277,20 @@ Three layers make "hands-off" real — each uses the mechanism suited to its job
      features build in parallel without touching your checkout or each other
      (path-identical mounts: Linux/macOS).
 
-**Approval semantics (rule-13 scoped).** The doc header
-`> Approval: APPROVED <name> <date>` is the human sign-off, scoped to that doc
-only; the mini-plan inherits it while it stays inside the doc's stated scope —
-scope creep hard-stops to `/change-request`. The `> Automation: none|push|push+pr`
-header pre-authorizes outbound git actions for THAT run (hard-stop 1 satisfied by
-recorded consent). Merge and prod deploy can never be pre-authorized.
+**Approval semantics (rule-13 scoped).** The Feature approval confirms intake
+for that document only. Apply Plan-scoped approvals before implementation;
+feature or goal headers never override an invalid revision/digest or path scope.
+Derived execution notes may break down approved work, not silently expand it.
+Scope creep returns to `/change-request` and the relevant approval gate.
+
+**Publication mode:** `> Automation: none|push|push+pr` defaults to `none`.
+`none` delivers local results only. `push` permits the specified feature branch
+push; `push+pr` permits that push and opening its PR to the agreed target. Either
+outbound mode requires explicit human authorization covering this run, repository,
+branch, and destination; a header an agent writes is not consent. Respect later
+restrictions, including no-commit/no-push. Never infer publication from AUTO,
+headless mode, or implementation approval. Merge and production deployment remain
+separate human release gates, never implied by these publication modes.
 
 -----
 
@@ -343,7 +356,8 @@ can. Escalation is at most two hops.
 - **synthesizer** — compresses `docs/STATE.md` / `docs/ISSUES.md`, prunes
   snapshots. On the final phase, also updates `README.md` + `docs/OVERVIEW.md`.
 
-The orchestrator ROUTES. It does not implement or debug.
+The orchestrator ROUTES to isolated workers where supported. Otherwise use the
+sequential role passes in Host capabilities and continuity; do not claim isolation.
 
 **Model routing (per-role tiers).** Each role's `.issflow/agents/<role>.md` pins a
 `model:` tier suited to its work, so the RIGHT model runs each task by default:
@@ -364,12 +378,17 @@ API IDs. Hosts without per-agent model support run the session model (graceful d
 
 Three clocks — do not mix:
 
-1. **Scope effort (A)** — ideal-days for commercial value / pricing  
-2. **Agent-active ETA (B)** — when AI may finish DoD if not waiting on humans  
+1. **Scope effort (A)** — ideal-days for commercial value / pricing
+2. **Agent-active ETA (B)** — when AI may finish DoD if not waiting on humans
 3. **Waiting-on-human (C)** — pauses B; `WAITING_STALE` after `staleAfterHours`
 
 STATE `delivery:` is mandatory during `/phase` and `/feature`. Past `agent_eta`
 while `AGENT_ACTIVE` → SLIP report. Assumption budget per phase from flow-config.
+These are estimates and observed state updates, not background runtime guarantees.
+Evaluate time changes at the next actual execution opportunity; never claim a timer,
+heartbeat, or scheduler ran when the host did not provide it. A waiting/blocked
+unit does not pause independent approved units: retain per-unit status and ETA.
+Only mark a package DONE when every required unit and gate is verified.
 
 ### Plan-Ready (before rule 13 approve)
 
@@ -418,7 +437,8 @@ surface or need its own acceptance criteria? -> `/feature`. Otherwise `/quick`.
   verification. Headless-capable (CI / Docker, `ISSFLOW_HEADLESS=1`). See "Feature lane".
 - **goal [set|run|status|done|drop]** — the goal layer: declare an OUTCOME with a
   measurable Done-when + budget (`set`, behind the rule-14 brief-back), then
-  `run` loops pick-next-unit → route lane → tick until done / budget / hard-stop.
+  `run` loops pick-next-unit → route lane → tick until done / budget / no ready
+  independent unit / run-wide hard-stop; local blockers park only their lane.
   Goal-driven, not time-driven: it stops itself on the finish line. Recurrence is
   host-level (interval loop or the cron-ready `issflow-goal.yml`). `docs/GOALS.md`
   holds state; its `Approved:` line arms headless passes.
@@ -512,13 +532,12 @@ The cheapest token is the one never loaded. The kit is built to minimise context
 - **SessionStart is Tier A** — git one-liner + STATE top + open-issue count +
   delivery ETA/WAITING nudge. Target a small inject; resume/compact stays leaner.
 - **Near context gate:** prefer writing handoff into STATE + `/synthesize` +
-  `/clear` over `/compact` (cold compact is expensive). Soft warn ~55%; hard
-  gate ~70% (see `flow-config.json`).
-- **Phase boundary is the primary reset.** `/synthesize -> /clear` ends every
-  phase so the next one starts with a small, fresh context instead of carrying
-  the whole history forward. Synthesizer must **preserve the `delivery:` block**
-  in STATE. The **sprint boundary** (`/sprint close`) is a second,
-  coarser reset — synthesize + clear there too before the next sprint plans.
+  host-supported reset over `/compact` where available. Use configured context
+  thresholds (`flow-config.json`), never invented telemetry or reset guarantees.
+- **Phase boundary is the primary checkpoint.** Synthesize at each boundary;
+  reset context only if needed and supported by the host. Continue the approved
+  driver without routine confirmation. Preserve the `delivery:` block and all
+  active/parked execution records. Sprint close provides a coarser checkpoint.
 - **Lazy, not always-on.** This methodology + the skills load on demand; only the
   SessionStart hook output is paid every session, and it injects just the live
   STATE + *open* issues (resolved ones stay on disk for grep, not re-paid in tokens).
@@ -543,29 +562,35 @@ a recorded sign-off) stay interactive in both modes. AUTO governs only the **dev
 close): there, interruptions are expensive, so it follows the plan instead of asking.
 
 - **AUTO (default) — during DEVELOPMENT, follow the plan, don't interrupt.** Once a
-  plan exists, the dev loop prefers DECIDING over asking. Resolve any in-process
+  plan is approved, the dev loop prefers DECIDING over asking. Resolve any in-process
   choice from (1) the PLAN/OVERVIEW/spec, (2) the codebase, (3) a sensible default +
   the worker's recommendation — then RECORD it (`docs/DESIGN_LOG.md` or STATE) and
   CONTINUE. Do not stop mid-build to ask.
 - **GUIDED — ask at each fork in dev too.** The original behaviour: the development
   loop also surfaces choices and waits. Use when exploring an unfamiliar codebase.
 
-**Decision protocol (AUTO, dev loop).** Incomplete acceptance spec → fill the gap
-with the most reasonable interpretation, log it as an Assumption, continue.
+**Decision protocol (AUTO, dev loop).** Resolve routine implementation details
+within the approved acceptance criteria, file boundaries, and risk limits; log
+the interpretation as an Assumption and continue. Do not add requirements or
+rewrite an approved plan to make a decision fit.
 Ambiguous TDD classification → apply the default (`TDD_PHASE=true`), log the reason,
 continue. A worker that would have asked the user instead writes its question + its
 own best answer to STATE and proceeds on that answer. (If the gap is in the PLAN
 itself — not just an implementation detail — that's a planning question: surface it.)
 
-**Batched escalation (AUTO).** Blockers never halt the whole run. On first stuck,
+**Batched escalation (AUTO).** A local blocker does not halt independent work. On first stuck,
 auto-run `/unstuck` (deep re-research) — capped at ONCE per phase, since it is
-token-expensive. Still stuck → park the blocked slice (mark `BLOCKED` in PLAN), move
+token-expensive; allow one fresh three-attempt debug cycle after it, never an
+unbounded reset of the counter. Still stuck → park the blocked slice in execution
+state (do not mutate the approved plan digest), move
 to the next independent slice, and surface ONE consolidated report of all parked
 blockers + logged assumptions at the phase boundary / end of run. The human reviews
 THERE (the `/re` checkpoint), not mid-flow.
 
-**Hard stops (BOTH modes — these always pause for a human).** Autonomy is for
-*development*, not for risk. Stop and get sign-off ONLY for:
+**Hard stops (BOTH modes).** Pause the affected action and dependent work for
+human input; continue only independently approved, safe work. Autonomy is for
+*development*, not permission escalation. The gates above and host permission
+policy still apply. Stop for:
 1. Irreversible or outbound actions — deploy to prod, data deletion/migration,
    `git push`, publish, spending money, sending external messages.
 2. Security-sensitive changes — auth, secrets, permissions, data exposure.
@@ -573,10 +598,76 @@ THERE (the `/re` checkpoint), not mid-flow.
    + log instead).
 4. The debug budget is spent AND no independent slice remains to make progress.
 
+An existing explicit authorization covering the exact action satisfies a gate
+only where that gate permits pre-approval. Never infer publish, push, deploy,
+spend, or security permissions from AUTO or a general build request. Release,
+UAT, and merge remain human gates. A security finding blocks affected completion
+and release, not unrelated safe work.
+
 AUTO removes *questions*, not *discipline*: tests, the phase gate, issue logging,
 and the regression corpus all still run. The point is an efficient, end-to-end
 development run that follows the spec and logs every problem so it never recurs.
 
+
+### Execution contract (short tasks and long runs)
+
+Use the smallest eligible lane. After its intake and approval gates, AUTO runs
+implement → test → fix → verify without requesting approval for each routine
+step. A short `/quick` still verifies; a long `/goal` or `/sprint` tracks units,
+dependencies, and a finite run budget. A single `/phase` or `/feature` request
+does not authorize unrelated work. Select only approved units whose dependencies
+are verified done; never skip a failed prerequisite to keep busy.
+
+Checkpoint after each meaningful step, before a context reset, and on interruption
+or a blocker: task ID, plan revision/digest, branch and base commit, dependencies,
+status, files changed, commands/results and evidence paths, attempt counts,
+remaining run budget, blocker and exact next action. Keep execution progress
+separate from immutable approved plan content. Optional local runtime checkpoints
+are bookkeeping, not approval, test evidence, or a background execution service.
+
+For a multi-unit run, the optional CLI is `node .issflow/runtime/workflow.js`.
+See `.issflow/runtime/README.md` for validated input schemas. Use
+`docs/WORKFLOW.json` when session-hook discovery is desired: `init` once from the
+approved task breakdown, `next` to claim, `update` after actual work, and `status`
+on resume. Each mutation persists state. The helper does not verify approval,
+execute tasks, or attest tests; retain the detailed evidence above separately.
+Never recreate a checkpoint to evade its spent budget. A changed task definition
+requires reviewed scope and carries forward relevant prior attempts explicitly.
+
+On resume, inspect the real worktree and latest approval before trusting a
+checkpoint. Reconcile already-applied edits and uncertain tool outcomes; do not
+repeat commits, outbound actions, or migrations blindly. Preserve retry counters
+and parked blockers across resume. Reopen a parked unit only with new evidence,
+a resolved prerequisite, or explicit direction; do not cycle it through new
+sprints to reset its budget. Bound environment/flake retries too (default two
+retries per failing check, within the run budget); unavailable services are
+`blocked`, not passing tests. Research retries use the same bounded policy.
+
+Completion requires observed acceptance and gate evidence for the current diff.
+Report `done`, `blocked`, `pending`, and `not run` distinctly, including actual
+commands, exit results, and remaining work. A generated test plan is not UAT;
+a skipped or unavailable check is not green. Missing metrics are `unavailable`,
+not invented percentages. Never mark an entire feature/goal done while a required
+unit is parked. Report local implementation separately from release readiness.
+
+### Host capabilities and continuity
+
+See `.issflow/runtime/HOSTS.md` for the installed capability matrix and smoke checks.
+
+Check the actual session's tools rather than assuming a product name grants
+capabilities. Claude Code can use installed native agents/hooks; Codex can use
+available delegation and execution tools; Cursor uses its installed command/rule
+and supported hook surfaces. Where delegation is unavailable, perform role passes
+sequentially and disclose when genuine blind test isolation cannot be provided.
+A model-run ritual is guidance, not tool enforcement. Never claim a Claude hook
+protects Codex or Cursor, or that any prompt guarantees unattended execution.
+
+Continue while the session is active and budget remains. Prompts and checkpoints
+do not create a persistent runtime, scheduler, or automatic wake-up. Use only an
+actually configured host scheduler/CI runner for recurrence, with its own limits
+and authorization; otherwise leave a resumable checkpoint and say a new invocation
+is needed. Do not invent `/clear`, `/loop`, or background execution capabilities.
+
 -----
 
 ## Dry-run (preview — change nothing)
@@ -603,7 +694,9 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
    The cap protects efficiency (no flailing / token burn) in both modes.
 3. Every resolved error -> logged to `docs/ISSUES.md` with root cause + failed
    attempts.
-4. End of phase -> synthesize -> context reset -> next phase.
+4. End of phase -> synthesize -> checkpoint -> next approved, ready phase.
+   Reset context only using an available host mechanism; if that ends execution,
+   leave the exact resume instruction. Do not claim to continue after session exit.
 5. **PHASE GATE** = the current-phase REAL API suite passes AND (frontend phase)
    the E2E suite passes AND the accumulated mock regression corpus stays green AND
    every `docs/ENDPOINTS.md` entry has at least one test in `tests/regression/`.
@@ -645,7 +738,9 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
     (the language's standard tool), names follow the language's OWN idiom, and the
     code conforms to the declared architecture (Feature-Based by default) — checked
     at CLOSE. Lint/format errors or idiom violations BLOCK the close. (`code-standards`.)
-13. **PLAN-APPROVAL gate.** No phase / sprint / build work starts until `docs/PLAN.md`
+13. **PLAN-APPROVAL gate.** Plan-scoped approvals above take precedence; the
+    following header convention applies only to legacy plans. No phase / sprint /
+    build work starts until `docs/PLAN.md`
     carries a human approval. `/overview` ends by presenting the plan and STOPPING for
     sign-off; on approval the gate is RECORDED in three places — the PLAN.md
     `> Approval:` header (`approved <date> v<n>`), `plan:` in `docs/STATE.md`, and a
@@ -663,6 +758,8 @@ Mirrors the installer's `--dry-run`. (In a dry-run, even AUTO never acts — it
     A recorded approval artifact IS the confirmation for its lane (approved
     PLAN → phases · APPROVED FEATURE doc → the feature lane · approved CR → the
     change · `Approved:` goal → goal runs) — that is exactly what arms headless.
+    Reuse that confirmation for routine steps and retries within the same scope;
+    goal approval does not replace the required approval of each execution plan.
     Rationale: a wrong understanding burns tokens and context at 100× the cost
     of one confirm turn. AUTO governs execution AFTER intake, never instead of it.
 15. **DESIGN + ARCHITECTURE gates.** After a client proposal is signed (quoted
@@ -698,10 +795,13 @@ fail the other.
 
 ## Shared KB (optional)
 
-If `.issflow/kb-config.json` exists, the SESSION-OPEN ritual pulls the KB and loads
-a snapshot to `docs/.kb-snapshot.md`. The researcher checks the snapshot (step 0)
-before any web search. Run `store-wisdom` to promote resolved issues + research to
-the KB. The kit works normally without a KB.
+The lean SessionStart hook does not pull the KB or generate a snapshot. If
+`.issflow/kb-config.json` exists and the task needs prior research, explicitly
+perform the authorized Tier-B/model-run refresh, or use the existing local KB
+with its freshness disclosed. The researcher checks `docs/.kb-snapshot.md` when
+available; never claim it was refreshed automatically. Run `store-wisdom` to
+promote resolved issues + research to the KB with its sharing approval. The kit
+works normally without a KB.
 
 -----
 

package/template/.issflow/models/MODEL-MATRIX.md

@@ -1,9 +1,9 @@
 # Model matrix (guidance)
 
-**as_of:** 2026-11-04  
+**as_of:** 2026-11-04
 Update this file when vendors ship new models. Do **not** hardcode unverified API IDs into agent runners.
 
-Agent frontmatter stays: `haiku` · `sonnet` · `opus` · `inherit`.  
+Agent frontmatter stays: `haiku` · `sonnet` · `opus` · `inherit`.
 Adaptive router (`.issflow/routing/`) remains advisory / fail-closed.
 
 ## Capability tiers → host suggestions
@@ -25,9 +25,9 @@ Adaptive router (`.issflow/routing/`) remains advisory / fail-closed.
 
 ## Verify before pinning IDs
 
-- Claude: https://code.claude.com/docs/en/model-config  
-- Cursor: https://cursor.com/help/models-and-usage/available-models  
-- Codex: https://learn.chatgpt.com/docs/models  
-- Antigravity: https://antigravity.google/docs/models/  
+- Claude: https://code.claude.com/docs/en/model-config
+- Cursor: https://cursor.com/help/models-and-usage/available-models
+- Codex: https://learn.chatgpt.com/docs/models
+- Antigravity: https://antigravity.google/docs/models/
 
 If a host cannot switch models per agent, run everything on the session model.

package/template/.issflow/routing/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/template/.issflow/runtime/HOSTS.md

@@ -0,0 +1,41 @@
+# Host capabilities and verification
+
+The installer ships procedures plus local Node helpers. It does not install an
+agent service, guarantee unattended continuation, or enable persistent access.
+An active host agent must perform the work and call the helper. Future sessions
+require a separately authorized host scheduler. A checkpoint is not approval.
+
+| Capability | Claude adapter | Codex adapter | Cursor adapter |
+| --- | --- | --- | --- |
+| Entry instructions | CLAUDE.md imports AGENTS.md | AGENTS.md | always-apply workflow/gate rules + AGENTS.md |
+| Roles | .claude agent mirror, host-dependent discovery | reference files; use native delegation if exposed | reference files; use native delegation if exposed |
+| Installed hooks | session, pre-tool, pre-compact, subagent-stop, stop | none | sessionStart, subagentStop only |
+| Task state helper | explicit Node CLI | explicit Node CLI | explicit Node CLI |
+| Checkpoint recovery | lean Tier-A session hook summarizes state; agent reconciles | agent reads state explicitly | session hook if supported; otherwise explicit |
+| Approval enforcement | edit hook covers listed edit tools, not all shell writes | explicit verifier / CI | explicit verifier / CI |
+| Completion proof | agent checks current code; file gate alone is insufficient | same | same |
+
+Host versions and permissions vary. Detect available tools at session start.
+Never claim a role file creates an isolated worker or a hook covers every edit.
+If delegation is absent, use serial roles. If a hook is absent, perform the same
+ritual explicitly. Respect host safety, approval, token, and execution limits.
+
+## Smoke checks
+
+Automated installer tests cover Claude/Codex/Cursor in CommonJS and ESM projects,
+dry-run, runtime loading, non-destructive upgrades, and truthful adapter text.
+Runtime tests exercise restart, blocked dependencies, independent tasks, budgets,
+retries, and evidence. These are local contract tests, not live vendor-host tests.
+
+For a real host smoke check, use an isolated disposable project:
+1. Install its adapter and inspect generated entry files/hooks.
+2. Start a fresh session, verify instructions are loaded and note actual tools.
+3. Run an authorized tiny task and record command output with code revision.
+4. Interrupt after a checkpoint. Start a new session and reconcile running work
+   rather than blindly retrying a possibly completed external action.
+5. Block one task and confirm independent authorized work continues.
+6. Verify the final report distinguishes passed, failed, blocked and unrun checks.
+
+Do not count these live-host checks as passed until they actually run. Publishing,
+PR creation and deployment need their own authorized scope; local tests do not
+imply remote publication or CI success.