@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/CHANGELOG.md

@@ -0,0 +1,490 @@
+# Changelog
+
+## [3.0.0] - 2026-05-10
+
+A consolidation release covering every change since v2.4.2. Foundry 3.0.0
+restructures the branch model into three explicit kinds (`config/*`,
+`work/*`, `dry-run/*/*`), introduces deterministic attestation, replaces
+the markdown-parsed feedback section with a typed YAML store, adds the
+assay pre-forge stage and the flow-memory subsystem, unifies law
+authoring around a JSONL-validator model, and adds a verbose tracing /
+forensic-snapshot loop for dry-runs. The work was developed across what
+were originally numbered as 2.5.0, 2.6.0, 2.7.0, and 3.0.0 internal
+milestones; only 3.0.0 is being released. Where an intermediate
+milestone introduced a feature and a later milestone modified it, this
+entry documents the 3.0.0 end-state only.
+
+### Branch-model breaking changes
+
+- **`foundry_git_branch` requires explicit `kind`.** The previous
+  `{ flowId, description }` signature is removed. Callers must now pass
+  `kind: 'config' | 'work' | 'dry-run'`. Per-kind requirements:
+  `kind: 'config'` needs `description` and a non-`config/*`,
+  non-`work/*` starting branch; `kind: 'work'` needs `flowId`,
+  `description`, and a non-`config/*`, non-`work/*` starting branch;
+  `kind: 'dry-run'` needs `flowId`, `description`, and the operator
+  must already be on a `config/<x>` branch. `flowId` is invalid for
+  `kind: 'config'`.
+- **`foundry_git_finish` dispatches on the current branch prefix.**
+  `work/<x>` retains existing semantics (squash-merge plus WORK
+  cleanup); `config/<x>` is new (squash-merge, no WORK cleanup);
+  `dry-run/<x>/<y>` writes a forensic snapshot under `.snapshots/`
+  on the parent `config/<x>` working tree and force-deletes the
+  dry-run branch (see "Dry-run finish writes a forensic snapshot"
+  below). Any other branch is refused with "nothing to finish".
+  `baseBranch` is rejected for dry-run finish (the parent config
+  branch is encoded in the dry-run branch name).
+- **Dry-run namespace is `dry-run/<parent>/<flowId>-<desc>`, not
+  nested under `config/<parent>`.** Originally specified as
+  `config/<x>/dry-run/<y>`; git refuses to coexist a parent ref with
+  a child-prefixed ref, so the namespace is a flat sibling instead.
+- **Schema/config mutation now requires a `config/*` branch.**
+  Affected tools: `foundry_config_create_artefact_type`,
+  `_create_appraiser`, `_create_flow`, `_create_cycle`,
+  `foundry_config_add_law`, `foundry_config_edit_law`,
+  `foundry_memory_create_entity_type` / `_create_edge_type` /
+  `_rename_entity_type` / `_rename_edge_type` / `_drop_entity_type` /
+  `_drop_edge_type`, `foundry_extractor_create`, `foundry_memory_init`,
+  `foundry_memory_reset`, `foundry_memory_change_embedding_model`. All
+  refuse on any branch other than `config/<description>`.
+- **Flow-data mutation now requires a `work/*` or `dry-run/*/*`
+  branch.** Affected tools: `foundry_orchestrate`,
+  `foundry_workfile_create` / `_delete`, `foundry_artefacts_set_status`,
+  `foundry_feedback_*` (mutating variants), `foundry_assay_run`,
+  `foundry_validate_run`, `foundry_appraisers_select`,
+  `foundry_stage_begin` / `_end` / `_retry`, `foundry_memory_put` /
+  `_relate` / `_unrelate`.
+
+### Attestation, dry-run, and snapshot breaking changes
+
+- **`foundry_git_finish` on `work/*` refuses without ATTEST.md at HEAD.**
+  Work-branch merges are gated on a deterministic attestation commit
+  produced by `foundry_attest`. Operators must run `foundry_attest`
+  with `confirm: true` before finishing a work branch.
+- **Dry-run finish writes a forensic snapshot.** `foundry_git_finish`
+  on a `dry-run/<x>/<y>` branch writes `.snapshots/<run-id>/` on the
+  parent `config/<x>` working tree (containing `README.md`,
+  `work/WORK*`, `diff.patch`, `trace.jsonl`) and force-deletes the
+  dry-run branch. No merge, no commit.
+- **`.snapshots/` is a new gitignored top-level directory.** It
+  appears in projects only after the first dry-run finish. Snapshots
+  are local operator artefacts and never committed by foundry.
+- **Verbose tool-call tracing on dry-run branches.** Every `foundry_*`
+  tool call (except `foundry_orchestrate`, which uses inline guards)
+  appends a JSONL record to `.foundry/trace/<branch-slug>.jsonl` while
+  on a dry-run branch. The trace is truncated when the dry-run branch
+  is created and copied into the snapshot at finish.
+
+### Feedback and state-machine breaking changes
+
+- **Feedback storage moved from markdown to YAML.** The `## Feedback`
+  section in `WORK.md` is removed. Feedback items now live in
+  `WORK.feedback.yaml` with full transition history per item. Any
+  legacy `## Feedback` content in an old `WORK.md` is inert text:
+  not parsed, not deleted, not written to.
+- **Feedback tools switch from `{ file, index }` to `{ id }`
+  addressing.** `foundry_feedback_add` drops the `stageBase?`
+  argument (source is read from the active stage).
+  `foundry_feedback_list` response shape is now
+  `{ id, file, tag, text, source, state, depth, reason? }`. Item ids
+  are ULIDs.
+- **Feedback state machine expands from 4 states to 6:** `open |
+  actioned | wont-fix | rejected | deadlocked | resolved`. `approved`
+  is renamed to `resolved` internally; the public resolve tool still
+  accepts `resolution: 'approved' | 'rejected'` as input.
+- **Deadlock detection is per-item.** Each item's depth in its own
+  transition history is checked against `deadlock-iterations`. Items
+  freshly added in the threshold-th iteration are never auto-deadlocked.
+- **Source-authorship rule.** Only the stage that created a feedback
+  item can resolve or reject it. `human-appraise` has universal
+  override authority — it may transition any non-resolved item to any
+  legal target state regardless of source.
+- **Assay rejected as a feedback source.** `foundry_feedback_add`
+  and `WORK.feedback.yaml` refuse `source: 'assay'`. Assay failures
+  surface as a hard flow failure (see Assay breaking changes below).
+
+### Cycle and artefact-type breaking changes
+
+- **Cycle frontmatter key renamed: `output:` → `output-type:`.** The
+  orchestrator no longer reads `output:`. Cycle definitions in
+  `foundry/flows/*/cycles/*.md` must use `output-type:` to declare
+  the artefact-type id the cycle produces. Unmigrated cycles yield a
+  hard violation pointing to the upgrade skill.
+- **Artefact-type frontmatter `output:` is removed.** The field had
+  zero runtime consumers — forge's write scope is governed by
+  `file-patterns`, and `file-patterns` legitimately spans multiple
+  directories, so a single `output:` (or earlier-proposed
+  `output-dir:`) could not honestly describe artefact location.
+  Stale `output:` entries are harmless but should be deleted.
+
+### Assay and memory breaking changes
+
+- **Assay extractor failure marks the workfile failed.** When an
+  extractor exits non-zero, parses incorrectly, violates permissions,
+  or times out, `foundry_assay_run` calls `markWorkfileFailed` and
+  returns `{flow_failed: true, error, …}`. It does not file a
+  `#validation` feedback item. Rationale: the failure cause (a
+  project-authored script under `foundry/memory/extractors/`) lives
+  outside any artefact's `file-patterns`, so forge has no way to act
+  on assay-sourced feedback; the prior behaviour produced
+  unsatisfiable state-machine items. Tooling that pattern-matched
+  assay-sourced feedback must instead detect `flow_failed: true` on
+  the assay-run response.
+- **Memory NDJSON relations moved to `foundry-memory/relations/`.**
+  Per-type row data (`<entity-type>.ndjson`, `<edge-type>.ndjson`)
+  lives at the top-level `foundry-memory/relations/` directory,
+  sibling to `foundry/`. The rest of the memory tree (`config.md`,
+  `schema.json`, `entities/`, `edges/`, `extractors/`, the gitignored
+  `memory.db*` runtime files) stays under `foundry/memory/`.
+  Rationale: the relations directory is large, frequently rewritten,
+  and benefits from being separable from the human-authored config.
+
+### Law model breaking changes
+
+- **Quench executes law-defined JSONL validators.** Each law in
+  `foundry/laws/*.md` or `foundry/artefacts/<typeId>/laws.md` declares
+  one or more validator commands in a fenced code block.
+  `foundry_validate_run` executes them, parses their JSONL output, and
+  returns per-item feedback (`{ lawId, validatorId, file, text,
+  location?, severity? }`). The quench skill emits one
+  `foundry_feedback_add` call per item tagged
+  `law:<lawId>:<validatorId>`. Items whose `file` falls outside the
+  artefact type's `file-patterns` are surfaced as `pattern-mismatch`
+  errors rather than silently swallowed.
+- **Law authoring split into `add` and `edit`.** There is no
+  `foundry_config_create_law`; use `foundry_config_add_law` for new
+  laws and `foundry_config_edit_law` to replace an existing law in
+  place. `foundry_config_read_law` returns the full markdown for a
+  single law by id, and `foundry_config_validate_law` runs schema
+  validation against a candidate body without writing.
+
+### Added
+
+- **`foundry_attest`, `foundry_attestation_show`,
+  `foundry_attestation_verify`.** Deterministic attestation
+  primitives. `foundry_attest` verifies the current work cycle is
+  complete (all required stages ran, no unresolved feedback, no
+  blocked artefacts), writes a canonical-JSON ATTEST.md payload
+  (cycle id, diff sha, stages, attestation tools, models), and
+  commits it to the work branch. `foundry_attestation_show` and
+  `_verify` read and re-verify an attestation after the fact. Takes
+  `baseBranch` (optional, default `main`), `message` (required goal
+  text), and `confirm` (must be `true` to write).
+- **`foundry_stage_retry` tool.** Re-runs the last failed stage on a
+  failed workfile without abandoning the cycle. Requires the
+  workfile to be in `status: failed` and the cause to be transient
+  (network, model error). Restores the active-stage token and clears
+  the failed marker.
+- **`foundry_config_create_*` tools** for the four kinds with a
+  single-file canonical layout (artefact-type, appraiser, flow,
+  cycle). Each produces one git commit per invocation on the current
+  `config/*` branch. Updates (replacing an existing file) are not
+  exposed as MCP tools for these kinds; operators edit by hand on
+  the current `config/*` branch.
+- **`foundry_config_validate_*` tools** for all five config kinds
+  (artefact-type, law, appraiser, flow, cycle). Schema-only, no
+  branch guard, callable from any branch. Authors iterate on a draft
+  body, then call the corresponding `_create_*` or `_add_law` /
+  `_edit_law` to commit.
+- **`foundry_config_read_law` tool.** Reads a single law by id,
+  returning its full markdown including the validators block. No
+  branch guard.
+- **`foundry_snapshot_*` tools.** `foundry_snapshot_list`, `_show`,
+  `_delete`, `_prune` — programmatic inspection and cleanup of
+  dry-run forensic snapshots. Allowed on every branch.
+- **Assay stage.** A deterministic pre-forge stage that runs
+  project-authored extractor scripts to populate flow memory before
+  forge starts. Opt-in per cycle via `assay: { extractors: [...] }`
+  in cycle frontmatter. Iteration-0-only. See
+  [docs/concepts.md](docs/concepts.md#assay).
+- **`foundry_assay_run` and `foundry_extractor_create` plugin tools.**
+  `foundry_assay_run` executes the extractors declared by the active
+  assay stage. `foundry_extractor_create` registers a new extractor
+  definition at `foundry/memory/extractors/<name>.md`.
+- **`add-extractor` skill.** Authoring loop for extractor definitions.
+- **Flow memory subsystem.** A typed, graph-shaped knowledge store
+  that persists across cycles. Entity types, edge types, and their
+  prose briefs live in `foundry/memory/`; row data is committed as
+  NDJSON under `foundry-memory/relations/`; the live database
+  (`foundry/memory/memory.db*`) is gitignored and rebuilt on demand
+  from the NDJSON files. Each cycle declares read/write permissions
+  in its frontmatter (`memory: { read: [...], write: [...] }`). The
+  dispatched stage prompt is augmented with a vocabulary block
+  listing the entity/edge types and memory tools visible to that
+  cycle.
+- **20 memory tools.** `foundry_memory_{put,relate,unrelate,get,list,
+  neighbours,query,search}` for read/write,
+  `foundry_memory_{create,rename,drop}_{entity,edge}_type` for
+  vocabulary management, `foundry_memory_{init,validate,reset,dump,
+  vacuum,change_embedding_model}` for admin. Destructive operations
+  (`_drop_*`) take an optional `confirm` — without it they return a
+  preview of affected rows.
+- **9 memory authoring skills.** `init-memory`,
+  `add-memory-entity-type`, `add-memory-edge-type`,
+  `rename-memory-entity-type`, `rename-memory-edge-type`,
+  `drop-memory-entity-type`, `drop-memory-edge-type`, `reset-memory`,
+  `change-embedding-model`.
+- **Optional semantic search.** When `embeddings.enabled` is true in
+  `foundry/memory/config.md`, entities are embedded on write against
+  an OpenAI-compatible endpoint (default: local Ollama
+  `nomic-embed-text`, 768 dims) and exposed via
+  `foundry_memory_search`. Embeddings can be disabled; the graph
+  still works without them.
+- **`dry-run` skill.** Documents the
+  config-edit → dry-run → finish → inspect-snapshot loop.
+- **`WORK.feedback.yaml`.** First-class persistent record of every
+  feedback item and its full transition history. Atomic writes via
+  write-temp-then-rename.
+- **`open_feedback` and `seq` on every `WORK.history.yaml` entry.**
+  `open_feedback` records the count of open items at each tick; `seq`
+  acts as a tiebreaker for same-millisecond timestamps.
+- **Failed-flow guards on mutating tools.** `foundry_validate_run`
+  and 11 mutating memory admin tools (`foundry_memory_init`,
+  `_reset`, `_vacuum`, `_change_embedding_model`,
+  `_create_entity_type`, `_create_edge_type`, `_rename_entity_type`,
+  `_rename_edge_type`, `_drop_entity_type`, `_drop_edge_type`, and
+  `foundry_extractor_create`) refuse on a failed workfile. Read-only
+  memory tools (`_dump`, `_validate`) remain callable.
+- **Deterministic orchestration.** `foundry_orchestrate` owns the
+  sort → history → dispatch → finalize → history → commit loop in
+  plugin code. Orphaned-stage detection: if `orchestrate` is called
+  without `lastResult` while an active stage exists, returns
+  `violation`.
+- **Atomic stage tokens.** `foundry_stage_begin(stage, cycle, token)`
+  consumes a single-use HMAC-signed token issued by `foundry_sort`;
+  `foundry_stage_end(summary)` closes a stage preserving `baseSha`
+  for finalize; `foundry_stage_finalize` verifies stage output
+  against allowed file patterns and registers matching files as
+  draft artefacts, rejecting 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), and `trace/` (dry-run JSONL traces).
+
+### Changed
+
+- **`foundry_memory_dump` response wrapped in a JSON envelope.** Now
+  returns `{ dump: "<text>" }`, matching every other plugin tool's
+  contract. Callers that previously consumed the raw string must
+  read `.dump`.
+- **`foundry_git_branch` errors return a JSON envelope.** Failures
+  are returned as `{ error: "<message>" }`, giving callers a
+  structured alternative to raw `execFileSync` errors.
+- **`cozo-node` is now an optional dependency.** Foundry installs
+  without it; the memory subsystem reports
+  `"cozo-node is not installed on this platform"` if a memory tool
+  is invoked. This unblocks installation on platforms without
+  prebuilt cozo binaries.
+- **Test suite split into unit, integration, and e2e tiers.** Run
+  individually with `pnpm run test`, `pnpm run test:integration`,
+  `pnpm run test:e2e`, or all together with `pnpm run test:all`.
+  `pnpm run build:all` chains lint → test:all → build.
+- **`prepublishOnly` runs `build:all`.** Publish is now gated on the
+  full quality pipeline, not just `build`.
+
+### Fixed
+
+- **Stage-end memory sync failure is a hard flow failure.** When
+  `foundry_stage_end` cannot flush the in-memory DB to the NDJSON
+  source of truth, WORK.md is marked `status: failed` with the sync
+  error as `reason`, and every mutating tool refuses until the cycle
+  is abandoned via `foundry_workfile_delete`. Read-only tools and
+  the escape hatches (`workfile_delete`, `git_finish`) remain
+  callable. Skills driving each stage (`forge`, `quench`, `appraise`,
+  `human-appraise`, `orchestrate`, `assay`, `flow`) were updated to
+  check for the failed state at the top of their procedure and hand
+  control back to the user. Previously, sync failures were silently
+  swallowed and the live DB was allowed to drift ahead of on-disk
+  NDJSON.
+- **`foundry_orchestrate` catches `requireNotFailed` violations.**
+  Moved the failed-flow check inside the wrapper try/catch so a
+  malformed-frontmatter `YAMLException` collapses to
+  `{action: 'violation'}` instead of an uncaught throw.
+- **Missing artefact-type definitions surface a typed finalize error.**
+  The orchestrator's finalize bridge now returns
+  `{ok: false, error: "missing_artefact_type: <type> (<reason>)"}`
+  when `getArtefactType` fails, preserving the real error and
+  avoiding a false `unexpected_files` violation.
+- **Atomic history writes.** `WORK.history.yaml` writes use
+  write-temp-then-rename, closing observed incompleteness in the
+  wild. Malformed history on read now marks the flow failed via
+  `markWorkfileFailed`, allowing graceful recovery rather than
+  silent corruption.
+- **Validation results structured per item.** `foundry_validate_run`
+  returns `{ ok, validatorsRun, items, errors }` with `items` as
+  parsed JSONL entries and `errors` separating parse failures from
+  pattern mismatches. Replaces the prior unstructured aggregate.
+
+### Migration
+
+Run the `upgrade-foundry` skill from a clean project state. Foundry
+upgrades use a rebuild-style workflow: the skill preserves the
+existing `foundry/` directory, initialises a clean current-version
+configuration, analyses the preserved directory as source material,
+and recreates supported concepts through current tools.
+
+The skill asks clarifying questions for ambiguous flow routing, input
+contracts, validation behaviour, memory settings, and deprecated
+concepts. It does not migrate in-flight `WORK.md` state, feedback
+state, branch state, or active flow execution. Complete or discard
+active flows before upgrading.
+
+Cycle definitions must rename `output:` to `output-type:`. Artefact-type
+definitions should delete the `output:` line. Projects with a populated
+memory store should `git mv foundry/memory/relations
+foundry-memory/relations` before re-initialising; projects that have
+not yet populated memory can simply re-run `foundry_memory_init` on a
+fresh `config/*` branch. Pre-3.0.0 in-flight feedback in the markdown
+`## Feedback` section is not auto-migrated: finish or discard
+in-flight cycles before upgrading.
+
+Projects with populated memory should validate memory before upgrading
+so the preserved source material reflects committed state. The
+recreated current-version config should be validated with the current
+config and memory validation tools before merging the config branch.
+
+### Known issues
+
+- **Flow memory backend (`cozo-node`) is unmaintained.** The optional
+  flow-memory subsystem persists to `cozo-node`, whose upstream
+  packages have not seen a release since December 2023
+  (`cozo-node@0.7.6`) and whose Rust core (`cozodb/cozo`) has not
+  been pushed to since December 2024. The memory tools continue to
+  work and there are no known runtime issues, but `cozo-node@0.7.6`
+  transitively depends on `@mapbox/node-pre-gyp@^1`, which surfaces
+  six `deprecated subdependency` warnings at install time
+  (`are-we-there-yet`, `gauge`, `glob@7`, `inflight`, `npmlog`,
+  `rimraf@3`). These warnings are cosmetic: `pnpm audit` reports
+  zero vulnerabilities. Foundry will migrate to a maintained graph +
+  vector backend in a future release; the memory tool surface
+  (`foundry_memory_*`) and the on-disk vocabulary / NDJSON format
+  are designed to remain stable across that migration.
+
+## 2.4.2 — 2026-04-23
+
+### Changed
+
+- README: new hero-style "Governed work for AI" section before the TOC — names the discipline problem, lists what developers get, speaks to teams under a "structural, not cultural" framing.
+- README: old "Why Foundry?" section removed; the five bullets it contained now live under a renamed "Design principles" section (was "Design decisions"), prefaced with the governing rule (*trust the tool, not the LLM*) and extended with a new principle entry on human-in-the-loop gates.
+
+## 2.4.1 — 2026-04-23
+
+### Fixed
+
+- `docs/getting-started.md` install snippet used a `packages` key that doesn't exist in OpenCode's config schema. Corrected to the `plugin: ["@really-knows-ai/foundry"]` form already shown in `README.md`.
+
+## 2.4.0 — 2026-04-23
+
+### Added
+
+- **Flow memory** — a typed, graph-shaped knowledge store that persists across cycles. Entity types, edge types, and their prose briefs live in `foundry/memory/`; entity rows and edge rows are committed as NDJSON under `foundry/memory/relations/`; the live Cozo 0.7 database (`foundry/memory/memory.db*`) is gitignored and rebuilt on demand from the NDJSON files. Each cycle declares read/write permissions in its frontmatter (`memory: { read: [...], write: [...] }`); the dispatched stage prompt is augmented with a vocabulary block listing the entity/edge types visible to that cycle and the memory tools available to it.
+- **Optional semantic search.** When `embeddings.enabled` is true in `foundry/memory/config.md`, entities are embedded on write against an OpenAI-compatible endpoint (default: local Ollama `nomic-embed-text`, 768 dims) and exposed via `foundry_memory_search`. Embeddings can be disabled; the graph still works.
+- **20 memory tools** registered by the plugin: `foundry_memory_{put,relate,unrelate,get,list,neighbours,query,search}` for read/write, `foundry_memory_{create,rename,drop}_{entity,edge}_type` for vocabulary management, `foundry_memory_{init,validate,reset,dump,vacuum,change_embedding_model}` for admin. Destructive operations (`drop_*`) take an optional `confirm` — without it they return a preview of affected rows.
+- **9 memory skills**: `init-memory`, `add-memory-entity-type`, `add-memory-edge-type`, `rename-memory-entity-type`, `rename-memory-edge-type`, `drop-memory-entity-type`, `drop-memory-edge-type`, `reset-memory`, `change-embedding-model`. All wrap the deterministic admin tools with the usual conflict-checking, preview-then-confirm, and commit discipline.
+- `docs/memory-maintenance.md` — contributor notes on Cozo 0.7 adaptations (`::compact`, typed `<F32;N>?` vector columns, `?[...] <- [[...]]` put syntax, single-vs-double-quote string literal semantics, `::relations` HNSW filtering) and the session-singleton lifecycle constraint.
+
+### Notes
+
+- Memory is strictly opt-in. A project without `foundry/memory/` behaves exactly as before; the prompt-extras injection no-ops, and cycles that don't declare a `memory:` block see no vocabulary and no memory tools in their prompt.
+- On store open, orphan relations left behind by drops/renames are reconciled automatically (`::relations` filtered to `^(ent|edge)_[^:]+$`, HNSW indices dropped before `::remove`).
+- Memory prompt injection is wrapped in a swallow-errors guard: if memory is misconfigured or drifted, dispatch still succeeds with no vocabulary block rather than failing the cycle.
+
+## 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.
+- **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.
+- **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/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Really Knows AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.