archgen-skill 0.1.0 → 0.1.2

package/lib/node_modules/archgen-mcp/node_modules/zod/v4/package.json

@@ -0,0 +1,7 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts",
+  "sideEffects": false
+}

package/lib/node_modules/archgen-mcp/node_modules/zod/v4-mini/index.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+const z = __importStar(require("../v4/mini/external.cjs"));
+exports.z = z;
+__exportStar(require("../v4/mini/external.cjs"), exports);
+
+// seal-cjs-exports
+(function () {
+  var keys = Object.getOwnPropertyNames(exports);
+  for (var i = 0; i < keys.length; i++) {
+    var desc = Object.getOwnPropertyDescriptor(exports, keys[i]);
+    if (!desc || !desc.get || !desc.configurable) continue;
+    var value;
+    try {
+      value = desc.get();
+    } catch (e) {
+      continue;
+    }
+    // a circular require may not have settled this one yet, so leave it live
+    if (value === undefined) continue;
+    Object.defineProperty(exports, keys[i], { value: value, writable: false, enumerable: desc.enumerable, configurable: false });
+  }
+  Object.freeze(exports);
+})();

package/lib/node_modules/archgen-mcp/node_modules/zod/v4-mini/index.d.cts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.cjs";
+export * from "../v4/mini/external.cjs";
+export { z };

package/lib/node_modules/archgen-mcp/node_modules/zod/v4-mini/index.d.ts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/lib/node_modules/archgen-mcp/node_modules/zod/v4-mini/index.js

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/lib/node_modules/archgen-mcp/node_modules/zod/v4-mini/package.json

@@ -0,0 +1,7 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts",
+  "sideEffects": false
+}

package/lib/node_modules/archgen-mcp/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "archgen-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for archgen \u2014 the single runtime that owns architecture-plan validation, wave execution, artifact navigation, CodeGraph bootstrap and harness MCP wiring for coding agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "archgen-mcp": "bin/archgen-mcp.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "mcp",
+    "model-context-protocol",
+    "architecture",
+    "task-graph",
+    "planning",
+    "codegraph"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/akashmaurya99/archgen.git"
+  },
+  "homepage": "https://github.com/akashmaurya99/archgen#readme",
+  "bugs": {
+    "url": "https://github.com/akashmaurya99/archgen/issues"
+  },
+  "scripts": {
+    "test": "node --test",
+    "inspect": "npx -y @modelcontextprotocol/inspector node bin/archgen-mcp.mjs",
+    "prepublishOnly": "node scripts/verify-version.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.4.0",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.4.0"
+  }
+}

package/lib/node_modules/archgen-mcp/src/cli.mjs

