@really-knows-ai/foundry 2.3.2 → 3.0.1

package/scripts/lib/feedback.js

@@ -1,440 +0,0 @@
-/**
- * Feedback parsing and manipulation utilities for WORK.md.
- */
-
-import { extractAllTags } from './tags.js';
-import { validateTransition, hashText } from './feedback-transitions.js';
-
-// ---------------------------------------------------------------------------
-// Parsing
-// ---------------------------------------------------------------------------
-
-export function parseFeedbackItem(line) {
-  const item = { raw: line, state: 'unknown', tags: [], resolved: false };
-
-  if (line.startsWith('- [ ]')) {
-    item.state = 'open';
-  } else if (line.startsWith('- [x]')) {
-    item.state = 'actioned';
-  } else if (line.startsWith('- [~]')) {
-    item.state = 'wont-fix';
-  }
-
-  if (line.includes('| approved')) {
-    item.resolved = true;
-  } else if (line.includes('| rejected')) {
-    item.state = 'rejected';
-    item.resolved = false;
-  }
-
-  item.tags = extractAllTags(line);
-
-  return item;
-}
-
-export function parseFeedback(text, cycle, artefacts) {
-  const cycleFiles = new Set();
-  for (const art of artefacts) {
-    if (art.cycle === cycle) {
-      cycleFiles.add(art.file || '');
-    }
-  }
-  const filterByFile = cycleFiles.size > 0;
-
-  const items = [];
-  let currentFile = null;
-  let inFeedback = false;
-  let feedbackLevel = 0;
-
-  for (const line of text.split('\n')) {
-    const stripped = line.trim();
-
-    if (stripped === '# Feedback' || stripped === '## Feedback') {
-      inFeedback = true;
-      feedbackLevel = stripped.startsWith('## ') ? 2 : 1;
-      continue;
-    }
-
-    // Exit feedback on a heading at the same or higher level
-    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;
-
-    // File sub-headings are one level below the Feedback heading
-    const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
-    if (stripped.startsWith(fileHeadingPrefix)) {
-      currentFile = stripped.slice(fileHeadingPrefix.length).trim();
-      continue;
-    }
-
-    if ((!filterByFile || cycleFiles.has(currentFile)) && /^- \[/.test(stripped)) {
-      items.push(parseFeedbackItem(stripped));
-    }
-  }
-
-  return items;
-}
-
-// ---------------------------------------------------------------------------
-// Manipulation
-// ---------------------------------------------------------------------------
-
-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');
-
-  // Find ## Feedback section
-  let feedbackIdx = -1;
-  let feedbackLevel = 0;
-  for (let i = 0; i < lines.length; i++) {
-    const stripped = lines[i].trim();
-    if (stripped === '## Feedback') {
-      feedbackIdx = i;
-      feedbackLevel = 2;
-      break;
-    }
-    if (stripped === '# Feedback') {
-      feedbackIdx = i;
-      feedbackLevel = 1;
-      break;
-    }
-  }
-
-  const fileHeadingPrefix = feedbackLevel === 1 ? '## ' : '### ';
-  const fileHeading = `${fileHeadingPrefix}${file}`;
-
-  if (feedbackIdx === -1) {
-    // No Feedback section — append one
-    lines.push('', '## Feedback', '', `### ${file}`, newItem);
-    return { text: lines.join('\n'), deduped: false };
-  }
-
-  // Find the file heading within the feedback section
-  let fileIdx = -1;
-  let sectionEnd = lines.length; // end of feedback section
-  for (let i = feedbackIdx + 1; i < lines.length; i++) {
-    const stripped = lines[i].trim();
-    // Check if we've left the feedback section
-    if (/^#{1,2} /.test(stripped)) {
-      const level = stripped.startsWith('## ') ? 2 : 1;
-      if (level <= feedbackLevel && stripped !== '# Feedback' && stripped !== '## Feedback') {
-        sectionEnd = i;
-        break;
-      }
-    }
-    if (stripped === fileHeading.trim()) {
-      fileIdx = i;
-    }
-  }
-
-  if (fileIdx === -1) {
-    // File heading doesn't exist — add it before section end
-    lines.splice(sectionEnd, 0, '', fileHeading, newItem);
-    return { text: lines.join('\n'), deduped: false };
-  }
-
-  // Find last item under this file heading
-  let insertIdx = fileIdx + 1;
-  for (let i = fileIdx + 1; i < sectionEnd; i++) {
-    const stripped = lines[i].trim();
-    if (stripped.startsWith(fileHeadingPrefix)) break; // next file heading
-    if (/^- \[/.test(stripped)) {
-      insertIdx = i + 1;
-    }
-  }
-
-  lines.splice(insertIdx, 0, newItem);
-  return { text: lines.join('\n'), deduped: false };
-}
-
-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, stageBase) {
-  return transformFeedbackItemWithValidation(text, file, index, 'wont-fix', stageBase, (line) =>
-    line.replace('- [ ]', '- [~]') + ` | wont-fix: ${reason}`
-  );
-}
-
-export function resolveFeedbackItem(text, file, index, resolution, reason, stageBase) {
-  return transformFeedbackItemWithValidation(text, file, index, resolution, stageBase, (line) => {
-    if (resolution === 'approved') {
-      return line + ' | approved';
-    }
-    return line + ` | rejected: ${reason}`;
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Listing
-// ---------------------------------------------------------------------------
-
-export function listFeedback(text, cycle, artefacts, filterFile) {
-  const cycleFiles = new Set();
-  for (const art of artefacts) {
-    if (art.cycle === cycle) {
-      cycleFiles.add(art.file || '');
-    }
-  }
-  const filterByCycle = cycleFiles.size > 0;
-
-  const results = [];
-  let currentFile = null;
-  let fileIndex = 0;
-  let inFeedback = false;
-  let feedbackLevel = 0;
-
-  for (const line of text.split('\n')) {
-    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();
-      fileIndex = 0;
-      continue;
-    }
-
-    if ((!filterByCycle || cycleFiles.has(currentFile)) && /^- \[/.test(stripped)) {
-      if (!filterFile || filterFile === currentFile) {
-        const item = parseFeedbackItem(stripped);
-        results.push({
-          file: currentFile,
-          index: fileIndex,
-          text: item.raw,
-          state: item.state,
-          tags: item.tags,
-          resolved: item.resolved,
-        });
-      }
-      fileIndex++;
-    }
-  }
-
-  return results;
-}
-
-/**
- * Detect feedback items stuck in a deadlock — rejected N or more times.
- * A deadlock occurs when forge-appraise cycles keep rejecting the same item.
- */
-export function detectDeadlocks(feedback, history, threshold = 3) {
-  // Count forge→appraise cycles (each pair = one iteration)
-  const forgeAppraiseCount = history.filter(
-    e => (e.stage || '').split(':')[0] === 'appraise'
-  ).length;
-
-  if (forgeAppraiseCount < threshold) return [];
-
-  // Items that are still rejected after threshold iterations are deadlocked
-  return feedback.filter(f => f.state === 'rejected' || f.state === 'open');
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-  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) {
-        lines[i] = transform(lines[i]);
-        return lines.join('\n');
-      }
-      fileIndex++;
-    }
-  }
-
-  return text;
-}

