@really-knows-ai/foundry 2.1.0 → 2.3.0

package/skills/appraise/SKILL.md

@@ -14,34 +14,48 @@ 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.
 
+## Stage lifecycle (mandatory)
+
+Appraise runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt.
+2. **Last:** `foundry_stage_end({summary})`.
+
+Appraise makes **no disk writes**. All output flows through `foundry_feedback_add`. `foundry_stage_finalize` flags any unexpected writes as a violation.
+
 ## Protocol
 
-1. Gather context:
-   - Call `foundry_workfile_get` — identify the artefact to appraise and its type
-   - Call `foundry_config_laws` — get all applicable laws (global + type-specific)
-   - Call `foundry_config_artefact_type` with the type ID — get the artefact type definition
-   - Call `foundry_appraisers_select` with the type ID — returns selected appraiser personalities with their raw model IDs
+1. `foundry_stage_begin(...)`.
+2. Gather context:
+   - `foundry_workfile_get` — read the `cycle` from frontmatter
+   - `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate this cycle's artefacts. Always pass the `cycle` filter; omitting it returns stale rows from prior sessions. Skip rows whose status is `done` or `blocked`.
+   - For each remaining row, gather its type-specific context:
+     - `foundry_config_laws` with the row's type — applicable laws (global + type-specific)
+     - `foundry_config_artefact_type` with the type ID — the artefact type definition
+     - `foundry_appraisers_select` with the type ID — selected appraiser personalities with their raw model IDs
 
-2. Dispatch each appraiser as an independent sub-agent (see Dispatch below)
+3. Dispatch each appraiser as an independent sub-agent (see Dispatch below). If this cycle produced multiple artefacts, appraisers evaluate each.
 
-3. Collect results from all appraisers
+4. Collect results from all appraisers
 
-4. Consolidate (this is judgment):
+5. Consolidate (this is judgment):
    - Union of all issues — if any one appraiser flags it, it's feedback
    - De-duplicate: merge overlapping observations into a single feedback item
    - Preserve which appraiser(s) raised each issue (for traceability)
 
-5. For each consolidated issue: call `foundry_feedback_add` with the artefact file path, the issue description, and tag `law:<law-id>`
+6. For each consolidated issue: `foundry_feedback_add(file, text, tag: 'law:<law-id>')`. Tag MUST start with `law:` — the tool rejects other tags during appraise. The tool also de-duplicates by text-hash.
+
+7. If no appraiser found any issues, the artefact clears appraisal.
 
-6. If no appraiser found any issues, the artefact clears appraisal
+8. `foundry_stage_end({summary})`.
 
 ## Reviewing actioned and wont-fix feedback
 
 On subsequent passes, review previously actioned and wont-fix items:
 
-1. Call `foundry_feedback_list` to find `actioned` and `wontfix` items for this artefact
-2. For each item, the appraiser sub-agents evaluate whether the change addresses the issue (actioned) or the justification is sound (wont-fix)
-3. Call `foundry_feedback_resolve` with disposition `"approved"` or `"rejected"` (with reason) for each
+1. `foundry_feedback_list` — find `actioned` and `wont-fix` items for this artefact.
+2. Appraiser sub-agents evaluate whether the change addresses the issue (`actioned`) or the justification is sound (`wont-fix`).
+3. `foundry_feedback_resolve(file, index, resolution: 'approved'|'rejected', reason?)`. Appraise is the only stage (other than human-appraise) allowed to resolve `wont-fix` items.
 
 ## Dispatch
 
@@ -91,7 +105,7 @@ If there are no issues, return an empty list.
 
 ## History
 
-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.
+Do NOT call `foundry_history_append` or `foundry_git_commit` — the sort skill handles those. Return a summary via `foundry_stage_end` (e.g., "3 issues found across 2 appraisers" or "No issues found").
 
 ### Human override awareness
 
@@ -99,6 +113,8 @@ When reviewing an artefact, check the feedback history for `#human` tagged items
 
 ## What you do NOT do
 
