@really-knows-ai/foundry 2.3.1 → 3.0.0

package/README.md

@@ -1,276 +1,278 @@
 # 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.
+> Engineered confidence for AI-generated work. Define what good looks like.
 
-## Compatibility
+[![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)
 
-- **OpenCode** — full support, multi-model routing via file-based 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.
+## Engineering confidence
 
-## Installation
+### Confidence is engineered
 
-Add `@really-knows-ai/foundry` to your OpenCode config:
+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.
 
-```json
-// opencode.json
-{
-  "packages": {
-    "@really-knows-ai/foundry": "latest"
-  }
-}
-```
+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.
 
-## Quick start
+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.
 
-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
+### The operating model: assay, then forge → quench → appraise
 
-## How it works
+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.
 
-```
-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
-```
+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:
 
-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.
+- **Forge** produces or revises the artefact. The stage that creates and reshapes
+  work, responding to feedback from appraisers or building on prior drafts.
 
-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.
+- **Quench** runs deterministic checks that harden or reject the work. Validation is
+  fast and non-negotiable, catching errors before they reach appraisers.
 
-## Custom tools
+- **Appraise** judges quality against written laws. Independent evaluators inspect
+  whether the work meets the subjective standards you define.
 
-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.
+- **Human-appraise** provides direct judgement when the stakes require it or the loop
+  deadlocks. Offers human oversight at critical decision points.
 
-| 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` |
+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.
 
-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.
+### What you describe, what Foundry enforces
 
-## Core concepts
+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.
 
-### Foundry Flows
+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.
 
-Defined in `foundry/flows/`. A flow lists cycles to execute in order. Starting a flow creates a work branch and a fresh `WORK.md`.
+---
 
-### Foundry Cycles
+## Compatibility
 
-Defined in `foundry/cycles/`. A cycle specifies:
-- `output` — the artefact type it produces (read-write)
-- `inputs` — artefact types from previous cycles (read-only)
+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.
 
-### Stages
+- **OpenCode** — full support. Multi-model routing via file-based `foundry-*` agents.
+  This is the primary target platform.
 
-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
+- **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.
 
-### Artefact types
+---
 
-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
+## Install
 
-### Laws
+Add the plugin to `opencode.json`:
 
-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
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
+```
 
-Each law is a `## heading` (the identifier, used in feedback tags as `#law:<id>`) with a description, passing criteria, and failing criteria.
+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.
 
-### 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`:
+## Upgrade
 
-```yaml
-appraisers:
-  count: 3                          # how many appraisers (default: 3)
-  allowed: [pedantic, pragmatic]    # which personalities (default: all available)
-```
+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.
 
-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).
+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.
 
-### 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
+## Quick start
 
-### Feedback lifecycle
+### Phase 1 — Install
 
-```
-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
-```
+Add the plugin to `opencode.json` (see Install section above):
 
-Validation feedback (`#validation`) cannot be wont-fixed — deterministic rules are not negotiable.
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
+```
 
-### File modification enforcement
+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.
 
-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
+### Phase 2 — Initialise
 
-> **Merge hygiene:** WORK.md and WORK.history.yaml are ephemeral working files. Delete them before squash-merging the branch back into main.
+Open OpenCode in your project repo and say:
 
-## Skills
+```
+> run init-foundry
+```
 
-Everything is a skill. Skills are either atomic (do one thing) or composite (orchestrate other skills).
+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.
 
-### Pipeline skills
+Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
 
-| 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 |
+### Phase 3 — Build a flow without writing one
 
-### Helper skills
+Ask Foundry to set up a flow:
 
-| 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 |
+```
+> set up a flow that writes haikus
+```
 
-### Utility skills
+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.
 
-| Skill | Purpose |
-|-------|---------|
-| `sort` | Deterministic cycle router — determines and dispatches the next stage |
-| `hitl` | Human-in-the-loop intervention points |
+Now run it:
 
-All helper skills are interactive — they walk you through the process, check for conflicts, and confirm before writing files.
+```
+> write me a haiku about autumn
+```
 
-## Package structure
+Here is what the loop produces:
 
 ```
