@really-knows-ai/foundry 3.8.5 → 3.9.0

package/dist/.opencode/plugins/foundry-tools/stage-output-tool.js

@@ -0,0 +1,113 @@
+// src/plugin/tools/stage-output-tool.js
+// Stage output tool for foundry stages — validates and accumulates structured
+// output before stage end. Registered as `foundry_stage_output`.
+
+import { stageBaseOf, requireActiveStage } from '../../../scripts/lib/stage-guard.js';
+import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
+import { makeIO, flowBranchGuard, branchIoFactory, asyncIoFactory } from './helpers.js';
+import {
+  validateForgeOutput,
+  validateAppraiseOutput,
+  validateHumanAppraiseOutput,
+} from '../../../scripts/lib/stage-output-schemas.js';
+
+/** @type {Map<string, object[]>} In-memory buffer keyed by stageId::tokenHash. */
+const stageOutputsBuffer = new Map();
+
+/** Gate that rejects when the subagent's flow is in a failed state. */
+const gateNotFailed = notFailedGuard(makeIO);
+
+/** Validator dispatch table keyed by stage base name. */
+const VALIDATORS = Object.freeze({
+  forge: validateForgeOutput,
+  appraise: validateAppraiseOutput,
+  'human-appraise': validateHumanAppraiseOutput,
+});
+
+/**
+ * Execute the stage output handler: validate data against the active stage
+ * schema and accumulate it in the in-memory buffer.
+ * @param {{ data: object }} args
+ * @param {{ worktree: string }} context
+ * @returns {Promise<string>} JSON result
+ */
+async function handleStageOutput(args, context) {
+  const io = makeIO(context.worktree);
+  const activeResult = requireActiveStage(io);
+  if (!activeResult.ok) {
+    return JSON.stringify({ error: `foundry_stage_output: ${activeResult.error}` });
+  }
+
+  const base = stageBaseOf(activeResult.active.stage);
+  const validator = VALIDATORS[base];
+  if (!validator) {
+    return JSON.stringify({ error: `unknown stage base: ${base}` });
+  }
+
+  const validationResult = validator(args.data);
+  if (!validationResult.ok) {
+    const msg = `${base} stage_output: ${validationResult.errors.join('; ')}`;
+    return JSON.stringify({ error: msg });
+  }
+
+  const stageId = activeResult.active.stage;
+  const tokenHash = activeResult.active.tokenHash;
+  const key = `${stageId}::${tokenHash}`;
+  const buf = stageOutputsBuffer.get(key) || [];
+  buf.push(args.data);
+  stageOutputsBuffer.set(key, buf);
+
+  const totalCount = getStageOutputs(stageId).length;
+  return JSON.stringify({ ok: true, count: totalCount });
+}
+
+export function createStageOutputTool({ tool }) {
+  return {
+    foundry_stage_output: tool({
+      description: 'Validate and store structured output for the active stage. Call before foundry_stage_end(). Forge and human-appraise stages require exactly one call; appraise stages accept zero or more.',
+      args: {
+        data: tool.schema.object().describe('The JSON data to validate against the active stage schema'),
+      },
+      execute: guarded('foundry_stage_output', [flowBranchGuard, gateNotFailed],
+        handleStageOutput,
+        { branchIo: branchIoFactory, io: asyncIoFactory }),
+    }),
+  };
+}
+
+/**
+ * Retrieve all accumulated outputs for a given stage ID.
+ * Returns a shallow copy of the internal array to prevent mutation.
+ * @param {string} stageId - The full stage alias (e.g. "forge:cycle-1")
+ * @returns {object[]} Array of validated data objects
+ */
+export function getStageOutputs(stageId) {
+  const results = [];
+  for (const [key, outputs] of stageOutputsBuffer) {
+    if (key.startsWith(stageId + '::') || key === stageId) {
+      results.push(...outputs);
+    }
+  }
+  return results;
+}
+
+/**
+ * Clear all accumulated outputs for a given stage ID.
+ * Used after flushing buffer entries to disk.
+ * @param {string} stageId - The full stage alias (e.g. "forge:cycle-1")
+ */
+export function clearStageOutputs(stageId) {
+  for (const key of stageOutputsBuffer.keys()) {
+    if (key.startsWith(stageId + '::') || key === stageId) {
+      stageOutputsBuffer.delete(key);
+    }
+  }
+}
+
+/**
+ * Clear all accumulated outputs for every stage.
+ * Internal helper for test isolation — exported with underscore prefix.
+ */
+export function _clearAllOutputs() {
+  stageOutputsBuffer.clear();
+}

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