-- You do not revise the artefact
-- You do not check deterministic rules — that is the quench skill's job
-- You do not filter out feedback because only one appraiser raised it — one is enough
+- You do not write files — all output goes through `foundry_feedback_add`.
+- You do not revise the artefact.
+- You do not check deterministic rules — that is the quench skill's job.
+- You do not filter out feedback because only one appraiser raised it — one is enough.
+- You do not register artefacts — that happens automatically via `foundry_stage_finalize`.

package/skills/flow/SKILL.md

@@ -2,7 +2,7 @@
 name: flow
 type: composite
 description: Runs a defined foundry flow to produce artefacts. Use this whenever the user references a flow by id, name, or paraphrase (e.g. "use the creative flow", "run creative-flow"). Do not brainstorm — the flow's cycles already define the work. The user's request is the goal to pass in.
-composes: [cycle]
+composes: [orchestrate]
 ---
 
 # Flow
@@ -23,8 +23,15 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
    - 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 **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `cycle` skill will read the cycle definition and populate those via `foundry_workfile_set` in the next step.
-5. Execute the cycle by invoking the cycle skill
+4. Pre-check for an existing workfile (prevents silent data loss from an aborted prior session):
+   a. Call `foundry_workfile_get`.
+   b. If it returns `{error: ...}` (no WORK.md), proceed to step 5.
+   c. If it returns an existing workfile, present its `flow`, `cycle`, and `goal` to the user alongside the values just requested, then prompt for one of:
+      - **Resume** — keep the existing workfile and skip to step 6. **Only offer resume if the existing `flow` AND `cycle` match what the user just asked for.** If either differs, do not offer resume — running the wrong cycle against stale state corrupts the workflow.
+      - **Discard** — call `foundry_workfile_delete`, then proceed to step 5.
+      - **Abort** — stop the skill without modifying anything.
+5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `orchestrate` skill will read the cycle definition and handle setup on its first call.
+6. Execute the cycle by invoking the orchestrate skill
 
 ## Between cycles
 
@@ -42,9 +49,9 @@ When a cycle completes (sort returns `done`):
    - 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
+   - Call `foundry_workfile_delete` to clear the completed cycle's WORK.md
+   - Call `foundry_workfile_create` with **only** the flow ID, the next cycle ID, and the goal — do **not** pass `stages` or `maxIterations`. The orchestrate skill will detect `needsSetup` on its first call and bootstrap the rest of the frontmatter from the cycle definition.
+   - Execute the cycle by invoking the orchestrate skill
 
 ## Completing a flow
 

package/skills/forge/SKILL.md

@@ -14,33 +14,42 @@ 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.
 
+## Stage lifecycle (mandatory)
+
+Forge runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — the orchestrator hands you `stage`, `cycle`, and an opaque `token` string in the dispatch prompt. Copy the token verbatim; never invent, edit, or re-sign it. No other tool call is permitted before this one. Any writes before `stage_begin` will be blocked by preconditions.
+2. **Last:** `foundry_stage_end({summary})` — return control to the orchestrator. After `stage_end`, the orchestrator calls `foundry_stage_finalize` which scans the disk and registers your output artefact. **You do not register artefacts yourself.**
+
 ## Protocol
 
 ### First generation (no artefact registered yet)
 
