@really-knows-ai/foundry 2.3.1 → 3.0.0

package/CHANGELOG.md

@@ -1,90 +0,0 @@
-# Changelog
-
-## 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,59 +0,0 @@
-# Concepts
-
-Core concepts and how they relate.
-
-## Foundry Flow
-
-A foundry flow is the top-level unit of work. It is defined in `foundry/flows/` and lists the foundry cycles to execute in order. Starting a foundry flow creates a work branch and a WORK.md file. A foundry flow is complete when all its foundry cycles are done.
-
-## Foundry Cycle
-
-A foundry cycle is an iterative loop that produces a single artefact type. It is defined in `foundry/cycles/` and specifies:
-- An output artefact type (read-write)
-- Zero or more input artefact types (read-only, from previous foundry cycles)
-
-A foundry cycle runs: forge → quench → appraise, repeating until all feedback is resolved or the iteration limit is hit.
-
-## Stage
-
-The steps within a foundry cycle. Each stage is referenced using a `base:alias` format (e.g. `forge:write-haiku`) where the base is the stage type and the alias describes its role in that cycle.
-
-- Forge — produce or revise the artefact
-- Quench — run deterministic CLI checks
-- Appraise — subjective evaluation by multiple appraisers
-- HITL — human-in-the-loop checkpoint (see below)
-
-## Artefact type
-
-A definition of what kind of thing is being produced. Lives in `foundry/artefacts/<type>/` with:
-- `definition.md` — identity, file patterns, output location, prose description
-- `laws.md` — type-specific subjective evaluation criteria
-- `validation.md` — CLI commands for deterministic quench checks
-
-## Law
-
-A subjective pass/fail criterion. Global laws live in `foundry/laws/` (all files concatenated). Type-specific laws live in `foundry/artefacts/<type>/laws.md`. Each law has an identifier (its heading), used in feedback tags.
-
-## Appraiser
-
-An independent evaluator with a defined personality. Lives in `foundry/appraisers/`. Each appraiser can optionally specify a `model` to override the cycle-level appraise model. Model diversity is configured at the cycle level (via the `models` frontmatter map) and optionally per-appraiser. They can be assigned to specific artefact types or appraise everything.
-
-## WORK.md
-
-The transient shared state for a foundry flow. Created on the work branch, it tracks: where the foundry flow is (frontmatter cursor), what artefacts exist, and all feedback with its full lifecycle. See [work-spec.md](work-spec.md) for the full spec.
-
-## Feedback
-
-The communication mechanism between stages. Written as markdown checklist items in WORK.md with tags (`#validation` or `#law:<id>`). Follows a lifecycle: open → actioned/wont-fix → approved/rejected. See [work-spec.md](work-spec.md) for details.
-
-## HITL
-
-Human-in-the-loop checkpoint. A stage type that pauses the foundry cycle and requests human input before continuing. Configured per cycle by including a `hitl:alias` entry in the `stages` list. When a hitl stage runs, it presents the current artefact state to the human and collects feedback tagged `#hitl`. Like other feedback, hitl feedback follows the standard lifecycle (open → actioned → approved/rejected).
-
-## Micro commit
-
-Every stage ends with a commit (via the `foundry_git_commit` tool). This enables file modification enforcement — the sort tool checks the git diff to ensure each stage only touched files it was allowed to.
-
-## Custom tools
-
-All deterministic pipeline operations are exposed as custom tools via the Foundry plugin. Skills call tools instead of manipulating files directly. The tools are backed by shared library modules in `scripts/lib/` with injectable I/O for testability. This separation ensures that file format parsing, state transitions, and routing logic are handled by tested code rather than LLM interpretation.

package/docs/getting-started.md

