@really-knows-ai/foundry 2.0.1 → 2.2.1

package/scripts/lib/feedback-transitions.js

@@ -0,0 +1,25 @@
+import { createHash } from 'node:crypto';
+
+// Matrix: [current][target] => set of allowed stageBases
+const MATRIX = {
+  open:       { actioned: ['forge'], 'wont-fix': ['forge'] },
+  actioned:   { approved: ['quench', 'appraise', 'human-appraise'], rejected: ['quench', 'appraise', 'human-appraise'] },
+  'wont-fix': { approved: ['appraise', 'human-appraise'], rejected: ['appraise', 'human-appraise'] },
+  rejected:   { actioned: ['forge'], 'wont-fix': ['forge'] },
+  approved:   {}, // terminal
+};
+
+export function validateTransition(current, target, stageBase) {
+  const row = MATRIX[current];
+  if (!row) return { ok: false, reason: `unknown state: ${current}` };
+  const allowedStages = row[target];
+  if (!allowedStages) return { ok: false, reason: `invalid transition ${current} → ${target}` };
+  if (!allowedStages.includes(stageBase)) {
+    return { ok: false, reason: `stage ${stageBase} cannot transition ${current} → ${target}` };
+  }
+  return { ok: true };
+}
+
+export function hashText(text) {
+  return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}

package/scripts/lib/feedback.js

@@ -3,6 +3,7 @@
  */
 
 import { extractAllTags } from './tags.js';
+import { validateTransition, hashText } from './feedback-transitions.js';
 
 // ---------------------------------------------------------------------------
 // Parsing
