@ijfw/memory-server 1.3.0 → 1.4.1

package/src/blackboard.js

@@ -0,0 +1,360 @@
+// Project-local blackboard coordination for IJFW swarm work.
+//
+// Runtime state lives under <project>/.ijfw/blackboard/. It is deliberately
+// small and dependency-free: tasks/claims are atomic JSON, notes are append-only
+// JSONL, and handoff is plain markdown.
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { writeAtomic, readSafe, withLock } from './lib/atomic-io.js';
+
+export const BLACKBOARD_VERSION = 1;
+
+export function blackboardPaths(projectRoot = process.cwd()) {
+  const root = resolve(projectRoot);
+  const dir = join(root, '.ijfw', 'blackboard');
+  return {
+    root,
+    dir,
+    lock: join(dir, '.lock'),
+    tasks: join(dir, 'tasks.json'),
+    claims: join(dir, 'claims.json'),
+    findings: join(dir, 'findings.jsonl'),
+    decisions: join(dir, 'decisions.jsonl'),
+    blockers: join(dir, 'blockers.jsonl'),
+    notes: join(dir, 'notes.jsonl'),
+    events: join(dir, 'events.jsonl'),
+    handoff: join(dir, 'handoff.md'),
+  };
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDir(paths) {
+  if (!existsSync(paths.dir)) mkdirSync(paths.dir, { recursive: true, mode: 0o700 });
+}
+
+function defaultTasks() {
+  return { version: BLACKBOARD_VERSION, tasks: [], updated_at: nowIso() };
+}
+
+function defaultClaims() {
+  return { version: BLACKBOARD_VERSION, claims: [], updated_at: nowIso() };
+}
+
+function validTasks(data) {
+  return data && data.version === BLACKBOARD_VERSION && Array.isArray(data.tasks);
+}
+
+function validClaims(data) {
+  return data && data.version === BLACKBOARD_VERSION && Array.isArray(data.claims);
+}
+
+function readJson(path, fallback, validator) {
+  const res = readSafe(path, validator);
+  if (res.ok) return { ok: true, data: res.data };
+  return { ok: false, data: fallback(), error: res.error, message: res.message };
+}
+
+function writeJson(path, data) {
+  data.updated_at = nowIso();
+  return writeAtomic(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+}
+
+function readJsonl(path, limit = 5) {
+  try {
+    if (!existsSync(path)) return [];
+    const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    return lines.slice(-limit).map((line) => {
+      try { return JSON.parse(line); } catch { return { malformed: true, raw: line }; }
+    });
+  } catch {
+    return [];
+  }
+}
+
+function appendJsonlUnlocked(path, entry) {
+  appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', mode: 0o600 });
+  return entry;
+}
+
+function appendJsonl(paths, path, entry) {
+  return withLock(paths.lock, () => appendJsonlUnlocked(path, entry)).result ?? null;
+}
+
+function blackboardEventEntry(input) {
+  return {
+    ts: nowIso(),
+    type: String(input.type || 'event'),
+    actor: input.actor || input.owner || 'ijfw',
+    task_id: input.task_id || null,
+    artifact_ids: Array.isArray(input.artifact_ids) ? input.artifact_ids : [],
+    message: input.message || null,
+    data: input.data || {},
+  };
+}
+
+export function initBlackboard(projectRoot = process.cwd()) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  if (!existsSync(paths.tasks)) writeJson(paths.tasks, defaultTasks());
+  if (!existsSync(paths.claims)) writeJson(paths.claims, defaultClaims());
+  for (const p of [paths.findings, paths.decisions, paths.blockers, paths.notes, paths.events]) {
+    if (!existsSync(p)) writeFileSync(p, '', { encoding: 'utf8', mode: 0o600 });
+  }
+  if (!existsSync(paths.handoff)) {
+    writeFileSync(paths.handoff, '# IJFW Blackboard Handoff\n\nNo active handoff.\n', { encoding: 'utf8', mode: 0o600 });
+  }
+  return { ok: true, dir: paths.dir };
+}
+
+export function readBlackboard(projectRoot = process.cwd()) {
+  const paths = blackboardPaths(projectRoot);
+  const tasks = readJson(paths.tasks, defaultTasks, validTasks);
+  const claims = readJson(paths.claims, defaultClaims, validClaims);
+  return {
+    paths,
+    tasks,
+    claims,
+    recent: {
+      findings: readJsonl(paths.findings),
+      decisions: readJsonl(paths.decisions),
+      blockers: readJsonl(paths.blockers),
+      notes: readJsonl(paths.notes),
+      events: readJsonl(paths.events),
+    },
+  };
+}
+
+export function appendBlackboardEvent(projectRoot, input) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  const entry = blackboardEventEntry(input);
+  const written = appendJsonl(paths, paths.events, entry);
+  if (!written) return { ok: false, error: 'locked' };
+  return { ok: true, entry: written };
+}
+
+export function writeBlackboardTasks(projectRoot, tasks, options = {}) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.tasks, defaultTasks, validTasks).data;
+    const next = {
+      version: BLACKBOARD_VERSION,
+      tasks: options.replace ? [] : current.tasks.slice(),
+      updated_at: nowIso(),
+    };
+    const incoming = tasks.map((task) => ({
+      ...task,
+      updated_at: task.updated_at || nowIso(),
+    }));
+    const incomingIds = new Set(incoming.map((task) => task.id));
+    next.tasks = next.tasks.filter((task) => !incomingIds.has(task.id));
+    next.tasks.push(...incoming);
+    writeJson(paths.tasks, next);
+    return { ok: true, written: incoming.length, total: next.tasks.length };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+export function listBlackboardTasks(projectRoot = process.cwd()) {
+  const state = readBlackboard(projectRoot);
+  const tasks = state.tasks.data.tasks || [];
+  return { ok: state.tasks.ok, tasks, error: state.tasks.error };
+}
+
+export function updateBlackboardTask(projectRoot, taskId, patch) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.tasks, defaultTasks, validTasks).data;
+    const index = current.tasks.findIndex((task) => task.id === taskId);
+    if (index === -1) return { ok: false, error: 'task-not-found' };
+    const before = current.tasks[index];
+    const next = {
+      ...before,
+      ...patch,
+      updated_at: nowIso(),
+    };
+    current.tasks[index] = next;
+    writeJson(paths.tasks, current);
+    return { ok: true, task: next, previous: before };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+function activeClaims(claimsData) {
+  return claimsData.claims.filter((claim) => claim.status === 'active');
+}
+
+function claimArtifactId(claim) {
+  return claim.artifact_id || claim.artifact;
+}
+
+function claimAgent(claim) {
+  return claim.agent || claim.owner;
+}
+
+function normalizePaths(paths) {
+  if (!paths) return [];
+  if (Array.isArray(paths)) return paths.map(String).filter(Boolean);
+  return String(paths).split(',').map((p) => p.trim()).filter(Boolean);
+}
+
+function commonPrefixBeforeGlob(pattern) {
+  const idx = pattern.search(/[*?[\]{}]/);
+  return idx === -1 ? pattern : pattern.slice(0, idx);
+}
+
+function pathsOverlap(a, b) {
+  if (!a.length || !b.length) return false;
+  for (const left of a) {
+    for (const right of b) {
+      if (left === right) return true;
+      const lp = commonPrefixBeforeGlob(left);
+      const rp = commonPrefixBeforeGlob(right);
+      if (lp && right.startsWith(lp)) return true;
+      if (rp && left.startsWith(rp)) return true;
+    }
+  }
+  return false;
+}
+
+function claimConflicts(existing, next) {
+  return activeClaims(existing).filter((claim) => {
+    if (claimAgent(claim) === next.agent) return false;
+    if (claimArtifactId(claim) === next.artifact_id) return true;
+    return pathsOverlap(claim.paths || [], next.paths || []);
+  });
+}
+
+export function claimArtifact(projectRoot, input) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.claims, defaultClaims, validClaims).data;
+    const artifactId = String(input.artifact_id || input.artifact || '').trim();
+    const agent = String(input.agent || input.owner || '').trim();
+    const next = {
+      id: input.id || `${artifactId}:${agent}`,
+      artifact_id: artifactId,
+      agent,
+      paths: normalizePaths(input.paths),
+      status: 'active',
+      claimed_at: nowIso(),
+      note: input.note ? String(input.note) : undefined,
+    };
+    if (!next.artifact_id) return { ok: false, error: 'artifact-required' };
+    if (!next.agent) return { ok: false, error: 'owner-required' };
+
+    const conflicts = claimConflicts(current, next);
+    if (conflicts.length) return { ok: false, error: 'conflict', conflicts };
+
+    current.claims = current.claims.filter((claim) => !(claimArtifactId(claim) === next.artifact_id && claimAgent(claim) === next.agent));
+    current.claims.push(next);
+    writeJson(paths.claims, current);
+    appendJsonlUnlocked(paths.events, blackboardEventEntry({
+      type: 'claim.acquired',
+      actor: next.agent,
+      artifact_ids: [next.artifact_id],
+      message: `Claimed ${next.artifact_id}`,
+      data: { paths: next.paths },
+    }));
+    return { ok: true, claim: next };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+export function releaseClaim(projectRoot, input) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.claims, defaultClaims, validClaims).data;
+    const artifactId = String(input.artifact_id || input.artifact || '').trim();
+    const agent = input.agent || input.owner ? String(input.agent || input.owner).trim() : null;
+    if (!artifactId) return { ok: false, error: 'artifact-required' };
+
+    let released = 0;
+    current.claims = current.claims.map((claim) => {
+      if (claimArtifactId(claim) !== artifactId) return claim;
+      if (agent && claimAgent(claim) !== agent) return claim;
+      if (claim.status !== 'active') return claim;
+      released += 1;
+      return { ...claim, status: 'released', released_at: nowIso() };
+    });
+    writeJson(paths.claims, current);
+    if (released > 0) {
+      appendJsonlUnlocked(paths.events, blackboardEventEntry({
+        type: 'claim.released',
+        actor: agent || 'ijfw',
+        artifact_ids: [artifactId],
+        message: `Released ${released} claim(s) for ${artifactId}`,
+      }));
+    }
+    return { ok: true, released };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+export function addBlackboardNote(projectRoot, input) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  const kind = input.kind || 'note';
+  const targets = {
+    note: paths.notes,
+    finding: paths.findings,
+    decision: paths.decisions,
+    blocker: paths.blockers,
+  };
+  const target = targets[kind];
+  if (!target) return { ok: false, error: 'unknown-kind' };
+  const entry = {
+    kind,
+    author: input.author || input.owner || 'unknown',
+    artifact: input.artifact || null,
+    message: String(input.message || '').trim(),
+    ts: nowIso(),
+  };
+  if (!entry.message) return { ok: false, error: 'message-required' };
+  const written = appendJsonl(paths, target, entry);
+  if (!written) return { ok: false, error: 'locked' };
+  return { ok: true, entry: written };
+}
+
+export function writeHandoff(projectRoot, body) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  const text = String(body || '').trim();
+  if (!text) return { ok: false, error: 'handoff-required' };
+  writeAtomic(paths.handoff, `${text}\n`, { mode: 0o600 });
+  return { ok: true, path: paths.handoff };
+}
+
+export function blackboardStatus(projectRoot = process.cwd()) {
+  const paths = blackboardPaths(projectRoot);
+  const state = readBlackboard(projectRoot);
+  const claims = state.claims.data.claims || [];
+  const tasks = state.tasks.data.tasks || [];
+  return {
+    ok: true,
+    dir: paths.dir,
+    initialized: existsSync(paths.dir),
+    tasks: {
+      total: tasks.length,
+      open: tasks.filter((task) => !['done', 'cancelled'].includes(task.status)).length,
+    },
+    claims: {
+      total: claims.length,
+      active: activeClaims({ claims }).length,
+      active_items: activeClaims({ claims }).map((claim) => ({
+        artifact_id: claimArtifactId(claim),
+        agent: claimAgent(claim),
+        paths: claim.paths || [],
+      })),
+    },
+    recent: state.recent,
+    health: {
+      tasks: state.tasks.ok ? 'ok' : state.tasks.error,
+      claims: state.claims.ok ? 'ok' : state.claims.error,
+    },
+  };
+}

