create-issflow 1.10.1 → 1.12.0

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

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-// SessionStart hook. stdout is injected into the agent's context every session.
-// Pure Node, cross-platform (macOS / Windows / Linux) — no bash/jq/python needed.
+// SessionStart — Tier A inject (~lean). stdout → agent context.
 'use strict';
 const fs = require('fs');
 const path = require('path');
@@ -15,144 +14,106 @@ const read = (f) => { try { return fs.readFileSync(f, 'utf8'); } catch (_) { ret
 const exists = (f) => fs.existsSync(f);
 const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }); } catch (_) { return ''; } };
 
-emit('=== iStartSoftFlow AUTO-CONTEXT (injected by hook, NOT optional) ===');
-emit('');
+let cfg = {};
+try { cfg = JSON.parse(read('.issflow/flow-config.json') || '{}'); } catch (_) {}
+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)
+let source = 'startup';
+try {
+  const raw = fs.readFileSync(0, 'utf8');
+  if (raw) {
+    const j = JSON.parse(raw);
+    source = j.source || j.hook_event_name || source;
+  }
+} catch (_) {}
+const leanResume = /resume|compact/i.test(String(source));
 
-// 1. git state
-emit('## Git');
-emit('branch: ' + (sh('git branch --show-current').trim() || 'n/a'));
-const uncommitted = sh('git status --short').split('\n').filter((l) => l.trim() !== '').length;
-emit('uncommitted: ' + uncommitted + ' file(s)');
-for (const l of sh('git log --oneline -3').replace(/\n+$/, '').split('\n').filter(Boolean)) emit('  ' + l);
+emit('=== iStartSoftFlow Tier-A (session) ===');
+emit('source: ' + source);
+emit('git: ' + (sh('git branch --show-current').trim() || 'n/a') +
+  ' · dirty ' + sh('git status --short').split('\n').filter((l) => l.trim()).length);
 emit('');
 
-// 2. active state (cap size — STATE.md is meant to stay small)
 const state = read('docs/STATE.md');
