@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/scripts/lib/feedback-store.js

@@ -0,0 +1,249 @@
+// scripts/lib/feedback-store.js
+import yaml from 'js-yaml';
+import { ulid } from './ulid.js';
+import { validateTransition, hashText, canForgeWontFix } from './feedback-transitions.js';
+
+const YAML_OPTS = { lineWidth: -1 };
+
+const VALID_SOURCE_BASES = new Set(['forge', 'quench', 'appraise', 'human-appraise']);
+
+function validateSourceBase(base) {
+  if (!VALID_SOURCE_BASES.has(base)) {
+    throw new Error(`unknown source base: ${base} (expected one of: forge, quench, appraise, human-appraise)`);
+  }
+}
+
+function validateSourceFormat(source) {
+  if (typeof source !== 'string' || !source.includes(':')) {
+    throw new Error(`source must be in 'base:alias' form; got ${JSON.stringify(source)}`);
+  }
+  const [base, ...aliasParts] = source.split(':');
+  const alias = aliasParts.join(':');
+  if (!base || !alias) {
+    throw new Error(`source must be in 'base:alias' form; got ${JSON.stringify(source)}`);
+  }
+  validateSourceBase(base);
+}
+
+function parseYamlDoc(raw) {
+  const doc = yaml.load(raw);
+  if (doc === null) return null;
+  if (!Array.isArray(doc.items)) {
+    throw new Error(`WORK.feedback.yaml malformed: top-level must be an object with an 'items' array`);
+  }
+  return doc.items;
+}
+
+function loadItems(path, io) {
+  if (!io.exists(path)) return [];
+  const raw = io.readFile(path);
+  if (!raw || !raw.trim()) return [];
+  return parseYamlDoc(raw) || [];
+}
+
+function saveItems(path, items, io) {
+  const body = yaml.dump({ items }, YAML_OPTS);
+  const tmp = `${path}.tmp`;
+  io.writeFile(tmp, body);
+  io.rename(tmp, path);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function currentState(item) {
+  return item.history[0].state;
+}
+
+function cloneItem(it) {
+  return { ...it, history: it.history.map(h => ({ ...h })) };
+}
+
+export function openFeedbackStore(path, io) {
+  let items = loadItems(path, io);
+
+  function persist(nextItems) {
+    saveItems(path, nextItems, io);
+    items = nextItems;
+  }
+
+  return {
+    list() { return items.map(cloneItem); },
+    get(id) {
+      const it = items.find(x => x.id === id);
+      return it ? cloneItem(it) : null;
+    },
+    add(params) {
+      return storeAdd(params, items, {
+        hashFn: hashText, stateOf: currentState,
+        validateSrc: validateSourceFormat, persist,
+        makeUlid: ulid, timestamp: nowIso,
+      });
+    },
+    transition(params) {
+      return storeTransition(params, items, {
+        validateTransitionFn: validateTransition,
+        canForgeWontFixFn: canForgeWontFix,
+        timestamp: nowIso, persist,
+      });
+    },
+    writeDeadlockedSnapshotForTest(params) {
+      return storeWriteDeadlockedSnapshot(params, items, {
+        timestamp: nowIso, persist,
+      });
+    },
+    writeDeadlockedSnapshots(ids, reason, stage, cycle) {
+      return storeWriteDeadlockedSnapshots({ ids, reason, stage, cycle }, items, {
+        timestamp: nowIso, persist,
+      });
+    },
+  };
+}
+
+function isDuplicate(item, file, tag, textHash, stateOf) {
+  return item.file === file &&
+    item.tag === tag &&
+    hashText(item.text) === textHash &&
+    stateOf(item) !== 'resolved';
+}
+
+function assertAddParams(...params) {
+  for (const p of params) {
+    if (!p) throw new Error('add requires file, tag, text, source, cycle');
+  }
+}
+
+function storeAdd(params, items, deps) {
+  const { file, tag, text, source, cycle } = params;
+  const { hashFn, stateOf, validateSrc, persist, makeUlid, timestamp } = deps;
+  assertAddParams(file, tag, text, source, cycle);
+  validateSrc(source);
+
+  const textHash = hashFn(text);
+  const existing = items.find(it => isDuplicate(it, file, tag, textHash, stateOf));
+  if (existing) return { id: existing.id, deduped: true };
+
+  const id = makeUlid();
+  const item = {
+    id, file, tag, text, source,
+    history: [{ state: 'open', stage: source, cycle, timestamp: timestamp() }],
+  };
+  persist([...items, item]);
+  return { id, deduped: false };
+}
+
+function forgeWontFixAllowed(item, stageBase, target, canForgeWontFixFn) {
+  if (stageBase !== 'forge') return true;
+  if (target !== 'wont-fix') return true;
+  return canForgeWontFixFn(item, stageBase);
+}
+
+function forgeWontFixError(item) {
+  return `forge may only mark wont-fix on feedback whose source is ` +
+    `appraise; this item's source is ${item.source}`;
+}
+
+function reasonRequiredForTransition(target, current, reason) {
+  const REASON_REQUIRED_TARGETS = new Set(['rejected', 'wont-fix']);
+  return (REASON_REQUIRED_TARGETS.has(target) || current === 'deadlocked')
+    && (!reason || !reason.trim());
+}
+
+function sourceMatchesStage(stageBase, stage, itemSource) {
+  return stageBase === 'human-appraise' || stage === itemSource;
+}
+
+function validateTransitionInput(item, ctx, fns) {
+  if (!forgeWontFixAllowed(item, ctx.stageBase, ctx.target, fns.canForgeWontFixFn)) {
+    return forgeWontFixError(item);
+  }
+  const current = item.history[0].state;
+  const check = fns.validateTransitionFn({
+    currentState: current, target: ctx.target, stageBase: ctx.stageBase,
+    sourceMatches: sourceMatchesStage(ctx.stageBase, ctx.stage, item.source),
+  });
+  if (!check.ok) return check.reason;
+  if (reasonRequiredForTransition(ctx.target, current, ctx.reason)) {
+    return `reason is required for transition → ${ctx.target}`;
+  }
+  return null;
+}
+
+function hasNonEmptyReason(reason) {
+  return Boolean(reason && reason.trim());
+}
+
+function applyTransition(items, id, snapshot) {
+  return items.map(it =>
+    it.id === id ? { ...it, history: [snapshot, ...it.history] } : it
+  );
+}
+
+function storeTransition(params, items, deps) {
+  const { id, target, stage, cycle, reason } = params;
+  const { validateTransitionFn, canForgeWontFixFn, timestamp, persist } = deps;
+
+  const item = items.find(x => x.id === id);
+  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
+
+  const stageBase = stage.split(':')[0];
+  const error = validateTransitionInput(item,
+    { stageBase, stage, target, reason },
+    { canForgeWontFixFn, validateTransitionFn },
+  );
+  if (error) return { ok: false, error };
+
+  const snapshot = { state: target, stage, cycle, timestamp: timestamp() };
+  if (hasNonEmptyReason(reason)) snapshot.reason = reason;
+
+  persist(applyTransition(items, id, snapshot));
+  return { ok: true };
+}
+
+function storeWriteDeadlockedSnapshot(params, items, deps) {
+  const { id, cycle, reason } = params;
+  const { timestamp, persist } = deps;
+
+  const item = items.find(x => x.id === id);
+  if (!item) return { ok: false, error: `feedback item not found: ${id}` };
+  if (!reason || !reason.trim()) {
+    return { ok: false, error: 'reason is required for deadlocked snapshot' };
+  }
+
+  const snapshot = { state: 'deadlocked', stage: 'sort', cycle, timestamp: timestamp(), reason };
+  persist(items.map(it =>
+    it.id === id ? { ...it, history: [snapshot, ...it.history] } : it
+  ));
+  return { ok: true };
+}
+
+function assertDeadlockedSnapshotArgs(ids, reason) {
+  if (!Array.isArray(ids)) return { ok: false, error: 'ids must be an array' };
+  if (ids.length === 0) return { ok: true };
+  if (!reason) return { ok: false, error: 'reason is required for deadlocked snapshot' };
+  return null;
+}
+
+function storeWriteDeadlockedSnapshots(params, items, deps) {
+  const { ids, reason, stage, cycle } = params;
+  const { timestamp, persist } = deps;
+
+  const precheck = assertDeadlockedSnapshotArgs(ids, reason);
+  if (precheck) return precheck;
+
+  const ts = timestamp();
+  const idSet = new Set(ids);
+  const nextItems = items.map(it => {
+    if (!idSet.has(it.id)) return it;
+    return { ...it, history: [{ state: 'deadlocked', stage, cycle, timestamp: ts, reason }, ...it.history] };
+  });
+  for (const id of ids) {
+    if (!items.some(it => it.id === id)) {
+      return { ok: false, error: `feedback item(s) not found: ${id}` };
+    }
+  }
+
+  persist(nextItems);
+  return { ok: true };
+}

package/dist/scripts/lib/feedback-transitions.js

@@ -0,0 +1,105 @@
+// scripts/lib/feedback-transitions.js
+import { createHash } from 'node:crypto';
+
+// State machine per spec §5.
+//
+// States: open, actioned, wont-fix, rejected, deadlocked, resolved (terminal).
+//
+// Transition rules (spec §5.1):
+//   1. Forge operates on {open, rejected} → {actioned, wont-fix}.
+//   2. Source-stage (quench/appraise/human-appraise) operates on {actioned, wont-fix}
+//      → {resolved, rejected}, when caller's stageId === item.source.
+//   3. Sort writes 'deadlocked' via its own state machine logic (spec §6.1).
+//      Forge, quench, appraise, and human-appraise use this validator.
+//   4. Human-appraise override: on a deadlocked item, transitions to
+//      {resolved, rejected} are legal regardless of source match. The
+//      override authority mirrors the source-stage targets — wont-fix is
+//      a forge declaration ("considered, choosing to defer") and stays
+//      outside reviewer verdicts, excluded here per spec.
+//   5. 'resolved' is terminal.
+//
+// validateTransition takes an options object so new dimensions (sourceMatches,
+// potential future flags) don't break the call shape.
+
+const FORGE_TARGETS = new Set(['actioned', 'wont-fix']);
+const SOURCE_TARGETS = new Set(['resolved', 'rejected']);
+const HUMAN_OVERRIDE_TARGETS = new Set(['resolved', 'rejected']);
+const KNOWN_STATES = new Set(['open', 'actioned', 'wont-fix', 'rejected', 'deadlocked', 'resolved']);
+const SOURCE_STAGES = new Set(['quench', 'appraise', 'human-appraise']);
+
+function validateDeadlocked(target, stageBase) {
+  if (stageBase !== 'human-appraise') {
+    return { ok: false, reason: `only human-appraise may resolve a deadlocked item; got ${stageBase}` };
+  }
+  if (!HUMAN_OVERRIDE_TARGETS.has(target)) {
+    return { ok: false, reason: `invalid deadlock-override transition → ${target}` };
+  }
+  return { ok: true };
+}
+
+function validateForge(currentState, target) {
+  if (currentState !== 'open' && currentState !== 'rejected') {
+    return { ok: false, reason: `forge cannot transition from ${currentState}` };
+  }
+  if (!FORGE_TARGETS.has(target)) {
+    return { ok: false, reason: `forge cannot produce ${target}` };
+  }
+  return { ok: true };
+}
+
+function validateSourceStage(currentState, target, stageBase, sourceMatches) {
+  if (currentState !== 'actioned' && currentState !== 'wont-fix') {
+    return { ok: false, reason: `${stageBase} cannot transition from ${currentState}` };
+  }
+  if (!SOURCE_TARGETS.has(target)) {
+    return { ok: false, reason: `${stageBase} cannot produce ${target}` };
+  }
+  if (!sourceMatches) {
+    return { ok: false, reason: `only the source stage may resolve/reject this item` };
+  }
+  return { ok: true };
+}
+
+function checkPreconditions(currentState, sourceMatches) {
+  if (typeof sourceMatches !== 'boolean') {
+    throw new TypeError(
+      `validateTransition: sourceMatches must be a boolean; got ${typeof sourceMatches}`
+    );
+  }
+  if (!KNOWN_STATES.has(currentState)) return { ok: false, reason: `unknown state: ${currentState}` };
+  if (currentState === 'resolved') return { ok: false, reason: 'resolved is terminal' };
+  return null;
+}
+
+export function validateTransition({ currentState, target, stageBase, sourceMatches }) {
+  const pre = checkPreconditions(currentState, sourceMatches);
+  if (pre) return pre;
+  if (currentState === 'deadlocked') return validateDeadlocked(target, stageBase);
+  if (stageBase === 'forge') return validateForge(currentState, target);
+  if (SOURCE_STAGES.has(stageBase)) return validateSourceStage(currentState, target, stageBase, sourceMatches);
+  return { ok: false, reason: `unsupported stage base: ${stageBase}` };
+}
+
+export function hashText(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+
+/**
+ * Per spec §5.1 rule 7 (REVISION-CONTRACT §A2): forge may produce the
+ * `wont-fix` target when the source stage base is `appraise`.
+ * For `quench`- or `human-appraise`-sourced items, forge's legal
+ * target from {open, rejected} is `actioned`.
+ *
+ * Forge-specific helper. Forge callers check this before attempting wont-fix
+ * transitions. Other stages use validateTransition directly.
+ *
+ * @param {{source: string}} item — feedback item; `source` is `base:alias`.
+ * @param {string} callerStageBase — the caller's stage base (e.g. 'forge').
+ * @returns {boolean}
+ */
+export function canForgeWontFix(item, callerStageBase) {
+  if (callerStageBase !== 'forge') return false;
+  if (!item || typeof item.source !== 'string' || !item.source) return false;
+  const sourceBase = item.source.split(':')[0];
+  return sourceBase === 'appraise';
+}

package/dist/scripts/lib/finalize.js

@@ -0,0 +1,70 @@
+// scripts/lib/finalize.js
+import { minimatch } from 'minimatch';
+import { sortPaths } from './attestation/hash.js';
+import { isToolManaged } from './git-policy.js';
+
+// Accepts short (>=7) and full (<=64) hex SHAs. Rejects symbolic refs (HEAD),
+// argument-injection (--upload-pack=...), and shell metacharacters. The
+// practical attack surface is .foundry/active-stage.json and last-stage.json,
+// which are persisted on disk and may be edited or corrupted; we validate
+// here for defence-in-depth before passing the value to git.
+const SHA_RE = /^[0-9a-f]{7,64}$/i;
+
+function assertValidSha(baseSha) {
+  if (typeof baseSha !== 'string' || !SHA_RE.test(baseSha)) {
+    throw new Error(`invalid baseSha: ${JSON.stringify(baseSha)}`);
+  }
+}
+
+function git(exec, args) {
+  return exec(['git', ...args]).toString().split('\n').filter(Boolean);
+}
+
+function changedFiles(exec, baseSha) {
+  const tracked = git(exec, ['diff', '--name-only', '--no-renames', baseSha, 'HEAD']);
+  const diffUnstaged = git(exec, ['diff', '--name-only', '--no-renames']);
+  const diffStaged = git(exec, ['diff', '--cached', '--name-only', '--no-renames']);
+  const untracked = git(exec, ['ls-files', '--others', '--exclude-standard']);
+  return [...new Set([...tracked, ...diffUnstaged, ...diffStaged, ...untracked])];
+}
+
+function getAllowedPatterns(stageBase, cycleDef, artefactTypes) {
+  if (stageBase === 'forge') {
+    return artefactTypes[cycleDef.outputArtefactType]?.filePatterns ?? [];
+  }
+  if (stageBase === 'assay') {
+    return ['foundry-memory/**'];
+  }
+  return [];
+}
+
+function classifyFiles(files, allowedPatterns) {
+  const unexpected = [];
+  const matched = [];
+  for (const f of files) {
+    const hit = allowedPatterns.find(p => minimatch(f, p));
+    if (hit) matched.push(f);
+    else unexpected.push(f);
+  }
+  return { matched, unexpected };
+}
+
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, registerArtefact, io }) {
+  if (!io?.exec) {
+    throw new Error('finalizeStage: io.exec is required');
+  }
+  assertValidSha(baseSha);
+  const files = changedFiles(io.exec, baseSha).filter(f => !isToolManaged(f));
+  const allowedPatterns = getAllowedPatterns(stageBase, cycleDef, artefactTypes);
+  const { matched, unexpected } = classifyFiles(files, allowedPatterns);
+  if (unexpected.length) return { ok: false, error: 'unexpected_files', files: unexpected };
+  const sortedFiles = sortPaths(matched);
+  // For non-forge stages, matched files are tool-managed side effects
+  // (e.g. assay's memory writes) that should not become artefacts.
+  if (stageBase !== 'forge') return { ok: true, artefacts: [], changedFiles: sortedFiles };
+  const artefacts = sortedFiles.map(file => {
+    registerArtefact({ file, type: cycleDef.outputArtefactType, status: 'draft' });
+    return { file, type: cycleDef.outputArtefactType, status: 'draft' };
+  });
+  return { ok: true, artefacts, changedFiles: sortedFiles };
+}

