@really-knows-ai/foundry 3.5.8 → 3.6.0

package/dist/docs/concepts.md

@@ -20,9 +20,9 @@ An iterative unit that produces one artefact type and routes to later cycles thr
 - `output-type` — 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`).
+- `always-human-appraise` — whether a human quality gate runs every iteration (default: `false`).
+- `deadlock-human-appraise` — whether a human is pulled in when the deadlock threshold is reached (default: `true`).
+- `max-iterations` — maximum forge iterations (default: `3`).
 - `models` — optional per-stage model overrides.
 
 A cycle runs **assay** first when configured, then **forge → quench → appraise** (and optionally **human-appraise**), looping until all feedback is resolved or `max-iterations` is hit.
@@ -35,9 +35,9 @@ The stage names come from the foundry metaphor because the system treats AI outp
 
 - **assay** — opt-in pre-forge stage that populates flow memory by running project-authored extractor scripts (iteration 0 only). No artefact, no feedback, no output beyond memory writes. See the [Assay](#assay) and [Extractor](#extractor) entries below.
 - **forge** — produce or revise the artefact.
-- **quench** — run deterministic CLI checks declared in laws (via their optional `validators:` blocks).
-- **appraise** — subjective evaluation by multiple appraiser sub-agents.
-- **human-appraise** — human quality gate. Can run every iteration, only on deadlock, or both.
+- **quench** — deterministic validation run inside the orchestrator against laws that contain validators.
+- **appraise** — orchestrator-managed `dispatch_multi` fan-out to appraiser sub-agents, with internal consolidation.
+- **human-appraise** — human quality gate. Runs every iteration when `always-human-appraise` is true, or on deadlock when `deadlock-human-appraise` is true.
 
 Feedback is always *about an artefact* and flows backward to forge. Assay sits outside the artefact-feedback loop because it precedes the artefact and its only failure mode (a broken extractor under `foundry/memory/extractors/`) lives outside forge's `file-patterns`.
 
@@ -63,31 +63,35 @@ See also: [Extractor](#extractor).
 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, with optional validators for deterministic checks.
+- `laws.md` *(optional)* — type-specific criteria, with optional validators for deterministic 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. Two scopes:
+A rule or criterion that defines expectations for artefacts. 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.
+Each law is a `## heading` (its identifier, used in feedback tags as `law:<id>`) with a description, passing criteria, and failing criteria. Laws may declare optional validators, which are deterministic scripts that verify the artefact programmatically.
+
+## Validator
+
+An optional deterministic script attached to a law. Declared in a law's `validators` field and run during the quench stage. Each validator produces feedback tagged `law:<law-id>:<validator-id>` when its check fails. Validators are the mechanism for automated, deterministic enforcement of law requirements.
 
 ## Appraiser
 
-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.
+An evaluator that judges artefacts against laws through its personality or perspective. 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. Appraisers receive the artefact content and applicable laws; they do not receive validator metadata.
 
 ## WORK.md
 
-The transient shared state for a flow. Created on the work branch by the flow skill, it tracks:
+The transient shared state for a flow. Created on the work branch, it tracks:
 
 - Current position (flow, cycle, stage list, iteration limits) in frontmatter.
 - The goal (prose — written once).
-- An artefact registry (file, type, cycle, status).
-- Feedback state lives alongside it in `WORK.feedback.yaml`.
+
+Artefacts are discovered from branch changes against the current cycle's output-type file patterns, not stored as an artefact table in `WORK.md`. Feedback state lives alongside `WORK.md` in `WORK.feedback.yaml`.
 
 See [work-spec.md](work-spec.md) for the full spec.
 
@@ -100,12 +104,12 @@ Append-only log of every stage execution, sitting next to WORK.md. Used by sort
 Feedback items live in `WORK.feedback.yaml` — a yaml file at the worktree
 root, alongside `WORK.md`. Every item has a ULID, a source stage, and a
 full history of state transitions (open → actioned → resolved, or variants
-including wont-fix / rejected / deadlocked).
+including wont-fix / rejected).
 
 Plugins read and write feedback through the `foundry_feedback_*` tools;
