mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/doc-tiers.js

@@ -1,56 +1,9 @@
 /**
- * Doc-tier resolver (Story #4438, Epic #4430 — Context Economy).
- *
- * Pure functions that classify the repository's documentation into the four
- * read-tiers Mandrel's context model recognizes, each entry carrying its
- * on-disk byte size so a byte budget can ratchet against it:
- *
- *   - `alwaysLoaded`  — `CLAUDE.md` plus the transitive closure of its
- *                       `@`-import references (`@AGENTS.md`,
- *                       `@.agents/instructions.md`, the always-on rules, …).
- *                       This is the context every session re-pays
- *                       on every subagent spawn (instructions.md § 4), so it is
- *                       the primary budget the context-budget ratchet gates.
- *   - `mandatoryRead` — the resolved `project.docsContextFiles` set (prefixed
- *                       by `project.paths.docsRoot`), existing files only. This
- *                       is the `docsContextFiles` half the Epic AC gates; it
- *                       skips silently when the set is unconfigured or its
- *                       files are absent.
- *   - `digestVisible` — the situational **Conditional Reads** docs from
- *                       instructions.md § 3 (`docs/style-guide.md`,
- *                       `docs/web-routes.md`) — surfaced only when a task
- *                       touches UI/routing, i.e. visible through the docs
- *                       digest rather than always read. Existing files only.
- *   - `onDemand`      — the on-demand `.agents/rules/*.md` set (instructions.md
- *                       § 1.F): every rule file that is **not** part of the
- *                       always-on core already captured in `alwaysLoaded`.
- *   - `agentBoot`     — the role-scoped boot contexts `.agents/agents/*.md`
- *                       (issue #4478). Each is a standalone system prompt a
- *                       converted spawn boots on **instead of** the always-loaded
- *                       closure, so it is budgeted independently (per-file ≤8KB
- *                       ceiling gated by `check-context-budget.js`).
- *   - `workflow` /    — the `.agents/workflows/**` read-tier (Story #4752),
- *     `workflowOnDemand` resolved as each entry point's transitive
- *                       markdown-link closure by
- *                       [`workflow-closure.js`](workflow-closure.js): the files
- *                       an entry point's `mandatoryReads:` frontmatter forces
- *                       you to read (`workflow`, gated) versus the reachable
- *                       remainder (`workflowOnDemand`, recorded only).
- *
- * A file that could appear in more than one tier is kept in its **highest**
- * tier only (alwaysLoaded > mandatoryRead > digestVisible > onDemand), so the
- * arrays partition the doc set with no double-counting. `agentBoot` is disjoint
- * from the read-tiers (it lives under `.agents/agents/`, not the doc/rules set),
- * and so are the workflow tiers (confined to `.agents/workflows/`).
- *
- * The closure is discovered by parsing `@`-import references and following
- * them recursively (cycle-safe via a visited set). A candidate `@`-token only
- * counts as an import when it resolves to an existing repo file, which
- * naturally filters prose mentions (`@[USERNAME]`, `noreply@example.com`,
- * backtick-wrapped `` `@`-imported `` phrasing).
- *
- * Security (security-baseline § 5 — Data Leakage & Logging): every function
- * emits only repo-relative paths and byte counts — never file contents.
+ * Doc-tier resolver: partition the repo's docs into read-tiers with byte
+ * sizes for the context-budget ratchet (`alwaysLoaded` = CLAUDE.md's
+ * `@`-import closure; `agentBoot` and `workflowOnDemand` are recorded, not
+ * gated). A path lives only in its highest tier. Emits paths and byte
+ * counts, never file contents.
  */
 
 import nodeFs from 'node:fs';