-1. Call `foundry_workfile_get` — understand the goal
-2. Call `foundry_config_cycle` — understand what to produce and what inputs are available
-3. Call `foundry_config_artefact_type` with the output type ID — get the artefact type definition
-4. Call `foundry_config_laws` — get all applicable laws (global + type-specific)
-5. If the cycle has inputs, read the input artefacts (read-only context)
-6. Produce the artefact, respecting all applicable laws from the start (this is judgment — use your craft)
-7. Write the artefact file to the location specified in the artefact type definition
-8. Call `foundry_artefacts_add` with the file path, type, and cycle to register it with status `"draft"`
+1. `foundry_stage_begin(...)` with the token from the dispatch prompt.
+2. `foundry_workfile_get` — understand the goal.
+3. `foundry_config_cycle` — understand what to produce and what inputs are available.
+4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
+5. `foundry_config_laws` — get all applicable laws (global + type-specific).
+6. If the cycle has inputs, read the input artefacts (read-only context).
+7. Produce the artefact, respecting all applicable laws from the start.
+8. Write the artefact file to a location that matches the artefact type's `file-patterns`.
+9. `foundry_stage_end({summary})`.
 
 ### Revision (feedback exists)
 
-1. Call `foundry_feedback_list` to find unresolved feedback for the artefact
-2. Read the artefact file
-3. If the cycle has inputs, read the input artefacts (read-only context)
-4. For each unresolved feedback item, either:
-   - Address it and call `foundry_feedback_action` with the item ID (marks as actioned)
-   - Call `foundry_feedback_wontfix` with the item ID and a justification (appraisal feedback only)
-5. Update the artefact file
-6. Wont-fix is only available for `law:` feedback (subjective appraisal). Validation feedback must be actioned — deterministic rules are not negotiable.
+1. `foundry_stage_begin(...)`.
+2. `foundry_feedback_list` — find unresolved feedback for the artefact.
+3. Read the artefact file.
+4. If the cycle has inputs, read the input artefacts (read-only context).
+5. For each unresolved feedback item, either:
+   - Address it and call `foundry_feedback_action` (marks item `actioned`), or
+   - Call `foundry_feedback_wontfix` with a justification — available only for `law:` / `human` tags (validation feedback must be actioned).
+6. Update the artefact file.
+7. `foundry_stage_end({summary})`.
 
-### After (both paths)
+## File-pattern hygiene
 
-Do NOT call `foundry_history_append` — the sort skill (your caller) is responsible for writing history. Instead, return a clear summary of what you did so sort can log it.
+Writes during forge must match the output artefact type's `file-patterns`. Writing to any other path causes `foundry_stage_finalize` to return `{error: 'unexpected_files'}` and the orchestrator will mark the cycle's target artefact `blocked`. You will not get a retry. Plus `WORK.md` and `WORK.history.yaml` (managed by tools). Nothing else.
 
 ## Unresolved feedback
 
@@ -53,14 +62,17 @@ An item is resolved if it is `approved`.
 ## #human feedback
 
 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
+- 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
 
-- You do not evaluate or score the artefact
-- You do not add feedback — that is the quench skill's and appraise skill's job
-- You do not mark feedback as actioned unless you actually changed the artefact to address it
-- You do not wont-fix validation feedback
-- You do not modify input artefacts — they are read-only
+- You do not add feedback — that is the quench and appraise skills' job. (`foundry_feedback_add` is blocked for you at the tool layer.)
+- You do not `foundry_feedback_resolve` — that belongs to quench/appraise/human-appraise.
+- You do not register artefacts — `foundry_stage_finalize` handles that automatically.
+- You do not call `foundry_history_append` or `foundry_git_commit` — the sort skill does.
+- You do not evaluate or score the artefact.
+- You do not mark feedback as actioned unless you actually changed the artefact to address it.
+- You do not wont-fix validation feedback.
+- You do not modify input artefacts — they are read-only.

package/skills/human-appraise/SKILL.md

@@ -14,17 +14,39 @@ 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.
 
+## Stage lifecycle (mandatory)
+
+Human-appraise runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt.
+2. **Last:** `foundry_stage_end({summary})`.
+
+Human-appraise makes **no disk writes**. All output flows through `foundry_feedback_add` / `foundry_feedback_resolve` / `foundry_artefacts_set_status`. `foundry_stage_finalize` flags unexpected writes as a violation.
+
+## Input
+
+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
+
+Your FIRST tool call must be `foundry_stage_begin({stage: 'human-appraise:<cycle>', cycle, token})`.
+
+Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence description of the user verdict>'})` — orchestrate reads this summary for the commit message.
+
 ## Protocol
 