@@ -0,0 +1,244 @@
+// cli.mjs — the command-line facade over the MCP server.
+//
+// WHY A CLI FACADE: two consumers need the same capability, and they must
+// never drift apart:
+//   - agents          -> MCP over stdio
+//   - the CLI installer -> `archgen-mcp bootstrap`
+//
+// `exec` runs the SAME tool handlers the MCP server exposes — there is no
+// second implementation of any capability, only a second way to reach it.
+//
+// Commands:
+//   serve                              (default) the stdio MCP server
+//   exec <tool> '<json-args>'          run one tool, print the envelope as JSON
+//   bootstrap [--project <dir>]         wire the archgen MCP + ensure CodeGraph
+//   doctor [--project <dir>]            health report
+//   uninstall-mcp [--project <dir>]     remove the archgen MCP entries
+import { guard } from './envelope.mjs';
+import { Context } from './context.mjs';
+import { createServer } from './server.mjs';
+import { getToolSpec, registeredToolNames } from './tools/_register.mjs';
+import { loadAsset } from './context.mjs';
+import { wireArchgenMcp, uninstallArchgenMcp, archgenMcpStatus } from './core/mcp-server-manager.mjs';
+import { manageCodegraph, assertLocation, findCodegraph } from './core/codegraph-manager.mjs';
+import { detectHarnesses } from './core/harness-wiring.mjs';
+
+const USAGE = `archgen-mcp — MCP server for archgen
+
+Usage:
+  archgen-mcp                                  serve the MCP server over stdio (default)
+  archgen-mcp exec <tool> '<json-args>'        run one tool, print JSON
+  archgen-mcp bootstrap [--project <dir>]      wire the archgen MCP + ensure CodeGraph
+  archgen-mcp doctor [--project <dir>]         health report
+  archgen-mcp uninstall-mcp [--project <dir>]  remove the archgen MCP entries
+
+Options:
+  --project <dir>   project root (default: current directory)
+  --location <s>    project | global | both (default: both)
+  --yes             approve MCP-config writes
+  --json            machine-readable output
+  --tool <name>     list a tool's schema
+  --list            list every tool
+  --catalog         print the injected tool catalog (name + description + JSON schema)
+
+Tools: ${registeredToolNames().join(', ')}`;
+
+/**
+ * Parse the CLI arguments.
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const opts = {
+    command: 'serve',
+    tool: null,
+    args: null,
+    project: null,
+    location: 'both',
+    yes: false,
+    json: false,
+    list: false,
+    catalog: false,
+  };
+  const rest = [...argv];
+  const command = rest[0];
+  if (command && !command.startsWith('-')) {
+    opts.command = command;
+    rest.shift();
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '--project') opts.project = rest[++i];
+    else if (a === '--location') opts.location = rest[++i];
+    else if (a === '--yes') opts.yes = true;
+    else if (a === '--json') opts.json = true;
+    else if (a === '--list') opts.list = true;
+    else if (a === '--catalog') opts.catalog = true;
+    else if (a === '--tool') opts.tool = rest[++i];
+    else if (a === '--help' || a === '-h') opts.command = 'help';
+    else if (!a.startsWith('-')) {
+      if (opts.tool === null && opts.command === 'exec') opts.tool = a;
+      else if (opts.args === null) opts.args = a;
+      else opts.extra = a;
+    }
+  }
+  return opts;
+}
+
+/**
+ * Run the CLI facade.
+ * @param {string[]} argv
+ * @param {{stdout?: (s: string) => void, stderr?: (s: string) => void}} [io]
+ * @returns {Promise<number>} the process exit code
+ */
+export async function runCli(argv, io = {}) {
+  const out = io.stdout ?? ((s) => process.stdout.write(s + '\n'));
+  const err = io.stderr ?? ((s) => process.stderr.write(s + '\n'));
+  const opts = parseArgs(argv);
+
+  if (opts.command === 'help') {
+    out(USAGE);
+    return 0;
+  }
+
+  // Register every tool (also populates the spec registry `exec` reads).
+  const server = createServer();
+
+  if (opts.list) {
+    out(JSON.stringify(registeredToolNames(), null, 2));
+    return 0;
+  }
+
+  if (opts.catalog) {
+    // The EXACT payload a client injects into the model's context for every
+    // request: each tool's name, description and JSON schema. The internal
+    // token-budget tool measures this, so the catalog cost is budgeted like
+    // any other context expense.
+    const catalog = registeredToolNames().map((name) => ({
+      name,
+      description: getToolSpec(name)?.description ?? '',
+      inputSchema: server.toolInputSchemaJson(name) ?? null,
+    }));
+    out(JSON.stringify(catalog, null, 2));
+    return 0;
+  }
+
+  const ctx = new Context({ projectRoot: opts.project ?? process.cwd() });
+
+  if (opts.command === 'exec') {
+    if (!opts.tool) {
+      err('exec requires a tool name');
+      out(USAGE);
+      return 2;
+    }
+    const spec = getToolSpec(opts.tool);
+    if (!spec) {
+      err(`unknown tool '${opts.tool}' — known tools: ${registeredToolNames().join(', ')}`);
+      return 2;
+    }
+    if (opts.tool === undefined) return 2;
+    let parsed = {};
+    if (opts.args) {
+      try {
+        parsed = JSON.parse(opts.args);
+      } catch (e) {
+        err(`arguments must be valid JSON: ${e.message}`);
+        return 2;
+      }
+    }
+    if (parsed.projectRoot === undefined && opts.project) parsed.projectRoot = opts.project;
+    const check = spec.inputSchema.safeParse(parsed);
+    if (!check.success) {
+      const envelope = {
+        ok: false,
+        error: { code: 'INVALID_INPUT', message: 'arguments do not match the tool schema', details: { issues: check.error.issues } },
+        meta: ctx.meta(),
+      };
+      out(JSON.stringify(envelope, null, 2));
+      return 1;
+    }
+    const envelope = await guard(spec.handler, ctx, check.data);
+    out(JSON.stringify(envelope, null, 2));
+    return envelope.ok ? 0 : 1;
+  }
+
+  const registry = loadAsset('harness-mcp.json');
+
+  if (opts.command === 'bootstrap') {
+    const location = assertLocation(opts.location);
+    const mcp = wireArchgenMcp({
+      projectRoot: ctx.projectRoot,
+      registry,
+      home: ctx.home,
+      location,
+      approved: opts.yes,
+      env: ctx.env,
+    });
+    const codegraph = await manageCodegraph({
+      mode: 'ensure',
+      projectRoot: ctx.projectRoot,
+      registry,
+      location,
+      approved: opts.yes,
+      home: ctx.home,
+      env: ctx.env,
+    });
+    if (opts.json) {
+      out(JSON.stringify({ mcp, codegraph }, null, 2));
+    } else {
+      out(`archgen-mcp bootstrap — ${ctx.projectRoot}`);
+      out(`  mcp:     ${mcp.detected.length} harness(es) detected — ${mcp.wired.map((w) => `${w.harness}:${w.status}`).join(', ') || 'none'}`);
+      out(`  binary: ${mcp.binary.bin ?? 'npx fallback'}`);
+      out(`  codegraph: ${codegraph.cli.present ? codegraph.cli.version : 'not installed'} · index ${codegraph.index.action}`);
+    }
+    return codegraph.ok === false ? 1 : 0;
+  }
+
+  if (opts.command === 'doctor') {
+    const status = archgenMcpStatus({ projectRoot: ctx.projectRoot, registry, home: ctx.home });
+    const codegraph = findCodegraph(ctx.env);
+    const report = {
+      projectRoot: ctx.projectRoot,
+      skill: ctx.skill ? { path: ctx.skill.path, version: ctx.skill.version, scope: ctx.skill.scope } : null,
+      server: ctx.serverVersion,
+      node: process.versions.node,
+      codegraph: codegraph ? { bin: codegraph.bin, version: codegraph.version } : null,
+      mcpBinary: status.binary,
+      mcpTargets: status.targets,
+      harnesses: detectHarnesses(registry, ctx.projectRoot, ctx.home, ctx.env).map((d) => d.id),
+    };
+    if (opts.json) {
+      out(JSON.stringify(report, null, 2));
+    } else {
+      out(`archgen-mcp doctor — ${ctx.projectRoot}`);
+      out(`  node:    ${report.node}`);
+      out(`  server:  ${report.server}`);
+      out(`  skill:   ${report.skill ? `${report.skill.path} (${report.skill.version ?? 'unknown'})` : 'NOT FOUND'}`);
+      out(`  mcp bin: ${report.mcpBinary.bin ?? 'not on PATH (npx fallback)'} (${report.mcpBinary.source})`);
+      out(`  codegraph: ${report.codegraph ? report.codegraph.version : 'not installed'}`);
+      out(`  harnesses: ${report.harnesses.join(', ') || 'none detected'}`);
+    }
+    return 0;
+  }
+
+  if (opts.command === 'uninstall-mcp') {
+    if (!opts.yes) {
+      err('uninstall-mcp needs --yes (nothing was removed)');
+      return 2;
+    }
+    const res = uninstallArchgenMcp(ctx.projectRoot, ctx.home, 'both', ctx.env);
+    if (opts.json) out(JSON.stringify(res, null, 2));
+    else {
+      out(`removed ${res.removed.length} config(s)`);
+      for (const r of res.removed) out(`  - ${r}`);
+      for (const s of res.skipped) out(`  ! ${s}`);
+    }
+    return 0;
+  }
+
+  if (opts.command === 'serve') return null; // the caller connects the transport
+
+  err(`unknown command '${opts.command}'`);
+  out(USAGE);
+  return 2;
+}
+