package/dist/scripts/lib/foundational-guards.js

@@ -0,0 +1,13 @@
+export function requireGitRepo(io) {
+  if (io.exists('.git')) return { ok: true };
+  return { ok: false, error: 'not a git repository (no .git directory at worktree root)' };
+}
+
+export function requireFoundryRoot(io) {
+  // Probe the bare directory name — matches requireGitRepo's '.git'.
+  if (io.exists('foundry')) return { ok: true };
+  return {
+    ok: false,
+    error: 'foundry/ directory not found at worktree root. Run the init-foundry skill to scaffold it.',
+  };
+}

package/dist/scripts/lib/git-bridge.js

@@ -0,0 +1,77 @@
+// scripts/lib/git-bridge.js
+//
+// Policy-enforcing git commit helper used by the orchestrator.
+//
+// This helper stages exactly the paths allowed for the current phase and
+// creates the commit. It:
+//
+//   1. Reads the worktree status (NUL-terminated) so paths with spaces /
+//      renames are handled safely.
+//   2. Partitions dirty files against the phase's allowed patterns and
+//      Foundry's tool-managed list (WORK.md / WORK.history.yaml /
+//      WORK.feedback.yaml / .foundry/**).
+//   3. If anything unexpected is dirty, throws a structured error with the
+//      offending file list — the orchestrator turns this into a `violation`
+//      action with `affected_files`. Nothing is staged or committed.
+//   4. Stages allowed paths explicitly via argv and creates the commit.
+//
+// `execFile` is injected so tests can drive the helper.
+//
+// Returns the short commit SHA on success.
+
+import { partitionDirty, parsePorcelainZ } from './git-policy.js';
+
+class UnexpectedFilesError extends Error {
+  constructor(files) {
+    super(`unexpected_files: ${files.length} file(s)`);
+    this.code = 'unexpected_files';
+    this.files = files;
+  }
+}
+
+export { UnexpectedFilesError };
+
+/**
+ * @param {object} opts
+ * @param {string} opts.message      Commit message.
+ * @param {string[]} [opts.allowedPatterns]  Globs allowed to be dirty for this phase.
+ * @param {(args: string[]) => string} opts.execFile
+ *   Synchronous git runner: receives argv (no `git`), returns stdout as utf-8.
+ * @returns {string|null}  Short SHA of the new commit, or null if the worktree
+ *   is clean (nothing to commit).
+ * @throws {UnexpectedFilesError} if the worktree contains any file outside
+ *   the tool-managed list and the allow list. Nothing is staged in this case.
+ */
+export function commitWithPolicy({
+  message,
+  allowedPatterns = [],
+  execFile,
+}) {
+  const porcelain = execFile(['status', '-z', '--porcelain', '--untracked-files=all']);
+  const dirty = parsePorcelainZ(porcelain);
+  const { allowed, unexpected } = partitionDirty(dirty, allowedPatterns);
+  if (unexpected.length) throw new UnexpectedFilesError(unexpected);
+
+  // Reset the index so a previous `git add` of an unexpected file (e.g. left
+  // over from a failed run) cannot leak into our commit. Then add the
+  // allowed paths explicitly via argv.
+  execFile(['reset', '--quiet']);
+  if (allowed.length === 0) {
+    // Nothing to commit; the worktree is clean of any change we'd be
+    // expected to capture. Return null so the caller knows no SHA was made.
+    return null;
+  }
+  
+  // Wrap add + commit in try/catch to maintain atomicity guarantee.
+  // If commit fails (pre-commit hook reject, gpg error, empty commit after
+  // gitignore filtering), we must reset the index to restore "Nothing is
+  // staged or committed" invariant.
+  try {
+    execFile(['add', '--', ...allowed]);
+    execFile(['commit', '-m', message]);
+  } catch (err) {
+    execFile(['reset', '--quiet']);
+    throw err;
+  }
+  return execFile(['rev-parse', '--short', 'HEAD']).trim();
+}