-1. Gather context by calling:
-   - `foundry_workfile_get` — current state, goal, artefacts
-   - `foundry_artefacts_list` — current artefact files and status
+1. `foundry_stage_begin(...)`.
+2. Gather context by calling:
+   - `foundry_workfile_get` — current state, goal, cycle
+   - `foundry_artefacts_list({cycle: <current-cycle>})` — this cycle's artefact files and status (always pass the `cycle` filter; omitting it returns stale rows from prior sessions)
    - `foundry_feedback_list` — all existing feedback
    - `foundry_history_list` — what has happened so far
 
-2. Read the artefact file(s) for this cycle.
+3. Read the artefact file(s) for this cycle.
 
-3. Present to the human:
+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:
@@ -33,15 +55,15 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
      - Forge's wont-fix or revision justification
      - Ask the human to resolve the disagreement
 
-4. Wait for the human's response.
+5. 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. 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.
+   - **Dismiss deadlocked feedback** — `foundry_feedback_resolve(file, index, resolution: 'approved')`. Human-appraise may resolve items in state `actioned` or `wont-fix`. This overrides the appraiser.
+   - **Abort** — `foundry_artefacts_set_status(file, 'blocked')`, cycle ends.
 
-6. Return a clear summary of what the human decided so sort can log it in history.
+7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
 
 ## #human feedback rules
 
