@ijfw/memory-server 1.4.4 → 1.5.0

package/src/team/generator.js

@@ -10,15 +10,262 @@ import { fileURLToPath } from 'node:url';
 import { writeAtomic } from '../lib/atomic-io.js';
 import { syncCodexAgents } from '../codex-agents.js';
 import { detect } from '../project-type-detector.js';
-import { assertValidTeamBundle, validateTeamCharter, validateWorkflowManifest } from './schemas.js';
+import {
+  DOMAIN_SPECIALIST_AGENT_IDS as CANONICAL_DOMAIN_SPECIALIST_AGENT_IDS,
+  SOFTWARE_CORE_AGENT_IDS as CANONICAL_SOFTWARE_CORE_AGENT_IDS,
+  assertValidTeamBundle,
+  validateTeamCharter,
+  validateWorkflowManifest,
+} from './schemas.js';
 
 const FIXTURE_DIR = resolve(fileURLToPath(new URL('../../fixtures/team/', import.meta.url)));
 const SUPPORTED_ARCHETYPES = new Set(['software', 'design', 'content', 'book', 'research', 'business', 'mixed']);
 
+// 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
+// these — it references them by id and trusts the installer to deploy the
+// markdown files into platform-native agent directories.
+//
+// Single source of truth lives in `./schemas.js` (so downstream validators
+// can reference the canonical list without importing the generator). This
+// re-export keeps the historic generator.js surface intact for callers
+// already wired to `SOFTWARE_CORE_AGENT_IDS`.
+//
+// Static set (order is deterministic for snapshot stability):
+//   - ijfw-doc-verifier        — factual-claim verification post-doc-gen
+//   - ijfw-integration-checker — cross-subagent E2E flow verification
+//   - ijfw-nyquist-auditor     — coverage-gap closure + skeleton-test proposals
+//   - ijfw-code-fixer          — atomic per-finding code fixes (G4 fixer)
+export const SOFTWARE_CORE_AGENT_IDS = CANONICAL_SOFTWARE_CORE_AGENT_IDS;
+
+// T25 / G7-gen: canonical per-domain specialist agent ids. Re-exported from
+// schemas.js so callers wired to `generator.js` get a stable surface. See
+// schemas.js for the per-archetype contract and the rationale for which
+// archetypes are populated today.
+export const DOMAIN_SPECIALIST_AGENT_IDS = CANONICAL_DOMAIN_SPECIALIST_AGENT_IDS;
+
+// T24: archetypes that always include the software-core agent set.
+// Currently only `software`; future domains (`mixed` with software files)
+// may opt in via T25's domain-aware generator.
+const SOFTWARE_CORE_ARCHETYPES = new Set(['software']);
+
+// F-FUN-1: alias map -- detector returns language-flavoured labels and
+// project-type-detector emits 'unknown' / unmapped domains. Canonicalize
+// BEFORE the SUPPORTED_ARCHETYPES gate so detector outputs don't collapse
+// to 'mixed' just because the literal string isn't in the supported set.
+const ARCHETYPE_ALIASES = new Map([
+  // language-specific aliases that some detector paths surface
+  ['typescript', 'software'],
+  ['javascript', 'software'],
+  ['python', 'software'],
+  ['rust', 'software'],
+  ['go', 'software'],
+  ['java', 'software'],
+  ['ruby', 'software'],
+  ['php', 'software'],
+  ['cpp', 'software'],
+  ['c++', 'software'],
+  ['csharp', 'software'],
+  ['code', 'software'],
+  ['app', 'software'],
+  ['api', 'software'],
+  // domain synonyms surfaced by briefs and detector secondaries
+  ['marketing', 'content'],
+  ['campaign', 'content'],
+  ['launch', 'content'],
+  ['blog', 'content'],
+  ['copy', 'content'],
+  ['ui', 'design'],
+  ['ux', 'design'],
+  ['novel', 'book'],
+  ['story', 'book'],
+  ['manuscript', 'book'],
+  ['paper', 'research'],
+  ['study', 'research'],
+  ['thesis', 'research'],
+  ['strategy', 'business'],
+  ['ops', 'business'],
+  ['operations', 'business'],
+  ['education', 'mixed'],
+  ['unknown', 'mixed'],
+]);
+
+// F-FUN-1: brief keyword maps. Each phrase scores +1 toward the listed
+// archetype on whole-word hit. Word boundaries matter -- "research" matches
+// in "research project" but not "researching" -- so we tokenize the brief
+// before scoring. Mirrors the canonical domain list in team-templates.md.
+const BRIEF_KEYWORDS = {
+  software: [
+    'software', 'app', 'application', 'api', 'code', 'codebase', 'service',
+    'webapp', 'backend', 'frontend', 'mobile', 'sdk', 'library', 'cli',
+    'feature', 'endpoint', 'module', 'refactor', 'bugfix', 'plugin',
+    'platform', 'integration', 'pipeline',
+  ],
+  book: [
+    'book', 'novel', 'novella', 'story', 'chapter', 'chapters', 'manuscript',
+    'memoir', 'fiction', 'nonfiction', 'prose', 'narrative', 'screenplay',
+    'cookbook', 'anthology',
+  ],
+  content: [
+    'campaign', 'launch', 'marketing', 'content', 'blog', 'article',
+    'newsletter', 'copy', 'copywriting', 'landing', 'social', 'seo',
+    'email', 'post', 'posts', 'announcement', 'press',
+  ],
+  design: [
+    'design', 'ui', 'ux', 'wireframe', 'mockup', 'figma', 'prototype',
+    'visual', 'brand', 'logo', 'illustration', 'typography', 'palette',
+    'design-system',
+  ],
+  research: [
+    'research', 'paper', 'study', 'thesis', 'methodology', 'experiment',
+    'literature', 'corpus', 'survey', 'analysis', 'hypothesis', 'findings',
+    'whitepaper',
+  ],
+  business: [
+    'business', 'strategy', 'operations', 'ops', 'financial', 'finance',
+    'budget', 'forecast', 'plan', 'pitch', 'investor', 'gtm', 'b2b', 'b2c',
+    'revenue', 'roadmap', 'okrs',
+  ],
+};
+
+// F-FUN-1: brief signal threshold. A single keyword hit isn't enough to
+// override filesystem signals (a software repo whose README says "we plan to
+// research X" should stay software). Two distinct keyword hits OR a strong
+// signal phrase ("write a book", "marketing campaign", "research paper")
+// flips the result. Phrases score double because they're explicit.
+const BRIEF_PHRASES = {
+  software: [/\b(build|ship|develop|implement)\s+(?:a|an|the)?\s*(app|application|api|service|feature|module|library)\b/i, /\bsource\s+code\b/i],
+  book: [/\bwrite\s+(?:a|an|the)?\s*(book|novel|memoir|story|chapter)\b/i, /\bbook\s+about\b/i],
+  content: [/\b(marketing|launch|content|seo|social\s+media)\s+(campaign|strategy|plan|push)\b/i, /\bblog\s+post\b/i],
+  design: [/\b(design|brand|ui|ux)\s+(system|kit|guide|language|review)\b/i, /\bwireframe(?:s|d)?\s+(?:the|for|of)\b/i],
+  research: [/\bresearch\s+(paper|project|study|report|brief)\b/i, /\bliterature\s+review\b/i],
+  business: [/\b(business|strategy|operations)\s+(plan|roadmap|memo)\b/i, /\binvestor\s+(deck|pitch|memo)\b/i],
+};
+
+const BRIEF_SCORE_FLIP_THRESHOLD = 2;
+
 export function detectTeamArchetype(projectRoot = process.cwd(), options = {}) {
   if (options.archetype) return normalizeArchetype(options.archetype);
+
+  // F-FUN-1: brief-first archetype routing. When the caller hands us a
+  // non-empty project brief, score it for explicit domain signals before
+  // falling back to filesystem-only detection. An explicit brief domain
+  // (e.g. "I'm writing a book about ...") MUST outweigh the filesystem
+  // signal -- otherwise book/research/campaign projects collapse to 'mixed'
+  // when run from a tmp directory or a freshly cloned repo with no files.
+  const brief = typeof options.brief === 'string' ? options.brief : '';
+  const briefScores = scoreBrief(brief);
+  const briefWinner = topBriefDomain(briefScores);
+
   const detected = detect(projectRoot, { maxFiles: options.maxFiles || 4000, c9Available: false });
-  return normalizeArchetype(detected.primary_type || detected.type);
+  const detectedArchetype = normalizeArchetype(detected.primary_type || detected.type);
+
+  if (briefWinner) return briefWinner;
+  return detectedArchetype;
+}
+
+// F-FUN-1: brief scorer. Returns a map of {archetype: score}. Word-boundary
+// match for single tokens, regex match for phrase signals (which count
+// double). The caller picks the winner.
+export function scoreBrief(brief) {
+  const scores = { software: 0, book: 0, content: 0, design: 0, research: 0, business: 0 };
+  if (!brief || typeof brief !== 'string') return scores;
+  const text = brief.toLowerCase();
+
+  for (const [domain, tokens] of Object.entries(BRIEF_KEYWORDS)) {
+    for (const token of tokens) {
+      const re = new RegExp(`\\b${escapeRegExp(token)}\\b`, 'i');
+      if (re.test(text)) scores[domain] += 1;
+    }
+  }
+
+  for (const [domain, patterns] of Object.entries(BRIEF_PHRASES)) {
+    for (const re of patterns) {
+      if (re.test(text)) scores[domain] += 2;
+    }
+  }
+
+  return scores;
+}
+
+function topBriefDomain(scores) {
+  let best = null;
+  let bestScore = 0;
+  for (const [domain, score] of Object.entries(scores)) {
+    if (score > bestScore) {
+      best = domain;
+      bestScore = score;
+    }
+  }
+  // Require at least the flip threshold AND a clear margin over runner-up.
+  // Without margin, "research the market for an app" ties software vs
+  // research and we should fall through to filesystem detection instead.
+  if (bestScore < BRIEF_SCORE_FLIP_THRESHOLD) return null;
+  const second = Object.entries(scores)
+    .filter(([d]) => d !== best)
+    .reduce((m, [, s]) => Math.max(m, s), 0);
+  if (second >= bestScore) return null;
+  return best;
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// T24 / G7-core: resolve the static software-core agent set for an
+// archetype. Returns `[]` for non-software archetypes. The returned ids
+// each resolve to `claude/agents/<id>.md` in the IJFW repo — callers can
+// look the files up via the installer's deploy step (the markdown is the
+// agent spec; the generator doesn't render its content, it references
+// it). Deterministic order.
+export function resolveSoftwareCoreAgentIds(archetype) {
+  const normalized = normalizeArchetype(archetype);
+  if (!SOFTWARE_CORE_ARCHETYPES.has(normalized)) return [];
+  // Return a fresh array so callers cannot mutate the frozen source set
+  // through the public surface.
+  return [...SOFTWARE_CORE_AGENT_IDS];
+}
+
+// T25 / G7-gen: resolve the per-domain specialist agent set. Returns the
+// archetype's specialist ids per `DOMAIN_SPECIALIST_AGENT_IDS`, or `[]` if
+// the archetype has no domain specialists yet (e.g. `research`, `business`,
+// `mixed`). For `software` this returns `[]` — the software roster is
+// covered by `resolveSoftwareCoreAgentIds`, not duplicated here.
+//
+// Deterministic order. Returns a fresh array per call.
+export function resolveDomainSpecialistAgentIds(archetype) {
+  const normalized = normalizeArchetype(archetype);
+  const specialists = DOMAIN_SPECIALIST_AGENT_IDS[normalized];
+  if (!Array.isArray(specialists)) return [];
+  return [...specialists];
+}
+
+// T25 / G7-gen: resolve the FULL roster for an archetype — the union of
+// software-core agents (when applicable) plus domain specialists. This is
+// the single function downstream callers (installers, dashboard tiles,
+// `roster.synthesize` consumers) should reach for when they want the
+// complete set of agents the generator believes a domain needs.
+//
+// Contract:
+//   - software archetype  → all 4 SOFTWARE_CORE_AGENT_IDS, no specialists
+//   - book/content/design → only the domain specialists for that archetype
+//   - other archetypes    → []
+//   - order is deterministic: software-core first, then domain specialists
+//   - no duplicates: even if a domain ever overlaps with a core id (it
+//     should not, by convention — see schemas.js), the union dedupes.
+//
+// The returned array is fresh per call so callers cannot mutate the
+// canonical sources via the public surface.
+export function resolveRosterForDomain(archetype) {
+  const normalized = normalizeArchetype(archetype);
+  const core = resolveSoftwareCoreAgentIds(normalized);
+  const specialists = resolveDomainSpecialistAgentIds(normalized);
+  const merged = [...core];
+  for (const id of specialists) {
+    if (!merged.includes(id)) merged.push(id);
+  }
+  return merged;
 }
 
 export function loadTeamTemplate(archetype) {
@@ -31,6 +278,9 @@ export function loadTeamTemplate(archetype) {
 
 export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
   const root = resolve(projectRoot);
+  // F-FUN-1: `options.brief` flows through to detectTeamArchetype so a
+  // CLI / MCP caller can hand in a project brief and get a correct
+  // archetype before any filesystem signals exist.
   const archetype = detectTeamArchetype(root, options);
   const bundle = loadTeamTemplate(archetype);
   const teamName = options.teamName || `${basename(root) || archetype}-team`;
@@ -63,6 +313,21 @@ export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
   }
   const codexAgents = syncCodexAgents(root, { bundle });
 
+  // T24 / G7-core: software-domain rosters always advertise the static
+  // software-core agent set. Non-software archetypes get an empty array
+  // (preserves the field on every return shape so callers don't need to
+  // null-check). The ids point to `claude/agents/<id>.md` in the IJFW
+  // install; the installer is responsible for placing the markdown.
+  const softwareCoreAgentIds = resolveSoftwareCoreAgentIds(archetype);
+
+  // T25 / G7-gen: domain-specific specialist agent ids. Same on-disk
+  // contract as the software-core ids — each id resolves to
+  // `claude/agents/<id>.md`. T25 returns the ids; T26 lands the matching
+  // markdown files. Until T26 ships, downstream installers should treat
+  // a missing file as "deploy stub" rather than fail-closed.
+  const domainSpecialistAgentIds = resolveDomainSpecialistAgentIds(archetype);
+  const rosterAgentIds = resolveRosterForDomain(archetype);
+
   return {
     ok: true,
     archetype,
@@ -73,6 +338,9 @@ export function createTeamAssembly(projectRoot = process.cwd(), options = {}) {
     workflowPath,
     agentFiles,
     codexAgents,
+    softwareCoreAgentIds,
+    domainSpecialistAgentIds,
+    rosterAgentIds,
   };
 }
 
@@ -105,7 +373,14 @@ export function readTeamAssembly(projectRoot = process.cwd()) {
 
 function normalizeArchetype(value) {
   const archetype = String(value || '').toLowerCase();
-  return SUPPORTED_ARCHETYPES.has(archetype) ? archetype : 'mixed';
+  if (SUPPORTED_ARCHETYPES.has(archetype)) return archetype;
+  // F-FUN-1: canonicalize via the alias map BEFORE collapsing to 'mixed'.
+  // Without this, the detector's language-flavoured outputs (typescript,
+  // javascript, python, ...) and project-type-detector's 'unknown' all
+  // collapse to 'mixed', losing the strongest signal we have.
+  const aliased = ARCHETYPE_ALIASES.get(archetype);
+  if (aliased && SUPPORTED_ARCHETYPES.has(aliased)) return aliased;
+  return 'mixed';
 }
 
 function renderAgent(role, bundle) {

package/src/team/modify.js

@@ -0,0 +1,203 @@
+// F-FUN-4 + F-FUN-5 (audit-MED-teams-#7 + #13): team-charter mutation
+// helpers. Honors the SKILL.md "Custom Agent Requests" promise -- users can
+// add, remove, swap, list, and check roles on their custom team without
+// hand-editing JSON.
+//
+// Every mutating helper:
+//   1. Reads the current charter/workflow.
+//   2. Applies the mutation in-memory.
+//   3. Validates the resulting charter via team/schemas.js.
+//   4. Writes the charter back atomically.
+//   5. Re-runs syncCodexAgents so .codex/agents/ stays in lockstep.
+//
+// `checkTeamAssembly` is the standalone validator surfaced by
+// `ijfw team check` -- it does not write anything and does not require
+// `ijfw swarm plan` to surface error messages.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { writeAtomic } from '../lib/atomic-io.js';
+import { syncCodexAgents } from '../codex-agents.js';
+import { readTeamAssembly } from './generator.js';
+import { validateTeamCharter, validateWorkflowManifest } from './schemas.js';
+
+function teamPaths(root) {
+  return {
+    charterPath: join(root, '.ijfw', 'team', 'charter.json'),
+    workflowPath: join(root, '.ijfw', 'team', 'workflow.json'),
+  };
+}
+
+function loadCharter(root) {
+  const { charterPath } = teamPaths(root);
+  if (!existsSync(charterPath)) return null;
+  return JSON.parse(readFileSync(charterPath, 'utf8'));
+}
+
+function loadWorkflow(root) {
+  const { workflowPath } = teamPaths(root);
+  if (!existsSync(workflowPath)) return null;
+  return JSON.parse(readFileSync(workflowPath, 'utf8'));
+}
+
+function writeCharter(root, charter) {
+  const { charterPath } = teamPaths(root);
+  writeAtomic(charterPath, `${JSON.stringify(charter, null, 2)}\n`, { mode: 0o600 });
+  return charterPath;
+}
+
+/**
+ * List the current roles + summary metadata for the team. Returns a
+ * structured payload so callers (CLI + future MCP tool) can render however
+ * they like.
+ */
+export function listTeamRoles(projectRoot = process.cwd()) {
+  const root = resolve(projectRoot);
+  const charter = loadCharter(root);
+  if (!charter) return { ok: false, error: 'missing-charter' };
+  const roles = Array.isArray(charter.roles) ? charter.roles : [];
+  return {
+    ok: true,
+    team_name: charter.team_name || null,
+    project_archetypes: charter.project_archetypes || [],
+    roles: roles.map((r) => ({
+      name: r.name,
+      role_type: r.role_type,
+      model: r.model,
+      effort: r.effort || 'medium',
+      phase_scope: r.phase_scope || [],
+    })),
+  };
+}
+
+/**
+ * Add a role to the charter. The charter is supplied as a JSON path; we
+ * read+validate it before splicing in. Triggers a codex agent re-sync.
+ */
+export function addTeamRole(projectRoot, { charterPath, role }) {
+  const root = resolve(projectRoot);
+  const charter = loadCharter(root);
+  if (!charter) return { ok: false, error: 'missing-charter' };
+
+  const incoming = role || readJsonFile(charterPath);
+  if (!incoming || typeof incoming !== 'object') return { ok: false, error: 'invalid-role-payload' };
+  if (!incoming.name) return { ok: false, error: 'role-name-required' };
+
+  const existing = (charter.roles || []).find((r) => r.name === incoming.name);
+  if (existing) return { ok: false, error: 'role-exists', name: incoming.name };
+
+  const next = { ...charter, roles: [...(charter.roles || []), incoming] };
+  const validation = validateTeamCharter(next);
+  if (!validation.ok) return { ok: false, error: 'invalid-charter', errors: validation.errors };
+
+  writeCharter(root, next);
+  const codex = syncCodexAgents(root);
+  return { ok: true, role: incoming, codex };
+}
+
+/**
+ * Remove a role by name. Refuses if removing the role would leave the
+ * charter invalid (e.g. last role).
+ */
+export function removeTeamRole(projectRoot, { name }) {
+  const root = resolve(projectRoot);
+  const charter = loadCharter(root);
+  if (!charter) return { ok: false, error: 'missing-charter' };
+
+  const before = (charter.roles || []).length;
+  const roles = (charter.roles || []).filter((r) => r.name !== name);
+  if (roles.length === before) return { ok: false, error: 'role-not-found', name };
+
+  const next = { ...charter, roles };
+  const validation = validateTeamCharter(next);
+  if (!validation.ok) return { ok: false, error: 'invalid-charter', errors: validation.errors };
+
+  writeCharter(root, next);
+  const codex = syncCodexAgents(root);
+  return { ok: true, removed: name, codex };
+}
+
+/**
+ * Replace one role with another. `oldName` must exist; `replacement` is a
+ * full role object (or path to a JSON file describing one).
+ */
+export function swapTeamRole(projectRoot, { oldName, charterPath, replacement }) {
+  const root = resolve(projectRoot);
+  const charter = loadCharter(root);
+  if (!charter) return { ok: false, error: 'missing-charter' };
+
+  const incoming = replacement || readJsonFile(charterPath);
+  if (!incoming || typeof incoming !== 'object') return { ok: false, error: 'invalid-role-payload' };
+  if (!incoming.name) return { ok: false, error: 'role-name-required' };
+
+  const roles = charter.roles || [];
+  const idx = roles.findIndex((r) => r.name === oldName);
+  if (idx === -1) return { ok: false, error: 'role-not-found', name: oldName };
+
+  // Name collision when the replacement keeps a *different* existing name.
+  if (incoming.name !== oldName && roles.some((r) => r.name === incoming.name)) {
+    return { ok: false, error: 'role-exists', name: incoming.name };
+  }
+
+  const nextRoles = roles.slice();
+  nextRoles[idx] = incoming;
+  const next = { ...charter, roles: nextRoles };
+  const validation = validateTeamCharter(next);
+  if (!validation.ok) return { ok: false, error: 'invalid-charter', errors: validation.errors };
+
+  writeCharter(root, next);
+  const codex = syncCodexAgents(root);
+  return { ok: true, swapped: { old: oldName, new: incoming.name }, codex };
+}
+
+/**
+ * F-FUN-5 (audit-MED-teams-#13): standalone team validation. Returns a
+ * structured pass/fail report so the CLI can render a human-readable list
+ * without forcing the caller into `ijfw swarm plan`.
+ */
+export function checkTeamAssembly(projectRoot = process.cwd()) {
+  const root = resolve(projectRoot);
+  const charter = loadCharter(root);
+  const workflow = loadWorkflow(root);
+  const report = {
+    ok: true,
+    has_charter: Boolean(charter),
+    has_workflow: Boolean(workflow),
+    charter: { ok: true, errors: [] },
+    workflow: { ok: true, errors: [] },
+    role_count: 0,
+    artifact_count: 0,
+  };
+  if (!charter) {
+    report.ok = false;
+    report.charter = { ok: false, errors: ['charter.json is missing -- run: ijfw team init'] };
+  } else {
+    const c = validateTeamCharter(charter);
+    report.charter = c;
+    report.role_count = Array.isArray(charter.roles) ? charter.roles.length : 0;
+    if (!c.ok) report.ok = false;
+  }
+  if (!workflow) {
+    report.ok = false;
+    report.workflow = { ok: false, errors: ['workflow.json is missing -- run: ijfw team init'] };
+  } else {
+    const w = validateWorkflowManifest(workflow, charter);
+    report.workflow = w;
+    report.artifact_count = Array.isArray(workflow.artifacts) ? workflow.artifacts.length : 0;
+    if (!w.ok) report.ok = false;
+  }
+  return report;
+}
+
+function readJsonFile(path) {
+  if (!path) return null;
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// Re-exports for the CLI surface so it can `import * as teamModify`.
+export { readTeamAssembly };

package/src/team/schemas.js

@@ -10,6 +10,54 @@ const ARCHETYPES = new Set([
   'mixed',
 ]);
 
+// T24 / G7-core: canonical software-core agent ids. Mirrored by
+// `SOFTWARE_CORE_AGENT_IDS` in generator.js — this re-export gives
+// schema-side consumers (validators, downstream tools, T25's domain-aware
+// generator) a single source of truth without circular import on
+// generator.js. Any change to the set MUST update both locations and the
+// matching `claude/agents/<id>.md` files on disk.
+export const SOFTWARE_CORE_AGENT_IDS = Object.freeze([
+  'ijfw-doc-verifier',
+  'ijfw-integration-checker',
+  'ijfw-nyquist-auditor',
+  'ijfw-code-fixer',
+]);
+
+// T25 / G7-gen: canonical domain-specialist agent ids by archetype. The map
+// is the single source of truth for which specialist ids the generator
+// returns for each domain — T26 will author the matching
+// `claude/agents/<id>.md` files so the installer can deploy them; T25 just
+// makes the generator hand them back per archetype.
+//
+// Contract:
+//   - keys are normalized archetypes (post-alias-map). `book`, `content`,
+//     and `design` are populated today; other archetypes get `[]` until
+//     T26 expands the set.
+//   - values are deterministic arrays; insertion order is roster-display order.
+//   - software domain's specialists are the SOFTWARE_CORE_AGENT_IDS — this
+//     map intentionally does NOT duplicate them (`resolveDomainSpecialistAgentIds`
+//     in generator.js returns the union for software). Non-software domains
+//     own their own specialist lists exclusively.
+//
+// Choice of three+ domains (`book`, `content`, `design`) satisfies the
+// "≥3 non-software domains" constraint and gives T26 concrete templates
+// to flesh out. Other archetypes will gain rosters in later tasks.
+export const DOMAIN_SPECIALIST_AGENT_IDS = Object.freeze({
+  book: Object.freeze([
+    'ijfw-narrative-continuity-checker',
+    'ijfw-line-editor',
+    'ijfw-lore-keeper',
+  ]),
+  content: Object.freeze([
+    'ijfw-campaign-strategist',
+    'ijfw-copy-reviewer',
+  ]),
+  design: Object.freeze([
+    'ijfw-design-critic',
+    'ijfw-accessibility-reviewer',
+  ]),
+});
+
 const ROLE_TYPES = new Set([
   'lead',
   'software',

package/src/update-apply.js

@@ -1,5 +1,14 @@
 // MCP tool: ijfw_update_apply
 //
+// @deprecated since v1.5.0; will be removed in v1.6.0 (F-FUN-3 / v1.5.0 audit-MED-M7).
+// `ijfw_update_check` already issues a confirmation token whose instruction tells
+// the user to type `ijfw update --confirm <token>` in their terminal directly.
+// The intermediate `ijfw_update_apply` step writes a pending sentinel, but the
+// 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).
+//
 // Does NOT execute the update. Validates the token, writes (or overwrites)
 // the pending sentinel, returns instruction telling the user to run the
 // terminal-side confirm command. Idempotent against a matching sentinel
@@ -10,6 +19,11 @@
 import { validateToken, writePendingSentinel } from './lib/token.js';
 import { isVersionStringValid } from './lib/npm-view.js';
 
+/**
+ * @deprecated since v1.5.0; scheduled for removal in v1.6.0. Callers should
+ * skip straight from `ijfw_update_check` to the terminal-side confirm command;
+ * the intermediate sentinel write is redundant given the token contract.
+ */
 export function ijfwUpdateApply(args = {}) {
   const { target_version, confirmation_token } = args || {};
   const sessionId = args.session_id || process.env.IJFW_SESSION_ID || 'default-session';
@@ -64,9 +78,11 @@ export function ijfwUpdateApply(args = {}) {
 export const TOOL_DEF = {
   name: 'ijfw_update_apply',
   description:
-    'Stage an IJFW update behind out-of-band terminal confirmation. Writes a pending sentinel; ' +
-    "actual update only runs when the user types 'ijfw update --confirm <token>' in their terminal. " +
-    'This MCP tool NEVER executes the update directly.',
+    '[DEPRECATED v1.5.0; removal in v1.6.0] Stage an IJFW update behind out-of-band terminal ' +
+    'confirmation. Writes a pending sentinel; actual update only runs when the user types ' +
+    "'ijfw update --confirm <token>' in their terminal. This MCP tool NEVER executes the " +
+    'update directly. Prefer calling ijfw_update_check and forwarding the returned ' +
+    "'ijfw update --confirm <token>' instruction directly to the user.",
   inputSchema: {
     type: 'object',
     required: ['target_version', 'confirmation_token'],