@ijfw/memory-server 1.4.4 → 1.5.0

package/src/swarm/worktree.js

@@ -7,6 +7,7 @@
 import { existsSync, mkdirSync, realpathSync, rmSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { appendBlackboardEvent, listBlackboardTasks, updateBlackboardTask } from '../blackboard.js';
 import { createCheckpoint } from '../recovery/checkpoint.js';
 
@@ -29,12 +30,31 @@ export function createTaskWorktree(projectRoot, taskId, options = {}) {
 
   const baseRef = options.baseRef || 'HEAD';
   const worktreeDir = join(root, '.ijfw', 'worktrees');
-  const worktreePath = join(worktreeDir, safeTaskId(taskId));
-  if (existsSync(worktreePath)) return { ok: false, error: 'worktree-exists', path: worktreePath };
   mkdirSync(worktreeDir, { recursive: true, mode: 0o700 });
 
+  // v1.5.0 audit-LOW-teams-#15: safeTaskId collision detection.
+  // Two distinct taskIds that normalize to the same safe id (e.g. `task:1`
+  // and `task/1` both become `task-1`) would otherwise collide on the same
+  // worktree path AND the same branch name. Detect the collision by checking
+  // BOTH the worktree dir AND the existing branch list; if either is taken,
+  // suffix the safe id with a short content hash of the original taskId so
+  // distinct tasks get distinct worktrees + branches.
+  const baseSafeId = safeTaskId(taskId);
+  let safeId = baseSafeId;
+  let candidatePath = join(worktreeDir, safeId);
+  let candidateBranch = options.branch || `ijfw/${safeId}`;
+  const branchExists = (name) => git(root, ['show-ref', '--verify', '--quiet', `refs/heads/${name}`]).status === 0;
+  if (!options.branch && (existsSync(candidatePath) || branchExists(candidateBranch))) {
+    const suffix = createHash('sha256').update(String(taskId)).digest('hex').slice(0, 7);
+    safeId = `${baseSafeId}-${suffix}`;
+    candidatePath = join(worktreeDir, safeId);
+    candidateBranch = `ijfw/${safeId}`;
+  }
+  const worktreePath = candidatePath;
+  if (existsSync(worktreePath)) return { ok: false, error: 'worktree-exists', path: worktreePath };
+
   createCheckpoint(root, 'before-worktree-create', { actor: 'ijfw', message: taskId });
-  const branch = options.branch || `ijfw/${safeTaskId(taskId)}`;
+  const branch = options.branch || candidateBranch;
   const result = git(root, ['worktree', 'add', '-b', branch, worktreePath, baseRef]);
   if (result.status !== 0) return { ok: false, error: 'worktree-add-failed', stderr: result.stderr, stdout: result.stdout };
 
@@ -81,7 +101,10 @@ export function integrateTaskWorktree(projectRoot, taskId, options = {}) {
   if (wtDirty.stdout.trim()) return { ok: false, error: 'worktree-has-uncommitted-changes', detail: wtDirty.stdout.trim().split('\n') };
 
   createCheckpoint(root, 'before-worktree-integrate', { actor: 'ijfw', message: taskId });
-  const merge = git(root, ['merge', '--no-ff', '--no-edit', validation.branch]);
+  // v1.5.0 audit-LOW-teams-#14: tag merge commits with task-id so
+  // `git log --grep="ijfw merge: <task-id>"` recovers the merge boundary
+  // even after history rewrites lose the branch label.
+  const merge = git(root, ['merge', '--no-ff', '-m', `ijfw merge: ${taskId}`, validation.branch]);
   if (merge.status !== 0) {
     updateBlackboardTask(root, taskId, {
       worktree: { ...wt, status: 'merge-blocked', last_error: merge.stderr || merge.stdout },

package/src/swarm-config.js

@@ -25,22 +25,92 @@ const BASE = [
 const TESTS_SPECIALIST = { id: 'tests', role: 'Test coverage', agent_type: 'pr-test-analyzer' };
 const TYPES_SPECIALIST = { id: 'types', role: 'Type invariants', agent_type: 'type-design-analyzer' };
 
-// v1.4.4 N6 — 5 specialist agents addressing v1.4.3 build pain points
-const DOC_VERIFIER     = { id: 'doc-verifier',       role: 'Doc accuracy',       agent_type: 'ijfw-doc-verifier' };
-const PATTERN_MAPPER   = { id: 'pattern-mapper',     role: 'Onboarding patterns', agent_type: 'ijfw-pattern-mapper' };
-const SECURITY_AUDITOR = { id: 'security-auditor',   role: 'Security mitigations', agent_type: 'ijfw-security-auditor' };
-const INTEGRATION_CHECKER = { id: 'integration-checker', role: 'E2E flow verification', agent_type: 'ijfw-integration-checker' };
-const NYQUIST_AUDITOR  = { id: 'nyquist-auditor',    role: 'Coverage gaps',      agent_type: 'ijfw-nyquist-auditor' };
+// v1.4.4 N6 — 5 specialist agents addressing v1.4.3 build pain points.
+// `since` is the version the specialist was introduced (lock-in #40 added
+// retroactively in v1.5.0 W11-D1 so registration-history queries can sort
+// by introduction).
+const DOC_VERIFIER     = { id: 'doc-verifier',       role: 'Doc accuracy',       agent_type: 'ijfw-doc-verifier',       since: '1.4.4' };
+const PATTERN_MAPPER   = { id: 'pattern-mapper',     role: 'Onboarding patterns', agent_type: 'ijfw-pattern-mapper',     since: '1.4.4' };
+const SECURITY_AUDITOR = { id: 'security-auditor',   role: 'Security mitigations', agent_type: 'ijfw-security-auditor', since: '1.4.4' };
+const INTEGRATION_CHECKER = { id: 'integration-checker', role: 'E2E flow verification', agent_type: 'ijfw-integration-checker', since: '1.4.4' };
+const NYQUIST_AUDITOR  = { id: 'nyquist-auditor',    role: 'Coverage gaps',      agent_type: 'ijfw-nyquist-auditor',    since: '1.4.4' };
+
+// v1.5.0 W11-D1 S9 — 5 NEW IJFW specialists addressing v1.4.4 build pain points.
+const RALPH_LOOP_RUNNER  = { id: 'ralph-loop-runner',  role: 'Subagent truncation recovery', agent_type: 'ijfw-ralph-loop-runner',  since: '1.5.0' };
+const PLAN_CHECKER       = { id: 'plan-checker',       role: 'Plan vs codebase reality check', agent_type: 'ijfw-plan-checker',     since: '1.5.0' };
+const DEP_AUDIT          = { id: 'dep-audit',          role: 'Dependency / publishConfig drift', agent_type: 'ijfw-dep-audit',     since: '1.5.0' };
+const E2E_RUNNER         = { id: 'e2e-runner',         role: 'Pre-ship install/update/uninstall', agent_type: 'ijfw-e2e-runner',   since: '1.5.0' };
+const LLM_BUDGET_WATCHER = { id: 'llm-budget-watcher', role: 'Token-cost vs phase budget',       agent_type: 'ijfw-llm-budget-watcher', since: '1.5.0' };
+
+// v1.5.0 W11-D1 F1 — 3 GSD specialists folded in from R3 research.
+const RELEASE_ENG       = { id: 'release-eng',       role: 'Release mechanics (version, tag, publish, rollback)', agent_type: 'ijfw-release-eng',       since: '1.5.0' };
+const DOC_WRITER        = { id: 'doc-writer',        role: 'CHANGELOG + README derivation',                       agent_type: 'ijfw-doc-writer',        since: '1.5.0' };
+const ACCESSIBILITY_ENG = { id: 'accessibility-eng', role: 'WCAG AA audit of frontend surfaces',                  agent_type: 'ijfw-accessibility-eng', since: '1.5.0' };
+
+// All 8 v1.5.0 specialists, appended universally per W11-D1 spec.
+const V150_SPECIALISTS = [
+  RALPH_LOOP_RUNNER, PLAN_CHECKER, DEP_AUDIT, E2E_RUNNER, LLM_BUDGET_WATCHER,
+  RELEASE_ENG, DOC_WRITER, ACCESSIBILITY_ENG,
+];
+
+// F-FUN-3 (audit-MED-teams-#6): non-software domain specialists. Mirrors
+// the fixture role definitions so we don't duplicate prompts; the IDs here
+// are the *bench* names the swarm config tracks. Selecting a non-software
+// archetype yields a bench tailored to the domain (book gets story-architect,
+// not accessibility-eng). Software remains the default to preserve back-compat.
+const STORY_ARCHITECT     = { id: 'story-architect',    role: 'Plot + structure architecture', agent_type: 'ijfw-story-architect',    since: '1.5.0' };
+const CONTINUITY_EDITOR   = { id: 'continuity-editor',  role: 'Timeline + voice continuity',   agent_type: 'ijfw-continuity-editor',  since: '1.5.0' };
+const PROSE_STYLIST       = { id: 'prose-stylist',      role: 'Sentence-level voice + pacing', agent_type: 'ijfw-prose-stylist',      since: '1.5.0' };
+
+const CAMPAIGN_STRATEGIST = { id: 'campaign-strategist', role: 'Audience + funnel strategy',   agent_type: 'ijfw-campaign-strategist', since: '1.5.0' };
+const COPY_EDITOR         = { id: 'copy-editor',         role: 'Channel-aware copy editing',   agent_type: 'ijfw-copy-editor',         since: '1.5.0' };
+
+const RESEARCH_LEAD       = { id: 'research-lead',       role: 'Methodology + literature review', agent_type: 'ijfw-research-lead',    since: '1.5.0' };
+const DATA_ANALYST        = { id: 'data-analyst',        role: 'Quantitative analysis',         agent_type: 'ijfw-data-analyst',        since: '1.5.0' };
+
+// Per-archetype bench definitions. Keys here track the project_archetypes
+// vocabulary used by team/generator.js so a brief-detected archetype maps
+// directly to the right bench without an extra translation layer.
+const SOFTWARE_BENCH = [...BASE, TESTS_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR, ...V150_SPECIALISTS];
+const TYPED_BENCH    = [...BASE, TESTS_SPECIALIST, TYPES_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR, ...V150_SPECIALISTS];
+const GO_RUST_BENCH  = [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR, ...V150_SPECIALISTS];
+const OTHER_BENCH    = [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR, ...V150_SPECIALISTS];
+
+const BOOK_BENCH      = [STORY_ARCHITECT, CONTINUITY_EDITOR, PROSE_STYLIST, DOC_VERIFIER, NYQUIST_AUDITOR];
+const CONTENT_BENCH   = [CAMPAIGN_STRATEGIST, COPY_EDITOR, DOC_VERIFIER, NYQUIST_AUDITOR];
+const RESEARCH_BENCH  = [RESEARCH_LEAD, DATA_ANALYST, DOC_VERIFIER, NYQUIST_AUDITOR];
 
 export const DEFAULT_SPECIALISTS = {
-  node:   [...BASE, TESTS_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
-  python: [...BASE, TESTS_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
-  typed:  [...BASE, TESTS_SPECIALIST, TYPES_SPECIALIST, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
-  go:     [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
-  rust:   [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
-  other:  [...BASE, DOC_VERIFIER, PATTERN_MAPPER, SECURITY_AUDITOR, INTEGRATION_CHECKER, NYQUIST_AUDITOR],
+  // Language-keyed defaults (preserved for back-compat with v1.4.x callers
+  // that hand in a detectProjectType() result).
+  node:   SOFTWARE_BENCH,
+  python: SOFTWARE_BENCH,
+  typed:  TYPED_BENCH,
+  go:     GO_RUST_BENCH,
+  rust:   GO_RUST_BENCH,
+  other:  OTHER_BENCH,
+  // Archetype-keyed defaults (new in v1.5.0 audit-MED-teams-#6) -- selected
+  // when the caller hands in a project archetype from the team detector.
+  software:  SOFTWARE_BENCH,
+  book:      BOOK_BENCH,
+  content:   CONTENT_BENCH,
+  marketing: CONTENT_BENCH,
+  research:  RESEARCH_BENCH,
+  design:    CONTENT_BENCH,
+  business:  SOFTWARE_BENCH,
+  mixed:     SOFTWARE_BENCH,
 };
 
+// F-FUN-3: helper -- pick the right bench for a (language, archetype) pair.
+// Archetype wins when supplied (a "book" project running from a tmp dir
+// with no package.json must still receive the book bench). Falls back to
+// language and then `other` so older callers keep working.
+export function specialistsFor({ archetype, language } = {}) {
+  if (archetype && DEFAULT_SPECIALISTS[archetype]) return DEFAULT_SPECIALISTS[archetype];
+  if (language && DEFAULT_SPECIALISTS[language]) return DEFAULT_SPECIALISTS[language];
+  return DEFAULT_SPECIALISTS.other;
+}
+
 // Detects project type from filesystem signals in projectDir.
 // Returns 'node' | 'python' | 'go' | 'rust' | 'typed' | 'other'.
 export function detectProjectType(projectDir) {
@@ -74,14 +144,21 @@ function applySwarmDefaults(config) {
 }
 
 // Returns a fresh default config object for the given project type.
-function buildDefault(projectType) {
-  const specialists = DEFAULT_SPECIALISTS[projectType] ?? DEFAULT_SPECIALISTS.other;
-  return applySwarmDefaults({ project_type: projectType, specialists: specialists.map(s => ({ ...s })) });
+// F-FUN-3: supports an optional `archetype` keyed selection so non-software
+// projects (book, content, research, ...) get a domain-tailored bench.
+function buildDefault(projectType, options = {}) {
+  const specialists = specialistsFor({ archetype: options.archetype, language: projectType });
+  const config = { project_type: projectType, specialists: specialists.map(s => ({ ...s })) };
+  if (options.archetype) config.archetype = options.archetype;
+  return applySwarmDefaults(config);
 }
 
 // Reads .ijfw/swarm.json if present, otherwise detects type, generates
 // default config, persists it, and returns it.
-export function loadSwarmConfig(projectDir) {
+//
+// F-FUN-3: optional `options.archetype` overrides language-only selection so
+// brief-detected domains (book, content, research, ...) hit a tailored bench.
+export function loadSwarmConfig(projectDir, options = {}) {
   const swarmPath = join(projectDir, '.ijfw', 'swarm.json');
 
   if (existsSync(swarmPath)) {
@@ -91,7 +168,7 @@ export function loadSwarmConfig(projectDir) {
   }
 
   const projectType = detectProjectType(projectDir);
-  const config = buildDefault(projectType);
+  const config = buildDefault(projectType, { archetype: options.archetype });
 
   const ijfwDir = join(projectDir, '.ijfw');
   if (!existsSync(ijfwDir)) mkdirSync(ijfwDir, { recursive: true });

package/src/team/domain-templates/book.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "book",
+  "display_name": "Book / Long-form Narrative",
+  "description": "Novels, memoirs, non-fiction books, anthologies, and other long-form narrative works.",
+  "agent_ids": [
+    "ijfw-narrative-continuity-checker",
+    "ijfw-line-editor",
+    "ijfw-lore-keeper"
+  ],
+  "agent_id_source": "domain-specialist",
+  "workflow_phases": ["outline", "draft", "revise", "review"],
+  "brief_fields": [
+    {
+      "key": "premise",
+      "type": "string",
+      "description": "Core premise or log-line — one to two sentences summarising what the book is about.",
+      "required": true
+    },
+    {
+      "key": "genre",
+      "type": "string",
+      "description": "Genre or sub-genre (e.g. literary fiction, memoir, thriller, cookbook).",
+      "required": false
+    },
+    {
+      "key": "characters",
+      "type": "array",
+      "description": "Named principal characters with a one-sentence description each.",
+      "required": false
+    },
+    {
+      "key": "themes",
+      "type": "array",
+      "description": "Central themes the work explores (e.g. identity, grief, redemption).",
+      "required": false
+    },
+    {
+      "key": "target_length",
+      "type": "string",
+      "description": "Approximate word-count target or chapter count.",
+      "required": false
+    },
+    {
+      "key": "pov",
+      "type": "string",
+      "description": "Narrative point-of-view (first-person, third-person limited, omniscient, etc.).",
+      "required": false
+    }
+  ]
+}

package/src/team/domain-templates/business.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "business",
+  "display_name": "Business / Strategy",
+  "description": "Business plans, strategy memos, GTM plans, investor decks, OKRs, and operational roadmaps.",
+  "agent_ids": [],
+  "agent_id_source": "domain-specialist",
+  "workflow_phases": ["diagnose", "plan", "decide", "review"],
+  "brief_fields": [
+    {
+      "key": "business_objective",
+      "type": "string",
+      "description": "Primary business objective this work must serve (e.g. enter new market, cut costs, raise Series A).",
+      "required": true
+    },
+    {
+      "key": "stakeholders",
+      "type": "array",
+      "description": "Key stakeholders or decision-makers the output is written for.",
+      "required": false
+    },
+    {
+      "key": "time_horizon",
+      "type": "string",
+      "description": "Planning horizon (e.g. 90-day, annual, 3-year).",
+      "required": false
+    },
+    {
+      "key": "constraints",
+      "type": "array",
+      "description": "Known hard constraints: budget, headcount, regulatory, timeline.",
+      "required": false
+    },
+    {
+      "key": "success_metrics",
+      "type": "array",
+      "description": "Measurable success criteria (e.g. revenue target, churn rate, NPS).",
+      "required": false
+    }
+  ]
+}

package/src/team/domain-templates/content.json

@@ -0,0 +1,50 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "content",
+  "display_name": "Content / Campaign",
+  "description": "Marketing campaigns, launch copy, blog posts, newsletters, social media, and SEO content.",
+  "agent_ids": [
+    "ijfw-campaign-strategist",
+    "ijfw-copy-reviewer"
+  ],
+  "agent_id_source": "domain-specialist",
+  "workflow_phases": ["plan", "execute", "review", "publish"],
+  "brief_fields": [
+    {
+      "key": "objective",
+      "type": "string",
+      "description": "Primary campaign objective (e.g. product launch, lead gen, brand awareness).",
+      "required": true
+    },
+    {
+      "key": "audience",
+      "type": "string",
+      "description": "Target audience segment — who the content is written for.",
+      "required": true
+    },
+    {
+      "key": "channels",
+      "type": "array",
+      "description": "Distribution channels in scope (e.g. blog, email, Twitter/X, LinkedIn, press).",
+      "required": false
+    },
+    {
+      "key": "tone",
+      "type": "string",
+      "description": "Brand voice and tone guidelines (e.g. authoritative, conversational, playful).",
+      "required": false
+    },
+    {
+      "key": "key_messages",
+      "type": "array",
+      "description": "Top-line messages that every piece must reinforce.",
+      "required": false
+    },
+    {
+      "key": "cta",
+      "type": "string",
+      "description": "Primary call-to-action the campaign drives toward.",
+      "required": false
+    }
+  ]
+}

package/src/team/domain-templates/design.json

@@ -0,0 +1,44 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "design",
+  "display_name": "Design / UX",
+  "description": "UI/UX design, design systems, brand identity, wireframes, and visual prototypes.",
+  "agent_ids": [
+    "ijfw-design-critic",
+    "ijfw-accessibility-reviewer"
+  ],
+  "agent_id_source": "domain-specialist",
+  "workflow_phases": ["discovery", "shape", "execute", "review"],
+  "brief_fields": [
+    {
+      "key": "product",
+      "type": "string",
+      "description": "The product or surface being designed (e.g. mobile app, dashboard, landing page).",
+      "required": true
+    },
+    {
+      "key": "design_goal",
+      "type": "string",
+      "description": "Primary design goal (e.g. reduce cognitive load, increase conversion, establish brand).",
+      "required": false
+    },
+    {
+      "key": "platform",
+      "type": "string",
+      "description": "Target platform(s): web, iOS, Android, desktop, cross-platform.",
+      "required": false
+    },
+    {
+      "key": "design_system",
+      "type": "string",
+      "description": "Existing design system or style guide in use (e.g. Material, Tailwind, proprietary).",
+      "required": false
+    },
+    {
+      "key": "accessibility_target",
+      "type": "string",
+      "description": "Accessibility conformance target (e.g. WCAG 2.1 AA, Section 508).",
+      "required": false
+    }
+  ]
+}

package/src/team/domain-templates/research.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "research",
+  "display_name": "Research / Analysis",
+  "description": "Academic papers, whitepapers, literature reviews, studies, and investigative analysis.",
+  "agent_ids": [],
+  "agent_id_source": "domain-specialist",
+  "workflow_phases": ["question", "collect", "synthesize", "review"],
+  "brief_fields": [
+    {
+      "key": "research_question",
+      "type": "string",
+      "description": "Primary research question or hypothesis the work addresses.",
+      "required": true
+    },
+    {
+      "key": "methodology",
+      "type": "string",
+      "description": "Research methodology (e.g. qualitative, quantitative, mixed-methods, literature review).",
+      "required": false
+    },
+    {
+      "key": "sources",
+      "type": "array",
+      "description": "Key source types or corpora to consult (e.g. academic databases, proprietary data, interviews).",
+      "required": false
+    },
+    {
+      "key": "output_format",
+      "type": "string",
+      "description": "Intended output artefact (e.g. journal paper, internal report, executive summary).",
+      "required": false
+    },
+    {
+      "key": "scope_constraints",
+      "type": "string",
+      "description": "Explicit scope limits: time range, geography, population, domain.",
+      "required": false
+    }
+  ]
+}

package/src/team/domain-templates/software.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "domain-template/v1",
+  "domain": "software",
+  "display_name": "Software / Engineering",
+  "description": "Code, APIs, services, libraries, CLIs, mobile and web applications.",
+  "agent_ids": [
+    "ijfw-doc-verifier",
+    "ijfw-integration-checker",
+    "ijfw-nyquist-auditor",
+    "ijfw-code-fixer"
+  ],
+  "agent_id_source": "software-core",
+  "workflow_phases": ["plan", "execute", "review", "verify"],
+  "brief_fields": [
+    {
+      "key": "stack",
+      "type": "string",
+      "description": "Primary language / framework stack (e.g. Node.js + Express, Python + FastAPI).",
+      "required": false
+    },
+    {
+      "key": "architecture",
+      "type": "string",
+      "description": "High-level architecture pattern (e.g. monolith, microservices, serverless).",
+      "required": false
+    },
+    {
+      "key": "entry_points",
+      "type": "array",
+      "description": "Key modules or endpoints the team should focus on first.",
+      "required": false
+    },
+    {
+      "key": "test_strategy",
+      "type": "string",
+      "description": "Preferred test approach: unit, integration, e2e, TDD.",
+      "required": false
+    }
+  ]
+}