@really-knows-ai/foundry 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.3.2 — 2026-04-21
+
+### Changed
+
+- Config-modifying skills (`add-flow`, `add-cycle`, `add-law`, `add-appraiser`, `add-artefact-type`) now refuse to run on a work branch. They require the current branch to not start with `work/`, directing the user to complete or discard the in-flight flow before changing foundry configuration. Structural changes belong on the base branch, not alongside transient flow state.
+
+### Removed
+
+- Historical planning docs (`docs/plans/`, `docs/specs/`, `docs/superpowers/`) and `HARDEN.md`. All described features that shipped in v2.2.0–v2.3.1; git history preserves the full record.
+
 ## 2.3.1 — 2026-04-20
 
 ### Changed

package/README.md

@@ -1,12 +1,51 @@
 # Foundry
 
-A skill-driven framework for governed artefact generation and evaluation using AI coding tools. Install it as an npm package and define your own artefact types, laws, and flows — Foundry handles the forge-quench-appraise pipeline.
+> A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.
+
+[![npm version](https://img.shields.io/npm/v/@really-knows-ai/foundry.svg)](https://www.npmjs.com/package/@really-knows-ai/foundry)
+[![license](https://img.shields.io/npm/l/@really-knows-ai/foundry.svg)](LICENSE)
+
+---
+
+## Table of contents
+
+- [Why Foundry?](#why-foundry)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Core concepts](#core-concepts)
+- [The pipeline in depth](#the-pipeline-in-depth)
+- [Feedback lifecycle](#feedback-lifecycle)
+- [Enforcement model](#enforcement-model)
+- [Multi-model routing](#multi-model-routing)
+- [Skills](#skills)
+- [Custom tools](#custom-tools)
+- [Project layout](#project-layout)
+- [Design decisions](#design-decisions)
+- [Further reading](#further-reading)
+- [License](#license)
+
+---
+
+## Why Foundry?
+
+LLMs are excellent at producing artefacts — code, specs, docs, tests — but they are erratic about *governing* that production. They skip checks, silently ignore feedback, drift from constraints, and forget what stage they're in. Foundry is an opinionated framework that separates **creative work** (handled by LLMs via skills) from **process work** (handled by deterministic tools):
+
+- **The pipeline is code, not prose.** Routing, state transitions, commit discipline, and write invariants live inside tested plugin tools. LLMs can't rationalise their way past them.
+- **Every artefact is governed by laws.** Global and per-type pass/fail criteria are evaluated by a panel of independent appraisers before anything is considered done.
+- **Nothing is silent.** Feedback has a full lifecycle (open → actioned/wont-fix → approved/rejected). Wont-fix requires appraiser approval. Validation is non-negotiable.
+- **Writes are enforced.** Each stage is allowed to modify a specific, narrow set of files. Violations halt the cycle.
+- **Humans can step in.** Human-in-the-loop gates can run every iteration or only when LLM appraisers deadlock.
+
+---
 
 ## Compatibility
 
-- **OpenCode** — full support, multi-model routing via file-based agents
+- **OpenCode** — full support. Multi-model routing via file-based `foundry-*` agents. This is the primary target.
+- **Other skill-aware AI tools** — the skills and tools are portable. Multi-model stage routing is OpenCode-specific today because it relies on `.opencode/agents/` files generated by `refresh-agents`.
 
-Multi-model support enables model diversity across pipeline stages. Foundry agents are defined as `.opencode/agents/foundry-*.md` files, generated by the `refresh-agents` skill (also run during `init-foundry`). Cycle definitions specify which model each stage uses. Tools limited to a single model lose model-diversity but still get personality-based diversity.
+---
 
 ## Installation
 
@@ -15,211 +54,339 @@ Add `@really-knows-ai/foundry` to your OpenCode config:
 ```json
 // opencode.json
 {
-  "packages": {
-    "@really-knows-ai/foundry": "latest"
-  }
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
 }
 ```
 
+---
+
 ## Quick start
 
-1. **Install** the package as shown above
-2. **Initialize** — use the `init-foundry` skill to scaffold a `foundry/` directory in your project
-3. **Define artefact types** — use `add-artefact-type` to create types with file patterns, descriptions, and optional validation
-4. **Add laws** — use `add-law` to define subjective pass/fail criteria (global or per-type)
-5. **Add appraisers** — use `add-appraiser` to create appraiser personalities
-6. **Define cycles** — use `add-cycle` to wire artefact types into forge/quench/appraise loops
-7. **Define flows** — use `add-flow` to sequence cycles into end-to-end pipelines
-8. **Run** — use the `flow` skill to execute a flow
+1. **Install** the package (above).
+2. **Initialize** — run the `init-foundry` skill to scaffold a `foundry/` directory and generate `foundry-*` agent files.
+3. **Define artefact types** — `add-artefact-type` walks you through identity, file patterns, output directory, laws, and optional CLI validation.
+4. **Add laws** — `add-law` creates subjective pass/fail criteria, globally or per-type.
+5. **Add appraisers** — `add-appraiser` creates appraiser personalities with conflict detection.
+6. **Define cycles** — `add-cycle` wires artefact types into a forge/quench/appraise loop with targets and input contracts.
+7. **Define a flow** — `add-flow` groups cycles and declares entry points.
+8. **Run** — invoke the `flow` skill with your goal. It creates a work branch, picks the right cycle, and hands off to `orchestrate`.
+
+---
 
 ## How it works
 
 ```
-Foundry Flow
- └─ Cycle 1 (e.g., ideation)
- │   ├─ Forge → produce the artefact
- │   ├─ Quench → deterministic CLI checks (if defined)
- │   ├─ Appraise → subjective evaluation by multiple appraisers
- │   └─ ↺ iterate until all feedback is resolved
- └─ Cycle 2 (e.g., creation)
-     ├─ reads output from Cycle 1 (read-only)
-     ├─ Forge → produce the artefact
-     ├─ Quench → deterministic CLI checks
-     ├─ Appraise → subjective evaluation
-     └─ ↺ iterate until all feedback is resolved
+                     ┌─────────────────────────────┐
+                     │  Flow  (entry points + set) │
+                     └──────────────┬──────────────┘
+                                    │ starting cycle picked
+                                    ▼
+ ┌────────────────────────────────────────────────────────────────┐
+ │  Cycle  (outputs exactly one artefact type)                    │
+ │                                                                │
+ │    ┌─────────┐    ┌─────────┐    ┌─────────────┐               │
+ │    │  forge  │ → │ quench  │ → │  appraise   │  ──┐           │
+ │    └─────────┘    └─────────┘    └─────────────┘    │  loop    │
+ │          ▲                                           │  until  │
+ │          └───── unresolved feedback ─────────────────┘  clean  │
+ │                                                                │
+ │    [ optional: human-appraise  — every iter or on deadlock ]  │
+ └──────────────┬─────────────────────────────────────────────────┘
+                │ targets (may branch)
+                ▼
+          next cycle  →  …  →  done
 ```
 
-A **foundry flow** runs one or more **foundry cycles** in sequence. Each cycle produces a single artefact type by looping through forge → quench → appraise until the artefact passes all criteria. The output of one cycle becomes read-only input for the next.
+- A **flow** defines the set of cycles and their entry points.
+- A **cycle** produces exactly one artefact type and declares its own `targets` — Foundry follows a dependency graph, not a linear list.
+- Each cycle loops through **forge → quench → appraise** until there is no unresolved feedback, or an iteration limit is hit.
+- All inter-stage communication goes through **WORK.md** on a dedicated work branch; every stage ends with a micro-commit.
 
-All state lives in `WORK.md` on a dedicated work branch. Every stage micro-commits, and file modification enforcement ensures stages only touch what they're allowed to.
+---
 
-## Custom tools
+## Core concepts
 
-The Foundry plugin exposes 25 custom tools that handle all deterministic pipeline operations. Skills call these tools instead of manipulating files directly — this eliminates LLM interpretation of file formats and ensures consistent state management.
+### Flow
 
-| Category | Tools |
-|----------|-------|
-| **Workfile** | `foundry_workfile_create`, `foundry_workfile_get`, `foundry_workfile_set`, `foundry_workfile_delete` |
-| **Artefacts** | `foundry_artefacts_add`, `foundry_artefacts_list`, `foundry_artefacts_set_status` |
-| **Feedback** | `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, `foundry_feedback_resolve`, `foundry_feedback_list` |
-| **History** | `foundry_history_append`, `foundry_history_list` |
-| **Sort** | `foundry_sort` |
-| **Config** | `foundry_config_cycle`, `foundry_config_artefact_type`, `foundry_config_laws`, `foundry_config_validation`, `foundry_config_appraisers`, `foundry_config_flow` |
-| **Validation** | `foundry_validate_run`, `foundry_appraisers_select` |
-| **Git** | `foundry_git_branch`, `foundry_git_commit` |
+A flow lives in `foundry/flows/`. It declares:
 
-Tools are backed by shared library modules in `scripts/lib/` that use injectable I/O for testability. The sort routing engine (`scripts/sort.js`) exports `runSort()` for the sort tool.
+- `starting-cycles` — hints about where the flow can be entered.
+- The set of cycles it contains (routing between them is owned by cycles, not by the flow).
 
-## Core concepts
+Starting a flow creates a work branch and a fresh `WORK.md`.
 
-### Foundry Flows
+### Cycle
 
-Defined in `foundry/flows/`. A flow lists cycles to execute in order. Starting a flow creates a work branch and a fresh `WORK.md`.
+A cycle lives in `foundry/cycles/`. It declares:
 
-### Foundry Cycles
+- `output` — the artefact type the cycle produces (read-write).
+- `inputs` — a contract (`any-of` or `all-of`) over artefact types from other cycles. Inputs are discovered on disk by filesystem scan against each input type's file-patterns; they are read-only.
+- `targets` — which cycle(s) may run next after this one completes.
+- `human-appraise` / `deadlock-appraise` / `deadlock-iterations` — human-in-the-loop configuration.
+- `models` — optional per-stage model overrides for multi-model diversity.
 
-Defined in `foundry/cycles/`. A cycle specifies:
-- `output` — the artefact type it produces (read-write)
-- `inputs` — artefact types from previous cycles (read-only)
+### Stage
 
-### Stages
+A single step within a cycle. Stages are identified as `base:alias` (e.g. `forge:write-haiku`, `quench:check-syllables`). The base is one of:
 
-The three steps within a cycle:
-- **Forge** — produce or revise the artefact
-- **Quench** — run deterministic CLI checks (skipped if artefact type has no `validation.md`)
-- **Appraise** — subjective evaluation by multiple independent appraisers
+- **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 independent appraiser sub-agents.
+- **human-appraise** — human quality gate, either every iteration or only on deadlock.
 
-### Artefact types
+### Artefact type
 
-Defined in `foundry/artefacts/<type>/`. Each type has:
-- `definition.md` — id, name, file patterns, output directory, appraiser config, prose description
-- `laws.md` (optional) — type-specific subjective criteria
-- `validation.md` (optional) — CLI commands with `{file}` placeholder; non-zero exit = failure
+Defined in `foundry/artefacts/<type>/`:
+
+- `definition.md` — id, name, file patterns, output directory, appraiser configuration, prose description.
+- `laws.md` *(optional)* — type-specific subjective criteria.
+- `validation.md` *(optional)* — CLI commands with a `{file}` placeholder; non-zero exit = failure.
 
 ### Laws
 
-Subjective pass/fail criteria. Two scopes:
-- `foundry/laws/*.md` — global laws, all files concatenated, apply to everything
-- `foundry/artefacts/<type>/laws.md` — type-specific laws
+Subjective pass/fail criteria evaluated by appraisers.
+
+- `foundry/laws/*.md` — global laws (all files concatenated, apply everywhere).
+- `foundry/artefacts/<type>/laws.md` — type-specific laws.
 
-Each law is a `## heading` (the identifier, used in feedback tags as `#law:<id>`) with a description, passing criteria, and failing criteria.
+Each law is a `## heading` (its identifier, referenced in feedback as `#law:<id>`) with a description, passing criteria, and failing criteria.
 
 ### Appraisers
 
-Defined in `foundry/appraisers/`. Each appraiser has a personality and an optional model override. Appraisers are assigned to artefact types via the `appraisers` section in the type's `definition.md`:
+Defined in `foundry/appraisers/`. Each appraiser is a named personality with an optional `model` override. Artefact types pick which appraisers may evaluate them:
 
 ```yaml
 appraisers:
-  count: 3                          # how many appraisers (default: 3)
-  allowed: [pedantic, pragmatic]    # which personalities (default: all available)
+  count: 3                       # how many appraisers (default: 3)
+  allowed: [pedantic, pragmatic] # which personalities (default: all)
 ```
 
-Appraisers are distributed evenly across available personalities for maximum diversity. If you request 6 appraisers with 3 personalities, you get 2 of each. Model diversity is configured at the cycle level (per-stage) and optionally per-appraiser — see [concepts](docs/concepts.md).
+Appraisers are distributed evenly across the allowed set for maximum diversity.
 
 ### WORK.md
 
-Transient shared state on the work branch. Tracks:
-- Current position (flow, cycle, stage) in frontmatter
-- Goal description
-- Artefact registry (what exists, its status)
-- All feedback with full lifecycle
+Transient shared state on the work branch. Created when the flow starts, deleted before the branch is squash-merged. It contains:
+
+- **Frontmatter** — current position (`flow`, `cycle`, stage list, max iterations, model map, human-appraise config).
+- **Goal** — the prose request that kicked off the flow.
+- **Artefacts** — a table of every file produced by the flow and its status (`draft`, `done`, `blocked`).
+- **Feedback** — grouped by artefact file, every feedback item with its full lifecycle.
+
+A sibling file `WORK.history.yaml` is an append-only log of every stage execution. See [docs/work-spec.md](docs/work-spec.md).
+
+---
+
+## The pipeline in depth
+
+### Stages run inside a token-gated lifecycle
+
+Every dispatched stage (forge, quench, appraise, human-appraise) runs under a single-use HMAC token:
+
+1. The `orchestrate` tool mints a token and hands it to the sub-agent in the dispatch prompt.
+2. The sub-agent's **first** call must be `foundry_stage_begin({stage, cycle, token})`. The token is redeemed; mutation tools now check that the active stage matches.
+3. The sub-agent does its work (reads WORK.md, writes artefact files / feedback, etc.).
+4. The sub-agent's **last** call is `foundry_stage_end({summary})`.
+5. The orchestrator then calls `foundry_stage_finalize`, which:
+   - Scans the git diff against the stage's allowed file-patterns.
+   - Registers any new files matching the output artefact type as `draft` artefacts.
+   - Returns `{error: 'unexpected_files'}` if the stage wrote anywhere it shouldn't have.
+6. The cycle is committed (`foundry_git_commit` internally) and routing advances.
+
+Per-stage write rules:
+
+| Stage | May write |
+|-------|-----------|
+| `forge` | Files matching the output artefact type's `file-patterns`, plus `WORK.md` / `WORK.history.yaml` |
+| `quench` | `WORK.md` / `WORK.history.yaml` only (feedback) |
+| `appraise` | `WORK.md` / `WORK.history.yaml` only (feedback) |
+| `human-appraise` | `WORK.md` / `WORK.history.yaml` only (feedback) |
+
+Input artefacts are read-only. Files outside any artefact type's patterns are read-only. Violations hard-stop the cycle.
+
+### Deterministic orchestration
+
+The `orchestrate` skill is thin — a 3-line loop:
+
+```text
+call foundry_orchestrate({lastResult})
+switch on action:
+  dispatch        → task tool (subagent) → report back
+  human_appraise  → run human-appraise inline → report back
+  done / blocked / violation → terminate the loop
+```
+
+`foundry_orchestrate` owns sort routing, history, commits, finalize, deadlock detection, and violation handling. Because the protocol lives in a plugin tool, the LLM can't skip steps, reorder them, or silently drop a commit.
+
+---
 
-### Feedback lifecycle
+## Feedback lifecycle
+
+Feedback is markdown checklists under each artefact in WORK.md, tagged to indicate source.
 
 ```
-open         - [ ] issue #tag                                    → needs generator action
-actioned     - [x] issue #tag                                    → needs approval
-wont-fix     - [~] issue #tag | wont-fix: <reason>               → needs approval
-approved     - [x] issue #tag | approved                         → resolved
-approved     - [~] issue #tag | wont-fix: <reason> | approved    → resolved
-rejected     - [x] issue #tag | rejected: <reason>               → re-opened
-rejected     - [~] issue #tag | wont-fix: <reason> | rejected    → re-opened
+- [ ] issue #tag                                    → open          — needs forge action
+- [x] issue #tag                                    → actioned      — needs appraise approval
+- [~] issue #tag | wont-fix: <reason>               → wont-fix      — needs appraise approval
+- [x] issue #tag | approved                         → resolved
+- [~] issue #tag | wont-fix: <reason> | approved    → resolved
+- [x] issue #tag | rejected: <reason>               → re-opened
+- [~] issue #tag | wont-fix: <reason> | rejected    → re-opened
 ```
 
-Validation feedback (`#validation`) cannot be wont-fixed — deterministic rules are not negotiable.
+Tags:
+
+| Tag | Source | Notes |
+|-----|--------|-------|
+| `#validation` | quench (CLI command failed) | Cannot be wont-fixed. Deterministic rules are not negotiable. |
+| `#law:<id>` | appraise (subjective law) | May be wont-fixed with justification; an appraiser must approve. |
+| `#human` | human-appraise | Takes absolute priority. Forge MUST address it — cannot wont-fix. |
+
+Feedback is append-only: items are never deleted, only resolved. Re-opened items show their full history.
+
+### Deadlock handling
+
+If forge and appraise ping-pong on the same items for `deadlock-iterations` (default 5) iterations, and the cycle has `deadlock-appraise: true` (default), the router inserts a `human-appraise` stage. If `deadlock-appraise: false`, the cycle is marked `blocked` and control returns to the human.
+
+---
+
+## Enforcement model
+
+Foundry is designed around "trust the tool, not the LLM". The following guarantees are enforced in plugin code, not prose:
+
+- **Stage-locked mutations.** `foundry_feedback_*`, `foundry_artefacts_*`, and `foundry_workfile_*` tools require the caller's role to match the active stage. A forge sub-agent cannot add feedback; a quench sub-agent cannot register artefacts.
+- **Single-use tokens.** `foundry_stage_begin` verifies an HMAC token minted at dispatch time. Replays, forgery, and cross-stage reuse all fail closed. Keys live in `.foundry/.secret` (mode 0600, gitignored, one per worktree).
+- **Commit-per-stage contract.** `foundry_orchestrate` refuses to proceed if there are uncommitted changes to `WORK.md`, `WORK.history.yaml`, or anything under `.foundry/` at the start of a sort call and history is non-empty.
+- **Write invariants.** `foundry_stage_finalize` scans the git diff and rejects stray writes with `{error: 'unexpected_files'}`.
+- **Feedback state machine.** Only legal transitions are accepted: `approved` is terminal; quench cannot approve/reject a `wont-fix`; validation cannot be wont-fixed.
+- **Artefact-type glob uniqueness.** `add-artefact-type` refuses to create a type whose file patterns overlap with an existing type; the enforcer can't determine file ownership otherwise.
+
+---
 
-### File modification enforcement
+## Multi-model routing
 
-Every stage micro-commits. The cycle checks the git diff:
-- After forge: only output artefact file patterns + WORK.md + WORK.history.yaml (input artefacts are read-only — violation if touched)
-- After quench/appraise: only WORK.md + WORK.history.yaml
-- Violations are hard stops
+Different stages can run on different models for genuine cognitive diversity (mitigating shared blind spots):
 
-> **Merge hygiene:** WORK.md and WORK.history.yaml are ephemeral working files. Delete them before squash-merging the branch back into main.
+- Cycle definitions can declare a `models` map, e.g. `models: { forge: anthropic/claude-opus-4.7, appraise: openai/gpt-5 }`.
+- Individual appraisers can override the cycle-level appraise model via a `model` field in their personality definition.
+- `refresh-agents` generates a `foundry-<provider>-<model>.md` agent file in `.opencode/agents/` for every model available in the session. `orchestrate` picks the matching agent when dispatching.
+
+Resolution order for a given stage: **appraiser `model`** → **cycle `models.<stage>`** → **session default**.
+
+Run `list-agents` to see what's available.
+
+---
 
 ## Skills
 
-Everything is a skill. Skills are either atomic (do one thing) or composite (orchestrate other skills).
+Foundry is a collection of skills. Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
 
-### Pipeline skills
+### Pipeline
 
 | Skill | Type | Purpose |
 |-------|------|---------|
-| `forge` | atomic | Produce or revise an artefact |
-| `quench` | atomic | Run deterministic CLI checks |
-| `appraise` | atomic | Dispatch multiple appraisers, consolidate feedback |
-| `cycle` | composite | forge → quench → appraise → iterate |
-| `flow` | composite | Orchestrate cycles on a work branch |
+| `flow` | composite | Entry point. Picks a starting cycle, creates the work branch, invokes `orchestrate`, follows `targets` between cycles. |
+| `orchestrate` | atomic | Thin driver around `foundry_orchestrate`. Dispatches sub-agents, runs human-appraise inline, reports terminal states. |
+| `forge` | atomic | Produce or revise the artefact. Discovers inputs by filesystem scan. |
+| `quench` | atomic | Run the artefact type's CLI validation commands; write `#validation` feedback. |
+| `appraise` | atomic | Dispatch the selected appraiser personalities as parallel sub-agents; consolidate `#law:<id>` feedback (union + dedup). |
+| `human-appraise` | atomic | Human quality gate. Presents the artefact, collects `#human` feedback. |
 
-### Helper skills
+### Authoring
 
 | Skill | Purpose |
 |-------|---------|
-| `init-foundry` | Scaffold the `foundry/` directory in your project |
-| `add-artefact-type` | Create a new artefact type with conflict and glob-overlap checks |
-| `add-law` | Create a new law with conflict detection |
-| `add-appraiser` | Create a new appraiser personality with semantic overlap checks |
-| `add-cycle` | Create a new cycle within a flow with dependency validation |
-| `add-flow` | Create a new flow definition |
+| `init-foundry` | Scaffold the `foundry/` directory and generate agent files. |
+| `add-artefact-type` | Create a new artefact type, with conflict and glob-overlap checks. |
+| `add-law` | Create a new law with conflict detection. |
+| `add-appraiser` | Create an appraiser personality with semantic-overlap checks. |
+| `add-cycle` | Create a cycle, validate its targets and input contract against the flow. |
+| `add-flow` | Create a flow definition with cycle-graph reachability checks. |
 
-### Utility skills
+### Utility
 
 | Skill | Purpose |
 |-------|---------|
-| `sort` | Deterministic cycle router — determines and dispatches the next stage |
-| `hitl` | Human-in-the-loop intervention points |
+| `list-agents` | List available `foundry-*` sub-agents (for multi-model routing). |
+| `refresh-agents` | Regenerate `foundry-*` agent files from the currently available models. |
+| `upgrade-foundry` | Analyse and migrate `foundry/` config to the current version. |
 
-All helper skills are interactive — they walk you through the process, check for conflicts, and confirm before writing files.
+All authoring skills are interactive and conflict-aware — they explain what they're about to write and ask before writing.
 
-## Package structure
+---
+
+## Custom tools
+
+The plugin registers **24 custom tools**. Skills call these rather than manipulating files directly, which keeps format-parsing and state transitions out of LLM hands.
+
+| Category | Tools |
+|----------|-------|
+| **Orchestration** | `foundry_orchestrate` |
+| **Stage lifecycle** | `foundry_stage_begin`, `foundry_stage_end` |
+| **Workfile** | `foundry_workfile_create`, `foundry_workfile_get`, `foundry_workfile_delete` |
+| **Artefacts** | `foundry_artefacts_set_status`, `foundry_artefacts_list` |
+| **Feedback** | `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, `foundry_feedback_resolve`, `foundry_feedback_list` |
+| **History** | `foundry_history_list` |
+| **Config** | `foundry_config_cycle`, `foundry_config_artefact_type`, `foundry_config_laws`, `foundry_config_validation`, `foundry_config_appraisers`, `foundry_config_flow` |
+| **Validation** | `foundry_validate_run`, `foundry_appraisers_select` |
+| **Git** | `foundry_git_branch`, `foundry_git_finish` |
+
+A handful of internal tools (`foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_set`, `foundry_workfile_configure_from_cycle`) are intentionally *not* registered — they exist only inside `foundry_orchestrate` so they cannot be called out of band.
+
+Tools are backed by shared modules in `scripts/lib/` with injectable I/O for testability (see `tests/`).
+
+---
+
+## Project layout
+
+### Package (this repo)
 
 ```
 @really-knows-ai/foundry
 ├── .opencode/
 │   └── plugins/
-│       └── foundry.js          # OpenCode plugin (skills + 25 custom tools)
-├── skills/                     # skill definitions (the pipeline)
+│       └── foundry.js          # plugin: skills + 24 custom tools
+├── skills/                     # skill definitions
+│   ├── flow/                   # pipeline
+│   ├── orchestrate/
 │   ├── forge/
 │   ├── quench/
 │   ├── appraise/
-│   ├── cycle/
-│   ├── flow/
-│   ├── init-foundry/
+│   ├── human-appraise/
+│   ├── init-foundry/           # authoring
 │   ├── add-artefact-type/
 │   ├── add-law/
 │   ├── add-appraiser/
 │   ├── add-cycle/
 │   ├── add-flow/
-│   ├── sort/
-│   └── hitl/
-├── scripts/                    # shared library and routing engine
-│   ├── lib/
-│   │   ├── workfile.js         # WORK.md frontmatter parsing/writing
-│   │   ├── artefacts.js        # artefacts table operations
-│   │   ├── history.js          # WORK.history.yaml operations
-│   │   ├── feedback.js         # feedback lifecycle operations
+│   ├── list-agents/            # utility
+│   ├── refresh-agents/
+│   └── upgrade-foundry/
+├── scripts/
+│   ├── lib/                    # shared libraries (injectable I/O)
+│   │   ├── workfile.js         # WORK.md frontmatter
+│   │   ├── artefacts.js        # artefact table ops
+│   │   ├── history.js          # WORK.history.yaml ops
+│   │   ├── feedback.js         # feedback lifecycle
+│   │   ├── feedback-transitions.js
+│   │   ├── finalize.js         # stage_finalize implementation
+│   │   ├── stage-guard.js      # stage-lock preconditions
+│   │   ├── token.js            # HMAC token mint/verify
+│   │   ├── secret.js           # .foundry/.secret handling
+│   │   ├── pending.js          # active-stage state
+│   │   ├── state.js            # .foundry state dir
 │   │   ├── config.js           # foundry/ config readers
-│   │   └── tags.js             # tag extraction
-│   └── sort.js                 # deterministic routing engine (exports runSort)
-├── tests/                      # test suite (node:test)
-├── docs/                       # concept docs and specs
-├── package.json
+│   │   ├── tags.js             # feedback tag extraction
+│   │   └── slug.js
+│   ├── orchestrate.js          # orchestration loop (exports runOrchestrate)
+│   └── sort.js                 # routing engine (exports runSort)
+├── tests/                      # node:test suite
+├── docs/                       # concepts, getting-started, work-spec
+├── CHANGELOG.md
 └── README.md
 ```
 
-## User project structure
-
-After running `init-foundry`, your project gets a `foundry/` directory:
+### User project (after `init-foundry`)
 
 ```
 your-project/
@@ -229,47 +396,71 @@ your-project/
 │   ├── artefacts/              # artefact type definitions
 │   │   └── <type>/
 │   │       ├── definition.md
-│   │       ├── laws.md         # (optional) type-specific laws
-│   │       └── validation.md   # (optional) CLI checks
+│   │       ├── laws.md         # optional
+│   │       └── validation.md   # optional
 │   ├── laws/                   # global laws
 │   └── appraisers/             # appraiser personalities
+├── .foundry/                   # runtime state (gitignored)
+│   └── .secret                 # per-worktree HMAC key (mode 0600)
+├── .opencode/
+│   └── agents/
+│       └── foundry-*.md        # generated by refresh-agents
 ├── opencode.json
 └── ...
 ```
 
+During a flow, a work branch also contains `WORK.md` and `WORK.history.yaml` at the repo root. Both are ephemeral — delete them before squash-merging.
+
+---
+
 ## Design decisions
 
 ### Everything is markdown
 
-Flow definitions, cycle definitions, artefact types, laws, appraiser personalities, skills — all markdown. Readable by humans, consumable by LLMs, versionable in git. No config files, no databases, no custom formats.
+Flows, cycles, artefact types, laws, appraiser personalities, skills — all markdown with YAML frontmatter. Readable by humans, consumable by LLMs, diff-able in git. No bespoke formats, no databases.
 
 ### Skills are the pipeline, tools are the machinery
 
-Composition happens via skills referencing other skills. The `flow` skill reads a flow definition and invokes the `cycle` skill. The `cycle` skill invokes `forge`, `quench`, and `appraise`. Skills handle creative and subjective work; deterministic operations (parsing, routing, state updates) are handled by custom tools backed by shared library code.
+Composition happens at the skill layer. `flow` reads a definition and invokes `orchestrate`. `orchestrate` calls `foundry_orchestrate` in a loop. The hard guarantees — routing, commits, state transitions, enforcement — live inside the plugin's custom tools and the libraries under `scripts/lib/`. Skills handle creative and subjective work; tools handle everything else.
 
 ### WORK.md as shared state
 
-All communication between stages goes through WORK.md. No stage passes output directly to another — all reads and writes go through the `foundry_workfile_*`, `foundry_artefacts_*`, and `foundry_feedback_*` tools. This gives a complete audit trail, makes the process resumable, and means any stage can be re-run independently.
+All inter-stage communication goes through WORK.md via the `foundry_workfile_*`, `foundry_artefacts_*`, `foundry_feedback_*`, and `foundry_history_*` tools. No stage passes output directly to another. This gives a complete audit trail, makes flows resumable after a crash, and lets any stage be re-run independently.
+
+### Cycles own their routing
+
+A flow declares starting points; individual cycles declare `targets` and input contracts. The flow skill walks the resulting graph. This keeps cycles composable across flows and prevents the flow file from becoming a procedural monolith.
 
-### Feedback as checklist items
+### Feedback as checklists
 
-Feedback uses markdown checklists with `#validation` or `#law:<id>` tags. Human-readable, trivially parseable by an LLM, with lifecycle states expressed inline.
+Markdown checkboxes with `#validation`, `#law:<id>`, or `#human` tags. Human-readable, trivially parseable, lifecycle encoded inline. Feedback is append-only; history is part of the artefact's story.
 
-### Wont-fix requires appraiser approval
+### Wont-fix requires approval
 
-The generator can decline subjective feedback with a justification, but an appraiser must approve or reject that decision. This prevents silently ignoring feedback while allowing legitimate pushback.
+A forge sub-agent can decline subjective feedback with a justification, but an appraiser must approve or reject that decision on the next iteration. Validation and human feedback cannot be wont-fixed.
 
-### Multi-model stage routing
+### Multi-model diversity
 
-Cycle definitions specify which model each stage uses via a `models` map. The `refresh-agents` skill generates `foundry-*` agent files in `.opencode/agents/` from available models. Individual appraisers can override the cycle-level model. Resolution order: appraiser `model` → cycle `models.<stage>` → session default. Multiple personalities catch different issues. Consolidation is union with dedup — one appraiser flagging an issue is enough.
+Cycle definitions specify per-stage models; individual appraisers may override. Different models catch different issues; consolidation is a union. One appraiser flagging an issue is enough to raise it.
 
 ### Input artefacts are read-only
 
-When a cycle reads from a previous cycle's output, those files cannot be modified. Enforced via git diff after every micro-commit. This prevents downstream cycles from corrupting upstream work.
+When a cycle reads from another cycle's output, those files cannot be modified. Enforced via `stage_finalize` and `sort`'s diff check. Downstream cycles cannot corrupt upstream work.
 
 ### Glob patterns must not overlap
 
-Two artefact types cannot have file patterns that match the same files. This is checked when creating new types and is a hard block — file modification enforcement can't determine ownership if patterns overlap.
+Two artefact types cannot have file patterns that match the same files. Hard-blocked at creation time; the file-ownership rule doesn't have a meaningful answer otherwise.
+
+---
+
+## Further reading
+
+- [docs/concepts.md](docs/concepts.md) — every concept defined concisely.
+- [docs/getting-started.md](docs/getting-started.md) — end-to-end walkthrough.
+- [docs/work-spec.md](docs/work-spec.md) — the full WORK.md + WORK.history.yaml spec.
+- [CHANGELOG.md](CHANGELOG.md) — version history and migration notes.
+
+---
 
 ## License
 

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.1",
+  "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