@really-knows-ai/foundry 3.5.8 → 3.6.0

package/dist/docs/work-spec.md

@@ -32,9 +32,8 @@ flow: <flow-id>
 cycle: <current-cycle-id>
 stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
 max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
+always-human-appraise: false
+deadlock-human-appraise: true
 models:
   forge: anthropic/claude-opus-4.7
   appraise: openai/gpt-5
@@ -46,21 +45,21 @@ assay:
 Fields:
 - `flow` — the foundry flow being executed.
 - `cycle` — the current cycle id.
-- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff any applicable law declares validators; `human-appraise` is included iff the cycle sets `human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
+- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, `human-appraise`, or `assay`) and `alias` is a human-readable name for what that stage does in this cycle. The list is derived from the cycle and artefact type: `forge` and `appraise` are always included; `quench` is included iff any applicable law declares validators; `human-appraise` is included iff the cycle sets `always-human-appraise: true`; and `assay` is included iff the cycle declares an `assay.extractors` block.
 - `max-iterations` — how many forge passes before the cycle is blocked (default: 3).
-- `human-appraise` — run human-appraise every iteration (default: `false`).
-- `deadlock-appraise` — route to human-appraise when LLM appraisers deadlock (default: `true`).
-- `deadlock-iterations` — deadlock threshold (default: 5).
+- `always-human-appraise` — run human-appraise every iteration (default: `false`).
+- `deadlock-human-appraise` — route to human-appraise when the iteration count reaches `max-iterations` (default: `true`).
 - `models` — optional per-stage model overrides; individual appraisers may further override via their own `model` field.
 - `assay.extractors` — optional list of extractor names (defined under `foundry/memory/extractors/`) to run at iteration 0 before the first forge. Requires `foundry/memory/` to be initialized; cycle fails to load otherwise.
 
-The `stages` list is the happy path. Sort follows it, loops back to `forge` when unresolved feedback demands it, and may insert `human-appraise` on deadlock. If `assay` is configured, it runs once at iteration 0 before the route begins.
+The `stages` list is the happy path. Sort follows it, loops back to `forge` when unresolved feedback demands it, and routes to `human-appraise` when the iteration count reaches `max-iterations` (provided `deadlock-human-appraise` is `true`). If `assay` is configured, it runs once at iteration 0 before the route begins.
 
 ### Who sets what
 
 - `flow`, `cycle` — set by the `flow` skill via `foundry_workfile_create` at flow start and updated as the flow advances between cycles.
 - `goal` — written once by the `flow` skill when `WORK.md` is created.
-- `stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`, `assay` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
+- `stages`, `max-iterations`, `always-human-appraise`, `deadlock-human-appraise`, `models`, `assay` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
+- The frontmatter may also contain `status: failed` with a `reason` when the flow enters a failed state, locking all mutation tools.
 
 ## Sections
 
@@ -68,22 +67,6 @@ The `stages` list is the happy path. Sort follows it, loops back to `forge` when
 
 Free text describing what the foundry flow is producing and any context the human provided. Written once at foundry flow start, not modified after.
 
-### Artefacts
-
-A table tracking every artefact produced by the foundry flow. The generator (`createWorkfile` in `src/scripts/lib/workfile.js`) writes the table immediately after the `# Goal` body — there is no `# Artefacts` heading. The orchestrator's internal finalise step appends rows for matching output files; authoring tools should not edit the artefacts table directly.
-
-```markdown
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/login-change.md | petition | write-petition | draft |
-| features/login-change.feature | gherkin | petition-to-gherkin | draft |
-```
-
-Statuses:
-- `draft` — artefact exists but has not cleared all stages
-- `done` — artefact has cleared all stages
-- `blocked` — artefact hit iteration limit or a violation
-
 ## WORK.feedback.yaml
 
 The flow run owns one `WORK.feedback.yaml` file alongside `WORK.md` and
