@really-knows-ai/foundry 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 2.3.0 — 2026-04-20
+
+### Breaking
+
+- **LLM orchestration replaced with deterministic `foundry_orchestrate` tool.** The `cycle` and `sort` skills are removed; replaced by a single thin `orchestrate` skill that drives a 3-line loop.
+- **Six tools deregistered** from the plugin (still exist as internal imports for tests): `foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_configure_from_cycle`, `foundry_workfile_set`.
+- Upgrade requires clean main + no in-flight workfile (see `upgrade-foundry` skill).
+
+### Added
+
+- `foundry_orchestrate` — single tool that owns the sort → history → dispatch → finalize → history → commit loop. Atomic stage completion.
+- `scripts/orchestrate.js` — deterministic orchestration logic, composes existing internal functions.
+- Orphaned-stage detection: if orchestrate is called without `lastResult` but an active stage exists, returns `violation`. Fixes the ses_256c failure mode where an LLM skipped the post-dispatch history append and wedged the cycle.
+
+### Fixed
+
+- Root cause of all deferred HARDEN.md bugs (B, C, D, E, G) and the ses_256c bug: LLM misfollowing a deterministic protocol. Protocol now lives inside the plugin tool.
+
+### Migration
+
+See `skills/upgrade-foundry/SKILL.md` for v2.3.0 pre-flight checks. No automated state migration — complete or discard in-flight cycles on v2.2.x before upgrading.
+
+## 2.2.1 — 2026-04-20
+
+Follow-up patch addressing the five bugs deferred from v2.2.0 (see `HARDEN.md` §Deferred).
+
+### Breaking changes
+
+- **Cycle-definition deadlock config flattened.** The nested `human-appraise: {enabled, deadlock-threshold}` block is replaced by three flat keys:
+  - `human-appraise: <bool>` (default `false`) — include `human-appraise` in the stage loop every iteration
+  - `deadlock-appraise: <bool>` (default `true`) — route to `human-appraise` when LLM appraisers deadlock
+  - `deadlock-iterations: <number>` (default `5`) — deadlock threshold
+  Run the `upgrade-foundry` skill to migrate existing cycle defs — the old nested form is no longer read.
+
+### New
+
+- **`foundry_workfile_configure_from_cycle({cycleId, stages})`** — populates WORK.md frontmatter from a cycle definition in one call. Replaces the prior 6–7 sequential `foundry_workfile_set` calls at cycle start. Defaults for `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, and `models` now live in plugin code rather than skill prose.
+- **`foundry_artefacts_list({cycle})`** — optional cycle filter. Callers should always pass the current cycle to avoid picking up stale rows from prior aborted sessions.
+
+### Fixed
+
+- **Bug B — deadlock routing.** Sort now reads the flat deadlock keys from WORK.md frontmatter and routes to `human-appraise` on deadlock (either an existing `human-appraise:<cycle>` stage in `stages`, or a synthesized one). When `deadlock-appraise: false`, deadlock marks the cycle `blocked`.
+- **Bug C — stale artefact validation.** `quench`, `appraise`, and `human-appraise` skills now pass the current cycle to `foundry_artefacts_list`, scoping validation to artefacts produced by the current cycle instead of every row that has ever landed in WORK.md.
+- **Bug D — overwriting WORK.md.** The `flow` skill now calls `foundry_workfile_get` before `foundry_workfile_create` and prompts the user to resume, discard, or abort when an existing workfile is detected. Silent overwrite is not offered; resume requires matching `flow` and `cycle`.
+- **Bug E — missing micro-commits.** `foundry_sort` now returns `{route: 'violation'}` when `WORK.md`, `WORK.history.yaml`, or anything under `.foundry/` has uncommitted changes at the start of a sort call and history is non-empty. Structurally enforces the one-commit-per-stage contract that previously lived only in skill prose. First sort of a cycle is exempt (empty history).
+- **Bug G — workfile setup boilerplate.** See `foundry_workfile_configure_from_cycle` above.
+
+### Migration
+
+Run the `upgrade-foundry` skill to migrate cycle definitions to the flat deadlock keys (Bug B). No other migration required — WORK.md, `.foundry/`, and feedback state are forward-compatible.
+
+## 2.2.0 — 2026-04-19
+
+### Breaking changes
+
+- **`foundry_artefacts_add` removed.** Artefact registration now happens exclusively via `foundry_stage_finalize` after a forge stage closes.
+- **`foundry_artefacts_set_status` no longer accepts `draft`.** Only `done` and `blocked` are valid. New artefacts are registered as `draft` automatically by `stage_finalize`.
+- **Feedback / artefact / workfile mutation tools now enforce stage-lock preconditions.** Tools callable by subagents require an active stage matching their role; tools callable by the orchestrator require no active stage. Out-of-band calls return a structured error instead of mutating state.
+- **Feedback state machine strictly enforced.** `approved` is terminal. `quench` cannot approve/reject `wont-fix` items. See `HARDEN.md` §4 for the full matrix.
+- **`foundry_sort` dispatchable routes now return a `token` field.** Subagents must redeem the token via `foundry_stage_begin`; forged or replayed tokens are rejected.
+
+### New
+
+- **`foundry_stage_begin(stage, cycle, token)`** — subagents open a work stage by consuming a single-use HMAC-signed token.
+- **`foundry_stage_end(summary)`** — subagents close a stage; preserves `baseSha` for finalize.
+- **`foundry_stage_finalize(cycle)`** — orchestrator verifies stage output against allowed file patterns, registers matching files as draft artefacts, rejects stray writes with `{error: "unexpected_files", files: [...]}`.
+- **`.foundry/` state directory** (gitignored) — holds `.secret` (per-worktree HMAC key, mode 0600), `active-stage.json` (present only during an active stage), `last-stage.json` (for finalize lookup).
+
+### Fixed
+
+- Normalized `maxIterations` → `max-iterations` across workfile read/write paths (previously inconsistent between flow and cycle skills, causing latent deadlock-detection issues).
+
+### Migration
+
+Upgrade with the `upgrade-foundry` skill. `.foundry/` is created automatically on first plugin boot; `.secret` is generated idempotently. No data migration required — existing `WORK.md` and `foundry/*` configs are compatible.

package/docs/work-spec.md

@@ -25,8 +25,8 @@ The `stages` list is the happy path. Sort follows it but loops back to `forge` w
 
 - `flow` — set by the foundry flow skill at foundry flow start, never changes
 - `cycle` — set by the foundry flow skill when starting each foundry cycle
-- `stages` — set by the foundry cycle skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
-- `max-iterations` — set by the foundry cycle skill (default 3, could be overridden in foundry cycle definition)
+- `stages` — set by the orchestrate skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
+- `max-iterations` — set by the orchestrate skill (default 3, could be overridden in foundry cycle definition)
 
 ## Sections
 
@@ -96,9 +96,9 @@ Grouped by artefact file path. Each item is a checklist entry with a tag indicat
 | Section | Written by | Updated by |
 |---------|-----------|------------|
 | Frontmatter (`flow`) | `foundry_workfile_create` (flow skill) | nobody |
-| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (cycle skill) | `foundry_workfile_set` (reset on each new cycle) |
+| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (orchestrate skill) | `foundry_workfile_set` (reset on each new cycle) |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (cycle skill) |
+| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (orchestrate skill) |
 | Feedback | `foundry_feedback_add` (quench/appraise/hitl) | `foundry_feedback_action`/`foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench/appraise/hitl) |
 
 ## WORK.history.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",
@@ -40,6 +40,7 @@
     "docs/concepts.md",
     "docs/getting-started.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ]
 }

package/scripts/lib/artefacts.js

@@ -86,6 +86,12 @@ export function addArtefactRow(text, { file, type, cycle, status }) {
  * @returns {string} Updated text
  */
 export function setArtefactStatus(text, file, newStatus) {
+  if (newStatus === 'draft') {
+    throw new Error('status draft not permitted; use stage_finalize for registration');
+  }
+  if (!['done', 'blocked'].includes(newStatus)) {
+    throw new Error(`invalid status: ${newStatus}`);
+  }
   const lines = text.split('\n');
   let inTable = false;
   let found = false;

package/scripts/lib/feedback-transitions.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+
+// Matrix: [current][target] => set of allowed stageBases
+const MATRIX = {
+  open:       { actioned: ['forge'], 'wont-fix': ['forge'] },
+  actioned:   { approved: ['quench', 'appraise', 'human-appraise'], rejected: ['quench', 'appraise', 'human-appraise'] },
+  'wont-fix': { approved: ['appraise', 'human-appraise'], rejected: ['appraise', 'human-appraise'] },
+  rejected:   { actioned: ['forge'], 'wont-fix': ['forge'] },
+  approved:   {}, // terminal
+};
+
+export function validateTransition(current, target, stageBase) {
+  const row = MATRIX[current];
+  if (!row) return { ok: false, reason: `unknown state: ${current}` };
+  const allowedStages = row[target];
+  if (!allowedStages) return { ok: false, reason: `invalid transition ${current} → ${target}` };
+  if (!allowedStages.includes(stageBase)) {
+    return { ok: false, reason: `stage ${stageBase} cannot transition ${current} → ${target}` };
+  }
+  return { ok: true };
+}
+
+export function hashText(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}

package/scripts/lib/feedback.js

@@ -3,6 +3,7 @@
  */
 
 import { extractAllTags } from './tags.js';
+import { validateTransition, hashText } from './feedback-transitions.js';
 
 // ---------------------------------------------------------------------------
 // Parsing
@@ -85,6 +86,16 @@ export function parseFeedback(text, cycle, artefacts) {
 // ---------------------------------------------------------------------------
 
 export function addFeedbackItem(text, file, itemText, tag) {
+  // Dedup by (file, tag, text hash): if any existing item under this file
+  // heading has the same tag and the same itemText, return without mutating.
+  const existing = collectItemsForFile(text, file);
+  const h = hashText(itemText);
+  for (const ex of existing) {
+    if (ex.tags.includes(`#${tag}`) && hashText(ex.coreText) === h) {
+      return { text, deduped: true };
+    }
+  }
+
   const newItem = `- [ ] ${itemText} #${tag}`;
   const lines = text.split('\n');
 
@@ -111,7 +122,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (feedbackIdx === -1) {
     // No Feedback section — append one
     lines.push('', '## Feedback', '', `### ${file}`, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find the file heading within the feedback section
@@ -135,7 +146,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (fileIdx === -1) {
     // File heading doesn't exist — add it before section end
     lines.splice(sectionEnd, 0, '', fileHeading, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find last item under this file heading
@@ -149,23 +160,23 @@ export function addFeedbackItem(text, file, itemText, tag) {
   }
 
   lines.splice(insertIdx, 0, newItem);
-  return lines.join('\n');
+  return { text: lines.join('\n'), deduped: false };
 }
 
-export function actionFeedbackItem(text, file, index) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function actionFeedbackItem(text, file, index, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'actioned', stageBase, (line) =>
     line.replace('- [ ]', '- [x]')
   );
 }
 
-export function wontfixFeedbackItem(text, file, index, reason) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function wontfixFeedbackItem(text, file, index, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'wont-fix', stageBase, (line) =>
     line.replace('- [ ]', '- [~]') + ` | wont-fix: ${reason}`
   );
 }
 
-export function resolveFeedbackItem(text, file, index, resolution, reason) {
-  return transformFeedbackItem(text, file, index, (line) => {
+export function resolveFeedbackItem(text, file, index, resolution, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, resolution, stageBase, (line) => {
     if (resolution === 'approved') {
       return line + ' | approved';
     }
@@ -257,6 +268,132 @@ export function detectDeadlocks(feedback, history, threshold = 3) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Collect feedback items under a specific file heading, returning the parsed
+ * representation plus the "core text" (item body with tag and trailing resolution
+ * stripped) for dedup hashing.
+ */
+function collectItemsForFile(text, file) {
+  const items = [];
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+
+  for (const line of lines) {
+    const stripped = line.trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      const parsed = parseFeedbackItem(stripped);
+      // Strip checkbox, tags, and trailing `| approved` / `| rejected: ...` /
+      // `| wont-fix: ...` to get the core author-supplied text for dedup.
+      let core = stripped.replace(/^- \[[ x~]\]\s*/, '');
+      core = core.replace(/\s*\|\s*(approved|rejected[^|]*|wont-fix[^|]*)\s*$/, '');
+      for (const t of parsed.tags) {
+        core = core.replace(t, '');
+      }
+      core = core.trim();
+      items.push({ line: stripped, state: parsed.state, tags: parsed.tags, coreText: core });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Read the line at (file, index) and return its current feedback state
+ * (or null if not found).
+ */
+function readItemState(text, file, index) {
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+  let fileIndex = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const stripped = lines[i].trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      fileIndex = 0;
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      if (fileIndex === index) {
+        const parsed = parseFeedbackItem(stripped);
+        // Map parseFeedbackItem's (state, resolved) pair onto state-machine states:
+        // - `| approved` → terminal "approved"
+        // - `| rejected` → "rejected" (parseFeedbackItem already sets this)
+        // - bare `[x]`   → "actioned"
+        // - bare `[~]`   → "wont-fix"
+        // - bare `[ ]`   → "open"
+        if (parsed.resolved) return 'approved';
+        return parsed.state;
+      }
+      fileIndex++;
+    }
+  }
+  return null;
+}
+
+function transformFeedbackItemWithValidation(text, file, index, target, stageBase, transform) {
+  if (stageBase !== undefined) {
+    const current = readItemState(text, file, index);
+    if (!current) {
+      return { ok: false, error: `feedback item not found: file=${file} index=${index}` };
+    }
+    const v = validateTransition(current, target, stageBase);
+    if (!v.ok) {
+      return { ok: false, error: v.reason };
+    }
+    const updated = transformFeedbackItem(text, file, index, transform);
+    return { ok: true, text: updated };
+  }
+  // Backward-compatible path: return plain string.
+  return transformFeedbackItem(text, file, index, transform);
+}
+
 function transformFeedbackItem(text, file, index, transform) {
   const lines = text.split('\n');
   let inFeedback = false;

package/scripts/lib/finalize.js

@@ -0,0 +1,41 @@
+// scripts/lib/finalize.js
+import { execSync } from 'node:child_process';
+import { minimatch } from 'minimatch';
+
+const TOOL_MANAGED = [
+  'WORK.md',
+  'WORK.history.yaml',
+];
+const TOOL_MANAGED_PREFIX = ['.foundry/'];
+
+function changedFiles(cwd, baseSha) {
+  const tracked = execSync(`git diff --name-only ${baseSha} HEAD`, { cwd }).toString().split('\n').filter(Boolean);
+  const diffUnstaged = execSync('git diff --name-only', { cwd }).toString().split('\n').filter(Boolean);
+  const untracked = execSync('git ls-files --others --exclude-standard', { cwd }).toString().split('\n').filter(Boolean);
+  return [...new Set([...tracked, ...diffUnstaged, ...untracked])];
+}
+
+function isToolManaged(f) {
+  if (TOOL_MANAGED.includes(f)) return true;
+  return TOOL_MANAGED_PREFIX.some(p => f.startsWith(p));
+}
+
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, registerArtefact }) {
+  const files = changedFiles(cwd, baseSha).filter(f => !isToolManaged(f));
+  const allowedPatterns = stageBase === 'forge'
+    ? (artefactTypes[cycleDef.outputArtefactType]?.filePatterns ?? [])
+    : [];
+  const unexpected = [];
+  const matched = [];
+  for (const f of files) {
+    const hit = allowedPatterns.find(p => minimatch(f, p));
+    if (hit) matched.push(f);
+    else unexpected.push(f);
+  }
+  if (unexpected.length) return { ok: false, error: 'unexpected_files', files: unexpected };
+  const artefacts = matched.map(file => {
+    registerArtefact({ file, type: cycleDef.outputArtefactType, status: 'draft' });
+    return { file, type: cycleDef.outputArtefactType, status: 'draft' };
+  });
+  return { ok: true, artefacts };
+}

package/scripts/lib/history.js

@@ -18,7 +18,7 @@ export function loadHistory(historyPath, cycle, io) {
 /**
  * Append a history entry with auto-generated ISO timestamp.
  */
-export function appendEntry(historyPath, { cycle, stage, iteration, comment }, io) {
+export function appendEntry(historyPath, { cycle, stage, iteration, comment, route }, io) {
   if (iteration == null) throw new Error('iteration is required');
   if (!comment) throw new Error('comment is required');
 
@@ -27,13 +27,15 @@ export function appendEntry(historyPath, { cycle, stage, iteration, comment }, i
     existing = yaml.load(io.readFile(historyPath)) || [];
   }
 
-  existing.push({
+  const entry = {
     cycle,
     stage,
     iteration,
     comment,
     timestamp: new Date().toISOString(),
-  });
+  };
+  if (route !== undefined) entry.route = route;
+  existing.push(entry);
 
   io.writeFile(historyPath, yaml.dump(existing));
 }
@@ -45,3 +47,13 @@ export function getIteration(historyPath, cycle, io) {
   const history = loadHistory(historyPath, cycle, io);
   return history.filter(e => (e.stage || '').split(':')[0] === 'forge').length;
 }
+
+/**
+ * Return the `route` field from the most recent `sort` history entry for a
+ * given cycle, or null if none exists.
+ */
+export function readLastSortRoute(historyPath, cycle, io) {
+  const entries = loadHistory(historyPath, cycle, io).filter(e => e.stage === 'sort');
+  if (!entries.length) return null;
+  return entries[entries.length - 1].route ?? null;
+}

package/scripts/lib/pending.js

@@ -0,0 +1,18 @@
+export function createPendingStore() {
+  const map = new Map();
+  return {
+    add(nonce, meta) { map.set(nonce, meta); },
+    consume(nonce) {
+      const meta = map.get(nonce);
+      if (!meta) return null;
+      map.delete(nonce);
+      if (meta.exp < Date.now()) return null;
+      return meta;
+    },
+    size() {
+      const now = Date.now();
+      for (const [k, v] of map) if (v.exp < now) map.delete(k);
+      return map.size;
+    },
+  };
+}

package/scripts/lib/secret.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+export function readOrCreateSecret(directory) {
+  const dir = join(directory, '.foundry');
+  const file = join(dir, '.secret');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const bytes = randomBytes(32);
+  let fd;
+  try {
+    fd = openSync(file, 'wx', 0o600);
+  } catch (err) {
+    if (err.code === 'EEXIST') return readFileSync(file);
+    throw err;
+  }
+  try {
+    writeSync(fd, bytes);
+  } finally {
+    closeSync(fd);
+  }
+  return bytes;
+}

package/scripts/lib/stage-guard.js

@@ -0,0 +1,25 @@
+// scripts/lib/stage-guard.js
+import { readActiveStage } from './state.js';
+
+export function stageBaseOf(stage) {
+  const i = stage.indexOf(':');
+  return i === -1 ? stage : stage.slice(0, i);
+}
+
+export function requireNoActiveStage(io) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: true };
+  return { ok: false, error: `tool requires no active stage; current: ${a.stage}` };
+}
+
+export function requireActiveStage(io, { stageBase, cycle } = {}) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: false, error: `tool requires active stage; current: none` };
+  if (stageBase && stageBaseOf(a.stage) !== stageBase) {
+    return { ok: false, error: `tool requires active ${stageBase} stage; current: ${a.stage}` };
+  }
+  if (cycle && a.cycle !== cycle) {
+    return { ok: false, error: `tool requires active stage in cycle ${cycle}; current cycle: ${a.cycle}` };
+  }
+  return { ok: true, active: a };
+}

package/scripts/lib/state.js

@@ -0,0 +1,31 @@
+const ACTIVE = '.foundry/active-stage.json';
+const LAST = '.foundry/last-stage.json';
+const DIR = '.foundry';
+
+export function ensureFoundryDir(io) {
+  if (!io.exists(DIR)) io.mkdir(DIR);
+}
+
+export function readActiveStage(io) {
+  if (!io.exists(ACTIVE)) return null;
+  return JSON.parse(io.readFile(ACTIVE));
+}
+
+export function writeActiveStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(ACTIVE, JSON.stringify(payload, null, 2));
+}
+
+export function clearActiveStage(io) {
+  io.unlink(ACTIVE);
+}
+
+export function readLastStage(io) {
+  if (!io.exists(LAST)) return null;
+  return JSON.parse(io.readFile(LAST));
+}
+
+export function writeLastStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(LAST, JSON.stringify(payload, null, 2));
+}

package/scripts/lib/token.js

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function signToken(payload, secret) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+export function verifyToken(token, secret) {
+  if (typeof token !== 'string' || !token.includes('.')) return { ok: false, reason: 'malformed' };
+  const [body, mac] = token.split('.');
+  if (!body || !mac) return { ok: false, reason: 'malformed' };
+  const expected = createHmac('sha256', secret).update(body).digest();
+  let given;
+  try { given = Buffer.from(mac, 'base64url'); } catch { return { ok: false, reason: 'malformed' }; }
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  let payload;
+  try { payload = JSON.parse(Buffer.from(body, 'base64url').toString()); }
+  catch { return { ok: false, reason: 'malformed' }; }
+  if (typeof payload.exp !== 'number' || payload.exp < Date.now()) {
+    return { ok: false, reason: 'expired' };
+  }
+  return { ok: true, payload };
+}

package/scripts/lib/workfile.js

@@ -11,7 +11,16 @@ import yaml from 'js-yaml';
 export function parseFrontmatter(text) {
   const match = text.match(/^---\n(.+?)\n---/s);
   if (!match) return {};
-  return yaml.load(match[1]) || {};
+  const fm = yaml.load(match[1]) || {};
+  // Normalize: on-disk canonical key is `max-iterations` (kebab).
+  // Tolerate legacy `maxIterations` (camel) by rewriting on read.
+  if (fm.maxIterations !== undefined) {
+    if (fm['max-iterations'] === undefined) {
+      fm['max-iterations'] = fm.maxIterations;
+    }
+    delete fm.maxIterations;
+  }
+  return fm;
 }
 
 export function writeFrontmatter(fields) {
@@ -25,6 +34,8 @@ export function getFrontmatterField(text, key) {
 }
 
 export function setFrontmatterField(text, key, value) {
+  // Coerce legacy camelCase key to canonical kebab form on write.
+  if (key === 'maxIterations') key = 'max-iterations';
   const fm = parseFrontmatter(text);
   fm[key] = value;
   const fmBlock = writeFrontmatter(fm);