-skills never edit the yaml directly. Sort-side detection of deadlocked
-items (per-item history depth) replaces the earlier global-iteration
-counter.
+skills never edit the yaml directly. Sort routing uses the iteration count
+and `max-iterations` / `deadlock-human-appraise` settings to detect
+deadlock, not per-item deadlock history.
 
 See `docs/work-spec.md` for the full schema and state machine.
 
@@ -113,8 +117,8 @@ See `docs/work-spec.md` for the full schema and state machine.
 
 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.
+1. **Every-iteration** — the cycle declares `always-human-appraise: true`. The `human-appraise` stage runs after LLM appraise each iteration.
+2. **Deadlock** — the cycle declares `deadlock-human-appraise: true` (default). If the iteration count reaches `max-iterations`, sort inserts a `human-appraise` stage to break the tie.
 
 Human feedback is tagged `human` and takes priority over LLM feedback on the same topic.
 
@@ -194,6 +198,28 @@ The signed squash commit on the base branch references the archive
 branch tip SHA in its attestation block. Archive branches accumulate
 indefinitely — periodic manual pruning is outside the tool's scope.
 
+## Attestation
+
+A cryptographic claim that a work branch completed all required stages
+and all feedback was resolved. Created by `foundry_attest({ confirm: true })`,
+which writes and commits `ATTEST.md` at `HEAD` containing the cycle
+goal, a diff SHA-256 of the branch changes, and a canonical JSON payload
+with the flow contract, governance hashes, output artefact list, process
+log, and archive branch reference. Work-branch `foundry_git_finish`
+verifies the attestation before allowing the squash merge. Config and
+dry-run branches do not require attestation.
+
+## ATTEST.md
+
+The attestation document written by `foundry_attest` as the work-branch
+`HEAD` commit. Contains the goal prose, `diff-sha256` of the branch
+diff, and a signed attestation block between `-----BEGIN FOUNDRY
+ATTESTATION-----` and `-----END FOUNDRY ATTESTATION-----` delimiters.
+`foundry_git_finish` verifies `ATTEST.md` exists at `HEAD`, checks the
+`diff-sha256` matches the recomputed branch diff, uses the attestation
+payload in the signed final commit message, and preserves the archive
+branch reference.
+
 ## 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.
@@ -267,6 +293,16 @@ All deterministic pipeline operations are exposed as custom tools by the Foundry
 
 A self-contained workflow written as markdown with YAML frontmatter. Foundry ships a user-facing `Foundry` guide agent plus skills for pipeline execution, authoring, maintenance, and memory administration. The guide agent is the normal interface for users; skills and tools provide the internal workflows it uses to initialise projects, create artefact types, define laws, configure appraisers, build cycles and flows, and run governed artefact generation. Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
 
+## Foundry agent wizard
+
+The interactive configuration process that runs when the user first
+interacts with the Foundry agent. The wizard walks through four phases
+— Understand, Plan, Confirm, Build — asking one question at a time.
+Configuration files are created only after the user confirms the plan.
+The wizard eliminates hand-authoring of normal setup by using the
+structured config creation tools (`foundry_config_create_*`) on a
+`config/*` branch.
+
 ---
 
 ## Extractor

package/dist/docs/getting-started.md

@@ -26,7 +26,7 @@ directory structure, generates stage agents, and installs the Foundry guide
 agent automatically.
 
 After restart, type **hello foundry**. The assistant will tell you whether a
-further restart is needed and when to switch to the Foundry agent.
+further restart is needed and when to switch to the **Foundry** agent.
 
 Optionally, if you want the package available to your project's local node_modules (for editor tooling or scripts), run:
 
@@ -44,7 +44,7 @@ assistant will read the Foundry bootstrap context and respond with guidance:
 - If Foundry is already set up: it will tell you to switch to the Foundry agent
   directly.
 
