create-issflow 1.11.1 → 1.12.0

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/package.json

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

package/template/.issflow/skills/ux-design/SKILL.md

@@ -48,8 +48,9 @@ STOP and update the wireframe baseline first (a design decision -> `log-decision
 When an approved `docs/UX-PACK.md` exists, treat it as the project frame — drift
 from the pack is a defect unless the pack is re-approved.
 When `docs/design/tokens.css` exists, components must use those semantic tokens —
-raw hex / off-grid spacing in UI files is a **BLOCK** (run `node scripts/token-lint.js`
-when present). Frontend CLOSE also needs a **task check** for the primary user job.
+unapproved colors / off-grid spacing in UI files are a **BLOCK**. Run
+`node .issflow/scripts/token-lint.js` for unlisted hex/RGB colors; review semantic
+token usage and spacing separately because the script does not verify those. Frontend CLOSE also needs a **task check** for the primary user job.
 
 -----