@really-knows-ai/foundry 2.3.2 → 3.0.1

package/dist/.opencode/plugins/foundry-tools/appraiser-tools.js

@@ -0,0 +1,28 @@
+import { selectAppraisers } from '../../../scripts/lib/config.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+export function createAppraiserTools({ tool }) {
+  return {
+    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'),
+      },
+      // Flow-tier mutation per SPEC §6: appraiser selection mutates the
+      // dispatch state of the in-flight cycle. Branch guard runs before
+      // failed-flow gate so wrong-branch refusals win over failed-state.
+      execute: guarded('foundry_appraisers_select', [flowBranchGuard, gateNotFailed], async (args, context) => {
+        const io = makeIO(context.worktree);
+        const result = await selectAppraisers('foundry', args.typeId, {
+          io,
+          countOverride: args.count ?? null,
+        });
+        return JSON.stringify(result);
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/artefact-tools.js

@@ -0,0 +1,58 @@
+import path from 'path';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { parseArtefactsTable, setArtefactStatus } from '../../../scripts/lib/artefacts.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard } from './helpers.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+function makeListTool(tool) {
+  return tool({
+    description: 'List artefacts from the WORK.md table. Optionally filter by cycle — callers should always pass the current cycle to avoid picking up stale rows from prior sessions.',
+    args: {
+      cycle: tool.schema.string().optional().describe('Only return rows whose Cycle column matches this value'),
+    },
+    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 rows = parseArtefactsTable(text);
+      const filtered = args.cycle ? rows.filter(r => r.cycle === args.cycle) : rows;
+      return JSON.stringify(filtered);
+    },
+  });
+}
+
+export function createArtefactTools({ tool }) {
+  return {
+    // NOTE: `foundry_artefacts_add` was removed in v2.2.0. Artefacts are now
+    // registered automatically by the orchestrator's internal finalize step as drafts,
+    // then promoted to done|blocked via `foundry_artefacts_set_status`.
+    foundry_artefacts_set_status: tool({
+      description: 'Update the status of an artefact in WORK.md (done|blocked only)',
+      args: {
+        file: tool.schema.string().describe('Artefact file path'),
+        status: tool.schema.string().describe('New status (done|blocked)'),
+      },
+      execute: guarded('foundry_artefacts_set_status', [flowBranchGuard, gateNotFailed], async (args, context) => {
+        const io = makeIO(context.worktree);
+        const guard = requireNoActiveStage(io);
+        if (!guard.ok) return JSON.stringify({ error: `foundry_artefacts_set_status ${guard.error}` });
+        const workPath = path.join(context.worktree, 'WORK.md');
+        const text = readFileSync(workPath, 'utf-8');
+        try {
+          const updated = setArtefactStatus(text, args.file, args.status);
+          writeFileSync(workPath, updated, 'utf-8');
+          return JSON.stringify({ ok: true });
+        } catch (e) {
+          return JSON.stringify({ error: e.message });
+        }
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+
+    foundry_artefacts_list: makeListTool(tool),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/assay-tools.js

@@ -0,0 +1,92 @@
+import { requireActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { markWorkfileFailed } from '../../../scripts/lib/failed-flow.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { runAssay } from '../../../scripts/lib/assay/run.js';
+import { syncStore } from '../../../scripts/lib/memory/store.js';
+import { putEntity, relate as memRelate } from '../../../scripts/lib/memory/writes.js';
+import { withStore } from './memory-helpers.js';
+import { makeIO, branchIoFactory, asyncIoFactory, flowBranchGuard, errorJson } from './helpers.js';
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+function truncateStderr(stderr) {
+  if (!stderr) return '';
+  const trimmed = stderr.trim();
+  if (trimmed.length <= 500) return trimmed;
+  const bytesRemaining = trimmed.length - 500;
+  const plural = bytesRemaining === 1 ? 'byte' : 'bytes';
+  return `${trimmed.slice(0, 500)}... (${bytesRemaining} more ${plural})`;
+}
+
+function handleExtractorFailure(io, res) {
+  const stderrSnippet = truncateStderr(res.stderr);
+  const msg = `assay aborted on extractor \`${res.failedExtractor}\`: ${res.reason}` +
+    (stderrSnippet ? ` (stderr: ${stderrSnippet})` : '');
+  try { markWorkfileFailed(io, msg); } catch { /* WORK.md gone? nothing we can do */ }
+  return JSON.stringify({
+    error: msg,
+    flow_failed: true,
+    aborted: true,
+    failedExtractor: res.failedExtractor,
+    reason: res.reason,
+    stderr: res.stderr,
+    perExtractor: res.perExtractor,
+  });
+}
+
+async function syncAfterAssay(store, memIo) {
+  try {
+    await syncStore({ store, io: memIo });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, err };
+  }
+}
+
+function handleSyncFailure(io, err) {
+  const msg = `assay post-run memory sync failed: ${err?.message ?? err}`;
+  try { markWorkfileFailed(io, msg); } catch { /* WORK.md gone? nothing we can do */ }
+  return JSON.stringify({ error: msg, flow_failed: true });
+}
+
+async function handleAssayRun(args, context) {
+  const io = makeIO(context.worktree);
+  const guard = requireActiveStage(io, { stageBase: 'assay', cycle: args.cycle });
+  if (!guard.ok) return JSON.stringify({ error: `foundry_assay_run requires active assay stage for cycle '${args.cycle}'; ${guard.error}` });
+
+  try {
+    const { store, vocabulary, writeEmbedder, io: memIo } = await withStore(context);
+    const res = await runAssay({
+      foundryDir: 'foundry',
+      cwd: context.worktree,
+      io: memIo,
+      extractors: args.extractors,
+      store,
+      vocabulary,
+      putEntity,
+      relate: memRelate,
+      writeEmbedder,
+      syncStore, // G29: Pass syncStore so it's called after each extractor
+    });
+
+    if (!res.ok) return handleExtractorFailure(io, res);
+
+    const syncResult = await syncAfterAssay(store, memIo);
+    if (!syncResult.ok) return handleSyncFailure(io, syncResult.err);
+
+    return JSON.stringify(res);
+  } catch (err) { return errorJson(err); }
+}
+
+export function createAssayTools({ tool }) {
+  return {
+    foundry_assay_run: tool({
+      description: 'Run extractors to populate flow memory. Only callable during an active assay stage. Aborts on first failure; marks the workfile failed. Extractors must output one JSON object per line (JSONL/NDJSON format), not pretty-printed multi-line JSON.',
+      args: {
+        cycle: tool.schema.string().describe('Cycle name'),
+        extractors: tool.schema.array(tool.schema.string()).describe('Extractor names, executed in order'),
+      },
+      execute: guarded('foundry_assay_run', [flowBranchGuard, gateNotFailed], handleAssayRun, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}

package/dist/.opencode/plugins/foundry-tools/attestation-tools.js

@@ -0,0 +1,191 @@
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, existsSync, readFileSync, unlinkSync } from 'node:fs';
+import path from 'node:path';
+import { extractAttestationBlock } from '../../../scripts/lib/attestation/parse.js';
+import { verifyAttestationRef } from '../../../scripts/lib/attestation/verify.js';
+import { buildAttestation } from '../../../scripts/lib/attestation/attest.js';
+import { parseFrontmatter } from '../../../scripts/lib/workfile.js';
+import { requireNoActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { currentBranch } from '../../../scripts/lib/branch-guard.js';
+import { errorJson, makeIO, makeExec } from './helpers.js';
+
+function refuse(error) { return JSON.stringify({ error }); }
+
+function createShowTool(tool) {
+  return tool({
+    description: 'Show parsed attestation payload and human summary for a commit ref (default HEAD).',
+    args: {
+      ref: tool.schema.string().optional().describe('Git ref (default: HEAD)'),
+    },
+    async execute(args, context) {
+      try {
+        const ref = args.ref || 'HEAD';
+        const cwd = context.worktree;
+        const message = execFileSync('git', ['log', '-1', '--pretty=%B', ref],
+          { cwd, encoding: 'utf8', stdio: 'pipe' }
+        );
+        const json = extractAttestationBlock(message);
+        let payload;
+        try {
+          payload = JSON.parse(json);
+        } catch {
+          return errorJson(new Error(`malformed attestation JSON: ${json}`));
+        }
+        const subjectLine = message.split('\n')[0];
+        return JSON.stringify({ ok: true, human_summary: subjectLine, payload });
+      } catch (err) {
+        return errorJson(err);
+      }
+    },
+  });
+}
+
+function createVerifyTool(tool) {
+  return tool({
+    description: 'Verify GPG signature and attestation payload for a commit ref (default HEAD).',
+    args: {
+      ref: tool.schema.string().optional().describe('Git ref (default: HEAD)'),
+    },
+    async execute(args, context) {
+      try {
+        const ref = args.ref || 'HEAD';
+        const cwd = context.worktree;
+        const result = verifyAttestationRef({ cwd, ref });
+        return JSON.stringify({ ok: true, ...result });
+      } catch (err) {
+        return errorJson(err);
+      }
+    },
+  });
+}
+
+function guardStageAndBranch(cwd) {
+  const io = makeIO(cwd);
+  const stageGuard = requireNoActiveStage(io);
+  if (!stageGuard.ok) {
+    return { ok: false, error: `foundry_attest: ${stageGuard.error}` };
+  }
+  const branch = currentBranch({ exec: makeExec(cwd) });
+  if (!branch || !branch.startsWith('work/')) {
+    return { ok: false, error: `foundry_attest: must be run on a work/* branch, current branch is '${branch}'` };
+  }
+  return { ok: true, branch };
+}
+
+function refuseConfirm(branch, baseBranch) {
+  return JSON.stringify({
+    ok: false,
+    error: 'foundry_attest requires {confirm: true}. Re-invoke with confirm:true to write ATTEST.md.',
+    planned: {
+      action: 'verify-cycle, compute-diff-sha, write-ATTEST.md, commit',
+      branch,
+      baseBranch: baseBranch || 'main',
+    },
+  });
+}
+
+function makeExecGit(cwd, opts) {
+  return (argv) => {
+    if (argv[0] === 'diff') {
+      return execFileSync('git', argv, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+    }
+    return execFileSync('git', argv, opts).toString();
+  };
+}
+
+function readCycleFromWorkfile(cwd) {
+  const workText = readFileSync(path.join(cwd, 'WORK.md'), 'utf8');
+  const frontmatter = parseFrontmatter(workText);
+  return frontmatter.cycle ?? 'unknown';
+}
+
+function gitRevParseHead(opts) {
+  return execFileSync('git', ['rev-parse', 'HEAD'], opts).trim();
+}
+
+function commitErrorString(err) {
+  const stderr = err.stderr ?? err.stdout ?? '';
+  return `foundry_attest: commit failed. ${String(stderr).trim()}`;
+}
+
+function cleanupFailedCommit(attestPath, opts) {
+  try { execFileSync('git', ['reset', 'HEAD', 'ATTEST.md'], opts); } catch { /* best effort */ }
+  try { unlinkSync(attestPath); } catch { /* best effort */ }
+}
+
+function commitAttestation(cwd, cycle, content, opts) {
+  const attestPath = path.join(cwd, 'ATTEST.md');
+  writeFileSync(attestPath, content, 'utf8');
+  try {
+    execFileSync('git', ['add', 'ATTEST.md'], opts);
+    const commitMsg = `[${cycle}] attest: cycle complete`;
+    execFileSync('git', ['commit', '--no-gpg-sign', '-m', commitMsg], opts);
+  } catch (err) {
+    cleanupFailedCommit(attestPath, opts);
+    return { ok: false, error: commitErrorString(err) };
+  }
+  const commitSha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], opts).trim();
+  return { ok: true, commitSha };
+}
+
+function buildAttestationInputs(opts) {
+  return {
+    cwd: opts.cwd,
+    baseBranch: opts.baseBranch,
+    goalText: opts.goalText,
+    archiveBranch: opts.archiveBranch,
+    archiveTipSha: opts.archiveTipSha,
+    io: { readFile: (p) => readFileSync(p, 'utf8'), fileExists: (p) => existsSync(p) },
+    execGit: opts.execGit,
+  };
+}
+
+function handleBuildResult(result, cwd, cycle, opts) {
+  if (!result.ok) return JSON.stringify(result);
+  const commitResult = commitAttestation(cwd, cycle, result.content, opts);
+  if (!commitResult.ok) return JSON.stringify(commitResult);
+  return JSON.stringify({ ok: true, diffSha: result.diffSha, commitSha: commitResult.commitSha });
+}
+
+function createAttestTool(tool) {
+  return tool({
+    description:
+      'Verify the current work cycle is complete (all required stages ran, no unresolved ' +
+      'feedback, no blocked artefacts) and commit an ATTEST.md attestation file to the work branch. ' +
+      'foundry_git_finish will not merge without this commit at HEAD.',
+    args: {
+      baseBranch: tool.schema.string().optional()
+        .describe('Branch to compute diff from (default: main)'),
+      message: tool.schema.string()
+        .describe('Goal text / human summary for the attestation'),
+      confirm: tool.schema.boolean().optional()
+        .describe('Must be true to write and commit ATTEST.md'),
+    },
+    async execute(args, context) {
+      const cwd = context.worktree;
+      const opts = { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] };
+      const guard = guardStageAndBranch(cwd);
+      if (!guard.ok) return refuse(guard.error);
+      if (args.confirm !== true) return refuseConfirm(guard.branch, args.baseBranch);
+      const baseBranch = args.baseBranch || 'main';
+      const execGit = makeExecGit(cwd, opts);
+      const cycle = readCycleFromWorkfile(cwd);
+      const tipSha = gitRevParseHead(opts);
+      const archiveBranch = `archive/${guard.branch}-${tipSha.slice(0, 7)}`;
+      const inputs = buildAttestationInputs({
+        cwd, baseBranch, goalText: args.message,
+        archiveBranch, archiveTipSha: tipSha, execGit,
+      });
+      const result = await buildAttestation(inputs);
+      return handleBuildResult(result, cwd, cycle, opts);
+    },
+  });
+}
+
+export function createAttestationTools({ tool }) {
+  return {
+    foundry_attestation_show: createShowTool(tool),
+    foundry_attestation_verify: createVerifyTool(tool),
+    foundry_attest: createAttestTool(tool),
+  };
+}

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

@@ -0,0 +1,128 @@
+// Tools for creating and validating the five foundry config kinds:
+// artefact-type, law, appraiser, flow, cycle.
+//
+// `_validate_<kind>` tools are read-only — they parse the supplied body
+// and report errors. They run anywhere (no branch guard, no failed-flow
+// guard) so authors can iterate on a draft from any branch.
+//
+// `_create_<kind>` tools mutate the worktree (write the file + commit
+// it) and so carry the full guard stack:
+//   gitRepo → foundryRoot → configBranch → notFailed
+// matching the config-tier policy.
+
+import { execFileSync } from 'child_process';
+import { create as createArtefactType } from '../../../scripts/lib/config-creators/artefact-type.js';
+import { create as createAppraiser } from '../../../scripts/lib/config-creators/appraiser.js';
+import { create as createFlow } from '../../../scripts/lib/config-creators/flow.js';
+import { create as createCycle } from '../../../scripts/lib/config-creators/cycle.js';
+import { validate as validateArtefactType } from '../../../scripts/lib/config-validators/artefact-type.js';
+import { validate as validateLaw } from '../../../scripts/lib/config-validators/law.js';
+import { validate as validateAppraiser } from '../../../scripts/lib/config-validators/appraiser.js';
+import { validate as validateFlow } from '../../../scripts/lib/config-validators/flow.js';
+import { validate as validateCycle } from '../../../scripts/lib/config-validators/cycle.js';
+import { requireGitRepo, requireFoundryRoot } from '../../../scripts/lib/foundational-guards.js';
+import { requireOnConfigBranch } from '../../../scripts/lib/branch-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { UnexpectedFilesError } from '../../../scripts/lib/git-bridge.js';
+import { makeIO, makeExec, makeAsyncIO, errorJson, branchIoFactory, asyncIoFactory } from './helpers.js';
+
+// --- 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) });
+}
+
+const gateNotFailed = notFailedGuard(makeIO);
+
+// `git`-prefixed argv runner that satisfies commitWithPolicy's contract:
+// it accepts argv WITHOUT the `git` prefix and prepends it itself.
+function makeExecFile(cwd) {
+  return (argv) => execFileSync('git', argv, { cwd, encoding: 'utf8', stdio: 'pipe' });
+}
+
+const CREATE_GUARDS = [gitRepoGuard, foundryRootGuard, configBranchGuard, gateNotFailed];
+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).`;
+
+    if (kind === 'law') {
+      desc += ' target must be {kind:"global", file:"<name>.md"} or {kind:"type-specific", typeId:"<id>"}.';
+    }
+
+    return tool({
+      description: desc,
+      args: { ...baseArgs, ...extraArgs },
+      execute: guarded(toolName, CREATE_GUARDS, async (args, context) => {
+        try {
+          const io = makeAsyncIO(context.worktree);
+          const execFile = makeExecFile(context.worktree);
+          const out = await creator({ ...args, io, execFile });
+          return JSON.stringify(out);
+        } catch (err) {
+          if (err instanceof UnexpectedFilesError) {
+            return JSON.stringify({ error: err.message, affected_files: err.files });
+          }
+          return errorJson(err);
+        }
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    });
+  };
+}
+
+// Module-level helper: returns a `makeValidate` function bound to `tool` and `baseArgs`.
+function createMakeValidate(tool, baseArgs) {
+  return function makeValidate(toolName, validator) {
+    return tool({
+      description: `Validate a ${toolName.replace('foundry_config_validate_', '')} body without writing it.`,
+      args: baseArgs,
+      execute: guarded(toolName, VALIDATE_GUARDS, async (args, context) => {
+        try {
+          const io = makeAsyncIO(context.worktree);
+          const out = await validator({ ...args, io });
+          return JSON.stringify(out);
+        } catch (err) {
+          return errorJson(err);
+        }
+      }, { branchIo: branchIoFactory, io: asyncIoFactory }),
+    });
+  };
+}
+
+// --- tool factory ---------------------------------------------------------
+
+export function createConfigCreateTools({ tool }) {
+  const baseArgs = {
+    name: tool.schema.string(),
+    body: tool.schema.string(),
+  };
+
+  const makeCreate = createMakeCreate(tool, baseArgs);
+  const makeValidate = createMakeValidate(tool, baseArgs);
+
+  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_validate_artefact_type: makeValidate('foundry_config_validate_artefact_type', validateArtefactType),
+    foundry_config_validate_law: makeValidate('foundry_config_validate_law', validateLaw),
+    foundry_config_validate_appraiser: makeValidate('foundry_config_validate_appraiser', validateAppraiser),
+    foundry_config_validate_flow: makeValidate('foundry_config_validate_flow', validateFlow),
+    foundry_config_validate_cycle: makeValidate('foundry_config_validate_cycle', validateCycle),
+  };
+}