@really-knows-ai/foundry 2.3.2 → 3.0.0

package/README.md

@@ -1,467 +1,278 @@
 # Foundry
 
-> 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.
+> Engineered confidence for AI-generated work. Define what good looks like.
 
 [![npm version](https://img.shields.io/npm/v/@really-knows-ai/foundry.svg)](https://www.npmjs.com/package/@really-knows-ai/foundry)
+[![Tests](https://github.com/really-knows-ai/foundry/actions/workflows/test.yml/badge.svg)](https://github.com/really-knows-ai/foundry/actions/workflows/test.yml)
 [![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)
+## Engineering confidence
 
----
+### Confidence is engineered
 
-## Why Foundry?
+Generation is cheap; trust is expensive. An agent can produce output quickly, skip
+validation, or lose feedback between iterations. The work arrives fast, but the
+evidence is incomplete and trust is fragile. Nobody can see the path from prompt to
+finish. Nobody knows how many times the agent tried, what it fixed, or why it
+stopped.
 
-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):
+Foundry is the system around the prompt: explicit standards, repeatable checks, and
+recorded sign-off applied to every artefact your AI produces. It transforms "ask an
+agent and hope" into a staged system where the checks are structural and mandatory.
+If an artefact should be validated, it is validated. If feedback must be resolved,
+that state is recorded. If a stage writes outside its lane, the cycle stops. The
+framework is deterministic; the LLM is not. Your laws are.
 
-- **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.
+Variability helps where creativity matters; control enforces discipline where
+reliability does. You choose what gates each stage passes through, what laws your
+artefacts must satisfy, and which models you trust for each decision. Foundry runs
+the loop and records every step in git, so the path from draft to approved artefact
+is auditable, repeatable, and defensible to auditors and stakeholders. You can show
+exactly how the output was made. Confidence is engineered; it is not hoped for.
 
----
+### The operating model: assay, then forge → quench → appraise
 
-## Compatibility
+A codebase-aware cycle can begin with **assay**: a deterministic pre-forge stage
+that runs project-authored extractor scripts, parses the strict JSONL facts they
+emit, and writes typed facts into flow memory. In the foundry metaphor, an assay
+establishes composition before work begins. In Foundry, assay gives forge a
+measured map of the project before it creates an artefact. Cycles without memory
+configuration skip this stage.
 
-- **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`.
+After assay, one draft enters a short loop and leaves only when it passes quality
+gates. Each loop has four distinct roles that turn a candidate into a verified output:
 
----
+- **Forge** produces or revises the artefact. The stage that creates and reshapes
+  work, responding to feedback from appraisers or building on prior drafts.
 
-## Installation
+- **Quench** runs deterministic checks that harden or reject the work. Validation is
+  fast and non-negotiable, catching errors before they reach appraisers.
 
-Add `@really-knows-ai/foundry` to your OpenCode config:
+- **Appraise** judges quality against written laws. Independent evaluators inspect
+  whether the work meets the subjective standards you define.
 
-```json
-// opencode.json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@really-knows-ai/foundry"]
-}
-```
+- **Human-appraise** provides direct judgement when the stakes require it or the loop
+  deadlocks. Offers human oversight at critical decision points.
 
----
+Every stage commits separately, so every step leaves a record. Every decision is
+timestamped. A single loop produces an **output** — a verified draft. A flow
+composes one or more such loops to produce an **outcome** — the final artefact that
+reaches your codebase or customers.
 
-## Quick start
+### What you describe, what Foundry enforces
 
-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`.
+You write the laws — the criteria that define acceptable. You describe the artefact
+types you want produced and what files they generate. You choose which stages each
+cycle passes through and what models to use at each step. You control the operating
+model entirely. Your configuration is law.
 
----
-
-## How it works
-
-```
-                     ┌─────────────────────────────┐
-                     │  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 **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.
+Foundry runs the loop, gates writes per stage so only the right mutation happens at
+the right time, records every decision in git, and stops when there is nothing left
+to fix. Each stage holds a token that authorises its mutations. Stages cannot write
+outside their assigned lane. Feedback state moves through a state machine that
+prevents invalid transitions. The framework owns the process and enforces the rules;
+the LLM performs the creative and evaluative work inside each stage. You define the
+machine; Foundry runs it. Confidence is the difference.
 
 ---
 
-## Core concepts
-
-### Flow
-
-A flow lives in `foundry/flows/`. It declares:
-
-- `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).
-
-Starting a flow creates a work branch and a fresh `WORK.md`.
-
-### Cycle
-
-A cycle lives in `foundry/cycles/`. It declares:
-
-- `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.
-
-### Stage
-
-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:
-
-- **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 type
-
-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.
+## Compatibility
 
-### Laws
+Foundry works primarily with OpenCode. The skills and tools are portable to other
+skill-aware AI systems. Multi-model stage routing is OpenCode-specific today.
 
-Subjective pass/fail criteria evaluated by appraisers.
+- **OpenCode** — full support. Multi-model routing via file-based `foundry-*` agents.
+  This is the primary target platform.
 
-- `foundry/laws/*.md` — global laws (all files concatenated, apply everywhere).
-- `foundry/artefacts/<type>/laws.md` — type-specific laws.
+- **Other skill-aware AI tools** — the skills and tools are portable to any
+  skill-aware AI system. Multi-model stage routing is OpenCode-specific today
+  because it relies on `.opencode/agents/` files.
 
-Each law is a `## heading` (its identifier, referenced in feedback as `#law:<id>`) with a description, passing criteria, and failing criteria.
+---
 
-### Appraisers
+## Install
 
-Defined in `foundry/appraisers/`. Each appraiser is a named personality with an optional `model` override. Artefact types pick which appraisers may evaluate them:
+Add the plugin to `opencode.json`:
 
-```yaml
-appraisers:
-  count: 3                       # how many appraisers (default: 3)
-  allowed: [pedantic, pragmatic] # which personalities (default: all)
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
 ```
 
-Appraisers are distributed evenly across the allowed set for maximum diversity.
-
-### WORK.md
-
-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).
+Restart OpenCode so the plugin registers its tools and skills. You will see new
+tools and skills become available in OpenCode's command palette once the restart
+completes. The `init-foundry` skill and flow-management tools are now ready to use.
 
 ---
 
-## 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:
+## Upgrade
 
-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.
+Run the `upgrade-foundry` skill from a clean project state when moving an existing project to the installed Foundry version. The skill preserves the existing `foundry/` directory, initialises a fresh current-version configuration, analyses the preserved configuration as source material, and recreates supported concepts through current tools.
 
-Per-stage write rules:
+The upgrade process asks clarifying questions for ambiguous routing, input contracts, validation behaviour, memory settings, and deprecated concepts. It leaves the preserved source directory in place until you explicitly approve cleanup.
 
-| 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.
+## Quick start
 
-### Deterministic orchestration
+### Phase 1 — Install
 
-The `orchestrate` skill is thin — a 3-line loop:
+Add the plugin to `opencode.json` (see Install section above):
 
-```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
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
 ```
 
-`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.
-
----
+Then restart OpenCode so the plugin registers its tools and skills. You will see new
+tools and skills become available in OpenCode's command palette once the restart
+completes. The `init-foundry` skill and flow-management tools are now ready to use.
 
-## Feedback lifecycle
+### Phase 2 — Initialise
 
-Feedback is markdown checklists under each artefact in WORK.md, tagged to indicate source.
+Open OpenCode in your project repo and say:
 
 ```
-- [ ] 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
+> run init-foundry
 ```
 
-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.
+Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` agent file
+per model available in your session, commits the structure, and then asks you to
+restart. All the foundational configuration directories are created; you will
+populate them next.
 
-### 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.
-
----
+Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
 
-## 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.
-
----
-
-## Multi-model routing
-
-Different stages can run on different models for genuine cognitive diversity (mitigating shared blind spots):
-
-- 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.
-
----
+### Phase 3 — Build a flow without writing one
 
-## Skills
+Ask Foundry to set up a flow:
 
-Foundry is a collection of skills. Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
-
-### Pipeline
-
-| Skill | Type | Purpose |
-|-------|------|---------|
-| `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. |
-
-### Authoring
-
-| Skill | Purpose |
-|-------|---------|
-| `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
-
-| Skill | Purpose |
-|-------|---------|
-| `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 authoring skills are interactive and conflict-aware — they explain what they're about to write and ask before writing.
-
----
-
-## 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/`).
-
----
+```
+> set up a flow that writes haikus
+```
 
-## Project layout
+Foundry will ask clarifying questions about the flow's purpose, constraints, and
+entry points. It will then scaffold a haiku artefact type with a syllable-count
+validator, laws for form / imagery / mood, two appraisers with different
+sensibilities and bias profiles, a cycle that connects them in sequence, and a flow
+that ties it all together. Everything is scaffolded; you do not write any
+configuration by hand. This demonstrates the full system in action.
 
-### Package (this repo)
+Now run it:
 
 ```
-@really-knows-ai/foundry
-├── .opencode/
-│   └── plugins/
-│       └── foundry.js          # plugin: skills + 24 custom tools
-├── skills/                     # skill definitions
-│   ├── flow/                   # pipeline
-│   ├── orchestrate/
-│   ├── forge/
-│   ├── quench/
-│   ├── appraise/
-│   ├── human-appraise/
-│   ├── init-foundry/           # authoring
-│   ├── add-artefact-type/
-│   ├── add-law/
-│   ├── add-appraiser/
-│   ├── add-cycle/
-│   ├── add-flow/
-│   ├── 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             # 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
+> write me a haiku about autumn
 ```
 
-### User project (after `init-foundry`)
+Here is what the loop produces:
 
 ```
-your-project/
-├── foundry/
-│   ├── flows/                  # flow definitions
-│   ├── cycles/                 # cycle definitions
-│   ├── artefacts/              # artefact type definitions
-│   │   └── <type>/
-│   │       ├── definition.md
-│   │       ├── 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
-└── ...
+forge     → drafts a haiku                          [commit]
+quench    → 7/7/5 — fails syllable check            [commit]
+forge     → revises                                 [commit]
+quench    → 5/7/5 — passes                          [commit]
+appraise  → 2 appraisers, one flags weak imagery    [commit]
+forge     → revises                                 [commit]
+appraise  → clean                                   [commit]
+done      → squash-merged to main with attestation
 ```
 
-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.
+Every stage commits. Every decision is recorded. Every piece of feedback and every
+revision leaves a trace in the work branch. The final artefact on `main` carries a
+signed attestation showing exactly how that output was produced, which models
+contributed, and when each appraiser signed off.
+
+This trace is the proof. You can play it back, audit it, replay it under a different
+model, or use it to argue that the AI output is trustworthy. Every step is visible.
+Nothing is hidden.
+
+For codebase-aware flows, add flow memory after the first run: initialise memory,
+declare the entity and edge vocabulary, add extractors, and opt a cycle into
+`assay.extractors`. See [Optional: flow memory](docs/getting-started.md#optional-flow-memory)
+and [Assay](docs/concepts.md#assay) for the configuration path.
+
+> **Note (3.0.0):** flow memory currently persists to `cozo-node`, which is
+> unmaintained upstream. Installation produces six cosmetic deprecation warnings
+> from transitive dependencies (`pnpm audit` is clean). Foundry will migrate to
+> a maintained backend in a future release; the public `foundry_memory_*` tools
+> and on-disk vocabulary/NDJSON format are designed to survive that migration.
+> See `CHANGELOG.md` and [docs/memory-maintenance.md](docs/memory-maintenance.md#backend-status-as-of-300).
 
 ---
 
-## Design decisions
+## What you can show your team
 
-### Everything is markdown
+After the quick start completes, you have five concrete artefacts to point at to
+demonstrate engineered confidence:
 
-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.
+- **The artefact itself** — `haikus/autumn.md` on `main`. The final, approved output
+  ready for use or deployment.
 
-### Skills are the pipeline, tools are the machinery
+- **The laws it satisfied** — `foundry/artefacts/haiku/laws.md`. The criteria it was
+  measured against, written in markdown and version-controlled.
 
-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.
+- **The feedback ledger** — `WORK.feedback.yaml` on the archived work branch. Every
+  issue raised, by whom, and how it was resolved during the loop.
 
-### WORK.md as shared state
+- **The per-stage commit history** — the raw commits on `archive/work/<flow>-<...>`.
+  A micro-commit per stage showing exactly what changed and why at each step.
 
-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.
+- **The signed attestation on main** — the squash commit with the Foundry attestation
+  block embedded in its message. Proof of approval, signed and timestamped.
 
-### Cycles own their routing
+This is what makes "engineered confidence" concrete. You can show your team exactly
+how that AI output was produced, what it passed through, why you trust it, and who
+signed off. Every step is auditable. Every decision is recorded. The loop is
+reproducible.
 
-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 checklists
+## What's in the box
 
-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.
+- **Deterministic governance** — routing, commits, write boundaries, and feedback
+  state live in tested plugin code, outside LLM control.
 
-### Wont-fix requires approval
+- **Written quality criteria** — laws are markdown files; an appraiser panel scores
+  each artefact against them, so quality is objective.
 
-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 diversity** — forge on one model, appraise on another, every
+  appraiser on a different model if you want. Different models catch different
+  mistakes.
 
-### Multi-model diversity
+- **Full git audit trail** — one commit per stage with `WORK.md`,
+  `WORK.feedback.yaml`, and `WORK.history.yaml`. Every iteration is recorded.
 
-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.
+- **Signed attestation on main** — every flow finishes with a squash commit carrying
+  a canonical Foundry attestation block that proves the artefact was processed.
 
-### Input artefacts are read-only
+- **Archived forensic branch** — the raw work branch is retained for auditors as
+  `archive/work/<flow>-<desc>-<hash>`. The full micro-history is never lost.
 
-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.
+- **Bring your own pipeline** — artefact types, laws, and stages are yours; works
+  for code, specs, docs, data, and anything else you can describe as files with
+  pass/fail criteria.
 
-### Glob patterns must not overlap
+- **Assay preflight** — deterministic extractor stage that measures the project
+  before forge starts, so codebase-aware flows can begin from structured facts.
 
-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.
+- **Flow memory** — typed graph store with scoped tools, semantic search when
+  enabled, and committed NDJSON rows for cross-cycle reuse.
 
 ---
 
 ## 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.
+The full reference set lives in [docs/](docs/) — start at [docs/README.md](docs/README.md)
+for a guided index of every document and when to read it.
 
 ---
 
 ## License
 
-[MIT](LICENSE)
+MIT.