-switch to the **Foundry** agent before authoring flows. The Foundry agent
+Switch to the **Foundry** agent before authoring flows. The Foundry agent
 understands Foundry's authoring workflow and handles dependent setup such as
 artefact types, laws, validators, appraisers, cycles, and config branches.
 
@@ -59,6 +59,12 @@ Foundry's configuration is five things: artefact types, laws, appraisers, cycles
 
 ### Author through the Foundry agent
 
+The Foundry agent walks through a four-phase wizard protocol — **Understand,
+Plan, Confirm, Build** — asking one question at a time. Configuration files are
+created only after you confirm the plan. This wizard eliminates hand-authoring
+of normal setup by using the structured config creation tools on a `config/*`
+branch.
+
 Ask the Foundry agent to author or modify any part of the configuration. For example:
 
 > Add a `haiku` artefact type with a `poetic-form` appraiser.
@@ -77,11 +83,27 @@ These are the five pieces of a Foundry configuration, in dependency order:
 
 1. **Artefact types** — define the output of each cycle. Each type has an `id`, `name`, prose description, `file-patterns` (forge's write scope), appraiser config, and optional type-specific `laws.md`. Produces `foundry/artefacts/<id>/definition.md`.
 
-2. **Laws** — subjective pass/fail criteria evaluated by appraisers. Two scopes: global (`foundry/laws/*.md`, concatenated for every artefact) and type-specific (`foundry/artefacts/<type>/laws.md`). Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
+2. **Laws** — rules or criteria evaluated by appraisers. Two scopes: global (`foundry/laws/*.md`, concatenated for every artefact) and type-specific (`foundry/artefacts/<type>/laws.md`). Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
 
 3. **Appraisers** — independent evaluators with named personalities. Each may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
 
-4. **Cycles** — produce one artefact type and declare `output-type`, `inputs` (a contract over other types), `targets` (reachable downstream cycles), human-gate config, and optional per-stage model overrides. Example:
+4. **Cycles** — produce one artefact type from a definition with these fields:
+
+   | Field | Purpose |
+   |-------|---------|
+   | `id` | Unique identifier |
+   | `name` | Human-readable label |
+   | `output-type` | The artefact type this cycle produces |
+   | `inputs` | Contract over upstream types (e.g. `any-of`, `all-of`) |
+   | `targets` | Reachable downstream cycles for flow routing |
+   | `always-human-appraise` | Bypass LLM appraisers on every iteration |
+   | `deadlock-human-appraise` | Escalate to human appraiser at iteration limit |
+   | `max-iterations` | Maximum forge iterations before deadlock |
+   | `assay` | Optional extractor config for pre-forge measurement |
+   | `memory` | Optional entity read/write permissions |
+   | `models` | Per-stage model overrides (e.g. `appraise`, `forge`) |
+
+   Example:
 
    ```markdown
    ---
@@ -93,9 +115,9 @@ These are the five pieces of a Foundry configuration, in dependency order:
      artefacts:
        - petition
    targets: []
-   human-appraise: false
-   deadlock-appraise: true
-   deadlock-iterations: 5
+   always-human-appraise: false
+   deadlock-human-appraise: true
+   max-iterations: 5
    models:
      appraise: openai/gpt-5
    ---
@@ -114,15 +136,15 @@ Users who prefer to write configuration files by hand open a config branch first
 To run a flow, ask the Foundry agent with your goal as the input (e.g. "Run the make-haiku flow to write a haiku about autumn rain"). The Foundry agent dispatches the `flow` skill, which:
 
 1. Checks prerequisites and picks 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. Creates a work branch and scaffolds `WORK.md` with the goal.
-3. Hands off to `orchestrate`, which drives the cycle:
+2. Creates a work branch and scaffolds `WORK.md` with frontmatter (`flow`, `cycle`) and the `# Goal` section. No artefact table is stored in the workfile; artefacts are discovered from branch diffs.
+3. Hands off to `orchestrate`, which drives the cycle. Orchestrate setup fills the remaining frontmatter (`stages`, `max-iterations`, model overrides, `assay` config) from the cycle definition, then runs the loop:
    - **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.
+   - **quench** runs deterministic validation inside the orchestrator, executing any validators attached to laws.
+   - **appraise** fans out parallel appraiser sub-agents via `dispatch_multi` and internally consolidates their `law:<id>` feedback.
+   - **human-appraise** (if configured, or at the iteration limit) 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.
+5. When all desired cycles are complete, the flow skill asks you to attest the work via `foundry_attest`, which verifies cycle completion, writes and commits `ATTEST.md`. After attestation succeeds, `foundry_git_finish` squash-merges to the base branch with a signed attestation block, preserves the work branch as an archive, and creates the final signed commit. See [`docs/tools.md`](./tools.md#foundry_attest) for the attestation contract.
 
 Every stage ends with a micro-commit. Violations of the write invariant (writing to disallowed files) hard-stop the cycle.
 
@@ -154,7 +176,7 @@ never committed by foundry. See the `dry-run` skill for the full loop.
 
 While a flow is running, the state of the world is in four places:
 
-- `WORK.md` — current cycle, goal, and artefact table.
+- `WORK.md` — current cycle, goal, and frontmatter state. Artefacts are discovered from branch diffs against the current cycle output type; see `foundry_artefacts_list`.
 - `WORK.feedback.yaml` — feedback items and their lifecycle history.
 - `WORK.history.yaml` — append-only stage execution log.
 - `git log` — one commit per stage.
@@ -185,7 +207,7 @@ Use `foundry_stage_retry()` when the underlying problem is fixed and you want to
 
 ## Cleaning up
 
-When a flow completes, `foundry_git_finish` handles integration with audit guarantees. On `work/*` branches, it commits `WORK.*` cleanup, preserves the branch as `archive/work/<flow>-<desc>-<hash>` for immutable forensic history, squash-merges to the base branch, and creates a signed commit whose message embeds the canonical Foundry attestation block. See [`docs/tools.md`](./tools.md#foundry_git_finish) for the full contract.
+When a flow completes, the flow skill asks you to attest the work via `foundry_attest`, which verifies cycle completion, writes `ATTEST.md` at `HEAD`, and commits it. After attestation succeeds, `foundry_git_finish` handles integration with audit guarantees: it commits `WORK.*` cleanup, preserves the branch as `archive/work/<flow>-<desc>-<hash>` for immutable forensic history, squash-merges to the base branch, and creates a signed commit whose message embeds the canonical Foundry attestation block. See [`docs/tools.md`](./tools.md#foundry_attest) and [`docs/tools.md`](./tools.md#foundry_git_finish) for the full contracts.
 
 ---
 

package/dist/docs/memory-maintenance.md

@@ -4,7 +4,7 @@ Contributor-facing notes. This file records the derived details from the
 Cozo docs / plugin surface that cost us time to establish. Add entries when a
 fix required non-trivial spelunking, so the next maintainer can reuse the result.
 
-## Backend status (as of 3.0.0)
+## Backend status
 
 The memory subsystem persists to `cozo-node@0.7.6`, which wraps the Rust
 `cozodb` engine. Both are effectively unmaintained:
@@ -23,7 +23,7 @@ property-graph with HNSW, Cypher dialect), **SurrealDB embedded**,
 **DuckDB + vss + PGQ**, and **SQLite + `sqlite-vec`** with hand-rolled
 graph traversal. The migration is structured so the public memory tool
 surface (`foundry_memory_*`) and the on-disk durable artefacts
-(`foundry-memory/entities/*.md`, `foundry-memory/edges/*.md`,
+(`foundry/memory/entities/*.md`, `foundry/memory/edges/*.md`,
 `foundry-memory/relations/*.ndjson`) remain stable; only the live
 in-process store changes.
 
@@ -126,7 +126,7 @@ Extractors are defined at `foundry/memory/extractors/<name>.md` with a `command`
 
 ## Memory layout: two trees
 
-Since Phase 2 (3.0.0), memory is split across two top-level trees:
+Memory is split across two top-level trees:
 
 - `foundry/memory/` — *config*. Holds `config.md`, `schema.json`,
   `entities/<name>.md`, `edges/<name>.md`, `extractors/<name>.md`,

package/dist/docs/tools.md

@@ -1,8 +1,8 @@
 # Foundry Public Tool Reference
 
-Generated from the v3.0.x public plugin API. The authoritative tool set is
+Generated from the current public plugin API for Foundry 3.5.8. The authoritative tool set is
 enforced by `tests/plugin/tool-registration.test.js` — if that snapshot
-drifts, this doc must be updated. Total: **66 tools**.
+drifts, this doc must be updated. Total: **65 tools**.
 
 All tools accept arguments as a JSON object and return JSON-stringified
 results. Errors are returned as a stringified `{error: "..."}` object (not
@@ -39,13 +39,15 @@ state machine, see [`docs/concepts.md`](./concepts.md) and
 
   | Namespace | Applies to | Notes |
   |-----------|------------|-------|
-  | `config/<description>` | `foundry_config_create_*` (5), `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_*`, `foundry_memory_drop_*`, `foundry_memory_reset`, `foundry_memory_init`, `foundry_memory_change_embedding_model`, `foundry_extractor_create` | Config and schema mutation only. |
+  | `config/<description>` | `foundry_config_create_artefact_type`, `foundry_config_create_appraiser`, `foundry_config_create_flow`, `foundry_config_create_cycle`, `foundry_config_add_law`, `foundry_config_edit_law`, `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_*`, `foundry_memory_drop_*`, `foundry_memory_reset`, `foundry_memory_init`, `foundry_memory_change_embedding_model`, `foundry_extractor_create` | Config and schema mutation only. |
   | `work/<flow>-<desc>` or `dry-run/<x>/<y>` | `foundry_orchestrate`, `foundry_stage_begin`, `foundry_stage_end`, `foundry_stage_retry`, `foundry_workfile_*`, `foundry_artefacts_*`, `foundry_feedback_*`, `foundry_assay_run`, `foundry_validate_run`, `foundry_memory_put`, `foundry_memory_relate`, `foundry_memory_unrelate` | Flow-data mutation only. |
   | Any branch | `foundry_workfile_get`, `foundry_artefacts_list`, `foundry_feedback_list`, `foundry_history_list`, `foundry_config_*` read tools, `foundry_config_validate_*`, `foundry_appraisers_select`, `foundry_memory_get`, `foundry_memory_list`, `foundry_memory_neighbours`, `foundry_memory_query`, `foundry_memory_search`, `foundry_memory_dump`, `foundry_memory_validate`, `foundry_snapshot_*` | No branch guard and no failed-flow guard. |
   | Self-classifying | `foundry_git_branch`, `foundry_git_finish` | Each tool checks its own branch rules. Leaving the failed branch is the recovery path. |
 
   Off-namespace calls return a structured refusal envelope naming the required namespace and the current branch.
 
+> **Memory admin callability:** Schema-mutation and destructive memory admin tools (`foundry_memory_init`, `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_entity_type`, `foundry_memory_rename_edge_type`, `foundry_memory_drop_entity_type`, `foundry_memory_drop_edge_type`, `foundry_memory_reset`, `foundry_memory_change_embedding_model`) require `config/*` branches and non-failed flow. Read-only diagnostics (`foundry_memory_get`, `foundry_memory_list`, `foundry_memory_neighbours`, `foundry_memory_query`, `foundry_memory_search`, `foundry_memory_dump`, `foundry_memory_validate`) are broadly callable. `foundry_memory_vacuum` uses only the failed-flow guard and is not config-branch guarded.
+
 ## Tool index
 
 **Lifecycle**
@@ -238,12 +240,17 @@ frontmatter.
 **Args:**
 - `lastResult` (object, optional): `{ ok: boolean, error?: string }` — output of the
   prior action.
+- `lastResults` (array, optional): Output of prior `dispatch_multi` actions.
 - `cycleDef` (string, optional): Test-mode override path to a cycle file.
+- `baseBranch` (string, optional, default `main`): Base branch for diff and merge.
+- `defaultModel` (string, optional): Model override for all dispatch prompts.
 
 **Returns:** one of:
 - `{ action: "dispatch", stage, cycle, prompt, token, ... }` — caller
   should dispatch a subagent. The `prompt` field is augmented with cycle
   memory context (entity types, edge types, extractor briefs) when configured.
+- `{ action: "dispatch_multi", tasks: [...], ... }` — caller should
+  dispatch multiple subagents in parallel (used for parallel appraiser dispatch).
 - `{ action: "human_appraise", ... }` — surface to the user.
 - `{ action: "done", ... }` — cycle complete.
 - `{ action: "blocked", ... }` — cycle stalled.
@@ -261,6 +268,8 @@ failed flow.
 **Side effects:** mints/persists dispatch tokens (in-memory pending
 store); commits via `commitWithPolicy` when finalising stages (refuses
 on unexpected files); appends WORK.md artefact rows when finalising.
+Runs quench synchronously when laws contain validators; runs appraise
+via `gatherAppraiseContext` + `consolidateAppraise`.
 
 ### `foundry_workfile_create`
 
@@ -325,7 +334,7 @@ flow** (escape hatch).
 
 ### `foundry_artefacts_list`
 
-> List artefact changes on the current work branch for the current cycle.
+> List artefact changes on the current work branch for the current cycle. Artefacts are discovered from branch diff status (git diff against base branch), filtered by the current cycle's output-type file patterns.
 
 **Args:**
 - none.
@@ -359,7 +368,7 @@ existing equivalent item was returned). `{ error: ... }` otherwise.
 **Stage requirements:** requires active stage. Tag is gated by stage
 base:
 - `forge` → forbidden (forge stages do not add feedback).
-- `quench` → tag must be exactly `validation`.
+- `quench` → tag must start with `law:`.
 - `appraise` → tag must start with `law:`.
 - `human-appraise` → tag must be exactly `human`.
 - `assay` → forbidden. Extractor failures mark the workfile failed and end
@@ -542,7 +551,8 @@ that id is registered.
 `file-patterns`.
 
 **Stage requirements:** none (callable outside any stage; intended to be
-invoked by quench, but not enforced). Refused on a failed flow.
+invoked by quench, but not enforced). Requires a `work/*` or `dry-run/*`
+branch (flow-data mutation namespace). Refused on a failed flow.
 
 **Side effects:** spawns subprocesses via `execSync` in the worktree —
 external commands may have arbitrary side effects, which is why the tool
@@ -654,11 +664,13 @@ can branch away to recover.
 | current branch       | mode      | what happens                                                                                                                              |
 | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `work/<x>`                 | work      | commits `WORK.*` cleanup on the work branch, preserves the branch as `archive/work/<x>-<hash>`, squash-merges to `baseBranch`, creates a signed commit whose message embeds the canonical Foundry attestation block. |
-| `config/<x>`               | config    | squash-merges to `baseBranch`, force-deletes the config branch. No WORK cleanup.                                                          |
+| `config/<x>`               | config    | squash-merges to `baseBranch`, force-deletes the config branch. No WORK cleanup. |
 | `dry-run/<x>/<y>`          | dry-run   | writes `.snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}` on the parent `config/<x>` working tree; force-deletes the dry-run branch. No merge, no commit. |
 | base branch (`main` by default) | noop | `{ ok: true, noop: true, ... }`.                                                                                                           |
 | anything else              | refused   | `{ ok: false, error: "... nothing to finish ..." }`.                                                                                      |
 
+**Work-branch precondition (work mode):** `ATTEST.md` must exist at HEAD, created by a prior `foundry_attest({ confirm: true })` call. Without it, the work mode refuses.
+
 **Returns:**
 - Plan (when `confirm` is not true):
   - Work mode: `{ ok: false, error: "... requires {confirm: true}...",
@@ -789,8 +801,7 @@ schema checks without writing. Laws use a different shape: `add_law`
 creates a new entry, `edit_law` updates an existing one, and
 `foundry_config_validate_law` covers schema validation for either.
 
-Common args across the `_create_*` tools: `name` (string), `body`
-(string, markdown). Common returns across the whole family:
+Common returns across the whole family:
 `{ ok: true, path, sha }` on success; `{ ok: false, errors: [...] }`
 on validation failure; `{ error, affected_files: [...] }` on
 commit-policy refusal (the worktree was dirty with files outside
@@ -805,9 +816,11 @@ to update an existing law in place.
 > `foundry/artefacts/<typeId>/`.
 
 **Args:**
-- `name` (string, required): typeId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`file-patterns`, optional `description`, etc.).
+- `id` (string, required): Artefact type id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `filePatterns` (string[], required): Glob patterns for matching artefacts.
+- `description` (string, required): Prose description of the artefact type.
+- `appraisers` (object, optional): `{ allowed: string[], count: number }` — appraiser pool and selection count.
 
 **Returns:** `{ ok: true, path, sha }` on success;
 `{ ok: false, errors: [...] }` on schema failure;
@@ -832,49 +845,53 @@ current `config/*` branch.
 
 ### `foundry_config_add_law`
 
-> Add a new law markdown entry. Locator depends on `target.kind`.
+> Add a new law entry.
 
 **Args:**
-- `name` (string, required): law id (kebab-case slug). Used in the
-  commit message.
-- `body` (string, required): markdown body for the law, starting with
-  a `## <law-id>` heading.
-- `target` (object, required):
-  - `{ kind: "global", file: "<name>.md" }` — appends or writes
-    `foundry/laws/<file>`.
-  - `{ kind: "type-specific", typeId: "<id>" }` — appends or writes
-    `foundry/artefacts/<typeId>/laws.md`.
-
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
-
-**Failure modes:** as for `foundry_config_create_artefact_type`, plus
-`target` shape errors:
-- Missing or non-object `target` → `{ ok: false, errors: ["target
-  argument is required (object with kind + locator)"] }`.
-- Unknown `target.kind` → `{ ok: false, errors: ["unknown
-  target.kind: <kind>"] }`.
-- Missing `target.file` for `global` / missing `target.typeId` for
-  `type-specific` → `{ ok: false, errors: [...] }`.
-- Target file already exists →
-  `{ ok: false, errors: ["… already exists; use foundry_config_edit_law
-  to update an existing law in place"] }`.
+- `id` (string, required): Law id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `description` (string, required): Prose description of the law.
+- `passing` (string, required): Feedback text when the law passes.
+- `failing` (string, required): Feedback text when the law fails.
+- `target` (object, required): `{ kind: "global"|"type-specific", file?: string, typeId?: string }` — locator for the law target.
+- `validators` (array, optional): Array of `{ name: string, command: string }` objects defining validator commands.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on validation failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
+
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure → `{ ok: false, errors: [...] }`.
+- Target file already exists → `{ ok: false, errors: ["… already
+  exists; use foundry_config_edit_law to update an existing law in place"] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
+
+**Side effects:** writes the law file and commits it on the current
+`config/*` branch.
 
 ### `foundry_config_edit_law`
 
-> Replace the body of an existing law in place, preserving sibling
-> laws in the same file. Locates the law by id across both global laws
-> and per-type `laws.md` files.
+> Update an existing law's fields in place. Locates the law by id across
+> both global laws and per-type `laws.md` files.
 
 **Args:**
-- `id` (string, required): law id to edit.
-- `body` (string, required): full new markdown body for the law,
-  starting with a `## <law-id>` heading.
+- `id` (string, required): Law id to edit.
+- `name` (string, optional): New human-readable name.
+- `description` (string, optional): New prose description.
+- `passing` (string, optional): New passing feedback text.
+- `failing` (string, optional): New failing feedback text.
+- `validators` (array, optional): New validator list replacing the current one.
 
 **Returns:** `{ ok: true, id, path, source }` on success, where
 `source` is `"global"` or `"type:<typeId>"`. Returns
 `{ ok: false, errors: ["Law \"<id>\" not found"] }` when no law of
-that id exists, or `{ ok: false, errors: [...] }` when the new body
+that id exists, or `{ ok: false, errors: [...] }` when the update
 fails law schema validation.
 
 **Stage requirements:** none (no active stage); requires a `config/*`
@@ -888,48 +905,92 @@ the current `config/*` branch with message `config: edit law <id>`.
 > Create a new appraiser personality at `foundry/appraisers/<id>.md`.
 
 **Args:**
-- `name` (string, required): appraiser id.
-- `body` (string, required): markdown body with frontmatter
-  (`description`, optional `model`, …).
+- `id` (string, required): Appraiser id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `description` (string, required): Prose description of the appraiser's role.
+- `model` (string, optional): Model override for this appraiser.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
+
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure (missing description, semantic overlap
+  with an existing appraiser, …) → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the appraiser schema (missing description, semantic overlap
-with an existing appraiser, …).
+**Side effects:** writes the appraiser file and commits it on the
+current `config/*` branch.
 
 ### `foundry_config_create_flow`
 
 > Create a new flow definition under `foundry/flows/<flowId>/`.
 
 **Args:**
-- `name` (string, required): flowId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`description`, `cycles: [...]`).
+- `id` (string, required): Flow id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `startingCycles` (string[], required): Ordered list of cycle ids for this flow.
+- `description` (string, required): Prose description of the flow.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the flow schema.
+**Side effects:** writes the flow file and commits it on the
+current `config/*` branch.
 
 ### `foundry_config_create_cycle`
 
 > Create a new cycle markdown file under `foundry/cycles/<cycleId>.md`.
 
 **Args:**
-- `name` (string, required): cycleId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`flowId`, `output`, optional `inputs`, `memory`, `models`, …).
+- `id` (string, required): Cycle id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `outputType` (string, required): Artefact type id for this cycle's output.
+- `inputs` (object, optional): `{ type: "any-of"|"all-of", artefacts: string[] }` — input filtering rules.
+- `targets` (string[], optional): Target artefact file paths.
+- `alwaysHumanAppraise` (boolean, optional): Force human appraisal on every run.
+- `deadlockHumanAppraise` (boolean, optional): Fall back to human appraisal on deadlock.
+- `maxIterations` (number, optional): Maximum forge-quench-appraise iterations.
+- `assay` (object, optional): `{ extractors: string[] }` — extractors to run in the assay stage.
+- `memory` (object, optional): `{ read: string[], write: string[] }` — memory permissions.
+- `models` (object, optional): Per-stage model overrides.
+- `description` (string, optional): Prose description of the cycle.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure (unknown `outputType`, unknown
+  `memory.read` / `memory.write` types, unknown referenced appraisers,
+  …) → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the cycle schema (unknown `output` artefact-type, unknown
-`memory.read` / `memory.write` types, unknown referenced appraisers,
-…).
+**Side effects:** writes the cycle file and commits it on the
+current `config/*` branch.
 
 ---
 
@@ -1181,7 +1242,7 @@ read-disallowed.
 
 **Args:**
 - `type`, `name` (string, required).
-- `depth` (number, optional, default 1).
+- `depth` (number, optional, default 1, maximum 5).
 - `edge_types` (string[], optional): Restrict traversal to named edges;
   defaults to all known edges.
 
@@ -1211,7 +1272,7 @@ cycle cannot read; query contains a forbidden keyword.
 
 **Args:**
 - `query_text` (string, required).
-- `k` (number, optional, default 5).
+- `k` (number, optional, default 5, maximum 100).
 - `type_filter` (string[], optional): default = all readable entity
   types.