package/scripts/lib/finalize.js

@@ -1,41 +0,0 @@
-// 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

@@ -1,59 +0,0 @@
-import yaml from 'js-yaml';
-
-/**
- * Load history entries for a cycle, sorted by timestamp ascending.
- */
-export function loadHistory(historyPath, cycle, io) {
-  if (!io.exists(historyPath)) return [];
-  const data = yaml.load(io.readFile(historyPath)) || [];
-  const filtered = data.filter(e => e.cycle === cycle);
-  filtered.sort((a, b) => {
-    const ta = a.timestamp ? new Date(a.timestamp).getTime() : 0;
-    const tb = b.timestamp ? new Date(b.timestamp).getTime() : 0;
-    return ta - tb;
-  });
-  return filtered;
-}
-
-/**
- * Append a history entry with auto-generated ISO timestamp.
- */
-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');
-
-  let existing = [];
-  if (io.exists(historyPath)) {
-    existing = yaml.load(io.readFile(historyPath)) || [];
-  }
-
-  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));
-}
-
-/**
- * Count forge entries for a cycle.
- */
-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/secret.js

@@ -1,23 +0,0 @@
-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/tags.js

@@ -1,108 +0,0 @@
-/**
- * Shared tag validation utilities used by sort.js and validate-tags.js.
- */
-
-import { readFileSync, existsSync, readdirSync } from 'fs';
-import { join } from 'path';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-export const VALID_TAG_RE = /^(#validation|#hitl|#law:[\w-]+)$/;
-
-// ---------------------------------------------------------------------------
-// Law collection
-// ---------------------------------------------------------------------------
-
-export function collectLawIds(foundryDir) {
-  const ids = new Set();
-
-  const lawsDir = join(foundryDir, 'laws');
-  if (existsSync(lawsDir)) {
-    for (const file of readdirSync(lawsDir)) {
-      if (!file.endsWith('.md')) continue;
-      const text = readFileSync(join(lawsDir, file), 'utf-8');
-      for (const id of extractLawHeadings(text)) ids.add(id);
-    }
-  }
-
-  const artefactsDir = join(foundryDir, 'artefacts');
-  if (existsSync(artefactsDir)) {
-    for (const typeDir of readdirSync(artefactsDir)) {
-      const lawsPath = join(artefactsDir, typeDir, 'laws.md');
-      if (!existsSync(lawsPath)) continue;
-      const text = readFileSync(lawsPath, 'utf-8');
-      for (const id of extractLawHeadings(text)) ids.add(id);
-    }
-  }
-
-  return ids;
-}
-
-export function extractLawHeadings(text) {
-  const ids = [];
-  for (const line of text.split('\n')) {
-    const match = line.match(/^## (.+)$/);
-    if (match) ids.push(match[1].trim());
-  }
-  return ids;
-}
-
-// ---------------------------------------------------------------------------
-// Tag extraction
-// ---------------------------------------------------------------------------
-
-/**
- * Extract all hash-tags from a feedback line.
- * Returns an array of strings like ['#validation', '#law:brevity'].
- */
-export function extractAllTags(line) {
-  return (line.match(/#[\w][\w:-]*/g) || []);
-}
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/**
- * Validate all feedback tags in the Feedback section of WORK.md text.
- *
- * Returns an array of error strings. Empty array = all valid.
- */
-export function validateTags(workText, foundryDir) {
-  const lawIds = collectLawIds(foundryDir);
-  const errors = [];
-  let inFeedback = false;
-  let lineNum = 0;
-
-  for (const line of workText.split('\n')) {
-    lineNum++;
-    const stripped = line.trim();
-
-    if (stripped === '# Feedback') { inFeedback = true; continue; }
-    if (inFeedback && stripped.startsWith('# ') && stripped !== '# Feedback') {
-      inFeedback = false; continue;
-    }
-    if (!inFeedback || !(/^- \[/.test(stripped))) continue;
-
-    const tags = extractAllTags(stripped);
-    if (tags.length === 0) {
-      errors.push({ line: lineNum, message: 'Feedback item has no tag', raw: stripped });
-      continue;
-    }
-
-    for (const tag of tags) {
-      if (!VALID_TAG_RE.test(tag)) {
-        errors.push({ line: lineNum, message: `Unknown tag: ${tag}`, raw: stripped });
-      } else if (tag.startsWith('#law:')) {
-        const lawId = tag.slice(5);
-        if (!lawIds.has(lawId)) {
-          errors.push({ line: lineNum, message: `Law not found: ${lawId}`, raw: stripped });
-        }
-      }
-    }
-  }
-
-  return errors;
-}

package/scripts/lib/token.js

@@ -1,26 +0,0 @@
-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 };
-}