@@ -1,5 +1,6 @@
 import { execSync } from 'child_process';
 import { createHash } from 'node:crypto';
+import { join } from 'node:path';
 import { readActiveStage, writeActiveStage, clearActiveStage, writeLastStage, clearLastStage } from '../../../scripts/lib/state.js';
 import { verifyToken } from '../../../scripts/lib/token.js';
 import { readOrCreateSecret } from '../../../scripts/lib/secret.js';
@@ -10,6 +11,17 @@ import { markWorkfileFailed, readFailedStatus, clearWorkfileFailed } from '../..
 import { guarded, notFailedGuard } from '../../../scripts/lib/guards.js';
 import { initForgeCallLog, readForgeCallSet } from '../../../scripts/lib/stage-calls.js';
 import { openFeedbackStore } from '../../../scripts/lib/feedback-store.js';
+import { stageBaseOf } from '../../../scripts/lib/stage-guard.js';
+import { ulid } from '../../../scripts/lib/ulid.js';
+import { getStageOutputs, clearStageOutputs } from './stage-output-tool.js';
+
+function ensureDir(io, outDir) {
+  io.mkdir(outDir);
+}
+
+function contractError(stage, expected, got) {
+  return `${stage} stage_end: expected exactly ${expected} stage_output call${expected === 1 ? '' : 's'}, got ${got}`;
+}
 
 const FORGE_REQUIRED_TOOLS = [
   'foundry_config_cycle',
@@ -106,6 +118,9 @@ async function executeStageBegin(args, context, pending) {
   };
   writeActiveStage(io, active);
   initForgeIfApplicable(io, active.stage);
+
+  cleanStageOutputDir(io);
+
   return JSON.stringify({ ok: true, active });
 }
 
@@ -113,6 +128,53 @@ function initForgeIfApplicable(io, stage) {
   if (stageBase(stage) === 'forge') initForgeCallLog(io);
 }
 
+// -- Stage output directory helpers --
+
+function cleanStageOutputDir(io) {
+  const outDir = '.foundry/stage-outputs/';
+  if (io.exists(outDir)) {
+    for (const f of io.readDir(outDir)) {
+      io.unlink(join(outDir, f));
+    }
+  }
+  io.mkdir(outDir);
+}
+
+function checkContractViolation(outputs, base) {
+  if (base === 'forge' || base === 'human-appraise') {
+    if (outputs.length !== 1) {
+      return contractError(base, 1, outputs.length);
+    }
+  }
+  return null;
+}
+
+function writeAtomicOutputFile(io, outputs, id) {
+  const outDir = '.foundry/stage-outputs/';
+  ensureDir(io, outDir);
+  if (outputs.length === 0) {
+    io.writeFile(outDir + '.tmp-' + id, '');
+  } else {
+    const content = outputs.map(o => JSON.stringify(o)).join('\n') + '\n';
+    io.writeFile(outDir + '.tmp-' + id, content);
+  }
+  io.rename(outDir + '.tmp-' + id, outDir + id + '.jsonl');
+}
+
+function trySyncMemory(worktree) {
+  try {
+    return syncMemoryAtStageEnd(worktree);
+  } catch {
+    return { error: 'memory sync at stage end failed' };
+  }
+}
+
+function activeStageOrError(io) {
+  const active = readActiveStage(io);
+  if (!active) return null;
+  return active;
+}
+
 // -- Helpers for foundry_stage_end --
 
 function markWorkfileFailedSilently(io, msg) {
@@ -127,34 +189,51 @@ async function syncMemoryAtStageEnd(worktree) {
   }
 }
 