@@ -58,38 +11,24 @@ import path from 'node:path';
 import { resolveWorkflowClosures } from './workflow-closure.js';
 
 /**
- * Basename of the always-loaded entry document (the root of the closure).
  * @type {string}
  */
 const ENTRY_DOC = 'CLAUDE.md';
 
 /**
- * Always-on core rule files (instructions.md § 1.F). These live in the
- * `alwaysLoaded` closure (imported by `CLAUDE.md`); every other
- * `.agents/rules/*.md` file is `onDemand`.
  * @type {string[]}
  */
 const ALWAYS_ON_RULES = ['security-baseline.md', 'git-conventions.md'];
 
 /**
- * Conditional-read docs (instructions.md § 3 — "Conditional Reads"), resolved
- * against `project.paths.docsRoot`. Present in the `digestVisible` tier when
- * they exist.
  * @type {string[]}
  */
 const CONDITIONAL_DOCS = ['style-guide.md', 'web-routes.md'];
 
-/**
- * Match `@`-import tokens: an `@` at start-of-line or after whitespace,
- * followed by a path token that stops at whitespace or common closing
- * punctuation. The resolved-file existence check downstream is the real
- * filter; this regex only harvests candidates.
- */
+/** Candidates only; the file-existence check filters out prose `@` tokens. */
 const IMPORT_RE = /(?:^|\s)@([^\s'"`)\]}>,]+)/gm;
 
 /**
- * Default fs surface — a small subset of `node:fs` so callers can inject a
- * fixture double in tests without touching the real filesystem.
  * @typedef {{
  *   existsSync: (p: string) => boolean,
  *   readFileSync: (p: string, enc: string) => string,
@@ -98,17 +37,15 @@ const IMPORT_RE = /(?:^|\s)@([^\s'"`)\]}>,]+)/gm;
  */
 
 /**
- * Parse the raw `@`-import specifiers from a source document. A trailing `.`
- * or `:` (sentence punctuation) is trimmed so `@AGENTS.md.` still resolves.
+ * Trailing `.`/`:` is trimmed so `@AGENTS.md.` still resolves.
  *
  * @param {string} source
- * @returns {string[]} raw specifiers in first-seen order
+ * @returns {string[]}
  */
 export function parseImportSpecifiers(source) {
   const specs = [];
   for (const m of String(source ?? '').matchAll(IMPORT_RE)) {
     let spec = m[1];
-    // Strip trailing sentence punctuation that the greedy class allowed in.
     while (spec.length > 0 && (spec.endsWith('.') || spec.endsWith(':'))) {
       spec = spec.slice(0, -1);
     }
@@ -118,10 +55,8 @@ export function parseImportSpecifiers(source) {
 }
 
 /**
- * Convert an absolute path to a repo-relative, posix-separated id.
- *
- * @param {string} root absolute repo root
- * @param {string} abs absolute path
+ * @param {string} root
+ * @param {string} abs
  * @returns {string}
  */
 function toRepoRel(root, abs) {
@@ -129,11 +64,8 @@ function toRepoRel(root, abs) {
 }
 
 /**
- * Build a `{ path, bytes }` entry for a repo file, or `null` when it does not
- * exist. `path` is repo-relative posix; `bytes` is the on-disk byte size.
- *
- * @param {string} root absolute repo root
- * @param {string} rel repo-relative path
+ * @param {string} root
+ * @param {string} rel
  * @param {FsLike} fs
  * @returns {{ path: string, bytes: number } | null}
  */
@@ -150,16 +82,11 @@ function fileEntry(root, rel, fs) {
 }
 
 /**
- * Resolve the always-loaded closure: `CLAUDE.md` plus every file reachable by
- * recursively parsing `@`-import references. Cycle-safe (a visited set keyed
- * by repo-relative path). Nested imports resolve relative to the importing
- * file's directory (Claude Code `@`-import semantics). Non-resolving `@`-tokens
- * are ignored, so prose mentions never pollute the closure.
+ * Cycle-safe; nested imports resolve relative to the importing file.
  *
- * @param {string} root absolute repo root (where `CLAUDE.md` lives)
+ * @param {string} root
  * @param {{ fs?: FsLike }} [opts]
- * @returns {Array<{ path: string, bytes: number }>} sorted by path; empty when
- *   `CLAUDE.md` is absent
+ * @returns {Array<{ path: string, bytes: number }>}
  */
 export function resolveAlwaysLoadedClosure(root, { fs = nodeFs } = {}) {
   const entryAbs = path.resolve(root, ENTRY_DOC);
@@ -200,13 +127,10 @@ export function resolveAlwaysLoadedClosure(root, { fs = nodeFs } = {}) {
 }
 
 /**
- * Read the resolved `project.docsContextFiles` list from a config object,
- * prefixed by `project.paths.docsRoot`. Resolves new-shape
- * `project.docsContextFiles` first and falls back to the legacy top-level
- * key, so a config written against either shape yields the same list.
+ * Reads `project.*` first, then the legacy top-level keys.
  *
- * @param {object} config resolved config (`resolveConfig()` output)
- * @returns {string[]} repo-relative posix doc paths (existence not yet checked)
+ * @param {object} config
+ * @returns {string[]}
  */
 export function docsContextPaths(config) {
   const project = config?.project ?? config;
@@ -221,13 +145,7 @@ export function docsContextPaths(config) {
 }
 
 /**
- * Resolve the documentation read-tiers, each entry `{ path, bytes }`,
- * partitioned so no path appears in more than one tier (highest tier wins).
- * `workflowClosure` rides alongside the tiers as the per-entry-point workflow
- * measurement (Story #4752) — its `reachableTotalBytes` is a recorded drift
- * signal, never a gate.
- *
- * @param {object} config resolved config (`resolveConfig()` output)
+ * @param {object} config
  * @param {{ root?: string, fs?: FsLike }} [opts]
  * @returns {{
  *   tiers: {
@@ -264,33 +182,22 @@ export function resolveDocTiers(
     return out.sort((a, b) => a.path.localeCompare(b.path));
   };
 
-  // 1. always-loaded: CLAUDE.md @-import closure. Pre-claim its paths first so
-  //    a lower tier never re-lists a closure member.
+  // Pre-claim the closure so a lower tier never re-lists a member.
   const alwaysLoaded = resolveAlwaysLoadedClosure(root, { fs });
   for (const e of alwaysLoaded) claimed.add(e.path);
 
-  // 2. mandatory-read: resolved docsContextFiles (existing files only).
   const docsRoot =
     config?.project?.paths?.docsRoot ?? config?.paths?.docsRoot ?? 'docs';
   const mandatoryRead = collect(docsContextPaths(config));
 
-  // 3. digest-visible: situational Conditional-Read docs.
   const digestVisible = collect(
     CONDITIONAL_DOCS.map((f) => path.posix.join(docsRoot, f)),
   );
 
-  // 4. on-demand: every .agents/rules/*.md that is not an always-on core rule
-  //    (the always-on ones already live in the alwaysLoaded closure).
   const onDemand = collect(listOnDemandRules(root, fs));
 
-  // 5. agent-boot: role-scoped boot contexts .agents/agents/*.md (#4478). These
-  //    are standalone system prompts, disjoint from the doc read-tiers.
   const agentBoot = collect(listAgentDefs(root, fs));
 
-  // 6. workflow: each entry point's transitive markdown-link closure (#4752),
-  //    split into the gated mandatory set and the recorded on-demand remainder.
-  //    The walk is confined to `.agents/workflows/**`, and `collect` still
-  //    de-dupes, so no path is counted against two tiers.
   const closure = resolveWorkflowClosures(root, { fs });
   const workflow = collect(closure.mandatoryFiles.map((e) => e.path));
   const workflowOnDemand = collect(closure.onDemandFiles.map((e) => e.path));
@@ -314,10 +221,7 @@ export function resolveDocTiers(
 }
 
 /**
- * List the role-scoped agent-boot defs (repo-relative posix): every
- * `.agents/agents/*.md`. Returns [] when the directory is absent.
- *
- * @param {string} root absolute repo root
+ * @param {string} root
  * @param {FsLike} fs
  * @returns {string[]}
  */
@@ -336,11 +240,7 @@ function listAgentDefs(root, fs) {
 }
 
 /**
- * List the on-demand rule files (repo-relative posix): every `.agents/rules/
- * *.md` whose basename is not an always-on core rule. Returns [] when the
- * rules directory is absent.
- *
- * @param {string} root absolute repo root
+ * @param {string} root
  * @param {FsLike} fs
  * @returns {string[]}
  */
@@ -359,8 +259,6 @@ function listOnDemandRules(root, fs) {
 }
 
 /**
- * Sum the `bytes` of every entry in a tier array.
- *
  * @param {Array<{ bytes: number }>} entries
  * @returns {number}
  */

package/.agents/scripts/lib/duplicate-search.js

@@ -1,31 +1,7 @@
 /**
- * duplicate-search.js — Cross-Story Duplicate Detection
- *
- * Used by `/mandrel-plan` to surface open Stories whose scope overlaps with a
- * seed / seed-file / tickets corpus before new Stories are created.
- * Returns ranked candidates with an overlap score and URL so the host
- * LLM can pause for HITL confirmation.
- *
- * Design notes:
- *  - Prefer `provider.searchIssues` to narrow open Stories server-side
- *    (`label:"type::story" state:open` + top seed tokens), capped at
- *    ~100 hits, then rank that set. Fall back to `listIssuesByLabel`
- *    when search errors, is unavailable, or returns **nothing** (same
- *    try/catch pattern as `TicketGateway.getTickets`).
- *  - The narrowing query is deliberately weak (Story #4541). GitHub ANDs
- *    free-text terms, so the former 8-token query demanded that a candidate
- *    contain all eight of a multi-sentence seed's longest words — which no
- *    real Story does. Gate #1 duplicate triage therefore reported "no
- *    candidates" on every realistic seed while looking perfectly healthy.
- *    Search is now a cheap best-case narrowing over a handful of tokens; an
- *    empty result is treated as "search did not help", not "no duplicates",
- *    and falls through to the label listing whose Jaccard ranker has real
- *    recall.
- *  - Scoring is intentionally simple (token Jaccard over title + body).
- *    It is a triage signal, not a semantic-search replacement.
- *  - Provider errors on the list fallback propagate verbatim — the
- *    caller is responsible for translating them into a friction comment
- *    or operator-visible failure.
+ * duplicate-search.js — rank open Stories overlapping a planning seed (token
+ * Jaccard over title + body: a triage signal, not semantic search). List
+ * fallback errors propagate verbatim to the caller.
  */
 
 import { Logger } from './Logger.js';
@@ -88,23 +64,11 @@ const STOPWORDS = new Set([
 
 const DEFAULT_MIN_SCORE = 0.15;
 const DEFAULT_MAX_RESULTS = 5;
-/**
- * How many seed tokens to pass as free-text search terms.
- *
- * GitHub ANDs these, so the cap is a precision/recall dial pointing the
- * wrong way: every extra token shrinks the candidate set. Three is a
- * best-case narrowing that can plausibly hit on a focused seed; anything
- * beyond that reliably matched nothing on a multi-sentence one (Story
- * #4541). Recall does not rest on this number — an empty result falls back
- * to label-listing plus client-side ranking.
- */
+/** GitHub ANDs terms, so more tokens match nothing; recall is the fallback's. */
 const DEFAULT_SEARCH_TOKEN_CAP = 3;
-/** Hard cap on search hits ranked client-side (~one Search API page). */
 const SEARCH_RESULT_CAP = 100;
 
 /**
- * Tokenize freeform text into a deduplicated set of meaningful words.
- *
  * @param {string} text
  * @returns {Set<string>}
  */
@@ -119,8 +83,7 @@ export function tokenize(text) {
 }
 
 /**
- * Pick the highest-signal seed tokens for a Search API free-text query.
- * Longer tokens first (specificity proxy), then alphabetical for stability.
+ * Longest first (specificity), then alphabetical.
  *
  * @param {string} seed
  * @param {number} [maxTokens]
@@ -134,9 +97,6 @@ export function pickSearchTokens(seed, maxTokens = DEFAULT_SEARCH_TOKEN_CAP) {
 }
 
 /**
- * Build the `/search/issues` query for open Stories overlapping a seed.
- * Repo scoping is left to `provider.searchIssues`.
- *
  * @param {string} seed
  * @returns {string}
  */
@@ -146,8 +106,6 @@ export function buildOpenStorySearchQuery(seed) {
 }
 
 /**
- * Compute the Jaccard overlap between two token sets.
- *
  * @param {Set<string>} a
  * @param {Set<string>} b
  * @returns {number} 0..1
@@ -161,9 +119,6 @@ export function overlapScore(a, b) {
 }
 
 /**
- * Build the issue URL for an id. The candidate exposes the URL so the
- * HITL pause can render clickable links without a second round-trip.
- *
  * @param {number|string} id
  * @param {{ owner?: string, repo?: string }} [opts]
  * @returns {string}
@@ -178,8 +133,6 @@ function buildIssueUrl(id, opts = {}) {
 }
 
 /**
- * Normalize a provider issue (list or search hit) into the ranking shape.
- *
  * @param {object} issue
  * @returns {{ id: number, title: string, body: string, url?: string }}
  */
@@ -193,9 +146,6 @@ function normalizeIssue(issue) {
 }
 
 /**
- * Rank a pre-fetched open-Story list against a seed corpus.
- * Pure helper shared by the provider-backed search and tests.
- *
  * @param {{
  *   seed: string,
  *   openStories: Array<{ id:number, title?:string, body?:string, url?:string }>,
@@ -253,8 +203,6 @@ function rankOpenStoryDuplicates({
 }
 
 /**
- * Server-narrowed open-Story fetch via `/search/issues`.
- *
  * @param {object} provider
  * @param {string} seed
  * @returns {Promise<Array<{ id:number, title:string, body:string, url?:string }>>}
@@ -267,8 +215,6 @@ async function fetchOpenStoriesViaSearch(provider, seed) {
 }
 
 /**
- * Full open-Story backlog via label listing (fallback path).
- *
  * @param {object} provider
  * @returns {Promise<Array<{ id:number, title:string, body:string, url?:string }>>}
  */
@@ -287,16 +233,9 @@ async function fetchOpenStoriesViaList(provider) {
 }
 
 /**
- * Fetch open-Story candidates: try Search API narrowing first, fall back to
- * `listIssuesByLabel` when search errors, is unavailable, or **returns no
- * hits**.
- *
- * The empty-result fallback is the load-bearing one (Story #4541). The
- * narrowing query ANDs seed tokens, so on any real multi-sentence seed it
- * matches nothing — and treating that as an authoritative "no duplicates
- * exist" is what made Gate #1 triage report a clean bill of health while
- * never actually looking. An empty search is evidence about the *query*, not
- * about the backlog.
+ * Search first; fall back to the label listing when search errors, is
+ * unavailable, or returns no hits. An empty search is evidence about the
+ * AND-ed query, not about the backlog.
  *
  * @param {object} provider
  * @param {string} seed
@@ -337,9 +276,6 @@ async function fetchOpenStoryCandidates(provider, seed) {
 }
 
 /**
- * Find open Stories whose title + body overlap with the supplied seed
- * above a configurable threshold.
- *
  * @param {{
  *   seed: string,
  *   provider: import('./ITicketingProvider.js').ITicketingProvider,

package/.agents/scripts/lib/env-loader.js

@@ -3,21 +3,9 @@ import path from 'node:path';
 import { Logger } from './Logger.js';
 
 /**
- * Parse the right-hand side of a `KEY=` line into its value.
- *
- * Two rules, and the quoting decides which one applies:
- *
- *  - **Quoted** (`"…"` / `'…'`): the contents between the opening quote and
- *    its matching closing quote are kept **verbatim** — a `#` inside quotes is
- *    part of the value, not a comment. Anything after the closing quote is
- *    trailing commentary and is discarded.
- *  - **Unquoted**: the value ends at the first **unescaped** `#`. A `\#`
- *    escape emits a literal `#` and keeps the scan going, so a value that
- *    genuinely contains a hash can still be written without quotes.
- *
- * An opening quote with no closing partner is not a quoted value — it falls
- * through to the unquoted rule so a malformed line still yields something
- * rather than swallowing the rest of the file's intent.
+ * Quoted values are kept verbatim up to the matching quote (text after it is
+ * dropped); unquoted values end at the first unescaped `#` (`\#` is a
+ * literal). An unclosed quote falls through to the unquoted rule.
  *
  * @param {string} raw — the text after the `=`, unparsed.
  * @returns {string} The value with any inline comment removed.
@@ -29,7 +17,6 @@ function parseEnvValue(raw) {
   const quote = trimmed.charAt(0);
   if (quote === '"' || quote === "'") {
     const closing = trimmed.indexOf(quote, 1);
-    // Verbatim contents: no comment stripping, no unescaping.
     if (closing !== -1) return trimmed.slice(1, closing);
   }
 
@@ -47,23 +34,14 @@ function parseEnvValue(raw) {
   return value.trim();
 }
 
-/**
- * Auto-load .env from the project root if it exists
- */
 export function loadEnv(projectRoot) {
   const envPath = path.resolve(projectRoot, '.env');
   let envContent;
   try {
-    // Read directly rather than existsSync + readFileSync: the latter is a
-    // TOCTOU race (the file can vanish between the two calls) and double-stats
-    // the path. A single read with code-based error handling is both correct
-    // and cheaper.
+    // A single read, not existsSync + read, avoids a TOCTOU race.
     envContent = fs.readFileSync(envPath, 'utf8');
   } catch (err) {
-    // A missing .env is the expected case — environment may be provided via
-    // other means, so stay silent. Any other failure (permissions, a
-    // directory in place of the file, I/O error) is worth surfacing so the
-    // operator gets a one-line hint instead of an opaque silent skip.
+    // A missing .env is expected; anything else deserves a one-line hint.
     if (err.code !== 'ENOENT') {
       Logger.warn(
         `env-loader: failed to read ${envPath} (${err.code ?? err.message}); skipping .env load.`,

package/.agents/scripts/lib/error-redactor.js

@@ -1,13 +1,6 @@
 /**
- * Story #1651 (CWE-209): error-envelope redactor for CLI scripts.
- *
- * Rewrites absolute filesystem paths to repo-relative form, elides
- * `$HOME` / `$USERPROFILE` segments outside the repo, and scrubs
- * token-shaped substrings before error envelopes hit the public CI log.
- *
- * Pure and dependency-free so callers (tests, ad-hoc loggers, the
- * runAsCli default handler) can reuse it without standing up the rest
- * of the cli-utils harness.
+ * Error-envelope redactor (CWE-209): repo-relative paths, elided home dir,
+ * scrubbed token-shaped strings. Dependency-free.
  */
 
 import path from 'node:path';
@@ -16,10 +9,7 @@ import { fileURLToPath } from 'node:url';
 const REPO_ROOT_CACHE = { value: null };
 
 /**
- * Resolve the repository root the redactor rewrites against. The
- * heuristic walks up from this file's directory; consumers may override
- * via the `repoRoot` option on `redactErrorMessage`. The result is
- * memoised because the redactor runs in the hot path of error-printing.
+ * Memoised — the redactor runs on the error-printing hot path.
  *
  * @returns {string}
  */
@@ -34,10 +24,7 @@ export function resolveRepoRoot() {
 const TOKEN_SHAPED = /\b(?:gh[pousr]_[A-Za-z0-9_]{20,}|[A-Fa-f0-9]{32,})\b/g;
 
 /**
- * Normalise both Windows-style and POSIX-style absolute paths in
- * `message` to repo-relative form, elide `$HOME` / `$USERPROFILE`
- * outside the repo, and scrub token-shaped substrings (`ghp_*`,
- * `gho_*`, `ghs_*`, `ghu_*`, `ghr_*`, 32+ hex chars).
+ * Handles both Windows and POSIX path separators.
  *
  * @param {string|undefined} message
  * @param {object} [options]
@@ -80,15 +67,8 @@ function pathVariants(p) {
 }
 
 /**
- * Determine whether error-message redaction is enabled for this process.
- *
- * Precedence (any one is enough to opt in):
- *   1. Explicit `--quiet-errors` flag in `argv`.
- *   2. `AGENT_CLI_QUIET_ERRORS=1` (or `true`) in `env`.
- *   3. `CI=true` (or any other truthy non-empty value) in `env`.
- *
- * Operator workstations stay verbose by default; CI runs (where logs
- * are public on OSS forks) get redaction automatically.
+ * On with `--quiet-errors`, `AGENT_CLI_QUIET_ERRORS`, or a truthy `CI` —
+ * CI logs are public on OSS forks; workstations stay verbose.
  *
  * @param {string[]} [argv]      Defaults to `process.argv.slice(2)`.
  * @param {NodeJS.ProcessEnv} [env]  Defaults to `process.env`.
@@ -111,11 +91,6 @@ function isTruthyEnv(value) {
 }
 
 /**
- * Format a thrown error for stderr, applying redaction when
- * `parseQuietErrorsFlag()` says we should. Extracted from `runAsCli` so
- * the cli-utils default error handler stays a single expression and the
- * redaction logic lives next to the redactor itself.
- *
  * @param {unknown} err
  * @returns {string}
  */

package/.agents/scripts/lib/errors/index.js

@@ -1,10 +1,4 @@
-/**
- * lib/errors/ — canonical home for custom Error subclasses used by the
- * orchestration SDK.
- *
- * Consumers import by class so tests can match on `instanceof` rather than
- * message substrings.
- */
+/** Custom Error subclasses; match on `instanceof`, not message text. */
 
 class ConflictingTypeLabelsError extends Error {
   constructor(message) {
@@ -21,12 +15,6 @@ export class ValidationError extends Error {
   }
 }
 
-/**
- * Errors raised by the `gh` CLI bridge (currently the bootstrap preflight;
- * later the `lib/gh-exec.js` shim outlined in Tech Spec #1350). Tests
- * match on `instanceof` rather than message substrings so message text
- * can evolve without churning the assertions.
- */
 export class GhNotInstalledError extends Error {
   constructor(message = 'gh CLI is not installed or not on PATH') {
     super(message);
@@ -49,15 +37,7 @@ export class GhVersionError extends Error {
   }
 }
 
-/**
- * Raised when a framework runtime dependency (e.g. `ajv`) cannot be
- * resolved from the consumer's `node_modules/`. Surfaces during the
- * `agents-bootstrap-github` preflight to redirect operators to the
- * correct remediation (`mandrel init` for new projects, or
- * `npm install mandrel` for existing ones). `missing` carries the
- * package specifiers that failed to resolve so the CLI can render an
- * actionable hint.
- */
+/** A runtime dep (e.g. `ajv`) did not resolve; `missing` names the specifiers. */
 export class MissingRuntimeDepsError extends Error {
   constructor(message, details = {}) {
     super(message);