@ijfw/memory-server 1.5.0 → 1.5.1

package/src/team/generator.js

@@ -19,8 +19,20 @@ import {
 } from './schemas.js';
 
 const FIXTURE_DIR = resolve(fileURLToPath(new URL('../../fixtures/team/', import.meta.url)));
+// W1.5.B (ADR W1.5 Option C "merge"): domain-templates is the canonical
+// agent-id spec; fixtures remain canonical for the executable team bundle.
+// `loadTeamTemplate` cross-validates the two sources at load time so any
+// future drift surfaces as a load-time signal rather than a silent
+// runtime mismatch. See `.planning/1.5.1/decisions/W1.5-canonical-source.md`.
+const DOMAIN_TEMPLATES_DIR = resolve(fileURLToPath(new URL('./domain-templates/', import.meta.url)));
 const SUPPORTED_ARCHETYPES = new Set(['software', 'design', 'content', 'book', 'research', 'business', 'mixed']);
 
+// W1.5.B: one-time warning suppression per archetype so drift between
+// fixtures and domain-templates emits a single, clearly-attributed
+// warning rather than spamming stderr on every loadTeamTemplate call
+// (tests + the CLI may both call into the loader inside the same process).
+const _crossValidationWarned = new Set();
+
 // T24 / G7-core: the four universal software-core agents. Any software-
 // domain roster MUST include all four. The ids resolve to static markdown
 // files under `claude/agents/<id>.md`; the generator does not synthesise
@@ -273,9 +285,121 @@ export function loadTeamTemplate(archetype) {
   const path = join(FIXTURE_DIR, `${normalized}.json`);
   const bundle = JSON.parse(readFileSync(path, 'utf8'));
   assertValidTeamBundle(bundle);
+
+  // W1.5.B cross-validation gate. Read the matching T26 domain-template
+  // (if any) and cross-check that the fixture's `charter.roles[].name`
+  // set agrees with the template's `agent_ids`. Two sources of truth
+  // that SHOULD agree by construction (ADR W1.5 Option C "merge"); this
+  // gate makes future drift self-detect at load time rather than as a
+  // silent runtime miss far from the cause.
+  //
+  // Behaviour:
+  //   - template file missing
+  //       → e.g. `mixed` (deliberately template-free per ADR W1.5).
+  //         Fixture is the sole source of truth; gate is a no-op.
+  //   - template present but `agent_ids` empty
+  //       → fall back to fixture as ground truth; emit a one-time
+  //         warning so the unpopulated template is visible. W1.5.C
+  //         populated research + business; if any other archetype ever
+  //         lands empty in future, operators see it immediately.
+  //   - template populated AND agrees with fixture role names
+  //         (every fixture role name appears in template `agent_ids`)
+  //       → silent pass; the canonical contract holds.
+  //   - template populated AND disagrees
+  //       → emit a one-time warning naming the drifting role(s) and the
+  //         template ids they failed to match. Fail-loud at load time
+  //         via `process.emitWarning` so CI logs and operators see the
+  //         drift, but DON'T throw during the v1.5.1 transitional
+  //         window where W1.5.E (fixture rename) and W1.5.B (this gate)
+  //         ship in separate commits. Once W1.5.E lands and shipped
+  //         fixtures are realigned, this warning never fires in the
+  //         normal codepath; downstream may graduate the warning to a
+  //         thrown error once the steady state is confirmed.
+  //
+  // The contract for callers: a non-throwing return ALWAYS means the
+  // fixture bundle is structurally valid (assertValidTeamBundle above);
+  // drift between fixture role names and the domain-template agent_ids
+  // surfaces as a one-time `IjfwTeamFixtureDrift` warning on stderr.
+  crossValidateAgainstDomainTemplate(normalized, bundle);
+
   return structuredClone(bundle);
 }
 
