mandrel 2.37.0 → 2.39.0

package/.agents/scripts/plan-run-epilogue.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * plan-run-epilogue.js — execute the real per-run closeout for a
- * multi-Story `/deliver`.
+ * multi-Story `/mandrel-deliver`.
  *
  * Usage:
  *   node .agents/scripts/plan-run-epilogue.js --stories 1,2,3
@@ -67,7 +67,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
   // along with the label itself. The epilogue is keyed on the delivered id
   // set, and the synthesized `adhoc-<ids>` id it already used for positional
   // runs is now the only id it needs.
-  // Range tokens expand here too (`--stories 101-104`): /deliver blesses the
+  // Range tokens expand here too (`--stories 101-104`): /mandrel-deliver blesses the
   // dash range at the operator surface, so the id set the epilogue is keyed on
   // must read the same shape. Rejecting a bad token is deliberate — the old
   // silent filter turned a typo into an empty, wrongly-keyed rollup.

package/.agents/scripts/providers/github/board-add.js

@@ -3,7 +3,7 @@
  *
  * Story #3822 — single source of truth for the post-create board-add
  * step. Issues created through any create path (`createTicket`,
- * `createIssue` — which backs `/plan` persist and the `/plan`
+ * `createIssue` — which backs `/mandrel-plan` persist and the `/mandrel-plan`
  * Phase 4 Epic open) must land on the configured Projects V2 board
  * without relying on GitHub's "Auto-add to project" built-in workflow,
  * which is off by default on fresh boards and cannot be enabled via API.

package/.agents/scripts/providers/github/errors.js