@@ -85,6 +86,16 @@ export function parseFeedback(text, cycle, artefacts) {
 // ---------------------------------------------------------------------------
 
 export function addFeedbackItem(text, file, itemText, tag) {
+  // Dedup by (file, tag, text hash): if any existing item under this file
+  // heading has the same tag and the same itemText, return without mutating.
+  const existing = collectItemsForFile(text, file);
+  const h = hashText(itemText);
+  for (const ex of existing) {
+    if (ex.tags.includes(`#${tag}`) && hashText(ex.coreText) === h) {
+      return { text, deduped: true };
+    }
+  }
+
   const newItem = `- [ ] ${itemText} #${tag}`;
   const lines = text.split('\n');
 
@@ -111,7 +122,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (feedbackIdx === -1) {
     // No Feedback section — append one
     lines.push('', '## Feedback', '', `### ${file}`, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find the file heading within the feedback section
@@ -135,7 +146,7 @@ export function addFeedbackItem(text, file, itemText, tag) {
   if (fileIdx === -1) {
     // File heading doesn't exist — add it before section end
     lines.splice(sectionEnd, 0, '', fileHeading, newItem);
-    return lines.join('\n');
+    return { text: lines.join('\n'), deduped: false };
   }
 
   // Find last item under this file heading
@@ -149,23 +160,23 @@ export function addFeedbackItem(text, file, itemText, tag) {
   }
 
   lines.splice(insertIdx, 0, newItem);
-  return lines.join('\n');
+  return { text: lines.join('\n'), deduped: false };
 }
 
-export function actionFeedbackItem(text, file, index) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function actionFeedbackItem(text, file, index, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'actioned', stageBase, (line) =>
     line.replace('- [ ]', '- [x]')
   );
 }
 
-export function wontfixFeedbackItem(text, file, index, reason) {
-  return transformFeedbackItem(text, file, index, (line) =>
+export function wontfixFeedbackItem(text, file, index, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, 'wont-fix', stageBase, (line) =>
     line.replace('- [ ]', '- [~]') + ` | wont-fix: ${reason}`
   );
 }
 
-export function resolveFeedbackItem(text, file, index, resolution, reason) {
-  return transformFeedbackItem(text, file, index, (line) => {
+export function resolveFeedbackItem(text, file, index, resolution, reason, stageBase) {
+  return transformFeedbackItemWithValidation(text, file, index, resolution, stageBase, (line) => {
     if (resolution === 'approved') {
       return line + ' | approved';
     }
@@ -257,6 +268,132 @@ export function detectDeadlocks(feedback, history, threshold = 3) {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Collect feedback items under a specific file heading, returning the parsed
+ * representation plus the "core text" (item body with tag and trailing resolution
+ * stripped) for dedup hashing.
+ */
+function collectItemsForFile(text, file) {
+  const items = [];
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+
+  for (const line of lines) {
+    const stripped = line.trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      const parsed = parseFeedbackItem(stripped);
+      // Strip checkbox, tags, and trailing `| approved` / `| rejected: ...` /
+      // `| wont-fix: ...` to get the core author-supplied text for dedup.
+      let core = stripped.replace(/^- \[[ x~]\]\s*/, '');
+      core = core.replace(/\s*\|\s*(approved|rejected[^|]*|wont-fix[^|]*)\s*$/, '');
+      for (const t of parsed.tags) {
+        core = core.replace(t, '');
+      }
+      core = core.trim();
+      items.push({ line: stripped, state: parsed.state, tags: parsed.tags, coreText: core });
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Read the line at (file, index) and return its current feedback state
+ * (or null if not found).
+ */
+function readItemState(text, file, index) {
+  const lines = text.split('\n');
+  let inFeedback = false;
+  let feedbackLevel = 0;
+  let currentFile = null;
+  let fileIndex = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const stripped = lines[i].trim();
+
+    if (stripped === '# Feedback' || stripped === '## Feedback') {
+      inFeedback = true;
+      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
+      continue;
+    }
+
+    if (inFeedback && /^#{1,2} /.test(stripped)) {
+      const level = stripped.startsWith('## ') ? 2 : 1;
+      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
+        inFeedback = false;
+        continue;
+      }
+    }
+
+    if (!inFeedback) continue;
+
+    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
+    if (stripped.startsWith(fileHeadingPrefix)) {
+      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
+      fileIndex = 0;
+      continue;
+    }
+
+    if (currentFile === file && /^- \[/.test(stripped)) {
+      if (fileIndex === index) {
+        const parsed = parseFeedbackItem(stripped);
+        // Map parseFeedbackItem's (state, resolved) pair onto state-machine states:
+        // - `| approved` → terminal "approved"
+        // - `| rejected` → "rejected" (parseFeedbackItem already sets this)
+        // - bare `[x]`   → "actioned"
+        // - bare `[~]`   → "wont-fix"
+        // - bare `[ ]`   → "open"
+        if (parsed.resolved) return 'approved';
+        return parsed.state;
+      }
+      fileIndex++;
+    }
+  }
+  return null;
+}
+
+function transformFeedbackItemWithValidation(text, file, index, target, stageBase, transform) {
+  if (stageBase !== undefined) {
+    const current = readItemState(text, file, index);
+    if (!current) {
+      return { ok: false, error: `feedback item not found: file=${file} index=${index}` };
+    }
+    const v = validateTransition(current, target, stageBase);
+    if (!v.ok) {
+      return { ok: false, error: v.reason };
+    }
+    const updated = transformFeedbackItem(text, file, index, transform);
+    return { ok: true, text: updated };
+  }
+  // Backward-compatible path: return plain string.
+  return transformFeedbackItem(text, file, index, transform);
+}
+
 function transformFeedbackItem(text, file, index, transform) {
   const lines = text.split('\n');
   let inFeedback = false;

package/scripts/lib/finalize.js

@@ -0,0 +1,41 @@
+// scripts/lib/finalize.js
+import { execSync } from 'node:child_process';
+import { minimatch } from 'minimatch';
+
+const TOOL_MANAGED = [
+  'WORK.md',
+  'WORK.history.yaml',
+];
+const TOOL_MANAGED_PREFIX = ['.foundry/'];
+
+function changedFiles(cwd, baseSha) {
+  const tracked = execSync(`git diff --name-only ${baseSha} HEAD`, { cwd }).toString().split('\n').filter(Boolean);
+  const diffUnstaged = execSync('git diff --name-only', { cwd }).toString().split('\n').filter(Boolean);
+  const untracked = execSync('git ls-files --others --exclude-standard', { cwd }).toString().split('\n').filter(Boolean);
+  return [...new Set([...tracked, ...diffUnstaged, ...untracked])];
+}
+
+function isToolManaged(f) {
+  if (TOOL_MANAGED.includes(f)) return true;
+  return TOOL_MANAGED_PREFIX.some(p => f.startsWith(p));
+}
+
+export function finalizeStage({ cwd, baseSha, stageBase, cycleDef, artefactTypes, registerArtefact }) {
+  const files = changedFiles(cwd, baseSha).filter(f => !isToolManaged(f));
+  const allowedPatterns = stageBase === 'forge'
+    ? (artefactTypes[cycleDef.outputArtefactType]?.filePatterns ?? [])
+    : [];
+  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);
+  }
+  if (unexpected.length) return { ok: false, error: 'unexpected_files', files: unexpected };
+  const artefacts = matched.map(file => {
+    registerArtefact({ file, type: cycleDef.outputArtefactType, status: 'draft' });
+    return { file, type: cycleDef.outputArtefactType, status: 'draft' };
+  });
+  return { ok: true, artefacts };
+}

package/scripts/lib/history.js

@@ -18,7 +18,7 @@ export function loadHistory(historyPath, cycle, io) {
 /**
  * Append a history entry with auto-generated ISO timestamp.
  */
-export function appendEntry(historyPath, { cycle, stage, iteration, comment }, io) {
+export function appendEntry(historyPath, { cycle, stage, iteration, comment, route }, io) {
   if (iteration == null) throw new Error('iteration is required');
   if (!comment) throw new Error('comment is required');
 
@@ -27,13 +27,15 @@ export function appendEntry(historyPath, { cycle, stage, iteration, comment }, i
     existing = yaml.load(io.readFile(historyPath)) || [];
   }
 
-  existing.push({
+  const entry = {
     cycle,
     stage,
     iteration,
     comment,
     timestamp: new Date().toISOString(),
-  });
+  };
+  if (route !== undefined) entry.route = route;
+  existing.push(entry);
 
   io.writeFile(historyPath, yaml.dump(existing));
 }
@@ -45,3 +47,13 @@ export function getIteration(historyPath, cycle, io) {
   const history = loadHistory(historyPath, cycle, io);
   return history.filter(e => (e.stage || '').split(':')[0] === 'forge').length;
 }
+
+/**
+ * Return the `route` field from the most recent `sort` history entry for a
+ * given cycle, or null if none exists.
+ */
+export function readLastSortRoute(historyPath, cycle, io) {
+  const entries = loadHistory(historyPath, cycle, io).filter(e => e.stage === 'sort');
+  if (!entries.length) return null;
+  return entries[entries.length - 1].route ?? null;
+}

package/scripts/lib/pending.js

@@ -0,0 +1,18 @@
+export function createPendingStore() {
+  const map = new Map();
+  return {
+    add(nonce, meta) { map.set(nonce, meta); },
+    consume(nonce) {
+      const meta = map.get(nonce);
+      if (!meta) return null;
+      map.delete(nonce);
+      if (meta.exp < Date.now()) return null;
+      return meta;
+    },
+    size() {
+      const now = Date.now();
+      for (const [k, v] of map) if (v.exp < now) map.delete(k);
+      return map.size;
+    },
+  };
+}

package/scripts/lib/secret.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync, mkdirSync, openSync, writeSync, closeSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+export function readOrCreateSecret(directory) {
+  const dir = join(directory, '.foundry');
+  const file = join(dir, '.secret');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const bytes = randomBytes(32);
+  let fd;
+  try {
+    fd = openSync(file, 'wx', 0o600);
+  } catch (err) {
+    if (err.code === 'EEXIST') return readFileSync(file);
+    throw err;
+  }
+  try {
+    writeSync(fd, bytes);
+  } finally {
+    closeSync(fd);
+  }
+  return bytes;
+}

package/scripts/lib/slug.js

@@ -0,0 +1,33 @@
+/**
+ * Slug utilities for generating shell-safe, git-ref-safe identifiers.
+ */
+
+/**
+ * Convert an arbitrary string into a URL/git-branch-friendly slug.
+ *
+ * Rules:
+ * - Strips diacritics (e.g. "café" → "cafe")
+ * - Lowercases
+ * - Replaces any run of non-[a-z0-9] characters with a single dash
+ * - Trims leading/trailing dashes
+ *
+ * Throws if the input is not a string or if the resulting slug is empty.
+ */
+export function slugify(input) {
+  if (typeof input !== 'string') {
+    throw new TypeError(`slugify: expected string, got ${typeof input}`);
+  }
+
+  const slug = input
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  if (slug.length === 0) {
+    throw new Error(`slugify: input produced empty slug (input: ${JSON.stringify(input)})`);
+  }
+
+  return slug;
+}

package/scripts/lib/stage-guard.js

@@ -0,0 +1,25 @@
+// scripts/lib/stage-guard.js
+import { readActiveStage } from './state.js';
+
+export function stageBaseOf(stage) {
+  const i = stage.indexOf(':');
+  return i === -1 ? stage : stage.slice(0, i);
+}
+
+export function requireNoActiveStage(io) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: true };
+  return { ok: false, error: `tool requires no active stage; current: ${a.stage}` };
+}
+
+export function requireActiveStage(io, { stageBase, cycle } = {}) {
+  const a = readActiveStage(io);
+  if (!a) return { ok: false, error: `tool requires active stage; current: none` };
+  if (stageBase && stageBaseOf(a.stage) !== stageBase) {
+    return { ok: false, error: `tool requires active ${stageBase} stage; current: ${a.stage}` };
+  }
+  if (cycle && a.cycle !== cycle) {
+    return { ok: false, error: `tool requires active stage in cycle ${cycle}; current cycle: ${a.cycle}` };
+  }
+  return { ok: true, active: a };
+}

package/scripts/lib/state.js

@@ -0,0 +1,31 @@
+const ACTIVE = '.foundry/active-stage.json';
+const LAST = '.foundry/last-stage.json';
+const DIR = '.foundry';
+
+export function ensureFoundryDir(io) {
+  if (!io.exists(DIR)) io.mkdir(DIR);
+}
+
+export function readActiveStage(io) {
+  if (!io.exists(ACTIVE)) return null;
+  return JSON.parse(io.readFile(ACTIVE));
+}
+
+export function writeActiveStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(ACTIVE, JSON.stringify(payload, null, 2));
+}
+
+export function clearActiveStage(io) {
+  io.unlink(ACTIVE);
+}
+
+export function readLastStage(io) {
+  if (!io.exists(LAST)) return null;
+  return JSON.parse(io.readFile(LAST));
+}
+
+export function writeLastStage(io, payload) {
+  ensureFoundryDir(io);
+  io.writeFile(LAST, JSON.stringify(payload, null, 2));
+}

package/scripts/lib/token.js

@@ -0,0 +1,26 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+export function signToken(payload, secret) {
+  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const mac = createHmac('sha256', secret).update(body).digest('base64url');
+  return `${body}.${mac}`;
+}
+
+export function verifyToken(token, secret) {
+  if (typeof token !== 'string' || !token.includes('.')) return { ok: false, reason: 'malformed' };
+  const [body, mac] = token.split('.');
+  if (!body || !mac) return { ok: false, reason: 'malformed' };
+  const expected = createHmac('sha256', secret).update(body).digest();
+  let given;
+  try { given = Buffer.from(mac, 'base64url'); } catch { return { ok: false, reason: 'malformed' }; }
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  let payload;
+  try { payload = JSON.parse(Buffer.from(body, 'base64url').toString()); }
+  catch { return { ok: false, reason: 'malformed' }; }
+  if (typeof payload.exp !== 'number' || payload.exp < Date.now()) {
+    return { ok: false, reason: 'expired' };
+  }
+  return { ok: true, payload };
+}

package/scripts/lib/workfile.js

@@ -11,7 +11,16 @@ import yaml from 'js-yaml';
 export function parseFrontmatter(text) {
   const match = text.match(/^---\n(.+?)\n---/s);
   if (!match) return {};
-  return yaml.load(match[1]) || {};
+  const fm = yaml.load(match[1]) || {};
+  // Normalize: on-disk canonical key is `max-iterations` (kebab).
+  // Tolerate legacy `maxIterations` (camel) by rewriting on read.
+  if (fm.maxIterations !== undefined) {
+    if (fm['max-iterations'] === undefined) {
+      fm['max-iterations'] = fm.maxIterations;
+    }
+    delete fm.maxIterations;
+  }
+  return fm;
 }
 
 export function writeFrontmatter(fields) {
@@ -25,6 +34,8 @@ export function getFrontmatterField(text, key) {
 }
 
 export function setFrontmatterField(text, key, value) {
+  // Coerce legacy camelCase key to canonical kebab form on write.
+  if (key === 'maxIterations') key = 'max-iterations';
   const fm = parseFrontmatter(text);
   fm[key] = value;
   const fmBlock = writeFrontmatter(fm);