harness-everything 0.3.6 → 0.4.0

package/multi-agent-workspace/scripts/consume-workflow-plan.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  derivePlanId,
+  getWorkspaceKey,
+  getWorkspaceStateRoot,
+  validateRouterPlan,
+} = require('../../fable-mode/scripts/workflow-plan-consumer');
+
+function canonicalPath(value) {
+  const resolved = path.resolve(value || process.cwd());
+  try { return fs.realpathSync(resolved); } catch (_) { return resolved; }
+}
+
+function sanitizeRunId(value) {
+  const text = String(value || `run-${crypto.randomUUID()}`).trim();
+  if (!/^[A-Za-z0-9._-]+$/.test(text)) throw new Error(`runId contains unsupported characters: ${text}`);
+  return text.slice(0, 128);
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function consumeWorkspacePlan({ routerContract, workspaceRoot, runId }) {
+  const plan = validateRouterPlan(routerContract);
+  if (plan.strategy !== 'fable-multi-agent-workspace' || !plan.workspace || plan.workspace.required !== true) {
+    throw new Error(`workspace consumer requires fable-multi-agent-workspace with workspace.required=true; received ${plan.strategy}`);
+  }
+
+  const root = canonicalPath(workspaceRoot || process.cwd());
+  const handoffPath = path.join(root, '.ai', 'handoff.json');
+  if (!fs.existsSync(handoffPath)) {
+    throw new Error('workspace handoff does not exist; run multi-agent-workspace/scripts/scaffold.js first');
+  }
+
+  let handoff;
+  try {
+    handoff = JSON.parse(fs.readFileSync(handoffPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`workspace handoff is invalid JSON: ${err.message}`);
+  }
+
+  if (!Array.isArray(handoff.selectedAgents) || typeof handoff.memoryIndex !== 'string') {
+    throw new Error('workspace handoff is missing existing selectedAgents/memoryIndex contract fields');
+  }
+
+  const resolvedRunId = sanitizeRunId(runId);
+  const planId = derivePlanId(routerContract);
+  const correlation = {
+    schemaVersion: 1,
+    planId,
+    runId: resolvedRunId,
+    strategy: plan.strategy,
+    workspace: plan.workspace,
+    memory: plan.memory,
+    rolePolicy: 'existing-workspace-selection',
+    updatedAt: new Date().toISOString(),
+  };
+
+  // Preserve the existing handoff contract and role/memory ownership. The
+  // workflow consumer only adds correlation and the router-owned slices.
+  const nextHandoff = {
+    ...handoff,
+    workflowCorrelation: correlation,
+  };
+  atomicWriteJson(handoffPath, nextHandoff);
+
+  const workspaceStateDir = path.dirname(getWorkspaceStateRoot(root));
+  atomicWriteJson(path.join(workspaceStateDir, 'multi-agent-workspace-runs', `${resolvedRunId}.json`), {
+    ...correlation,
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    handoffPath,
+    selectedAgents: handoff.selectedAgents.map(agent => ({ id: agent.id, provider: agent.provider, source: agent.source })),
+    memoryIndex: handoff.memoryIndex,
+  });
+
+  return nextHandoff;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--plan-file') args.planFile = argv[++i];
+    else if (token === '--root') args.root = argv[++i];
+    else if (token === '--run-id') args.runId = argv[++i];
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`unknown argument: ${token}`);
+  }
+  return args;
+}
+
+function usage() {
+  return 'Usage: node multi-agent-workspace/scripts/consume-workflow-plan.js --plan-file <router-contract.json> [--root <workspace>] [--run-id <id>]';
+}
+
+if (require.main === module) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (!args.planFile) throw new Error(usage());
+    const routerContract = JSON.parse(fs.readFileSync(path.resolve(args.planFile), 'utf8'));
+    const handoff = consumeWorkspacePlan({
+      routerContract,
+      workspaceRoot: args.root || process.cwd(),
+      runId: args.runId,
+    });
+    process.stdout.write(`${JSON.stringify(handoff)}\n`);
+  } catch (err) {
+    console.error(`[WORKSPACE PLAN CONSUMER] ${err.message}`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  consumeWorkspacePlan,
+};

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

@@ -3,49 +3,102 @@
 
 const fs = require('fs');
 const path = require('path');
+const { getWorkspaceRoot, getRuntimeRoot, resolveProjectDocs } = require('./project-docs-resolver');
 
-const ZONES = Object.freeze(['state', 'logs', 'decisions', 'domain', 'architecture', 'roles']);
+function option(args, ...names) {
+  for (const name of names) {
+    const index = args.indexOf(name);
+    if (index !== -1) return args[index + 1];
+  }
+  return undefined;
+}
+
+function manifestFromArgs(args) {
+  const workspace = path.resolve(option(args, '--workspace', '--root') || getWorkspaceRoot());
+  const manifestPath = path.resolve(option(args, '--manifest') || path.join(getRuntimeRoot(workspace), 'manifest.json'));
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`manifest not found: ${manifestPath}; pass --workspace or --manifest explicitly`);
+  }
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); }
+  catch (error) { throw new Error(`invalid manifest: ${error.message}`); }
+  return { workspace, manifestPath, manifest };
+}
 