package/src/cli-run.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * cli-run.js
+ *
+ * IJFW v1.4.0 / W6/S5 -- terminal shim for the colon-syntax dispatch surface.
+ *
+ * Why this exists:
+ *   The session-start hook needs a way to fire `domain-manifest:load` (and
+ *   `extension:deploy-lazy` from W6/S12) from bash without depending on the
+ *   long-lived MCP server. A 30-line shim that imports dispatchRun directly
+ *   keeps the dependency chain trivial: bash -> node -> dispatch/*.js.
+ *
+ * Usage:
+ *   node cli-run.js <namespace>:<command> [--project-root <dir>] [args...]
+ *
+ * Examples:
+ *   node cli-run.js domain-manifest:load --project-root /path/to/proj
+ *   node cli-run.js extension:deploy-lazy --project-root /path/to/proj
+ *
+ * Contract:
+ *   - Always exits 0 on a successful dispatch (even when the dispatched
+ *     command reports ok:false -- that's a *result*, not a shim failure).
+ *   - Exits 2 on argv-shape errors (missing colon expression).
+ *   - Exits 3 on a thrown error inside the dispatcher.
+ *   - Prints the JSON-stringified result to stdout. stderr stays empty on
+ *     the happy path so the session-start log isn't polluted.
+ *
+ * Discipline:
+ *   - Built-in Node only. No new deps.
+ *   - ESM. ASCII strings only.
+ *   - Detached fire-and-forget safe: the caller pipes stdin/stdout/stderr
+ *     to /dev/null and the shim never needs an interactive TTY.
+ */
+
+import { parseColonCommand, dispatchRun } from './dispatch/colon-syntax.js';
+
+function parseFlags(argv) {
+  // argv layout: [colonExpr, ...rest] -- rest may interleave flags and
+  // positional args. We only consume --project-root <value> here; anything
+  // else is passed through as part of the colon-expr args via space-join.
+  const out = { projectRoot: null, rest: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok === '--project-root') {
+      out.projectRoot = argv[i + 1] || null;
+      i += 1;
+      continue;
+    }
+    if (typeof tok === 'string' && tok.startsWith('--project-root=')) {
+      out.projectRoot = tok.slice('--project-root='.length);
+      continue;
+    }
+    out.rest.push(tok);
+  }
+  return out;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0) {
+    process.stderr.write('cli-run: usage: node cli-run.js <namespace>:<command> [--project-root <dir>] [args...]\n');
+    process.exit(2);
+  }
+  const colonExpr = argv[0];
+  const tail = argv.slice(1);
+  const { projectRoot, rest } = parseFlags(tail);
+
+  // Glue any positional args back onto the colon expression so the
+  // dispatcher's existing arg-parsing handles them. e.g.
+  //   cli-run domain-manifest:load extra args  ->  parseColonCommand sees
+  //   "domain-manifest:load extra args"
+  const expr = rest.length ? `${colonExpr} ${rest.join(' ')}` : colonExpr;
+  const parsed = parseColonCommand(expr);
+  if (!parsed) {
+    process.stderr.write(`cli-run: could not parse "${colonExpr}" as <namespace>:<command>\n`);
+    process.exit(2);
+  }
+
+  try {
+    const result = await dispatchRun(parsed, {
+      projectRoot: projectRoot || process.env.IJFW_PROJECT_DIR || process.cwd(),
+    });
+    process.stdout.write(JSON.stringify(result == null ? { ok: false, error: 'dispatch returned null (unknown namespace)' } : result) + '\n');
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`cli-run: dispatch threw: ${err && err.message ? err.message : String(err)}\n`);
+    process.exit(3);
+  }
+}
+
+main();

