@really-knows-ai/foundry 2.3.0 → 2.3.2

package/docs/concepts.md

@@ -1,59 +1,122 @@
 # Concepts
 
-Core concepts and how they relate.
+This is the glossary. Every term here has a single definition and links out to the spec document that elaborates it. Concepts are arranged roughly top-down: flows contain cycles, cycles contain stages, stages operate on artefacts, artefacts are governed by laws and evaluated by appraisers.
 
-## Foundry Flow
+---
 
-A foundry flow is the top-level unit of work. It is defined in `foundry/flows/` and lists the foundry cycles to execute in order. Starting a foundry flow creates a work branch and a WORK.md file. A foundry flow is complete when all its foundry cycles are done.
+## Flow
 
-## Foundry Cycle
+The top-level unit of work. Defined in `foundry/flows/*.md`. A flow declares:
 
-A foundry cycle is an iterative loop that produces a single artefact type. It is defined in `foundry/cycles/` and specifies:
-- An output artefact type (read-write)
-- Zero or more input artefact types (read-only, from previous foundry cycles)
+- A `starting-cycles` list — hints about which cycles can be entered first when the flow begins.
+- A set of cycles (listed under `## Cycles`). Order is not implied — routing between cycles is owned by cycles themselves via their `targets` field.
 
-A foundry cycle runs: forge → quench → appraise, repeating until all feedback is resolved or the iteration limit is hit.
+Running a flow creates a work branch and a `WORK.md`. The flow completes when no more reachable cycles remain to run, or when the user decides to stop.
+
+## Cycle
+
+An iterative loop that produces a single artefact type. Defined in `foundry/cycles/*.md`. A cycle declares:
+
+- `output` — the artefact type it produces (read-write).
+- `inputs` — a contract (`any-of` / `all-of`) over other artefact types. Inputs are discovered on disk; they are read-only unless the output type's patterns happen to cover them.
+- `targets` — the cycle(s) that may run after this one. May be empty (terminal cycle).
+- `human-appraise` — whether a human quality gate runs every iteration (default: `false`).
+- `deadlock-appraise` — whether a human is pulled in when LLM appraisers deadlock (default: `true`).
+- `deadlock-iterations` — deadlock threshold (default: `5`).
+- `models` — optional per-stage model overrides.
+
+A cycle runs **forge → quench → appraise** (and optionally **human-appraise**), looping until all feedback is resolved or `max-iterations` is hit.
 
 ## Stage
 
-The steps within a foundry cycle. Each stage is referenced using a `base:alias` format (e.g. `forge:write-haiku`) where the base is the stage type and the alias describes its role in that cycle.
+A single step within a cycle. Every stage is referenced as `base:alias` (e.g. `forge:write-haiku`, `quench:check-syllables`) — the base is the stage type; the alias makes the stage's role self-documenting in WORK.md.
 