@@ -51,8 +73,10 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## 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
+- You do not write files — all output goes through foundry tools.
+- 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` or `foundry_git_commit` — sort owns those.
+- You do not register artefacts — handled by `foundry_stage_finalize`.

package/skills/orchestrate/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: orchestrate
+description: Runs a foundry cycle by calling foundry_orchestrate in a loop and acting on the returned action.
+---
+
+# Orchestrate
+
+You drive a foundry cycle by calling `foundry_orchestrate` repeatedly and acting on each returned `action`. The tool owns all step-ordering, history, committing, and routing. Your job is to dispatch subagents, run human-appraise when asked, and report terminal states.
+
+## Prerequisites
+
+Before running this skill, verify that `foundry/` exists in the project root and `WORK.md` has been created by the flow skill (with `flow`, `cycle`, and `goal` fields). If not, stop and tell the user to run the flow skill first.
+
+## Protocol
+
+Loop until `foundry_orchestrate` returns a terminal action (`done`, `blocked`, or `violation`):
+
+1. Call `foundry_orchestrate({lastResult})`. Omit `lastResult` on the first iteration. On subsequent iterations, pass `{kind, ok}` reflecting the previous action's outcome.
+
+2. Switch on the returned `action`:
+
+### `dispatch`
+
+Payload: `{stage, subagent_type, prompt}`.
+
+Call the `task` tool:
+```
+task tool:
+  subagent_type: <subagent_type-from-payload>
+  description: "Run <stage> for <cycle>"
+  prompt: <prompt-from-payload — pass verbatim>
+```
+
+When the task returns, call `foundry_orchestrate({lastResult: {kind: 'dispatch', ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{kind: 'dispatch', ok: false, error: '<message>'}`.
+
+### `human_appraise`
+
+Payload: `{stage, token, context}`.
+
+Invoke the `human-appraise` skill inline, passing `{cycle, token, context}`. The skill will prompt the user, collect feedback, and call `foundry_stage_end({summary})`.
+
+When it returns, call `foundry_orchestrate({lastResult: {kind: 'human_appraise', ok: true}})`.
+
+### `done`
+
+Payload: `{cycle, artefact_file, next_cycles}`.
+
+1. Call `foundry_artefacts_set_status({file: artefact_file, status: 'done'})`.
+2. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
+3. Return control to the flow skill.
+
+### `blocked`
+
+Payload: `{cycle, artefact_file, reason}`.
+
+Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The artefact has already been marked blocked.
+
+### `violation`
+
+Payload: `{details, affected_files}`.
+
+Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. Affected artefacts have already been marked blocked.
+
+## What you do NOT do
+
+- You do NOT inline forge / quench / appraise work. Always dispatch via `task`.
+- You do NOT mint, modify, or cache tokens. The `prompt` from orchestrate already contains the token verbatim.
+- You do NOT call `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, or `foundry_sort`. These are not registered tools in v2.3+; orchestrate handles them internally.
+- You do NOT reorder the protocol. `foundry_orchestrate` returns, you act, you call back. Nothing else between.

package/skills/quench/SKILL.md

@@ -14,33 +14,49 @@ 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.
 
+## Stage lifecycle (mandatory)
+
+Quench runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt. Any other tool call before this will be blocked.
+2. **Last:** `foundry_stage_end({summary})`.
+
+Quench makes **no disk writes**. You produce feedback via `foundry_feedback_add`, never by creating or modifying files. `foundry_stage_finalize` (run by the orchestrator after you return) will flag any unexpected writes as a violation.
+
 ## Protocol
 
-1. Call `foundry_workfile_get` to identify the artefact and its type.
-2. Call `foundry_config_validation` with the artefact type ID. If it returns null, output SKIP and stop — there is no validation for this type.
-3. Call `foundry_validate_run` with the type ID and artefact file path. It executes all validation commands and returns results.
-4. For each failure: call `foundry_feedback_add` with the artefact file path, a description of the failure, and tag `"validation"`.
-5. If all commands pass, add no new feedback.
+1. `foundry_stage_begin(...)`.
+2. `foundry_workfile_get` — read the `cycle` from frontmatter.
+3. `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate the artefacts produced by **this** cycle. Always pass the `cycle` filter; omitting it returns rows from prior sessions and validates stale files. Skip rows whose status is `done` or `blocked`.
+4. For each remaining row:
+   a. `foundry_config_validation` with the row's type. If it returns null, skip this row.
+   b. `foundry_validate_run` with the type ID and the row's file path — executes all validation commands and returns results.
+   c. For each failure: `foundry_feedback_add(file, text, tag: 'validation')`. Tag MUST be `validation` — the tool rejects other tags during quench.
+5. If every command passes for every row, add no new feedback.
+6. If the artefact table has no rows for this cycle, `foundry_stage_end({summary: 'SKIP: no artefacts registered for this cycle'})` and stop.
+7. `foundry_stage_end({summary})`.
 
 ## Reviewing actioned feedback
 
 On subsequent passes, review previously actioned items:
 
-1. Call `foundry_feedback_list` to find `actioned` items tagged `validation` for this artefact.
+1. `foundry_feedback_list` — find `actioned` items tagged `validation` for artefacts in this cycle (use the file list from step 3 above).
 2. Re-run the relevant command via `foundry_validate_run`.
-3. If the check now passes: call `foundry_feedback_resolve` with disposition `"approved"`.
-4. If it still fails: call `foundry_feedback_resolve` with disposition `"rejected"` and a reason.
+3. If the check now passes: `foundry_feedback_resolve(file, index, resolution: 'approved')`.
+4. If it still fails: `foundry_feedback_resolve(file, index, resolution: 'rejected', reason)`.
 
-There is no wont-fix for validation feedback. Deterministic rules are not negotiable.
+There is no wont-fix for validation feedback — deterministic rules are not negotiable. Quench may only resolve items in state `actioned`; the feedback tool enforces this.
 
 ## History
 
-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., "2 validation issues found" or "Validation passed") so sort can log it.
+Do NOT call `foundry_history_append` or `foundry_git_commit` — the sort skill handles those. Return a clear summary via `foundry_stage_end` (e.g., "2 validation issues found" or "Validation passed").
 
 ## What you do NOT do
 
-- You do not make subjective judgments
-- You do not revise the artefact
-- You do not evaluate laws — that is the appraise skill's job
-- You do not invent validation rules — you only run commands from the validation config
-- You do not duplicate feedback that already exists
+- You do not write files — all output goes through `foundry_feedback_add`.
+- You do not make subjective judgments.
+- You do not revise the artefact (forge's job).
+- You do not evaluate laws — that is the appraise skill's job.
+- You do not invent validation rules — you only run commands from the validation config.
+- You do not duplicate feedback that already exists (the tool de-duplicates by text-hash, but don't rely on it).
+- You do not register artefacts — that happens automatically.

package/skills/upgrade-foundry/SKILL.md

@@ -46,7 +46,7 @@ Check each file against the current expected format:
 - 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 nested `human-appraise: {enabled, deadlock-threshold}`? → v2.2.1 flat-keys migration (see §4b)
 - Has `models` map? Check format
 
 **Artefact types:**
@@ -98,6 +98,69 @@ For each `.opencode/agents/foundry-*.md` file with a `.` in its filename:
 
 After renaming, remind the user: **Restart OpenCode** for the new agent filenames to register.
 
+### 4a. v2.2.0 lifecycle upgrade
+
+Foundry v2.2.0 introduces a tool-enforced stage lifecycle (`stage_begin` / `stage_end` / `stage_finalize`) backed by a per-project state directory and HMAC-signed dispatch tokens. The upgrade is non-destructive — no WORK.md or artefact migration is required — but the project needs three small changes:
+
+1. **Create `.foundry/`** (if absent):
+   - `mkdir -p .foundry`
+   - The plugin auto-creates `.foundry/.secret` on first boot via `readOrCreateSecret`. You do not need to generate it by hand; just ensure the directory exists and is writable.
+2. **Gitignore `.foundry/`**:
+   - Ensure `.gitignore` contains a line `.foundry/` (append if missing; do not duplicate). The directory holds a per-worktree HMAC secret and transient active-stage state — neither should be committed.
+3. **Pre-existing state:** v2.2.0 is a fresh state system. There is no `active-stage.json` to migrate. If one happens to exist from a manually-aborted prior run, leave it alone — the new plugin treats its absence as "no active stage" and its presence as a legitimate in-flight stage.
+
+The `foundry_artefacts_add` tool has been removed in v2.2.0 — artefact registration now happens automatically via `foundry_stage_finalize`. No existing config references this tool, so there is nothing to migrate in `foundry/`.
+
+### 4b. v2.2.1 cycle-definition flat human-appraise keys
+
+v2.2.1 replaces the nested `human-appraise: {enabled, deadlock-threshold}` block in cycle definitions with three flat keys:
+
+```yaml
+human-appraise: <true|false>         # default: false — run human-appraise every iteration
+deadlock-appraise: <true|false>      # default: true — pull in human-appraise when LLM appraisers deadlock
+deadlock-iterations: <number>        # default: 5 — deadlock detection threshold
+```
+
+For each `foundry/cycles/*.md` whose frontmatter has the old nested form, migrate:
+
+- `human-appraise.enabled: true` → `human-appraise: true`
+- `human-appraise.enabled: false` (or missing) → `human-appraise: false`
+- `human-appraise.deadlock-threshold: N` → `deadlock-iterations: N`
+- Always add `deadlock-appraise: true` unless the user explicitly wants the stricter "no human ever" behavior (`deadlock-appraise: false` → deadlock marks the cycle `blocked`).
+
+The old nested form is no longer read. After migration, verify by asking: "cycle `<id>`: human-appraise every iteration? deadlock-appraise on? deadlock-iterations = N?".
+
+### 4c. v2.2.x → v2.3.0
+
+v2.3.0 replaces the LLM-driven sort orchestrator with the `foundry_orchestrate` plugin tool. The `cycle` and `sort` skills are removed. Six tools are deregistered: `foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_configure_from_cycle`, `foundry_workfile_set`.
+
+#### Pre-flight checks
+
+Before upgrading, verify a clean base state. Abort the upgrade if any of these fail:
+
+1. **Branch**: must be on `main` (or the user's configured default base branch).
+   - Check: `git rev-parse --abbrev-ref HEAD` — must match expected default.
+   - If on `work/*`: abort with "You're on a work branch. Switch to main and complete or discard any in-flight flow before upgrading."
+
+2. **Working tree**: must be clean.
+   - Check: `git status --porcelain` — must be empty.
+   - If dirty: abort with "Uncommitted changes. Commit or stash before upgrading."
+
+3. **In-flight workfile**: `WORK.md` must not exist.
+   - Check: is `WORK.md` present in the repo root?
+   - If yes: abort with "In-flight workfile detected. Delete it (`foundry_workfile_delete`) or complete the cycle before upgrading."
+
+Only when all three pass, proceed with the plugin swap.
+
+#### Upgrade steps
+
+1. Install the new plugin package version: `npm install @really-knows-ai/foundry@2.3.0 --save-dev`.
+2. Swap `.opencode/plugins/foundry.js` with the new version from `node_modules/@really-knows-ai/foundry/.opencode/plugins/foundry.js`.
+3. Remove `skills/cycle/` and `skills/sort/` directories from the project if they exist locally (they shouldn't — skills live in the package).
+4. Commit the upgrade: `chore: upgrade foundry to 2.3.0`.
+
+No state migration is performed. In-flight cycles from v2.2.x must be completed or discarded before upgrading.
+
 ### 5. Migrate flows
 
 For each flow needing migration:

package/skills/cycle/SKILL.md

@@ -1,81 +0,0 @@
----
-name: cycle
-type: composite
-description: Runs a foundry cycle by delegating all routing to the sort skill.
-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/human-appraise loop.
-
-## 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.
-
-## Starting a foundry cycle
-
-1. Call `foundry_config_cycle` with the cycle ID — get the cycle definition
-2. Call `foundry_config_artefact_type` with the output type ID — get the artefact type definition
-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`
-   - 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>`
-   - `key: "stages"`, `value: <determined stages list>`
-   - `key: "max-iterations"`, `value: <default 3 or from cycle definition>`
-   - If the cycle definition has a `models` map: `key: "models"`, `value: <models map>`
-5. Invoke the sort skill
-
-## Sort drives everything
-
-Once sort is invoked, it calls `foundry_sort` to determine the next stage, invokes the corresponding skill, then calls sort again. This repeats until sort returns `done` or `blocked`.
-
-The cycle skill does not contain routing logic — sort owns all of that.
-
-## Completing a foundry cycle
-
-When sort returns `done`:
-- Call `foundry_artefacts_set_status` with status `"done"`
-- Return control to the flow skill
-
-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)
-
-## Human Appraise
-
-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
-
-Every stage must end with a micro commit. Call `foundry_git_commit` with message format: `[<cycle-id>] <base>:<alias>: <brief description>`
-
-Examples:
-- `[haiku-creation] forge:write-haiku: initial draft`
-- `[haiku-creation] quench:check-syllables: checked syllable pattern`
-- `[haiku-creation] forge:write-haiku: addressed validation feedback`
-
-## Feedback states
-
-```
-open         - needs generator action
-actioned     - needs approval
-wont-fix     - needs approval (appraisal only)
-approved     - resolved
-rejected     - re-opened
-```
-
-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
-
-- You do not make routing decisions — sort does that
-- You do not change the laws mid-cycle
-- You do not decide the artefact is "close enough" — it passes or it doesn't
-- You do not proceed past a file modification violation
-- You do not modify input artefacts — they are read-only