@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/scripts/sort.js

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+
+/**
+ * Sort — deterministic routing for a Foundry Cycle.
+ *
+ * Reads WORK.md, WORK.feedback.yaml, and WORK.history.yaml to determine
+ * the next stage to execute, or signal completion/blocked.
+ *
+ * Usage:
+ *     node scripts/sort.js [--work WORK.md] [--history WORK.history.yaml]
+ *
+ * Output (stdout): a full stage alias (e.g., forge:write-haiku), 'done', or 'blocked'
+ * Exit code: 0 on success, 1 on error
+ */
+
+import { parseFrontmatter } from './lib/workfile.js';
+import { loadHistory } from './lib/history.js';
+import { openFeedbackStore } from './lib/feedback-store.js';
+import { ulid as defaultUlid } from './lib/ulid.js';
+import {
+  baseStage,
+  findFirst,
+  determineRoute,
+} from './lib/sort-routing.js';
+import {
+  defaultIO,
+  checkModifiedFiles,
+  getDirtyToolManagedFiles,
+} from './lib/sort-fs-check.js';
+
+// ---------------------------------------------------------------------------
+// Top-level deadlock pass (spec §6.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk the feedback store and write a `state=deadlocked` snapshot for every
+ * non-resolved item whose history depth has reached the configured threshold.
+ * One atomic batch write via `store.writeDeadlockedSnapshots(ids, ...)`.
+ *
+ * Sort is the only writer of `state=deadlocked` per spec §6.1.
+ *
+ * @returns {boolean} true iff at least one snapshot was written.
+ */
+function runDeadlockPass(store, { threshold, enabled, cycle }) {
+  if (!enabled) return false;
+  const qualifying = store.list().filter(item => {
+    // history[0] is the most recent state per the feedback-store invariant
+    // (entries are prepended to keep newest at head).
+    const head = item.history[0];
+    if (head.state === 'resolved' || head.state === 'deadlocked') return false;
+    return item.history.length >= threshold;
+  });
+  if (qualifying.length === 0) return false;
+  store.writeDeadlockedSnapshots(
+    qualifying.map(it => it.id),
+    `depth >= threshold=${threshold}`,
+    'sort',
+    cycle,
+  );
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// runSort — structured result for programmatic use
+// ---------------------------------------------------------------------------
+
+function isDispatchableRoute(route) {
+  return typeof route === 'string' && /^(assay|forge|quench|appraise|human-appraise):/.test(route);
+}
+
+function validateStages(stages) {
+  if (!stages || !Array.isArray(stages)) return { error: 'No stages in WORK.md frontmatter' };
+  if (!findFirst(stages, 'forge')) return { error: 'stages must include at least one forge stage' };
+  return null;
+}
+
+function validateWorkMd(workPath, io) {
+  if (!io.exists(workPath)) return { error: 'WORK.md not found' };
+  const workText = io.readFile(workPath);
+  const frontmatter = parseFrontmatter(workText);
+  if (!frontmatter.cycle) return { error: 'No cycle in WORK.md frontmatter' };
+  const stagesError = validateStages(frontmatter.stages);
+  if (stagesError) return stagesError;
+  return { frontmatter, cycle: frontmatter.cycle, stages: frontmatter.stages };
+}
+
+function extractFrontmatterDefaults(frontmatter) {
+  return {
+    maxIterations: frontmatter['max-iterations'] ?? 3,
+    humanAppraiseEnabled: frontmatter['human-appraise'] === true,
+    deadlockAppraise: frontmatter['deadlock-appraise'] !== false,
+    deadlockIterations: frontmatter['deadlock-iterations'] ?? 5,
+  };
+}
+
+function checkDirtyFiles(history, io) {
+  if (history.length === 0) return null;
+  const dirty = getDirtyToolManagedFiles(io);
+  if (dirty.length === 0) return null;
+  return `Uncommitted tool-managed files since last sort: ${dirty.join(', ')}. `
+    + `Each stage's commit is performed internally by foundry_orchestrate; `
+    + `if you see this, the prior stage's commit was skipped or aborted. `
+    + `Re-run foundry_orchestrate or commit the listed files manually before retrying.`;
+}
+
+function loadFeedbackAndRunDeadlock(cycle, deadlockIterations, deadlockAppraise, io) {
+  const store = openFeedbackStore('WORK.feedback.yaml', io);
+  runDeadlockPass(store, { threshold: deadlockIterations, enabled: deadlockAppraise, cycle });
+  const feedback = store.list().map(item => ({
+    id: item.id,
+    file: item.file,
+    state: item.history[0].state,
+    depth: item.history.length,
+  }));
+  const anyDeadlocked = feedback.some(f => f.state === 'deadlocked');
+  return { feedback, anyDeadlocked };
+}
+
+function resolveCycleDef(cycleDef, frontmatter, foundryDir, cycle) {
+  return cycleDef || frontmatter['cycle-def'] || `${foundryDir}/cycles/${cycle}.md`;
+}
+
+function checkModifiedFilesAfterLastStage({ history, foundryDir, cycleDef, cycle, frontmatter, io }) {
+  const nonSortHistory = history.filter(e => baseStage(e.stage || '') !== 'sort');
+  if (nonSortHistory.length === 0) return { nonSortHistory };
+  const lastBase = baseStage(nonSortHistory[nonSortHistory.length - 1].stage || '');
+  const resolvedCycleDef = resolveCycleDef(cycleDef, frontmatter, foundryDir, cycle);
+  const result = checkModifiedFiles(lastBase, foundryDir, resolvedCycleDef, cycle, io);
+  if (!result.ok) {
+    return { error: `File modification violation after ${lastBase} stage: ${result.violations.join(', ')}` };
+  }
+  return { nonSortHistory };
+}
+
+function getCurrentNonSortStage(nonSortHistory) {
+  return nonSortHistory.length > 0 ? nonSortHistory[nonSortHistory.length - 1].stage : null;
+}
+
+function resolveDeadlockRoute(stages, nonSortHistory, cycle) {
+  const currentNonSort = getCurrentNonSortStage(nonSortHistory);
+  if (currentNonSort && baseStage(currentNonSort) === 'human-appraise') return 'blocked';
+  return findFirst(stages, 'human-appraise') || `human-appraise:${cycle}`;
+}
+
+function resolveRoute(ctx) {
+  if (ctx.anyDeadlocked) return resolveDeadlockRoute(ctx.stages, ctx.nonSortHistory, ctx.cycle);
+  return determineRoute(ctx.stages, ctx.history, ctx.feedback, ctx.maxIterations);
+}
+
+function resolveModel(route, frontmatter, agentsDir, io) {
+  const routeBase = baseStage(route);
+  if (!frontmatter.models || !frontmatter.models[routeBase]) return null;
+  const modelId = frontmatter.models[routeBase];
+  const model = `foundry-${modelId.replace(/[/.]/g, '-')}`;
+  const agentPath = `${agentsDir}/${model}.md`;
+  if (!io.exists(agentPath)) {
+    return {
+      error: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. `
+        + `Run the refresh-agents skill to regenerate agent files, then restart.`,
+    };
+  }
+  return model;
+}
+
+function checkModel(route, frontmatter, agentsDir, io) {
+  const modelResult = resolveModel(route, frontmatter, agentsDir, io);
+  if (modelResult && modelResult.error) return { error: modelResult.error };
+  return { model: typeof modelResult === 'string' ? modelResult : null };
+}
+
+function mintToken({ route, model, mint, cycle, now, ulid }) {
+  const result = { route, ...(model ? { model } : {}) };
+  if (mint && isDispatchableRoute(route)) {
+    const token = mint({ route, cycle, exp: now + 10 * 60 * 1000, nonce: ulid(now) });
+    if (token) result.token = token;
+  }
+  return result;
+}
+
+// runSort is decomposed into single-purpose phase helpers above so the
+// orchestrating function itself stays within the configured complexity
+// limit. Each phase either returns an error envelope (handled by
+// firstError) or contributes data to the routing decision.
+
+function firstError(...envelopes) {
+  for (const env of envelopes) {
+    if (env && env.error) return env.error;
+  }
+  return null;
+}
+
+function preparePhases({ workPath, historyPath, foundryDir, cycleDef, io }) {
+  const validation = validateWorkMd(workPath, io);
+  if (validation.error) return { kind: 'blocked', details: validation.error };
+  const { frontmatter, cycle, stages } = validation;
+  const defaults = extractFrontmatterDefaults(frontmatter);
+  const history = loadHistory(historyPath, cycle, io);
+  const dirtyError = checkDirtyFiles(history, io);
+  if (dirtyError) return { kind: 'violation', details: dirtyError };
+  const { feedback, anyDeadlocked } = loadFeedbackAndRunDeadlock(
+    cycle, defaults.deadlockIterations, defaults.deadlockAppraise, io,
+  );
+  const fileCheck = checkModifiedFilesAfterLastStage({
+    history, foundryDir, cycleDef, cycle, frontmatter, io,
+  });
+  const violation = firstError(fileCheck);
+  if (violation) return { kind: 'violation', details: violation };
+  return {
+    kind: 'ok',
+    frontmatter, cycle, stages, defaults, history, feedback, anyDeadlocked,
+    nonSortHistory: fileCheck.nonSortHistory,
+  };
+}
+
+const RUN_SORT_DEFAULTS = Object.freeze({
+  workPath: 'WORK.md',
+  historyPath: 'WORK.history.yaml',
+  foundryDir: 'foundry',
+  cycleDef: undefined,
+  agentsDir: '.opencode/agents',
+  mint: undefined,
+});
+
+function withRunSortDefaults(args) {
+  const merged = { ...RUN_SORT_DEFAULTS, ...args };
+  if (merged.now === undefined) merged.now = Date.now();
+  if (merged.ulid === undefined) merged.ulid = defaultUlid;
+  return merged;
+}
+
+function buildRouteCtx(prep) {
+  return {
+    stages: prep.stages,
+    history: prep.history,
+    feedback: prep.feedback,
+    maxIterations: prep.defaults.maxIterations,
+    cycle: prep.cycle,
+    anyDeadlocked: prep.anyDeadlocked,
+    nonSortHistory: prep.nonSortHistory,
+  };
+}
+
+export function runSort(args = {}, io = defaultIO) {
+  const opts = withRunSortDefaults(args);
+  const prep = preparePhases({ ...opts, io });
+  if (prep.kind !== 'ok') return { route: prep.kind, details: prep.details };
+
+  const route = resolveRoute(buildRouteCtx(prep));
+  const modelCheck = checkModel(route, prep.frontmatter, opts.agentsDir, io);
+  if (modelCheck.error) return { route: 'violation', details: modelCheck.error };
+
+  return mintToken({
+    route, model: modelCheck.model, mint: opts.mint, cycle: prep.cycle, now: opts.now, ulid: opts.ulid,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing) — keep main() private
+// ---------------------------------------------------------------------------
+
+export { parseArtefactsTable } from './lib/artefacts.js';
+export { loadHistory } from './lib/history.js';
+export { parseFrontmatter } from './lib/workfile.js';
+export {
+  baseStage,
+  findFirst,
+  nextInRoute,
+  determineRoute,
+  nextAfterQuench,
+  nextAfterAppraise,
+} from './lib/sort-routing.js';
+export {
+  globMatch,
+  getModifiedFiles,
+  getAllowedPatterns,
+  checkModifiedFiles,
+  getDirtyToolManagedFiles,
+} from './lib/sort-fs-check.js';

package/{skills → dist/skills}/add-appraiser/SKILL.md

@@ -10,15 +10,32 @@ You help the user create a new appraiser personality. You ensure it's genuinely
 
 ## Prerequisites
 
-Before running this skill, verify both of the following:
+Before running this skill, verify all three of the following:
 
-1. The `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
 
-2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
 
-   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
 
 ## Protocol
 
@@ -87,11 +104,25 @@ Iterate until the user is happy with the personality description. Key things to
 - Does the description give the LLM enough direction to adopt a consistent voice?
 - Is it clear what this appraiser would flag vs let pass?
 
-### 6. Write the file
+### 6. Validate the draft
+
+Call `foundry_config_validate_appraiser({ name: "<id>", body: "<full markdown>" })`.
+
+If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+
+### 7. Create the file
+
+Call `foundry_config_create_appraiser({ name: "<id>", body: "<full markdown>" })`. The tool:
+
+- re-validates the body (TOCTOU);
+- writes `foundry/appraisers/<id>.md`;
+- produces one git commit on the current `config/*` branch.
+
+If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_appraiser` does not support updates.
 
-Create `foundry/appraisers/<id>.md` with the agreed definition.
+Show the user the resulting commit hash from the response.
 
-### 7. Mention artefact type configuration
+### 8. Mention artefact type configuration
 
 After creating the appraiser, remind the user:
 
@@ -107,7 +138,6 @@ After creating the appraiser, remind the user:
 
 ## What you do NOT do
 
-- You do not write files without showing the user first
 - You do not skip the semantic overlap check
 - You do not modify artefact type definitions — that is the user's choice
 - You do not create appraisers with duplicate ids

package/{skills → dist/skills}/add-artefact-type/SKILL.md

@@ -10,15 +10,32 @@ You help the user create a new artefact type. You ensure it doesn't conflict wit
 
 ## Prerequisites
 
-Before running this skill, verify both of the following:
+Before running this skill, verify all three of the following:
 
-1. The `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
 
-2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
 
-   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
 
 ## Protocol
 
@@ -27,8 +44,7 @@ Before running this skill, verify both of the following:
 From the user's prompt, establish:
 - `id` — lowercase, hyphenated identifier
 - `name` — human-readable name
-- `file-patterns` — glob patterns for files this type produces
-- `output` — output directory
+- `file-patterns` — glob patterns for files this type produces (forge's write scope is exactly these patterns)
 - A prose description of what this artefact type is
 
 If any of these are missing, ask.
@@ -71,16 +87,12 @@ Present the definition to the user:
 
 ```markdown
 ---
-id: <id>
 name: <name>
 file-patterns:
   - "<pattern>"
-output: <output-dir>
-appraisers:
-  count: 3
 ---
 
-# <Name>
+## Definition
 
 <description>
 ```
@@ -143,26 +155,36 @@ Check the project's `package.json` for `"type": "module"`:
 - If CommonJS (no `"type"` field or `"type": "commonjs"`): `require()` is fine, or use `.cjs` extension
 - When in doubt, use `.mjs` or `.cjs` extensions to be explicit regardless of project settings
 
-### 8. Scaffold
+### 8. Validate the draft
 
-Create the directory and files:
+Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<full markdown>" })`.
 
-```
-foundry/artefacts/<id>/
-  definition.md      # always created
-  laws.md            # created if laws were defined
-  validation.md      # created if validation commands were defined
-```
+If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+
+### 9. Create the file
+
+Call `foundry_config_create_artefact_type({ name: "<id>", body: "<full markdown>" })`. The tool:
+
+- re-validates the body (TOCTOU);
+- writes `foundry/artefacts/<id>/definition.md`;
+- produces one git commit on the current `config/*` branch.
+
+If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_artefact_type` does not support updates.
+
+Show the user the resulting commit hash from the response.
+
+### 10. Add laws and validation files (if defined)
+
+The create tool writes only `definition.md`. If you drafted any type-specific laws in step 5, append them to `foundry/artefacts/<id>/laws.md` by hand on this same `config/*` branch (use the `Edit` tool to create the file) and commit that as a separate microcommit.
 
-If laws or validation were skipped, do not create empty files.
+If you drafted validation commands in step 7, write `foundry/artefacts/<id>/validation.md` (and any companion validation script files) by hand and commit as a separate microcommit.
 
-### 9. Confirm
+### 11. Confirm
 
-Show the user the complete file listing and contents. Confirm before writing.
+Show the user the complete file listing and the commit hashes.
 
 ## What you do NOT do
 
 - You do not create artefact types with overlapping file patterns — this is a hard block
-- You do not write files without showing the user first
 - You do not skip the naming or glob checks
 - You do not create laws without checking for conflicts (delegate to add-law pattern)

package/{skills → dist/skills}/add-cycle/SKILL.md

@@ -10,15 +10,32 @@ You help the user create a new foundry cycle and add it to an existing foundry f
 
 ## Prerequisites
 
-Before running this skill, verify both of the following:
+Before running this skill, verify all three of the following:
 
-1. The `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
 
-   > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
 
-2. The current git branch is not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
 
-   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
 
 ## Protocol
 
@@ -33,7 +50,7 @@ Verify the flow exists. If it doesn't, tell the user and ask if they want to cre
 From the user's prompt, establish:
 - `id` — lowercase, hyphenated identifier for the foundry cycle
 - `name` — human-readable name
-- `output` — the artefact type this foundry cycle produces (must exist in `foundry/artefacts/`)
+- `output-type` — the artefact type this foundry cycle produces (must exist in `foundry/artefacts/`)
 - `inputs` — artefact types this cycle reads, with a contract type:
   - `type`: `any-of` (at least one must exist) or `all-of` (all must exist)
   - `artefacts`: list of artefact type IDs
@@ -72,7 +89,7 @@ Ask the user:
 
 ### 5. Validate artefact types
 
-For `output` and each entry in `inputs`:
+For `output-type` and each entry in `inputs`:
 - Verify the artefact type exists in `foundry/artefacts/<type>/definition.md`
 - If it doesn't, tell the user and ask if they want to create it first (separate skill)
 
@@ -81,12 +98,12 @@ For `output` and each entry in `inputs`:
 Read the flow definition from `foundry/flows/<flow-id>.md`. Check:
 
 - No existing foundry cycle in the foundry flow already outputs the same artefact type. Two foundry cycles producing the same type in one foundry flow is a conflict — the file modification enforcement can't distinguish which foundry cycle owns the files.
-- Each `input` artefact type is produced by an earlier foundry cycle in the foundry flow. If an input references an artefact type that no prior foundry cycle outputs, warn:
+- Each `input` artefact type is produced by some cycle that can run before this one according to the flow's `targets` graph (a reachable predecessor). If an input references an artefact type that no reachable predecessor outputs, warn:
 
-> Input `<type>` is not produced by any earlier foundry cycle in this foundry flow. The artefact won't exist when this foundry cycle runs.
+> Input `<type>` is not produced by any reachable predecessor of this foundry cycle in the flow's `targets` graph. The artefact won't exist when this foundry cycle runs.
 >
 > Options:
-> 1. Add a foundry cycle that produces `<type>` before this one
+> 1. Add a foundry cycle that produces `<type>` and route to this cycle via `targets`
 > 2. Remove `<type>` from inputs (this foundry cycle won't have that context)
 > 3. Proceed anyway (the artefact may exist from a previous foundry flow run)
 
@@ -112,7 +129,7 @@ Present the foundry cycle definition to the user:
 ---
 id: <id>
 name: <name>
-output: <artefact-type-id>
+output-type: <artefact-type-id>
 inputs:
   type: <any-of|all-of>
   artefacts:
@@ -144,19 +161,42 @@ For input validation:
 - Verify that at least one cycle in the flow has the input artefact type(s) as its output
 - If using `all-of`, verify all input types are producible
 
-### 11. Write files
+### 11. Validate the draft
+
+Call `foundry_config_validate_cycle({ name: "<id>", body: "<full markdown>" })`.
+
+If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+
+### 12. Create the cycle file
+
+Call `foundry_config_create_cycle({ name: "<id>", body: "<full markdown>" })`. The tool:
+
+- re-validates the body (TOCTOU);
+- writes `foundry/cycles/<id>.md`;
+- produces one git commit on the current `config/*` branch.
 
-- Create `foundry/cycles/<id>.md` with the cycle definition
-- Update `foundry/flows/<flow-id>.md` to add the cycle to the `## Cycles` list (if not already present)
+If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_cycle` does not support updates.
+
+Show the user the resulting commit hash from the response.
+
+### 13. Add the cycle to the flow's cycle list
+
+`foundry_config_create_cycle` writes the cycle file only. The cycle still needs to appear in the parent flow's `## Cycles` list.
+
+Edit `foundry/flows/<flow-id>.md` by hand on this same `config/*` branch using the `Edit` tool. Add the new cycle id under `## Cycles` (if not already present). Commit that edit by hand as a separate microcommit, e.g.:
+
+```
+git add foundry/flows/<flow-id>.md
+git commit -m "config(flow): add <cycle-id> to <flow-id>"
+```
 
-### 12. Confirm
+### 14. Confirm
 
-Show the user the created/modified files and their contents.
+Show the user the cycle file, the updated flow file, and both commit hashes.
 
 ## What you do NOT do
 
 - You do not create foundry cycles that output an artefact type already produced by another foundry cycle in the same foundry flow
-- You do not write files without showing the user first
 - You do not skip artefact type validation
 - You do not create artefact types — that is a separate skill
 - You do not create foundry flows — that is a separate skill