@@ -113,40 +96,48 @@ Each history snapshot:
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `state` | enum | yes | `open \| actioned \| wont-fix \| rejected \| deadlocked \| resolved` |
+| `state` | enum | yes | `open \| actioned \| wont-fix \| rejected \| resolved` |
 | `stage` | string (`base:alias`) or literal `sort` | yes | Who performed the transition |
 | `cycle` | string | yes | Cycle id at the time of the transition |
 | `timestamp` | ISO-8601 UTC with ms | yes | |
-| `reason` | string | conditional | Required on `rejected`, `wont-fix`, `deadlocked`, `resolved`; forbidden on `open`; optional on `actioned` |
+| `reason` | string | conditional | Required on `rejected`, `wont-fix`; forbidden on `open`; optional on `actioned`, `resolved` |
 
 `history[0]` is always the current state; new snapshots are prepended.
 `resolved` is terminal.
 
 ### State machine
 
-Feedback items flow through a six-state lifecycle: `open` (newly raised), `actioned` (forge has addressed it), `wont-fix` (forge declined subjective feedback with justification), `rejected` (appraiser or human overruled the wont-fix), `deadlocked` (sort detected repeated forge/appraise iterations on the same item), and `resolved` (approved by the item's originating stage or human override). Transitions are source-based: the legal moves depend on what stage created the item and who is trying to transition it. The feedback state machine is the engine that routes work between cycles.
+Feedback items flow through a five-state lifecycle: `open` (newly raised), `actioned` (forge has addressed it), `wont-fix` (forge declined subjective feedback with justification), `rejected` (appraiser or human overruled the wont-fix), and `resolved` (approved by the item's originating stage or human override). Transitions are source-based: the legal moves depend on what stage created the item and who is trying to transition it. The feedback state machine is the engine that routes work between cycles.
 
-The six states and the legal transitions are:
+The five states and the legal transitions are:
 
-| From \ Caller | forge (any source) | source-stage (quench / appraise / human-appraise where stageId === item.source) | sort | human-appraise (override authority, any source) |
-|---|---|---|---|---|
-| `open` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | -> `deadlocked` (if depth >= threshold) | — |
-| `rejected` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | -> `deadlocked` (if depth >= threshold) | — |
-| `actioned` | — | -> `{resolved, rejected}` | -> `deadlocked` (if depth >= threshold) | -> `{resolved, rejected}` |
-| `wont-fix` | — | -> `{resolved, rejected}` | -> `deadlocked` (if depth >= threshold) | -> `{resolved, rejected}` |
-| `deadlocked` | — | — | — | -> `{resolved, rejected}` |
-| `resolved` | — | — | — | — (terminal) |
+| From \ Caller | forge (any source) | source-stage (quench / appraise / human-appraise where stageId === item.source) | human-appraise (override authority, any source) |
+|---|---|---|---|
+| `open` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | — |
+| `actioned` | — | -> `{resolved, rejected}` | -> `{resolved, rejected}` |
+| `wont-fix` | — | -> `{resolved, rejected}` | -> `{resolved, rejected}` |
+| `rejected` | -> `actioned` always; -> `wont-fix` only if `item.source` base is `appraise` | — | — |
+| `resolved` | — | — | — (terminal) |
 
 Notes:
 
-- `source-stage` column applies when the caller's stage id exactly matches `item.source` (e.g. `appraise:write-check` resolving an item it created). `human-appraise` override authority (last column) applies regardless of `item.source` and is the only path that can transition out of `deadlocked`.
+- `source-stage` column applies when the caller's stage id exactly matches `item.source` (e.g. `appraise:write-check` resolving an item it created). `human-appraise` override authority (last column) applies regardless of `item.source` and operates only on items in `actioned` or `wont-fix` state (or `deadlocked` for backward compatibility with existing feedback files).
 - **Forge `wont-fix` scope.** When `item.source` base is `quench` (objective validation failure) or `human-appraise` (direct user instruction), forge may not `wont-fix` — it must `actioned`. Only `appraise`-sourced items are wont-fix-able by forge. This replaces the earlier tag-based restriction on `validation` / `human` tags.
-- `tag` is categorical and display-only. The state machine consults `source`, not tags; `validation` / `human` tag-based restrictions are legacy and do not apply.
-- **Reason required on** `rejected`, `wont-fix`, `deadlocked`, `resolved`. **Forbidden on** `open`. **Optional on** `actioned` (the code change is the reason).
-- Sort is the only writer of `state: deadlocked`; it writes these via its internal pass, not through the plugin API.
+- `tag` is categorical and display-only. The state machine consults `source`, not tags.
+- **Reason required on** `rejected`, `wont-fix`. **Forbidden on** `open`. **Optional on** `actioned`, `resolved`.
+- Sort does not write `state: deadlocked`. Deadlock detection in sort uses iteration count comparison against `max-iterations` and `deadlock-human-appraise` to decide whether to route to human-appraise, not per-item deadlock state. The feedback-transition validator still recognises `deadlocked` state for backward compatibility with existing feedback files.
 
 This section is the authoritative specification of the feedback state machine.
 
+### Feedback tag gates
+
+`foundry_feedback_add` enforces per-stage tag rules:
+
+- **forge** and **assay** stages cannot add feedback; the tool returns an error.
+- **quench** and **appraise** stages require tags starting with `law:`.
+- **human-appraise** requires the tag `human`.
+- Quench validator feedback uses the tag format `law:<law-id>:<validator-id>`.
+
 ### Transitions are made via the plugin API
 
 No direct yaml editing. Every state change goes through one of:
@@ -166,10 +157,10 @@ A crash between the two steps leaves the live file untouched.
 | Section | Written by | Updated by |
 |---------|-----------|------------|
 | Frontmatter (`flow`, `cycle`) | `foundry_workfile_create` (flow skill) | updated in place as the flow advances between cycles |
-| Frontmatter (`stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
+| Frontmatter (`stages`, `max-iterations`, `always-human-appraise`, `deadlock-human-appraise`, `models`, `assay`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
 | Artefact files | forge stage writes files on disk | git tracks file changes; cycle-level state records completion or failure |
-| `WORK.feedback.yaml` | `foundry_feedback_add` (`quench` / `appraise` / `human-appraise`) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (source stage / human-appraise override); sort writes only deadlocked snapshots |
+| `WORK.feedback.yaml` | `foundry_feedback_add` (`quench` / `appraise` / `human-appraise`) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (source stage / human-appraise override) |
 | `WORK.history.yaml` | `foundry_orchestrate` | `foundry_orchestrate` |
 
 Artefact files are discovered from branch changes matching the cycle output type's `file-patterns`.
@@ -231,7 +222,8 @@ A separate file (`WORK.history.yaml`) alongside WORK.md. Append-only log of ever
 | `timestamp` | ISO-8601 UTC with ms | yes | |
 | `seq` | integer | yes on write | Monotonic per file; sort tiebreaker for same-ms entries |
 | `route` | string | conditional | Only on `stage: sort` entries; records the route decision. Throws if set on a non-sort entry |
-| `open_feedback` | integer | yes on write | Count of non-resolved items in `WORK.feedback.yaml` at the time of write; deadlocked items are counted |
+| `open_feedback` | integer | yes on write | Count of non-resolved items in `WORK.feedback.yaml` at the time of write |
+| `changed_files` | array of strings | conditional | Only on stage entries; records the list of files detected as changed by the finalise step for that stage |
 
 ### Rules
 
@@ -265,9 +257,8 @@ flow: make-haiku
 cycle: haiku-creation
 stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
 max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
+always-human-appraise: false
+deadlock-human-appraise: true
 ---
 
 # Goal
@@ -275,9 +266,4 @@ deadlock-iterations: 5
 Write a haiku about autumn rain. Should evoke loneliness
 and the sound of rain on leaves.
 
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/autumn-rain-haiku.md | petition | haiku-ideation | done |
-| haiku/autumn-rain.md | haiku | haiku-creation | draft |
-
 ```

package/dist/scripts/appraise-module.js

@@ -11,8 +11,9 @@
  * so the orchestrator can re-sort and determine the next action.
  */
 
-import { getArtefactFiles } from './lib/artefacts.js';
+import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
 import { selectAppraisers, getLaws, getCycleDefinition } from './lib/config.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
 import yaml from 'js-yaml';
 
 // ---------------------------------------------------------------------------
@@ -39,6 +40,8 @@ export async function gatherAppraiseContext(ctx) {
     return violation('cycleId is required', []);
   }
 
+  await resolveStaleAppraiseFeedback(ctx);
+
   const cd = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
   const outputType = cd.frontmatter['output-type'];
   if (!outputType) {
@@ -147,11 +150,51 @@ function emptyDispatch(cycleId) {
 // ---------------------------------------------------------------------------
 
 /**
- * Consolidate appraiser results after all subagents have run.
+ * Resolve stale feedback items whose artefact version does not match the
+ * current on-disk version. Items from this stage's source base with a
+ * mismatched artefact_version are auto-resolved as superseded.
+ */
+export function resolveStaleFeedback(items, currentVersion, stageBase, feedback, cycle) {
+  for (const item of items) {
+    if (shouldSkipStaleResolve(item, currentVersion, stageBase)) continue;
+    const reason = `superseded by forge revision ${currentVersion}`;
+    feedback.autoResolve({ id: item.id, reason, cycle });
+  }
+}
+
+function shouldSkipStaleResolve(item, currentVersion, stageBase) {
+  if (item.history[0].state === 'resolved') return true;
+  const itemBase = typeof item.source === 'string' ? item.source.split(':')[0] : '';
+  if (itemBase !== stageBase) return true;
+  if (item.artefact_version === currentVersion) return true;
+  return false;
+}
+
+/**
+ * Resolve stale appraise-sourced feedback. Errors propagate to the caller
+ * which must handle them (e.g. by returning a violation).
+ */
+async function resolveStaleAppraiseFeedback(ctx) {
+  try {
+    const cycleDef = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+    const outputType = cycleDef.frontmatter['output-type'];
+    if (outputType) {
+      const store = openFeedbackStore('WORK.feedback.yaml', ctx.io);
+      const currentVersion = await computeArtefactVersion(ctx.foundryDir, outputType, ctx.io, ctx.cwd);
+      resolveStaleFeedback(store.list(), currentVersion, 'appraise', store, ctx.cycleId);
+    }
+  } catch {
+    // Graceful degrade — stale resolution is best-effort.
+    // The orchestrator handles IO failures at the cycle level.
+  }
+}
+
+/**
+ * Consolidate appraiser results and finalise the appraise stage.
  *
- * Parses each successful output for structured issues, unions across
- * appraisers, de-duplicates by (file, law-id, issue text), posts feedback,
- * resolves stale prior appraise feedback, and finalises the stage.
+ * Called by orchestrator after all appraisers have completed. Parses results,
+ * posts combined feedback, resolves prior appraise feedback, and advances
+ * the cycle to the next stage via finalize.
  *
  * @param {object} ctx
  * @param {Array<{ok: boolean, output?: string, error?: string}>} lastResults
@@ -170,10 +213,13 @@ export async function consolidateAppraise(ctx, lastResults) {
     return violation('All appraisers failed to evaluate the artefact', []);
   }
 
+  await resolveStaleAppraiseFeedback(ctx);
+
   const consolidated = parseConsolidated(successful);
   const stageId = `appraise:${ctx.cycleId}`;
 
-  postConsolidatedFeedback(ctx, consolidated);
+  const artefactVersion = await computeAppraiseArtefactVersion(ctx);
+  postConsolidatedFeedback(ctx, consolidated, artefactVersion);
   resolvePriorAppraise(ctx, consolidated, stageId);
 
   const summary = buildConsolidateSummary(consolidated.length);
@@ -219,15 +265,31 @@ function deduplicateIssues(issues) {
   return result;
 }
 
+/**
+ * Compute artefact version for the appraise cycle so feedback items carry
+ * a version hash and are not auto-resolved by sort as legacy items.
+ */
+async function computeAppraiseArtefactVersion(ctx) {
+  try {
+    const cycleDef = await getCycleDefinition(ctx.foundryDir, ctx.cycleId, ctx.io);
+    const outputType = cycleDef.frontmatter['output-type'];
+    if (outputType) {
+      return await computeArtefactVersion(ctx.foundryDir, outputType, ctx.io, ctx.cwd);
+    }
+  } catch { /* skip */ }
+  return undefined;
+}
+
 /**
  * Post one feedback item per consolidated issue.
  */
-function postConsolidatedFeedback(ctx, consolidated) {
+function postConsolidatedFeedback(ctx, consolidated, artefactVersion) {
   for (const issue of consolidated) {
     ctx.feedback.add({
       file: issue.file,
       text: issue.issue,
       tag: `law:${issue.law}`,
+      artefact_version: artefactVersion,
     });
   }
 }

package/dist/scripts/lib/artefacts.js

@@ -6,8 +6,9 @@
  */
 
 import { minimatch } from 'minimatch';
-import { sortPaths } from './attestation/hash.js';
+import { sortPaths, sha256Text } from './attestation/hash.js';
 import { getArtefactType } from './config.js';
+import { expandPatterns } from './validation.js';
 
 // --- Shared branch artefact discovery ---
 
@@ -164,3 +165,44 @@ export async function getArtefactFiles(foundryDir, typeId, io, options = {}) {
 
   return result;
 }
+
+/**
+ * Compute the artefact version hash for a given artefact type.
+ *
+ * Reads the artefact type definition, expands its file patterns across the
+ * worktree, and computes a SHA-256 hash over all matching files. Each file
+ * contributes `sha256(filePath + ":" + content)` and the per-file hashes are
+ * joined with "\n" before the final SHA-256.
+ *
+ * When no patterns are defined or no files match, returns the SHA-256 of an
+ * empty input (e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855).
+ *
+ * @param {string} foundryDir - Path to the foundry config directory
+ * @param {string} typeId - Artefact type identifier
+ * @param {object} io - IO interface with readFile(path, encoding)
+ * @param {string} [worktree] - Worktree root for pattern expansion (defaults to foundryDir)
+ * @returns {Promise<string>} SHA-256 hex string (64 characters)
+ * @throws {Error} On IO errors (unknown type, file read failure, glob error)
+ */
+export async function computeArtefactVersion(foundryDir, typeId, io, worktree = foundryDir) {
+  const def = await getArtefactType(foundryDir, typeId, io);
+  const patterns = getFilePatterns(def);
+
+  if (patterns.length === 0) {
+    return sha256Text('');
+  }
+
+  const files = await expandPatterns(patterns, worktree);
+
+  if (files.length === 0) {
+    return sha256Text('');
+  }
+
+  const perFileHashes = await Promise.all(files.map(async file => {
+    const content = await io.readFile(file, 'utf-8');
+    return sha256Text(file + ':' + content);
+  }));
+
+  const joined = perFileHashes.join('\n');
+  return sha256Text(joined);
+}

package/dist/scripts/lib/config-creators/cycle.js

@@ -52,14 +52,11 @@ function renderModels(models) {
 /** Render boolean and numeric flags (camelCase to kebab-case). */
 function renderFlags(args) {
   let fm = '';
-  if (args.humanAppraise !== undefined) {
-    fm += `human-appraise: ${args.humanAppraise}\n`;
+  if (args.alwaysHumanAppraise !== undefined) {
+    fm += `always-human-appraise: ${args.alwaysHumanAppraise}\n`;
   }
-  if (args.deadlockAppraise !== undefined) {
-    fm += `deadlock-appraise: ${args.deadlockAppraise}\n`;
-  }
-  if (args.deadlockIterations !== undefined) {
-    fm += `deadlock-iterations: ${args.deadlockIterations}\n`;
+  if (args.deadlockHumanAppraise !== undefined) {
+    fm += `deadlock-human-appraise: ${args.deadlockHumanAppraise}\n`;
   }
   if (args.maxIterations !== undefined) {
     fm += `max-iterations: ${args.maxIterations}\n`;
@@ -76,9 +73,8 @@ function renderFlags(args) {
  * @param {string} args.outputType       Artefact type ID this cycle produces.
  * @param {{ type: 'any-of'|'all-of', artefacts: string[] }} [args.inputs]  Input contract.
  * @param {string[]} [args.targets]      Downstream cycle IDs.
- * @param {boolean} [args.humanAppraise] Include human-appraise in every iteration.
- * @param {boolean} [args.deadlockAppraise] Route to human-appraise on deadlock.
- * @param {number} [args.deadlockIterations] Iteration threshold for deadlock detection.
+ * @param {boolean} [args.alwaysHumanAppraise] Include human-appraise in every iteration.
+ * @param {boolean} [args.deadlockHumanAppraise] Route to human-appraise when max-iterations is reached.
  * @param {number} [args.maxIterations]  Maximum forge iterations.
  * @param {{ extractors: string[] }} [args.assay]  Assay stage config.
  * @param {{ read: string[], write: string[] }} [args.memory]  Flow memory permissions.

package/dist/scripts/lib/config-validators/cycle.js

@@ -29,7 +29,6 @@ export async function validate({ name, body, io }) {
     await checkOutputType(fm, io),
     ...await checkInputs(fm, io),
     ...await checkTargets(fm, io),
-    checkIterationLimits(fm),
   ].filter(Boolean);
 
   return errors.length ? { ok: false, errors } : { ok: true };
@@ -131,11 +130,4 @@ async function validateCycleRefs(targets, io) {
   return errors;
 }
 
-function checkIterationLimits(fm) {
-  const maxIt = fm['max-iterations'];
-  const dlIt = fm['deadlock-iterations'];
-  if (maxIt !== undefined && dlIt !== undefined && dlIt > maxIt) {
-    return `deadlock-iterations (${dlIt}) must be <= max-iterations (${maxIt}); deadlock would never trigger before the cycle blocks`;
-  }
-  return null;
-}
+

package/dist/scripts/lib/feedback-store.js

@@ -5,11 +5,11 @@ import { validateTransition, hashText, canForgeWontFix } from './feedback-transi
 
 const YAML_OPTS = { lineWidth: -1 };
 
-const VALID_SOURCE_BASES = new Set(['forge', 'quench', 'appraise', 'human-appraise']);
+const VALID_SOURCE_BASES = new Set(['forge', 'quench', 'appraise', 'human-appraise', 'system']);
 
 function validateSourceBase(base) {
   if (!VALID_SOURCE_BASES.has(base)) {
-    throw new Error(`unknown source base: ${base} (expected one of: forge, quench, appraise, human-appraise)`);
+    throw new Error(`unknown source base: ${base} (expected one of: forge, quench, appraise, human-appraise, system)`);
   }
 }
 
@@ -96,11 +96,11 @@ export function openFeedbackStore(path, io) {
         timestamp: nowIso, persist,
       });
     },
-    writeDeadlockedSnapshotForTest(params) {
-      return storeWriteDeadlockedSnapshot(params, items, { timestamp: nowIso, persist });
+    autoResolve({ id, reason, cycle }) {
+      return storeAutoResolve({ id, reason, cycle, items, persist, timestamp: nowIso });
     },
-    writeDeadlockedSnapshots(ids, reason, stage, cycle) {
-      return storeWriteDeadlockedSnapshots({ ids, reason, stage, cycle }, items, { timestamp: nowIso, persist });
+    forceState(id, state, cycle) {
+      return storeForceState({ id, state, cycle, items, persist });
     },
     resolveSystemItems(stage, cycle) {
       resolveSystemItemsImpl({ items, stage, cycle, timestamp: nowIso, persist });
@@ -115,20 +115,21 @@ function isDuplicate(item, file, tag, textHash, stateOf) {
     stateOf(item) !== 'resolved';
 }
 
-function assertAddParams(...params) {
-  for (const p of params) {
-    if (!p) throw new Error('add requires file, tag, text, source, cycle');
-  }
+function assertAddParams(file, tag, text, source, cycle) {
+  const missing = typeof file !== 'string' || [tag, text, source, cycle].some(v => !v);
+  if (missing) throw new Error('add requires file, tag, text, source, cycle');
 }
 
 function storeAdd(params, items, deps) {
-  const { file, tag, text, source, cycle } = params;
+  const { file, tag, text, source, cycle, artefact_version } = params;
   const { hashFn, stateOf, validateSrc, persist, makeUlid, timestamp } = deps;
   assertAddParams(file, tag, text, source, cycle);
   validateSrc(source);
 
   const textHash = hashFn(text);
-  const existing = items.find(it => isDuplicate(it, file, tag, textHash, stateOf));
+  const existing = items.find(it =>
+    it.artefact_version === artefact_version && isDuplicate(it, file, tag, textHash, stateOf)
+  );
   if (existing) return { id: existing.id, deduped: true };
 
   const id = makeUlid();
@@ -136,6 +137,9 @@ function storeAdd(params, items, deps) {
     id, file, tag, text, source,
     history: [{ state: 'open', stage: source, cycle, timestamp: timestamp() }],
   };
+  if (artefact_version !== undefined) {
+    item.artefact_version = artefact_version;
+  }
   persist([...items, item]);
   return { id, deduped: false };
 }
@@ -153,7 +157,7 @@ function forgeWontFixError(item) {
 
 function reasonRequiredForTransition(target, current, reason) {
   const REASON_REQUIRED_TARGETS = new Set(['rejected', 'wont-fix']);
-  return (REASON_REQUIRED_TARGETS.has(target) || current === 'deadlocked')
+  return REASON_REQUIRED_TARGETS.has(target)
     && (!reason || !reason.trim());
 }
 
@@ -208,49 +212,20 @@ function storeTransition(params, items, deps) {
   return { ok: true };
 }
 
-function storeWriteDeadlockedSnapshot(params, items, deps) {
-  const { id, cycle, reason } = params;
-  const { timestamp, persist } = deps;
-
+function storeForceState({ id, state, cycle, items, persist }) {
   const item = items.find(x => x.id === id);
   if (!item) return { ok: false, error: `feedback item not found: ${id}` };
-  if (!reason || !reason.trim()) {
-    return { ok: false, error: 'reason is required for deadlocked snapshot' };
-  }
-
-  const snapshot = { state: 'deadlocked', stage: 'sort', cycle, timestamp: timestamp(), reason };
-  persist(items.map(it =>
-    it.id === id ? { ...it, history: [snapshot, ...it.history] } : it
-  ));
+  const snapshot = { state, stage: 'system:forge-contract-mismatch', cycle, timestamp: nowIso() };
+  persist(applyTransition(items, id, snapshot));
   return { ok: true };
 }
 
-function assertDeadlockedSnapshotArgs(ids, reason) {
-  if (!Array.isArray(ids)) return { ok: false, error: 'ids must be an array' };
-  if (ids.length === 0) return { ok: true };
-  if (!reason) return { ok: false, error: 'reason is required for deadlocked snapshot' };
-  return null;
+function storeAutoResolve({ id, reason, cycle, items, persist, timestamp }) {
+  const item = items.find(x => x.id === id);
+  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
+  const snapshot = { state: 'resolved', stage: 'system', cycle, reason, timestamp: timestamp() };
+  persist(applyTransition(items, id, snapshot));
+  return { ok: true };
 }
 
-function storeWriteDeadlockedSnapshots(params, items, deps) {
-  const { ids, reason, stage, cycle } = params;
-  const { timestamp, persist } = deps;
 
-  const precheck = assertDeadlockedSnapshotArgs(ids, reason);
-  if (precheck) return precheck;
-
-  const ts = timestamp();
-  const idSet = new Set(ids);
-  const nextItems = items.map(it => {
-    if (!idSet.has(it.id)) return it;
-    return { ...it, history: [{ state: 'deadlocked', stage, cycle, timestamp: ts, reason }, ...it.history] };
-  });
-  for (const id of ids) {
-    if (!items.some(it => it.id === id)) {
-      return { ok: false, error: `feedback item(s) not found: ${id}` };
-    }
-  }
-
-  persist(nextItems);
-  return { ok: true };
-}

package/dist/scripts/lib/finalize.js

@@ -49,7 +49,7 @@ function classifyFiles(files, allowedPatterns) {
   return { matched, unexpected };
 }
 
-export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, io }) {
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, io, artefact_version }) {
   if (!io?.exec) {
     throw new Error('finalizeStage: io.exec is required');
   }
@@ -66,5 +66,13 @@ export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes
     file,
     type: cycleDef.outputArtefactType,
   }));
-  return { ok: true, artefacts, changedFiles: sortedFiles };
+  return forgeResult(artefacts, sortedFiles, artefact_version);
+}
+
+function forgeResult(artefacts, files, artefact_version) {
+  const result = { ok: true, artefacts, changedFiles: files };
+  if (artefact_version !== undefined) {
+    result.artefact_version = artefact_version;
+  }
+  return result;
 }

package/dist/scripts/lib/forge-contract.js

@@ -0,0 +1,93 @@
+/**
+ * Forge contract enforcement — validates that forge responded to every
+ * presented feedback item and that the batch-level artefact version
+ * semantics are satisfied.
+ *
+ * Per-item check: every item must end in 'actioned' or 'wont-fix'.
+ * Batch-level check: if any item is actioned, version must change.
+ * If no item is actioned, version must be unchanged.
+ */
+
+function currentState(feedbackStore, id) {
+  const item = feedbackStore.get(id);
+  return item ? item.history[0].state : null;
+}
+
+function revertAll(items, feedbackStore, cycleId) {
+  for (const item of items) {
+    feedbackStore.forceState(item.id, 'open', cycleId);
+  }
+}
+
+function postSystemFeedback(feedbackStore, cycleId, postVersion, text) {
+  feedbackStore.add({
+    file: '',
+    tag: 'system:forge-contract-mismatch',
+    text,
+    source: 'system:forge-contract-mismatch',
+    artefact_version: postVersion,
+    cycle: cycleId,
+  });
+}
+
+function checkPerItemResponse(items, feedbackStore, cycleId, postVersion) {
+  for (const item of items) {
+    const state = currentState(feedbackStore, item.id);
+    if (state !== 'actioned' && state !== 'wont-fix') {
+      revertAll(items, feedbackStore, cycleId);
+      postSystemFeedback(
+        feedbackStore, cycleId, postVersion,
+        'forge did not respond to every presented feedback item',
+      );
+      return false;
+    }
+  }
+  return true;
+}
+
+function hasActionedItem(items, feedbackStore) {
+  return items.some(item => currentState(feedbackStore, item.id) === 'actioned');
+}
+
+function checkBatchVersion(items, feedbackStore, cycleId, postVersion, preVersion) {
+  const hasActioned = hasActionedItem(items, feedbackStore);
+
+  if (hasActioned && preVersion === postVersion) {
+    revertAll(items, feedbackStore, cycleId);
+    postSystemFeedback(
+      feedbackStore, cycleId, postVersion,
+      'forge marked feedback as actioned without changing artefacts',
+    );
+    return { contractPassed: false };
+  }
+
+  if (!hasActioned && preVersion !== postVersion) {
+    revertAll(items, feedbackStore, cycleId);
+    postSystemFeedback(
+      feedbackStore, cycleId, postVersion,
+      'forge changed artefacts but did not mark any feedback as actioned',
+    );
+    return { contractPassed: false };
+  }
+
+  return { contractPassed: true };
+}
+
+/**
+ * Enforce the forge contract on a batch of items presented to forge.
+ *
+ * Two-level check:
+ * 1. Per-item: every item must end in 'actioned' or 'wont-fix'.
+ * 2. Batch-level: artefact version semantics must be consistent.
+ *
+ * @param {{ items: Array<{id: string}>, preVersion: string, postVersion: string,
+ *   feedbackStore: object, cycleId: string }} params
+ * @returns {{ contractPassed: boolean }}
+ */
+export function enforceForgeContract({ items, preVersion, postVersion, feedbackStore, cycleId }) {
+  if (!checkPerItemResponse(items, feedbackStore, cycleId, postVersion)) {
+    return { contractPassed: false };
+  }
+
+  return checkBatchVersion(items, feedbackStore, cycleId, postVersion, preVersion);
+}