package/src/codex-agents.js

@@ -0,0 +1,177 @@
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { writeAtomic } from './lib/atomic-io.js';
+
+export function renderCodexAgentToml(role, bundle = {}) {
+  assertRole(role);
+  const charter = bundle.charter || bundle;
+  const workflow = bundle.workflow || null;
+  const archetypes = list(charter.project_archetypes).length ? list(charter.project_archetypes) : ['mixed'];
+  const agentName = codexAgentName(role.name);
+  const description = renderDescription(role, archetypes);
+  const instructions = renderDeveloperInstructions(role, { archetypes, workflow });
+  const lines = [
+    `name = ${tomlString(agentName)}`,
+    `description = ${tomlString(description)}`,
+  ];
+
+  const codexConfig = role.codex && typeof role.codex === 'object' ? role.codex : {};
+  if (typeof codexConfig.model === 'string' && codexConfig.model.trim()) {
+    lines.push(`model = ${tomlString(codexConfig.model.trim())}`);
+  }
+  if (typeof codexConfig.model_reasoning_effort === 'string' && codexConfig.model_reasoning_effort.trim()) {
+    lines.push(`model_reasoning_effort = ${tomlString(codexConfig.model_reasoning_effort.trim())}`);
+  }
+
+  lines.push(`developer_instructions = ${tomlMultiline(instructions)}`);
+  return `${lines.join('\n')}\n`;
+}
+
+export function syncCodexAgents(projectRoot = process.cwd(), options = {}) {
+  const root = resolve(projectRoot);
+  const bundle = options.bundle || readTeamBundle(root);
+  if (!bundle?.charter?.roles?.length) {
+    return { ok: false, error: 'missing-team-charter', agentsDir: join(root, '.codex', 'agents'), agentFiles: [] };
+  }
+
+  const agentsDir = join(root, '.codex', 'agents');
+  mkdirSync(agentsDir, { recursive: true, mode: 0o700 });
+
+  const agentFiles = [];
+  for (const role of bundle.charter.roles) {
+    const agentPath = join(agentsDir, `${codexAgentFilename(role.name)}.toml`);
+    writeAtomic(agentPath, renderCodexAgentToml(role, bundle), { mode: 0o600 });
+    agentFiles.push(agentPath);
+  }
+
+  return {
+    ok: true,
+    agentsDir,
+    agentFiles,
+    count: agentFiles.length,
+  };
+}
+
+function readTeamBundle(root) {
+  const charterPath = join(root, '.ijfw', 'team', 'charter.json');
+  if (!existsSync(charterPath)) return null;
+  const workflowPath = join(root, '.ijfw', 'team', 'workflow.json');
+  return {
+    charter: JSON.parse(readFileSync(charterPath, 'utf8')),
+    workflow: existsSync(workflowPath) ? JSON.parse(readFileSync(workflowPath, 'utf8')) : null,
+  };
+}
+
+function renderDescription(role, archetypes) {
+  const owns = list(role.owns).map((item) => item.artifact_type).filter(Boolean);
+  const owned = owns.length ? owns.join(', ') : 'assigned artifacts';
+  return `${role.name} for ${archetypes.join(', ')} projects; owns ${owned}.`;
+}
+
+function renderDeveloperInstructions(role, context) {
+  const owns = renderArtifactRefs(role.owns, '- No primary ownership declared.');
+  const reviews = renderReviews(role.reviews);
+  const phaseScope = list(role.phase_scope).join(', ') || 'project workflow';
+  const archetypes = context.archetypes.join(', ');
+  const artifacts = renderWorkflowArtifacts(role.name, context.workflow);
+  const conflicts = list(role.coordination?.conflicts_with).join(', ') || 'none declared';
+  const claimRequired = role.coordination?.claim_required ? 'yes' : 'no';
+  const parallelSafe = role.coordination?.parallel_safe ? 'yes' : 'no';
+  const sections = list(role.handoff?.required_sections).join(', ') || 'changed_artifacts, verification, risks';
+
+  return [
+    `You are the ${role.name} Codex custom agent for this IJFW Team Assembly.`,
+    '',
+    `Role type: ${role.role_type}`,
+    `Project archetypes: ${archetypes}`,
+    `Phase scope: ${phaseScope}`,
+    '',
+    'Work project-agnostically. Treat artifacts as whatever this project uses: source files, documents, designs, datasets, plans, research notes, workflows, diagrams, or other durable project outputs.',
+    '',
+    'Owns:',
+    owns,
+    '',
+    'Reviews:',
+    reviews,
+    '',
+    'Workflow artifacts assigned to this role:',
+    artifacts,
+    '',
+    'Blackboard coordination:',
+    `- Claim required: ${claimRequired}`,
+    `- Parallel safe: ${parallelSafe}`,
+    `- Conflicts with: ${conflicts}`,
+    '- Before editing or producing durable output, coordinate through the IJFW blackboard when swarm execution is active.',
+    '- Start assigned swarm work with: ijfw swarm start <task-id>',
+    '- Complete finished swarm work with: ijfw swarm complete <task-id>',
+    '- Report blocked swarm work with: ijfw swarm block <task-id> --message <why>',
+    '- Record findings, decisions, and blockers in .ijfw/blackboard/ through IJFW commands when relevant.',
+    '',
+    'Safety:',
+    '- You are not alone in this repo. Never revert user changes or another agent\'s changes unless the parent session explicitly asks for that exact revert.',
+    '- Keep edits scoped to your claimed artifacts and paths. If ownership is unclear, stop and report the ambiguity.',
+    '- Preserve existing project conventions and validate the behavior or artifact quality you changed.',
+    '',
+    'Handoff:',
+    `- Format: ${role.handoff?.format || 'markdown'}`,
+    `- Required sections: ${sections}`,
+  ].join('\n');
+}
+
+function renderArtifactRefs(refs, fallback) {
+  const lines = list(refs).map((item) => {
+    const targets = list(item.paths).concat(list(item.refs));
+    const targetText = targets.length ? targets.join(', ') : 'project-defined locations';
+    return `- ${item.artifact_type || 'artifact'}: ${targetText}`;
+  });
+  return lines.length ? lines.join('\n') : fallback;
+}
+
+function renderReviews(refs) {
+  const lines = list(refs).map((item) => {
+    const criteria = list(item.criteria).join(', ') || 'quality, correctness, fit';
+    return `- ${item.artifact_type || 'artifact'}: ${criteria}`;
+  });
+  return lines.length ? lines.join('\n') : '- No review responsibility declared.';
+}
+
+function renderWorkflowArtifacts(roleName, workflow) {
+  const artifacts = list(workflow?.artifacts).filter((artifact) => {
+    return artifact.owner === roleName || list(artifact.reviewers).includes(roleName);
+  });
+  if (!artifacts.length) return '- No workflow artifact mapping found; follow the role owns/reviews contract.';
+  return artifacts.map((artifact) => {
+    const relationship = artifact.owner === roleName ? 'owns' : 'reviews';
+    const targets = list(artifact.paths).concat(list(artifact.refs));
+    const targetText = targets.length ? ` (${targets.join(', ')})` : '';
+    return `- ${artifact.id}: ${relationship} ${artifact.type}${targetText}`;
+  }).join('\n');
+}
+
+function assertRole(role) {
+  if (!role || typeof role !== 'object') throw new TypeError('role must be an object');
+  if (!role.name || typeof role.name !== 'string') throw new TypeError('role.name is required');
+  if (!role.role_type || typeof role.role_type !== 'string') throw new TypeError('role.role_type is required');
+}
+
+function codexAgentName(value) {
+  const name = String(value || '').trim().toLowerCase().replace(/[^a-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+  return name || 'ijfw_agent';
+}
+
+function codexAgentFilename(value) {
+  const name = String(value || '').trim().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return name || 'ijfw-agent';
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function tomlMultiline(value) {
+  return `"""\n${String(value).replace(/"""/g, '\\"\\"\\"')}\n"""`;
+}
+
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}

package/src/compute/extract.js

@@ -101,6 +101,7 @@ const DOTFILE_RE = new RegExp(
 // Windows path: drive letter + (\\ or \) + chain. The fixture body
 // contains DOUBLE backslashes; expected name uses SINGLE backslashes.
 // Match doubled-backslash form, then normalize to single backslash on emit.
+// eslint-disable-next-line security/detect-unsafe-regex -- extractor input is capped by caller; character classes are bounded to non-whitespace path segments.
 const WINDOWS_PATH_RE = /(?<![\w])([A-Za-z]:(?:\\\\[^\s\\]+)+\.[a-zA-Z][a-zA-Z0-9]{0,8})(?![\w])/g;
 
 // Bare basename with extension (no path). Conservative: requires the
@@ -141,6 +142,7 @@ const DUNDER_BARE_RE = /\b(__[a-z][a-z0-9_]*)\b/g;
 const REACT_HOOK_RE = /\b(use[A-Z][A-Za-z0-9]*)\b/g;
 
 // --- identifier regex --------------------------------------------------
+// eslint-disable-next-line security/detect-unsafe-regex -- token extractor regex is linear over capped text and uses bounded identifier classes.
 const UPPER_SNAKE_RE = /\b([A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+)\b/g;
 const PASCAL_BARE_RE = /\b([A-Z][a-z][A-Za-z0-9]*|I[A-Z][a-z][A-Za-z0-9]*)\b/g;
 
@@ -171,6 +173,7 @@ const HTTP_EXPLICIT_RE = /\bHTTP[_ ]?([1-5]\d{2})\b/g;
 const EXCEPTION_RE = /\b([A-Z][a-z][A-Za-z0-9]*(?:Exception|Error))\b/g;
 
 // --- decision regex ----------------------------------------------------
+// eslint-disable-next-line security/detect-unsafe-regex -- token extractor regex is linear over capped text and uses bounded slug segments.
 const D_PREFIX_RE = /\b(d-[a-z][a-z0-9]{3,}(?:-[a-z0-9]+)+)\b/g;
 const HASH_DECISION_RE = /#decision:([a-z][a-z0-9-]+)/g;
 const ADR_NUMERIC_RE = /\b(ADR-\d{4})\b/g;

package/src/compute/fts5.js

@@ -15,7 +15,7 @@
 // Integrity discipline:
 //   - openDb()    -- enforces schema version; refuses downgrade.
 //   - safeWrite() -- runs `redactSecrets()` over `body` and `topic` BEFORE
-//                    inserting (D-PILLAR-SPEC §12 ingest scrub gate), then
+//                    inserting (D-PILLAR-SPEC section 12 ingest scrub gate), then
 //                    inserts inside a transaction and runs PRAGMA quick_check
 //                    after each insert; throws IntegrityError on anything
 //                    other than 'ok'. The scrub default is on; setting
@@ -25,7 +25,7 @@
 //                    by bm25 rank.
 //   - closeDb()   -- clean close; suppresses double-close errors.
 //
-// Security model (D-PILLAR-SPEC §12, real fix-wave C3):
+// Security model (D-PILLAR-SPEC section 12, real fix-wave C3):
 //   Secrets are scrubbed at the observation-ingest boundary. By the time a
 //   row reaches the FTS index, the entity extractor, or the kg layer, all
 //   `redactSecrets`-recognised tokens have been replaced with
@@ -40,7 +40,7 @@ import { runMigrations, highestKnownVersion, SchemaVersionError } from './migrat
 import { autoIndexGraphFromBody } from './graph-auto-index.js';
 import { redactSecrets } from '../redactor.js';
 
-// D-PILLAR-SPEC §12 ingest scrub gate. Default-on; the only escape hatch
+// D-PILLAR-SPEC section 12 ingest scrub gate. Default-on; the only escape hatch
 // is the IJFW_INGEST_SCRUB=0 env var, which exists for local debugging
 // (e.g. asserting raw body shape in a fixture) and is NOT a shipping
 // posture. Read on every safeWrite call so test harnesses can flip it
@@ -271,7 +271,7 @@ export function safeWrite(db, table, row) {
     }
   }
 
-  // D-PILLAR-SPEC §12 ingest scrub gate. Replace `body` and `topic` with
+  // D-PILLAR-SPEC section 12 ingest scrub gate. Replace `body` and `topic` with
   // their redacted forms BEFORE the INSERT runs, so the FTS index, the
   // entity extractor (D2), and any downstream reader only ever see the
   // scrubbed text. This applies to every `safeWrite` regardless of table