mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/single-story-sweep.js

@@ -1,54 +1,8 @@
 /**
- * single-story-sweep.js — the scope-agnostic merged-branch sweep engine
- * plus the `story-*` boot-sweep preset.
- *
- * `sweepMergedBranches` is the single reap engine every boot cleanup
- * path routes through. It sits directly over the `git-cleanup` phase
- * library (`planCleanup` / `executeCleanup` / `executeFastForward` /
- * `buildGlobFilter`) and the shared `evaluateProtection` guard set, so
- * no reap path re-implements the `git branch -D` / `git merge --ff-only`
- * primitives:
- *
- *   - Scope: caller-supplied `include` / `exclude` globs (via
- *            `buildGlobFilter`). The story preset pins `story-*`.
- *   - Reap:  merged local branches whose PR HEAD SHA equals the merged
- *            `headRefOid`, deleted local + origin with tracking-ref
- *            prune (`executeCleanup` in `--remote` mode).
- *   - Protection (Story #2011): each candidate is filtered through
- *            `evaluateProtection` before reaching `executeCleanup`. A
- *            candidate is protected (not reaped) when its branch HEAD
- *            differs from the PR's `headRefOid` (unpushed work), when
- *            its worktree has uncommitted edits, or when the parent
- *            Story ticket is not in a terminal state. Protected
- *            candidates surface under `protected`.
- *   - Fast-forward (opt-in via `fastForward: true`): fast-forward the
- *            base branch through `executeFastForward` after the reap.
- *            Best-effort — a failed fast-forward never fails the sweep.
- *   - Concurrency (Story #2011): the sweep acquires a process-scoped
- *            lockfile around plan + execute. On lock contention the
- *            sweep is skipped (the host continues — same contract as a
- *            plan failure).
- *   - Content-merged (Story #4396, report-only): a plan candidate the
- *            `git-cleanup` planner classified `detectedBy: 'content-merged'`
- *            (Story #4395's `git merge-tree --write-tree` content-equivalence
- *            probe) is a **weaker** signal than a merged PR or git ancestry —
- *            no CI/GitHub merge check ever validated its exact diff. This
- *            engine never reaps on that signal alone: content-merged
- *            candidates are pulled out of the plan before protection +
- *            execute and surfaced under `contentMerged` in the envelope so
- *            the operator can route them to `/git-cleanup` for a confirmed,
- *            eyeballed reap.
- *   - Never touches the stash stack.
- *   - Errors are caught and surfaced in the envelope. Callers MUST NOT
- *            propagate sweep failures — the host proceeds either way.
- *
- * `sweepMergedStoryBranches` is a thin preset over the engine tuned for
- * the boot path (`include: story-*`, `exclude: <current story branch>`,
- * `fastForward: false`). Its exported name, signature, and result
- * envelope are unchanged from the pre-engine implementation.
- *
- * Re-exports the same `planCleanup` / `executeCleanup` injection seams so
- * tests can stub git/`gh` without touching the CLI.
+ * Merged-branch sweep over the `git-cleanup` phases, plus the `story-*` boot
+ * preset. A candidate is protected when its HEAD differs from the PR's, its
+ * worktree is dirty, or its Story is not terminal. Lock contention skips.
+ * Errors land in the envelope; callers MUST NOT propagate them.
  */
 
 import {
@@ -64,8 +18,6 @@ import { acquireSweepLock as defaultAcquireSweepLock } from './single-story-swee
 const STORY_BRANCH_INCLUDE = 'story-*';
 
 /**
- * Scope-agnostic merged-branch sweep engine.
- *
  * @param {{
  *   cwd: string,
  *   baseBranch: string,
@@ -129,9 +81,7 @@ export async function sweepMergedBranches({
     return zeroResult({ error: 'baseBranch is required' });
   }
 
-  // Optional lock acquisition. Skip silently when no lockPath is
-  // supplied (e.g. unit tests, callers that opt out). Contention is
-  // non-fatal — return a skipped result and let the host continue.
+  // No lockPath → no lock. Contention returns a skipped result.
   let releaseLock = () => {};
   if (lockPath) {
     const lockResult = acquireLockFn({ lockPath, timeoutMs: lockTimeoutMs });
@@ -190,12 +140,8 @@ export async function sweepMergedBranches({
 }
 
 /**
- * Sweep merged `story-*` branches in `cwd`. Preset over
- * {@link sweepMergedBranches} for the boot path: it pins the `story-*`
- * include glob, excludes the current run's `currentStoryBranch`, and
- * keeps `fastForward` off (the boot caller fast-forwards the base branch
- * separately). Exported name, signature, and result-envelope shape are
- * unchanged from the pre-engine implementation.
+ * Boot preset: `story-*` only, current Story branch excluded, no
+ * fast-forward (the boot caller does that separately).
  *
  * @param {{
  *   cwd: string,
@@ -228,13 +174,9 @@ export function sweepMergedStoryBranches(args = {}) {
 }
 
 /**
- * Split a plan's candidates into the reapable set and the report-only
- * `content-merged` set (Story #4396). A candidate the `git-cleanup`
- * planner classified `detectedBy: 'content-merged'` (Story #4395's
- * `git merge-tree --write-tree` probe) never reaches protection or
- * `executeCleanup` — it is a weaker signal than a merged PR or git
- * ancestry, so the engine only reports it for the operator to route to
- * `/git-cleanup`.
+ * Content-merged candidates are report-only: content equivalence is weaker
+ * than a merged PR or ancestry, so only an operator-confirmed `/git-cleanup`
+ * may reap them.
  */
 function partitionContentMerged(candidates) {
   const contentMerged = [];
@@ -252,10 +194,6 @@ function partitionContentMerged(candidates) {
   return { contentMerged, reapCandidates };
 }
 
-/**
- * Inner: the plan + protect + execute pipeline. Kept separate so the
- * outer engine can stay focused on the lock and fast-forward wrappers.
- */
 async function runSweepUnderLock({
   cwd,
   baseBranch,
@@ -342,11 +280,6 @@ async function runSweepUnderLock({
   });
 }
 
-/**
- * Execute the reap plan for the reapable candidates and shape the result
- * envelope. Split out of {@link runSweepUnderLock} so each function keeps
- * a single responsibility.
- */
 function executeReap({
   reapable,
   protectedList,
@@ -403,10 +336,7 @@ function executeReap({
     candidates: candidateCount,
     localDeleted,
     remoteDeleted,
-    // Story #4794 — the branch names, not just the count. Each one is a merge
-    // this sweep CONFIRMED (merged PR + matching headRefOid), which is exactly
-    // the evidence the temp-retention catch-up needs to purge that Story's
-    // spent artifacts. Previously these existed only inside a log string.
+    // Confirmed merges: temp-retention's catch-up purges on these names.
     reaped: reapable.map((c) => c.branch),
     protected: protectedList,
     contentMerged,
@@ -414,11 +344,7 @@ function executeReap({
   };
 }
 
-/**
- * Best-effort fast-forward of the base branch through the git-cleanup
- * fast-forward phase. Never throws — a failed fast-forward is logged and
- * returned as `{ ok: false, error }` but must never fail the sweep.
- */
+/** Best-effort base fast-forward; never throws, never fails the sweep. */
 function runFastForwardStep({
   cwd,
   baseBranch,
@@ -453,17 +379,8 @@ function runFastForwardStep({
 }
 
 /**
- * Iterate plan candidates and split them into `reapable` (safe to pass
- * to executeCleanup) and `protectedList` (skipped, with a reason).
- *
- * Protection failures are treated as protected — never reap a candidate
- * whose state we cannot verify. The reason string travels into the
- * result envelope and the log line for postmortem clarity.
- *
- * When no `protectionCtx` is supplied (legacy callers, unit tests),
- * the protection check is bypassed entirely and every candidate is
- * reapable. The boot-path CLI surfaces always supply a ctx, so this
- * fallback never fires in production.
+ * A protection-eval error counts as protected: never reap what cannot be
+ * verified. No `protectionCtx` (tests only) bypasses protection.
  */
 async function partitionCandidates({
   candidates,

package/.agents/scripts/lib/skills/parse-skill.js

@@ -1,26 +1,8 @@
 // .agents/scripts/lib/skills/parse-skill.js
 //
-// Shared SKILL.md parser used by the skills index generator and the skills
-// validator. Pure I/O on top of a single fs.readFileSync — no network, no
-// child processes, no env reads. Tolerant of CRLF and LF line endings.
-//
-// Public API:
-//
-//   parseSkill(absolutePath, options?) -> {
-//     path,            // repo-relative POSIX path (string)
-//     tier,            // 'core' | 'stack'
-//     category,        // bucket directly under the tier (string)
-//     name,            // parent directory name of SKILL.md (string)
-//     frontmatter,     // YAML-parsed object from between the leading '---' markers
-//     policyCapsule: {
-//       found,         // boolean — true iff a '## Policy Capsule' heading exists
-//       bulletCount,   // integer — count of contiguous top-level '- ' bullets
-//       sectionStart,  // 1-based line number of the heading (null when absent)
-//     },
-//   }
-//
-// The parser asserts that frontmatter.name equals the parent directory name
-// and throws a descriptive Error when the two diverge.
+// Shared SKILL.md parser (CRLF/LF tolerant) returning
+// { path, tier, category, name, frontmatter, policyCapsule }. Throws when
+// frontmatter.name differs from the parent directory name.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -30,14 +12,11 @@ const FRONTMATTER_DELIMITER = '---';
 const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
 const ANY_H2_RE = /^## /;
 const BULLET_RE = /^- /;
-/** An indented (wrapped) continuation of the bullet above it. */
 const CONTINUATION_RE = /^\s+\S/;
 
 /**
- * Repo root resolver. Walks up from the SKILL.md path until we find a
- * directory that contains an `.agents/skills` folder — that's the canonical
- * marker. Falls back to the file's grandparent's grandparent if no marker
- * is found, which is good enough for tests using temp fixtures.
+ * Nearest ancestor holding `.agents/skills`; fixture trees fall back to four
+ * levels up.
  */
 function resolveRepoRoot(absoluteSkillPath) {
   let dir = path.dirname(absoluteSkillPath);
@@ -47,7 +26,6 @@ function resolveRepoRoot(absoluteSkillPath) {
     }
     dir = path.dirname(dir);
   }
-  // Fallback for fixture trees rooted outside a real .agents layout.
   return path.resolve(path.dirname(absoluteSkillPath), '..', '..', '..', '..');
 }
 
@@ -55,19 +33,11 @@ function toPosix(p) {
   return p.split(path.sep).join('/');
 }
 
-/**
- * Split the source on either CRLF or LF without normalizing line endings.
- * The returned array's length and indices match the original file's line
- * count, which lets callers report 1-based line numbers verbatim.
- */
+/** Indices match the file's lines, so 1-based line numbers report verbatim. */
 function splitLines(src) {
   return src.split(/\r\n|\n/);
 }
 
-/**
- * Extract the YAML frontmatter block sitting between the first two '---'
- * lines. Throws when the file lacks a leading delimiter or never closes it.
- */
 function extractFrontmatterBlock(lines, skillPath) {
   if (lines[0] !== FRONTMATTER_DELIMITER) {
     throw new Error(
@@ -85,16 +55,10 @@ function extractFrontmatterBlock(lines, skillPath) {
 }
 
 /**
- * Scan the body for the '## Policy Capsule' heading and count contiguous
- * top-level '- ' bullets that follow it, stopping at the next '## ' heading
- * or end-of-file. Blank lines inside the bullet run do not reset the count.
- *
- * An **indented** continuation line belongs to the bullet above it — capsule
- * bullets routinely wrap at the document's prose width — so it neither counts
- * as a new bullet nor terminates the run. Only a **flush-left**, non-blank,
- * non-bullet line after the run terminates it (Story #4546: treating any
- * non-bullet line as a terminator counted a wrapped 5-bullet capsule as 1 and
- * tripped the floor in validate-skills.js).
+ * Count top-level `- ` bullets under `## Policy Capsule` up to the next H2.
+ * Blank lines and indented (wrapped) continuations stay inside the run; only
+ * a flush-left non-bullet line after it terminates — otherwise a wrapped
+ * capsule would count as one bullet and trip the validator's floor.
  */
 function findPolicyCapsule(lines, bodyStart) {
   let headingIndex = -1;
@@ -119,19 +83,15 @@ function findPolicyCapsule(lines, bodyStart) {
       continue;
     }
     if (line.trim() === '') {
-      // Blank lines inside or before the bullet run are tolerated.
       continue;
     }
     if (sawBulletRun && CONTINUATION_RE.test(line)) {
-      // Indented continuation of the bullet above — same bullet, not a
-      // terminator. Wrapped capsule bullets are the norm, not an error.
       continue;
     }
     if (sawBulletRun) {
-      // Flush-left, non-blank, non-bullet line after the run terminates it.
       break;
     }
-    // Leading prose between heading and the first bullet is allowed.
+    // Leading prose before the first bullet is allowed.
   }
 
   return {
@@ -141,9 +101,6 @@ function findPolicyCapsule(lines, bodyStart) {
   };
 }
 
-/**
- * Parse a SKILL.md file. See module-level docstring for the return shape.
- */
 export function parseSkill(absolutePath, options = {}) {
   if (typeof absolutePath !== 'string' || absolutePath.length === 0) {
     throw new TypeError('parseSkill: absolutePath must be a non-empty string');
@@ -187,11 +144,8 @@ export function parseSkill(absolutePath, options = {}) {
     );
   }
 
-  // Derive tier / category from the path. Layout is:
-  //   <repo>/.agents/skills/<tier>/<...buckets>/<name>/SKILL.md
-  // For core skills the bucket is the literal 'core' (one level deep);
-  // for stack skills the bucket is the first segment under 'stack'
-  // (e.g. 'backend', 'frontend', 'qa').
+  // <repo>/.agents/skills/<tier>/<...buckets>/<name>/SKILL.md — core's
+  // category is 'core'; stack's is the first bucket under 'stack'.
   const relPath = toPosix(path.relative(repoRoot, absolutePath));
   const parts = relPath.split('/');
   const skillsIdx = parts.indexOf('skills');

package/.agents/scripts/lib/skills/skills-index.js

@@ -1,25 +1,15 @@
 // .agents/scripts/lib/skills/skills-index.js
 //
-// Shared I/O for the two skills manifests (Story #5135).
-//
-// Each skills root carries its own `skills.index.json`: the package payload's
-// at `.agents/skills/`, and the consumer-writable zone's at
-// `.agents/local/skills/`. The shipped one is a committed payload file that
-// `mandrel doctor` / `mandrel sync-agents` compare byte-for-byte against the
-// installed package, so the two manifests must never be merged — but they are
-// read, compared and reported identically, and both CLIs need that logic.
-// Before this module `generate-skills-index.js` and `validate-skills.js`
-// each carried their own near-identical reader.
+// Shared I/O for the two skills manifests (payload and local zone). They are
+// read, compared and audited identically but never merged: the shipped one is
+// compared byte-for-byte against the installed package.
 
 import fs from 'node:fs';
 import path from 'node:path';
 
-/** Manifest filename, shared by both roots. */
 export const INDEX_FILENAME = 'skills.index.json';
 
 /**
- * Absolute path of the manifest for one skills root.
- *
  * @param {string} repoRoot
  * @param {readonly string[]} rootSegments From `walk-skill-files.js`.
  * @returns {string}
@@ -29,9 +19,7 @@ export function indexPathFor(repoRoot, rootSegments) {
 }
 
 /**
- * Read a manifest from disk. Distinguishes "missing" from "unparseable" via
- * the `reason` channel so callers can report which drift they hit rather than
- * collapsing both into "not fresh".
+ * `reason` separates "missing" from "unparseable" so callers can say which.
  *
  * @param {string} indexPath
  * @returns {{ manifest: object | null, reason: string | null }}
@@ -54,9 +42,6 @@ export function readManifest(indexPath) {
 }
 
 /**
- * Read a manifest and project its entry paths into a Set, the shape the
- * validator's membership check consumes.
- *
  * @param {string} indexPath
  * @returns {{ exists: boolean, paths: Set<string> | null, manifest: object | null, indexPath: string, parseError?: string }}
  */
@@ -83,9 +68,7 @@ export function readIndexPaths(indexPath) {
 }
 
 /**
- * Compare two manifests ignoring `generatedAt` — the one volatile field, which
- * changes on every write and is not content. Returns null when they match, or
- * a diff-style message naming the entry counts.
+ * Ignores the volatile `generatedAt`; `null` when the manifests match.
  *
  * @param {object | null} diskManifest
  * @param {object} freshManifest
@@ -111,12 +94,10 @@ export function diffManifests(diskManifest, freshManifest, label) {
 }
 
 /**
- * Render a manifest's schema violations as field-named findings. The compiled
- * AJV validator is passed in so this module stays free of the schema-loading
- * side effects the validator CLI owns.
+ * The validator is injected so this module avoids schema-loading side effects.
  *
  * @param {object} manifest
- * @param {string} indexRelPath Repo-relative manifest path, for the message.
+ * @param {string} indexRelPath
  * @param {(m: object) => boolean} validateManifest Compiled AJV validator.
  * @returns {string[]}
  */
@@ -133,9 +114,7 @@ function validateManifestSchema(manifest, indexRelPath, validateManifest) {
 }
 
 /**
- * Audit one root's manifest: present, parseable, and schema-valid. Shared by
- * both skills roots so a consumer-authored index is held to the same bar as
- * the shipped one.
+ * Present, parseable and schema-valid — the same bar for both roots.
  *
  * @param {{ exists: boolean, paths: Set<string> | null, manifest: object | null, parseError?: string }} indexInfo
  * @param {string} indexRelPath

package/.agents/scripts/lib/skills/walk-skill-files.js

@@ -1,37 +1,20 @@
 // .agents/scripts/lib/skills/walk-skill-files.js
 //
-// Shared traversal for SKILL.md files across the two skills roots:
-// the package payload (`.agents/skills/{core,stack}/`) and the
-// consumer-writable local zone (`.agents/local/skills/{core,stack}/`).
-// Used by validate-skills.js and generate-skills-index.js so both CLIs
-// enumerate the same paths in the same deterministic order.
-//
-// The two roots stay **separately enumerable** on purpose (Story #5135).
-// `.agents/skills/skills.index.json` is a committed payload file that
-// `mandrel doctor` / `mandrel sync-agents` compare byte-for-byte against
-// the installed package; folding a consumer's local skills into it would
-// make every consumer's regenerated index read as payload drift and cause
-// those commands to refuse. The local zone therefore carries its own
-// index artifact, and the two roots are unified only at *lookup* time, by
-// `resolveSkillFile` — never for the shipped manifest.
+// SKILL.md traversal over the payload root and the consumer-writable local
+// zone, in deterministic order. The roots stay separately enumerable: the
+// shipped skills.index.json is compared byte-for-byte against the package, so
+// folding local skills into it would read as payload drift. They are unified
+// only at lookup time, by resolveSkillFile.
 
 import fs from 'node:fs';
 import path from 'node:path';
 
-/** Tier directories a skills root is enumerated under. */
 const TIERS = Object.freeze(['core', 'stack']);
 
-/**
- * Path segments (from the repo root) of the package-payload skills root.
- * Materialized by `mandrel sync`; every file under it is payload.
- */
 export const PAYLOAD_SKILLS_SEGMENTS = Object.freeze(['.agents', 'skills']);
 
 /**
- * Path segments (from the repo root) of the consumer-writable skills root.
- * It sits inside the `.agents/local/` zone (Story #3498), which sync never
- * copies into and never prunes, and which the agents-drift check cannot
- * flag because that check only walks files present in the package payload.
+ * Inside `.agents/local/`, which sync never touches and drift checks never walk.
  */
 export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
   '.agents',
@@ -40,27 +23,14 @@ export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
 ]);
 
 /**
- * A skill id is the tier-relative path naming a skill — e.g.
- * `core/test-first` or `stack/qa/playwright`. It is the value that
- * appears in `skills.index.json` minus the root prefix, and the value a
- * `qa.environments.*.signInSeam.skill` seam carries.
- *
- * The pattern is deliberately strict: ids resolve to filesystem paths, so
- * anything that could escape a root (`..`, absolute paths, backslashes) or
- * smuggle a shell metacharacter is rejected rather than normalized.
- *
- * Exported because `config-settings-schema.js` mirrors it as the `pattern`
- * on `qa.environments.*.signInSeam.skill`, so a malformed id is rejected at
- * config-validation time rather than surviving to a path join (Story #5285).
- * It is one regex with two enforcement points, never two regexes: the AJV
- * `pattern` keyword takes the source string, so the schema must import this
- * value rather than restate it.
+ * A tier-relative skill id (`stack/qa/playwright`). Strict because ids become
+ * filesystem paths: anything that could escape a root is rejected, not
+ * normalized. The config schema imports this as its `pattern` — one regex,
+ * two enforcement points.
  */
 export const SKILL_ID_RE = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)+$/;
 
 /**
- * Recursively enumerate `SKILL.md` paths under a directory.
- *
  * @param {string} rootDir
  * @returns {string[]} absolute paths
  */
@@ -89,9 +59,6 @@ function walkSkillFiles(rootDir) {
 }
 
 /**
- * Sort absolute paths by their POSIX repo-relative form so output order is
- * deterministic across platforms.
- *
  * @param {string[]} files
  * @param {string} repoRoot
  * @returns {string[]}
@@ -105,9 +72,6 @@ function sortByRepoRelative(files, repoRoot) {
 }
 
 /**
- * Enumerate the `SKILL.md` files under one skills root, sorted by POSIX
- * repo-relative path.
- *
  * @param {string} repoRoot
  * @param {readonly string[]} rootSegments One of the exported segment lists.
  * @returns {string[]} absolute paths
@@ -121,11 +85,7 @@ function collectUnderRoot(repoRoot, rootSegments) {
 }
 
 /**
- * Build the list of payload SKILL.md files under
- * `<repoRoot>/.agents/skills/{core,stack}/`.
- *
- * This is the set the **shipped** `skills.index.json` is generated from —
- * it must never include local-zone skills (see the module header).
+ * The set the shipped index is generated from — never local-zone skills.
  *
  * @param {string} repoRoot
  * @returns {string[]} absolute paths
@@ -135,11 +95,6 @@ export function collectSkillFiles(repoRoot) {
 }
 
 /**
- * Build the list of consumer-authored SKILL.md files under
- * `<repoRoot>/.agents/local/skills/{core,stack}/`. Empty when the
- * consumer has authored none — the common case, and the case in this
- * repository itself.
- *
  * @param {string} repoRoot
  * @returns {string[]} absolute paths
  */
@@ -148,26 +103,14 @@ export function collectLocalSkillFiles(repoRoot) {
 }
 
 /**
- * Resolve a skill id to a readable `SKILL.md`, searching the payload root
- * first and the local zone second (payload-wins, matching
- * {@link collectAllSkillFiles}).
- *
- * Returns rather than throwing so callers own the error message — a config
- * resolver wants to name the offending config key, a workflow wants to name
- * the seam. The two failures are **distinguishable** (Story #5285):
- *
- *   - `null` — a well-formed id that resolves under neither root. The remedy
- *     is to author the skill, so the caller says so.
- *   - `{ reason: 'invalid-id' }` — an id the pattern rejects (`../../secrets`,
- *     `Core/Foo`, a bare `core`). No filesystem lookup happens, and telling
- *     the operator to author `../../secrets/SKILL.md` would be advice that
- *     cannot be followed. The remedy is to fix the id.
+ * Payload root first, then local (payload wins). Returns rather than throws
+ * so the caller names the offending key; `null` (author the skill) and
+ * `{ reason: 'invalid-id' }` (fix the id; nothing was searched) need
+ * different remedies.
  *
  * @param {string} repoRoot
  * @param {string} skillId Tier-relative id, e.g. `stack/qa/acme-sso`.
  * @returns {{ path: string, root: string } | { reason: 'invalid-id' } | null}
- *   the absolute `SKILL.md` path and the POSIX repo-relative root it resolved
- *   under, the malformed-id marker, or `null` when nothing resolved.
  */
 export function resolveSkillFile(repoRoot, skillId) {
   if (typeof skillId !== 'string' || !SKILL_ID_RE.test(skillId)) {
@@ -180,17 +123,13 @@ export function resolveSkillFile(repoRoot, skillId) {
         return { path: candidate, root: segments.join('/') };
       }
     } catch {
-      // Unreadable or absent — try the next root.
+      // Absent — try the next root.
     }
   }
   return null;
 }
 
-/**
- * The POSIX repo-relative skills roots, in search order. Exported so error
- * messages can name exactly what was searched rather than restating the
- * paths as literals.
- */
+/** POSIX repo-relative roots in search order, for error messages. */
 export const SKILL_SEARCH_ROOTS = Object.freeze([
   PAYLOAD_SKILLS_SEGMENTS.join('/'),
   LOCAL_SKILLS_SEGMENTS.join('/'),

package/.agents/scripts/lib/source-extensions.js

@@ -1,45 +1,17 @@
 /**
- * source-extensions.js — the single source of truth for which file extensions
- * the CRAP and maintainability scanners score.
+ * SSOT for the extensions the CRAP/MI scanners score. The scanner walk, the
+ * coverage-freshness check and the CRAP projection filter must all agree: a
+ * narrower selector makes a gate green while measuring nothing. Not
+ * configurable, for the same reason.
  *
- * Three surfaces select "the files the scanner scores" and must agree, because
- * a selector narrower than the scanner's own walk makes a gate green while
- * measuring nothing: the maintainability/CRAP directory walk
- * (`maintainability-utils.js`), the coverage-freshness check
- * (`coverage-capture.js`), and the close-validation CRAP projection's
- * changed-file filter (`close-validation/projections/crap.js`). Story #5076
- * folded all three onto the set below after a TypeScript consumer's entire
- * source tree was filtered out of the freshness check by a `js|mjs`-only
- * literal.
- *
- * **This module MUST import nothing outside `node:` builtins.**
- * `coverage-capture.js` runs on the pre-push path; `maintainability-utils.js`
- * transitively pulls `typhonjs-escomplex` and `typescript`, so the shared set
- * cannot live there without dragging the scoring engines into every freshness
- * probe.
- *
- * The set is deliberately *not* configurable. Freshness exists only to serve
- * the CRAP gate, so the contract is "what the scanner walks" — a
- * consumer-settable extension list would be a second way to mis-scope the same
- * gate.
- *
- * Not to be confused with `transpile.js`'s `TS_EXTS`, which answers a
- * different question ("does this file need transpiling before scoring?") and
- * is correctly a subset of this set rather than a fork of it.
+ * MUST import only `node:` builtins — it runs on the pre-push path and must
+ * not drag the scoring engines in.
  */
 import path from 'node:path';
 
 /**
- * Extensions the CRAP and maintainability engines can score, lower-cased and
- * dot-prefixed. Frozen so a caller cannot mutate the shared set in place.
- *
- * Formats the engines cannot parse — `.astro`, `.vue`, `.svelte` — are
- * deliberately absent: this set selects what the scanner already scores, not
- * every source file that exists in a consumer's tree.
- *
- * Module-private: production consumers select through {@link
- * SCORABLE_SOURCE_EXT_RE} or {@link isScorableSourceFile}, so exporting the
- * raw list would be a dead production export.
+ * What the engines can parse (not `.vue`/`.svelte`/`.astro`). Private: select
+ * via the exported regex or predicate.
  *
  * @type {readonly string[]}
  */
@@ -54,10 +26,7 @@ const SCORABLE_SOURCE_EXTENSIONS = Object.freeze([
 ]);
 
 /**
- * Anchored pattern matching a scorable source path by extension, derived from
- * {@link SCORABLE_SOURCE_EXTENSIONS} so the list stays the only definition.
- * Use it where a path arrives as raw text (a `git ls-files` line, a porcelain
- * status entry) and `path.extname` would be the wrong tool.
+ * For paths arriving as raw text (git output lines).
  *
  * @type {RegExp}
  */
@@ -66,8 +35,8 @@ export const SCORABLE_SOURCE_EXT_RE = new RegExp(
 );
 
 /**
- * @param {string} filePath Absolute or relative path; only its extension is read.
- * @returns {boolean} True when the path's extension is one the engines score.
+ * @param {string} filePath
+ * @returns {boolean}
  */
 export function isScorableSourceFile(filePath) {
   return SCORABLE_SOURCE_EXTENSIONS.includes(