@really-knows-ai/foundry 1.2.2 → 1.3.0

package/scripts/sort.js

@@ -15,12 +15,13 @@
 
 import { readFileSync, existsSync } from 'fs';
 import { execSync } from 'child_process';
-import { parseArgs } from 'util';
-import { join } from 'path';
-import { fileURLToPath } from 'url';
 import yaml from 'js-yaml';
 import { minimatch } from 'minimatch';
-import { validateTags, extractAllTags } from './lib/tags.js';
+import { validateTags } from './lib/tags.js';
+import { parseFrontmatter } from './lib/workfile.js';
+import { parseArtefactsTable } from './lib/artefacts.js';
+import { loadHistory } from './lib/history.js';
+import { parseFeedback, parseFeedbackItem } from './lib/feedback.js';
 
 // ---------------------------------------------------------------------------
 // Stage helpers
@@ -59,121 +60,6 @@ const defaultIO = {
 // Parsing
 // ---------------------------------------------------------------------------
 
-function parseFrontmatter(text) {
-  const match = text.match(/^---\n(.+?)\n---/s);
-  if (!match) return {};
-  return yaml.load(match[1]) || {};
-}
-
-function parseFeedback(text, cycle, artefacts) {
-  const cycleFiles = new Set();
-  for (const art of artefacts) {
-    if (art.cycle === cycle) {
-      cycleFiles.add(art.file || '');
-    }
-  }
-
-  const items = [];
-  let currentFile = null;
-  let inFeedback = false;
-  let feedbackLevel = 0; // 1 for '# Feedback', 2 for '## Feedback'
-
-  for (const line of text.split('\n')) {
-    const stripped = line.trim();
-
-    if (stripped === '# Feedback' || stripped === '## Feedback') {
-      inFeedback = true;
-      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
-      continue;
-    }
-
-    // Exit feedback on a heading at the same or higher level
-    if (inFeedback && /^#{1,2} /.test(stripped)) {
-      const level = stripped.startsWith('## ') ? 2 : 1;
-      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
-        inFeedback = false;
-        continue;
-      }
-    }
-
-    if (!inFeedback) continue;
-
-    // File sub-headings are one level below the Feedback heading
-    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
-    if (stripped.startsWith(fileHeadingPrefix)) {
-      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
-      continue;
-    }
-
-    if (cycleFiles.has(currentFile) && /^- \[/.test(stripped)) {
-      items.push(parseFeedbackItem(stripped));
-    }
-  }
-
-  return items;
-}
-
-function parseFeedbackItem(line) {
-  const item = { raw: line, state: 'unknown', tags: [], resolved: false };
-
-  if (line.startsWith('- [ ]')) {
-    item.state = 'open';
-  } else if (line.startsWith('- [x]')) {
-    item.state = 'actioned';
-  } else if (line.startsWith('- [~]')) {
-    item.state = 'wont-fix';
-  }
-
-  if (line.includes('| approved')) {
-    item.resolved = true;
-  } else if (line.includes('| rejected')) {
-    item.state = 'rejected';
-    item.resolved = false;
-  }
-
-  item.tags = extractAllTags(line);
-
-  return item;
-}
-
-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;
-}
-
-function loadHistory(historyPath, cycle, io = defaultIO) {
-  if (!io.exists(historyPath)) return [];
-  const data = yaml.load(io.readFile(historyPath)) || [];
-  return data.filter(e => e.cycle === cycle);
-}
-
 // ---------------------------------------------------------------------------
 // Routing logic
 // ---------------------------------------------------------------------------
@@ -310,109 +196,81 @@ function checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle, io = defaultI
 }
 
 // ---------------------------------------------------------------------------
-// Exports (for testing) — keep main() private
+// Exported runSort — structured result for programmatic use
 // ---------------------------------------------------------------------------
 
