harness-everything 0.3.6 → 0.4.0

package/multi-agent-workspace/scripts/scaffold.js

@@ -4,18 +4,28 @@
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
+const {
+  ZONES: DOCUMENT_ZONES,
+  getWorkspaceRoot,
+  resolveProjectDocs,
+  ensureCommittableFallback
+} = require('./project-docs-resolver');
 const {
   SUPPORTED_PLATFORMS,
   readAgencyCatalog,
   resolveSelection
 } = require('./agency-catalog');
+const { assertContainedPath } = require('./path-boundary');
 
 const GENERATOR = 'harness-everything/multi-agent-workspace';
-const ZONES = Object.freeze(['state', 'logs', 'decisions', 'domain', 'architecture', 'roles']);
+const RUNTIME_ZONES = Object.freeze(['state', 'logs', 'roles']);
+const ALL_ZONES = Object.freeze(['state', 'logs', 'decisions', 'domain', 'architecture', 'roles']);
+const ROUTER_TEMPLATE = path.join(__dirname, '..', 'templates', 'AGENTS.md');
 
 function values(args, name) {
   const result = [];
-  for (let i = 0; i < args.length; i++) if (args[i] === name) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] !== name) continue;
     if (!args[i + 1] || args[i + 1].startsWith('--')) throw new Error(`${name} requires a value`);
     result.push(args[++i]);
   }