+// W1.5.B: read the T26 domain-template for an archetype (if any) and
+// compare it against the fixture bundle's role names. See
+// loadTeamTemplate above for the contract and ADR W1.5 for the rationale.
+function crossValidateAgainstDomainTemplate(archetype, bundle) {
+  const templatePath = join(DOMAIN_TEMPLATES_DIR, `${archetype}.json`);
+  if (!existsSync(templatePath)) {
+    // No T26 template for this archetype (e.g. `mixed` — deliberately
+    // template-free per ADR W1.5). Fixture is the sole source of truth.
+    return;
+  }
+
+  let template;
+  try {
+    template = JSON.parse(readFileSync(templatePath, 'utf8'));
+  } catch (err) {
+    // Unparseable template should not silently bypass the gate, but a
+    // parse error in the template is a separate failure mode from
+    // drift; emit a warning so the broken file is visible without
+    // breaking the generator for users whose fixture is structurally fine.
+    warnOnce(
+      `team-generator: domain-template "${archetype}.json" is unreadable (${err.message}); ` +
+        'falling back to fixture as ground truth.',
+      `parse:${archetype}`,
+    );
+    return;
+  }
+
+  const templateIds = Array.isArray(template.agent_ids) ? template.agent_ids : [];
+  if (templateIds.length === 0) {
+    // ADR W1.5 step 5: T26 empty. Fall back to fixture as ground truth
+    // and emit a one-time warning so the gap is visible to operators.
+    warnOnce(
+      `team-generator: domain-template "${archetype}" has empty agent_ids — ` +
+        'falling back to fixture as ground truth.',
+      `empty:${archetype}`,
+    );
+    return;
+  }
+
+  const fixtureRoleNames = (bundle.charter && Array.isArray(bundle.charter.roles))
+    ? bundle.charter.roles.map((role) => role && role.name).filter(Boolean)
+    : [];
+
+  // The contract (ADR W1.5 Option C): every shipped-fixture role.name
+  // MUST appear in the template's agent_ids set. Drift is a load-time
+  // observability signal — emitted as a one-time warning so CI/operators
+  // see it, but NOT thrown during the v1.5.1 transitional window where
+  // W1.5.E (fixture rename) and W1.5.B (this gate) ship in separate
+  // commits. Steady state post-W1.5.E: this warning never fires; the
+  // gate becomes effectively-throw because mismatch can no longer exist.
+  const templateSet = new Set(templateIds);
+  const missing = fixtureRoleNames.filter((name) => !templateSet.has(name));
+  if (missing.length === 0) return;
+
+  warnOnce(
+    `team-generator: fixtures/team/${archetype}.json drifted from ` +
+      `domain-templates/${archetype}.json — role name(s) ${missing.map((m) => `"${m}"`).join(', ')} ` +
+      `not present in template agent_ids [${templateIds.join(', ')}]. ` +
+      'See ADR .planning/1.5.1/decisions/W1.5-canonical-source.md (Option C "merge"): ' +
+      'fixture roles MUST be a subset of the domain-template agent_ids. ' +
+      'W1.5.E (fixture rename) will close any remaining drift; until then ' +
+      'the fixture is treated as ground truth for the executable team bundle.',
+    `drift:${archetype}`,
+  );
+}
+
+function warnOnce(message, key) {
+  if (_crossValidationWarned.has(key)) return;
+  _crossValidationWarned.add(key);
+  // process.emitWarning is the Node-canonical channel for non-fatal
+  // load-time signals — visible to CI logs, suppressible via
+  // --no-warnings, and includes a stack so the source is traceable.
+  process.emitWarning(message, { type: 'IjfwTeamFixtureDrift', code: 'IJFW_W1_5_B_DRIFT' });
+}
+
 export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
   const root = resolve(projectRoot);
   // F-FUN-1: `options.brief` flows through to detectTeamArchetype so a
@@ -306,10 +430,12 @@ export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
   writeAtomic(workflowPath, `${JSON.stringify(bundle.workflow, null, 2)}\n`, { mode: 0o600 });
 
   const agentFiles = [];
+  const writtenAgentNames = new Set();
   for (const role of bundle.charter.roles) {
     const agentPath = join(agentsDir, `${role.name}.md`);
     writeAtomic(agentPath, renderAgent(role, bundle), { mode: 0o600 });
     agentFiles.push(agentPath);
+    writtenAgentNames.add(role.name);
   }
   const codexAgents = syncCodexAgents(root, { bundle });
 
@@ -328,6 +454,30 @@ export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
   const domainSpecialistAgentIds = resolveDomainSpecialistAgentIds(archetype);
   const rosterAgentIds = resolveRosterForDomain(archetype);
 