@@ -156,7 +156,7 @@ export function classifyGithubError(err) {
 // Read-path callers (paginateRest, getTicket, getNativeSubIssues, …) all
 // absorb the same jittered exponential backoff on transient GitHub errors
 // through this one primitive, instead of bubbling a one-shot
-// 502/429/ECONNRESET that kills a longer pipeline (e.g. the /deliver
+// 502/429/ECONNRESET that kills a longer pipeline (e.g. the /mandrel-deliver
 // Phase E retro). The network consumers repointed here
 // (branch-protection, labels, projects-v2-graphql) call with no opts, so
 // they adopt these defaults; their retry *classes* (the network blips) are

package/.agents/scripts/providers/github/tickets.js

@@ -15,7 +15,7 @@
  * Epic-hierarchy write surface. It composed the exact `Epic: #N` footer that
  * `pr-base-guard.js` hard-refuses at delivery, so the framework retained the
  * ability to generate work it would then reject; it had no production caller
- * (`/plan` persists through the bare `createIssue` below).
+ * (`/mandrel-plan` persists through the bare `createIssue` below).
  *
  * Public surface: `GitHubProvider.createIssue / getTicket /
  * getTickets / updateTicket / getTicketDependencies / primeTicketCache /
@@ -251,8 +251,8 @@ export class TicketGateway {
 
   /**
    * Create a **bare** issue — no footer composition and no sub-issue link.
-   * Since Story #4545 this is the *only* create path: `/plan` persist and the
-   * `/plan` Phase 4 Epic open (`openEpicFromOnePager`'s `createIssue` port)
+   * Since Story #4545 this is the *only* create path: `/mandrel-plan` persist and the
+   * `/mandrel-plan` Phase 4 Epic open (`openEpicFromOnePager`'s `createIssue` port)
    * both route through it.
    *
    * After the POST, the new issue is added to the configured Project V2
@@ -264,13 +264,13 @@ export class TicketGateway {
    * The POST is wrapped in `withTransientRetry` (Story #4541) so it absorbs
    * the same 502/429/ECONNRESET blips the read surfaces already do. It used
    * to post bare, which made a single transient failure at story *k* of *N*
-   * abort `/plan` persist with `1..k-1` already live on the tracker.
+   * abort `/mandrel-plan` persist with `1..k-1` already live on the tracker.
    *
    * Retry alone is not sufficient for that failure mode — a POST whose
    * response is lost would double-create on the retry. Story #5112 closed
    * that: `findExisting` is consulted **before every retry POST**, and a hit
    * is adopted instead of re-created, so a response-lost first attempt files
-   * exactly one issue. `/plan` persist supplies the plan-fingerprint lookup
+   * exactly one issue. `/mandrel-plan` persist supplies the plan-fingerprint lookup
    * its resume path already uses (`plan-persist`'s `createStoryIssues`);
    * callers with no content identity omit it and keep the pre-#5112
    * retry-only behaviour.
@@ -405,7 +405,7 @@ export class TicketGateway {
    *
    * The additive POST goes through `withTransientRetry` (Story #4961) on the
    * same policy as every other call in this file. Story #4952 raised the
-   * `/plan` write loops that reach this endpoint — the `agent::ready` flips
+   * `/mandrel-plan` write loops that reach this endpoint — the `agent::ready` flips
    * and the checkpoint fan-out — off serial, which is precisely what makes
    * GitHub's secondary rate limit likelier; `gh-exec` already classifies that
    * as transient, so the only thing missing was a backoff behind it.

package/.agents/scripts/quality-preview.js

@@ -12,9 +12,18 @@
  *   2. `npm run quality:watch`     — chokidar wrapper re-emits on save.
  *   3. `.husky/pre-commit`         — block the commit on threshold violations.
  *
- * Story #1394 (Epic #1386) flipped the default scope of both gates to
- * diff-against-`main`, so passing `--changed-since HEAD` here mirrors what the
- * pre-commit hook actually wants: the delta the operator is about to commit.
+ * The pre-commit hook passes `--staged` and nothing else — the index is
+ * already the exact delta the operator is about to commit, and
+ * `tests/pre-commit-hook.test.js` pins that `--changed-since` stays off it.
+ * (This docblock previously claimed the hook passed `--changed-since HEAD`,
+ * describing a wiring the hook has not used for some time; the stale prose
+ * sent at least one bug report at the wrong flag — Story #5131.)
+ *
+ * `--staged` is merge-aware: while a merge is in progress the index is read
+ * against `MERGE_HEAD` rather than `HEAD`, so a base-sync merge commit is
+ * scored for the merging branch's own work and its conflict resolutions, not
+ * for everything the base branch landed. See `resolveMergeHead` in
+ * `lib/changed-files.js`.
  *
  * The CLI exits 0 when both envelopes report zero violations and the script
  * could not surface a regression. Any violation in either envelope, or any
@@ -29,6 +38,7 @@ import {
   runCrapPreview,
   runMaintainabilityPreview,
 } from './lib/baselines/preview-gates.js';
+import { resolveMergeHead } from './lib/changed-files.js';
 import { respondToHelp } from './lib/cli-usage.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import { resolveCyclomaticPolicy } from './lib/cyclomatic-ceiling.js';
@@ -39,7 +49,10 @@ const USAGE = {
   summary:
     'Preview the per-file maintainability and CRAP deltas for the change set, and exit non-zero on any threshold violation.',
   flags: [
-    ['--staged', 'Score the git index only (the pre-commit-hook scope).'],
+    [
+      '--staged',
+      'Score the git index only (the pre-commit-hook scope). During a merge the index is read against MERGE_HEAD.',
+    ],
     [
       '--changed-since <ref>',
       'Score the diff against <ref> (default: HEAD). Last occurrence wins.',
@@ -388,6 +401,35 @@ function runGateSafely(runner, args, label, stderr) {
   });
 }
 
+/**
+ * Render the scope header line.
+ *
+ * Story #5131 — when `--staged` runs during a merge the scope is re-based to
+ * `MERGE_HEAD`, and the header says so. Without that line the operator sees a
+ * table whose row count does not match `git diff --cached` with no way to tell
+ * the narrowing was deliberate.
+ *
+ * The merge state is resolved here rather than read back off a gate envelope's
+ * `summary.diffRef`: that field means "the ref this scope was resolved
+ * against" for every scope kind, so anything that populates it — a future
+ * scope mode, a test stub — would render a merge banner over a repo that is
+ * not merging. Resolving it after the `!staged` early return also keeps the
+ * probe off the `--changed-since` path, which has no use for it.
+ *
+ * @param {{ staged: boolean, ref: string|null, cwd: string }} args
+ * @returns {string}
+ */
+function stagedScopeLine({ staged, ref, cwd }) {
+  if (!staged) return `scope=diff ref=${ref}\n\n`;
+  const mergeHead = resolveMergeHead({ cwd });
+  if (!mergeHead) return 'scope=staged (git diff --cached)\n\n';
+  return (
+    `scope=staged (git diff --cached ${mergeHead.slice(0, 12)}) — merge in ` +
+    "progress: scored against MERGE_HEAD, not HEAD, so the base branch's " +
+    'incoming files are excluded\n\n'
+  );
+}
+
 /**
  * Write the run's report — the `--json` envelope, or the human-readable
  * table plus any gate diagnostics and the non-zero-exit summary.
@@ -401,6 +443,7 @@ function runGateSafely(runner, args, label, stderr) {
  *   json: boolean,
  *   staged: boolean,
  *   ref: string|null,
+ *   cwd: string,
  *   miResult: {exitCode: number, envelope: object|null},
  *   crapResult: {exitCode: number, envelope: object|null},
  *   merged: ReturnType<typeof mergeEnvelopes>,
@@ -413,6 +456,7 @@ function emitReport({
   json,
   staged,
   ref,
+  cwd,
   miResult,
   crapResult,
   merged,
@@ -438,11 +482,7 @@ function emitReport({
     return;
   }
   stdout.write('\n--- quality:preview ---\n');
-  stdout.write(
-    staged
-      ? 'scope=staged (git diff --cached)\n\n'
-      : `scope=diff ref=${ref}\n\n`,
-  );
+  stdout.write(stagedScopeLine({ staged, ref, cwd }));
   stdout.write(`${renderTable(merged)}\n`);
   const diagnostics = renderDiagnostics([miResult, crapResult]);
   if (diagnostics) stdout.write(`\n${diagnostics}\n`);
@@ -518,6 +558,7 @@ export async function runCli({
     json,
     staged,
     ref,
+    cwd,
     miResult,
     crapResult,
     merged,

package/.agents/scripts/resolve-stories.js

@@ -2,9 +2,9 @@
 
 /**
  * resolve-stories.js — resolve a list of Story ids into the
- * `{ stories, dag, done }` envelope `/deliver` sequences from.
+ * `{ stories, dag, done }` envelope `/mandrel-deliver` sequences from.
  *
- * This is the ONE resolution step for multi-Story delivery. `/deliver` takes
+ * This is the ONE resolution step for multi-Story delivery. `/mandrel-deliver` takes
  * only Story ids; the graph is discovered here, from live state, rather than
  * hand-transcribed by the host or implied by a batch label.
  *
@@ -63,7 +63,7 @@ const HELP = `\
 Usage:
   resolve-stories.js --ids <n,n,...> [--pretty] [--no-native]
 
-Resolve Story ids into the { stories, dag, done } envelope /deliver sequences
+Resolve Story ids into the { stories, dag, done } envelope /mandrel-deliver sequences
 from. Dependencies are discovered from live state: body edges union native
 blocked_by edges, with every blocker (in-set or foreign) resolved against its
 real issue state.

package/.agents/scripts/resync-status-column.js

@@ -5,7 +5,7 @@
  * resync-status-column.js — re-assert the GitHub Projects v2 Status
  * column for a ticket after auto-merge has fired (Story #2845).
  *
- * The `/single-story-deliver` and `/deliver` workflow docs call
+ * The `/single-story-deliver` and `/mandrel-deliver` workflow docs call
  * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
  * wins the race against the GitHub built-in `Pull request merged`
  * workflow, which would otherwise overwrite Status to whatever value

package/.agents/scripts/run-lint.js

@@ -84,7 +84,7 @@ const tasks = [
   nodeGate('lifecycle-lint', '.agents/scripts/check-lifecycle-lint.js'),
   // Workflow prose surface (Epic #4474 PR5). No workflow may instruct calling
   // an exported library function that has no CLI entrypoint — the measured
-  // shim-writing failure mode the /plan collapse killed. See
+  // shim-writing failure mode the /mandrel-plan collapse killed. See
   // check-workflow-cli-lint.js for the paragraph-level heuristic.
   nodeGate('workflow-cli-lint', '.agents/scripts/check-workflow-cli-lint.js'),
   // Label-vocabulary citations in `.agents/docs/SDLC.md` and

package/.agents/scripts/single-story-close.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * single-story-close.js — Close a Story against `main` (v2 `/deliver` path).
+ * single-story-close.js — Close a Story against `main` (v2 `/mandrel-deliver` path).
  *
- * Thin CLI entry for `/deliver` / `helpers/deliver-story`. Opens a PR from
+ * Thin CLI entry for `/mandrel-deliver` / `helpers/deliver-story`. Opens a PR from
  * `story-<id>` to `project.baseBranch`, runs Story-scope review, and arms
  * auto-merge. There is no Epic parent, epic-merge-lock, or wave merge.
  *

package/.agents/scripts/single-story-init.js

@@ -2,7 +2,7 @@
 /* node:coverage ignore file */
 
 /**
- * single-story-init.js — Initialize a Story for v2 `/deliver`.
+ * single-story-init.js — Initialize a Story for v2 `/mandrel-deliver`.
  *
  * Seeds `story-<id>` from `project.baseBranch` (default `main`), materialises
  * the per-Story worktree when isolation is enabled, upserts a `story-init`
@@ -122,7 +122,7 @@ export function assertDeliverableStory(story, storyId) {
   if (!story.labels.includes(TYPE_LABELS.STORY)) {
     throw new Error(
       `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). ` +
-        'v2 /deliver accepts type::story tickets only.',
+        'v2 /mandrel-deliver accepts type::story tickets only.',
     );
   }
   if (story.state === 'closed') {
@@ -132,7 +132,7 @@ export function assertDeliverableStory(story, storyId) {
   if (/\b(?:Epic|Parent):\s*#\d+/i.test(body)) {
     throw new Error(
       `Story #${storyId} still declares an Epic/Parent footer. ` +
-        'v2 delivery is Story-only — re-plan as a standalone Story before /deliver.',
+        'v2 delivery is Story-only — re-plan as a standalone Story before /mandrel-deliver.',
     );
   }
 }
@@ -189,7 +189,7 @@ export async function assertNotForeignExecuting({
       (lease.previousOwner
         ? ` (assignee @${lease.previousOwner})`
         : ' with no assignee') +
-      '. Another /deliver run may already own it. Confirm that run is dead, ' +
+      '. Another /mandrel-deliver run may already own it. Confirm that run is dead, ' +
       'then re-run with --steal to take it.',
   );
 }
@@ -607,7 +607,7 @@ export async function runSingleStoryInit({
   );
   progress('INIT', `Initializing standalone Story #${storyId}...`);
 
-  // Issue #4483 — deterministic remote evidence at the v2 `/deliver` entry
+  // Issue #4483 — deterministic remote evidence at the v2 `/mandrel-deliver` entry
   // seam (`single-story-init.js`). The
   // probe is read-only, so it runs under --dry-run too. The CLI records
   // the fact; the workflow owns the `agent::blocked` transition on

package/.agents/scripts/stories-wave-tick.js

@@ -2,7 +2,7 @@
 
 /**
  * stories-wave-tick.js — continuous ready-set planner for the standalone
- * `/deliver` story-list path.
+ * `/mandrel-deliver` story-list path.
  *
  * Thin **adapter** over the path-agnostic ready-set scheduling core
  * (`lib/wave-runner/ready-set.js#planReadySet`). It emits the set of
@@ -21,7 +21,7 @@
  * **Two modes, one kernel.**
  *
  *   - **Probe mode** (`--stories <csv> --probe-live [--dispatched <csv>]`) is
- *     the canonical `/deliver` beat: the graph, the done set, and the in-flight
+ *     the canonical `/mandrel-deliver` beat: the graph, the done set, and the in-flight
  *     count are resolved from **live state** via `lib/wave-runner/live-probe.js`.
  *     The caller supplies ids, so there is no accounting to hand-maintain
  *     across beats — the seed-the-first-beat's-`--done` footgun the workflow
@@ -97,14 +97,14 @@
  * `--done` and `ready` is empty.
  *
  * The per-beat concurrency cap is resolved from the same config seam
- * `/deliver` uses — `resolveConfig` + `getRunners` reading
+ * `/mandrel-deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
  * overrides the config-resolved value for that run only, and the envelope's
  * `capPrecedence` names which source won so the override is never silent
  * (Story #4875). This shares one
  * deterministic config source (`delivery.deliverRunner.concurrencyCap`) and
- * one scheduling kernel with every `/deliver` multi-Story invocation.
+ * one scheduling kernel with every `/mandrel-deliver` multi-Story invocation.
  *
  * Exit codes: 0 ok · 1 input error · 2 dependency cycle (`cycleError`) ·
  * 3 wedged (`wedged`) — ready is empty, nothing is in flight, and undone
@@ -170,7 +170,7 @@ and the same file-overlap guard as planReadySet.
 
 Two modes:
   --probe-live  Resolve the graph and derive done / in-flight from LIVE state
-                (the canonical /deliver beat). Nothing is hand-maintained
+                (the canonical /mandrel-deliver beat). Nothing is hand-maintained
                 across beats. Mutually exclusive with --dag/--dag-file/--done/
                 --in-flight. Adds "done" and "epilogueDue" to the envelope.
   --dag         Legacy flag mode: the caller supplies the graph and the run
@@ -662,7 +662,7 @@ export function parseConcurrencyOverride(raw) {
 /**
  * Resolve the per-beat concurrency cap.
  *
- * Mirrors the `/deliver` multi-Story seam (`helpers/deliver-story.md`): resolve the
+ * Mirrors the `/mandrel-deliver` multi-Story seam (`helpers/deliver-story.md`): resolve the
  * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
  * then read `delivery.deliverRunner.concurrencyCap` via `getRunners` (default
  * 3). An explicit `override` (the `--concurrency <n>` CLI flag) wins over
@@ -855,7 +855,7 @@ export function buildReadySetEnvelope(
     return {
       envelope: {
         ...base,
-        cycleError: `Dependency cycle detected: ${cycle.join(' → ')}. Fix the depends_on declarations before running /deliver.`,
+        cycleError: `Dependency cycle detected: ${cycle.join(' → ')}. Fix the depends_on declarations before running /mandrel-deliver.`,
       },
       exitCode: 2,
     };
@@ -1087,7 +1087,7 @@ export function runStoriesWaveTick({
  *
  * This is the flag-free beat. The caller supplies only the Story ids it was
  * asked to deliver; `done` and `inFlight` are probed rather than transcribed,
- * which is what makes the `/deliver` loop's old seed-the-first-beat footgun
+ * which is what makes the `/mandrel-deliver` loop's old seed-the-first-beat footgun
  * structurally impossible instead of merely documented.
  *
  * The envelope is the flag mode's, plus three probe-only fields the caller can

package/.agents/scripts/validate-skills.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
 // .agents/scripts/validate-skills.js
 //
-// Walk `.agents/skills/{core,stack}/**/SKILL.md` via the shared parser
+// Walk `SKILL.md` under both skills roots — the package payload
+// (`.agents/skills/{core,stack}/`) and the consumer-writable local zone
+// (`.agents/local/skills/{core,stack}/`, Story #5135) — via the shared parser
 // helper, validate each frontmatter block against
 // `.agents/schemas/skill.schema.json`, enforce Policy Capsule presence
-// (5–12 bullets), and verify membership in `.agents/skills/skills.index.json`
-// when that manifest exists. All findings are batched into a single
+// (5–12 bullets), and verify membership in each root's own manifest when it
+// exists. A consumer-authored skill is held to exactly the same bar as a
+// shipped one; the roots are validated separately because each carries its
+// own index (the shipped manifest is a payload file and must stay
+// payload-only — see generate-skills-index.js). All findings are batched into a single
 // human-readable report; the process exits non-zero when any finding is
 // surfaced.
 //
@@ -30,7 +35,17 @@ import { parseStandardCliArgs } from './lib/cli/standard-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
 import { parseSkill } from './lib/skills/parse-skill.js';
-import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
+import {
+  auditIndex,
+  indexPathFor,
+  readIndexPaths,
+} from './lib/skills/skills-index.js';
+import {
+  collectLocalSkillFiles,
+  collectSkillFiles,
+  LOCAL_SKILLS_SEGMENTS,
+  PAYLOAD_SKILLS_SEGMENTS,
+} from './lib/skills/walk-skill-files.js';
 
 const MIN_CAPSULE_BULLETS = 5;
 const MAX_CAPSULE_BULLETS = 12;
@@ -118,56 +133,11 @@ function buildManifestValidator(repoRoot) {
 }
 
 /**
- * Read the on-disk skills.index.json manifest, returning `{ exists, paths,
- * manifest }` where `paths` is the Set of `entry.path` values when the file
- * is present and parseable, or null otherwise.
+ * Read one root's manifest into the `{ exists, paths, manifest, indexPath }`
+ * shape the findings pass consumes.
  */
-function readIndex(repoRoot) {
-  const indexPath = path.join(
-    repoRoot,
-    '.agents',
-    'skills',
-    'skills.index.json',
-  );
-  if (!fs.existsSync(indexPath)) {
-    return { exists: false, paths: null, manifest: null, indexPath };
-  }
-  try {
-    const manifest = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
-    const paths = new Set(
-      Array.isArray(manifest.skills)
-        ? manifest.skills
-            .map((s) => s.path)
-            .filter((p) => typeof p === 'string')
-        : [],
-    );
-    return { exists: true, paths, manifest, indexPath };
-  } catch (err) {
-    return {
-      exists: true,
-      paths: null,
-      manifest: null,
-      indexPath,
-      parseError: err.message,
-    };
-  }
-}
-
-/**
- * Validate a parsed manifest against skills-index.schema.json. Returns
- * finding strings tagged with the `manifest-schema` pillar.
- */
-function validateManifestSchema(manifest, indexRelPath, validateManifest) {
-  const findings = [];
-  if (!validateManifest(manifest)) {
-    for (const err of validateManifest.errors ?? []) {
-      const where = err.instancePath || '(root)';
-      findings.push(
-        `${indexRelPath}: manifest-schema: schema violation at ${where}: ${err.message}`,
-      );
-    }
-  }
-  return findings;
+function readIndex(repoRoot, rootSegments = PAYLOAD_SKILLS_SEGMENTS) {
+  return readIndexPaths(indexPathFor(repoRoot, rootSegments));
 }
 
 /**
@@ -216,6 +186,7 @@ function rel(absPath, repoRoot) {
 /**
  * Pure entry point used by tests. Returns `{ status, output, findings }`.
  */
+
 export function run({ argv = [], repoRoot } = {}) {
   const parsed = parseArgs(argv);
   if (parsed.help) {
@@ -234,25 +205,41 @@ export function run({ argv = [], repoRoot } = {}) {
   const indexRel = rel(indexInfo.indexPath, root);
 
   const findings = [];
-  if (!indexInfo.exists) {
-    findings.push(
-      `index missing: ${indexRel} not found — run 'node .agents/scripts/generate-skills-index.js'`,
-    );
-  } else if (indexInfo.paths === null) {
-    findings.push(`index unparseable: ${indexRel} — ${indexInfo.parseError}`);
-  } else if (indexInfo.manifest !== null) {
-    findings.push(
-      ...validateManifestSchema(indexInfo.manifest, indexRel, validateManifest),
-    );
-  }
+  findings.push(
+    ...auditIndex(indexInfo, indexRel, validateManifest, { required: true }),
+  );
 
-  const skillFiles = collectSkillFiles(root);
+  const payloadFiles = collectSkillFiles(root);
   const indexPaths =
     indexInfo.exists && indexInfo.paths !== null ? indexInfo.paths : null;
-  for (const file of skillFiles) {
+  for (const file of payloadFiles) {
     findings.push(...validateOne(file, root, validateFrontmatter, indexPaths));
   }
 
+  // The local zone is optional: a repo with no consumer-authored skills has
+  // no local root and no local index, and that is a clean run, not a finding.
+  const localFiles = collectLocalSkillFiles(root);
+  if (localFiles.length > 0) {
+    const localIndexInfo = readIndex(root, LOCAL_SKILLS_SEGMENTS);
+    const localIndexRel = rel(localIndexInfo.indexPath, root);
+    findings.push(
+      ...auditIndex(localIndexInfo, localIndexRel, validateManifest, {
+        required: true,
+      }),
+    );
+    const localIndexPaths =
+      localIndexInfo.exists && localIndexInfo.paths !== null
+        ? localIndexInfo.paths
+        : null;
+    for (const file of localFiles) {
+      findings.push(
+        ...validateOne(file, root, validateFrontmatter, localIndexPaths),
+      );
+    }
+  }
+
+  const skillFiles = [...payloadFiles, ...localFiles];
+
   if (findings.length === 0) {
     Logger.info(`validate-skills: ${skillFiles.length} skill(s) passed`);
     return { status: 0, output: '', findings };

package/.agents/skills/core/idea-refinement/SKILL.md

@@ -13,7 +13,7 @@ description:
 - Phase 1 MUST restate the idea as a "How Might We" statement, ask 3–5 sharpening questions via `AskUserQuestion`, and generate 5–8 variations (never 20+ shallow ones) — each carrying a reason it exists, told as a short story, not a bare bullet. Do not proceed until target user and success criteria are explicit.
 - Phase 2 grill loop poses **one** question at a time, each with a recommended answer + one-line rationale grounded in user input / codebase / first principles; never batch questions and never omit the recommendation.
 - Re-enumerate open branches after every grill answer; stop only when no unresolved decisions remain. Take the off-ramp directly to Phase 3 when the idea is already crisply scoped. A branch consciously deferred rather than resolved records its deferral reason.
-- Phase 3 emits a markdown one-pager with the canonical five planning headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/plan` clarity gate depends on this verbatim.
+- Phase 3 emits a markdown one-pager with the canonical five planning headings exactly: `## Context`, `## Goal`, `## Non-Goals`, `## Scope`, `## Acceptance Criteria` (plus optional `## Open Questions`). No alternate heading text — the `/mandrel-plan` clarity gate depends on this verbatim.
 - Surface every key assumption inside `## Context` (or `## Scope`); assumptions do not get their own heading. Unresolved decisions MUST NOT carry into the one-pager.
 - The `## Non-Goals` list is mandatory and each entry includes a reason — focus is created by explicit exclusion.
 - Be honest, not supportive: push back on weak ideas with kindness; never function as a yes-machine.
@@ -22,10 +22,10 @@ description:
 
 ## Activation
 
-Called from [`/plan`](../../../workflows/plan.md) during ideation when the
+Called from [`/mandrel-plan`](../../../workflows/mandrel-plan.md) during ideation when the
 operator supplies `--seed "<text>"` (or runs ideation with no seed and the host
 collects one interactively). The skill sharpens freeform intent into the
-canonical planning sections that `/plan` then folds into a Story. There is no
+canonical planning sections that `/mandrel-plan` then folds into a Story. There is no
 separate Epic Clarity Gate path in v2 — N=1 Story authoring with a folded
 `## Spec` is the lean default.
 
@@ -134,9 +134,9 @@ clothes — inside the grill loop, not after the one-pager is written.
 #### Phase 3: Sharpen & Ship
 
 Produce a markdown one-pager that moves work forward. The five canonical
-headings below match `.agents/templates/epic-from-idea.md` and the `/plan`
+headings below match `.agents/templates/epic-from-idea.md` and the `/mandrel-plan`
 clarity gate; emit them verbatim so the renderer can substitute the body into a
-`/plan` Story seed without translation.
+`/mandrel-plan` Story seed without translation.
 
 ```markdown
 # [Idea Name]

package/.agents/skills/core/scope-triage/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: scope-triage
 description:
-  Optional split-advisory for `/plan`. Under v2 there is no epic|story routing
-  verdict — `/plan` always authors Stories. Use this skill only when judging
+  Optional split-advisory for `/mandrel-plan`. Under v2 there is no epic|story routing
+  verdict — `/mandrel-plan` always authors Stories. Use this skill only when judging
   whether a draft should stay one Story or legitimately split (near-zero
   overlap or an architectural seam).
 ---
@@ -11,7 +11,7 @@ description:
 
 ## Policy Capsule
 
-- There is **no** `epic | story | borderline` routing verdict in v2. `/plan`
+- There is **no** `epic | story | borderline` routing verdict in v2. `/mandrel-plan`
   is a single path that emits **one Story by default**.
 - This skill is an optional **split advisory**: should the author keep one
   Story, or does the seed clear the default-single split policy?

package/.agents/skills/skills.index.json

@@ -97,7 +97,7 @@
       "tier": "core",
       "category": "core",
       "path": ".agents/skills/core/scope-triage/SKILL.md",
-      "description": "Optional split-advisory for `/plan`. Under v2 there is no epic|story routing verdict — `/plan` always authors Stories. Use this skill only when judging whether a draft should stay one Story or legitimately split (near-zero overlap or an architectural seam).",
+      "description": "Optional split-advisory for `/mandrel-plan`. Under v2 there is no epic|story routing verdict — `/mandrel-plan` always authors Stories. Use this skill only when judging whether a draft should stay one Story or legitimately split (near-zero overlap or an architectural seam).",
       "policyCapsuleBullets": 5,
       "allowedTools": null,
       "vendor": null

package/.agents/skills/stack/qa/qa-harness/SKILL.md

@@ -170,7 +170,7 @@ Record each `F#` finding as a `QaLedgerItem` on the shared session ledger under
 `temp/qa/`, then route the ledger through the shared classify → route →
 disposition → promote core — both stated once in
 [`qa-core.md`](../../../../workflows/helpers/qa-core.md). The harness **MUST
-NOT** create tickets autonomously: findings are promoted through `/plan` only
+NOT** create tickets autonomously: findings are promoted through `/mandrel-plan` only
 after the operator confirms each disposition at the HITL write gate. That gate
 is the safety boundary against spurious filing.
 

package/.agents/workflows/audit-data-model.md

@@ -27,7 +27,7 @@ than empty findings. The applicability probe (`hasPersistenceLayer` in
 [`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js), gated
 by `target: "data-model"` in
 [`schemas/audit-rules.json`](../schemas/audit-rules.json)) makes this decision
-automatically in `/deliver` and plan-run modes; in a manual invocation you MUST
+automatically in `/mandrel-deliver` and plan-run modes; in a manual invocation you MUST
 make the same determination yourself before reading anything else.
 
 ## Scope

package/.agents/workflows/audit-documentation.md

@@ -188,7 +188,7 @@ auditable.
 ## Periodic full-scope sweep
 
 Context Economy findings accrete slowly — a doc that is lean today grows a
-bloated tail over many deliveries, and no single change-set-scoped `/deliver`
+bloated tail over many deliveries, and no single change-set-scoped `/mandrel-deliver`
 run sees the whole picture. Run this lens **full-scope** on a
 recurring cadence so the drift is caught before it compounds:
 
@@ -202,7 +202,7 @@ recurring cadence so the drift is caught before it compounds:
 Route the resulting `audit-documentation-results.md` through
 [`/audit-to-stories`](audit-to-stories.md), which groups the findings,
 deduplicates them against existing Issues by fingerprint, and opens
-remediation Stories (or chains into `/plan --seed`) so the Context-Economy
+remediation Stories (or chains into `/mandrel-plan --seed`) so the Context-Economy
 findings land as actionable, tracked work rather than a report nobody reads.
 
 ## Constraint (lens-specific carve-out)