-@really-knows-ai/foundry
-├── .opencode/
-│   └── plugins/
-│       └── foundry.js          # OpenCode plugin (skills + 25 custom tools)
-├── skills/                     # skill definitions (the pipeline)
-│   ├── forge/
-│   ├── quench/
-│   ├── appraise/
-│   ├── cycle/
-│   ├── flow/
-│   ├── init-foundry/
-│   ├── 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
-│   │   ├── 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
-└── README.md
+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
 ```
 
-## User project structure
+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.
 
-After running `init-foundry`, your project gets a `foundry/` directory:
+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.
 
-```
-your-project/
-├── foundry/
-│   ├── flows/                  # flow definitions
-│   ├── cycles/                 # cycle definitions
-│   ├── artefacts/              # artefact type definitions
-│   │   └── <type>/
-│   │       ├── definition.md
-│   │       ├── laws.md         # (optional) type-specific laws
-│   │       └── validation.md   # (optional) CLI checks
-│   ├── laws/                   # global laws
-│   └── appraisers/             # appraiser personalities
-├── opencode.json
-└── ...
-```
+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).
+
+---
+
+## What you can show your team
+
+After the quick start completes, you have five concrete artefacts to point at to
+demonstrate engineered confidence:
+
+- **The artefact itself** — `haikus/autumn.md` on `main`. The final, approved output
+  ready for use or deployment.
+
+- **The laws it satisfied** — `foundry/artefacts/haiku/laws.md`. The criteria it was
+  measured against, written in markdown and version-controlled.
+
+- **The feedback ledger** — `WORK.feedback.yaml` on the archived work branch. Every
+  issue raised, by whom, and how it was resolved during the loop.
+
+- **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.
 
-## Design decisions
+- **The signed attestation on main** — the squash commit with the Foundry attestation
+  block embedded in its message. Proof of approval, signed and timestamped.
 
-### Everything is markdown
+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.
 
-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.
+---
 
-### Skills are the pipeline, tools are the machinery
+## What's in the box
 
-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.
+- **Deterministic governance** — routing, commits, write boundaries, and feedback
+  state live in tested plugin code, outside LLM control.
 
-### WORK.md as shared state
+- **Written quality criteria** — laws are markdown files; an appraiser panel scores
+  each artefact against them, so quality is objective.
 
-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.
+- **Multi-model diversity** — forge on one model, appraise on another, every
+  appraiser on a different model if you want. Different models catch different
+  mistakes.
 
-### Feedback as checklist items
+- **Full git audit trail** — one commit per stage with `WORK.md`,
+  `WORK.feedback.yaml`, and `WORK.history.yaml`. Every iteration is recorded.
 
-Feedback uses markdown checklists with `#validation` or `#law:<id>` tags. Human-readable, trivially parseable by an LLM, with lifecycle states expressed inline.
+- **Signed attestation on main** — every flow finishes with a squash commit carrying
+  a canonical Foundry attestation block that proves the artefact was processed.
 
-### Wont-fix requires appraiser approval
+- **Archived forensic branch** — the raw work branch is retained for auditors as
+  `archive/work/<flow>-<desc>-<hash>`. The full micro-history is never lost.
 
-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.
+- **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.
 
-### Multi-model stage routing
+- **Assay preflight** — deterministic extractor stage that measures the project
+  before forge starts, so codebase-aware flows can begin from structured facts.
 
-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.
+- **Flow memory** — typed graph store with scoped tools, semantic search when
+  enabled, and committed NDJSON rows for cross-cycle reuse.
 
-### 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.
+## Further reading
 
-### Glob patterns must not overlap
+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.
 
-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.
+---
 
 ## License
 
-[MIT](LICENSE)
+MIT.

package/dist/.opencode/plugins/foundry-tools/appraiser-tools.js

@@ -0,0 +1,28 @@
+import { selectAppraisers } from '../../../scripts/lib/config.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+export function createAppraiserTools({ tool }) {
+  return {
+    foundry_appraisers_select: tool({
+      description: 'Select appraisers for an artefact type',
+      args: {
+        typeId: tool.schema.string().describe('Artefact type ID'),
+        count: tool.schema.number().optional().describe('Number of appraisers to select'),
+      },
+      // Flow-tier mutation per SPEC §6: appraiser selection mutates the
+      // dispatch state of the in-flight cycle. Branch guard runs before
+      // failed-flow gate so wrong-branch refusals win over failed-state.
+      execute: guarded('foundry_appraisers_select', [flowBranchGuard, gateNotFailed], async (args, context) => {
+        const io = makeIO(context.worktree);
+        const result = await selectAppraisers('foundry', args.typeId, {
+          io,
+          countOverride: args.count ?? null,
+        });
+        return JSON.stringify(result);
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/artefact-tools.js

@@ -0,0 +1,58 @@
+import path from 'path';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { parseArtefactsTable, setArtefactStatus } from '../../../scripts/lib/artefacts.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+function makeListTool(tool) {
+  return tool({
+    description: 'List artefacts from the WORK.md table. Optionally filter by cycle — callers should always pass the current cycle to avoid picking up stale rows from prior sessions.',
+    args: {
+      cycle: tool.schema.string().optional().describe('Only return rows whose Cycle column matches this value'),
+    },
+    async execute(args, context) {
+      const workPath = path.join(context.worktree, 'WORK.md');
+      if (!existsSync(workPath)) {
+        return JSON.stringify({ error: 'WORK.md not found' });
+      }
+      const text = readFileSync(workPath, 'utf-8');
+      const rows = parseArtefactsTable(text);
+      const filtered = args.cycle ? rows.filter(r => r.cycle === args.cycle) : rows;
+      return JSON.stringify(filtered);
+    },
+  });
+}
+
+export function createArtefactTools({ tool }) {
+  return {
+    // NOTE: `foundry_artefacts_add` was removed in v2.2.0. Artefacts are now
+    // registered automatically by the orchestrator's internal finalize step as drafts,
+    // then promoted to done|blocked via `foundry_artefacts_set_status`.
+    foundry_artefacts_set_status: tool({
+      description: 'Update the status of an artefact in WORK.md (done|blocked only)',
+      args: {
+        file: tool.schema.string().describe('Artefact file path'),
+        status: tool.schema.string().describe('New status (done|blocked)'),
+      },
+      execute: guarded('foundry_artefacts_set_status', [flowBranchGuard, gateNotFailed], async (args, context) => {
+        const io = makeIO(context.worktree);
+        const guard = requireNoActiveStage(io);
+        if (!guard.ok) return JSON.stringify({ error: `foundry_artefacts_set_status ${guard.error}` });
+        const workPath = path.join(context.worktree, 'WORK.md');
+        const text = readFileSync(workPath, 'utf-8');
+        try {
+          const updated = setArtefactStatus(text, args.file, args.status);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        } catch (e) {
+          return JSON.stringify({ error: e.message });
+        }
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+
+    foundry_artefacts_list: makeListTool(tool),
+  };
+}