+async function finishStageAndSync(io, active, context) {
+  writeLastStage(io, { cycle: active.cycle, stage: active.stage, baseSha: active.baseSha, summary: '' });
+  clearActiveStage(io);
+
+  try {
+    await syncMemoryAtStageEnd(context.worktree);
+    return {};
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const msg = `memory sync at stage end failed: ${detail}`;
+    markWorkfileFailedSilently(io, msg);
+    return { error: msg, flow_failed: true };
+  }
+}
+
 async function executeStageEnd(args, context) {
   const io = makeIO(context.worktree);
+
   const active = readActiveStage(io);
   if (!active) {
     return JSON.stringify({ error: 'foundry_stage_end requires active stage; current: none' });
   }
 
-  if (stageBase(active.stage) === 'forge') {
-    verifyAndManageForgeTools(io, active);
+  verifyForgeToolsIfApplicable(io, active);
+
+  const outputs = getStageOutputs(active.stage + '::' + active.tokenHash);
+  const base = stageBaseOf(active.stage);
+  const violation = checkContractViolation(outputs, base);
+  if (violation) {
+    return JSON.stringify({ error: violation });
   }
 
-  writeLastStage(io, {
-    cycle: active.cycle,
-    stage: active.stage,
-    baseSha: active.baseSha,
-    summary: args.summary,
-  });
-  clearActiveStage(io);
+  const id = ulid();
+  writeAtomicOutputFile(io, outputs, id);
+  clearStageOutputs(active.stage + '::' + active.tokenHash);
 
-  try {
-    await syncMemoryAtStageEnd(context.worktree);
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    const msg = `memory sync at stage end failed: ${detail}`;
-    markWorkfileFailedSilently(io, msg);
-    return JSON.stringify({ error: msg, flow_failed: true });
+  const result = await finishStageAndSync(io, active, context);
+  if (result.error) return JSON.stringify(result);
+  return JSON.stringify({ ok: true });
+}
+
+function verifyForgeToolsIfApplicable(io, active) {
+  if (stageBase(active.stage) === 'forge') {
+    verifyAndManageForgeTools(io, active);
   }
-  return JSON.stringify({ ok: true, summary: args.summary });
 }
 
 function postForbiddenToolsFeedback(io, active, forbidden) {
@@ -255,10 +334,8 @@ export function createStageTools({ tool, pending }) {
     }),
 
     foundry_stage_end: tool({
-      description: 'Close the active subagent work stage; preserves baseSha for finalize.',
-      args: {
-        summary: tool.schema.string().describe('Short summary of the work done'),
-      },
+      description: 'Close the active subagent work stage. Output must be provided via foundry_stage_output before calling this tool. Validates the output contract for the active stage, writes accumulated outputs to a JSONL file, and clears the stage.',
+      args: {},
       execute: guarded('foundry_stage_end', [flowBranchGuard],
         executeStageEnd,
         { branchIo: branchIoFactory, io: asyncIoFactory }),

package/dist/.opencode/plugins/foundry.js

@@ -36,6 +36,7 @@ import { createMemoryAdminTools } from './foundry-tools/memory-admin-tools.js';
 import { createSnapshotTools } from './foundry-tools/snapshot-tools.js';
 import { createAttestationTools } from './foundry-tools/attestation-tools.js';
 import { createRefreshAgentsTool } from './foundry-tools/refresh-agents-tool.js';
+import { createStageOutputTool } from './foundry-tools/stage-output-tool.js';
 import { resolveGit, resolvePnpm } from '../../scripts/lib/tool-paths.js';
 
 function findPackageRoot(startDir) {
@@ -201,6 +202,7 @@ function buildTools(createTool, pending) {
     ...createSnapshotTools({ tool: createTool }),
     ...createAttestationTools({ tool: createTool }),
     ...createRefreshAgentsTool({ tool: createTool }),
+    ...createStageOutputTool({ tool: createTool }),
   };
 }
 

package/dist/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [3.9.0] - 2026-05-30
+
+### Added
+
+- Structured stage output schemas with JSON Schema-style validation for forge, appraise, and human-appraise outputs. Each schema defines required and optional fields with type and enum constraints.
+- `foundry_stage_output` tool: stages can now return structured JSON output instead of free-text summaries.
+- `foundry_stage_end` contract enforcement: validates stage output against the declared schema and rejects malformed responses with actionable error messages.
+- Orchestrator integration: stage output validation wired into the orchestration post-dispatch path.
+- E2E integration tests and skill guidance for the stage output tooling.
+
+### Fixed
+
+- Appraise context now prefers the cycle frontmatter `models.appraise` value over the caller's `defaultModel` when resolving the appraise subagent model.
+
+### Changed
+
+- Reviewer agent and systematic-fix-and-review skill updated.
+
 ## [3.8.5] - 2026-05-27
 
 ### Changed

package/dist/docs/architecture.md

@@ -122,7 +122,7 @@ Foundry uses HMAC-SHA256 tokens to gate stage execution. Tokens are single-use,
    - The token has not expired.
    - The claimed `stage` and `cycle` match the token's signed payload.
 4. **Activate.** On success, the stage is recorded in `.foundry/active-stage.json`. Mutation tools (`foundry_feedback_*`, `foundry_artefacts_*`, etc.) now check that their role matches the active stage.
-5. **End.** The sub-agent's **last** call is `foundry_stage_end({summary})`. This removes `.foundry/active-stage.json` and writes `.foundry/last-stage.json` for the orchestrator's finalize step.
+5. **End.** The sub-agent's **last** call is `foundry_stage_end()`. This removes `.foundry/active-stage.json` and writes `.foundry/last-stage.json` for the orchestrator's finalize step.
 6. **Finalize.** The orchestrator's internal finalize step runs after `stage_end`, scanning the git diff and committing the stage.
 
 ### Secret key

package/dist/scripts/appraise-module.js

@@ -16,6 +16,7 @@
  * action.
  */
 
+import path from 'node:path';
 import { getArtefactFiles, computeArtefactVersion } from './lib/artefacts.js';
 import { selectAppraisers, getCycleDefinition } from './lib/config.js';
 import { openFeedbackStore } from './lib/feedback-store.js';
@@ -170,9 +171,29 @@ async function resolveStaleAppraiseFeedback(ctx) {
  * appraise feedback, and advances the cycle to the next stage via finalize.
  *
  * @param {object} ctx
- * @param {Array<{ok: boolean, output?: string, error?: string}>} lastResults
+ * @param {Array<{ok: boolean, error?: string}>} lastResults
  * @returns {Promise<{ok: boolean, summary?: string}|violation>}
  */
+async function readAppraiseStageOutputs(io) {
+  try {
+    const entries = await io.readDir('.foundry/stage-outputs');
+    if (!Array.isArray(entries)) return [];
+    return entries
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => path.join('.foundry/stage-outputs', f));
+  } catch {
+    return [];
+  }
+}
+
+function cleanupStageOutputFiles(filePaths, io) {
+  for (const fp of filePaths) {
+    try { io.unlink(fp); } catch (err) {
+      if (err.code !== 'ENOENT') console.warn('appraise: failed to delete output file', fp, err.message);
+    }
+  }
+}
+
 export async function consolidateAppraise(ctx, lastResults) {
   const baseSha = ctx.activeStage?.baseSha;
   if (!baseSha) {
@@ -188,15 +209,17 @@ export async function consolidateAppraise(ctx, lastResults) {
 
   await resolveStaleAppraiseFeedback(ctx);
 
-  const consolidated = parseConsolidated(successful);
+  const filePaths = await readAppraiseStageOutputs(ctx.io);
+  const consolidated = parseConsolidated(filePaths, ctx.io);
   const stageId = `appraise:${ctx.cycleId}`;
 
   const artefactVersion = await computeAppraiseArtefactVersion(ctx);
   postConsolidatedFeedback(ctx, consolidated, artefactVersion);
   resolvePriorAppraise(ctx, consolidated, stageId);
 
-  const summary = buildConsolidateSummary(consolidated.length);
+  cleanupStageOutputFiles(filePaths, ctx.io);
 
+  const summary = buildConsolidateSummary(consolidated.length);
   return finalizeAndReturn(ctx, stageId, summary, baseSha);
 }
 
@@ -211,71 +234,51 @@ async function finalizeAndReturn(ctx, stageId, summary, baseSha) {
 }
 
 /**
- * Parse JSONL from all successful appraiser outputs and de-duplicate the
- * combined issue list by (file, law-id, issue text).
- */
-function parseConsolidated(successful) {
-  const all = [];
-
-  for (const result of successful) {
-    const issues = parseAppraiserJsonl(result.output || '');
-    all.push(...issues);
-  }
-
-  return deduplicateIssues(all);
-}
-
-/**
- * Parse appraiser JSONL output.
+ * Parse consolidated findings from stage output files and de-duplicate
+ * the combined issue list by (file, law-id, issue text).
+ *
+ * Reads each file as JSONL (one JSON object per line), parses every line,
+ * and collects appraiser findings. Invalid lines are skipped with a
+ * warning, not a crash.
  *
- * Each line must be a JSON object with at least `file` and `text` fields.
- * Extra fields (`law`, `evidence`, `severity`, `location`) are preserved.
- * The `text` field maps to the issue description used for feedback text.
+ * @param {string[]} filePaths - Array of paths to .jsonl files
+ * @param {object} io          - IO adapter with readFile
+ * @returns {Array<{file: string, law: string, issue: string, evidence: string}>}
  */
-function parseAppraiserJsonl(output) {
-  const issues = [];
-  const lines = output.trim().split('\n');
-
-  for (const line of lines) {
-    const issue = parseAppraiserLine(line);
-    if (issue) issues.push(issue);
-  }
-
-  return issues;
-}
-
-function parseAppraiserLine(line) {
-  const trimmed = line.trim();
-  if (!trimmed) return null;
-
-  const obj = tryJsonParseLine(trimmed);
-  if (!obj) return null;
-
-  return validateJsonlIssue(obj);
-}
-
-function tryJsonParseLine(line) {
-  try { return JSON.parse(line); } catch { return null; }
-}
-
-function validateJsonlIssue(obj) {
-  if (!hasStringField(obj, 'file')) return null;
-  if (!hasStringField(obj, 'text')) return null;
-
-  return {
-    file: obj.file,
-    law: strOrEmpty(obj.law),
-    issue: obj.text,
-    evidence: strOrEmpty(obj.evidence),
-  };
+function isValidIssue(obj) {
+  return Boolean(obj) && typeof obj.file === 'string' && obj.file.length > 0 && typeof obj.text === 'string' && obj.text.length > 0;
 }
 
-function hasStringField(obj, key) {
-  return typeof obj[key] === 'string' && obj[key].length > 0;
+function parseConsolidatedLine(line) {
+  try {
+    const obj = JSON.parse(line);
+    if (!isValidIssue(obj)) return null;
+    return {
+      file: obj.file,
+      law: typeof obj.law === 'string' ? obj.law : '',
+      issue: obj.text,
+      evidence: typeof obj.evidence === 'string' ? obj.evidence : '',
+    };
+  } catch {
+    return null;
+  }
 }
 
-function strOrEmpty(value) {
-  return typeof value === 'string' ? value : '';
+function parseConsolidated(filePaths, io) {
+  const all = [];
+  for (const fp of filePaths) {
+    let content;
+    try { content = io.readFile(fp); } catch (err) {
+      console.warn(`appraise: failed to read output file ${fp}:`, err.message);
+      continue;
+    }
+    const lines = content.trim().split('\n').filter(Boolean);
+    for (const line of lines) {
+      const item = parseConsolidatedLine(line);
+      if (item) all.push(item);
+    }
+  }
+  return deduplicateIssues(all);
 }
 
 /**
@@ -348,9 +351,7 @@ function resolvePriorAppraise(ctx, consolidated, stageId) {
  * Build the summary string for consolidation.
  */
 function buildConsolidateSummary(count) {
-  if (count === 0) return 'No issues found by appraisers';
-
-  return `${count} issue(s) found by appraisers`;
+  return count === 0 ? 'No issues found by appraisers' : `actioned:${count}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -362,7 +363,7 @@ function buildConsolidateSummary(count) {
  *
  * The prompt contains only the appraiser's personality and the artefact type
  * ID. The subagent discovers artefact files, laws, and file-patterns via tool
- * calls and returns JSONL — one JSON object per line.
+ * calls and uses foundry_stage_output to report each violation.
  */
 function buildAppraiserPrompt({ appraiser, typeId }) {
   const lines = [
@@ -378,16 +379,12 @@ function buildAppraiserPrompt({ appraiser, typeId }) {
     '- foundry_artefacts_list for changed files',
     '- Read matching files from the worktree',
     '',
-    'For each law, evaluate each relevant file. If a violation is found,',
-    'output a JSONL line:',
-    '',
-    '{"file": "<path>", "law": "<law-slug>", "text": "<issue description>", "evidence": "<quote>"}',
-    '',
-    '`file` and `text` are required. `law` and `evidence` are recommended.',
+    'For each violation, call `foundry_stage_output({ file, law, text, evidence })`.',
+    '`file`, `law`, and `text` are required. `evidence` is recommended.',
     'Optional fields `severity` and `location` are passed through unchanged.',
     '',
-    'Output ONLY JSONL — one JSON object per line. No markdown, no commentary.',
-    'If no issues are found, output nothing.',
+    'If no issues, call `foundry_stage_end()` directly — no `stage_output` calls needed.',
+    'Do NOT write JSONL as text. Call the tool.',
   ];
 
   return lines.join('\n');

package/dist/scripts/lib/forge-contract.js

@@ -4,12 +4,12 @@
  *
  * Rules (per spec R4):
  *   - Version changed → transition item to `actioned`.
- *   - Version unchanged + summary contains `WONT-FIX:` + source base is
- *     `appraise` → transition item to `wont-fix` with the justification
- *     as the reason.
- *   - Version unchanged + summary contains `WONT-FIX:` + source base is
+ *   - Version unchanged + output.status is `wont-fix` + source base is
+ *     `appraise` → transition item to `wont-fix` with output.reason
+ *     as the justification.
+ *   - Version unchanged + output.status is `wont-fix` + source base is
  *     NOT `appraise` → contract violation.
- *   - Version unchanged + no `WONT-FIX:` in summary → contract violation.
+ *   - Version unchanged + output.status is `done` → contract violation.
  *   - No item (null/undefined) → no-op, contract passes.
  */
 
@@ -45,12 +45,13 @@ function handleVersionChanged(item, feedbackStore, cycleId, postVersion) {
 }
 
 function handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, reason) {
+  const reasonStr = reason || '';
   const result = feedbackStore.transition({
     id: item.id,
     target: 'wont-fix',
     stage: 'forge:' + cycleId,
     cycle: cycleId,
-    reason,
+    reason: reasonStr,
   });
   if (!result.ok) {
     postSystemFeedback(feedbackStore, cycleId, postVersion, result.error || 'store transition failed');
@@ -67,21 +68,20 @@ function handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, reas
  * exists yet and subsequent runs where all items were already resolved.
  *
  * @param {{ item: object|null, preVersion: string, postVersion: string,
- *           summary: string, feedbackStore: object, cycleId: string }} params
+ *           output: { status: string, reason?: string }, feedbackStore: object,
+ *           cycleId: string }} params
  * @returns {{ contractPassed: boolean }}
  */
-export function enforceForgeContract({ item, preVersion, postVersion, summary, feedbackStore, cycleId }) {
+export function enforceForgeContract({ item, preVersion, postVersion, output, feedbackStore, cycleId }) {
   if (!item) return { contractPassed: true };
 
-  const wontFixMatch = summary.match(/WONT-FIX:\s*(.+)/);
   const versionChanged = preVersion !== postVersion;
-  const actioned = summary.trim() === 'ACTIONED';
 
-  if (wontFixMatch) {
-    return handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, wontFixMatch[1]);
+  if (output.status === 'wont-fix') {
+    return handleWontFixWithReason(item, feedbackStore, cycleId, postVersion, output.reason);
   }
 
-  if (versionChanged || actioned) {
+  if (versionChanged || output.status === 'actioned') {
     return handleVersionChanged(item, feedbackStore, cycleId, postVersion);
   }