create-issflow 1.10.1 → 1.12.0

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

@@ -0,0 +1,33 @@
+# Model matrix (guidance)
+
+**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`.
+Adaptive router (`.issflow/routing/`) remains advisory / fail-closed.
+
+## Capability tiers → host suggestions
+
+| Kit alias / role band | Claude Code | Cursor | Codex CLI | Antigravity |
+|----------------------|-------------|--------|-----------|-------------|
+| `haiku` (synthesizer, cheap) | Haiku 5.5 alias `haiku` | Composer 2.5 / Auto | Luna-class (plan-dependent) | Gemini 3.8 Flash |
+| `sonnet` (researcher, e2e, daily) | Sonnet 5.5 alias `sonnet` | Composer 2.5 / Auto / Sonnet | Terra-class | Gemini 3.8 Flash |
+| `opus` / `inherit` hard (planner, debugger, arch) | Opus 5.5 / session model | Opus / Sol / Grok flagship | Sol-class | Gemini 4 Argon |
+| Long-horizon session | Fable / `opus[1m]` | Grok flagship | Sol + high effort | Argon High |
+
+## Role defaults (unchanged aliases)
+
+| Role | `model:` |
+|------|----------|
+| synthesizer | `haiku` |
+| researcher · e2e-runner | `sonnet` |
+| planner · debugger · implementer · test-author | `inherit` |
+
+## 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/
+
+If a host cannot switch models per agent, run everything on the session model.

package/template/.issflow/routing/model-router.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Host-aware model routing. Pure decision logic; does not alter approvals,
+ * mutate host configuration, or assume UI labels are model identifiers.
+ * Hosts must inject verified capabilities and a switchModel implementation.
+ */
+const policy = require('./policy.json');
+const SUPPORTED = Object.freeze(['codex', 'claude', 'cursor']);
+const TIERS = Object.freeze(['economy', 'balanced', 'advanced']);
+const HIGH_RISK = new Set(['security', 'authentication', 'authorization', 'payments', 'secrets', 'production', 'migration']);
+
+function route(input = {}) {
+  const { provider, agent = 'orchestrator', task = '', risk = 'low', complexity = 'medium',
+    mode = policy.defaultMode, capabilities = {} } = input;
+  if (!SUPPORTED.includes(provider)) throw new Error('Unsupported provider: ' + String(provider));
+  if (!['advisory', 'automatic'].includes(mode)) throw new Error('Invalid routing mode');
+  const elevated = risk === 'high' || HIGH_RISK.has(String(task).toLowerCase());
+  let tier = policy.agents[agent] || 'balanced';
+  if (elevated || complexity === 'high') tier = 'advanced';
+  if (!TIERS.includes(tier)) tier = 'balanced';
+
+  const preference = policy.providers[provider][tier];
+  const verified = Array.isArray(capabilities.models) ? capabilities.models : [];
+  // Never invent model IDs: only an explicitly configured, verified model is selectable.
+  const configured = capabilities.tiers && capabilities.tiers[tier];
+  const modelId = configured && configured.modelId || preference.modelId;
+  const match = verified.find(m => m.id === modelId);
+  const requestedEffort = configured && configured.reasoningEffort !== undefined
+    ? configured.reasoningEffort : preference.reasoningEffort;
+  const supportedEfforts = match && Array.isArray(match.reasoningEfforts) ? match.reasoningEfforts : [];
+  const effort = requestedEffort && supportedEfforts.includes(requestedEffort) ? requestedEffort : null;
+  const eligible = !!match && (!requestedEffort || !!effort);
+  return {
+    provider, agent, tier, mode, modelId: eligible ? modelId : null,
+    reasoningEffort: eligible ? effort : null,
+    availability: eligible ? 'verified' : 'unknown',
+    action: eligible ? (mode === 'automatic' ? 'switch-request' : 'recommend') : 'inherit',
+    reason: elevated ? 'Elevated risk' : complexity === 'high' ? 'High complexity' : 'Agent default',
+    fallback: 'inherit',
+  };
+}
+
+/**
+ * Automatic mode is opt-in. switchModel must be a host-provided function
+ * returning {confirmed:true, modelId, reasoningEffort}; a request alone is
+ * never considered a successful model switch.
+ */
+async function execute(input = {}, host = {}) {
+  const decision = route(input);
+  if (decision.action !== 'switch-request') return { ...decision, switched: false };
+  if (host.supportsSwitch !== true || typeof host.switchModel !== 'function') {
+    return { ...decision, action: 'recommend', switched: false, reason: 'Host switch unavailable' };
+  }
+  try {
+    const result = await host.switchModel({ modelId: decision.modelId, reasoningEffort: decision.reasoningEffort });
+    const confirmed = result && result.confirmed === true && result.modelId === decision.modelId &&
+      (decision.reasoningEffort === null || result.reasoningEffort === decision.reasoningEffort);
+    return { ...decision, action: confirmed ? 'switched' : 'recommend', switched: !!confirmed,
+      reason: confirmed ? decision.reason : 'Host did not confirm selected model/effort' };
+  } catch (_) {
+    return { ...decision, action: 'recommend', switched: false, reason: 'Host switch failed' };
+  }
+}
+
+module.exports = { route, execute, policy };

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

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

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

@@ -0,0 +1,69 @@
+{
+  "version": 1,
+  "defaultMode": "advisory",
+  "tiers": {
+    "economy": {
+      "description": "Low-risk documentation and routine checks"
+    },
+    "balanced": {
+      "description": "Implementation and test work"
+    },
+    "advanced": {
+      "description": "Architecture, security and complex debugging"
+    }
+  },
+  "agents": {
+    "orchestrator": "balanced",
+    "researcher": "economy",
+    "planner": "advanced",
+    "implementer": "balanced",
+    "test-author": "balanced",
+    "debugger": "balanced",
+    "e2e-runner": "economy",
+    "synthesizer": "economy"
+  },
+  "providers": {
+    "codex": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": "medium"
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": "high"
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": "xhigh"
+      }
+    },
+    "claude": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      }
+    },
+    "cursor": {
+      "economy": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "balanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      },
+      "advanced": {
+        "modelId": null,
+        "reasoningEffort": null
+      }
+    }
+  }
+}

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.

package/template/.issflow/runtime/README.md

@@ -0,0 +1,150 @@
+# Local workflow checkpoint helper
+
+`workflow.js` is a dependency-free Node.js CLI and CommonJS API. It persists a
+small goal/task DAG and selects the next eligible task. It does **not** run
+commands, start workers, verify tests, grant approval, or run as a daemon. An
+agent or person still performs work under the project's existing approval rules.
+Use Node.js 18 or later. Run tests from the repository root:
+
+```sh
+node --test tests/workflow-runtime.test.js
+```
+
+## Quick start
+
+Create `goal.json`:
+
+```json
+{
+  "goal": "Implement and verify the approved change",
+  "budget": 8,
+  "tasks": [
+    { "id": "implement", "title": "Implement approved scope", "maxAttempts": 2, "units": 2 },
+    { "id": "test", "title": "Verify the final change", "dependsOn": ["implement"] },
+    { "id": "docs", "title": "Update usage examples" }
+  ]
+}
+```
+
+Choose a local checkpoint path with an existing parent directory. Do not store
+secrets in state, reasons, or evidence. Keep personal run state out of commits.
+
+```sh
+node .issflow/runtime/workflow.js init workflow-state.json goal.json
+node .issflow/runtime/workflow.js status workflow-state.json
+node .issflow/runtime/workflow.js next workflow-state.json
+```
+
+`next` atomically claims a single runnable task, records `running`, increments its
+attempt count, and charges `units` to the global budget **before** external work
+starts. It returns `{ "task": ..., "status": ... }`. It does not do the task.
+Independent tasks remain runnable when another task is blocked, waiting, or
+running. A task with unfinished dependencies cannot be claimed.
+
+After actually doing and verifying the selected work, create `result.json`:
+
+```json
+{
+  "state": "done",
+  "expectedAttempt": 1,
+  "codeRevision": "git-tree:<exact-tested-tree-or-head-plus-diff-identity>",
+  "evidence": ["test: node --test tests/example.test.js; passed; log: <path>"],
+  "expectedRevision": 1
+}
+```
+
+```sh
+node .issflow/runtime/workflow.js update workflow-state.json implement result.json
+```
+
+Replace the placeholders with real evidence and the actual tested code identity.
+`expectedAttempt` must match the claimed task's attempt number. `expectedRevision`
+is mandatory optimistic concurrency protection for every update and must match
+the **workflow** revision from the latest response, not a Git revision. If another
+task changed the workflow, reload it, reconcile the result, and then submit a new
+update; never blindly retry a stale update.
+
+## States, retries, and stopping
+
+Task states are `pending`, `running`, `blocked`, `waiting`, and `done`.
+
+- `next` is the only way to start a task. No shell command is inferred from titles.
+- A `done` update requires a running task, the current `expectedAttempt`, a
+  nonempty `codeRevision`, and at least one nonempty evidence string.
+- `blocked` and `waiting` updates require a nonempty `reason`. For example,
+  `{"state":"blocked","reason":"Needs approval for expanded file scope","expectedRevision":1}`.
+- Mark an unfinished task `pending` to explicitly release it for another attempt.
+  `{"state":"pending","expectedRevision":1}` also clears prior evidence and code identity. The next
+  claim charges another attempt and units. No refund occurs after failed work.
+- `maxAttempts` and the total budget are immutable. Exhausted tasks are not
+  claimable even if marked pending. A lower-cost independent task can still run.
+- Completed tasks and task definitions are immutable. Changed scope or invalidated
+  completed work requires a new reviewed workflow rather than silently resetting
+  limits or reusing a stale completion record.
+
+Aggregate status is `ready` if work is claimable, `done` if all tasks completed,
+`waiting` if no work is claimable but a task is running or explicitly waiting,
+and otherwise `blocked`. The `tasks[].blockers` list explains pending dependency,
+attempt-limit, and budget constraints. `next` returns `task: null` without changing
+the checkpoint if there is no runnable task. It never loops, waits, or retries.
+
+## Resume and evidence boundary
+
+Every mutation is a checkpoint. After restart, run `status` and inspect unfinished
+work. Running tasks stay running: they are never silently reclaimed or repeated.
+If the original worker is gone, inspect its effects before explicitly returning
+its task to pending. Waiting and blocked tasks also need an explicit update.
+
+Evidence is **caller-attested**. The helper binds completion to the latest attempt
+and records the supplied code identity; it does not inspect Git, compare that
+identity to the working tree, execute tests, or prove a log is truthful. The caller
+must rerun relevant checks after edits and provide the identity of the exact code
+checked, including uncommitted changes. A later edit can invalidate a prior done
+record; `status` cannot detect that. Do not present persisted `done` as proof that
+the current checkout passes. This helper is not a replacement for CI, approval
+validation, or review.
+
+## Schemas and API
+
+Plan: `{goal, budget, tasks}`. `goal` and task `title` must be nonempty strings;
+`budget`, `units`, and `maxAttempts` must be positive safe integers. Each task is
+`{id,title,dependsOn?,maxAttempts?,units?}`. Defaults are `[]`, `3`, and `1`.
+IDs match `[A-Za-z0-9][A-Za-z0-9_-]{0,99}`. There must be 1–1000 tasks. Unknown,
+duplicate, self, and cyclic dependencies are rejected. Unknown fields fail closed.
+
+Update: `{state,reason?,evidence?,codeRevision?,expectedAttempt?,expectedRevision}`.
+`state` may be pending/blocked/waiting/done, never running. `evidence` is an array
+of nonempty strings. A done update requires evidence, codeRevision, and
+expectedAttempt. Every update requires the current expectedRevision. Updates replace reason/evidence/codeRevision; omitted values
+clear them. Callers cannot mutate attempts, budgets, or definitions via updates.
+
+```js
+const workflow = require('./.issflow/runtime/workflow.js');
+workflow.init('/existing/directory/state.json', plan); // returns persisted state
+workflow.status(file);                                // derived summary
+workflow.next(file);                                  // {task, status}
+workflow.update(file, taskId, patch);                  // derived summary
+workflow.load(file);                                  // validated raw state
+workflow.validate(state);                             // validates, returns state
+workflow.summarize(state);                            // summary without file I/O
+```
+
+API calls are synchronous and throw on invalid input. CLI success emits JSON on
+stdout; failures emit an error on stderr and exit nonzero. There is no implicit
+default checkpoint path. `init` refuses to overwrite an existing file.
+
+## Persistence safeguards and limits
+
+Writes use a same-directory private temporary file, file fsync, and atomic rename.
+Exclusive `.lock` files serialize cooperating writers. A crash can leave a lock:
+verify that no writer is active before manually removing the stale lock. Locks
+are not automatically expired. Readers see the previous or next complete snapshot.
+Directory entries are not fsynced, so sudden power-loss durability is not promised.
+
+State and JSON input files are limited to 4 MiB and must be ordinary single-link
+files. Symbolic links in the file or its parent path are rejected. Parent directories
+must exist. On systems where `/tmp` is a symlink (such as macOS), use its canonical
+physical path instead. Malformed/corrupt state is rejected without replacing it. These checks
+protect against accidental redirection, not hostile users racing filesystem
+changes. Local files remain editable by their owner; validation is not cryptographic
+tamper detection. Never place the checkpoint in an untrusted shared directory.

package/template/.issflow/runtime/package.json

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

package/template/.issflow/runtime/workflow.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+
+// A checkpoint and scheduling helper, not an executor or approval authority.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const MAX_BYTES = 4 * 1024 * 1024;
+const STATES = ['pending', 'running', 'blocked', 'waiting', 'done'];
+const assert = (condition, message) => { if (!condition) throw new Error(message); };
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+const integer = (value, min = 0) => Number.isSafeInteger(value) && value >= min;
+function keys(value, allowed) {
+  assert(object(value), 'Expected an object');
+  assert(Object.keys(value).every((key) => allowed.includes(key)), 'Unknown field');
+}
+
+function validate(state) {
+  keys(state, ['version', 'goal', 'budget', 'spent', 'revision', 'tasks']);
+  assert(state.version === 1 && nonempty(state.goal), 'Invalid version or goal');
+  assert(integer(state.budget, 1) && integer(state.spent) && state.spent <= state.budget && integer(state.revision), 'Invalid budget or revision');
+  assert(Array.isArray(state.tasks) && state.tasks.length > 0 && state.tasks.length <= 1000, 'Expected 1–1000 tasks');
+  const byId = new Map();
+  for (const task of state.tasks) {
+    keys(task, ['id', 'title', 'dependsOn', 'maxAttempts', 'units', 'attempts', 'state', 'reason', 'evidence', 'codeRevision']);
+    assert(typeof task.id === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/.test(task.id) && !byId.has(task.id), 'Invalid or duplicate task id');
+    assert(nonempty(task.title) && STATES.includes(task.state), 'Invalid title or task state');
+    assert(integer(task.maxAttempts, 1) && integer(task.units, 1) && integer(task.attempts) && task.attempts <= task.maxAttempts, 'Invalid task limits');
+    assert(Array.isArray(task.dependsOn) && task.dependsOn.every((id) => typeof id === 'string') && new Set(task.dependsOn).size === task.dependsOn.length, 'Invalid dependencies');
+    assert(typeof task.codeRevision === 'string', 'Invalid code revision');
+    assert(typeof task.reason === 'string' && Array.isArray(task.evidence) && task.evidence.every(nonempty), 'Invalid reason or evidence');
+    if (['running', 'done'].includes(task.state)) assert(task.attempts > 0, 'Task has not been attempted');
+    if (['blocked', 'waiting'].includes(task.state)) assert(nonempty(task.reason), 'Blocked/waiting requires a reason');
+    if (task.state === 'done') {
+      assert(task.evidence.length > 0, 'Done requires evidence');
+      assert(nonempty(task.codeRevision), 'Done requires codeRevision');
+    }
+    byId.set(task.id, task);
+  }
+  let total = 0;
+  for (const task of state.tasks) {
+    total += task.units * task.attempts;
+    assert(Number.isSafeInteger(total), 'Budget overflow');
+    for (const id of task.dependsOn) {
+      assert(byId.has(id) && id !== task.id, 'Unknown or self dependency');
+      if (['running', 'done'].includes(task.state)) assert(byId.get(id).state === 'done', 'Dependencies are not done');
+    }
+  }
+  assert(total === state.spent, 'Spent budget does not match attempts');
+  const visiting = new Set(); const visited = new Set();
+  function visit(id) {
+    assert(!visiting.has(id), 'Dependency cycle');
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of byId.get(id).dependsOn) visit(dep);
+    visiting.delete(id); visited.add(id);
+  }
+  for (const id of byId.keys()) visit(id);
+  return state;
+}
+
+// Existing parent directory required. Refuse symlinks in every path component.
+// This protects accidental redirection, not hostile concurrent filesystem changes.
+function safePath(file) {
+  assert(nonempty(file), 'A file path is required');
+  const full = path.resolve(file);
+  let part = path.parse(full).root;
+  const pieces = full.slice(part.length).split(path.sep);
+  for (let i = 0; i < pieces.length; i++) {
+    part = path.join(part, pieces[i]);
+    let stat;
+    try { stat = fs.lstatSync(part); } catch (error) {
+      if (error.code === 'ENOENT' && i === pieces.length - 1) return full;
+      throw error;
+    }
+    assert(!stat.isSymbolicLink(), 'Symbolic links are not allowed');
+    assert(i === pieces.length - 1 ? stat.isFile() && stat.nlink === 1 : stat.isDirectory(), 'Expected an ordinary file in a directory');
+  }
+  return full;
+}
+function readJSON(file) {
+  const full = safePath(file);
+  const fd = fs.openSync(full, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+  try {
+    const stat = fs.fstatSync(fd);
+    assert(stat.isFile() && stat.nlink === 1 && stat.size <= MAX_BYTES, 'Invalid or oversized JSON file');
+    return JSON.parse(fs.readFileSync(fd, 'utf8'));
+  } finally { fs.closeSync(fd); }
+}
+function load(file) { return validate(readJSON(file)); }
+function write(file, state) {
+  validate(state);
+  const text = JSON.stringify(state, null, 2) + '\n';
+  assert(Buffer.byteLength(text) <= MAX_BYTES, 'State exceeds size limit');
+  safePath(file);
+  const temp = `${file}.${crypto.randomUUID()}.tmp`;
+  let fd;
+  try {
+    fd = fs.openSync(temp, 'wx', 0o600);
+    fs.writeFileSync(fd, text); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+    fs.renameSync(temp, file);
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+function locked(file, operation) {
+  file = safePath(file);
+  const lock = `${file}.lock`;
+  let fd;
+  try { fd = fs.openSync(lock, 'wx', 0o600); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error('State is locked; verify no writer is active before removing a stale .lock file'); throw error; }
+  try { return operation(file); }
+  finally { fs.closeSync(fd); fs.unlinkSync(lock); }
+}
+function init(file, spec) {
+  keys(spec, ['goal', 'budget', 'tasks']);
+  assert(Array.isArray(spec.tasks), 'Expected tasks');
+  const state = { version: 1, goal: spec.goal, budget: spec.budget, spent: 0, revision: 0,
+    tasks: spec.tasks.map((task) => {
+      keys(task, ['id', 'title', 'dependsOn', 'maxAttempts', 'units']);
+      return { id: task.id, title: task.title, dependsOn: task.dependsOn ?? [], maxAttempts: task.maxAttempts ?? 3,
+        units: task.units ?? 1, attempts: 0, state: 'pending', reason: '', evidence: [], codeRevision: '' };
+    }) };
+  validate(state);
+  return locked(file, (full) => { assert(!fs.existsSync(full), 'State already exists'); write(full, state); return state; });
+}
+function summarize(state) {
+  validate(state);
+  const done = new Set(state.tasks.filter((t) => t.state === 'done').map((t) => t.id));
+  const runnable = state.tasks.filter((t) => t.state === 'pending' && t.attempts < t.maxAttempts &&
+    t.units <= state.budget - state.spent && t.dependsOn.every((id) => done.has(id))).map((t) => t.id);
+  const stateName = state.tasks.every((t) => t.state === 'done') ? 'done' : runnable.length ? 'ready' :
+    state.tasks.some((t) => ['running', 'waiting'].includes(t.state)) ? 'waiting' : 'blocked';
+  return { goal: state.goal, state: stateName, revision: state.revision, budget: state.budget, spent: state.spent,
+    remaining: state.budget - state.spent, runnable, tasks: state.tasks.map((t) => ({ ...t,
+      blockers: t.state === 'pending' ? [
+        ...(t.attempts >= t.maxAttempts ? ['attempt limit reached'] : []),
+        ...(t.units > state.budget - state.spent ? ['unit budget exhausted'] : []),
+        ...t.dependsOn.filter((id) => !done.has(id)).map((id) => `dependency: ${id}`)
+      ] : [] })) };
+}
+function status(file) { return summarize(load(file)); }
+function next(file) {
+  return locked(file, (full) => {
+    const state = load(full); const summary = summarize(state);
+    if (!summary.runnable.length) return { task: null, status: summary };
+    const task = state.tasks.find((t) => t.id === summary.runnable[0]);
+    task.state = 'running'; task.reason = ''; task.evidence = []; task.codeRevision = ''; task.attempts++;
+    state.spent += task.units; state.revision++;
+    write(full, state);
+    return { task, status: summarize(state) };
+  });
+}
+function update(file, id, patch) {
+  keys(patch, ['state', 'reason', 'evidence', 'expectedRevision', 'expectedAttempt', 'codeRevision']);
+  assert(['pending', 'blocked', 'waiting', 'done'].includes(patch.state), 'Invalid update state; use next to start work');
+  if (patch.codeRevision !== undefined) assert(nonempty(patch.codeRevision), 'Invalid codeRevision');
+  if (patch.reason !== undefined) assert(typeof patch.reason === 'string', 'Invalid reason');
+  if (patch.evidence !== undefined) assert(Array.isArray(patch.evidence) && patch.evidence.every(nonempty), 'Invalid evidence');
+  return locked(file, (full) => {
+    const state = load(full);
+    assert(integer(patch.expectedRevision) && patch.expectedRevision === state.revision, 'Stale or missing expectedRevision');
+    const task = state.tasks.find((t) => t.id === id);
+    assert(task, 'Unknown task'); assert(task.state !== 'done', 'Completed tasks are immutable');
+    if (patch.state === 'done') {
+      assert(task.state === 'running', 'Only running tasks can complete');
+      assert(integer(patch.expectedAttempt, 1) && patch.expectedAttempt === task.attempts, 'Done requires the current expectedAttempt; stale evidence rejected');
+    }
+    task.state = patch.state; task.reason = patch.reason ?? ''; task.evidence = patch.evidence ?? []; task.codeRevision = patch.codeRevision ?? '';
+    state.revision++; write(full, state); return summarize(state);
+  });
+}
+function cli(args) {
+  const [command, file, arg, patch] = args;
+  if (command === 'init' && args.length === 3) return init(file, readJSON(arg));
+  if (command === 'status' && args.length === 2) return status(file);
+  if (command === 'next' && args.length === 2) return next(file);
+  if (command === 'update' && args.length === 4) return update(file, arg, readJSON(patch));
+  throw new Error('Usage: workflow.js init STATE SPEC.json | status STATE | next STATE | update STATE TASK PATCH.json');
+}
+module.exports = { init, load, validate, summarize, status, next, update };
+if (require.main === module) {
+  try { process.stdout.write(JSON.stringify(cli(process.argv.slice(2)), null, 2) + '\n'); }
+  catch (error) { process.stderr.write(`workflow: ${error.message}\n`); process.exitCode = 1; }
+}

package/template/.issflow/scripts/entry-notice.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Repo-internal PostToolUse hook (NOT shipped by create-issflow — build.js only
+// copies agents/commands/skills/hooks/istartsoft-flow/templates + README).
+// When root entry shims are edited, nudge to keep AGENTS.md / host adapters aligned.
+'use strict';
+let data = '';
+process.stdin.on('data', (c) => (data += c)).on('end', () => {
+  try {
+    const f = (JSON.parse(data || '{}').tool_input || {}).file_path || '';
+    if (/(^|[\\/])CLAUDE\.md$/.test(f)) {
+      process.stdout.write(JSON.stringify({
+        systemMessage: 'CLAUDE.md is a host shim — keep `@AGENTS.md` as the only SoT pointer. Sync BMAD if needed: save_artifact type=claude-md',
+      }));
+    } else if (/(^|[\\/])AGENTS\.md$/.test(f)) {
+      process.stdout.write(JSON.stringify({
+        systemMessage: 'AGENTS.md changed — keep it an index of `.issflow/istartsoft-flow/METHODOLOGY.md` (anti-drift: do not paste hard rules here).',
+      }));
+    }
+  } catch (_) { /* ignore malformed hook input */ }
+});

package/template/.issflow/scripts/package.json

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

package/template/.issflow/scripts/token-lint.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Portable copy — prefer project `scripts/token-lint.js` after install.
+// Same logic as repo-root scripts/token-lint.js for kit consumers.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = process.cwd();
+const TOKENS = path.join(ROOT, 'docs', 'design', 'tokens.css');
+const SCAN_GLOBS = ['src', 'app', 'components', 'pages', 'web', 'frontend', 'ui'];
+const EXT = new Set(['.css', '.scss', '.tsx', '.jsx', '.vue', '.svelte', '.html']);
+const HEX = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
+const RGB = /\brgba?\([^)]+\)/g;
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.git') continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (EXT.has(path.extname(e.name))) out.push(p);
+  }
+  return out;
+}
+
+if (!fs.existsSync(TOKENS)) {
+  console.log('token-lint: skip (no docs/design/tokens.css)');
+  process.exit(0);
+}
+
+const tokenSrc = fs.readFileSync(TOKENS, 'utf8');
+const allowed = new Set();
+for (const m of tokenSrc.matchAll(HEX)) allowed.add(m[0].toLowerCase());
+for (const m of tokenSrc.matchAll(RGB)) allowed.add(m[0].replace(/\s+/g, '').toLowerCase());
+
+const files = SCAN_GLOBS.flatMap((d) => walk(path.join(ROOT, d)));
+const hits = [];
+for (const file of files) {
+  if (path.resolve(file) === path.resolve(TOKENS)) continue;
+  const text = fs.readFileSync(file, 'utf8');
+  const rel = path.relative(ROOT, file);
+  for (const m of text.matchAll(HEX)) {
+    if (!allowed.has(m[0].toLowerCase())) hits.push(`${rel}: raw hex ${m[0]}`);
+  }
+  for (const m of text.matchAll(RGB)) {
+    const norm = m[0].replace(/\s+/g, '').toLowerCase();
+    if (!allowed.has(norm)) hits.push(`${rel}: raw color ${m[0]}`);
+  }
+}
+
+if (!hits.length) {
+  console.log(`token-lint: ok (${files.length} files)`);
+  process.exit(0);
+}
+console.error('token-lint: BLOCK — use semantic tokens from docs/design/tokens.css');
+for (const h of hits.slice(0, 40)) console.error('  ' + h);
+if (hits.length > 40) console.error(`  … +${hits.length - 40} more`);
+process.exit(1);

package/template/.issflow/skills/ui-ux-pro-max/SKILL.md

@@ -66,5 +66,10 @@ python3 .issflow/skills/ui-ux-pro-max/scripts/search.py "<query>" --stack <detec
 4. Then apply `ux-design` authoring (wireframe + cookbook). Catalogue must still
    pass: no emoji icons, tokens not raw hex in components, WCAG AA.
 
-If UX-PACK is already **approved**, read it and stop — unless the human asked to
-change the look.
+If UX-PACK is already **approved**, or STATE `design-direction:` is **locked**,
+read the locked DIRECTION/tokens and stop — unless the human asked to change the
+look (then re-picker + re-approve). Never re-roll styles at `/propose` appendix or
+`/phase` CLOSE.
+
+Direction Picker: fill `.issflow/templates/design/picker.html` placeholders only;
+do not rewrite the template chrome.