package/lib/node_modules/archgen-mcp/src/context.mjs

@@ -0,0 +1,198 @@
+// context.mjs — resolves the project root, the installed skill, and the
+// server's own assets. Every tool call runs against a Context.
+//
+// WHY A CONTEXT OBJECT: a model can hand the server any path it likes. The
+// context pins the project root ONCE per process (or per explicit override)
+// and every path argument is proved to stay inside it before a read or a
+// write happens. Nothing in the tool layer touches the filesystem without
+// going through here first.
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { invalidInput } from './core/errors.mjs';
+import { assertWithinRoot, containPath } from './core/fs-safety.mjs';
+import { GLOBAL_SKILL_ROOTS, PROJECT_SKILL_ROOTS, skillSearchPaths } from './core/skill-roots.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** This package's own root (packages/mcp). */
+export const SERVER_ROOT = resolve(HERE, '..');
+
+/** This package's assets directory (harness-mcp.json, mcp-template.json, …). */
+export const ASSETS_DIR = join(SERVER_ROOT, 'assets');
+
+/** This package's dispatch-brief templates. */
+export const BRIEFS_DIR = join(ASSETS_DIR, 'briefs');
+
+/** This package's artifact templates (the canonical source for every shape). */
+export const TEMPLATES_DIR = join(ASSETS_DIR, 'templates');
+
+/** The server's own version (packages/mcp/package.json). */
+export function serverVersion() {
+  try {
+    return JSON.parse(readFileSync(join(SERVER_ROOT, 'package.json'), 'utf8')).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+/**
+ * Skill install locations, project-local first.
+ *
+ * Mirrors references/platforms.md § "Skill install paths". The canonical list
+ * lives in core/skill-roots.mjs so the archgen skill and the CAPABILITY
+ * skills are resolved against the same roots — one list, one answer.
+ */
+export const PROJECT_SKILL_DIRS = PROJECT_SKILL_ROOTS.map((r) => join(r, 'archgen'));
+
+/** User-global skill locations (same shape, under $HOME). */
+export const GLOBAL_SKILL_DIRS = GLOBAL_SKILL_ROOTS.map((r) => join(r, 'archgen'));
+
+/**
+ * Locate the installed archgen skill.
+ *
+ * Resolution order (first hit wins):
+ *   1. $ARCHGEN_SKILL_DIR        — explicit override
+ *   2. project-local, walking UP from the project root to the filesystem root
+ *   3. user-global under $HOME
+ *   4. null — the skill is not installed here
+ *
+ * @param {string} projectRoot absolute project root
+ * @param {string} [home] override $HOME (tests)
+ * @param {Record<string, string|undefined>} [env] override process.env (tests)
+ * @returns {{path: string, version: string|null, scope: 'override'|'project'|'global'}|null}
+ */
+export function resolveSkill(projectRoot, home = homedir(), env = process.env) {
+  const override = env.ARCHGEN_SKILL_DIR;
+  if (override) {
+    const abs = isAbsolute(override) ? override : resolve(projectRoot, override);
+    if (existsSync(join(abs, 'SKILL.md'))) return { path: abs, version: readSkillVersion(abs), scope: 'override' };
+  }
+
+  // The project chain (walking UP) and the user-global roots come from the
+  // ONE skill-root list, so the archgen skill and the capability skills are
+  // resolved against the same places.
+  for (const candidate of skillSearchPaths(projectRoot, 'archgen', { home })) {
+    if (existsSync(join(candidate.dir, 'SKILL.md'))) {
+      return { path: candidate.dir, version: readSkillVersion(candidate.dir), scope: candidate.scope };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Read the `.archgen-version` stamp written by the installer.
+ * @param {string} skillDir
+ * @returns {string|null}
+ */
+export function readSkillVersion(skillDir) {
+  try {
+    const v = readFileSync(join(skillDir, '.archgen-version'), 'utf8').trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load a JSON asset shipped with this package.
+ * @param {string} name file name inside assets/
+ * @returns {any}
+ */
+export function loadAsset(name) {
+  const p = join(ASSETS_DIR, name);
+  let text;
+  try {
+    text = readFileSync(p, 'utf8');
+  } catch {
+    throw invalidInput(`missing server asset '${name}'`, { asset: name });
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw invalidInput(`server asset '${name}' is not valid JSON: ${e.message}`, { asset: name });
+  }
+}
+
+/**
+ * The per-call context: project root + resolved skill + versions.
+ *
+ * THE ANCHOR. `anchorRoot` is the boundary the server works inside. It is
+ * set when the server starts — the directory the server was launched in, or
+ * the project the CLI named — and it does NOT change per call.
+ *
+ * `projectRoot` selects a directory INSIDE the anchor. It is a selector, not
+ * a boundary: naming a different root cannot move the edge of what the
+ * server may read or write. Before this, every containment check was
+ * relative to a root the MODEL chose, so the guard defended nothing — a
+ * model that named `/etc` simply moved the boundary to `/etc`.
+ */
+export class Context {
+  /**
+   * @param {{projectRoot?: string, anchorRoot?: string, home?: string, env?: Record<string, string|undefined>}} [opts]
+   */
+  constructor(opts = {}) {
+    this.env = opts.env ?? process.env;
+    this.home = opts.home ?? homedir();
+    // The anchor is the server's DECLARED root: what the server was started
+    // with. The cwd is only the fallback for a server started without one.
+    this.anchorRoot = resolve(
+      opts.anchorRoot ?? opts.projectRoot ?? this.env.ARCHGEN_PROJECT_ROOT ?? process.cwd(),
+    );
+    this.projectRoot = resolve(opts.projectRoot ?? this.anchorRoot);
+    this.skill = resolveSkill(this.projectRoot, this.home, this.env);
+    this.serverVersion = serverVersion();
+  }
+
+  /**
+   * A context for a directory inside the anchor.
+   *
+   * The candidate is resolved and proved to be inside the anchor; a path
+   * outside it is refused with PERMISSION_DENIED. The returned context
+   * keeps the SAME anchor, so containment checks made with it cannot be
+   * widened either.
+   *
+   * @param {string} candidate
+   * @returns {Context}
+   */
+  withProjectRoot(candidate) {
+    if (typeof candidate !== 'string' || candidate.trim() === '') {
+      throw invalidInput('projectRoot must be a non-empty string', { projectRoot: candidate });
+    }
+    const abs = resolve(this.anchorRoot, candidate);
+    assertWithinRoot(this.anchorRoot, abs);
+    return new Context({
+      projectRoot: abs,
+      anchorRoot: this.anchorRoot,
+      env: this.env,
+      home: this.home,
+    });
+  }
+
+  /**
+   * Resolve a caller-supplied path and prove it stays inside the project root.
+   * Relative paths are resolved against the project root.
+   * @param {string} p
+   * @returns {string} absolute path
+   */
+  contain(p) {
+    if (typeof p !== 'string' || p.trim() === '') throw invalidInput('path must be a non-empty string', { path: p });
+    return containPath(this.projectRoot, p);
+  }
+
+  /**
+   * The small metadata block every tool response carries.
+   * @returns {{serverVersion: string, skillVersion: string|null, skillPath: string|null, projectRoot: string, warnings: string[]}}
+   */
+  meta(warnings = []) {
+    return {
+      serverVersion: this.serverVersion,
+      skillVersion: this.skill?.version ?? null,
+      skillPath: this.skill?.path ?? null,
+      projectRoot: this.projectRoot,
+      warnings,
+    };
+  }
+}

package/lib/node_modules/archgen-mcp/src/core/brief-context.mjs

@@ -0,0 +1,106 @@
+// brief-context.mjs — what a dispatch brief carries besides its task.
+//
+// WHY A SEPARATE MODULE: the brief TEMPLATE holds the protocol (what to
+// examine, what to return). The CONTEXT holds the facts (which files exist,
+// which sections they have, what the tools already said). They change for
+// different reasons and at different times, so they are assembled separately
+// and composed once.
+//
+// THE RENDERING RULE: everything here is computed BY THE TOOL, not requested
+// by the orchestrator. The old review brief said "attach the mermaid graph
+// and the docs-validate result", which cost two tool calls per gate round —
+// and the graph call failed on every plan, so the reviewer ran without it.
+// Rendering it once, into the brief, removes the extra calls AND the
+// dependency.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { docIndex } from './doc-navigator.mjs';
+import { planGraph } from './plan-grapher.mjs';
+
+/**
+ * The archgen calls each brief kind is ALLOWED to make.
+ *
+ * The list is exhaustive on purpose: a sub-agent that runs the archgen tool
+ * suite is re-deriving facts the brief already carries, and can drift from
+ * the protocol the orchestrator is following.
+ */
+const ALLOWED_CALLS = {
+  verifier: ["archgen_plan{action:'verify'}", "archgen_docs{action:'validate'}"],
+  review: [],
+  survey: [],
+  investigate: ["archgen_plan{action:'impact'}"],
+};
+
+/** The archgen calls each brief kind may make — the single source of truth. */
+export { ALLOWED_CALLS };
+
+/**
+ * Build the context block for one brief.
+ *
+ * @param {string} kind the brief kind
+ * @param {{slug: string, slugDir: string, plansDir: string, tasksYaml: string}} scope
+ * @param {{projectRoot: string}} ctx
+ * @returns {{
+ *   scope: object,
+ *   allowedCalls: string[],
+ *   evidence: {files: Array<{path: string, sections: Array<{slug: string, title: string}>}>, fileCount: number}|null,
+ *   graph: string|null,
+ *   docsValidation: {valid: boolean, broken: unknown[], warnings: unknown[]}|null,
+ * }}
+ */
+export function buildBriefContext(kind, scope, ctx) {
+  const out = {
+    scope,
+    allowedCalls: ALLOWED_CALLS[kind] ?? [],
+    evidence: null,
+    graph: null,
+    docsValidation: null,
+  };
+
+  // The evidence map: every markdown artifact under the slug, with its
+  // section anchors. A MAP, not a copy — the agent reads the sections it
+  // needs and never re-reads the whole plan.
+  try {
+    if (existsSync(scope.slugDir)) {
+      const digest = docIndex(scope.slugDir, { mode: 'digest', projectRoot: ctx.projectRoot });
+      const files = (digest.data.files ?? []).map((f) => ({
+        path: f.path,
+        sections: (f.sections ?? []).map((s) => ({ slug: s.slug, title: s.title })),
+      }));
+      out.evidence = { files, fileCount: files.length };
+    }
+  } catch {
+    out.evidence = null; // a missing artifact space is not a brief failure
+  }
+
+  // The dependency graph — rendered once, so the reviewer reads it instead of
+  // spending a tool call to fetch it.
+  try {
+    if (existsSync(scope.tasksYaml)) {
+      const g = planGraph(scope.tasksYaml, {
+        mermaid: true,
+        status: true,
+        projectRoot: ctx.projectRoot,
+      });
+      out.graph = typeof g.data === 'string' ? g.data : null;
+    }
+  } catch {
+    out.graph = null; // a plan that cannot be graphed is reported by the verifier
+  }
+
+  // The reference-integrity result — the deterministic floor's second half.
+  try {
+    if (existsSync(scope.slugDir)) {
+      const v = docIndex(scope.slugDir, { mode: 'validate', projectRoot: ctx.projectRoot });
+      out.docsValidation = {
+        valid: v.data.valid === true,
+        broken: v.data.broken ?? [],
+        warnings: v.data.warnings ?? [],
+      };
+    }
+  } catch {
+    out.docsValidation = null;
+  }
+
+  return out;
+}