@really-knows-ai/foundry 3.2.7 → 3.3.0

package/dist/.opencode/plugins/foundry-tools/config-create-tools.js

@@ -53,19 +53,42 @@ const VALIDATE_GUARDS = [gitRepoGuard, foundryRootGuard];
 
 // --- tool factories --------------------------------------------------------
 
-// Module-level helper: returns a `makeCreate` function bound to `tool` and `baseArgs`.
-function createMakeCreate(tool, baseArgs) {
-  return function makeCreate(toolName, creator, extraArgs = {}) {
-    const kind = toolName.replace('foundry_config_create_', '');
-    let desc = `Create a new ${kind} definition (config-tier; requires a config/* branch).`;
+const TYPE_NAMES = {
+  ZodString: 'string',
+  ZodArray: 'string[]',
+  ZodBoolean: 'boolean',
+  ZodNumber: 'number',
+  ZodObject: 'object',
+  ZodEnum: 'string',
+};
+
+function unwrapOptional(schema) {
+  let s = schema;
+  while (s._def && s._def.typeName === 'ZodOptional') s = s._def.innerType;
+  return s;
+}
+
+function describeField(name, schema) {
+  const inner = unwrapOptional(schema);
+  const type = inner._def ? (TYPE_NAMES[inner._def.typeName] || 'any') : 'any';
+  const required = schema._def && schema._def.required !== false;
+  return required ? `${name} (${type})` : `${name} (${type}, optional)`;
+}
+
+function humaniseKind(kind) {
+  return kind.replace(/_/g, '-');
+}
 
-    if (kind === 'law') {
-      desc += ' target must be {kind:"global", file:"<name>.md"} or {kind:"type-specific", typeId:"<id>"}.';
-    }
+// Module-level helper: returns a `makeCreate` function bound to `tool`.
+function createMakeCreate(tool) {
+  return function makeCreate(toolName, creator, createArgs) {
+    const kind = humaniseKind(toolName.replace('foundry_config_create_', ''));
+    const fieldSummary = Object.keys(createArgs).map(k => describeField(k, createArgs[k])).join(', ');
+    const description = `Create a new ${kind} definition (config-tier; requires a config/* branch).\nFields: ${fieldSummary}`;
 
     return tool({
-      description: desc,
-      args: { ...baseArgs, ...extraArgs },
+      description,
+      args: createArgs,
       execute: guarded(toolName, CREATE_GUARDS, async (args, context) => {
         try {
           const io = makeAsyncIO(context.worktree);
@@ -104,20 +127,69 @@ function createMakeValidate(tool, baseArgs) {
 
 // --- tool factory ---------------------------------------------------------
 
+// Per-tool arg schemas (defined outside createConfigCreateTools to keep it under 40 lines).
+function artefactTypeArgs(s) { return {
+  id: s.string().describe('Slugged identifier used as directory name under foundry/artefacts/'),
+  name: s.string().describe('Human-readable display name (accepted at boundary, not persisted — id becomes frontmatter.name)'),
+  filePatterns: s.array(s.string()).describe('Glob patterns defining forge write scope (written to frontmatter.file-patterns)'),
+  description: s.string().describe('Prose description placed under ## Definition'),
+  appraisers: s.object({
+    count: s.number().optional().describe('Number of appraisers per cycle'),
+    allowed: s.array(s.string()).optional().describe('Restrict to specific appraiser IDs'),
+  }).optional().describe('Appraiser selection config'),
+}; }
+
+function appraiserArgs(s) { return {
+  id: s.string().describe('Slugged identifier matching the filename under foundry/appraisers/'),
+  name: s.string().describe('Human-readable display name written to frontmatter.name'),
+  description: s.string().describe('Prose personality description placed after frontmatter'),
+  model: s.string().optional().describe('Optional model override for this appraiser (e.g. openai/gpt-4o)'),
+}; }
+
+function flowArgs(s) { return {
+  id: s.string().describe('Slugged identifier matching the filename under foundry/flows/'),
+  name: s.string().describe('Human-readable display name written to frontmatter.name'),
+  startingCycles: s.array(s.string()).describe('Non-empty array of cycle IDs that can start this flow'),
+  description: s.string().describe('Prose description placed under ## Cycles'),
+}; }
+
+function cycleArgs(s) { return {
+  id: s.string().describe('Slugged identifier matching the filename under foundry/cycles/'),
+  name: s.string().describe('Human-readable display name written to frontmatter.name'),
+  outputType: s.string().describe('Artefact type ID this cycle produces (must exist in foundry/artefacts/)'),
+  inputs: s.object({
+    type: s.enum(['any-of', 'all-of']).describe('Contract type: any-of (at least one) or all-of (all must exist)'),
+    artefacts: s.array(s.string()).describe('Artefact type IDs this cycle reads'),
+  }).optional().describe('Input contract for this cycle'),
+  targets: s.array(s.string()).optional().describe('Downstream cycle IDs this cycle can route to'),
+  humanAppraise: s.boolean().optional().describe('Include human-appraise in every iteration'),
+  deadlockAppraise: s.boolean().optional().describe('Route to human-appraise on LLM appraiser deadlock'),
+  deadlockIterations: s.number().optional().describe('Iteration threshold for deadlock detection'),
+  maxIterations: s.number().optional().describe('Maximum forge iterations before cycle blocks'),
+  assay: s.object({
+    extractors: s.array(s.string()).describe('Extractor IDs for the assay stage'),
+  }).optional().describe('Assay stage configuration'),
+  memory: s.object({
+    read: s.array(s.string()).describe('Memory store keys this cycle can read'),
+    write: s.array(s.string()).describe('Memory store keys this cycle can write'),
+  }).optional().describe('Flow memory permissions'),
+  models: s.object({}).optional().describe('Per-stage model overrides (e.g. { forge: "openai/gpt-4o" })'),
+  description: s.string().optional().describe('Prose description placed after frontmatter'),
+}; }
+
 export function createConfigCreateTools({ tool }) {
-  const baseArgs = {
+  const makeValidate = createMakeValidate(tool, {
     name: tool.schema.string(),
     body: tool.schema.string(),
-  };
-
-  const makeCreate = createMakeCreate(tool, baseArgs);
-  const makeValidate = createMakeValidate(tool, baseArgs);
+  });
+  const makeCreate = createMakeCreate(tool);
+  const s = tool.schema;
 
   return {
-    foundry_config_create_artefact_type: makeCreate('foundry_config_create_artefact_type', createArtefactType),
-    foundry_config_create_appraiser: makeCreate('foundry_config_create_appraiser', createAppraiser),
-    foundry_config_create_flow: makeCreate('foundry_config_create_flow', createFlow),
-    foundry_config_create_cycle: makeCreate('foundry_config_create_cycle', createCycle),
+    foundry_config_create_artefact_type: makeCreate('foundry_config_create_artefact_type', createArtefactType, artefactTypeArgs(s)),
+    foundry_config_create_appraiser: makeCreate('foundry_config_create_appraiser', createAppraiser, appraiserArgs(s)),
+    foundry_config_create_flow: makeCreate('foundry_config_create_flow', createFlow, flowArgs(s)),
+    foundry_config_create_cycle: makeCreate('foundry_config_create_cycle', createCycle, cycleArgs(s)),
 
     foundry_config_validate_artefact_type: makeValidate('foundry_config_validate_artefact_type', validateArtefactType),
     foundry_config_validate_law: makeValidate('foundry_config_validate_law', validateLaw),

package/dist/.opencode/plugins/foundry-tools/config-law-tools.js

@@ -11,6 +11,7 @@ import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
 import { UnexpectedFilesError, commitWithPolicy } from '../../../scripts/lib/git-bridge.js';
 import { makeIO, makeExec, makeAsyncIO, errorJson, branchIoFactory, asyncIoFactory } from './helpers.js';
 import { execFileSync } from 'child_process';
+import { assembleLawMarkdown, assembleEditLawMarkdown } from '../../../scripts/lib/config-creators/law.js';
 
 // --- utility functions -------------------------------------------------------
 
@@ -22,18 +23,14 @@ function contentContainsLaw(content, lawId) {
 function findLawStart(lines, lawId) {
   for (let i = 0; i < lines.length; i++) {
     const heading = lines[i].match(/^## (.+)/);
-    if (heading && heading[1].trim() === lawId) {
-      return i;
-    }
+    if (heading && heading[1].trim() === lawId) return i;
   }
   return -1;
 }
 
 function findLawEnd(lines, startIdx) {
   for (let i = startIdx + 1; i < lines.length; i++) {
-    if (lines[i].match(/^## (.+)/)) {
-      return i;
-    }
+    if (lines[i].match(/^## (.+)/)) return i;
   }
   return lines.length;
 }
@@ -45,7 +42,7 @@ function extractLawMarkdown(content, lawId) {
   const endIdx = findLawEnd(lines, startIdx);
   const lawLines = lines.slice(startIdx, endIdx);
   while (lawLines.length > 0 && lawLines[lawLines.length - 1] === '') lawLines.pop();
-  return lawLines.join('\n') + '\n';
+  return lawLines.join('\n');
 }
 
 async function searchGlobalLaws(io, foundryDir, lawId) {
@@ -84,29 +81,18 @@ async function findLawByID(io, foundryDir, lawId) {
 
 // --- guard helpers ---------------------------------------------------------
 
-function gitRepoGuard(_args, context) {
-  return requireGitRepo(makeIO(context.worktree));
-}
-
-function foundryRootGuard(_args, context) {
-  return requireFoundryRoot(makeIO(context.worktree));
-}
-
-function configBranchGuard(_args, context) {
-  return requireOnConfigBranch({ exec: makeExec(context.worktree) });
-}
-
+function gitRepoGuard(_a, c) { return requireGitRepo(makeIO(c.worktree)); }
+function foundryRootGuard(_a, c) { return requireFoundryRoot(makeIO(c.worktree)); }
+function configBranchGuard(_a, c) { return requireOnConfigBranch({ exec: makeExec(c.worktree) }); }
 const gateNotFailed = notFailedGuard(makeIO);
 
-const GIT_COMMAND = 'git';
-
 function makeExecFile(cwd) {
-  return (argv) => execFileSync(GIT_COMMAND, argv, { cwd, encoding: 'utf8', stdio: 'pipe' });
+  return (argv) => execFileSync('git', argv, { cwd, encoding: 'utf8', stdio: 'pipe' });
 }
 
 const READ_GUARDS = [gitRepoGuard, foundryRootGuard];
-const CREATE_GUARDS = [gitRepoGuard, foundryRootGuard, configBranchGuard, gateNotFailed];
-const EDIT_GUARDS = [gitRepoGuard, foundryRootGuard, configBranchGuard, gateNotFailed];
+const CREATE_GUARDS = [...READ_GUARDS, configBranchGuard, gateNotFailed];
+const EDIT_GUARDS = [...READ_GUARDS, configBranchGuard, gateNotFailed];
 
 // --- read law executor -------------------------------------------------------
 
@@ -114,25 +100,10 @@ async function executeReadLaw(args, context) {
   try {
     const io = makeAsyncIO(context.worktree);
     const result = await findLawByID(io, 'foundry', args.id);
-    if (!result.found) {
-      return JSON.stringify({
-        ok: false,
-        errors: [`Law "${args.id}" not found`],
-      });
-    }
+    if (!result.found) return JSON.stringify({ ok: false, errors: [`Law "${args.id}" not found`] });
     const markdown = extractLawMarkdown(result.fullMarkdown, args.id);
-    if (!markdown) {
-      return JSON.stringify({
-        ok: false,
-        errors: [`Could not extract law "${args.id}" from file`],
-      });
-    }
-    return JSON.stringify({
-      ok: true,
-      id: args.id,
-      markdown,
-      source: result.source,
-    });
+    if (!markdown) return JSON.stringify({ ok: false, errors: [`Could not extract law "${args.id}" from file`] });
+    return JSON.stringify({ ok: true, id: args.id, markdown, source: result.source });
   } catch (err) {
     return errorJson(err);
   }
@@ -147,32 +118,24 @@ function validateAddLawTarget(target) {
 }
 
 function validateAddLawTargetStruct(target) {
-  if (!target || typeof target !== 'object') {
-    return 'target argument is required (object with kind + locator)';
-  }
+  if (!target || typeof target !== 'object') return 'target argument is required (object with kind + locator)';
   const kinds = ['global', 'type-specific'];
   if (!kinds.includes(target.kind)) return `unknown target.kind: ${target.kind}`;
   return null;
 }
 
 function validateGlobalLawTarget(target) {
-  if (typeof target.file !== 'string' || !target.file.trim()) {
-    return 'target.file is required for kind: "global"';
-  }
+  if (typeof target.file !== 'string' || !target.file.trim()) return 'target.file is required for kind: "global"';
   return null;
 }
 
 function validateTypeSpecLawTarget(target) {
-  if (typeof target.typeId !== 'string' || !target.typeId.trim()) {
-    return 'target.typeId is required for kind: "type-specific"';
-  }
+  if (typeof target.typeId !== 'string' || !target.typeId.trim()) return 'target.typeId is required for kind: "type-specific"';
   return null;
 }
 
 function computeTargetPath(target) {
-  if (target?.kind === 'global') {
-    return join('foundry', 'laws', target.file);
-  }
+  if (target?.kind === 'global') return join('foundry', 'laws', target.file);
   return join('foundry', 'artefacts', target.typeId, 'laws.md');
 }
 
@@ -195,14 +158,11 @@ async function checkExistingLaw(io, path, lawId) {
 async function validateAddLawPrerequisites(io, args) {
   const targetError = validateAddLawTarget(args.target);
   if (targetError) return { error: targetError };
-
   const path = computeTargetPath(args.target);
   const validation = await validateLaw({ body: args.body, io });
   if (!validation.ok) return validation;
-
   const lawId = extractLawId(args.body);
   if (!lawId) return { error: 'could not determine law id from body (expected "## <law-id>" heading)' };
-
   const existing = await checkExistingLaw(io, path, lawId);
   if (existing.error) return { error: existing.error };
   return { ok: true, path, lawId, ...existing };
@@ -219,34 +179,43 @@ function buildNextContent(existedBefore, priorContent, body) {
 }
 
 async function rollbackAddLaw(io, path, existedBefore, priorContent) {
+  if (!path) return;
   if (existedBefore) await io.writeFile(path, priorContent);
   else await io.rm(path);
 }
 
 async function executeAddLaw(args, context) {
+  if (!args.id) return JSON.stringify({ ok: false, errors: ['id is required'] });
+
   const io = makeAsyncIO(context.worktree);
   const execFile = makeExecFile(context.worktree);
+
+  const body = assembleLawMarkdown({
+    id: args.id, name: args.name, description: args.description,
+    passing: args.passing, failing: args.failing, validators: args.validators,
+  });
+
+  const addArgs = { name: args.id, body, target: args.target };
   let path, existedBefore, priorContent;
 
   try {
-    const prereq = await validateAddLawPrerequisites(io, args);
+    const prereq = await validateAddLawPrerequisites(io, addArgs);
     if (prereq.error) return JSON.stringify({ ok: false, errors: [prereq.error] });
     if (!prereq.ok) return JSON.stringify(prereq);
 
     ({ path, existedBefore, priorContent } = prereq);
-    const nextContent = buildNextContent(existedBefore, priorContent, args.body);
+    const nextContent = buildNextContent(existedBefore, priorContent, addArgs.body);
 
     await io.mkdirp(dirname(path));
     await io.writeFile(path, nextContent);
 
     const sha = commitWithPolicy({
       message: `config: add law ${args.name}\n\nvia foundry_config_add_law`,
-      allowedPatterns: ['foundry/**'],
-      execFile,
+      allowedPatterns: ['foundry/**'], execFile,
     });
     return JSON.stringify({ ok: true, path, sha });
   } catch (err) {
-    if (path) await rollbackAddLaw(io, path, existedBefore, priorContent);
+    await rollbackAddLaw(io, path, existedBefore, priorContent);
     return formatAddLawError(err);
   }
 }
@@ -268,6 +237,46 @@ function replaceLawInContent(content, lawId, newLawMarkdown) {
   return before.concat(newLines, after).join('\n') + '\n';
 }
 
+// --- edit law helpers -------------------------------------------------------
+
+class EditLawResponse extends Error {
+  constructor(response) {
+    super();
+    this.response = response;
+    this.isEditLawResponse = true;
+  }
+}
+
+function hasEditLawFields(args) {
+  return args.name !== undefined || args.description !== undefined ||
+    args.passing !== undefined || args.failing !== undefined || args.validators !== undefined;
+}
+
+async function findAndExtractEditLaw(io, lawId) {
+  const result = await findLawByID(io, 'foundry', lawId);
+  if (!result.found) throw new EditLawResponse({ ok: false, errors: [`Law "${lawId}" not found`] });
+  const existingBody = extractLawMarkdown(result.fullMarkdown, lawId);
+  if (!existingBody) throw new EditLawResponse({ ok: false, errors: [`Could not extract law "${lawId}" from file`] });
+  return { result, existingBody };
+}
+
+async function assembleEditLawBody(existingBody, args, io) {
+  const newBody = assembleEditLawMarkdown(existingBody, {
+    name: args.name, description: args.description,
+    passing: args.passing, failing: args.failing, validators: args.validators,
+  });
+  const validation = await validateLaw({ body: newBody, io });
+  if (!validation.ok) throw new EditLawResponse(validation);
+  return newBody;
+}
+
+async function commitEditLawChange(result, newBody, lawId, execFile, io) {
+  const fileContent = replaceLawInContent(result.fullMarkdown, lawId, newBody);
+  await io.writeFile(result.path, fileContent);
+  execFile(['add', result.path]);
+  execFile(['commit', '-m', `config: edit law ${lawId}\n\nvia foundry_config_edit_law`]);
+}
+
 // --- edit law executor -------------------------------------------------------
 
 async function executeEditLaw(args, context) {
@@ -275,34 +284,23 @@ async function executeEditLaw(args, context) {
   const execFile = makeExecFile(context.worktree);
 
   try {
-    const result = await findLawByID(io, 'foundry', args.id);
-    if (!result.found) {
-      return JSON.stringify({
-        ok: false,
-        errors: [`Law "${args.id}" not found`],
-      });
-    }
-
-    const validation = await validateLaw({ body: args.body, io });
-    if (!validation.ok) {
-      return JSON.stringify(validation);
-    }
-
-    const fileContent = replaceLawInContent(result.fullMarkdown, args.id, args.body);
-    await io.writeFile(result.path, fileContent);
-    execFile(['add', result.path]);
-    execFile(['commit', '-m', `config: edit law ${args.id}\n\nvia foundry_config_edit_law`]);
+    if (!hasEditLawFields(args)) throw new EditLawResponse({
+      ok: false,
+      errors: ['at least one field to update must be provided (name, description, passing, failing, validators)'],
+    });
+
+    const { result, existingBody } = await findAndExtractEditLaw(io, args.id);
+    const newBody = await assembleEditLawBody(existingBody, args, io);
+    await commitEditLawChange(result, newBody, args.id, execFile, io);
 
     return JSON.stringify({
-      ok: true,
-      id: args.id,
+      ok: true, id: args.id,
       path: result.path.replace(/^foundry\//, 'foundry/'),
       source: result.source,
     });
   } catch (err) {
-    if (err instanceof UnexpectedFilesError) {
-      return JSON.stringify({ error: err.message, affected_files: err.files });
-    }
+    if (err.isEditLawResponse) return JSON.stringify(err.response);
+    if (err instanceof UnexpectedFilesError) return JSON.stringify({ error: err.message, affected_files: err.files });
     return errorJson(err);
   }
 }
@@ -312,46 +310,51 @@ async function executeEditLaw(args, context) {
 function makeReadLawTool(tool) {
   return tool({
     description: 'Read a law by ID, returning the full markdown including validators block.',
-    args: {
-      id: tool.schema.string().describe('Law ID to read'),
-    },
-    execute: guarded('foundry_config_read_law', READ_GUARDS, executeReadLaw, {
-      branchIo: branchIoFactory,
-      io: asyncIoFactory,
-    }),
+    args: { id: tool.schema.string().describe('Law ID to read') },
+    execute: guarded('foundry_config_read_law', READ_GUARDS, executeReadLaw, { branchIo: branchIoFactory, io: asyncIoFactory }),
   });
 }
 
 function makeAddLawTool(tool) {
   return tool({
-    description: 'Add a new law (config-tier; requires a config/* branch). Target must be {kind:"global", file:"<name>.md"} or {kind:"type-specific", typeId:"<id>"}.',
+    description: 'Add a new law (config-tier; requires a config/* branch). ' +
+      'Fields: id, name, description, passing, failing, target ({kind, file|typeId}), validators ([{id, command, failureMeans?}]).',
     args: {
-      name: tool.schema.string(),
-      body: tool.schema.string(),
+      id: tool.schema.string().describe('Law identifier. Becomes the ## <id> heading.'),
+      name: tool.schema.string().describe('Human-readable name stored as prose after heading.'),
+      description: tool.schema.string().describe('Prose describing what the law covers.'),
+      passing: tool.schema.string().describe('Criteria that define a passing artefact.'),
+      failing: tool.schema.string().describe('Criteria that define a failing artefact.'),
       target: tool.schema.object({
-        kind: tool.schema.string(),
-        file: tool.schema.string().optional(),
-        typeId: tool.schema.string().optional(),
-      }),
+        kind: tool.schema.enum(['global', 'type-specific']).describe('Target kind: global or type-specific'),
+        file: tool.schema.string().optional().describe('Filename for global laws (e.g. rules.md)'),
+        typeId: tool.schema.string().optional().describe('Artefact type ID for type-specific laws'),
+      }).describe('Where to write the law'),
+      validators: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().describe('Validator identifier'),
+        command: tool.schema.string().describe('CLI command with optional {pattern} / {files} placeholders'),
+        failureMeans: tool.schema.string().optional().describe('Description of what failure means'),
+      })).optional().describe('Optional deterministic validators'),
     },
-    execute: guarded('foundry_config_add_law', CREATE_GUARDS, executeAddLaw, {
-      branchIo: branchIoFactory,
-      io: asyncIoFactory,
-    }),
+    execute: guarded('foundry_config_add_law', CREATE_GUARDS, executeAddLaw, { branchIo: branchIoFactory, io: asyncIoFactory }),
   });
 }
 
 function makeEditLawTool(tool) {
   return tool({
-    description: 'Edit an existing law by ID. Validates the new body, updates the file, and commits on the current config/* branch.',
+    description: 'Edit an existing law by ID (config-tier; requires a config/* branch). ' +
+      'At least one optional field must be provided. Fields: id, name?, description?, passing?, failing?, validators?.',
     args: {
       id: tool.schema.string().describe('Law ID to edit'),
-      body: tool.schema.string().describe('Full new markdown body for the law'),
+      name: tool.schema.string().optional().describe('Updated human-readable name'),
+      description: tool.schema.string().optional().describe('Updated description'),
+      passing: tool.schema.string().optional().describe('Updated passing criteria'),
+      failing: tool.schema.string().optional().describe('Updated failing criteria'),
+      validators: tool.schema.array(tool.schema.object({
+        id: tool.schema.string(), command: tool.schema.string(), failureMeans: tool.schema.string().optional(),
+      })).optional().nullable().describe('Updated validators (replaces existing; null removes validators block; omitted leaves unchanged)'),
     },
-    execute: guarded('foundry_config_edit_law', EDIT_GUARDS, executeEditLaw, {
-      branchIo: branchIoFactory,
-      io: asyncIoFactory,
-    }),
+    execute: guarded('foundry_config_edit_law', EDIT_GUARDS, executeEditLaw, { branchIo: branchIoFactory, io: asyncIoFactory }),
   });
 }
 

package/dist/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [3.3.0] - 2026-05-14
+
+### Added
+
+- **Structured config tool signatures.** All six config creation and editing
+  tools now accept typed, self-documenting fields instead of raw `body`
+  strings containing YAML frontmatter. Each tool generates the correct
+  markdown file internally from the provided fields. The AI no longer needs
+  to hand-craft YAML frontmatter or reverse-engineer format from validation
+  errors. Tool descriptions include field names and types.
+
+  | Tool | New args |
+  |------|----------|
+  | `foundry_config_create_artefact_type` | `id`, `name`, `filePatterns`, `description`, `appraisers?` |
+  | `foundry_config_create_appraiser` | `id`, `name`, `description`, `model?` |
+  | `foundry_config_create_flow` | `id`, `name`, `startingCycles`, `description` |
+  | `foundry_config_create_cycle` | `id`, `name`, `outputType` + 10 optional fields |
+  | `foundry_config_add_law` | `id`, `name`, `description`, `passing`, `failing`, `target`, `validators?` |
+  | `foundry_config_edit_law` | `id` + per-field optional updates |
+
+  All five authoring skills updated to use the new signatures. Validate tools
+  unchanged — they still accept `{ name, body }`.
+
+### Changed
+
+- **`tool-paths.js` resolves command paths from `PATH`.** `git` and `opencode`
+  paths are resolved lazily and overridable via `FOUNDRY_GIT_PATH` /
+  `FOUNDRY_OPENCODE_PATH` env vars. Removed `sonarjs/no-os-command-from-path`
+  overrides for `foundry.js` and `agent-refresh.js`.
+
 ## [3.2.7] - 2026-05-14
 
 ### Added

package/dist/scripts/lib/config-creators/appraiser.js

@@ -2,8 +2,35 @@ import { join } from 'node:path';
 import { validate } from '../config-validators/appraiser.js';
 import { makeCreator } from './factory.js';
 
-export const create = makeCreator({
+/**
+ * Assemble the markdown body for an appraiser definition from structured arguments.
+ *
+ * @param {object} args
+ * @param {string} args.id           Slugged identifier; becomes frontmatter.id.
+ * @param {string} args.name         Human-readable display name; becomes frontmatter.name.
+ * @param {string} args.description  Prose personality description after frontmatter.
+ * @param {string} [args.model]      Optional model override.
+ * @returns {string} Assembled markdown body.
+ */
+export function assembleAppraiserMarkdown(args) {
+  const { id, name, description } = args;
+  let body = `---\nid: ${id}\nname: ${name}\n`;
+
+  if (args.model) {
+    body += `model: ${args.model}\n`;
+  }
+
+  body += `---\n\n${description}\n`;
+  return body;
+}
+
+const _create = makeCreator({
   kind: { human: 'appraiser', underscored: 'appraiser' },
-  pathFor: (args) => join('foundry', 'appraisers', `${args.name}.md`),
+  pathFor: (args) => join('foundry', 'appraisers', `${args.id}.md`),
   validator: validate,
 });
+
+export async function create(args) {
+  const body = assembleAppraiserMarkdown(args);
+  return _create({ ...args, name: args.id, body });
+}

package/dist/scripts/lib/config-creators/artefact-type.js

@@ -2,8 +2,55 @@ import { join } from 'node:path';
 import { validate } from '../config-validators/artefact-type.js';
 import { makeCreator } from './factory.js';
 
-export const create = makeCreator({
+/**
+ * Render the optional appraisers block as YAML lines.
+ *
+ * @param {{ count?: number, allowed?: string[] } | undefined} appraisers
+ * @returns {string}
+ */
+function renderAppraisers(appraisers) {
+  if (!appraisers) return '';
+  let block = 'appraisers:\n';
+  if (appraisers.count !== undefined) {
+    block += `  count: ${appraisers.count}\n`;
+  }
+  if (appraisers.allowed && appraisers.allowed.length > 0) {
+    block += '  allowed:\n';
+    block += appraisers.allowed.map((a) => `    - ${a}`).join('\n') + '\n';
+  }
+  return block;
+}
+
+/**
+ * Assemble the markdown body for an artefact-type definition from structured arguments.
+ *
+ * @param {object} args
+ * @param {string} args.id              Slugged identifier; becomes frontmatter.name.
+ * @param {string} args.name            Human-readable display name (not persisted).
+ * @param {string[]} args.filePatterns  Glob patterns for write scope.
+ * @param {string} args.description     Prose under ## Definition.
+ * @param {{ count?: number, allowed?: string[] }} [args.appraisers]  Optional appraiser config.
+ * @returns {string} Assembled markdown body.
+ */
+export function assembleArtefactTypeMarkdown(args) {
+  const { id, filePatterns, description } = args;
+  let body = `---\nname: ${id}\nfile-patterns:\n`;
+  for (const p of filePatterns) {
+    body += `  - ${p}\n`;
+  }
+
+  body += renderAppraisers(args.appraisers);
+  body += `---\n\n## Definition\n\n${description}\n`;
+  return body;
+}
+
+const _create = makeCreator({
   kind: { human: 'artefact-type', underscored: 'artefact_type' },
-  pathFor: (args) => join('foundry', 'artefacts', args.name, 'definition.md'),
+  pathFor: (args) => join('foundry', 'artefacts', args.id, 'definition.md'),
   validator: validate,
 });
+
+export async function create(args) {
+  const body = assembleArtefactTypeMarkdown(args);
+  return _create({ ...args, name: args.id, body });
+}