@really-knows-ai/foundry 2.3.2 → 3.0.0

package/CHANGELOG.md

@@ -1,100 +0,0 @@
-# Changelog
-
-## 2.3.2 — 2026-04-21
-
-### Changed
-
-- Config-modifying skills (`add-flow`, `add-cycle`, `add-law`, `add-appraiser`, `add-artefact-type`) now refuse to run on a work branch. They require the current branch to not start with `work/`, directing the user to complete or discard the in-flight flow before changing foundry configuration. Structural changes belong on the base branch, not alongside transient flow state.
-
-### Removed
-
-- Historical planning docs (`docs/plans/`, `docs/specs/`, `docs/superpowers/`) and `HARDEN.md`. All described features that shipped in v2.2.0–v2.3.1; git history preserves the full record.
-
-## 2.3.1 — 2026-04-20
-
-### Changed
-
-- `flow` skill: any cycle in a flow may now be the starting cycle (previously limited to `starting-cycles`). The list becomes a hint for ambiguous requests. A cycle whose `inputs` contract cannot be satisfied from files on disk is not eligible to start.
-- `flow` skill: between-cycles logic no longer implies any carry-over ceremony. The next cycle's forge discovers the previous cycle's output via filesystem scan against its input types' `file-patterns`.
-- `forge` skill: input discovery now explicitly uses filesystem scan against each input type's `file-patterns`, with the goal guiding which candidates are relevant.
-- `forge` skill: the write invariant is restated accurately — forge may only write to files matching the output artefact type's `file-patterns` (plus the tool-managed files). All other files on disk are read-only. The previous "inputs are read-only" framing was a special case of this rule.
-
-### Notes
-
-- No tool, schema, or enforcement changes. Existing flows continue to work. `sort.js`'s `checkModifiedFiles` already enforces the write invariant.
-
-## 2.3.0 — 2026-04-20
-
-### Breaking
-
-- **LLM orchestration replaced with deterministic `foundry_orchestrate` tool.** The `cycle` and `sort` skills are removed; replaced by a single thin `orchestrate` skill that drives a 3-line loop.
-- **Six tools deregistered** from the plugin (still exist as internal imports for tests): `foundry_sort`, `foundry_history_append`, `foundry_stage_finalize`, `foundry_git_commit`, `foundry_workfile_configure_from_cycle`, `foundry_workfile_set`.
-- Upgrade requires clean main + no in-flight workfile (see `upgrade-foundry` skill).
-
-### Added
-
-- `foundry_orchestrate` — single tool that owns the sort → history → dispatch → finalize → history → commit loop. Atomic stage completion.
-- `scripts/orchestrate.js` — deterministic orchestration logic, composes existing internal functions.
-- Orphaned-stage detection: if orchestrate is called without `lastResult` but an active stage exists, returns `violation`. Fixes the ses_256c failure mode where an LLM skipped the post-dispatch history append and wedged the cycle.
-
-### Fixed
-
-- Root cause of all deferred HARDEN.md bugs (B, C, D, E, G) and the ses_256c bug: LLM misfollowing a deterministic protocol. Protocol now lives inside the plugin tool.
-
-### Migration
-
-See `skills/upgrade-foundry/SKILL.md` for v2.3.0 pre-flight checks. No automated state migration — complete or discard in-flight cycles on v2.2.x before upgrading.
-
-## 2.2.1 — 2026-04-20
-
-Follow-up patch addressing the five bugs deferred from v2.2.0 (see `HARDEN.md` §Deferred).
-
-### Breaking changes
-
-- **Cycle-definition deadlock config flattened.** The nested `human-appraise: {enabled, deadlock-threshold}` block is replaced by three flat keys:
-  - `human-appraise: <bool>` (default `false`) — include `human-appraise` in the stage loop every iteration
-  - `deadlock-appraise: <bool>` (default `true`) — route to `human-appraise` when LLM appraisers deadlock
-  - `deadlock-iterations: <number>` (default `5`) — deadlock threshold
-  Run the `upgrade-foundry` skill to migrate existing cycle defs — the old nested form is no longer read.
-
-### New
-
-- **`foundry_workfile_configure_from_cycle({cycleId, stages})`** — populates WORK.md frontmatter from a cycle definition in one call. Replaces the prior 6–7 sequential `foundry_workfile_set` calls at cycle start. Defaults for `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, and `models` now live in plugin code rather than skill prose.
-- **`foundry_artefacts_list({cycle})`** — optional cycle filter. Callers should always pass the current cycle to avoid picking up stale rows from prior aborted sessions.
-
-### Fixed
-
-- **Bug B — deadlock routing.** Sort now reads the flat deadlock keys from WORK.md frontmatter and routes to `human-appraise` on deadlock (either an existing `human-appraise:<cycle>` stage in `stages`, or a synthesized one). When `deadlock-appraise: false`, deadlock marks the cycle `blocked`.
-- **Bug C — stale artefact validation.** `quench`, `appraise`, and `human-appraise` skills now pass the current cycle to `foundry_artefacts_list`, scoping validation to artefacts produced by the current cycle instead of every row that has ever landed in WORK.md.
-- **Bug D — overwriting WORK.md.** The `flow` skill now calls `foundry_workfile_get` before `foundry_workfile_create` and prompts the user to resume, discard, or abort when an existing workfile is detected. Silent overwrite is not offered; resume requires matching `flow` and `cycle`.
-- **Bug E — missing micro-commits.** `foundry_sort` now returns `{route: 'violation'}` when `WORK.md`, `WORK.history.yaml`, or anything under `.foundry/` has uncommitted changes at the start of a sort call and history is non-empty. Structurally enforces the one-commit-per-stage contract that previously lived only in skill prose. First sort of a cycle is exempt (empty history).
-- **Bug G — workfile setup boilerplate.** See `foundry_workfile_configure_from_cycle` above.
-
-### Migration
-
-Run the `upgrade-foundry` skill to migrate cycle definitions to the flat deadlock keys (Bug B). No other migration required — WORK.md, `.foundry/`, and feedback state are forward-compatible.
-
-## 2.2.0 — 2026-04-19
-
-### Breaking changes
-
-- **`foundry_artefacts_add` removed.** Artefact registration now happens exclusively via `foundry_stage_finalize` after a forge stage closes.
-- **`foundry_artefacts_set_status` no longer accepts `draft`.** Only `done` and `blocked` are valid. New artefacts are registered as `draft` automatically by `stage_finalize`.
-- **Feedback / artefact / workfile mutation tools now enforce stage-lock preconditions.** Tools callable by subagents require an active stage matching their role; tools callable by the orchestrator require no active stage. Out-of-band calls return a structured error instead of mutating state.
-- **Feedback state machine strictly enforced.** `approved` is terminal. `quench` cannot approve/reject `wont-fix` items. See `HARDEN.md` §4 for the full matrix.
-- **`foundry_sort` dispatchable routes now return a `token` field.** Subagents must redeem the token via `foundry_stage_begin`; forged or replayed tokens are rejected.
-
-### New
-
-- **`foundry_stage_begin(stage, cycle, token)`** — subagents open a work stage by consuming a single-use HMAC-signed token.
-- **`foundry_stage_end(summary)`** — subagents close a stage; preserves `baseSha` for finalize.
-- **`foundry_stage_finalize(cycle)`** — orchestrator verifies stage output against allowed file patterns, registers matching files as draft artefacts, rejects stray writes with `{error: "unexpected_files", files: [...]}`.
-- **`.foundry/` state directory** (gitignored) — holds `.secret` (per-worktree HMAC key, mode 0600), `active-stage.json` (present only during an active stage), `last-stage.json` (for finalize lookup).
-
-### Fixed
-
-- Normalized `maxIterations` → `max-iterations` across workfile read/write paths (previously inconsistent between flow and cycle skills, causing latent deadlock-detection issues).
-
-### Migration
-
-Upgrade with the `upgrade-foundry` skill. `.foundry/` is created automatically on first plugin boot; `.secret` is generated idempotently. No data migration required — existing `WORK.md` and `foundry/*` configs are compatible.

package/docs/concepts.md

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

package/docs/getting-started.md

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

package/docs/work-spec.md

@@ -1,207 +0,0 @@
-# WORK.md Spec
-
-WORK.md is created at the start of a foundry flow on a work branch. It is the shared state between all stages in all foundry cycles. It is transient — it exists only for the duration of the foundry flow.
-
-## Frontmatter
-
-```yaml
----
-flow: <flow-id>
-cycle: <current-cycle-id>
-stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
-max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
-models:
-  forge: anthropic/claude-opus-4.7
-  appraise: openai/gpt-5
----
-```
-
-Fields:
-- `flow` — the foundry flow being executed.
-- `cycle` — the current cycle id.
-- `stages` — the ordered route for this cycle. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, or `human-appraise`) and `alias` is a human-readable name for what that stage does in this cycle. Derived from the cycle and artefact type: `forge` + `appraise` are always included, `quench` is included iff the artefact type has `validation.md`, `human-appraise` is included iff the cycle sets `human-appraise: true`.
-- `max-iterations` — how many forge passes before the cycle is blocked (default: 3).
-- `human-appraise` — run human-appraise every iteration (default: `false`).
-- `deadlock-appraise` — route to human-appraise when LLM appraisers deadlock (default: `true`).
-- `deadlock-iterations` — deadlock threshold (default: 5).
-- `models` — optional per-stage model overrides; individual appraisers may further override via their own `model` field.
-
-The `stages` list is the happy path. Sort follows it but loops back to `forge` when unresolved feedback demands it, and inserts a `human-appraise` stage on deadlock.
-
-### Who sets what
-
-- `flow`, `cycle`, `goal` — set by the `flow` skill via `foundry_workfile_create` at flow/cycle boundaries.
-- `stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models` — set by `foundry_orchestrate` on the first call of each cycle (via internal `workfile_configure_from_cycle`, reading the cycle definition).
-
-## Sections
-
-### Goal
-
-Free text describing what the foundry flow is producing and any context the human provided. Written once at foundry flow start, not modified after.
-
-### Artefacts
-
-A table tracking every artefact produced by the foundry flow.
-
-```markdown
-# Artefacts
-
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/login-change.md | petition | write-petition | draft |
-| features/login-change.feature | gherkin | petition-to-gherkin | draft |
-```
-
-Statuses:
-- `draft` — artefact exists but has not cleared all stages
-- `done` — artefact has cleared all stages
-- `blocked` — artefact hit iteration limit or a violation
-
-### Feedback
-
-Grouped by artefact file path. Each item is a checklist entry with a tag indicating its source.
-
-```markdown
-# Feedback
-
-## petitions/login-change.md
-
-- [ ] Missing "Acceptance Criteria" section #validation
-- [x] Justification is circular #law:justified-change | approved
-- [~] Could be more concise #law:clear-language | wont-fix: brevity would lose necessary context | approved
-```
-
-#### Tags
-
-- `#validation` — from a deterministic quench command
-- `#law:<law-id>` — from subjective appraise, tied to a specific law
-- `#human` — from human-provided feedback at a human-appraise checkpoint
-
-#### Lifecycle states
-
-```
-- [ ] issue #tag                                    open, needs forge action
-- [x] issue #tag                                    actioned, needs approval
-- [~] issue #tag | wont-fix: <reason>               declined by forge, needs approval (appraise only)
-- [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
-```
-
-#### Rules
-
-- Validation feedback (`#validation`) cannot be wont-fixed — deterministic rules are not negotiable.
-- Human feedback (`#human`) cannot be wont-fixed — it takes absolute priority over LLM feedback.
-- Feedback is never deleted — it stays as a record of the iteration history.
-- New feedback is appended, not inserted.
-- Items are grouped under the artefact they relate to.
-
-## Who writes what
-
-| Section | Written by | Updated by |
-|---------|-----------|------------|
-| Frontmatter (`flow`, `cycle`, `goal`) | `foundry_workfile_create` (flow skill) | `foundry_workfile_delete` + re-create between cycles |
-| Frontmatter (`stages`, `max-iterations`, `human-appraise`, `deadlock-appraise`, `deadlock-iterations`, `models`) | `foundry_orchestrate` (first call of each cycle, internally) | reset on each new cycle |
-| Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | `foundry_stage_finalize` (orchestrator, after forge closes) | `foundry_artefacts_set_status` (orchestrator → `done`/`blocked`) |
-| Feedback | `foundry_feedback_add` (quench / appraise / human-appraise) | `foundry_feedback_action` / `foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench / appraise / human-appraise) |
-
-Note: `foundry_artefacts_add` no longer exists as a public tool — artefact registration is automatic via `stage_finalize`, which scans the git diff and registers files matching the output type's `file-patterns` as `draft`.
-
-## WORK.history.yaml
-
-A separate file (`WORK.history.yaml`) alongside WORK.md. Append-only log of every stage execution.
-
-```yaml
-- timestamp: "2026-04-17T14:32:01Z"
-  cycle: write-petition
-  stage: forge:draft-petition
-  iteration: 1
-  comment: Initial petition draft created
-
-- timestamp: "2026-04-17T14:32:45Z"
-  cycle: write-petition
-  stage: quench:validate-petition
-  iteration: 1
-  comment: 2 validation issues found
-
-- timestamp: "2026-04-17T14:33:12Z"
-  cycle: write-petition
-  stage: forge:draft-petition
-  iteration: 2
-  comment: Addressed 2 validation issues
-
-- timestamp: "2026-04-17T14:33:30Z"
-  cycle: write-petition
-  stage: quench:validate-petition
-  iteration: 2
-  comment: Validation passed
-
-- timestamp: "2026-04-17T14:34:00Z"
-  cycle: write-petition
-  stage: appraise:review-petition
-  iteration: 2
-  comment: No issues found, cycle complete
-```
-
-### Fields
-
-- `timestamp` — ISO 8601 UTC
-- `cycle` — which foundry cycle this entry belongs to
-- `stage` — which stage just completed, in `base:alias` format (e.g. `forge:draft-petition`, `quench:validate-petition`, `appraise:review-petition`, `human-appraise:human-review`)
-- `iteration` — the current iteration number (increments each time forge runs within a cycle)
-- `comment` — brief description of what happened
-
-### Rules
-
-- Append-only — never edit or delete entries.
-- Every stage produces an entry when it completes.
-- Sort reads this to determine what has happened in the current cycle.
-- Iteration is derived from counting forge entries for the current cycle.
-
-### Who writes
-
-History entries are written by `foundry_orchestrate` after each stage closes (via its internal `foundry_history_append` — the tool is not registered publicly). Sub-agents never append history directly.
-
-## Example
-
-A complete WORK.md mid-foundry flow:
-
-```markdown
----
-flow: make-haiku
-cycle: haiku-creation
-stages: [forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]
-max-iterations: 3
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
----
-
-# Goal
-
-Write a haiku about autumn rain. Should evoke loneliness
-and the sound of rain on leaves.
-
-# Artefacts
-
-| File | Type | Cycle | Status |
-|------|------|-------|--------|
-| petitions/autumn-rain-haiku.md | petition | haiku-ideation | done |
-| haiku/autumn-rain.md | haiku | haiku-creation | draft |
-
-# Feedback
-
-## petitions/autumn-rain-haiku.md
-
-- [x] Acceptance criteria should mention seasonal reference #law:clear-acceptance-criteria | approved
-
-## haiku/autumn-rain.md
-
-- [ ] Line 2 has 8 syllables, expected 7 #validation
-- [x] No seasonal reference detected #law:seasonal-reference | approved
-```