@@ -1,78 +0,0 @@
-# Getting Started
-
-How to set up and run your first foundry flow.
-
-## Prerequisites
-
-- Git repository initialised
-- Node.js available (for validation scripts)
-- An AI coding tool that supports skills (OpenCode, Claude Code, Copilot CLI, etc.)
-
-## Step by step
-
-### 1. Define an artefact type
-
-Create a directory under `foundry/artefacts/` with three files:
-
-```
-foundry/artefacts/my-type/
-  definition.md    # what it is, file patterns, output location
-  laws.md          # subjective laws (optional)
-  validation.md    # CLI validation commands (optional)
-```
-
-Use the `init-foundry` skill to scaffold the `foundry/` directory, then use `add-artefact-type` to create your first artefact type interactively — or create the directory structure above manually.
-
-### 2. Write laws
-
-Add global laws to any `.md` file in `foundry/laws/`. Add type-specific laws to `foundry/artefacts/<type>/laws.md`.
-
-Each law is a `##` heading with: a description, what passing looks like, and what failing looks like.
-
-### 3. Define a foundry cycle
-
-Create a file in `foundry/cycles/` that specifies what artefact type the foundry cycle produces and what inputs it reads:
-
-```yaml
----
-id: my-cycle
-name: My Cycle
-output: my-type
-inputs: []
----
-```
-
-Cycles list their stages using `base:alias` format — e.g. `forge:write-haiku`, `quench:check-syllables`. The alias makes each stage's purpose clear when reading WORK.md. You can also include `hitl:alias` stages for human-in-the-loop checkpoints.
-
-### 4. Define a foundry flow
-
-Create a file in `foundry/flows/` that lists foundry cycles in order:
-
-```markdown
----
-id: my-flow
-name: My Flow
----
-
-# My Flow
-
-Description of what this flow produces.
-
-## Cycles
-
-1. my-cycle
-```
-
-### 5. Run the foundry flow
-
-Tell your AI tool to start the foundry flow. It will create a work branch, initialise WORK.md, and begin executing foundry cycles.
-
-## What happens during a foundry flow
-
-1. The foundry flow skill creates a branch and WORK.md
-2. For each foundry cycle:
-   - Forge produces the artefact
-   - Quench runs CLI commands (if defined)
-   - Appraise dispatches sub-agent appraisers against the laws
-   - If feedback exists, forge revises and the foundry cycle repeats
-3. When all foundry cycles complete, the human decides to merge, PR, or discard

package/docs/work-spec.md