-export {
-  baseStage,
-  findFirst,
-  nextInRoute,
-  parseFrontmatter,
-  parseFeedback,
-  parseFeedbackItem,
-  parseArtefactsTable,
-  loadHistory,
-  determineRoute,
-  nextAfterQuench,
-  nextAfterAppraise,
-  globMatch,
-  getModifiedFiles,
-  getAllowedPatterns,
-  checkModifiedFiles,
-};
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-function main() {
-  const { values } = parseArgs({
-    options: {
-      work: { type: 'string', default: 'WORK.md' },
-      history: { type: 'string', default: 'WORK.history.yaml' },
-      'foundry-dir': { type: 'string', default: 'foundry' },
-      'cycle-def': { type: 'string' },
-    },
-  });
-
-  const workPath = values.work;
-  const historyPath = values.history;
-  const foundryDir = values['foundry-dir'];
-
-  if (!existsSync(workPath)) {
-    process.stderr.write('ERROR: WORK.md not found\n');
-    process.exit(1);
+export function runSort({ workPath = 'WORK.md', historyPath = 'WORK.history.yaml', foundryDir = 'foundry', cycleDef } = {}, io = defaultIO) {
+  if (!io.exists(workPath)) {
+    return { route: 'blocked', details: 'WORK.md not found' };
   }
 
-  const workText = readFileSync(workPath, 'utf-8');
+  const workText = io.readFile(workPath);
   const frontmatter = parseFrontmatter(workText);
 
   const cycle = frontmatter.cycle;
   const stages = frontmatter.stages;
   const maxIterations = frontmatter['max-iterations'] ?? 3;
 
-  if (!cycle) {
-    process.stderr.write('ERROR: No cycle in WORK.md frontmatter\n');
-    process.exit(1);
-  }
-
-  if (!stages || !Array.isArray(stages)) {
-    process.stderr.write('ERROR: No stages in WORK.md frontmatter\n');
-    process.exit(1);
-  }
-
-  if (!findFirst(stages, 'forge')) {
-    process.stderr.write('ERROR: stages must include at least one forge stage\n');
-    process.exit(1);
-  }
+  if (!cycle) return { route: 'blocked', details: 'No cycle in WORK.md frontmatter' };
+  if (!stages || !Array.isArray(stages)) return { route: 'blocked', details: 'No stages in WORK.md frontmatter' };
+  if (!findFirst(stages, 'forge')) return { route: 'blocked', details: 'stages must include at least one forge stage' };
 
   const artefacts = parseArtefactsTable(workText);
-  const history = loadHistory(historyPath, cycle);
+  const history = loadHistory(historyPath, cycle, io);
   const feedback = parseFeedback(workText, cycle, artefacts);
 
-  // --- File modification enforcement ---
+  // File modification enforcement
   const nonSortHistory = history.filter(e => baseStage(e.stage || '') !== 'sort');
   if (nonSortHistory.length > 0) {
     const lastEntry = nonSortHistory[nonSortHistory.length - 1];
     const lastBase = baseStage(lastEntry.stage || '');
-
-    // Resolve cycle-def: CLI arg > WORK.md frontmatter field
-    const cycleDef = values['cycle-def']
-      || frontmatter['cycle-def']
-      || `${foundryDir}/cycles/${cycle}.md`;
-
-    const result = checkModifiedFiles(lastBase, foundryDir, cycleDef, cycle);
+    const resolvedCycleDef = cycleDef || frontmatter['cycle-def'] || `${foundryDir}/cycles/${cycle}.md`;
+    const result = checkModifiedFiles(lastBase, foundryDir, resolvedCycleDef, cycle, io);
     if (!result.ok) {
-      console.log('violation');
-      process.stderr.write(`File modification violation after ${lastBase} stage:\n`);
-      result.violations.forEach(f => process.stderr.write(`  ${f}\n`));
-      process.exit(0);
+      return { route: 'violation', details: `File modification violation after ${lastBase} stage: ${result.violations.join(', ')}` };
     }
   }
 
-  // --- Tag validation ---
+  // Tag validation
   const tagErrors = validateTags(workText, foundryDir);
   if (tagErrors.length > 0) {
-    console.log('violation');
-    process.stderr.write(`Feedback tag validation failed (${tagErrors.length} issue${tagErrors.length > 1 ? 's' : ''}):\n`);
-    tagErrors.forEach(e => process.stderr.write(`  line ${e.line}: ${e.message}\n`));
-    process.exit(0);
+    const details = tagErrors.map(e => `line ${e.line}: ${e.message}`).join('; ');
+    return { route: 'violation', details: `Feedback tag validation failed: ${details}` };
   }
 
   const route = determineRoute(stages, history, feedback, maxIterations);
-  console.log(route);
-}
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+  // Model resolution
+  let model = null;
+  const routeBase = baseStage(route);
+  if (frontmatter.models && frontmatter.models[routeBase]) {
+    const modelId = frontmatter.models[routeBase];
+    model = `foundry-${modelId.replace(/\//g, '-')}`;
+  }
+
+  return { route, ...(model ? { model } : {}) };
 }
+
+// ---------------------------------------------------------------------------
+// Exports (for testing) — keep main() private
+// ---------------------------------------------------------------------------
+
+export { parseArtefactsTable } from './lib/artefacts.js';
+export { loadHistory } from './lib/history.js';
+export { parseFeedback, parseFeedbackItem } from './lib/feedback.js';
+
+export {
+  baseStage,
+  findFirst,
+  nextInRoute,
+  parseFrontmatter,
+  determineRoute,
+  nextAfterQuench,
+  nextAfterAppraise,
+  globMatch,
+  getModifiedFiles,
+  getAllowedPatterns,
+  checkModifiedFiles,
+};
+
+

package/skills/appraise/SKILL.md

@@ -6,7 +6,7 @@ description: Subjective evaluation of an artefact against laws via multiple inde
 
 # Appraise
 
-You orchestrate subjective appraisal of an artefact by dispatching independent sub-agent appraisers, then consolidating their feedback into WORK.md.
+You orchestrate subjective appraisal of an artefact by dispatching independent sub-agent appraisers, then consolidating their feedback.
 
 ## Prerequisites
 
@@ -14,88 +14,49 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
 
-## Appraiser configuration
-
-Appraiser personalities are defined in `foundry/appraisers/` (the appraiser directory). Each markdown file defines:
-- `id` — identifier
-- `model` — (optional) specific model ID to use for this appraiser, overriding the cycle-level appraise model
-
-The artefact type definition (`foundry/artefacts/<type>/definition.md`) controls how appraisers are assigned via its `appraisers` frontmatter:
-
-```yaml
-appraisers:
-  count: 3                              # how many appraisers (default: 3)
-  allowed: [pedantic, pragmatic]        # which personalities (default: all available)
-```
+## Protocol
 
-### Appraiser selection
+1. Gather context:
+   - Call `foundry_workfile_get` — identify the artefact to appraise and its type
+   - Call `foundry_config_laws` — get all applicable laws (global + type-specific)
+   - Call `foundry_config_artefact_type` with the type ID — get the artefact type definition
+   - Call `foundry_appraisers_select` with the type ID — returns selected appraiser personalities with their raw model IDs
 
-1. Read the `appraisers` config from the artefact type definition
-2. If `allowed` is specified, filter to only those personalities. Otherwise use all in `foundry/appraisers/`.
-3. If `count` is omitted, default to 3
-4. Distribute evenly across available personalities for maximum diversity:
-   - 3 appraisers, 3 personalities → 1 of each
-   - 6 appraisers, 3 personalities → 2 of each
-   - 4 appraisers, 3 personalities → 2, 1, 1 (round-robin)
-5. If count > available personalities, wrap around (same personality, still independent sub-agents)
+2. Dispatch each appraiser as an independent sub-agent (see Dispatch below)
 
-Model diversity is configured at two levels: the cycle definition sets a default model for the appraise stage (which should differ from the forge model), and individual appraisers can optionally override with their own model. If no models are configured, the session's default model is used — personality diversity still adds value but model diversity is lost.
+3. Collect results from all appraisers
 
-## Protocol
-
-1. Read `WORK.md` — identify the artefact to appraise and its type
-2. Read all files in `foundry/laws/` — identify global laws
-3. Read `foundry/artefacts/<type>/laws.md` — identify type-specific laws (if it exists)
-4. Read `foundry/artefacts/<type>/definition.md` — for context and appraiser config
-5. Select appraisers (see Appraiser selection above)
-6. Dispatch each appraiser as a sub-agent (see Dispatch below)
-7. Collect results from all appraisers
-8. Consolidate:
+4. Consolidate (this is judgment):
    - Union of all issues — if any one appraiser flags it, it's feedback
    - De-duplicate: merge overlapping observations into a single feedback item
    - Preserve which appraiser(s) raised each issue (for traceability)
-9. Write consolidated feedback to WORK.md under the artefact's file heading:
 
-   Feedback MUST be scoped to the artefact file. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
+5. For each consolidated issue: call `foundry_feedback_add` with the artefact file path, the issue description, and tag `law:<law-id>`
+
+6. If no appraiser found any issues, the artefact clears appraisal
 
-   ```markdown
-   ## Feedback
+## Reviewing actioned and wont-fix feedback
 
-   ### foundry/output/haiku/pissed-off-spaghetti.md
-   - [ ] The imagery lacks originality #law:vivid-imagery
-   ```
+On subsequent passes, review previously actioned and wont-fix items:
 
-   If the `## Feedback` section or the file sub-heading already exists (e.g., quench already wrote validation feedback there), append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
-10. If no appraiser found any issues, the artefact clears appraisal
+1. Call `foundry_feedback_list` to find `actioned` and `wontfix` items for this artefact
+2. For each item, the appraiser sub-agents evaluate whether the change addresses the issue (actioned) or the justification is sound (wont-fix)
+3. Call `foundry_feedback_resolve` with disposition `"approved"` or `"rejected"` (with reason) for each
 
 ## Dispatch
 
 Each appraiser is dispatched as an independent sub-agent. The sub-agent receives a prompt containing:
-- The appraiser's personality (from their definition file)
+- The appraiser's personality (from their definition)
 - The artefact content
 - All applicable laws (global + type-specific)
 - Instructions to evaluate the artefact against each law and return issues as a structured list
 
 ### Model resolution
 
-For each appraiser being dispatched, resolve the model in this order:
-1. **Appraiser `model` field** — if the appraiser definition specifies a `model`, use it
-2. **Cycle `models.appraise`** — if the cycle definition specifies a model for the appraise stage, use it (read from WORK.md frontmatter or the cycle definition)
-3. **Default** — use `subagent_type: "general"` (inherits the session's model)
-
-If a model is resolved (options 1 or 2), convert it to an agent name: `foundry-<provider-id>-<model-key>` (e.g., `openai/gpt-4o` → `foundry-openai-gpt-4o`). If no agent with that name exists, **hard fail** with an error:
-
-> Appraiser `<appraiser-id>` specifies model `<model-id>` but no matching agent `foundry-<agent-name>` is registered. Check your OpenCode provider config.
+`foundry_appraisers_select` returns raw model IDs for each appraiser. Convert each to an agent name: `foundry-<model.replace(/\//g, '-')>` (e.g., `openai/gpt-4o` becomes `foundry-openai-gpt-4o`).
 
-### OpenCode dispatch
-
-Use the Task tool to dispatch each appraiser:
-
-```
-Task tool call for each appraiser:
-- subagent_type: "<resolved agent name>" or "general" if no model specified
-- prompt: contains personality, artefact, laws, evaluation instructions
-```
+- If a model is specified: dispatch with `subagent_type: "foundry-<converted-name>"`. If no agent with that name exists, **hard fail**.
+- If no model is specified: dispatch with `subagent_type: "general"` (inherits session model).
 
 Dispatch all appraisers in parallel (multiple Task calls in a single response).
 
@@ -104,7 +65,7 @@ Dispatch all appraisers in parallel (multiple Task calls in a single response).
 ```
 You are an appraiser. Your personality:
 
-<contents of foundry/appraisers/<id>.md>
+<contents of appraiser personality>
 
 Evaluate the following artefact against each law below. For each law, either:
 - Note no issues (pass)
@@ -128,32 +89,12 @@ Return a list of issues. For each issue:
 If there are no issues, return an empty list.
 ```
 
-## Reviewing actioned and wont-fix feedback
-
-On subsequent passes, appraisers also evaluate previously actioned and wont-fix items under the artefact's `### <file-path>` heading:
-
-- `[x]` actioned items: appraiser checks whether the change actually addresses the issue
-  - If yes: mark `| approved`
-  - If no: mark `| rejected: <reason>` (item is effectively re-opened)
-- `[~]` wont-fix items: appraiser reads the justification
-  - If the justification is sound: mark `| approved`
-  - If not: mark `| rejected` (item is effectively re-opened)
-
 ## History
 
-After completing the appraisal consolidation, append an entry to `WORK.history.yaml`:
-
-```yaml
-- timestamp: "<ISO 8601 UTC>"
-  cycle: <current-cycle-id>
-  stage: <alias>
-  iteration: <current iteration from history>
-  comment: <brief summary, e.g., "3 issues found across 2 appraisers" or "No issues found, cycle complete">
-```
+After completing the appraisal consolidation, call `foundry_history_append` with the current cycle, stage alias, and a brief summary (e.g., "3 issues found across 2 appraisers" or "No issues found").
 
 ## What you do NOT do
 
 - You do not revise the artefact
 - You do not check deterministic rules — that is the quench skill's job
 - You do not filter out feedback because only one appraiser raised it — one is enough
-- You do not write feedback items without a file sub-heading under `## Feedback`

package/skills/cycle/SKILL.md

@@ -7,7 +7,7 @@ composes: [sort, forge, quench, appraise, hitl]
 
 # Cycle
 
-A foundry cycle reads its definition from `foundry/cycles/<cycle-id>.md`, sets up WORK.md for routing, then hands control to the sort skill which drives the forge → quench → appraise loop.
+A foundry cycle reads its definition, sets up the work file for routing, then hands control to the sort skill which drives the forge/quench/appraise loop.
 
 ## Prerequisites
 
@@ -15,98 +15,61 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
 
-## Cycle definition
-
-The cycle definition (`foundry/cycles/<cycle-id>.md`) specifies:
-- `output` — the artefact type this foundry cycle produces (read-write)
-- `inputs` — artefact types from previous foundry cycles that are read-only context
-- `stages` — (optional) explicit stage list with aliases in `base:alias` format (e.g., `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`)
-- `hitl` — (optional) configuration for human-in-the-loop stages, including prompts
-- `models` — (optional) map of stage base names to model IDs for multi-model routing (e.g., `{ appraise: openai/gpt-4o }`). Stages not listed use the session's default model. If a specified model has no matching `foundry-*` agent, the cycle fails with an error.
-
-If `stages` is not provided, the cycle skill generates default aliases from the cycle id and artefact type.
-
 ## Starting a foundry cycle
 
-1. Read the cycle definition from `foundry/cycles/<cycle-id>.md`
-2. Read the output artefact type definition from `foundry/artefacts/<type>/definition.md`
-3. Determine the stage route using `base:alias` format:
-   - Build the stages list from the cycle definition's `stages` field if present
-   - Otherwise, generate defaults: always `forge`, add `quench` if `foundry/artefacts/<type>/validation.md` exists, always `appraise`
-   - Cycle definitions can include `hitl` entries in the stages list for human-in-the-loop checkpoints
-   - Examples:
-     - `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`
-     - `[forge:write-petition, appraise:evaluate-petition]`
-     - `[forge:draft-proposal, hitl:review-proposal, appraise:evaluate-proposal]`
-4. Update WORK.md frontmatter:
-   - Set `cycle` to the cycle id
-   - Set `stages` to the determined route (e.g., `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`)
-   - Set `max-iterations` (default 3, or from cycle definition if overridden)
-   - If the cycle definition has a `models` map, set `models` in WORK.md frontmatter (e.g., `models: { appraise: openai/gpt-4o }`)
+1. Call `foundry_config_cycle` with the cycle ID — get the cycle definition
+2. Call `foundry_config_artefact_type` with the output type ID — get the artefact type definition
+3. Determine the stage route:
+   - Use the cycle definition's `stages` field if present
+   - Otherwise generate defaults: always `forge`, add `quench` if `foundry_config_validation` returns non-null for the type, always `appraise`
+   - Cycle definitions can include `hitl` entries for human-in-the-loop checkpoints
+4. Call `foundry_workfile_set` to configure the work file:
+   - `key: "cycle"`, `value: <cycle-id>`
+   - `key: "stages"`, `value: <determined stages list>`
+   - `key: "max-iterations"`, `value: <default 3 or from cycle definition>`
+   - If the cycle definition has a `models` map: `key: "models"`, `value: <models map>`
 5. Invoke the sort skill
 
 ## Sort drives everything
 
-Once sort is invoked, it runs `scripts/sort.js` to determine the next stage, invokes the corresponding skill, then runs sort again. This repeats until sort returns `done` or `blocked`.
+Once sort is invoked, it calls `foundry_sort` to determine the next stage, invokes the corresponding skill, then calls sort again. This repeats until sort returns `done` or `blocked`.
 
 The cycle skill does not contain routing logic — sort owns all of that.
 
 ## Completing a foundry cycle
 
 When sort returns `done`:
-- Update the artefact status in WORK.md to `done`
-- Return control to the foundry flow skill
+- Call `foundry_artefacts_set_status` with status `"done"`
+- Return control to the flow skill
 
 When sort returns `blocked`:
-- Update the artefact status in WORK.md to `blocked`
-- Return control to the foundry flow skill (the foundry flow decides how to handle it)
+- Call `foundry_artefacts_set_status` with status `"blocked"`
+- Return control to the flow skill (the flow decides how to handle it)
 
 ## HITL stages
 
-Cycle definitions can include `hitl` entries in their stages list to pause for human input. The cycle definition's `hitl:` config section specifies prompts shown to the human at each hitl checkpoint.
-
-When sort routes to a `hitl` stage:
-- The hitl skill presents the configured prompt to the human
-- The human provides feedback, which is recorded in WORK.md and WORK.history.yaml
-- Sort then determines the next stage based on the feedback
-
-HITL stages follow the same file modification rules as quench/appraise — only WORK.md and WORK.history.yaml may be modified.
+Cycle definitions can include `hitl` entries in their stages list to pause for human input. When sort routes to a `hitl` stage, the hitl skill presents the configured prompt and records the human's response.
 
 ## Micro commits
 
-Every stage must end with a micro commit. Commit message format: `[<cycle-id>] <base>:<alias>: <brief description>`
+Every stage must end with a micro commit. Call `foundry_git_commit` with message format: `[<cycle-id>] <base>:<alias>: <brief description>`
 
 Examples:
 - `[haiku-creation] forge:write-haiku: initial draft`
 - `[haiku-creation] quench:check-syllables: checked syllable pattern`
 - `[haiku-creation] forge:write-haiku: addressed validation feedback`
-- `[haiku-creation] hitl:review-draft: recorded human feedback`
-
-## File modification enforcement
-
-File modification enforcement is handled automatically by the sort script (`scripts/sort.js`). Before routing to the next stage, sort checks the git diff from the last commit against allowed file patterns:
-
-- After forge: output artefact file patterns + WORK.md + WORK.history.yaml
-- After quench/appraise/hitl: only WORK.md + WORK.history.yaml
-- Input artefact files are never allowed (read-only)
-
-Sort reads the cycle definition and artefact type definition to determine allowed patterns. If a violation is detected, sort returns `violation` (with details on stderr) and the cycle halts.
-
-A violation is a hard stop. The foundry cycle sets artefact status to `blocked` and surfaces the issue to the human.
 
 ## Feedback states
 
 ```
-open         - [ ] issue #tag                              → needs generator action
-actioned     - [x] issue #tag                              → needs approval
-wont-fix     - [~] issue #tag | wont-fix: <reason>         → needs approval (appraisal only)
-approved     - [x] issue #tag | approved                   → resolved
-approved     - [~] issue #tag | wont-fix: <reason> | approved → resolved
-rejected     - [x] issue #tag | rejected: <reason>         → re-opened
-rejected     - [~] issue #tag | wont-fix: <reason> | rejected → re-opened
+open         - needs generator action
+actioned     - needs approval
+wont-fix     - needs approval (appraisal only)
+approved     - resolved
+rejected     - re-opened
 ```
 
-Tag types: `#validation` (from quench), `#law:<law-id>` (from appraise), `#hitl` (from human) — indicates the source and category of feedback.
+Tag types: `validation` (from quench), `law:<law-id>` (from appraise), `hitl` (from human) — indicates the source and category of feedback.
 
 ## What you do NOT do
 

package/skills/flow/SKILL.md

@@ -7,7 +7,7 @@ composes: [cycle]
 
 # Flow
 
-A foundry flow reads a flow definition from `foundry/flows/`, creates a work branch, initialises WORK.md, and executes each foundry cycle in sequence.
+A foundry flow reads a flow definition, creates a work branch, initialises the work file, and executes each foundry cycle in sequence.
 
 ## Prerequisites
 
@@ -17,42 +17,16 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## Starting a foundry flow
 
-1. Read the flow definition from `foundry/flows/<flow-id>.md`
-2. Create a branch off main: `work/<flow-id>-<short-description>`
-3. Create `WORK.md` in the project root with this structure:
-
-   ```markdown
-   ---
-   flow: <flow-id>
-   cycle: <first-cycle-id>
-   stages: [<determined by cycle skill>]
-   max-iterations: 3
-   ---
-
-   # Goal
-
-   <goal from flow definition + human context>
-
-   ## Artefacts
-
-   | File | Type | Cycle | Status |
-   |------|------|-------|--------|
-
-   ## Feedback
-   ```
-
-   - `flow` — set once, never changes
-   - `cycle` — current cycle id, updated when each cycle starts
-   - `stages` — the ordered route for the cycle, set by the cycle skill. Each entry uses `base:alias` format (e.g. `forge:write-haiku`, `quench:check-syllables`). Determined from the artefact type: if `validation.md` exists, include `quench`; always include `forge` and `appraise`. `hitl` stages are optional.
-   - `max-iterations` — how many forge passes before the cycle is blocked (default: 3, can be overridden in cycle definition)
-   - Feedback is grouped under `### <file-path>` sub-headings matching the artefact's File column. See the quench and appraise skills for the format.
-4. Execute each foundry cycle in order by reading its definition from `foundry/cycles/<cycle-id>.md`
-5. Update the frontmatter cursor as each foundry cycle starts (set `cycle` to the new cycle id)
-6. When all foundry cycles are done, delete WORK.md — the artefacts and git history are the record
+1. Call `foundry_config_flow` with the flow ID — get the flow definition
+2. Call `foundry_git_branch` with name `work/<flow-id>-<short-description>` — create the work branch
+3. Call `foundry_workfile_create` with the flow ID, first cycle ID, and goal from the flow definition + human context
+4. Execute each cycle in order by invoking the cycle skill
+5. Between cycles: call `foundry_workfile_set` with `key: "cycle"`, `value: <next-cycle-id>`
+6. When all cycles are done: call `foundry_workfile_delete` — the artefacts and git history are the record
 
 ## Completing a foundry flow
 
-When the foundry flow is complete, the branch contains:
+When the flow is complete, the branch contains:
 - The finished artefacts
 - The full git history of micro commits showing every stage
 
@@ -60,7 +34,7 @@ The human decides whether to merge, open a PR, or discard.
 
 ## What you do NOT do
 
-- You do not skip foundry cycles
-- You do not reorder foundry cycles
-- You do not modify artefacts directly — only foundry cycles modify artefacts
-- You do not delete or rewrite feedback history in WORK.md during the foundry flow
+- You do not skip cycles
+- You do not reorder cycles
+- You do not modify artefacts directly — only cycles modify artefacts
+- You do not delete or rewrite feedback history during the flow