-function option(args, name) {
-  const index = args.indexOf(name);
-  return index === -1 ? undefined : args[index + 1];
+function linkPath(workspace, absolute) {
+  const relative = path.relative(workspace, absolute).replace(/\\/g, '/');
+  return relative && !relative.startsWith('../') ? relative : path.resolve(absolute).replace(/\\/g, '/');
 }
 
-function buildIndex(root) {
-  const base = path.join(root, '.harness', 'multi-agent');
-  const manifestPath = path.join(base, 'manifest.json');
-  let manifest = {};
-  if (fs.existsSync(manifestPath)) manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+function linkTarget(workspace, absolute) {
+  const relative = path.relative(workspace, absolute).replace(/\\/g, '/');
+  if (relative && !relative.startsWith('../')) return relative;
+  const normalized = path.resolve(absolute).replace(/\\/g, '/');
+  return encodeURI(`file://${normalized.startsWith('/') ? '' : '/'}${normalized}`);
+}
+
+function buildIndex(input) {
+  // Keep the old string form for consumers that imported buildIndex directly;
+  // path resolution still comes from an explicit workspace, never output depth.
+  const args = typeof input === 'string' ? ['--workspace', input] : (Array.isArray(input) ? input : null);
+  const resolved = args ? manifestFromArgs(args) : {
+    workspace: path.resolve(input.workspace || getWorkspaceRoot()),
+    manifestPath: path.resolve(input.manifest),
+    manifest: input.manifestData || JSON.parse(fs.readFileSync(path.resolve(input.manifest), 'utf8'))
+  };
+  const { workspace, manifest } = resolved;
   const selected = Array.isArray(manifest.selectedAgents) ? manifest.selectedAgents : [];
+  const paths = manifest.paths || resolveProjectDocs(workspace).paths;
   const lines = [
-    '# Multi-Agent Memory Index',
-    '',
-    'This index is generated from the local multi-agent manifest. Read linked records on demand.',
-    '',
-    '## Zones',
-    ''
+    '# Multi-Agent Memory Index', '',
+    'This index is generated from the global multi-agent runtime manifest. Read linked records on demand.',
+    '', '## Runtime', '',
+    `- Root: \`${manifest.runtimeRoot || (manifest.runtime && manifest.runtime.root) || ''}\``,
+    `- Manifest: \`${resolved.manifestPath}\``,
+    '', '## Document paths', ''
   ];
-  for (const zone of ZONES) lines.push(`- [${zone}](${zone}/)`);
+  for (const zone of ['decision', 'domain', 'architecture']) {
+    const entry = paths[zone];
+    if (entry) lines.push(`- **${zone}**: [${linkPath(workspace, entry.path)}](${linkTarget(workspace, entry.path)}) (${entry.source})`);
+  }
   lines.push('', '## Selected specialists', '');
-  if (selected.length === 0) {
+  if (!selected.length) {
     lines.push('- None selected. Do not claim that the external roster is complete.');
   } else {
     for (const agent of selected) {
-      lines.push(`- **${agent.name}** (${agent.division}) - \`${agent.slug}\``);
+      if (typeof agent === 'string') lines.push(`- \`${agent}\``);
+      else lines.push(`- **${agent.name}** (${agent.division}) - \`${agent.slug}\``);
     }
   }
-  lines.push('', '## Handoff', '', '- [Structured handoff](handoff.json)', '- [Launcher](launcher.md)');
+  lines.push('', '## Handoff', '', `- [Structured handoff](${linkTarget(workspace, path.join(path.dirname(resolved.manifestPath), 'handoff.json'))})`, `- [Launcher](${linkTarget(workspace, path.join(path.dirname(resolved.manifestPath), 'launcher.md'))})`);
   return `${lines.join('\n')}\n`;
 }
 
+function parseArgs(args) {
+  const workspace = option(args, '--workspace', '--root');
+  const manifest = option(args, '--manifest');
+  const output = option(args, '--output');
+  if (!output) throw new Error('--output requires a path; output location is never inferred from its depth');
+  return { workspace, manifest, output: path.resolve(output) };
+}
+
 function main() {
-  const args = process.argv.slice(2);
-  const root = path.resolve(option(args, '--root') || '.');
-  const output = path.resolve(option(args, '--output') || path.join(root, '.harness', 'multi-agent', 'memory-index.md'));
-  fs.mkdirSync(path.dirname(output), { recursive: true });
-  fs.writeFileSync(output, buildIndex(root), 'utf8');
-  console.log(`Memory index written to ${output}`);
+  try {
+    const args = process.argv.slice(2);
+    const options = parseArgs(args);
+    const result = manifestFromArgs(args);
+    fs.mkdirSync(path.dirname(options.output), { recursive: true });
+    fs.writeFileSync(options.output, buildIndex({
+      workspace: result.workspace,
+      manifest: result.manifestPath,
+      manifestData: result.manifest
+    }), 'utf8');
+    console.log(`Memory index written to ${options.output}`);
+  } catch (error) {
+    console.error(`ERROR: ${error.message}`);
+    process.exitCode = 1;
+  }
 }
 
 if (require.main === module) main();
-module.exports = { ZONES, buildIndex };
+module.exports = { buildIndex, parseArgs, manifestFromArgs };

package/multi-agent-workspace/scripts/path-boundary.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function canonicalizePath(value) {
+  let current = path.resolve(value);
+  const missing = [];
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    missing.unshift(path.basename(current));
+    current = parent;
+  }
+  let existing = current;
+  try { existing = fs.realpathSync.native ? fs.realpathSync.native(current) : fs.realpathSync(current); }
+  catch { /* retain the nearest existing lexical ancestor */ }
+  return path.join(existing, ...missing);
+}
+
+function isWithin(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function assertNoLinkComponents(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return;
+  let current = path.resolve(root);
+  for (const component of relative ? relative.split(path.sep) : []) {
+    current = path.join(current, component);
+    let stat;
+    try { stat = fs.lstatSync(current); } catch { continue; }
+    if (stat.isSymbolicLink()) {
+      const error = new Error(`path contains a link component inside boundary: ${current}`);
+      error.code = 'LINK_COMPONENT_IN_BOUNDARY';
+      throw error;
+    }
+  }
+}
+
+function assertContainedPath(root, target) {
+  if (typeof root !== 'string' || typeof target !== 'string') {
+    const error = new TypeError('path boundary requires string root and target');
+    error.code = 'INVALID_BOUNDARY_PATH';
+    throw error;
+  }
+  assertNoLinkComponents(root, target);
+  const canonicalRoot = canonicalizePath(root);
+  const canonicalTarget = canonicalizePath(target);
+  if (!isWithin(canonicalRoot, canonicalTarget)) {
+    const error = new Error(`path escapes boundary: ${target}`);
+    error.code = 'PATH_OUTSIDE_BOUNDARY';
+    throw error;
+  }
+  return { root: canonicalRoot, target: canonicalTarget };
+}
+
+module.exports = { assertContainedPath };

package/multi-agent-workspace/scripts/project-docs-resolver.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+'use strict';
+
+// The resolver is deliberately self-contained.  multi-agent-workspace is
+// copied as a standalone skill, so it cannot depend on the package's source
+// tree or on another installed skill at runtime.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+
+const ZONES = Object.freeze(['decision', 'domain', 'architecture']);
+const PLATFORM_HOMES = Object.freeze(['.claude', '.cursor', '.github', '.codex', '.continue']);
+const PROJECT_DOC_FIELDS = Object.freeze({
+  decision: ['decisionLocation', 'decisions', 'adrLocation', 'adr'],
+  domain: ['domainLocation', 'domains', 'contextLocation', 'contexts', 'domain'],
+  architecture: ['architectureLocation', 'architectures', 'architecture']
+});
+const UNBOUND_WORKSPACE_KEY = 'unbound-workspace';
+
+function getWorkspaceRoot(start, allowNonGit = false) {
+  const candidate = typeof start === 'string' && start.trim() ? start : process.cwd();
+  let dir = path.resolve(candidate);
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return allowNonGit && typeof start === 'string' && start.trim() ? path.resolve(start) : null;
+}
+
+function getStateHome() {
+  return process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+}
+
+function getWorkspaceKey(workspaceRoot) {
+  const root = workspaceRoot || getWorkspaceRoot();
+  if (!root) return UNBOUND_WORKSPACE_KEY;
+  const absolute = path.resolve(root);
+  let real = absolute;
+  try { real = fs.realpathSync(absolute); } catch { /* the caller may be creating it */ }
+  const slug = path.basename(real).toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return `${slug}-${hash}`;
+}
+
+function getRuntimeRoot(workspaceRoot) {
+  return path.join(getStateHome(), 'workspaces', getWorkspaceKey(workspaceRoot), 'multi-agent');
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function getRepoManifestHomes(workspaceRoot) {
+  return PLATFORM_HOMES.map(home => path.join(workspaceRoot, home));
+}
+
+function readProjectDocs(workspaceRoot) {
+  const manifests = [];
+  for (const home of getRepoManifestHomes(workspaceRoot)) {
+    const file = path.join(home, 'harness-everything', 'manifest.json');
+    if (!fs.existsSync(file)) continue;
+    const data = readJson(file);
+    if (data && data.projectDocs && typeof data.projectDocs === 'object') {
+      manifests.push({ file, projectDocs: data.projectDocs });
+    }
+  }
+  const complete = manifests.find(entry =>
+    ['docLocation', 'tracker', 'issueDefinition'].every(field => String(entry.projectDocs[field] || '').trim())
+  );
+  return complete || manifests[0] || null;
+}
+
+function cleanConfiguredPath(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  return trimmed.replace(/[\\/]$/, '');
+}
+
+function resolvePath(workspaceRoot, value) {
+  const cleaned = cleanConfiguredPath(value);
+  if (!cleaned) return null;
+  return path.resolve(workspaceRoot, cleaned);
+}
+
+function pathIsFile(file) {
+  try { return fs.statSync(file).isFile(); } catch { return false; }
+}
+
+function pathIsDir(dir) {
+  try { return fs.statSync(dir).isDirectory(); } catch { return false; }
+}
+
+function parseContextMap(workspaceRoot, configuredMap) {
+  const candidates = [];
+  candidates.push(path.join(workspaceRoot, 'CONTEXT-MAP.md'));
+  const explicit = resolvePath(workspaceRoot, configuredMap);
+  if (explicit) candidates.push(explicit);
+  const mapPath = candidates.find(pathIsFile);
+  if (!mapPath) return null;
+
+  const raw = fs.readFileSync(mapPath, 'utf8');
+  const links = [];
+  const pattern = /\[[^\]]+\]\(([^)]+)\)/g;
+  let match;
+  while ((match = pattern.exec(raw))) {
+    const target = match[1].split('#')[0].trim();
+    if (!target || target.startsWith('http:') || target.startsWith('https:')) continue;
+    const absolute = path.resolve(path.dirname(mapPath), target);
+    if (/context\.md$/i.test(target) || /(?:context|domain)/i.test(target)) links.push(absolute);
+  }
+  const existing = links.filter(pathIsFile);
+  const domainDirs = existing.map(file => path.dirname(file));
+  const resolvedPath = domainDirs.length ? commonPath(domainDirs) : path.dirname(mapPath);
+  return { path: mapPath, domainDirs, resolvedPath, links: existing };
+}
+
+function commonPath(paths) {
+  if (!paths.length) return null;
+  const resolved = paths.map(item => path.resolve(item));
+  const parts = resolved.map(item => comparisonPath(item).split(path.sep));
+  const common = [];
+  for (let i = 0; i < parts[0].length; i++) {
+    if (parts.every(candidate => candidate[i] === parts[0][i])) common.push(parts[0][i]);
+    else break;
+  }
+  if (!common.length) return path.dirname(resolved[0]);
+  const selected = resolved[0].split(path.sep).slice(0, common.length).join(path.sep);
+  return selected || path.parse(resolved[0]).root;
+}
+
+function configuredZonePath(workspaceRoot, projectDocs, zone) {
+  for (const key of PROJECT_DOC_FIELDS[zone]) {
+    const configured = resolvePath(workspaceRoot, projectDocs && projectDocs[key]);
+    if (configured) return { path: configured, source: 'projectDocs', resolution: 'explicit', field: key };
+  }
+  return null;
+}
+
+function configuredBasePath(workspaceRoot, projectDocs, zone) {
+  const docLocation = resolvePath(workspaceRoot, projectDocs && projectDocs.docLocation);
+  if (!docLocation) return null;
+  const configuredBase = pathIsFile(docLocation) ? path.dirname(docLocation) : docLocation;
+  const names = {
+    decision: ['adr', 'decisions'],
+    domain: ['domain', 'contexts'],
+    architecture: ['architecture']
+  }[zone];
+  const baseName = path.basename(configuredBase).toLowerCase();
+  if (names.includes(baseName)) return configuredBase;
+  return path.join(configuredBase, names[0]);
+}
+
+function inferredZonePath(workspaceRoot, projectDocs, zone) {
+  const configured = configuredBasePath(workspaceRoot, projectDocs, zone);
+  if (configured) return { path: configured, source: 'projectDocs', resolution: 'inferred' };
+  const candidates = {
+    decision: ['docs/adr', 'docs/decisions', 'adr', 'decisions'],
+    domain: ['docs/domain', 'docs/contexts', 'domain', 'contexts'],
+    architecture: ['docs/architecture', 'architecture']
+  }[zone].map(candidate => path.join(workspaceRoot, candidate));
+  const existing = candidates.find(pathIsDir);
+  if (existing) {
+    return { path: existing, source: 'inference', resolution: 'inferred' };
+  }
+  // An existing docs/doc root is itself a repository convention. Create the
+  // zone below it lazily while retaining provenance distinct from fallback.
+  for (const base of ['docs', 'doc']) {
+    if (pathIsDir(path.join(workspaceRoot, base))) {
+      const names = { decision: 'adr', domain: 'domain', architecture: 'architecture' };
+      return { path: path.join(workspaceRoot, base, names[zone]), source: 'inference', resolution: 'inferred' };
+    }
+  }
+  return null;
+}
+
+function fallbackZonePath(workspaceRoot, zone) {
+  return path.join(workspaceRoot, {
+    decision: 'docs/adr',
+    domain: 'docs/domain',
+    architecture: 'docs/architecture'
+  }[zone]);
+}
+
+function relativePath(workspaceRoot, absolute) {
+  const relative = path.relative(workspaceRoot, absolute).replace(/\\/g, '/');
+  return relative || '.';
+}
+
+function realPathWithMissingSegments(value) {
+  let current = path.resolve(value);
+  const missing = [];
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    missing.unshift(path.basename(current));
+    current = parent;
+  }
+  let existing;
+  try {
+    existing = fs.realpathSync.native ? fs.realpathSync.native(current) : fs.realpathSync(current);
+  } catch {
+    existing = current;
+  }
+  return path.join(existing, ...missing);
+}
+
+function comparisonPath(value) {
+  const normalized = path.normalize(value);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function isWithinWorkspace(workspaceRoot, absolute) {
+  const realWorkspaceRoot = comparisonPath(realPathWithMissingSegments(workspaceRoot));
+  const realTarget = comparisonPath(realPathWithMissingSegments(absolute));
+  const relative = path.relative(realWorkspaceRoot, realTarget);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function resolveProjectDocs(workspaceRoot, options = {}) {
+  const resolvedRoot = workspaceRoot || getWorkspaceRoot();
+  if (!resolvedRoot) throw new Error('cannot resolve project docs outside a git workspace; pass --workspace <path> explicitly');
+  const root = path.resolve(resolvedRoot);
+  const manifest = readProjectDocs(root);
+  const projectDocs = manifest ? manifest.projectDocs : {};
+  const contextMap = parseContextMap(root, projectDocs.contextMap || projectDocs.contextMapPath);
+  const paths = {};
+
+  for (const zone of ZONES) {
+    const explicit = configuredZonePath(root, projectDocs, zone);
+    const inferred = contextMap
+      ? { path: contextMap.resolvedPath, source: 'context-map', resolution: 'explicit', mapPath: contextMap.path }
+      : (explicit ? null : inferredZonePath(root, projectDocs, zone));
+    const selected = inferred || explicit || {
+      path: fallbackZonePath(root, zone),
+      source: 'fallback',
+      resolution: 'fallback'
+    };
+    if (!isWithinWorkspace(root, selected.path)) {
+      throw new Error(`resolved ${zone} path must stay inside workspace: ${selected.path}`);
+    }
+    paths[zone] = {
+      path: path.resolve(selected.path),
+      relativePath: relativePath(root, selected.path),
+      source: selected.source,
+      resolution: selected.resolution || selected.source,
+      origin: selected.source,
+      ...(selected.field ? { field: selected.field } : {}),
+      ...(selected.mapPath ? { mapPath: selected.mapPath } : {}),
+      ...(contextMap ? { contextMap: contextMap.path, contextPaths: contextMap.links } : {})
+    };
+  }
+
+  const runtimeRoot = options.runtimeRoot ? path.resolve(options.runtimeRoot) : getRuntimeRoot(root);
+  return {
+    workspaceRoot: root,
+    workspaceKey: getWorkspaceKey(root),
+    stateHome: getStateHome(),
+    runtimeRoot,
+    runtime: {
+      root: runtimeRoot,
+      state: path.join(runtimeRoot, 'state'),
+      logs: path.join(runtimeRoot, 'logs'),
+      roles: path.join(runtimeRoot, 'roles')
+    },
+    projectDocs: manifest ? { ...projectDocs, manifestPath: manifest.file } : null,
+    contextMap: contextMap ? { path: contextMap.path, links: contextMap.links } : null,
+    paths,
+    // Plural aliases make the contract readable to callers that treat these
+    // as zones, while the singular keys match the project-docs vocabulary.
+    decisions: paths.decision,
+    domains: paths.domain,
+    architectures: paths.architecture
+  };
+}
+
+function detectProjectDocsConventions(workspaceRoot) {
+  const resolvedRoot = workspaceRoot || getWorkspaceRoot();
+  if (!resolvedRoot) return {};
+  const root = path.resolve(resolvedRoot);
+  const configured = readProjectDocs(root);
+  const inferred = {};
+  if (configured && configured.projectDocs && configured.projectDocs.docLocation) {
+    inferred.docLocation = configured.projectDocs.docLocation;
+  }
+  if (!inferred.docLocation) {
+    for (const dir of ['docs/roadmaps', 'docs/reference', 'docs/specs', 'docs', 'doc']) {
+      if (pathIsDir(path.join(root, dir))) {
+        inferred.docLocation = `${dir}/`;
+        break;
+      }
+    }
+  }
+  if (pathIsDir(path.join(root, '.github', 'ISSUE_TEMPLATE'))) {
+    inferred.tracker = 'GitHub Issues via .github/ISSUE_TEMPLATE/';
+  } else if (pathIsDir(path.join(root, 'docs', 'roadmaps'))) {
+    inferred.tracker = 'docs/roadmaps/ local markdown tickets';
+  } else if (pathIsDir(path.join(root, 'tasks', 'tickets'))) {
+    inferred.tracker = 'tasks/tickets/ local markdown tickets';
+  } else if (pathIsDir(path.join(root, '.scratch'))) {
+    inferred.tracker = '.scratch/ local markdown workspace';
+  } else if (inferred.docLocation) {
+    inferred.tracker = `${inferred.docLocation}tickets/ local markdown tickets`;
+  }
+  if (inferred.tracker && inferred.tracker.includes('ISSUE_TEMPLATE')) {
+    inferred.issueDefinition = '.github/ISSUE_TEMPLATE/ template structure';
+  } else if (inferred.tracker) {
+    inferred.issueDefinition = 'Title + acceptance criteria + Status: ready-for-agent';
+  }
+  return inferred;
+}
+
+function isIgnored(workspaceRoot, target) {
+  try {
+    execFileSync('git', ['-C', workspaceRoot, 'check-ignore', '--quiet', '--no-index', target], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function ensureCommittableFallback(resolution) {
+  for (const zone of ZONES) {
+    const entry = resolution.paths[zone];
+    if (entry.resolution === 'fallback' && isIgnored(resolution.workspaceRoot, entry.relativePath)) {
+      throw new Error(`fallback ${zone} path is ignored and cannot be committed: ${entry.relativePath}`);
+    }
+  }
+  return resolution;
+}
+
+module.exports = {
+  ZONES,
+  PLATFORM_HOMES,
+  getWorkspaceRoot,
+  getStateHome,
+  getWorkspaceKey,
+  getRuntimeRoot,
+  getRepoManifestHomes,
+  readProjectDocs,
+  parseContextMap,
+  resolveProjectDocs,
+  detectProjectDocsConventions,
+  ensureCommittableFallback,
+  isIgnored,
+  relativePath,
+  isWithinWorkspace
+};