-if (state !== null) {
-  emit('## STATE.md (current position - READ THIS FIRST)');
-  const sl = state.replace(/\n$/, '').split('\n');
-  for (const l of sl.slice(0, 40)) emit(l);
-  if (sl.length > 40) emit(`… (+${sl.length - 40} more — STATE.md should be small; trim it)`);
-  emit('');
+if (!state) {
+  emit('STATE.md missing → /overview');
 } else {
-  emit('## STATE.md missing -> run /overview to bootstrap the project.');
-  emit('');
-}
+  emit('## STATE (read first)');
+  const lines = state.replace(/\n$/, '').split('\n');
+  for (const l of lines.slice(0, maxStateLines)) emit(l.slice(0, 500));
+  if (lines.length > maxStateLines) emit(`… (+${lines.length - maxStateLines} more)`);
 
-// 2b. active sprint (sprint layer) — surface goal + burndown if one is active
-const sprintMatch = (state || '').match(/^\s*sprint:\s*(\d+)\s*\(active\)/m);
-if (sprintMatch) {
-  const sf = read(`docs/sprints/sprint-${sprintMatch[1]}.md`);
-  if (sf !== null) {
-    emit(`## Sprint ${sprintMatch[1]} (active)`);
-    const goal = (sf.match(/goal:\s*(.+)/i) || [])[1];
-    if (goal) emit('goal: ' + goal.trim());
-    const burn = sf.split('\n').find((l) => /burndown|remaining|pts? left|[▁▂▃▄▅▆▇█]/i.test(l));
-    if (burn) emit('burndown: ' + burn.trim());
-    emit(`see docs/sprints/sprint-${sprintMatch[1]}.md for the full sprint.`);
-    emit('');
+  // Delivery / WAITING_STALE nudge
+  const waitSince = (state.match(/waiting_since:\s*(\S+)/) || [])[1];
+  const status = (state.match(/^\s*status:\s*(\S+)/m) || [])[1] || '';
+  const waitingFor = (state.match(/waiting_for:\s*(.+)/) || [])[1];
+  const nextHuman = (state.match(/next_human_action:\s*(.+)/) || [])[1];
+  const agentEta = (state.match(/agent_eta:\s*(\S+)/) || [])[1];
+  if (agentEta && agentEta !== 'none') emit('delivery.agent_eta: ' + agentEta + ' · status: ' + status);
+  if (/WAITING/i.test(status) || (waitingFor && waitingFor.trim() !== 'none')) {
+    emit('WAITING_ON_HUMAN: ' + (waitingFor || status).trim());
+    if (nextHuman) emit('next_human_action: ' + nextHuman.trim());
+    if (waitSince && waitSince !== 'none') {
+      const since = Date.parse(waitSince);
+      if (!Number.isNaN(since)) {
+        const hours = (Date.now() - since) / 3600000;
+        if (hours >= staleHours) emit('WAITING_STALE: human gate older than ' + staleHours + 'h — AI clock paused; not an agent hang.');
+      }
+    }
   }
 }
+emit('');
 
-// 3. issue log — inject only OPEN issues (resolved ones stay in the file for
-//    grep, but are NOT re-paid in tokens every session). Capped.
-const issues = read('docs/ISSUES.md');
-if (issues !== null) {
-  const blocks = [];
-  let cur = null;
-  for (const l of issues.split('\n')) {
-    if (/^### /.test(l)) { if (cur) blocks.push(cur); cur = [l]; }
-    else if (cur) cur.push(l);
-  }
-  if (cur) blocks.push(cur);
-  const open = blocks.filter((b) => b.some((l) => /- \[ \]/.test(l)));
-  emit(`## ISSUES.md (${open.length} open) - grep this file before debugging anything`);
-  if (open.length) {
-    const flat = open.flat();
-    for (const l of flat.slice(0, 50)) emit(l);
-    if (flat.length > 50) emit('… (more — grep docs/ISSUES.md for full detail)');
-  } else {
-    emit('(no open issues)');
+// 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('');
 }
 
-// 3b. research index — token economy: inject only the 5 newest rows, each
-// truncated; the full table stays on disk for grep, sessions don't re-pay it.
-const idx = read('docs/research/INDEX.md');
-if (idx !== null) {
-  const rows = idx.split('\n').filter((l) => /^\|\s*\d{4}-\d{2}-\d{2}/.test(l));
-  emit(`## research/INDEX.md (${rows.length} prior investigations)`);
-  emit('grep this before any new research or debugging.');
-  for (const l of rows.slice(-5)) emit('  ' + (l.length > 220 ? l.slice(0, 217) + '…' : l));
-  if (rows.length > 5) emit(`  … (+${rows.length - 5} older — grep docs/research/INDEX.md)`);
-  emit('');
-}
-
-// 3d. shared KB — pull latest + load snapshot
-const KB_CONFIG = '.issflow/kb-config.json';
-let kbActive = false;
-if (exists(KB_CONFIG)) {
-  let cfg = {}; try { cfg = JSON.parse(read(KB_CONFIG) || '{}'); } catch (_) {}
-  let kbPath = cfg.kb_path || '';
-  if (kbPath.startsWith('~')) kbPath = path.join(os.homedir(), kbPath.slice(1));
-  if (kbPath && exists(kbPath) && fs.statSync(kbPath).isDirectory()) {
-    emit('## Shared KB');
-    let pulled = true;
-    try { execSync(`git -C "${kbPath}" pull --ff-only --quiet`, { stdio: 'ignore' }); } catch (_) { pulled = false; }
-    emit(pulled ? 'KB pulled: OK' : 'KB pull skipped (offline or conflict — using local copy)');
 
-    const cut = new Date(); cut.setMonth(cut.getMonth() - 6);
-    const cutoff = cut.toISOString().slice(0, 10);
-    const today = new Date().toISOString().slice(0, 10);
-    const kbIndex = path.join(kbPath, 'INDEX.md');
-    if (exists(kbIndex)) {
-      const lines = (read(kbIndex) || '').split('\n').filter((l) => l && !l.startsWith('#'));
-      const snap = [`# KB snapshot — loaded ${today}`, `# Stale = created date older than ${cutoff}`, ''];
-      let stale = 0, total = 0;
-      for (const line of lines) {
-        if (line.includes('|')) total++;
-        const entryDate = (line.split('|')[0] || '').trim();
-        if (/^\d{4}-\d{2}-\d{2}$/.test(entryDate) && entryDate < cutoff) { snap.push('[STALE] ' + line); stale++; }
-        else snap.push(line);
-      }
-      try { fs.mkdirSync('docs', { recursive: true }); fs.writeFileSync('docs/.kb-snapshot.md', snap.join('\n') + '\n'); } catch (_) {}
-      emit(`KB snapshot loaded: ${total} entries (${stale} stale — researcher will re-research these)`);
-      emit('Snapshot at docs/.kb-snapshot.md — researcher reads this before web search.');
-    } else {
-      emit(`KB INDEX.md not found at ${kbPath} — run /store-wisdom to populate it.`);
+if (!leanResume) {
+  const issues = read('docs/ISSUES.md');
+  let openCount = 0;
+  if (issues) {
+    const blocks = [];
+    let cur = null;
+    for (const l of issues.split('\n')) {
+      if (/^### /.test(l)) { if (cur) blocks.push(cur); cur = [l]; }
+      else if (cur) cur.push(l);
     }
-    emit('');
-    kbActive = true;
-  } else {
-    emit('## Shared KB: configured but path not found (' + (cfg.kb_path || '') + ')');
-    emit('Fix kb_path in .issflow/kb-config.json (or re-run: npx create-issflow).');
-    emit('');
+    if (cur) blocks.push(cur);
+    openCount = blocks.filter((b) => b.some((l) => /- \[ \]/.test(l))).length;
   }
+  emit('open issues: ' + openCount + ' (grep docs/ISSUES.md — bodies not injected)');
+  emit('');
 }
 
-// 4. hard rule reminder
-emit('## RULES (enforced this session)');
-emit('- AUTO mode (default) governs the DEV loop: follow the plan — decide + log +');
-emit('  continue, do NOT stop to ask. (Planning / grill still asks — that part is fine.)');
-emit('  Hard-stops only: security / irreversible-or-outbound actions / contradictory spec.');
-emit('- caveman ULTRA mode is active.');
-emit('- PLAN-APPROVAL gate (rule 13): no /phase or /sprint while STATE `plan:` reads');
-emit('  PENDING — the plan needs a human sign-off via /overview first.');
-emit('- UNDERSTAND-FIRST (rule 14): new free-text task -> brief back your understanding');
-emit('  (goal · scope · assumptions · blast radius) and WAIT for confirm before executing.');
-emit('- before debugging ANY error: grep ISSUES.md AND research/INDEX.md first.');
-emit('- debug attempts: WARN at 2; cap 3. AUTO: log + park the slice + continue (batched');
-emit('  report at the phase boundary). GUIDED: stop and ask you.');
-emit('- end of every phase: run /synthesize, then /clear.');
-emit('- small obvious change? use /quick, not /phase.');
-emit('- token economy: keep context lean. Delegate noisy work to subagents (they');
-emit('  return summaries). If one phase grows past ~50% of the model window, split');
-emit('  it or /synthesize -> /clear — do not coast to auto-compact.');
-if (kbActive) {
-  emit('- KB active: researcher checks docs/.kb-snapshot.md before web search.');
-  emit('- learned something worth keeping? run /store-wisdom.');
-}
-emit('=== END AUTO-CONTEXT ===');
+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: 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`):
@@ -200,14 +204,28 @@ those gates, never the plan, the money, or the design/arch frame.
 
 | House role | Kit surface |
 |------------|-------------|
-| BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates |
-| UX / UI | `/design` (UX pack) · `ui-ux-pro-max` (look) · `ux-design` (frame + gate) · `/ui-audit` · rule 9 CLOSE |
-| Architect | `/design` (ARCHITECTURE) · `researcher` DESIGN · `code-standards` · `/log-decision` |
-| Developer | `implementer` · `/phase` · `/feature` · `/quick` |
+| BA / PM | `/overview` grill · `grill-me` · PLAN / PROPOSAL / CR gates · delivery ETA board |
+| UX / UI | Direction Picker → tokens · `/design` UX pack · `ui-ux-pro-max` (only if unlocked) · `ux-design` · `/ui-audit` |
+| Architect / SA | `/design` ARCHITECTURE + auth decision · `researcher` DESIGN · `/log-decision` |
+| Developer | `implementer` · `/phase` · `/feature` · `/quick` — **no direct user chat** |
 | QA | `test-author` · `e2e-runner` · `/qa-audit` · `/uat` |
 | DevOps | final-phase deploy · `/release` promote |
 | Support | `/support` · `/log-issue` · `/runbook` · release hypercare |
 
+**Human conversation mode:** the owner talks to the orchestrator as PM/SA. Subagents
+never address the user. During AUTO build, report stage / ETA / WAITING / SLIP /
+DONE — do not pair-program unless GUIDED.
+
+### When `grill-me` runs
+
+| Command | Grill? |
+|---------|--------|
+| `/overview` | Yes — automatic double grill |
+| `/design` | Short grill only if auth/surfaces still open |
+| `/change-request` | No full grill — 1–3 mini-asks if UX/arch/auth hit |
+| `/phase` · `/feature` build | No — use STATE + stuck/ETA |
+| User says “grill me” | On demand anytime |
+
 -----
 
 ## Feature lane (hands-off delivery — `/feature`)
@@ -242,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.
@@ -258,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.
 
 -----
 
@@ -329,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:
@@ -341,9 +369,31 @@ The orchestrator ROUTES. It does not implement or debug.
 | synthesizer | `haiku` | mechanical compression — cheapest tier |
 
 Owner wants a SPECIFIC model? Edit the role's `model:` line — values `haiku` ·
-`sonnet` · `opus` · `inherit` · or a full model id. The installer is
-non-destructive, so your pins survive kit updates. Hosts without per-agent model
-support run everything on the session model (graceful degrade).
+`sonnet` · `opus` · `inherit` · or a full model id. Cross-host suggestions live in
+`.issflow/models/MODEL-MATRIX.md` (update `as_of` when vendors change). Adaptive
+router under `.issflow/routing/` is advisory/fail-closed — never invent unverified
+API IDs. Hosts without per-agent model support run the session model (graceful degrade).
+
+### Delivery clocks (finish-date honesty)
+
+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
+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)
+
+Testable acceptance per phase · no TBD on auth/money/PII/primary surfaces ·
+direction locked if UI · size+lane tags · dependencies clear.
 
 -----
 
@@ -387,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.
@@ -448,15 +499,18 @@ inject context, the model performs them itself.
 
 ### SESSION-OPEN (start / clear / compact-resume)
 
-At the start of every session, before any other work, surface:
-1. git state (branch, uncommitted count, last 3 commits).
-2. `docs/STATE.md` — the current position. READ THIS FIRST. If a sprint is active,
-   surface its goal + burndown from `docs/sprints/sprint-<n>.md`.
-3. open items in `docs/ISSUES.md`.
-4. `docs/research/INDEX.md` (research map) + infra/auth status.
-5. shared KB: pull latest + load `docs/.kb-snapshot.md` if `.issflow/kb-config.json`
-   exists.
-6. a one-line reminder of the hard rules below.
+**Tier A (default — keep short):** SessionStart hook / model-run checklist:
+1. git one-liner (branch · dirty count · tip).
+2. `docs/STATE.md` top — phase, plan, design-direction, **delivery ETA/status**.
+3. open-issue count (not full dump).
+4. If `WAITING_STALE` / past `agent_eta` while AGENT_ACTIVE → surface that first.
+5. Hard-rule one-liner (plan PENDING → no source edits).
+
+**Tier B (full, on demand / first overview):** research INDEX · infra/auth · KB
+snapshot · sprint burndown. Prefer Hard handoff (`/synthesize` keep `delivery:` →
+`/clear`) over cold `/compact` near the context gate.
+
+Hosts without hooks: the orchestrator runs Tier A by hand before any Edit/Write.
 
 ### SPRINT-STANDUP (auto — at phase close inside an active sprint)
 
@@ -475,10 +529,15 @@ recover: current phase, next action, open blocker.
 
 The cheapest token is the one never loaded. The kit is built to minimise context:
 
-- **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. The **sprint boundary** (`/sprint close`) is a second,
-  coarser reset — synthesize + clear there too before the next sprint plans.
+- **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` +
+  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).
@@ -503,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.
@@ -533,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)
@@ -563,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/`.
@@ -605,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
@@ -623,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
@@ -658,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.
 
 -----