@really-knows-ai/foundry 1.2.1 → 1.3.0

package/.opencode/plugins/foundry.js

@@ -9,7 +9,16 @@
 
 import path from 'path';
 import fs from 'fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, unlinkSync } from 'fs';
 import { fileURLToPath } from 'url';
+import { tool } from '@opencode-ai/plugin';
+import { loadHistory, appendEntry, getIteration } from '../../scripts/lib/history.js';
+import { parseFrontmatter, createWorkfile, setFrontmatterField, getFrontmatterField } from '../../scripts/lib/workfile.js';
+import { parseArtefactsTable, addArtefactRow, setArtefactStatus } from '../../scripts/lib/artefacts.js';
+import { addFeedbackItem, actionFeedbackItem, wontfixFeedbackItem, resolveFeedbackItem, listFeedback } from '../../scripts/lib/feedback.js';
+import { getCycleDefinition, getArtefactType, getLaws, getValidation, getAppraisers, getFlow, selectAppraisers } from '../../scripts/lib/config.js';
+import { runSort } from '../../scripts/sort.js';
+import { execSync } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageRoot = path.resolve(__dirname, '../..');
@@ -48,6 +57,16 @@ Scripts are located at: ${path.join(packageRoot, 'scripts')}
 </FOUNDRY_CONTEXT>`;
 }
 
+function makeIO(directory) {
+  const resolve = (p) => path.isAbsolute(p) ? p : path.join(directory, p);
+  return {
+    exists: (p) => existsSync(resolve(p)),
+    readFile: (p) => readFileSync(resolve(p), 'utf-8'),
+    writeFile: (p, content) => writeFileSync(resolve(p), content, 'utf-8'),
+    readDir: (p) => readdirSync(resolve(p)),
+  };
+}
+
 export const FoundryPlugin = async ({ directory }) => {
   return {
     config: async (config) => {
@@ -71,6 +90,394 @@ export const FoundryPlugin = async ({ directory }) => {
 
       const ref = firstUser.parts[0];
       firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
-    }
+    },
+
+    tool: {
+      // ── History tools ──
+      foundry_history_append: tool({
+        description: 'Append an entry to the cycle history (WORK.history.yaml)',
+        args: {
+          cycle: tool.schema.string().describe('Cycle name'),
+          stage: tool.schema.string().describe('Stage name'),
+          comment: tool.schema.string().describe('Comment for this entry'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+          const iteration = getIteration(historyPath, args.cycle, io);
+          appendEntry(historyPath, { cycle: args.cycle, stage: args.stage, iteration, comment: args.comment }, io);
+          return JSON.stringify({ ok: true, iteration });
+        },
+      }),
+
+      foundry_history_list: tool({
+        description: 'List history entries for a cycle',
+        args: {
+          cycle: tool.schema.string().describe('Cycle name'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const historyPath = path.join(context.worktree, 'WORK.history.yaml');
+          const entries = loadHistory(historyPath, args.cycle, io);
+          return JSON.stringify(entries);
+        },
+      }),
+
+      // ── Workfile tools ──
+      foundry_workfile_create: tool({
+        description: 'Create WORK.md with frontmatter and goal',
+        args: {
+          flow: tool.schema.string().describe('Flow name'),
+          cycle: tool.schema.string().describe('Cycle name'),
+          stages: tool.schema.array(tool.schema.string()).describe('Ordered stage names'),
+          maxIterations: tool.schema.number().describe('Maximum iterations'),
+          goal: tool.schema.string().describe('Goal text'),
+          models: tool.schema.record(tool.schema.string()).optional().describe('Per-stage model overrides'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md already exists' });
+          }
+          const fm = { flow: args.flow, cycle: args.cycle, stages: args.stages, maxIterations: args.maxIterations };
+          if (args.models) fm.models = args.models;
+          const content = createWorkfile(fm, args.goal);
+          writeFileSync(workPath, content, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_workfile_get: tool({
+        description: 'Read WORK.md and return frontmatter + goal',
+        args: {},
+        async execute(_args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (!existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md not found' });
+          }
+          const text = readFileSync(workPath, 'utf-8');
+          const fm = parseFrontmatter(text);
+          const goalMatch = text.match(/# Goal\n\n([\s\S]*?)(?=\n\||\n##|$)/);
+          const goal = goalMatch ? goalMatch[1].trim() : '';
+          return JSON.stringify({ ...fm, goal });
+        },
+      }),
+
+      foundry_workfile_set: tool({
+        description: 'Update a single frontmatter field in WORK.md',
+        args: {
+          key: tool.schema.string().describe('Frontmatter key'),
+          value: tool.schema.any().describe('Value to set'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (!existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md not found' });
+          }
+          const text = readFileSync(workPath, 'utf-8');
+          const updated = setFrontmatterField(text, args.key, args.value);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_workfile_delete: tool({
+        description: 'Delete WORK.md',
+        args: {},
+        async execute(_args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (existsSync(workPath)) {
+            unlinkSync(workPath);
+          }
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      // ── Artefacts tools ──
+      foundry_artefacts_add: tool({
+        description: 'Add an artefact row to the WORK.md table',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          type: tool.schema.string().describe('Artefact type'),
+          cycle: tool.schema.string().describe('Cycle name'),
+          status: tool.schema.string().optional().describe('Status (default: draft)'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const text = readFileSync(workPath, 'utf-8');
+          const updated = addArtefactRow(text, { file: args.file, type: args.type, cycle: args.cycle, status: args.status || 'draft' });
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_artefacts_set_status: tool({
+        description: 'Update the status of an artefact in WORK.md',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          status: tool.schema.string().describe('New status'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const text = readFileSync(workPath, 'utf-8');
+          const updated = setArtefactStatus(text, args.file, args.status);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_artefacts_list: tool({
+        description: 'List all artefacts from the WORK.md table',
+        args: {},
+        async execute(_args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (!existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md not found' });
+          }
+          const text = readFileSync(workPath, 'utf-8');
+          return JSON.stringify(parseArtefactsTable(text));
+        },
+      }),
+
+      // ── Feedback tools ──
+      foundry_feedback_add: tool({
+        description: 'Add a feedback item to WORK.md under a file heading',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          text: tool.schema.string().describe('Feedback text'),
+          tag: tool.schema.string().describe('Tag for the feedback item'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const content = readFileSync(workPath, 'utf-8');
+          const updated = addFeedbackItem(content, args.file, args.text, args.tag);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_feedback_action: tool({
+        description: 'Mark a feedback item as actioned [x]',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          index: tool.schema.number().describe('Zero-based index of the feedback item'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const content = readFileSync(workPath, 'utf-8');
+          const updated = actionFeedbackItem(content, args.file, args.index);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_feedback_wontfix: tool({
+        description: 'Mark a feedback item as wont-fix [~] with reason',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          index: tool.schema.number().describe('Zero-based index of the feedback item'),
+          reason: tool.schema.string().describe('Reason for wont-fix'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const content = readFileSync(workPath, 'utf-8');
+          const updated = wontfixFeedbackItem(content, args.file, args.index, args.reason);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_feedback_resolve: tool({
+        description: 'Resolve a feedback item (approved or rejected)',
+        args: {
+          file: tool.schema.string().describe('Artefact file path'),
+          index: tool.schema.number().describe('Zero-based index of the feedback item'),
+          resolution: tool.schema.enum(['approved', 'rejected']).describe('Resolution type'),
+          reason: tool.schema.string().optional().describe('Reason (required if rejected)'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          const content = readFileSync(workPath, 'utf-8');
+          const updated = resolveFeedbackItem(content, args.file, args.index, args.resolution, args.reason);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        },
+      }),
+
+      foundry_feedback_list: tool({
+        description: 'List feedback items, optionally filtered by file',
+        args: {
+          file: tool.schema.string().optional().describe('Filter by artefact file path'),
+        },
+        async execute(args, context) {
+          const workPath = path.join(context.worktree, 'WORK.md');
+          if (!existsSync(workPath)) {
+            return JSON.stringify({ error: 'WORK.md not found' });
+          }
+          const text = readFileSync(workPath, 'utf-8');
+          const fm = parseFrontmatter(text);
+          const artefacts = parseArtefactsTable(text);
+          const cycle = fm.cycle || '';
+          return JSON.stringify(listFeedback(text, cycle, artefacts, args.file));
+        },
+      }),
+
+      // ── Sort tool ──
+      foundry_sort: tool({
+        description: 'Run sort routing to determine the next stage',
+        args: {
+          cycleDef: tool.schema.string().optional().describe('Path to cycle definition file'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = runSort({ cycleDef: args.cycleDef }, io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      // ── Git tools ──
+      foundry_git_branch: tool({
+        description: 'Create and checkout a work branch for a flow',
+        args: {
+          flowId: tool.schema.string().describe('Flow ID'),
+          description: tool.schema.string().describe('Branch description suffix'),
+        },
+        async execute(args, context) {
+          const branch = `work/${args.flowId}-${args.description}`;
+          execSync(`git checkout -b ${branch}`, { cwd: context.worktree, encoding: 'utf8' });
+          return JSON.stringify({ ok: true, branch });
+        },
+      }),
+
+      foundry_git_commit: tool({
+        description: 'Stage all changes and commit with a cycle-prefixed message',
+        args: {
+          cycle: tool.schema.string().describe('Cycle name'),
+          stage: tool.schema.string().describe('Stage name'),
+          description: tool.schema.string().describe('Commit description'),
+        },
+        async execute(args, context) {
+          execSync('git add .', { cwd: context.worktree, encoding: 'utf8' });
+          const msg = `[${args.cycle}] ${args.stage}: ${args.description}`;
+          execSync(`git commit -m "${msg.replace(/"/g, '\\"')}"`, { cwd: context.worktree, encoding: 'utf8' });
+          const hash = execSync('git rev-parse --short HEAD', { cwd: context.worktree, encoding: 'utf8' }).trim();
+          return JSON.stringify({ ok: true, hash });
+        },
+      }),
+
+      // ── Config tools ──
+      foundry_config_cycle: tool({
+        description: 'Get a cycle definition from foundry config',
+        args: {
+          cycleId: tool.schema.string().describe('Cycle ID'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = await getCycleDefinition('foundry', args.cycleId, io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      foundry_config_artefact_type: tool({
+        description: 'Get an artefact type definition',
+        args: {
+          typeId: tool.schema.string().describe('Artefact type ID'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = await getArtefactType('foundry', args.typeId, io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      foundry_config_laws: tool({
+        description: 'Get laws, optionally filtered by artefact type',
+        args: {
+          typeId: tool.schema.string().optional().describe('Artefact type ID'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = args.typeId
+            ? await getLaws('foundry', args.typeId, io)
+            : await getLaws('foundry', io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      foundry_config_validation: tool({
+        description: 'Get validation commands for an artefact type',
+        args: {
+          typeId: tool.schema.string().describe('Artefact type ID'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = await getValidation('foundry', args.typeId, io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      foundry_config_appraisers: tool({
+        description: 'List all appraisers',
+        args: {},
+        async execute(_args, context) {
+          const io = makeIO(context.worktree);
+          const result = await getAppraisers('foundry', io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      foundry_config_flow: tool({
+        description: 'Get a flow definition',
+        args: {
+          flowId: tool.schema.string().describe('Flow ID'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = await getFlow('foundry', args.flowId, io);
+          return JSON.stringify(result);
+        },
+      }),
+
+      // ── Validate tool ──
+      foundry_validate_run: tool({
+        description: 'Run validation commands for an artefact type against a file',
+        args: {
+          typeId: tool.schema.string().describe('Artefact type ID'),
+          file: tool.schema.string().describe('File path to validate'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const commands = await getValidation('foundry', args.typeId, io);
+          if (!commands) return JSON.stringify({ error: 'No validation defined for type: ' + args.typeId });
+          const results = [];
+          for (const cmd of commands) {
+            const expanded = cmd.replace(/\{file\}/g, args.file);
+            try {
+              const output = execSync(expanded, { cwd: context.worktree, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+              results.push({ command: expanded, passed: true, output: output.trim() });
+            } catch (err) {
+              results.push({ command: expanded, passed: false, output: (err.stderr || err.stdout || err.message || '').trim() });
+            }
+          }
+          return JSON.stringify(results);
+        },
+      }),
+
+      // ── Appraiser selection tool ──
+      foundry_appraisers_select: tool({
+        description: 'Select appraisers for an artefact type',
+        args: {
+          typeId: tool.schema.string().describe('Artefact type ID'),
+          count: tool.schema.number().optional().describe('Number of appraisers to select'),
+        },
+        async execute(args, context) {
+          const io = makeIO(context.worktree);
+          const result = args.count
+            ? await selectAppraisers('foundry', args.typeId, args.count, io)
+            : await selectAppraisers('foundry', args.typeId, io);
+          return JSON.stringify(result);
+        },
+      }),
+    },
   };
 };

package/README.md

@@ -53,6 +53,23 @@ A **foundry flow** runs one or more **foundry cycles** in sequence. Each cycle p
 
 All state lives in `WORK.md` on a dedicated work branch. Every stage micro-commits, and file modification enforcement ensures stages only touch what they're allowed to.
 
+## Custom tools
+
+The Foundry plugin exposes 25 custom tools that handle all deterministic pipeline operations. Skills call these tools instead of manipulating files directly — this eliminates LLM interpretation of file formats and ensures consistent state management.
+
+| Category | Tools |
+|----------|-------|
+| **Workfile** | `foundry_workfile_create`, `foundry_workfile_get`, `foundry_workfile_set`, `foundry_workfile_delete` |
+| **Artefacts** | `foundry_artefacts_add`, `foundry_artefacts_list`, `foundry_artefacts_set_status` |
+| **Feedback** | `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, `foundry_feedback_resolve`, `foundry_feedback_list` |
+| **History** | `foundry_history_append`, `foundry_history_list` |
+| **Sort** | `foundry_sort` |
+| **Config** | `foundry_config_cycle`, `foundry_config_artefact_type`, `foundry_config_laws`, `foundry_config_validation`, `foundry_config_appraisers`, `foundry_config_flow` |
+| **Validation** | `foundry_validate_run`, `foundry_appraisers_select` |
+| **Git** | `foundry_git_branch`, `foundry_git_commit` |
+
+Tools are backed by shared library modules in `scripts/lib/` that use injectable I/O for testability. The sort routing engine (`scripts/sort.js`) exports `runSort()` for the sort tool.
+
 ## Core concepts
 
 ### Foundry Flows
@@ -170,7 +187,7 @@ All helper skills are interactive — they walk you through the process, check f
 @really-knows-ai/foundry
 ├── .opencode/
 │   └── plugins/
-│       └── foundry.js          # OpenCode plugin (registers skills)
+│       └── foundry.js          # OpenCode plugin (skills + 25 custom tools)
 ├── skills/                     # skill definitions (the pipeline)
 │   ├── forge/
 │   ├── quench/
@@ -185,7 +202,16 @@ All helper skills are interactive — they walk you through the process, check f
 │   ├── add-flow/
 │   ├── sort/
 │   └── hitl/
-├── scripts/                    # validation support scripts
+├── scripts/                    # shared library and routing engine
+│   ├── lib/
+│   │   ├── workfile.js         # WORK.md frontmatter parsing/writing
+│   │   ├── artefacts.js        # artefacts table operations
+│   │   ├── history.js          # WORK.history.yaml operations
+│   │   ├── feedback.js         # feedback lifecycle operations
+│   │   ├── config.js           # foundry/ config readers
+│   │   └── tags.js             # tag extraction
+│   └── sort.js                 # deterministic routing engine (exports runSort)
+├── tests/                      # test suite (node:test)
 ├── docs/                       # concept docs and specs
 ├── package.json
 └── README.md
@@ -217,13 +243,13 @@ your-project/
 
 Flow definitions, cycle definitions, artefact types, laws, appraiser personalities, skills — all markdown. Readable by humans, consumable by LLMs, versionable in git. No config files, no databases, no custom formats.
 
-### Skills are the pipeline
+### Skills are the pipeline, tools are the machinery
 
-No separate runner script. Composition happens via skills referencing other skills. The `flow` skill reads a flow definition and invokes the `cycle` skill. The `cycle` skill invokes `forge`, `quench`, and `appraise`. This keeps everything in one format.
+Composition happens via skills referencing other skills. The `flow` skill reads a flow definition and invokes the `cycle` skill. The `cycle` skill invokes `forge`, `quench`, and `appraise`. Skills handle creative and subjective work; deterministic operations (parsing, routing, state updates) are handled by custom tools backed by shared library code.
 
 ### WORK.md as shared state
 
-All communication between stages goes through WORK.md. No stage passes output directly to another. This gives a complete audit trail, makes the process resumable, and means any stage can be re-run independently.
+All communication between stages goes through WORK.md. No stage passes output directly to another — all reads and writes go through the `foundry_workfile_*`, `foundry_artefacts_*`, and `foundry_feedback_*` tools. This gives a complete audit trail, makes the process resumable, and means any stage can be re-run independently.
 
 ### Feedback as checklist items
 

package/docs/concepts.md

@@ -52,4 +52,8 @@ Human-in-the-loop checkpoint. A stage type that pauses the foundry cycle and req
 
 ## Micro commit
 
-Every stage ends with a commit. This enables file modification enforcement — the foundry cycle checks the git diff to ensure each stage only touched files it was allowed to.
+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/work-spec.md

@@ -95,11 +95,11 @@ Grouped by artefact file path. Each item is a checklist entry with a tag indicat
 
 | Section | Written by | Updated by |
 |---------|-----------|------------|
-| Frontmatter (`flow`) | foundry flow skill | nobody |
-| Frontmatter (`cycle`, `stages`, `max-iterations`) | foundry cycle skill | foundry cycle skill (reset on each new cycle) |
-| Goal | foundry flow skill | nobody |
-| Artefacts | forge skill (registers new) | foundry cycle skill (status changes) |
-| Feedback | quench skill, appraise skill, hitl skill | forge skill (actioned/wont-fix), quench/appraise/hitl skill (approved/rejected) |
+| Frontmatter (`flow`) | `foundry_workfile_create` (flow skill) | nobody |
+| Frontmatter (`cycle`, `stages`, `max-iterations`) | `foundry_workfile_set` (cycle 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` (cycle skill) |
+| Feedback | `foundry_feedback_add` (quench/appraise/hitl) | `foundry_feedback_action`/`foundry_feedback_wontfix` (forge), `foundry_feedback_resolve` (quench/appraise/hitl) |
 
 ## WORK.history.yaml
 
@@ -149,12 +149,12 @@ A separate file (`WORK.history.yaml`) alongside WORK.md. Append-only log of ever
 
 - Append-only — never edit or delete entries
 - Every stage skill appends an entry when it completes
-- The sort script reads this to determine what has happened in the current foundry cycle
+- 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.
+Every stage skill (forge, quench, appraise, hitl) appends an entry when it finishes via the `foundry_history_append` tool.
 
 ## Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",
@@ -25,7 +25,7 @@
     "node": ">=18.3.0"
   },
   "scripts": {
-    "test": "node --test tests/sort.test.js"
+    "test": "node --test tests/**/*.test.js"
   },
   "dependencies": {
     "js-yaml": "^4.1.0",

package/scripts/lib/artefacts.js

@@ -0,0 +1,118 @@
+/**
+ * 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) {
+  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');
+}