@@ -28,7 +38,11 @@ function commaValues(args, name) {
 
 function parseArgs(args) {
   if (args.includes('--help') || args.includes('-h')) return { help: true };
-  const workspace = values(args, '--workspace')[0] || '.';
+  const explicitWorkspace = values(args, '--workspace')[0];
+  const workspace = explicitWorkspace || getWorkspaceRoot();
+  if (!workspace) {
+    throw new Error('cannot infer a workspace outside a git repository; pass --workspace <path> explicitly');
+  }
   const sourceValues = values(args, '--agency-source');
   const platform = values(args, '--platform')[0] || null;
   if (platform && !SUPPORTED_PLATFORMS.includes(platform)) {
@@ -51,16 +65,16 @@ function json(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
-function readExistingManifest(outputRoot) {
-  const file = path.join(outputRoot, 'manifest.json');
+function readExistingManifest(runtimeRoot) {
+  const file = path.join(runtimeRoot, 'manifest.json');
   if (!fs.existsSync(file)) return null;
   try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
-  catch (error) { throw new Error(`existing manifest is invalid: ${error.message}`); }
+  catch (error) { throw new Error(`existing runtime manifest is invalid: ${error.message}`); }
 }
 
 function detectStack(workspaceRoot) {
-  const files = fs.readdirSync(workspaceRoot, { withFileTypes: true });
-  const names = new Set(files.filter(entry => entry.isFile()).map(entry => entry.name));
+  const names = new Set(fs.readdirSync(workspaceRoot, { withFileTypes: true })
+    .filter(entry => entry.isFile()).map(entry => entry.name));
   if (names.has('package.json')) return 'node';
   if (names.has('pyproject.toml') || names.has('requirements.txt')) return 'python';
   if (names.has('Cargo.toml')) return 'rust';
@@ -70,55 +84,47 @@ function detectStack(workspaceRoot) {
 
 function gitRevision(root) {
   if (!fs.existsSync(path.join(root, '.git'))) return null;
-  try { return execFileSync('git', ['-C', root, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).trim(); }
+  try { return execFileSync('git', ['-C', root, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
   catch { return null; }
 }
 
 function renderRouter(manifest) {
-  const agencyLine = manifest.agency.status === 'available'
-    ? `Agency catalog: ${manifest.agency.agentCount} agents in ${manifest.agency.divisionCount} divisions; load selected roles only.`
-    : `Agency catalog unavailable: ${manifest.agency.reason}`;
-  return `# Multi-Agent Workspace Router
-
-This router is generated by ${GENERATOR}. Sub-agents MUST NOT modify this file.
-
-## Bootstrap Protocol
-1. Read the task payload, then \`.harness/multi-agent/state/\`.
-2. Read only the relevant decision and architecture records.
-3. Load the launcher and selected roles before delegating.
-4. Return a structured handoff with changed files and verification evidence.
-
-## Boundaries
-- Write working state to \`.harness/multi-agent/state/\`; keep raw output in \`.harness/multi-agent/logs/\`.
-- Treat \`.harness/multi-agent/architecture/\` and this router as immutable contracts.
-- Delegate only the scope named in the launcher; never preload the external roster.
-- If a specialist fails, report the failure and use a bounded fallback or human escalation.
-
-## Catalog
-${agencyLine}
-`;
+  const values = {
+    RUNTIME_ROOT: manifest.runtime.root,
+    RUNTIME_STATE: manifest.runtime.state,
+    RUNTIME_LOGS: manifest.runtime.logs,
+    LAUNCHER: path.join(manifest.runtime.root, 'launcher.md'),
+    DECISION_PATH: manifest.paths.decision.path,
+    DOMAIN_PATH: manifest.paths.domain.path,
+    ARCHITECTURE_PATH: manifest.paths.architecture.path
+  };
+  const template = fs.readFileSync(ROUTER_TEMPLATE, 'utf8');
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (match, name) => {
+    if (!(name in values)) throw new Error(`router template placeholder is unknown: ${name}`);
+    return values[name];
+  });
 }
 
 function renderLauncher(manifest, selectedAgents) {
   const lines = [
-    '# Multi-Agent Launcher',
-    '',
+    '# Multi-Agent Launcher', '',
     `Generator: ${GENERATOR}`,
-    `Platform: ${manifest.platform || 'generic'}`,
-    `Stack: ${manifest.stack}`,
-    '',
-    '## Dispatch Contract',
+    `Runtime: ${manifest.runtime.root}`,
+    `Workspace: ${manifest.workspace.root}`,
+    `Platform: ${manifest.workspace.platform || 'generic'}`,
+    `Stack: ${manifest.workspace.stack}`,
     '',
-    'The orchestrator owns sequencing, scope assignment, retries, and final verification.',
-    'Each specialist receives one bounded brief and returns a structured handoff.',
-    'Load source bodies on demand; this workspace stores metadata, not an unreviewed roster copy.',
-    `Converter targets: ${(manifest.agency.converterTargets || []).join(', ') || 'none configured'}.`,
-    '',
-    '## Selected Specialists',
-    ''
+    'The installed multi-agent-workspace skill and indexer are immutable. Read',
+    'manifest.json and handoff.json from the runtime root before dispatching.',
+    '', '## Resolved document paths', ''
   ];
-  if (selectedAgents.length === 0) {
-    lines.push('- None selected. Search `roles/agency-catalog.json` and rerun the scaffold with `--agent` or `--division`.');
+  for (const zone of DOCUMENT_ZONES) {
+    const entry = manifest.paths[zone];
+    lines.push(`- ${zone}: ${entry.path} (${entry.source})`);
+  }
+  lines.push('', '## Selected Specialists', '');
+  if (!selectedAgents.length) {
+    lines.push('- None selected. Configure an agency source and rerun with --agent or --division.');
   } else {
     for (const agent of selectedAgents) {
       lines.push(`- **${agent.name}** [${agent.division}] - ${agent.description}`);
@@ -126,53 +132,148 @@ function renderLauncher(manifest, selectedAgents) {
       lines.push('  - boundary: only the files and deliverables named in the dispatch brief.');
     }
   }
-  lines.push('', '## Handoff Schema', '', 'Return `status`, `changes`, `verification`, `risks`, and `nextAction`; a failed verification is not a successful handoff.', '');
+  lines.push('', '## Handoff Schema', '', 'Return `status`, `changes`, `verification`, `risks`, and `nextAction`.', '');
   return lines.join('\n');
 }
 
-function planArtifacts(outputRoot, manifest, catalog, selectedAgents) {
-  const catalogPayload = catalog
-    ? { ...catalog, generatedBy: GENERATOR }
-    : { generatedBy: GENERATOR, status: 'unavailable', agents: [], divisions: [], reason: manifest.agency.reason };
-  const artifacts = [
-    ['manifest.json', json(manifest)],
-    ['AGENTS.md', renderRouter(manifest)],
-    ['launcher.md', renderLauncher(manifest, selectedAgents)],
-    ['roles/agency-catalog.json', json(catalogPayload)],
-    ['roles/selected-agents.json', json({ selected: selectedAgents })],
-    ['handoff.json', json({
-      schemaVersion: 1,
-      status: selectedAgents.length || manifest.agency.status !== 'available' ? 'ready' : 'selection-required',
-      generator: GENERATOR,
-      scope: { workspace: '.', root: '.harness/multi-agent', zones: ZONES },
-      selectedAgents: selectedAgents.map(agent => agent.slug),
-      verification: { catalog: manifest.agency.status, indexer: 'passed' },
-      nextAction: selectedAgents.length ? 'dispatch selected specialists with bounded briefs' : 'select specialists or configure AGENCY_AGENTS_SOURCE'
-    })],
-    ['index_memory.js', fs.readFileSync(path.join(__dirname, 'index_memory.js'))]
-  ];
-  for (const zone of ZONES) artifacts.push([`${zone}/.gitkeep`, '']);
-  return artifacts.map(([relative, content]) => ({ path: path.join(outputRoot, relative), content }));
+function listFiles(root) {
+  const files = [];
+  if (!fs.existsSync(root)) return files;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...listFiles(full));
+    else if (entry.isFile()) files.push(full);
+  }
+  return files;
 }
 
-function writeArtifacts(outputRoot, artifacts, force) {
-  for (const artifact of artifacts) {
-    if (!fs.existsSync(artifact.path)) continue;
-    const existing = fs.readFileSync(artifact.path);
-    if (!existing.equals(Buffer.isBuffer(artifact.content) ? artifact.content : Buffer.from(artifact.content)) && !force) {
-      throw new Error(`generated artifact conflict: ${path.relative(outputRoot, artifact.path)} (use --force only for Harness-owned output)`);
+function sameFile(left, right) {
+  try { return fs.readFileSync(left).equals(fs.readFileSync(right)); }
+  catch { return false; }
+}
+
+function isSamePath(left, right) {
+  const a = path.resolve(left);
+  const b = path.resolve(right);
+  return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+function migrationTargetKey(target) {
+  const resolved = path.normalize(path.resolve(target));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function generatedLegacyArtifact(file, manifest) {
+  const name = path.basename(file);
+  if (name === 'manifest.json') {
+    // The pre-#43 manifest had no schema marker, but was still Harness-owned
+    // because it lived at the reserved legacy root.
+    return manifest && (manifest.generator === GENERATOR || Object.keys(manifest).length === 0);
+  }
+  if (name === 'handoff.json') return manifest && manifest.generator === GENERATOR;
+  if (name === 'AGENTS.md') return /^# Multi-Agent Workspace Router\b/m.test(fs.readFileSync(file, 'utf8'));
+  if (name === 'launcher.md') return /^# Multi-Agent Launcher\b/m.test(fs.readFileSync(file, 'utf8'));
+  if (name === 'index_memory.js') return /^#!\/usr\/bin\/env node\b/m.test(fs.readFileSync(file, 'utf8'));
+  if (name === 'memory-index.md') return /^# Multi-Agent Memory Index\b/m.test(fs.readFileSync(file, 'utf8'));
+  return false;
+}
+
+function removeEmptyParents(start, stop) {
+  let current = start;
+  const boundary = path.resolve(stop);
+  while (path.resolve(current) !== boundary) {
+    const relative = path.relative(boundary, current);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) break;
+    try {
+      if (fs.readdirSync(current).length) break;
+      fs.rmdirSync(current);
+    } catch { break; }
+    current = path.dirname(current);
+  }
+}
+
+// Migrate authored records from the pre-#43 repository-local output only
+// after every destination conflict has been checked. Generated router,
+// launcher, indexer, and runtime files are intentionally not copied.
+function migrateLegacyWorkspace(workspaceRoot, resolution) {
+  const legacyRoot = path.join(workspaceRoot, '.harness', 'multi-agent');
+  if (!fs.existsSync(legacyRoot)) return null;
+  // The legacy root is an input boundary, not an allowed link target. A
+  // junction here could make the migration read and delete authored files
+  // outside the workspace while every lexical path still looks local.
+  assertContainedPath(workspaceRoot, legacyRoot);
+  const legacyBoundary = path.resolve(legacyRoot);
+  const copies = [];
+  const plannedTargets = new Map();
+  for (const zone of DOCUMENT_ZONES) {
+    const legacyZone = path.join(legacyRoot, zone === 'decision' ? 'decisions' : zone);
+    const destination = resolution.paths[zone].path;
+    for (const source of listFiles(legacyZone)) {
+      if (path.basename(source) === '.gitkeep') continue;
+      const relative = path.relative(legacyZone, source);
+      const target = path.join(destination, relative);
+      const containedSource = assertContainedPath(legacyRoot, source).target;
+      const containedTarget = assertContainedPath(workspaceRoot, target).target;
+      if (isSamePath(containedSource, containedTarget)) continue;
+      const targetFromLegacy = path.relative(legacyBoundary, containedTarget);
+      if (!targetFromLegacy.startsWith('..') && !path.isAbsolute(targetFromLegacy)) {
+        throw new Error(`migration destination is inside legacy workspace: ${path.relative(workspaceRoot, containedTarget).replace(/\\/g, '/')}`);
+      }
+      const targetKey = migrationTargetKey(containedTarget);
+      if (plannedTargets.has(targetKey)) {
+        throw new Error(`migration conflict: multiple legacy records target ${path.relative(workspaceRoot, containedTarget).replace(/\\/g, '/')}`);
+      }
+      plannedTargets.set(targetKey, containedSource);
+      if (fs.existsSync(containedTarget) && !sameFile(containedSource, containedTarget)) {
+        throw new Error(`migration conflict: ${path.relative(workspaceRoot, containedTarget).replace(/\\/g, '/')}`);
+      }
+      copies.push({ source: containedSource, target: containedTarget });
     }
   }
+
+  for (const copy of copies) {
+    fs.mkdirSync(path.dirname(copy.target), { recursive: true });
+    if (!fs.existsSync(copy.target)) fs.copyFileSync(copy.source, copy.target);
+  }
+
+  // Remove known generated artifacts only once migration has fully succeeded.
+  let legacyManifest = null;
+  const manifestPath = path.join(legacyRoot, 'manifest.json');
+  if (fs.existsSync(manifestPath)) {
+    try { legacyManifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { legacyManifest = null; }
+  }
+  const generated = ['manifest.json', 'AGENTS.md', 'launcher.md', 'index_memory.js', 'memory-index.md', 'handoff.json'];
+  for (const name of generated) {
+    const file = path.join(legacyRoot, name);
+    if (fs.existsSync(file) && generatedLegacyArtifact(file, legacyManifest)) fs.rmSync(file, { force: true });
+  }
+  for (const copy of copies) fs.rmSync(copy.source, { force: true });
+  for (const zone of ['roles', 'state', 'logs']) {
+    const runtimeZone = path.join(legacyRoot, zone);
+    if (fs.existsSync(runtimeZone)) fs.rmSync(runtimeZone, { recursive: true, force: true });
+  }
+  for (const zone of ['decisions', 'domain', 'architecture']) {
+    for (const marker of listFiles(path.join(legacyRoot, zone)).filter(file => path.basename(file) === '.gitkeep')) {
+      fs.rmSync(marker, { force: true });
+    }
+    removeEmptyParents(path.join(legacyRoot, zone), legacyRoot);
+  }
+  removeEmptyParents(legacyRoot, workspaceRoot);
+  return { from: legacyRoot, records: copies.length };
+}
+
+function writeRuntimeArtifacts(runtimeRoot, artifacts) {
   for (const artifact of artifacts) {
     fs.mkdirSync(path.dirname(artifact.path), { recursive: true });
-    fs.writeFileSync(artifact.path, artifact.content);
+    fs.writeFileSync(artifact.path, artifact.content, 'utf8');
   }
 }
 
-function runIndexer(outputRoot) {
-  const indexer = path.join(outputRoot, 'index_memory.js');
-  const output = path.join(outputRoot, 'memory-index.md');
-  execFileSync(process.execPath, [indexer, '--root', path.dirname(path.dirname(outputRoot)), '--output', output], { stdio: 'pipe' });
+function runIndexer(workspaceRoot, runtimeRoot) {
+  const indexer = path.join(__dirname, 'index_memory.js');
+  const manifest = path.join(runtimeRoot, 'manifest.json');
+  const output = path.join(runtimeRoot, 'memory-index.md');
+  execFileSync(process.execPath, [indexer, '--workspace', workspaceRoot, '--manifest', manifest, '--output', output], { stdio: 'pipe' });
   return output;
 }
 
@@ -180,44 +281,90 @@ function scaffold(options) {
   if (!fs.existsSync(options.workspace) || !fs.statSync(options.workspace).isDirectory()) {
     throw new Error(`workspace not found: ${options.workspace}`);
   }
-  const outputRoot = path.join(options.workspace, '.harness', 'multi-agent');
-  const existing = readExistingManifest(outputRoot);
-  if (existing && existing.generator !== GENERATOR) throw new Error('existing .harness/multi-agent belongs to another generator');
+  const resolution = ensureCommittableFallback(resolveProjectDocs(options.workspace));
+  const runtimeRoot = resolution.runtimeRoot;
+  const existing = readExistingManifest(runtimeRoot);
+  if (existing && existing.generator !== GENERATOR) throw new Error('existing Harness runtime belongs to another generator');
+
   const catalog = options.source ? readAgencyCatalog(options.source) : null;
   if (options.expectedRevision && (!catalog || catalog.source.revision !== options.expectedRevision)) {
     throw new Error(`agency source revision mismatch: expected ${options.expectedRevision}, got ${catalog && catalog.source.revision || '(unknown)'}`);
   }
-  if (existing && existing.agency && existing.agency.sourceRevision && (!catalog || existing.agency.sourceRevision !== catalog.source.revision) && !options.allowSourceDrift) {
+  if (existing && existing.agency && existing.agency.sourceRevision &&
+      (!catalog || existing.agency.sourceRevision !== catalog.source.revision) && !options.allowSourceDrift) {
     throw new Error(`agency source revision drift: existing ${existing.agency.sourceRevision}, current ${catalog && catalog.source.revision || '(unavailable)'}; pass --allow-source-drift to refresh`);
   }
-  const selection = catalog ? resolveSelection(catalog, options.divisions, options.agents, options.allAgents) : { divisionIds: [], agents: [] };
+  const selection = catalog
+    ? resolveSelection(catalog, options.divisions, options.agents, options.allAgents)
+    : { divisionIds: [], agents: [] };
   if (!catalog && (options.divisions.length || options.agents.length || options.allAgents)) {
     throw new Error('cannot select agency agents without --agency-source or AGENCY_AGENTS_SOURCE');
   }
+  const migration = migrateLegacyWorkspace(options.workspace, resolution);
+  for (const zone of DOCUMENT_ZONES) fs.mkdirSync(resolution.paths[zone].path, { recursive: true });
   const agency = catalog
     ? { status: 'available', ...catalog.source, selectedCount: selection.agents.length, selectionRequired: selection.agents.length === 0 }
     : { status: 'unavailable', reason: 'No agency source configured', requiredConfiguration: '--agency-source <path> or AGENCY_AGENTS_SOURCE', selectedCount: 0, selectionRequired: false };
+  const generatedAt = new Date().toISOString();
   const manifest = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     generator: GENERATOR,
-    workspaceRevision: gitRevision(options.workspace),
-    stack: detectStack(options.workspace),
-    platform: options.platform,
-    zones: ZONES,
+    workspace: {
+      root: resolution.workspaceRoot,
+      key: resolution.workspaceKey,
+      revision: gitRevision(options.workspace),
+      stack: detectStack(options.workspace),
+      platform: options.platform
+    },
+    runtime: {
+      root: runtimeRoot,
+      state: resolution.runtime.state,
+      logs: resolution.runtime.logs,
+      roles: resolution.runtime.roles,
+      manifest: path.join(runtimeRoot, 'manifest.json'),
+      handoff: path.join(runtimeRoot, 'handoff.json')
+    },
+    paths: resolution.paths,
+    zones: ALL_ZONES,
+    documentationZones: DOCUMENT_ZONES,
     supportedPlatforms: SUPPORTED_PLATFORMS,
     agency,
     selectedDivisions: selection.divisionIds,
     selectedAgents: selection.agents,
-    artifactPaths: ['AGENTS.md', 'launcher.md', 'index_memory.js', 'memory-index.md', 'manifest.json', 'handoff.json']
+    execution: { generatedAt, resolver: 'project-docs-resolver', migration },
+    artifactPaths: ['AGENTS.md', 'manifest.json', 'handoff.json', 'memory-index.md', 'launcher.md', 'roles/']
   };
-  const artifacts = planArtifacts(outputRoot, manifest, catalog, selection.agents);
-  writeArtifacts(outputRoot, artifacts, options.force || options.allowSourceDrift);
-  const memoryIndex = runIndexer(outputRoot);
-  const handoffPath = path.join(outputRoot, 'handoff.json');
-  const handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+  const catalogPayload = catalog
+    ? { ...catalog, generatedBy: GENERATOR }
+    : { generatedBy: GENERATOR, status: 'unavailable', agents: [], divisions: [], reason: agency.reason };
+  const handoff = {
+    schemaVersion: 2,
+    status: selection.agents.length || agency.status !== 'available' ? 'ready' : 'selection-required',
+    generator: GENERATOR,
+    workspace: resolution.workspaceRoot,
+    runtimeRoot,
+    paths: resolution.paths,
+    selectedAgents: selection.agents.map(agent => agent.slug),
+    changes: [],
+    execution: { generatedAt, workspaceRevision: manifest.workspace.revision },
+    verification: { catalog: agency.status, indexer: 'pending' },
+    risks: [],
+    nextAction: selection.agents.length ? 'dispatch selected specialists with bounded briefs' : 'select specialists or configure AGENCY_AGENTS_SOURCE'
+  };
+  const artifacts = [
+    { path: path.join(runtimeRoot, 'AGENTS.md'), content: renderRouter(manifest) },
+    { path: path.join(runtimeRoot, 'manifest.json'), content: json(manifest) },
+    { path: path.join(runtimeRoot, 'handoff.json'), content: json(handoff) },
+    { path: path.join(runtimeRoot, 'launcher.md'), content: renderLauncher(manifest, selection.agents) },
+    { path: path.join(runtimeRoot, 'roles', 'agency-catalog.json'), content: json(catalogPayload) },
+    { path: path.join(runtimeRoot, 'roles', 'selected-agents.json'), content: json({ selected: selection.agents }) }
+  ];
+  for (const zone of RUNTIME_ZONES) fs.mkdirSync(path.join(runtimeRoot, zone), { recursive: true });
+  writeRuntimeArtifacts(runtimeRoot, artifacts);
+  const memoryIndex = runIndexer(options.workspace, runtimeRoot);
   handoff.verification.indexer = 'passed';
-  fs.writeFileSync(handoffPath, json(handoff));
-  return { outputRoot, manifest, memoryIndex };
+  fs.writeFileSync(path.join(runtimeRoot, 'handoff.json'), json(handoff), 'utf8');
+  return { runtimeRoot, manifest, memoryIndex, resolution, migration };
 }
 
 function usage() {
@@ -229,7 +376,7 @@ function usage() {
     '  --all-agents                 Explicitly select the complete metadata catalog',
     '  --platform <name>            Validate a supported converter target',
     '  --allow-source-drift         Accept a different source revision on refresh',
-    '  --force                      Overwrite only existing Harness-owned artifacts'
+    '  --force                      Retained for compatibility; runtime files are Harness-owned'
   ].join('\n');
 }
 
@@ -238,8 +385,8 @@ function main() {
     const options = parseArgs(process.argv.slice(2));
     if (options.help) return console.log(usage());
     const result = scaffold(options);
-    console.log(`Multi-agent workspace written to ${result.outputRoot}`);
-    console.log(`  Zones: ${result.manifest.zones.length}`);
+    console.log(`Multi-agent runtime written to ${result.runtimeRoot}`);
+    console.log(`  Documentation zones: ${result.manifest.documentationZones.length}`);
     console.log(`  Agency: ${result.manifest.agency.status}`);
     console.log(`  Selected agents: ${result.manifest.selectedAgents.length}`);
     console.log(`  Memory index: ${result.memoryIndex}`);
@@ -250,4 +397,12 @@ function main() {
 }
 
 if (require.main === module) main();
-module.exports = { GENERATOR, ZONES, parseArgs, scaffold, usage };
+module.exports = {
+  GENERATOR,
+  ZONES: ALL_ZONES,
+  DOCUMENT_ZONES,
+  parseArgs,
+  migrateLegacyWorkspace,
+  scaffold,
+  usage
+};

package/multi-agent-workspace/templates/AGENTS.md

@@ -0,0 +1,20 @@
+# Multi-Agent Workspace Router
+
+This router is resolved from the installed `multi-agent-workspace` skill. Sub-agents MUST NOT modify it.
+
+## Bootstrap Protocol
+
+1. Read the task payload, then `{{RUNTIME_STATE}}`.
+2. Read only the relevant document records:
+   - decision records at `{{DECISION_PATH}}`
+   - domain records at `{{DOMAIN_PATH}}`
+   - architecture records at `{{ARCHITECTURE_PATH}}`
+3. Read `{{LAUNCHER}}` and the selected roles before delegating.
+4. Return a structured handoff with changed files and verification evidence.
+
+## Boundaries
+
+- Write working state to `{{RUNTIME_STATE}}`; keep raw output in `{{RUNTIME_LOGS}}`.
+- Treat `{{ARCHITECTURE_PATH}}` and this router as immutable contracts.
+- Delegate only the scope named in the launcher; never preload the external roster.
+- If a specialist fails, report the failure and use a bounded fallback or human escalation.

package/multi-agent-workspace/workflows/03-generation.md

@@ -10,18 +10,16 @@
 2. Semantic Integrity: For Smart Merge, align updates with logical consistency, memory management, and verification guardrails while preserving original YAML frontmatter.
 
 ## [Action Phase: Generation]
-3. Template Iteration: Process selected agents iteratively to manage context usage:
-   - Read the corresponding template for each chosen role.
-   - If merging into an existing file, read the target file first to preserve custom configuration.
-   - Inject cognitive guardrails: role boundaries, shared memory references (`memory-keeper`), and outcome verification guidelines.
-   - Align generated prompts with target platform capabilities (e.g. VS Code Copilot, Cursor, Claude Code) and appropriate task-tracking frameworks.
-   - Substitute placeholders using the `Context Profile`. If a placeholder remains unresolved, insert a clear comment tag (e.g. `// TODO: Manual configuration needed`).
-   - Save generated files to paths defined in `guidelines/platform-<platform>.md`.
-4. Orchestrator Generation: Consult `guidelines/platform-<platform>.md` for Orchestrator requirements and update central prompts if necessary.
+3. Run `node multi-agent-workspace/scripts/scaffold.js --workspace <root>` with the selected source, divisions, agents, and platform.
+   - Resolve document zones through the shared resolver; preserve the provenance of explicit, inferred, and fallback paths.
+   - Migrate authored decision, domain, and architecture records only after checking every destination conflict.
+   - Keep runtime metadata, roles, state, logs, and memory indexes under the global workspace-keyed state root.
+   - Resolve the router template and indexer from the installed skill directory; render the router into the global runtime, never into the repository.
+4. If the source is unavailable, retain the explicit unavailable-catalog status and do not claim a complete roster.
 
 ## [Summarize & Verification Phase]
-5. Integrity Check: Verify generated files exist on disk before reporting completion.
+5. Integrity Check: Verify the global manifest, handoff, launcher, selected roles, memory index, and resolved document paths before reporting completion.
 
 ## [Record: Exit]
 6. Completion: Record successful subagent scaffolding.
-7. Handoff: Load and execute `workflows/04-launcher.md`, passing the `Context Profile`, `Selected Agents`, and newly created file paths.
+7. Handoff: Load and execute `workflows/04-launcher.md`, passing the `Context Profile`, `Selected Agents`, and newly created file paths.

package/multi-agent-workspace/workflows/04-launcher.md

@@ -4,13 +4,13 @@
 - Verify inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and newly created file paths from Phase 3.
 
 ## [Action Phase: Entry Point Generation]
-1. Entry Point Generation: Read `templates/agent-launcher.md`.
-2. Handoff Integration: Substitute placeholders using the `Context Profile`. Dynamically inject the paths and roles of `Selected Agents` into the Launcher so it serves as an effective central router.
-3. Disk Write: Save the launcher entry point to the path specified in platform guidelines.
+1. Entry Point Generation: Read the installed multi-agent-workspace skill and the runtime `manifest.json`/`handoff.json`.
+2. Handoff Integration: Use the resolved decision, domain, and architecture paths plus the selected roles from the manifest when dispatching bounded briefs.
+3. Disk Write: Update the global runtime launcher and resolved router generated by `scaffold.js`; repository-local router and executable copies are not created.
 
 ## [Summarize: Verification]
-4. Check: Verify the Launcher was created successfully on disk.
+4. Check: Verify the runtime launcher, handoff schema, memory index, and selected-role metadata are readable from the global runtime root.
 
 ## [Record: Exit]
 5. Completion: Present a clean summary table listing generated agent files and their configured roles.
-6. UX Handoff: Provide the user with guidance on how to trigger or invoke their new agent scaffold.
+6. UX Handoff: Provide the user with guidance on how to trigger or invoke their new agent scaffold.