+  // W1.5.B: wire DOMAIN_SPECIALIST_AGENT_IDS through to file creation.
+  // Previously the canonical specialist ids were surfaced in the return
+  // value (`domainSpecialistAgentIds`, `rosterAgentIds`) but no matching
+  // `.md` files were written into `.ijfw/agents/` — so a swarm
+  // dispatcher resolving "the book domain specialists" by id got a list
+  // pointing at non-existent local files. This loop closes that gap by
+  // emitting a stub agent .md for every canonical specialist id that
+  // the fixture role-write loop above did NOT already cover. When
+  // fixture role names already match the canonical ids (the steady
+  // state post-W1.5.E), this loop is a no-op because `writtenAgentNames`
+  // already contains them.
+  //
+  // The stub references the canonical `claude/agents/<id>.md` so a
+  // swarm dispatcher resolving by id still gets a discoverable local
+  // entry; the installer is responsible for materialising the full
+  // agent spec.
+  for (const specialistId of domainSpecialistAgentIds) {
+    if (writtenAgentNames.has(specialistId)) continue;
+    const agentPath = join(agentsDir, `${specialistId}.md`);
+    writeAtomic(agentPath, renderSpecialistStub(specialistId, archetype, bundle), { mode: 0o600 });
+    agentFiles.push(agentPath);
+    writtenAgentNames.add(specialistId);
+  }
+
   return {
     ok: true,
     archetype,
@@ -383,6 +533,18 @@ function normalizeArchetype(value) {
   return 'mixed';
 }
 
+// W1.5.B: stub renderer for canonical domain-specialist ids that the
+// shipped fixture doesn't yet name as a `charter.roles[].name`. Keeps
+// the `.ijfw/agents/<id>.md` directory in agreement with
+// `domainSpecialistAgentIds` so downstream swarm dispatchers resolving
+// by id always find a local file. The stub is intentionally minimal —
+// the full agent spec lives in `claude/agents/<id>.md` and is deployed
+// by the installer; this is a discovery breadcrumb, not a duplicated spec.
+function renderSpecialistStub(specialistId, archetype, bundle) {
+  const archetypes = bundle.charter.project_archetypes.join(', ');
+  return `---\nname: ${specialistId}\nmodel: sonnet\neffort: medium\ndescription: ${specialistId} — canonical ${archetype} domain specialist (T26 domain-template).\nallowed-tools: Read, Write, Edit, Bash\n---\n\n# ${specialistId}\n\nCanonical domain specialist for ${archetypes} projects.\n\nFull agent specification: claude/agents/${specialistId}.md (deployed by the IJFW installer).\n\nThis stub exists so swarm dispatchers resolving by id find a local entry; the canonical spec is the source of truth.\n\nRecord claims, findings, blockers, and decisions in .ijfw/blackboard/ when swarm execution is active.\n`;
+}
+
 function renderAgent(role, bundle) {
   const owned = role.owns.map((item) => `- ${item.artifact_type}: ${(item.paths || item.refs || []).join(', ')}`).join('\n');
   const reviews = role.reviews.map((item) => `- ${item.artifact_type}: ${item.criteria.join(', ')}`).join('\n') || '- None';

package/src/update-apply.js

@@ -7,7 +7,7 @@
 // terminal CLI does not require the sentinel to confirm — the token itself is
 // authoritative. The tool is retained for v1.5.0 back-compat (older skills that
 // still call it work unchanged) and slated for retirement in v1.6.0 to free the
-// MCP-tool slot (see CLAUDE.md "MCP server: ≤12 tools" cap).
+// MCP-tool slot (see CLAUDE.md "MCP server: ≤13 tools" cap).
 //
 // Does NOT execute the update. Validates the token, writes (or overwrites)
 // the pending sentinel, returns instruction telling the user to run the

package/src/dashboard-charts.js

@@ -1,239 +0,0 @@
-/**
- * dashboard-charts.js — IJFW v1.4.3 W9-C (B19)
- *
- * Pure-JS canvas/DOM chart helpers for the dashboard. No external libs.
- * Theme-aware: reads CSS custom properties `--ijfw-chart-fg`,
- * `--ijfw-chart-bg`, `--ijfw-chart-warning` from the element's computed
- * style. Falls back to sane defaults if the host page hasn't set them.
- *
- * All helpers are defensive against malformed input so a bad payload from
- * the API can never throw inside the dashboard render loop.
- */
-
-const DEFAULTS = {
-  fg: '#9ad2ff',
-  bg: 'rgba(154,210,255,0.18)',
-  warning: '#ff9b3a',
-  text: '#cfd6dd',
-};
-
-function _readTheme(el) {
-  // Both `canvas` and plain `div` go through `getComputedStyle`. In the test
-  // environment the element is a hand-rolled mock that doesn't reach the DOM
-  // — guard so we don't blow up if `getComputedStyle` is unavailable.
-  let cs = null;
-  try {
-    if (el && typeof globalThis.getComputedStyle === 'function') {
-      cs = globalThis.getComputedStyle(el);
-    }
-  } catch { cs = null; }
-  const read = (prop, fallback) => {
-    if (!cs || typeof cs.getPropertyValue !== 'function') return fallback;
-    const v = cs.getPropertyValue(prop);
-    return (v && v.trim()) ? v.trim() : fallback;
-  };
-  return {
-    fg:      read('--ijfw-chart-fg',      DEFAULTS.fg),
-    bg:      read('--ijfw-chart-bg',      DEFAULTS.bg),
-    warning: read('--ijfw-chart-warning', DEFAULTS.warning),
-    text:    read('--ijfw-chart-text',    DEFAULTS.text),
-  };
-}
-
-function _safeNum(v, def = 0) {
-  return (typeof v === 'number' && Number.isFinite(v)) ? v : def;
-}
-
-/**
- * lineChart(canvas, points, opts)
- *   points: [{ x: number, y: number }, ...] OR [number, ...]
- *   opts:   { xMin?, xMax?, yMax?, color?, fill? }
- *
- * Empty data renders nothing (clears the canvas) without throwing.
- */
-export function lineChart(canvas, points, opts = {}) {
-  if (!canvas || typeof canvas.getContext !== 'function') return;
-  const ctx = canvas.getContext('2d');
-  if (!ctx) return;
-  const W = _safeNum(canvas.width, 200);
-  const H = _safeNum(canvas.height, 100);
-  const theme = _readTheme(canvas);
-  const color = opts.color || theme.fg;
-  const fill  = opts.fill === false ? null : theme.bg;
-
-  try { ctx.clearRect(0, 0, W, H); } catch {}
-
-  const pts = Array.isArray(points) ? points : [];
-  const norm = pts.map((p, i) => {
-    if (typeof p === 'number') return { x: i, y: _safeNum(p, 0) };
-    return { x: _safeNum(p && p.x, i), y: _safeNum(p && p.y, 0) };
-  }).filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y));
-
-  if (norm.length === 0) return;
-
-  let xMin = _safeNum(opts.xMin, norm[0].x);
-  let xMax = _safeNum(opts.xMax, norm[norm.length - 1].x);
-  if (xMax === xMin) xMax = xMin + 1;
-  const yMax = _safeNum(opts.yMax, Math.max(1, ...norm.map((p) => p.y)));
-  const yScale = yMax > 0 ? yMax : 1;
-
-  const pad = 4;
-  const innerW = Math.max(1, W - pad * 2);
-  const innerH = Math.max(1, H - pad * 2);
-
-  const px = (x) => pad + ((x - xMin) / (xMax - xMin)) * innerW;
-  const py = (y) => pad + (1 - (Math.max(0, y) / yScale)) * innerH;
-
-  // Filled area
-  if (fill) {
-    try {
-      ctx.beginPath();
-      ctx.moveTo(px(norm[0].x), H - pad);
-      for (const p of norm) ctx.lineTo(px(p.x), py(p.y));
-      ctx.lineTo(px(norm[norm.length - 1].x), H - pad);
-      ctx.closePath();
-      ctx.fillStyle = fill;
-      ctx.fill();
-    } catch {}
-  }
-
-  // Line stroke
-  try {
-    ctx.beginPath();
-    ctx.moveTo(px(norm[0].x), py(norm[0].y));
-    for (let i = 1; i < norm.length; i++) ctx.lineTo(px(norm[i].x), py(norm[i].y));
-    ctx.strokeStyle = color;
-    ctx.lineWidth   = 1.5;
-    ctx.stroke();
-  } catch {}
-}
-
-/**
- * barChart(canvas, bars, opts)
- *   bars: [{ label: string, value: number, color?: string }, ...]
- *   opts: { horizontal?: boolean, color?: string, maxValue?: number }
- *
- * Zero-value bars render as empty rails. Negative values are clamped to 0.
- */
-export function barChart(canvas, bars, opts = {}) {
-  if (!canvas || typeof canvas.getContext !== 'function') return;
-  const ctx = canvas.getContext('2d');
-  if (!ctx) return;
-  const W = _safeNum(canvas.width, 200);
-  const H = _safeNum(canvas.height, 100);
-  const theme = _readTheme(canvas);
-  const defaultColor = opts.color || theme.fg;
-  const horizontal = Boolean(opts.horizontal);
-
-  try { ctx.clearRect(0, 0, W, H); } catch {}
-
-  const rows = Array.isArray(bars) ? bars.filter((b) => b && typeof b === 'object') : [];
-  if (rows.length === 0) return;
-
-  const values = rows.map((b) => Math.max(0, _safeNum(b.value, 0)));
-  const maxVal = _safeNum(opts.maxValue, Math.max(1, ...values));
-  const scale = maxVal > 0 ? maxVal : 1;
-
-  const pad = 4;
-  const labelGutter = horizontal ? 80 : 14;
-  const innerW = Math.max(1, W - pad * 2 - (horizontal ? labelGutter : 0));
-  const innerH = Math.max(1, H - pad * 2 - (horizontal ? 0 : labelGutter));
-  const slot = (horizontal ? innerH : innerW) / rows.length;
-  const barW = Math.max(1, slot * 0.7);
-
-  for (let i = 0; i < rows.length; i++) {
-    const b = rows[i];
-    const v = values[i];
-    const color = b.color || defaultColor;
-    if (horizontal) {
-      const y = pad + i * slot + (slot - barW) / 2;
-      const len = (v / scale) * innerW;
-      try {
-        ctx.fillStyle = theme.bg;
-        ctx.fillRect(pad + labelGutter, y, innerW, barW);
-        ctx.fillStyle = color;
-        ctx.fillRect(pad + labelGutter, y, len, barW);
-        ctx.fillStyle = theme.text;
-        ctx.fillText(String(b.label || ''), pad, y + barW * 0.75);
-      } catch {}
-    } else {
-      const x = pad + i * slot + (slot - barW) / 2;
-      const len = (v / scale) * innerH;
-      try {
-        ctx.fillStyle = theme.bg;
-        ctx.fillRect(x, pad, barW, innerH);
-        ctx.fillStyle = color;
-        ctx.fillRect(x, pad + (innerH - len), barW, len);
-        ctx.fillStyle = theme.text;
-        ctx.fillText(String(b.label || '').slice(0, 8), x, H - pad);
-      } catch {}
-    }
-  }
-}
-
-/**
- * progressBar(div, data)
- *   data: { current: number, limit: number | null, label?: string, warning?: boolean }
- *
- * Mutates `div` in place. Renders an "unlimited" placeholder when limit is
- * null. Applies a warning class when `warning` is truthy.
- */
-export function progressBar(div, data = {}) {
-  if (!div) return;
-  const theme = _readTheme(div);
-  const cur = Math.max(0, _safeNum(data.current, 0));
-  const lim = (data.limit === null || data.limit === undefined) ? null : _safeNum(data.limit, null);
-  const label = typeof data.label === 'string' ? data.label : '';
-  const warn = Boolean(data.warning);
-
-  // Clear children.
-  try {
-    while (div.firstChild) div.removeChild(div.firstChild);
-  } catch {
-    // Some test mocks omit firstChild/removeChild. Skip cleanup.
-  }
-
-  const setClass = (extra) => {
-    try {
-      div.className = ['ijfw-progress', extra, warn ? 'ijfw-progress--warn' : '']
-        .filter(Boolean).join(' ');
-    } catch {}
-  };
-
-  // Helper to create child elements safely.
-  function appendEl(tag, opts) {
-    try {
-      if (typeof div.ownerDocument === 'object' && div.ownerDocument && typeof div.ownerDocument.createElement === 'function') {
-        const el = div.ownerDocument.createElement(tag);
-        if (opts && opts.text) el.textContent = opts.text;
-        if (opts && opts.style) el.setAttribute('style', opts.style);
-        if (opts && opts.cls) el.className = opts.cls;
-        if (typeof div.appendChild === 'function') div.appendChild(el);
-        return el;
-      }
-    } catch {}
-    return null;
-  }
-
-  if (lim === null) {
-    setClass('ijfw-progress--unlimited');
-    appendEl('span', { cls: 'ijfw-progress-label', text: label });
-    appendEl('span', { cls: 'ijfw-progress-val',   text: cur + ' / unlimited' });
-    return;
-  }
-
-  setClass('');
-  const denom = lim > 0 ? lim : 1;
-  const pct = Math.max(0, Math.min(100, (cur / denom) * 100));
-  appendEl('span', { cls: 'ijfw-progress-label', text: label });
-  const rail = appendEl('span', { cls: 'ijfw-progress-rail', style: 'background:' + theme.bg + ';display:inline-block;height:6px;width:120px;border-radius:3px;overflow:hidden;vertical-align:middle;margin:0 6px' });
-  if (rail) {
-    try {
-      const fill = (rail.ownerDocument || div.ownerDocument).createElement('span');
-      fill.className = 'ijfw-progress-fill';
-      fill.setAttribute('style', 'display:block;height:100%;width:' + pct.toFixed(1) + '%;background:' + (warn ? theme.warning : theme.fg));
-      rail.appendChild(fill);
-    } catch {}
-  }
-  appendEl('span', { cls: 'ijfw-progress-val', text: cur + ' / ' + lim });
-}