-- Forge — produce or revise the artefact
-- Quench — run deterministic CLI checks
-- Appraise — subjective evaluation by multiple appraisers
-- HITL — human-in-the-loop checkpoint (see below)
+Stage bases:
+
+- **forge** — produce or revise the artefact.
+- **quench** — run deterministic CLI checks (skipped if the artefact type has no `validation.md`).
+- **appraise** — subjective evaluation by multiple appraiser sub-agents.
+- **human-appraise** — human quality gate. Can run every iteration, only on deadlock, or both.
+
+Every stage runs inside a token-gated lifecycle (`foundry_stage_begin` / `foundry_stage_end` / `foundry_stage_finalize`). Mutation tools are stage-locked: a forge stage can't add feedback, a quench stage can't register artefacts. See the enforcement section of the [README](../README.md#enforcement-model).
 
 ## Artefact type
 
-A definition of what kind of thing is being produced. Lives in `foundry/artefacts/<type>/` with:
-- `definition.md` — identity, file patterns, output location, prose description
-- `laws.md` — type-specific subjective evaluation criteria
-- `validation.md` — CLI commands for deterministic quench checks
+A definition of what is being produced. Lives in `foundry/artefacts/<type>/`:
+
+- `definition.md` — identity, file patterns, output directory, appraiser config, prose description.
+- `laws.md` *(optional)* — type-specific subjective criteria.
+- `validation.md` *(optional)* — CLI commands for deterministic quench checks.
+
+File patterns must not overlap with any other artefact type's patterns — the write-invariant enforcer needs to know which type owns a given file.
 
 ## Law
 
-A subjective pass/fail criterion. Global laws live in `foundry/laws/` (all files concatenated). Type-specific laws live in `foundry/artefacts/<type>/laws.md`. Each law has an identifier (its heading), used in feedback tags.
+A subjective pass/fail criterion. Two scopes:
+
+- **Global** — `foundry/laws/*.md`, all files concatenated, applies to every artefact.
+- **Type-specific** — `foundry/artefacts/<type>/laws.md`.
+
+Each law is a `## heading` (its identifier, used in feedback tags as `#law:<id>`) with a description, passing criteria, and failing criteria.
 
 ## Appraiser
 
-An independent evaluator with a defined personality. Lives in `foundry/appraisers/`. Each appraiser can optionally specify a `model` to override the cycle-level appraise model. Model diversity is configured at the cycle level (via the `models` frontmatter map) and optionally per-appraiser. They can be assigned to specific artefact types or appraise everything.
+An independent evaluator with a defined personality. Lives in `foundry/appraisers/*.md`. Appraisers may specify a `model` field to override the cycle-level appraise model. Each artefact type picks which appraisers may evaluate it (`appraisers.allowed`) and how many run per iteration (`appraisers.count`). Selection distributes evenly across allowed personalities.
 
 ## WORK.md
 
-The transient shared state for a foundry flow. Created on the work branch, it tracks: where the foundry flow is (frontmatter cursor), what artefacts exist, and all feedback with its full lifecycle. See [work-spec.md](work-spec.md) for the full spec.
+The transient shared state for a flow. Created on the work branch by the flow skill, it tracks:
+
+- Current position (flow, cycle, stage list, iteration limits) in frontmatter.
+- The goal (prose — written once).
+- An artefact registry (file, type, cycle, status).
+- All feedback with its full lifecycle.
+
+See [work-spec.md](work-spec.md) for the full spec.
+
+## WORK.history.yaml
+
+Append-only log of every stage execution, sitting next to WORK.md. Used by sort to reconstruct what has happened in the current cycle. See [work-spec.md](work-spec.md).
 
 ## Feedback
 
-The communication mechanism between stages. Written as markdown checklist items in WORK.md with tags (`#validation` or `#law:<id>`). Follows a lifecycle: open → actioned/wont-fix → approved/rejected. See [work-spec.md](work-spec.md) for details.
+The communication mechanism between stages. Written as markdown checklist items in WORK.md, grouped by artefact file, tagged by source:
+
+- `#validation` — from a deterministic quench command. Cannot be wont-fixed.
+- `#law:<law-id>` — from an appraiser, tied to a specific law. May be wont-fixed with justification.
+- `#human` — from a human-appraise stage. Takes absolute priority; cannot be wont-fixed.
+
+Lifecycle: `open` → `actioned` / `wont-fix` → `approved` / `rejected`. `approved` is terminal; `rejected` re-opens. Items are never deleted.
+
+## HITL / human-appraise
+
+Human-in-the-loop checkpoint. A stage where Foundry pauses and asks a human for input. Two triggers:
+
+1. **Every-iteration** — the cycle declares `human-appraise: true`. The `human-appraise` stage runs after LLM appraise each iteration.
+2. **Deadlock** — the cycle declares `deadlock-appraise: true` (default). If forge and appraisers ping-pong on the same items for `deadlock-iterations` (default 5) iterations, sort inserts a `human-appraise` stage to break the tie.
 
-## HITL
+Human feedback is tagged `#human` and takes priority over LLM feedback on the same topic.
 
-Human-in-the-loop checkpoint. A stage type that pauses the foundry cycle and requests human input before continuing. Configured per cycle by including a `hitl:alias` entry in the `stages` list. When a hitl stage runs, it presents the current artefact state to the human and collects feedback tagged `#hitl`. Like other feedback, hitl feedback follows the standard lifecycle (open → actioned → approved/rejected).
+## Micro-commit
 
-## Micro commit
+Every stage ends with a commit made by the orchestrator. This enables two things: file-modification enforcement (the write-invariant check compares the stage's diff to its allowed patterns) and recoverability (a crash mid-flow leaves a clean commit boundary to resume from). Orchestration refuses to proceed if uncommitted work is lingering in `WORK.md`, `WORK.history.yaml`, or `.foundry/`.
 
-Every stage ends with a commit (via the `foundry_git_commit` tool). This enables file modification enforcement — the sort tool checks the git diff to ensure each stage only touched files it was allowed to.
+## Stage token
+
+A single-use HMAC-signed string, minted by `foundry_orchestrate` when a stage is dispatched. The sub-agent must redeem the token via `foundry_stage_begin`; mutation tools then check the active stage matches their role. Keys live in `.foundry/.secret` (mode 0600, gitignored, one per worktree). This prevents out-of-band mutations, replayed stages, and sub-agents skipping the lifecycle.
+
+## `.foundry/` state directory
+
+A gitignored directory created on first plugin boot, holding runtime state:
+
+- `.secret` — the HMAC key.
+- `active-stage.json` — present only during an active stage.
+- `last-stage.json` — used by `foundry_stage_finalize` after `stage_end`.
 
 ## Custom tools
 
-All deterministic pipeline operations are exposed as custom tools via the Foundry plugin. Skills call tools instead of manipulating files directly. The tools are backed by shared library modules in `scripts/lib/` with injectable I/O for testability. This separation ensures that file format parsing, state transitions, and routing logic are handled by tested code rather than LLM interpretation.
+All deterministic pipeline operations are exposed as custom tools by the Foundry plugin. Skills call these tools instead of manipulating files directly. Tools are backed by shared library modules in `scripts/lib/` with injectable I/O so they can be unit-tested. This separation ensures state transitions and routing logic are tested code, not LLM interpretation. See the [README](../README.md#custom-tools) for the full catalogue.
+
+## Skill
+
+A self-contained workflow written as markdown with YAML frontmatter. Foundry ships pipeline skills (`flow`, `orchestrate`, `forge`, `quench`, `appraise`, `human-appraise`), authoring skills (`add-*`, `init-foundry`), and utility skills (`list-agents`, `refresh-agents`, `upgrade-foundry`). Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).

package/docs/getting-started.md

@@ -1,78 +1,187 @@
 # Getting Started
 
-How to set up and run your first foundry flow.
+End-to-end walkthrough for setting up Foundry and running your first flow.
+
+---
 
 ## Prerequisites
 
-- Git repository initialised
-- Node.js available (for validation scripts)
-- An AI coding tool that supports skills (OpenCode, Claude Code, Copilot CLI, etc.)
+- A git repository initialised with a clean working tree.
+- Node.js ≥ 18.3.0 (for the plugin and validation scripts).
+- [OpenCode](https://opencode.ai) (primary target — multi-model routing relies on OpenCode's agent files).
+
+## Install
+
+Add Foundry to `opencode.json`:
+
+```json
+{
+  "packages": {
+    "@really-knows-ai/foundry": "latest"
+  }
+}
+```
+
+Restart OpenCode (or reload plugins) so the plugin registers its tools and skills.
+
+## Initialize
+
+In your project, invoke the `init-foundry` skill. It:
+
+1. Creates the `foundry/` directory structure:
+   ```
+   foundry/
+     artefacts/.gitkeep
+     flows/.gitkeep
+     cycles/.gitkeep
+     laws/.gitkeep
+     appraisers/.gitkeep
+   ```
+2. Runs `refresh-agents` to generate `.opencode/agents/foundry-*.md` — one per available model — so cycles can dispatch to specific models later.
+3. Commits the scaffolding.
+
+The `.foundry/` runtime directory (holding `.secret` for stage tokens) is created automatically on first plugin boot and added to `.gitignore`.
 
-## Step by step
+---
+
+## Author the configuration
+
+Foundry's configuration is five things: artefact types, laws, appraisers, cycles, and flows. You can write the files by hand, but the authoring skills do conflict checking, scaffolding, and validation — use them.
 
 ### 1. Define an artefact type
 
-Create a directory under `foundry/artefacts/` with three files:
+Run `add-artefact-type`. It walks you through:
 
-```
-foundry/artefacts/my-type/
-  definition.md    # what it is, file patterns, output location
-  laws.md          # subjective laws (optional)
-  validation.md    # CLI validation commands (optional)
-```
+- `id` (lowercase, hyphenated), `name`, prose description.
+- `file-patterns` — glob patterns describing which files this type owns. The skill refuses patterns that overlap with existing types.
+- `output-dir` — where forge should write new files.
+- Appraiser config — how many appraisers evaluate this type and which personalities are allowed.
+- Optional `laws.md` — type-specific criteria.
+- Optional `validation.md` — CLI commands for quench (non-zero exit = failure).
 
-Use the `init-foundry` skill to scaffold the `foundry/` directory, then use `add-artefact-type` to create your first artefact type interactively — or create the directory structure above manually.
+Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`, `validation.md`).
 
 ### 2. Write laws
 
-Add global laws to any `.md` file in `foundry/laws/`. Add type-specific laws to `foundry/artefacts/<type>/laws.md`.
+Laws are subjective pass/fail criteria evaluated by appraisers. Two scopes:
+
+- **Global** — `foundry/laws/*.md`. All files are concatenated and apply to every artefact.
+- **Type-specific** — `foundry/artefacts/<type>/laws.md`.
 
-Each law is a `##` heading with: a description, what passing looks like, and what failing looks like.
+Run `add-law` to create one with conflict detection. Each law is a `## heading` (its identifier, referenced as `#law:<id>` in feedback) with a description, passing criteria, and failing criteria.
 
-### 3. Define a foundry cycle
+### 3. Create appraisers
 
-Create a file in `foundry/cycles/` that specifies what artefact type the foundry cycle produces and what inputs it reads:
+Appraisers are independent evaluators with named personalities. Run `add-appraiser`. Each appraiser may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
 
-```yaml
+### 4. Define a cycle
+
+Run `add-cycle`. A cycle produces one artefact type and declares:
+
+- `output` — the artefact type (must already exist).
+- `inputs` — a contract (`any-of` or `all-of`) over other types. Empty for starting cycles.
+- `targets` — the cycle(s) that may run after this one. Empty for terminal cycles.
+- `human-appraise` / `deadlock-appraise` / `deadlock-iterations` — human-gate config.
+- `models` — optional per-stage model overrides.
+
+Example:
+
+```markdown
 ---
-id: my-cycle
-name: My Cycle
-output: my-type
-inputs: []
+id: haiku-creation
+name: Haiku Creation
+output: haiku
+inputs:
+  type: any-of
+  artefacts:
+    - petition
+targets: []
+human-appraise: false
+deadlock-appraise: true
+deadlock-iterations: 5
+models:
+  appraise: openai/gpt-5
 ---
+
+# Haiku Creation
+
+Writes a haiku satisfying the petition produced by haiku-ideation.
 ```
 
-Cycles list their stages using `base:alias` format — e.g. `forge:write-haiku`, `quench:check-syllables`. The alias makes each stage's purpose clear when reading WORK.md. You can also include `hitl:alias` stages for human-in-the-loop checkpoints.
+The skill validates that every input type can be produced by some cycle in the flow and that targets are reachable.
 
-### 4. Define a foundry flow
+### 5. Define a flow
 
-Create a file in `foundry/flows/` that lists foundry cycles in order:
+Run `add-flow`. A flow groups cycles and declares starting points:
 
 ```markdown
 ---
-id: my-flow
-name: My Flow
+id: make-haiku
+name: Make a Haiku
+starting-cycles:
+  - haiku-ideation
 ---
 
-# My Flow
+# Make a Haiku
 
-Description of what this flow produces.
+End-to-end flow: petition → haiku, with a human quality gate.
 
 ## Cycles
 
-1. my-cycle
+- haiku-ideation
+- haiku-creation
 ```
 
-### 5. Run the foundry flow
+Routing between cycles is owned by individual cycles via their `targets`, not by the flow.
+
+---
+
+## Run the flow
+
+Tell OpenCode something like:
+
+> Run the `make-haiku` flow to write a haiku about autumn rain.
+
+The `flow` skill will:
+
+1. Check prerequisites and pick a starting cycle — matching your prose to a cycle's output type. If the request is ambiguous, it prompts (defaulting to `starting-cycles`). If a cycle's input contract can't be satisfied from files on disk, it won't be chosen.
+2. Create a work branch and scaffold `WORK.md` with the goal.
+3. Hand off to `orchestrate`, which drives the cycle:
+   - **forge** writes the artefact.
+   - **quench** runs CLI validators (if configured).
+   - **appraise** dispatches parallel appraiser sub-agents and consolidates their `#law:<id>` feedback.
+   - **human-appraise** (if configured, or on deadlock) asks you for input.
+   - If any unresolved feedback remains, another forge iteration begins.
+4. When the cycle completes, the flow skill checks the cycle's `targets`. If a target's input contract is satisfied, it asks whether to proceed.
+5. When all desired cycles are done, the flow skill summarises the output and asks how to finish — squash-merge, PR, or leave the branch.
+
+Every stage ends with a micro-commit. Violations of the write invariant (writing to disallowed files) hard-stop the cycle.
+
+---
+
+## Inspecting progress
+
+While a flow is running, the state of the world is in three places:
 
-Tell your AI tool to start the foundry flow. It will create a work branch, initialise WORK.md, and begin executing foundry cycles.
+- `WORK.md` — current cycle, goal, artefact table, all feedback with full lifecycle.
+- `WORK.history.yaml` — append-only log of every stage execution.
+- `git log` — one commit per stage.
+
+You can pause and resume: if the flow skill sees an existing `WORK.md` when you start, it asks whether to resume, discard, or abort. Resume is only offered if the existing flow and cycle match the current request.
+
+---
+
+## Cleaning up
+
+Before squash-merging the work branch back into main, **delete `WORK.md` and `WORK.history.yaml`** — they're ephemeral per-flow state, not artefacts. `.foundry/` is gitignored and doesn't need cleanup.
+
+If you used `foundry_git_finish`, it handles this for you.
+
+---
 
-## What happens during a foundry flow
+## Next steps
 
-1. The foundry flow skill creates a branch and WORK.md
-2. For each foundry cycle:
-   - Forge produces the artefact
-   - Quench runs CLI commands (if defined)
-   - Appraise dispatches sub-agent appraisers against the laws
-   - If feedback exists, forge revises and the foundry cycle repeats
-3. When all foundry cycles complete, the human decides to merge, PR, or discard
+- [docs/concepts.md](concepts.md) — concise glossary.
+- [docs/work-spec.md](work-spec.md) — full WORK.md spec.
+- [README.md](../README.md) — architecture, enforcement, design decisions.
+- [CHANGELOG.md](../CHANGELOG.md) — version history.

package/docs/work-spec.md

@@ -10,23 +10,31 @@ 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
+models:
+  forge: anthropic/claude-opus-4.7
+  appraise: openai/gpt-5
 ---
 ```
 
 Fields:
-- `flow` — the foundry flow being executed
-- `cycle` — the current foundry cycle id
-- `stages` — the ordered route for this foundry cycle, set when the foundry cycle starts. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, or `hitl`) and `alias` is a human-readable name for what that stage does in this cycle. Determined from the artefact type: if `validation.md` exists, include `quench`; always include `forge` and `appraise`. A `hitl` stage can be included for human-in-the-loop checkpoints.
-- `max-iterations` — how many forge passes before the foundry cycle is blocked (default: 3)
+- `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`, or `human-appraise`) and `alias` is a human-readable name for what that stage does in this cycle. Derived from the cycle and artefact type: `forge` + `appraise` are always included, `quench` is included iff the artefact type has `validation.md`, `human-appraise` is included iff the cycle sets `human-appraise: true`.
+- `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).
+- `models` — optional per-stage model overrides; individual appraisers may further override via their own `model` field.
 
-The `stages` list is the happy path. Sort follows it but loops back to `forge` when unresolved feedback demands it.
+The `stages` list is the happy path. Sort follows it but loops back to `forge` when unresolved feedback demands it, and inserts a `human-appraise` stage on deadlock.
 
 ### Who sets what
 
-- `flow` — set by the foundry flow skill at foundry flow start, never changes
-- `cycle` — set by the foundry flow skill when starting each foundry cycle
-- `stages` — set by the orchestrate skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
-- `max-iterations` — set by the orchestrate skill (default 3, could be overridden in foundry cycle definition)
+- `flow`, `cycle`, `goal` — set by the `flow` skill via `foundry_workfile_create` at flow/cycle boundaries.
+- `stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
 
 ## Sections
 
@@ -70,7 +78,7 @@ Grouped by artefact file path. Each item is a checklist entry with a tag indicat
 
 - `#validation` — from a deterministic quench command
 - `#law:<law-id>` — from subjective appraise, tied to a specific law
-- `#hitl` — from human-provided feedback at a hitl checkpoint
+- `#human` — from human-provided feedback at a human-appraise checkpoint
 
 #### Lifecycle states
 
@@ -86,20 +94,23 @@ Grouped by artefact file path. Each item is a checklist entry with a tag indicat
 
 #### Rules
 
-- Validation feedback (`#validation`) cannot be wont-fixed
-- Feedback is never deleted — it stays as a record of the iteration history
-- New feedback is appended, not inserted
-- Items are grouped under the artefact they relate to
+- Validation feedback (`#validation`) cannot be wont-fixed — deterministic rules are not negotiable.
+- Human feedback (`#human`) cannot be wont-fixed — it takes absolute priority over LLM feedback.
+- Feedback is never deleted — it stays as a record of the iteration history.
+- New feedback is appended, not inserted.
+- Items are grouped under the artefact they relate to.
 
 ## Who writes what
 
 | Section | Written by | Updated by |
 |---------|-----------|------------|
-| Frontmatter (`flow`) | `foundry_workfile_create` (flow skill) | nobody |
-| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (orchestrate skill) | `foundry_workfile_set` (reset on each new cycle) |
+| Frontmatter (`flow`, `cycle`, `goal`) | `foundry_workfile_create` (flow skill) | `foundry_workfile_delete` + re-create 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 |
 | Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (orchestrate skill) |
-| Feedback | `foundry_feedback_add` (quench/appraise/hitl) | `foundry_feedback_action`/`foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench/appraise/hitl) |
+| Artefacts | `foundry_stage_finalize` (orchestrator, after forge closes) | `foundry_artefacts_set_status` (orchestrator → `done`/`blocked`) |
+| Feedback | `foundry_feedback_add` (quench / appraise / human-appraise) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench / appraise / human-appraise) |
+
+Note: `foundry_artefacts_add` no longer exists as a public tool — artefact registration is automatic via `stage_finalize`, which scans the git diff and registers files matching the output type's `file-patterns` as `draft`.
 
 ## WORK.history.yaml
 
@@ -141,20 +152,20 @@ A separate file (`WORK.history.yaml`) alongside WORK.md. Append-only log of ever
 
 - `timestamp` — ISO 8601 UTC
 - `cycle` — which foundry cycle this entry belongs to
-- `stage` — which stage just completed, in `base:alias` format (e.g. `forge:draft-petition`, `quench:validate-petition`, `appraise:review-petition`, `hitl:human-review`)
+- `stage` — which stage just completed, in `base:alias` format (e.g. `forge:draft-petition`, `quench:validate-petition`, `appraise:review-petition`, `human-appraise:human-review`)
 - `iteration` — the current iteration number (increments each time forge runs within a cycle)
 - `comment` — brief description of what happened
 
 ### Rules
 
-- Append-only — never edit or delete entries
-- Every stage skill appends an entry when it completes
-- The sort tool reads this to determine what has happened in the current foundry cycle
-- Iteration is derived from counting forge entries for the current foundry cycle
+- Append-only — never edit or delete entries.
+- Every stage produces an entry when it completes.
+- Sort reads this to determine what has happened in the current cycle.
+- Iteration is derived from counting forge entries for the current cycle.
 
 ### Who writes
 
-Every stage skill (forge, quench, appraise, hitl) appends an entry when it finishes via the `foundry_history_append` tool.
+History entries are written by `foundry_orchestrate` after each stage closes (via its internal `foundry_history_append` — the tool is not registered publicly). Sub-agents never append history directly.
 
 ## Example
 
@@ -166,6 +177,9 @@ 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
 ---
 
 # Goal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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/skills/add-appraiser/SKILL.md

@@ -10,9 +10,15 @@ You help the user create a new appraiser personality. You ensure it's genuinely
 
 ## 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:
+Before running this skill, verify both of the following:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+1. 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.
+
+2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+
+   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
 
 ## Protocol
 

package/skills/add-artefact-type/SKILL.md

@@ -10,9 +10,15 @@ You help the user create a new artefact type. You ensure it doesn't conflict wit
 
 ## 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:
+Before running this skill, verify both of the following:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+1. 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.
+
+2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+
+   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
 
 ## Protocol
 

package/skills/add-cycle/SKILL.md

@@ -10,9 +10,15 @@ You help the user create a new foundry cycle and add it to an existing foundry f
 
 ## 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:
+Before running this skill, verify both of the following:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+1. 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.
+
+2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+
+   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
 
 ## Protocol
 

package/skills/add-flow/SKILL.md

@@ -10,9 +10,15 @@ You help the user create a new foundry flow. A foundry flow is a set of foundry
 
 ## 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:
+Before running this skill, verify both of the following:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+1. 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.
+
+2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+
+   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
 
 ## Protocol
 

package/skills/add-law/SKILL.md

@@ -10,9 +10,15 @@ You help the user create a new law. You ensure it's well-scoped, doesn't conflic
 
 ## 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:
+Before running this skill, verify both of the following:
 
-> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+1. 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.
+
+2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+
+   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
 
 ## Protocol