@really-knows-ai/foundry 3.5.7 → 3.5.9

package/dist/scripts/sort.js

@@ -29,38 +29,6 @@ import {
   getDirtyToolManagedFiles,
 } from './lib/sort-fs-check.js';
 
-// ---------------------------------------------------------------------------
-// Top-level deadlock pass (spec §6.1)
-// ---------------------------------------------------------------------------
-
-/**
- * Walk the feedback store and write a `state=deadlocked` snapshot for every
- * non-resolved item whose history depth has reached the configured threshold.
- * One atomic batch write via `store.writeDeadlockedSnapshots(ids, ...)`.
- *
- * Sort is the only writer of `state=deadlocked` per spec §6.1.
- *
- * @returns {boolean} true iff at least one snapshot was written.
- */
-function runDeadlockPass(store, { threshold, enabled, cycle }) {
-  if (!enabled) return false;
-  const qualifying = store.list().filter(item => {
-    // history[0] is the most recent state per the feedback-store invariant
-    // (entries are prepended to keep newest at head).
-    const head = item.history[0];
-    if (head.state === 'resolved' || head.state === 'deadlocked') return false;
-    return item.history.length >= threshold;
-  });
-  if (qualifying.length === 0) return false;
-  store.writeDeadlockedSnapshots(
-    qualifying.map(it => it.id),
-    `depth >= threshold=${threshold}`,
-    'sort',
-    cycle,
-  );
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // runSort — structured result for programmatic use
 // ---------------------------------------------------------------------------
@@ -89,9 +57,8 @@ function extractFrontmatterDefaults(frontmatter) {
   const maxIt = frontmatter['max-iterations'] ?? 3;
   return {
     maxIterations: maxIt,
-    humanAppraiseEnabled: frontmatter['human-appraise'] === true,
-    deadlockAppraise: frontmatter['deadlock-appraise'] !== false,
-    deadlockIterations: frontmatter['deadlock-iterations'] ?? maxIt,
+    alwaysHumanAppraise: frontmatter['always-human-appraise'] === true,
+    deadlockHumanAppraise: frontmatter['deadlock-human-appraise'] !== false,
   };
 }
 
@@ -105,17 +72,14 @@ function checkDirtyFiles(history, io) {
     + `Re-run foundry_orchestrate or commit the listed files manually before retrying.`;
 }
 
-function loadFeedbackAndRunDeadlock(cycle, deadlockIterations, deadlockAppraise, io) {
+function loadFeedback(io, cycle) {
   const store = openFeedbackStore('WORK.feedback.yaml', io);
-  runDeadlockPass(store, { threshold: deadlockIterations, enabled: deadlockAppraise, cycle });
-  const feedback = store.list().map(item => ({
+  return store.list().map(item => ({
     id: item.id,
     file: item.file,
     state: item.history[0].state,
     depth: item.history.length,
   }));
-  const anyDeadlocked = feedback.some(f => f.state === 'deadlocked');
-  return { feedback, anyDeadlocked };
 }
 
 function resolveCycleDef(cycleDef, frontmatter, foundryDir, cycle) {
@@ -138,15 +102,15 @@ function getCurrentNonSortStage(nonSortHistory) {
   return nonSortHistory.length > 0 ? nonSortHistory[nonSortHistory.length - 1].stage : null;
 }
 
-function resolveDeadlockRoute(stages, nonSortHistory, cycle) {
-  const currentNonSort = getCurrentNonSortStage(nonSortHistory);
-  if (currentNonSort && baseStage(currentNonSort) === 'human-appraise') return 'blocked';
-  return findFirst(stages, 'human-appraise') || `human-appraise:${cycle}`;
-}
-
 function resolveRoute(ctx) {
-  if (ctx.anyDeadlocked) return resolveDeadlockRoute(ctx.stages, ctx.nonSortHistory, ctx.cycle);
-  return determineRoute(ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations);
+  return determineRoute(
+    ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations,
+    {
+      alwaysHumanAppraise: ctx.alwaysHumanAppraise,
+      deadlockHumanAppraise: ctx.deadlockHumanAppraise,
+      cycle: ctx.cycle,
+    },
+  );
 }
 
 function firstModelValue(models) {
@@ -215,9 +179,7 @@ function preparePhases({ workPath, historyPath, foundryDir, cycleDef, io }) {
   const history = loadHistory(historyPath, cycle, io);
   const dirtyError = checkDirtyFiles(history, io);
   if (dirtyError) return { kind: 'violation', details: dirtyError };
-  const { feedback, anyDeadlocked } = loadFeedbackAndRunDeadlock(
-    cycle, defaults.deadlockIterations, defaults.deadlockAppraise, io,
-  );
+  const feedback = loadFeedback(io, cycle);
   const fileCheck = checkModifiedFilesAfterLastStage({
     history, foundryDir, cycleDef, cycle, frontmatter, io,
   });
@@ -225,7 +187,7 @@ function preparePhases({ workPath, historyPath, foundryDir, cycleDef, io }) {
   if (violation) return { kind: 'violation', details: violation };
   return {
     kind: 'ok',
-    frontmatter, cycle, stages, defaults, history, feedback, anyDeadlocked,
+    frontmatter, cycle, stages, defaults, history, feedback,
     nonSortHistory: fileCheck.nonSortHistory,
   };
 }
@@ -253,8 +215,9 @@ function buildRouteCtx(prep) {
     history: prep.history,
     feedback: prep.feedback,
     maxIterations: prep.defaults.maxIterations,
+    alwaysHumanAppraise: prep.defaults.alwaysHumanAppraise,
+    deadlockHumanAppraise: prep.defaults.deadlockHumanAppraise,
     cycle: prep.cycle,
-    anyDeadlocked: prep.anyDeadlocked,
     nonSortHistory: prep.nonSortHistory,
   };
 }

package/dist/skills/add-cycle/SKILL.md

@@ -38,7 +38,7 @@ Do not tell the user to call branch tools directly.
 
 When invoked with pre-filled fields matching the `foundry_config_create_cycle` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-Context fields: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`
+Context fields: `{id, name, outputType, description, inputs?, targets?, alwaysHumanAppraise?, deadlockHumanAppraise?, maxIterations?, assay?, memory?, models?}`
 
 `inputs` is optional. A source cycle that starts from the user's run goal and has no upstream artefact dependency omits `inputs` entirely. Empty input contracts are invalid: do not pass `inputs: {type: "any-of", artefacts: []}`.
 
@@ -85,12 +85,12 @@ If the parent flow or required artefact type is missing and the user's goal clea
 **Optional clusters** — After each cluster, ask whether the user wants to configure it; if not, skip:
 
 - **Routing**: `inputs` (input contract: `{type: "any-of"|"all-of", artefacts: string[]}`; omit for source cycles with no upstream artefact dependency), `targets` (cycle IDs to route to after completion), `maxIterations` (maximum iterations before forced progression)
-- **Human-appraise**: `humanAppraise` (boolean, default false) — human reviews every iteration; `deadlockAppraise` (boolean, default true) — human is pulled in when LLM appraisers deadlock; `deadlockIterations` (number, defaults to `max-iterations` value) — deadlock threshold. Only applies when either appraise is enabled.
+- **Human-appraise**: `alwaysHumanAppraise` (boolean, default false) — human reviews every iteration; when true, `max-iterations` is not enforced. `deadlockHumanAppraise` (boolean, default true) — route to human for review when the iteration cap is reached, instead of blocking the cycle. Only applies when `alwaysHumanAppraise` is false.
 - **Memory and models**: `assay` (assay configuration), `memory` (memory configuration), `models` (stage-specific model overrides, e.g. `{forge: "openai/gpt-4o", appraise: "openai/gpt-4o"}`). For models, offer each stage (forge, quench, appraise) individually. If the user has no preference, omit the `models` map and use the session defaults.
 
 ### 2. Plan
 
-Present a structured summary of the cycle definition: id, name, outputType, description, and any configured optional fields (inputs, targets, humanAppraise, deadlockAppraise, deadlockIterations, maxIterations, assay, memory, models). Include only fields that have values.
+Present a structured summary of the cycle definition: id, name, outputType, description, and any configured optional fields (inputs, targets, alwaysHumanAppraise, deadlockHumanAppraise, maxIterations, assay, memory, models). Include only fields that have values.
 
 Ask: "Does this capture the cycle correctly?" Iterate until the user is satisfied.
 
@@ -102,7 +102,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_cycle({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that do not exist yet.
 
-2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. Include `inputs` only when the cycle reads upstream artefacts, and include `models` whenever the user selected stage-specific model overrides. The tool:
+2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", targets: ..., alwaysHumanAppraise: ..., deadlockHumanAppraise: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. Include `inputs` only when the cycle reads upstream artefacts, and include `models` whenever the user selected stage-specific model overrides. The tool:
    - re-validates the body (TOCTOU);
    - writes `foundry/cycles/<id>.md`;
    - produces one git commit on the current `config/*` branch.

package/dist/skills/add-flow/SKILL.md

@@ -69,7 +69,7 @@ Create missing dependencies in validation order:
 
 3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
 
-4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`. For a source cycle that starts from the user's run goal and has no upstream artefact dependency, omit `inputs` entirely; never pass `inputs` with an empty `artefacts` array.
+4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, alwaysHumanAppraise?, deadlockHumanAppraise?, maxIterations?, assay?, memory?, models?}`. For a source cycle that starts from the user's run goal and has no upstream artefact dependency, omit `inputs` entirely; never pass `inputs` with an empty `artefacts` array.
 
 For the haiku example, default to a `haiku` artefact type, `haikus/*.md` file pattern, laws for form, imagery, and mood, a deterministic syllable validator where project dependencies allow it, two or three distinct appraisers, one cycle, and one flow.
 

package/dist/skills/add-law/SKILL.md

@@ -66,7 +66,7 @@ Walk the user through which elements of the law can be validated deterministical
 >
 > Shall I add validators for the script-checkable elements?
 
-For each script-checkable element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Prefer Node.js built-ins and libraries already in the project; hand-rolled heuristics are fragile — use available packages instead of writing custom validation logic from scratch.
+For each script-checkable element, write a standalone `.mjs` script next to the artefacts it validates (e.g. `foundry/artefacts/<type>/check-line-count.mjs`) and reference it in the command (e.g. `node foundry/artefacts/<type>/check-line-count.mjs {files}`). Place validators alongside the artefacts so they colocate with what they validate. Use existing project dependencies and Node.js built‑ins. Hand‑rolled heuristics (custom syllable counters, regex parsers, manual character walks) are a last resort — they produce false positives, waste tokens on debugging, and break on edge cases. Install a library instead. Only write validation logic from scratch when no npm package exists for the task and the heuristic is trivially correct.
 
 **Validators**: Ask about `validators` (optional) — offer to create one or skip.
 

package/dist/skills/human-appraise/SKILL.md

@@ -6,7 +6,7 @@ description: Human quality gate. Presents the artefact to the human for review a
 
 # Human Appraise
 
-You are a human quality gate. Sort has routed to you either because the LLM appraisers have finished (normal flow) or because a deadlock was detected between forge and appraisers.
+You are a human quality gate. Sort has routed to you for the human to review the current artefact and provide feedback or approve.
 
 ## Prerequisites
 
@@ -31,7 +31,7 @@ When invoked from orchestrate, you receive `{cycle, token, context}`:
 - `cycle` — the current cycle id
 - `token` — single-use token for `foundry_stage_begin`
 - `context.artefact_file` — the target artefact
-- `context.recent_feedback` — recent deadlocked feedback items to present to the user
+- `context.recent_feedback` — recent unresolved feedback items to present to the user
 
 Your FIRST tool call must be `foundry_stage_begin({stage: 'human-appraise:<cycle>', cycle, token})`.
 
@@ -63,31 +63,24 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
 4. Present to the human:
    - The current artefact content (full file content or multi-file diff)
    - A summary of this iteration's feedback (resolved and open)
-   - If this is a deadlock escalation, clearly explain the deadlock:
-     - Which feedback item(s) are stuck
-     - The appraiser's reasoning
-     - Forge's wont-fix or revision justification
-     - Ask the human to resolve the disagreement
+   - Ask the human to review, provide feedback, or approve
 
 5. Wait for the human's response.
 
 6. Act on the response (tag MUST be `human` on any added feedback — the tool rejects other tags during human-appraise):
    - **Approve** — "looks good" / "continue" — no feedback added, sort will advance.
    - **Provide feedback** — `foundry_feedback_add({ file, text, tag: 'human' })`. Sort will route back to forge.
-   - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix, deadlocked}`. See "Feedback handling" below for the legal transitions and authority rules.
+   - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix}`. See "Feedback handling" below for the legal transitions and authority rules.
    - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the repository no longer has a per-artefact status tool or table). To abort: end the stage with a summary explaining the abort, then either (a) instruct the user to call `foundry_workfile_delete({ confirm: true })` to discard the cycle, or (b) reject outstanding feedback so routing exhausts iterations and sort blocks the cycle on its own.
 
 7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
 
 ## Feedback handling
 
-As a human-appraise stage, you can add human feedback and resolve feedback
-items (including deadlock overrides). **Human-appraise can resolve any
-non-resolved source-stage item regardless of source** — this is the
-universal override authority recorded in spec §5.1 rule 5. It is not
-limited to deadlocked items, though in practice most overrides today are
-on deadlocked items because default sort routing only surfaces deadlocked
-items to human-appraise (see §17 future-work note below).
+As a human-appraise stage, you can add human feedback and resolve
+feedback items. **Human-appraise can resolve any non-resolved
+source-stage item regardless of source** — this is the universal
+override authority recorded in spec §5.1 rule 5.
 
 What human-appraise can NOT do:
 
@@ -109,37 +102,16 @@ What human-appraise CAN do:
    found and no new snapshot was written, `deduped: false` indicates a new
    item was created.
 
-2. **Resolve any non-resolved source-stage item.** For items in
-   `{actioned, wont-fix}` (sourced from quench, appraise, or
-   human-appraise), call `foundry_feedback_resolve` with
+2. **Resolve any non-resolved item.** For items in
+   `{actioned, wont-fix}`, call `foundry_feedback_resolve` with
    `{ id, resolution: 'approved' | 'rejected', reason? }`. Human-appraise
    may resolve any such item regardless of source, including items from
    other stage ids.
 
-3. **Resolve deadlocked items.** When items reach `state: deadlocked`
-   (written by sort when an item's history depth hits
-   `deadlock-iterations`), human-appraise is the ONLY stage authorised
-   to resolve them. Call `foundry_feedback_resolve` with
-   `{ id, resolution: 'approved' | 'rejected', reason: '...' }`.
-   `reason` is always required on deadlock override — it documents why
-   the deadlock is being broken. After human-appraise resolves every
-   deadlocked item, the cycle resumes normal forge/appraise routing. If
-   deadlocks remain after human-appraise, the cycle blocks (per spec §5.2).
-
 **Reason rules.** `reason` is required when rejecting feedback
-(`resolution: 'rejected'`) and when overriding a deadlocked item.
-Non-deadlocked approved resolution via
+(`resolution: 'rejected'`). Approved resolution via
 `foundry_feedback_resolve({ id, resolution: 'approved', reason? })` may
-omit `reason`; deadlock override always requires `reason` to document why
-the deadlock is being broken.
-
-**Future work.** Spec §17 notes that a cycle-level mode flag letting
-human-appraise see all unresolved feedback (not just deadlocked items)
-before sort routes is planned for a future release. In v2.6.0 the
-authority is universal but reachability is limited — you typically only
-see deadlocked items on the route from sort. If you do see non-deadlocked
-items (e.g. you were invoked directly by the user), the same authority
-applies.
+omit `reason`.
 
 ## What you do NOT do
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.5.7",
+  "version": "3.5.9",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",