@really-knows-ai/foundry 1.5.1 → 2.0.0

package/.opencode/plugins/foundry.js

@@ -209,13 +209,17 @@ export const FoundryPlugin = async ({ directory }) => {
       }),
 
       foundry_workfile_delete: tool({
-        description: 'Delete WORK.md',
+        description: 'Delete WORK.md and WORK.history.yaml',
         args: {},
         async execute(_args, context) {
           const workPath = path.join(context.worktree, 'WORK.md');
+          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
           if (existsSync(workPath)) {
             unlinkSync(workPath);
           }
+          if (existsSync(historyPath)) {
+            unlinkSync(historyPath);
+          }
           return JSON.stringify({ ok: true });
         },
       }),
@@ -392,6 +396,53 @@ export const FoundryPlugin = async ({ directory }) => {
         },
       }),
 
+      foundry_git_finish: tool({
+        description: 'Clean up work files, squash merge to base branch, and delete the work branch',
+        args: {
+          message: tool.schema.string().describe('Squash merge commit message'),
+          baseBranch: tool.schema.string().optional().describe('Target branch (default: main)'),
+        },
+        async execute(args, context) {
+          const base = args.baseBranch || 'main';
+          const cwd = context.worktree;
+          const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+
+          // Get current branch name
+          const workBranch = execSync('git branch --show-current', opts).trim();
+          if (workBranch === base) {
+            return JSON.stringify({ error: `Already on ${base} — nothing to merge` });
+          }
+
+          // Delete work files
+          const workPath = path.join(cwd, 'WORK.md');
+          const historyPath = path.join(cwd, 'WORK.history.yaml');
+          if (existsSync(workPath)) unlinkSync(workPath);
+          if (existsSync(historyPath)) unlinkSync(historyPath);
+
+          // Commit cleanup if there are changes
+          try {
+            execSync('git add -A', opts);
+            const status = execSync('git status --porcelain', opts).trim();
+            if (status) {
+              const cleanupMsg = `[${workBranch.replace('work/', '')}] cleanup: remove work files`;
+              execSync(`git commit -m "${cleanupMsg.replace(/"/g, '\\"')}"`, opts);
+            }
+          } catch { /* no changes to commit */ }
+
+          // Switch to base and squash merge
+          execSync(`git checkout ${base}`, opts);
+          execSync(`git merge --squash ${workBranch}`, opts);
+          const msg = args.message.replace(/"/g, '\\"');
+          execSync(`git commit -m "${msg}"`, opts);
+          const hash = execSync('git rev-parse --short HEAD', opts).trim();
+
+          // Force-delete work branch (required after squash)
+          execSync(`git branch -D ${workBranch}`, opts);
+
+          return JSON.stringify({ ok: true, hash, branch: base });
+        },
+      }),
+
       // ── Config tools ──
       foundry_config_cycle: tool({
         description: 'Get a cycle definition from foundry config',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.5.1",
+  "version": "2.0.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",

package/scripts/lib/feedback.js

@@ -237,6 +237,22 @@ export function listFeedback(text, cycle, artefacts, filterFile) {
   return results;
 }
 
+/**
+ * Detect feedback items stuck in a deadlock — rejected N or more times.
+ * A deadlock occurs when forge-appraise cycles keep rejecting the same item.
+ */
+export function detectDeadlocks(feedback, history, threshold = 3) {
+  // Count forge→appraise cycles (each pair = one iteration)
+  const forgeAppraiseCount = history.filter(
+    e => (e.stage || '').split(':')[0] === 'appraise'
+  ).length;
+
+  if (forgeAppraiseCount < threshold) return [];
+
+  // Items that are still rejected after threshold iterations are deadlocked
+  return feedback.filter(f => f.state === 'rejected' || f.state === 'open');
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------

package/scripts/sort.js

@@ -21,7 +21,7 @@ import { validateTags } from './lib/tags.js';
 import { parseFrontmatter } from './lib/workfile.js';
 import { parseArtefactsTable } from './lib/artefacts.js';
 import { loadHistory } from './lib/history.js';
-import { parseFeedback, parseFeedbackItem } from './lib/feedback.js';
+import { parseFeedback, parseFeedbackItem, detectDeadlocks } from './lib/feedback.js';
 
 // ---------------------------------------------------------------------------
 // Stage helpers
@@ -73,11 +73,6 @@ function determineRoute(stages, history, feedback, maxIterations) {
 
   if (lastBase === null) return stages[0];
 
-  if (lastBase === 'hitl') {
-    const next = nextInRoute(stages, lastEntry);
-    return next ?? 'done';
-  }
-
   if (lastBase === 'forge') {
     const next = nextInRoute(stages, lastEntry);
     return next ?? 'done';
@@ -88,7 +83,11 @@ function determineRoute(stages, history, feedback, maxIterations) {
   }
 
   if (lastBase === 'appraise') {
-    return nextAfterAppraise(stages, feedback, forgeCount, maxIterations);
+    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory);
+  }
+
+  if (lastBase === 'human-appraise') {
+    return nextAfterAppraise(stages, lastEntry, feedback, forgeCount, maxIterations, nonSortHistory);
   }
 
   return 'blocked';
@@ -104,7 +103,18 @@ function nextAfterQuench(stages, current, feedback, forgeCount, maxIterations) {
   return nextInRoute(stages, current) ?? 'done';
 }
 
-function nextAfterAppraise(stages, feedback, forgeCount, maxIterations) {
+function nextAfterAppraise(stages, current, feedback, forgeCount, maxIterations, history = []) {
+  // Check for deadlock escalation
+  const deadlocked = detectDeadlocks(feedback, history);
+  if (deadlocked.length > 0) {
+    const humanAppraise = findFirst(stages, 'human-appraise');
+    if (humanAppraise && baseStage(current) !== 'human-appraise') {
+      return humanAppraise;
+    }
+    // Human-appraise not available or we're already in it — blocked
+    if (forgeCount >= maxIterations) return 'blocked';
+  }
+
   const needsForge = feedback.some(f => f.state === 'open' || f.state === 'rejected');
   if (needsForge) {
     if (forgeCount >= maxIterations) return 'blocked';
@@ -118,7 +128,7 @@ function nextAfterAppraise(stages, feedback, forgeCount, maxIterations) {
     return findFirst(stages, 'appraise') ?? 'blocked';
   }
 
-  return 'done';
+  return nextInRoute(stages, current) ?? 'done';
 }
 
 // ---------------------------------------------------------------------------

package/skills/add-cycle/SKILL.md

@@ -6,7 +6,7 @@ description: Creates a new foundry cycle within a foundry flow, specifying the o
 
 # Add Cycle
 
-You help the user create a new foundry cycle and add it to an existing foundry flow. A foundry cycle produces one artefact type (read-write) and optionally reads from artefact types produced by earlier foundry cycles (read-only).
+You help the user create a new foundry cycle and add it to an existing foundry flow. A foundry cycle produces one artefact type (read-write), declares its input contract, targets the next cycle(s), and optionally enables human-appraise as a quality gate.
 
 ## Prerequisites
 
@@ -28,7 +28,11 @@ From the user's prompt, establish:
 - `id` — lowercase, hyphenated identifier for the foundry cycle
 - `name` — human-readable name
 - `output` — the artefact type this foundry cycle produces (must exist in `foundry/artefacts/`)
-- `inputs` — artefact types from earlier foundry cycles that this foundry cycle reads (may be empty)
+- `inputs` — artefact types this cycle reads, with a contract type:
+  - `type`: `any-of` (at least one must exist) or `all-of` (all must exist)
+  - `artefacts`: list of artefact type IDs
+  - May be empty for starting cycles
+- `targets` — cycle(s) to route to after this cycle completes (may be empty for terminal cycles)
 - A prose description of what this foundry cycle does
 
 If any of these are missing, ask.
@@ -46,13 +50,22 @@ For each stage in the cycle (forge, quench, appraise), ask the user if they want
 
 Only stages with an explicitly specified model are included in the `models` frontmatter map.
 
-### 4. Validate artefact types
+### 4. Configure human appraise
+
+Ask the user:
+
+> Do you want a human quality gate on this cycle? If enabled, a human reviewer will check the artefact after LLM appraisers pass, and can break deadlocks between forge and appraisers.
+>
+> - Enable human-appraise? (yes/no)
+> - If yes, deadlock threshold (default: 3 — number of forge/appraise iterations before escalating to human)
+
+### 5. Validate artefact types
 
 For `output` and each entry in `inputs`:
 - Verify the artefact type exists in `foundry/artefacts/<type>/definition.md`
 - If it doesn't, tell the user and ask if they want to create it first (separate skill)
 
-### 5. Validate against the foundry flow
+### 6. Validate against the foundry flow
 
 Read the flow definition from `foundry/flows/<flow-id>.md`. Check:
 
@@ -66,13 +79,13 @@ Read the flow definition from `foundry/flows/<flow-id>.md`. Check:
 > 2. Remove `<type>` from inputs (this foundry cycle won't have that context)
 > 3. Proceed anyway (the artefact may exist from a previous foundry flow run)
 
-### 6. Check for id conflicts
+### 7. Check for id conflicts
 
 Read all existing cycle definitions in `foundry/cycles/*.md`.
 
 - Exact id match → hard conflict, must choose a different id
 
-### 7. Check for semantic overlap
+### 8. Check for semantic overlap
 
 For foundry cycles already in this foundry flow, check whether the new foundry cycle overlaps in purpose:
 - Does another foundry cycle already transform the same inputs into a similar output?
@@ -80,7 +93,7 @@ For foundry cycles already in this foundry flow, check whether the new foundry c
 
 If overlap is found, present it and ask the user to confirm the distinction is real.
 
-### 8. Draft the definition
+### 9. Draft the definition
 
 Present the foundry cycle definition to the user:
 
@@ -90,41 +103,42 @@ id: <id>
 name: <name>
 output: <artefact-type-id>
 inputs:
-  - <artefact-type-id>
+  type: <any-of|all-of>
+  artefacts:
+    - <artefact-type-id>
+targets:
+  - <cycle-id>
+human-appraise:
+  enabled: <true|false>
+  deadlock-threshold: <number>
 models:
-  appraise: <model-id>       # optional, only if specified
+  appraise: <model-id>
 ---
 
 # <Name>
 
-<description — what this foundry cycle does, what it reads, what it produces>
+<description>
 ```
 
 Ask: does this capture the foundry cycle correctly?
 
-### 9. Determine position in foundry flow
+### 10. Validate target routing
 
-The foundry cycle needs a position in the foundry flow's ordered cycle list. Based on its inputs:
-- If no inputs: it can go first (or early)
-- If it reads from other foundry cycles: it must come after those foundry cycles
+For each target cycle:
+- Verify the target cycle exists in `foundry/cycles/`
+- Verify this cycle's output type satisfies at least one of the target's input artefacts
+- If the target doesn't exist yet, note it as pending
 
-Propose a position and confirm with the user:
-
-> This foundry cycle reads from `<inputs>`, which are produced by `<cycle-ids>`. It should go after those foundry cycles.
->
-> Proposed order:
-> 1. <existing-cycle>
-> 2. <existing-cycle>
-> 3. <new-cycle> ← here
->
-> Does this look right?
+For input validation:
+- Verify that at least one cycle in the flow has the input artefact type(s) as its output
+- If using `all-of`, verify all input types are producible
 
-### 10. Write files
+### 11. Write files
 
-- Create `foundry/cycles/<id>.md` with the foundry cycle definition
-- Update `foundry/flows/<flow-id>.md` to add the foundry cycle at the agreed position
+- Create `foundry/cycles/<id>.md` with the cycle definition
+- Update `foundry/flows/<flow-id>.md` to add the cycle to the `## Cycles` list (if not already present)
 
-### 11. Confirm
+### 12. Confirm
 
 Show the user the created/modified files and their contents.
 

package/skills/add-flow/SKILL.md

@@ -6,7 +6,7 @@ description: Creates a new foundry flow definition.
 
 # Add Flow
 
-You help the user create a new foundry flow. A foundry flow is an ordered list of foundry cycles that transforms a request into finished artefacts.
+You help the user create a new foundry flow. A foundry flow is a set of foundry cycles with declared starting points — cycles own their own routing via targets and input contracts.
 
 ## Prerequisites
 
@@ -32,35 +32,35 @@ Read all existing flow definitions in `foundry/flows/*.md`.
 - Exact id match → hard conflict, must choose a different id
 - Semantically similar name or description → warn and ask if the new foundry flow is genuinely distinct
 
-### 3. Determine foundry cycles
+### 3. Determine foundry cycles and starting cycles
 
-Ask the user which foundry cycles this foundry flow should include, in order. List available cycles from `foundry/cycles/*.md` for reference.
+Ask the user which foundry cycles this flow includes. List available cycles from `foundry/cycles/*.md` for reference.
 
-The user may:
-- Pick from existing foundry cycles
-- Describe foundry cycles that don't exist yet — note these and tell the user they'll need to create them with the add-cycle skill
+Then ask: which of these are **starting cycles** — the cycles that can be entered first when the flow begins?
 
-For each selected foundry cycle, verify it exists in `foundry/cycles/`. If it doesn't, note it as pending:
+- Starting cycles typically have no input dependencies
+- Multiple starting cycles are fine — the user (or context) determines which one to run first
 
-> Foundry cycle `<id>` doesn't exist yet. I'll include it in the foundry flow definition, but you'll need to create it before running the foundry flow.
+### 4. Validate cycle graph
 
-### 4. Validate foundry cycle ordering
+For each non-starting cycle, verify it is reachable:
+- At least one other cycle in the flow has it as a target
+- Its input contract can be satisfied by cycles in the flow
 
-Check that input dependencies are satisfied:
-- For each foundry cycle, its `inputs` must be produced as `output` by an earlier foundry cycle in the list
+If a cycle is unreachable (no cycle targets it and it's not a starting cycle), warn:
 
-If a dependency is unmet, warn:
-
-> Foundry cycle `<cycle-id>` reads from `<type>`, but no earlier foundry cycle produces it. Either reorder or add a foundry cycle that produces `<type>` first.
+> Cycle `<id>` is not a starting cycle and no other cycle targets it. It will never be reached in this flow.
 
 ### 5. Draft the definition
 
-Present the foundry flow definition to the user:
+Present the flow definition to the user:
 
 ```markdown
 ---
 id: <id>
 name: <name>
+starting-cycles:
+  - <cycle-id>
 ---
 
 # <Name>
@@ -69,11 +69,13 @@ name: <name>
 
 ## Cycles
 
-1. <cycle-id>
-2. <cycle-id>
+- <cycle-id>
+- <cycle-id>
 ```
 
-Ask: does this capture the foundry flow correctly?
+The `starting-cycles` field lists entry points. `## Cycles` lists all cycles in the flow (no ordering implied — routing is owned by individual cycle definitions via their `targets` field).
+
+Ask: does this capture the flow correctly?
 
 ### 6. Write the file
 

package/skills/appraise/SKILL.md

@@ -93,6 +93,10 @@ If there are no issues, return an empty list.
 
 Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you found (e.g., "3 issues found across 2 appraisers" or "No issues found") so sort can log it.
 
+### Human override awareness
+
+When reviewing an artefact, check the feedback history for `#human` tagged items. If a human has already ruled on a topic in a prior iteration, do not re-raise the same issue — the human's decision is final.
+
 ## What you do NOT do
 
 - You do not revise the artefact

package/skills/cycle/SKILL.md

@@ -2,12 +2,12 @@
 name: cycle
 type: composite
 description: Runs a foundry cycle by delegating all routing to the sort skill.
-composes: [sort, forge, quench, appraise, hitl]
+composes: [sort, forge, quench, appraise, human-appraise]
 ---
 
 # Cycle
 
-A foundry cycle reads its definition, sets up the work file for routing, then hands control to the sort skill which drives the forge/quench/appraise loop.
+A foundry cycle reads its definition, sets up the work file for routing, then hands control to the sort skill which drives the forge/quench/appraise/human-appraise loop.
 
 ## Prerequisites
 
@@ -22,7 +22,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 3. Determine the stage route:
    - Use the cycle definition's `stages` field if present
    - Otherwise generate defaults: always `forge`, add `quench` if `foundry_config_validation` returns non-null for the type, always `appraise`
-   - Cycle definitions can include `hitl` entries for human-in-the-loop checkpoints
+   - If the cycle definition has `human-appraise.enabled: true`, append `human-appraise` as the final stage
    - Stages should use `base:alias` format (e.g. `forge:write-haiku`, `quench:check-syllables`). If you pass bare names, the tool will auto-append the cycle ID as the alias.
 4. Call `foundry_workfile_set` to configure the work file:
    - `key: "cycle"`, `value: <cycle-id>`
@@ -47,9 +47,9 @@ When sort returns `blocked`:
 - Call `foundry_artefacts_set_status` with status `"blocked"`
 - Return control to the flow skill (the flow decides how to handle it)
 
-## HITL stages
+## Human Appraise
 
-Cycle definitions can include `hitl` entries in their stages list to pause for human input. When sort routes to a `hitl` stage, the hitl skill presents the configured prompt and records the human's response.
+If the cycle definition has `human-appraise.enabled: true`, the human-appraise stage is included after appraise. Sort will route to it after LLM appraisers pass, or earlier if a deadlock is detected.
 
 ## Micro commits
 
@@ -70,7 +70,7 @@ approved     - resolved
 rejected     - re-opened
 ```
 
-Tag types: `validation` (from quench), `law:<law-id>` (from appraise), `hitl` (from human) — indicates the source and category of feedback.
+Tag types: `validation` (from quench), `law:<law-id>` (from appraise), `human` (from human-appraise) — indicates the source and category of feedback.
 
 ## What you do NOT do
 

package/skills/flow/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: flow
 type: composite
-description: Orchestrates foundry cycles on a work branch, driven by a foundry flow definition.
+description: Orchestrates foundry cycles as a dependency graph, driven by a flow definition.
 composes: [cycle]
 ---
 
 # Flow
 
-A foundry flow reads a flow definition, creates a work branch, initialises the work file, and executes each foundry cycle in sequence.
+A foundry flow reads a flow definition, creates a work branch, and executes cycles by following the dependency graph — each cycle declares its own targets and input contracts.
 
 ## Prerequisites
 
@@ -15,26 +15,52 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
 
-## Starting a foundry flow
+## Starting a flow
 
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
-2. Call `foundry_git_branch` with name `work/<flow-id>-<short-description>` — create the work branch
-3. Call `foundry_workfile_create` with the flow ID, first cycle ID, and goal from the flow definition + human context
-4. Execute each cycle in order by invoking the cycle skill
-5. Between cycles: call `foundry_workfile_set` with `key: "cycle"`, `value: <next-cycle-id>`
-6. When all cycles are done: call `foundry_workfile_delete` — the artefacts and git history are the record
+2. Call `foundry_git_branch` with the flow ID and a short description — create the work branch
+3. Determine the starting cycle:
+   - If only one starting cycle, use it
+   - If multiple starting cycles, check whether the user's request makes the choice obvious (e.g., "write a haiku" clearly maps to `create-haiku`)
+   - If ambiguous, prompt the user to choose
+4. Call `foundry_workfile_create` with the flow ID, chosen cycle ID, and goal
+5. Execute the cycle by invoking the cycle skill
 
-## Completing a foundry flow
+## Between cycles
 
-When the flow is complete, the branch contains:
-- The finished artefacts
-- The full git history of micro commits showing every stage
+When a cycle completes (sort returns `done`):
 
-The human decides whether to merge, open a PR, or discard.
+1. Read the completed cycle's definition to find its `targets`
+2. If no targets → this branch of the flow is done. Proceed to "Completing a flow"
+3. If one target:
+   - Read the target cycle's definition
+   - Check input contract: `any-of` requires at least one listed artefact type to exist as a completed artefact; `all-of` requires all
+   - If satisfied → ask the user if they want to proceed, or run another starting cycle first
+   - If not satisfied → inform the user which artefacts are missing, offer to run cycles that produce them
+4. If multiple targets:
+   - Present the options to the user
+   - Check input contracts for each
+   - The user chooses which target to pursue (or which to pursue first)
+5. Set up the next cycle:
+   - Call `foundry_workfile_set` with `key: "cycle"`, `value: <next-cycle-id>`
+   - Reset stages and iteration count for the new cycle
+   - Execute the cycle by invoking the cycle skill
+
+## Completing a flow
+
+When all desired cycles are done:
+
+1. Present a summary of what was produced (all artefacts and their status)
+2. Ask the user how they want to finish:
+   - **Squash merge** — call `foundry_git_finish` with a commit message and base branch
+   - **Keep the branch** — leave as-is for manual handling
+   - **Create a PR** — push and create a pull request
+3. Execute the chosen option
 
 ## What you do NOT do
 
-- You do not skip cycles
-- You do not reorder cycles
+- You do not skip input contract validation
 - You do not modify artefacts directly — only cycles modify artefacts
 - You do not delete or rewrite feedback history during the flow
+- You do not route to a target cycle whose input contract is not met
+- You do not assume cycle order — follow the targets declared by each cycle

package/skills/forge/SKILL.md

@@ -50,9 +50,12 @@ An item is unresolved if it is:
 
 An item is resolved if it is `approved`.
 
-## Feedback tagged `#hitl`
+## #human feedback
 
-Feedback tagged `hitl` (human-in-the-loop) is treated the same as any other open feedback. Address it or wont-fix it using the same rules as other feedback items.
+Feedback tagged `human` (from the human-appraise stage) takes absolute priority:
+- You MUST address it — you cannot wont-fix `#human` feedback
+- When `#human` feedback contradicts LLM appraiser feedback on the same topic, follow the human's direction
+- Acknowledge the human's input in your revision
 
 ## What you do NOT do
 

package/skills/human-appraise/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: human-appraise
+type: atomic
+description: Human quality gate. Presents the artefact to the human for review and collects feedback tagged #human.
+---
+
+# 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.
+
+## Prerequisites
+
+Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+
+> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+
+## Protocol
+
+1. Gather context by calling:
+   - `foundry_workfile_get` — current state, goal, artefacts
+   - `foundry_artefacts_list` — current artefact files and status
+   - `foundry_feedback_list` — all existing feedback
+   - `foundry_history_list` — what has happened so far
+
+2. Read the artefact file(s) for this cycle.
+
+3. 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
+
+4. Wait for the human's response.
+
+5. Act on the response:
+   - **Approve** — "looks good" / "continue" — no feedback added, sort will advance
+   - **Provide feedback** — call `foundry_feedback_add` with the human's feedback and tag `human`. Sort will route back to forge.
+   - **Dismiss deadlocked feedback** — call `foundry_feedback_resolve` with `resolution: "approved"` on the deadlocked item(s). This overrides the appraiser.
+   - **Abort** — call `foundry_artefacts_set_status` with status `"blocked"`, cycle ends
+
+6. Return a clear summary of what the human decided so sort can log it in history.
+
+## #human feedback rules
+
+- Feedback tagged `human` takes priority over all LLM appraiser feedback
+- Forge MUST address `#human` feedback — it cannot wont-fix it
+- When `#human` feedback contradicts LLM appraiser feedback, forge follows the human's direction
+
+## What you do NOT do
+
+- You do not make decisions for the human — present the state and wait
+- You do not modify the artefact
+- You do not skip the pause — the human must respond before continuing
+- You do not filter or summarise away important details — show the full picture
+- You do not call `foundry_history_append` — sort owns history writing

package/skills/sort/SKILL.md

@@ -24,7 +24,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - `forge:*` — dispatch the forge skill as a sub-agent. Use model dispatch (see below).
    - `quench:*` — dispatch the quench skill as a sub-agent. Use model dispatch.
    - `appraise:*` — dispatch the appraise skill as a sub-agent. Use model dispatch. Note: the appraise skill handles its own per-appraiser model resolution internally.
-   - `hitl:*` — invoke the hitl skill (no model dispatch — human stage)
+   - `human-appraise:*` — invoke the human-appraise skill (no model dispatch — human stage)
    - `done` — foundry cycle is complete, return to the cycle skill
    - `blocked` — foundry cycle is blocked (iteration limit hit with unresolved feedback), return to the cycle skill
    - `violation` — file modification or tag validation violation detected (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"blocked"`, and return to the cycle skill

package/skills/upgrade-foundry/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: upgrade-foundry
+type: atomic
+description: Analyses and migrates foundry configuration to the current version format.
+---
+
+# Upgrade Foundry
+
+You analyse the entire `foundry/` directory and migrate configuration files to the current format, asking the user for clarification where needed.
+
+## Prerequisites
+
+Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+
+> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+
+## Protocol
+
+### 1. Scan entire foundry directory
+
+Read all configuration files:
+- `foundry/flows/*.md` — flow definitions
+- `foundry/cycles/*.md` — cycle definitions
+- `foundry/artefacts/*/definition.md` — artefact type definitions
+- `foundry/artefacts/*/laws.md` — type-specific laws
+- `foundry/artefacts/*/validation.md` — validation commands
+- `foundry/laws/*.md` — global laws
+- `foundry/appraisers/*.md` — appraiser definitions
+
+For each file, parse the frontmatter and body content.
+
+### 2. Detect what needs migration
+
+Check each file against the current expected format:
+
+**Flows:**
+- Has `starting-cycles` field? If not → needs DAG migration
+- Has ordered numbered list under `## Cycles`? → needs conversion to unordered list
+
+**Cycles:**
+- Has `targets` field? If not → needs target routing
+- Has `inputs.type` (`any-of`/`all-of`)? If `inputs` is a plain list → needs contract type
+- Has `hitl` in stages or frontmatter? → needs human-appraise migration
+- Has `human-appraise` config? Check format is correct
+- Has `models` map? Check format
+
+**Artefact types:**
+- Has required frontmatter fields (`id`, `name`, `file-patterns`)?
+- Has `appraisers` config if applicable?
+
+**Appraisers:**
+- Has `id` and personality content?
+- Has optional `model` field?
+- References any deprecated stage types?
+
+**Laws:**
+- Uses `## heading` per law?
+- Any structural issues?
+
+**Validation:**
+- Uses `Command:` / `Failure means:` format?
+- Commands have backticks that could cause issues? (Suggest removing — the parser strips them but clean is better)
+
+### 3. Present findings
+
+Present a grouped summary of all issues found:
+
+> **Migration Report**
+>
+> **Flows (N issues):**
+> - `creative-flow.md` — missing `starting-cycles`, has ordered cycle list
+>
+> **Cycles (N issues):**
+> - `create-haiku.md` — missing `targets` field
+> - `create-short-story.md` — inputs is plain list, needs `any-of`/`all-of` contract
+>
+> **Artefact types (N issues):**
+> - (none found)
+>
+> **Appraisers (N issues):**
+> - (none found)
+>
+> **Everything else clean**
+
+If nothing needs migration, say so and stop.
+
+### 4. Migrate flows
+
+For each flow needing migration:
+- Show the current ordered cycle list
+- Ask: which cycles are starting cycles?
+- Infer targets from adjacency (cycle N → cycle N+1)
+- Present the proposed `starting-cycles` and confirm
+- Convert numbered `## Cycles` list to unordered
+
+### 5. Migrate cycles
+
+For each cycle needing migration:
+
+**Targets:** Infer from the flow's old ordering. Present and confirm:
+> Cycle `create-haiku` was followed by `create-short-story` in the flow. Set `targets: [create-short-story]`?
+
+**Input contracts:** If inputs exist as a plain list, ask:
+> Cycle `create-short-story` has inputs `[haiku, limerick]`. Should it require:
+> 1. `any-of` — at least one must exist
+> 2. `all-of` — all must exist
+
+**HITL migration:** If `hitl` is found in stages:
+> Cycle `create-haiku` has an `hitl` stage. This has been replaced by `human-appraise`.
+> - Enable human-appraise? (yes/no)
+> - Deadlock threshold? (default: 3)
+
+Remove `hitl` from stages and add `human-appraise` config if enabled.
+
+### 6. Migrate other config
+
+For artefact types, appraisers, laws, and validation with issues:
+- Present each issue with a suggested fix
+- Ask the user to confirm or adjust
+
+### 7. Present migration plan
+
+Before writing anything, show the complete list of changes:
+- Group by category
+- Show each file and the specific changes
+- Ask for confirmation
+
+### 8. Apply changes
+
+- Update all affected files
+- Commit with message: `[foundry] upgrade: migrate to current format`
+
+## What you do NOT do
+
+- You do not create new cycles, artefact types, or appraisers
+- You do not delete existing files without confirmation
+- You do not modify artefact content (produced artefacts, not config)
+- You do not run automatically — the user invokes it explicitly
+- You do not guess when uncertain — ask the user

package/skills/hitl/SKILL.md

@@ -1,48 +0,0 @@
----
-name: hitl
-type: atomic
-description: Human-in-the-loop checkpoint. Pauses the cycle for human input before continuing.
----
-
-# HITL
-
-You are a human-in-the-loop checkpoint. Sort has routed to you because the cycle definition includes a pause point here. Your job is to present context, ask the human whatever needs asking, record their response, and return control to sort.
-
-## Prerequisites
-
-Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
-
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
-
-## Protocol
-
-1. Gather context by calling:
-   - `foundry_workfile_get` — current state, goal, artefacts
-   - `foundry_config_cycle` — cycle definition and hitl configuration
-   - `foundry_history_list` — what has happened so far
-   - `foundry_feedback_list` — any existing feedback
-
-2. Present to the human:
-   - A summary of where we are in the cycle (what's happened so far)
-   - The current state of the artefact (show it or summarise it)
-   - Any feedback that exists
-   - The prompt from the hitl configuration (or a sensible default: "The cycle has paused for your input. Here's the current state. How would you like to proceed?")
-
-3. Wait for the human's response.
-
-4. Act on the response:
-   - **Approve** — "looks good, continue" — no changes needed, sort will route to next stage
-   - **Request changes** — call `foundry_feedback_add` with the human's request and tag `"hitl"`
-   - **Provide context** — note in the history comment for future stages to reference
-   - **Abort** — call `foundry_artefacts_set_status` with status `"blocked"`, cycle ends
-
-5. Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what the human said or decided so sort can log it.
-
-6. Return control to the sort skill.
-
-## What you do NOT do
-
-- You do not make decisions for the human — present the state and wait
-- You do not modify the artefact
-- You do not skip the pause — the human must respond before continuing
-- You do not filter or summarise away important details — show the full picture