@@ -1,193 +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
----
-```
-
-Fields:
-- `flow` — the foundry flow being executed
-- `cycle` — the current foundry cycle id
-- `stages` — the ordered route for this foundry cycle, set when the foundry cycle starts. Each entry uses `base:alias` format where `base` is the stage type (`forge`, `quench`, `appraise`, or `hitl`) and `alias` is a human-readable name for what that stage does in this cycle. Determined from the artefact type: if `validation.md` exists, include `quench`; always include `forge` and `appraise`. A `hitl` stage can be included for human-in-the-loop checkpoints.
-- `max-iterations` — how many forge passes before the foundry cycle is blocked (default: 3)
-
-The `stages` list is the happy path. Sort follows it but loops back to `forge` when unresolved feedback demands it.
-
-### Who sets what
-
-- `flow` — set by the foundry flow skill at foundry flow start, never changes
-- `cycle` — set by the foundry flow skill when starting each foundry cycle
-- `stages` — set by the orchestrate skill when starting each foundry cycle (reads artefact type to determine if quench is needed)
-- `max-iterations` — set by the orchestrate skill (default 3, could be overridden in foundry 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
-- `#hitl` — from human-provided feedback at a hitl 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
-- 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`) | `foundry_workfile_create` (flow skill) | nobody |
-| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (orchestrate skill) | `foundry_workfile_set` (reset on each new cycle) |
-| Goal | `foundry_workfile_create` (flow skill) | nobody |
-| Artefacts | `foundry_artefacts_add` (forge skill) | `foundry_artefacts_set_status` (orchestrate skill) |
-| Feedback | `foundry_feedback_add` (quench/appraise/hitl) | `foundry_feedback_action`/`foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench/appraise/hitl) |
-
-## 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`, `hitl: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 skill appends an entry when it completes
-- The sort tool reads this to determine what has happened in the current foundry cycle
-- Iteration is derived from counting forge entries for the current foundry cycle
-
-### Who writes
-
-Every stage skill (forge, quench, appraise, hitl) appends an entry when it finishes via the `foundry_history_append` tool.
-
-## 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
----
-
-# 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
-```

package/scripts/lib/artefacts.js

@@ -1,124 +0,0 @@
-/**
- * Artefacts table utilities for WORK.md.
- *
- * Parses, adds rows to, and updates status in the markdown artefacts table.
- */
-
-/**
- * Parse the artefacts markdown table from text.
- * @param {string} text
- * @returns {Array<{file: string, type: string, cycle: string, status: string}>}
- */
-export function parseArtefactsTable(text) {
-  const artefacts = [];
-  let inTable = false;
-
-  for (const line of text.split('\n')) {
-    const stripped = line.trim();
-
-    if (stripped.startsWith('| File')) {
-      inTable = true;
-      continue;
-    }
-    if (inTable && stripped.startsWith('|---')) {
-      continue;
-    }
-    if (inTable && stripped.startsWith('|')) {
-      const cols = stripped.split('|').slice(1, -1).map(c => c.trim());
-      if (cols.length >= 4) {
-        artefacts.push({
-          file: cols[0],
-          type: cols[1],
-          cycle: cols[2],
-          status: cols[3],
-        });
-      }
-    } else if (inTable) {
-      inTable = false;
-    }
-  }
-
-  return artefacts;
-}
-
-/**
- * Add a row to the artefacts table.
- * @param {string} text - Full WORK.md text
- * @param {{file: string, type: string, cycle: string, status: string}} row
- * @returns {string} Updated text
- */
-export function addArtefactRow(text, { file, type, cycle, status }) {
-  const lines = text.split('\n');
-  let lastTableRow = -1;
-  let inTable = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    const stripped = lines[i].trim();
-    if (stripped.startsWith('| File')) {
-      inTable = true;
-      continue;
-    }
-    if (inTable && stripped.startsWith('|---')) {
-      if (lastTableRow < 0) lastTableRow = i; // insert after separator if no data rows
-      continue;
-    }
-    if (inTable && stripped.startsWith('|')) {
-      lastTableRow = i;
-    } else if (inTable) {
-      break;
-    }
-  }
-
-  if (lastTableRow === -1) {
-    throw new Error('Artefacts table not found');
-  }
-
-  const newRow = `| ${file} | ${type} | ${cycle} | ${status} |`;
-  lines.splice(lastTableRow + 1, 0, newRow);
-  return lines.join('\n');
-}
-
-/**
- * Update the status column for a specific file in the artefacts table.
- * @param {string} text - Full WORK.md text
- * @param {string} file - File name to match
- * @param {string} newStatus - New status value
- * @returns {string} Updated text
- */
-export function setArtefactStatus(text, file, newStatus) {
-  if (newStatus === 'draft') {
-    throw new Error('status draft not permitted; use stage_finalize for registration');
-  }
-  if (!['done', 'blocked'].includes(newStatus)) {
-    throw new Error(`invalid status: ${newStatus}`);
-  }
-  const lines = text.split('\n');
-  let inTable = false;
-  let found = false;
-
-  for (let i = 0; i < lines.length; i++) {
-    const stripped = lines[i].trim();
-    if (stripped.startsWith('| File')) {
-      inTable = true;
-      continue;
-    }
-    if (inTable && stripped.startsWith('|---')) continue;
-    if (inTable && stripped.startsWith('|')) {
-      const cols = stripped.split('|').slice(1, -1).map(c => c.trim());
-      if (cols.length >= 4 && cols[0] === file) {
-        cols[3] = newStatus;
-        lines[i] = '| ' + cols.join(' | ') + ' |';
-        found = true;
-        break;
-      }
-    } else if (inTable) {
-      break;
-    }
-  }
-
-  if (!found) {
-    throw new Error(`File not found in artefacts table: ${file}`);
-  }
-
-  return lines.join('\n');
-}