mandrel 2.38.0 → 2.40.0

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

@@ -0,0 +1,168 @@
+// .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.
+
+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}
+ */
+export function indexPathFor(repoRoot, rootSegments) {
+  return path.join(repoRoot, ...rootSegments, INDEX_FILENAME);
+}
+
+/**
+ * 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".
+ *
+ * @param {string} indexPath
+ * @returns {{ manifest: object | null, reason: string | null }}
+ */
+export function readManifest(indexPath) {
+  if (!fs.existsSync(indexPath)) {
+    return { manifest: null, reason: 'missing' };
+  }
+  let src;
+  try {
+    src = fs.readFileSync(indexPath, 'utf8');
+  } catch (err) {
+    return { manifest: null, reason: `read-error: ${err.message}` };
+  }
+  try {
+    return { manifest: JSON.parse(src), reason: null };
+  } catch (err) {
+    return { manifest: null, reason: `parse-error: ${err.message}` };
+  }
+}
+
+/**
+ * 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 }}
+ */
+export function readIndexPaths(indexPath) {
+  const { manifest, reason } = readManifest(indexPath);
+  if (reason === 'missing') {
+    return { exists: false, paths: null, manifest: null, indexPath };
+  }
+  if (manifest === null) {
+    return {
+      exists: true,
+      paths: null,
+      manifest: null,
+      indexPath,
+      parseError: reason,
+    };
+  }
+  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 };
+}
+
+/**
+ * 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.
+ *
+ * @param {object | null} diskManifest
+ * @param {object} freshManifest
+ * @param {string} label Manifest name for the message.
+ * @returns {string | null}
+ */
+export function diffManifests(diskManifest, freshManifest, label) {
+  if (diskManifest === null) {
+    return `${label}: on-disk manifest is missing or unreadable`;
+  }
+  const a = { ...diskManifest };
+  const b = { ...freshManifest };
+  a.generatedAt = undefined;
+  b.generatedAt = undefined;
+  if (JSON.stringify(a) === JSON.stringify(b)) return null;
+  const count = (m) => (Array.isArray(m.skills) ? m.skills.length : 'n/a');
+  return [
+    `${label} drift detected:`,
+    `  on-disk entries:  ${count(diskManifest)}`,
+    `  generated entries: ${count(freshManifest)}`,
+    "  run 'node .agents/scripts/generate-skills-index.js' to refresh",
+  ].join('\n');
+}
+
+/**
+ * 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.
+ *
+ * @param {object} manifest
+ * @param {string} indexRelPath Repo-relative manifest path, for the message.
+ * @param {(m: object) => boolean} validateManifest Compiled AJV validator.
+ * @returns {string[]}
+ */
+function validateManifestSchema(manifest, indexRelPath, validateManifest) {
+  const findings = [];
+  if (validateManifest(manifest)) return findings;
+  for (const err of validateManifest.errors ?? []) {
+    const where = err.instancePath || '(root)';
+    findings.push(
+      `${indexRelPath}: manifest-schema: schema violation at ${where}: ${err.message}`,
+    );
+  }
+  return findings;
+}
+
+/**
+ * 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.
+ *
+ * @param {{ exists: boolean, paths: Set<string> | null, manifest: object | null, parseError?: string }} indexInfo
+ * @param {string} indexRelPath
+ * @param {(m: object) => boolean} validateManifest
+ * @param {{ required: boolean }} options
+ * @returns {string[]}
+ */
+export function auditIndex(
+  indexInfo,
+  indexRelPath,
+  validateManifest,
+  { required },
+) {
+  if (!indexInfo.exists) {
+    return required
+      ? [
+          `index missing: ${indexRelPath} not found — run 'node .agents/scripts/generate-skills-index.js'`,
+        ]
+      : [];
+  }
+  if (indexInfo.paths === null) {
+    return [`index unparseable: ${indexRelPath} — ${indexInfo.parseError}`];
+  }
+  if (indexInfo.manifest === null) return [];
+  return validateManifestSchema(
+    indexInfo.manifest,
+    indexRelPath,
+    validateManifest,
+  );
+}

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

@@ -1,12 +1,56 @@
 // .agents/scripts/lib/skills/walk-skill-files.js
 //
-// Shared traversal for SKILL.md files under `.agents/skills/{core,stack}/`.
+// 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.
 
 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.
+ */
+export const LOCAL_SKILLS_SEGMENTS = Object.freeze([
+  '.agents',
+  'local',
+  'skills',
+]);
+
+/**
+ * A skill id is the tier-relative path naming a skill — e.g.
+ * `core/scope-triage` 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.
+ */
+const SKILL_ID_RE = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)+$/;
+
 /**
  * Recursively enumerate `SKILL.md` paths under a directory.
  *
@@ -38,19 +82,99 @@ function walkSkillFiles(rootDir) {
 }
 
 /**
- * Build the list of SKILL.md files under `<repoRoot>/.agents/skills/{core,
- * stack}/`, sorted by POSIX repo-relative path for deterministic output.
+ * Sort absolute paths by their POSIX repo-relative form so output order is
+ * deterministic across platforms.
  *
+ * @param {string[]} files
  * @param {string} repoRoot
- * @returns {string[]} absolute paths
+ * @returns {string[]}
  */
-export function collectSkillFiles(repoRoot) {
-  const skillsRoot = path.join(repoRoot, '.agents', 'skills');
-  const coreFiles = walkSkillFiles(path.join(skillsRoot, 'core'));
-  const stackFiles = walkSkillFiles(path.join(skillsRoot, 'stack'));
-  return [...coreFiles, ...stackFiles].sort((a, b) => {
+function sortByRepoRelative(files, repoRoot) {
+  return [...files].sort((a, b) => {
     const ra = path.relative(repoRoot, a).split(path.sep).join('/');
     const rb = path.relative(repoRoot, b).split(path.sep).join('/');
     return ra < rb ? -1 : ra > rb ? 1 : 0;
   });
 }
+
+/**
+ * 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
+ */
+function collectUnderRoot(repoRoot, rootSegments) {
+  const skillsRoot = path.join(repoRoot, ...rootSegments);
+  const files = TIERS.flatMap((tier) =>
+    walkSkillFiles(path.join(skillsRoot, tier)),
+  );
+  return sortByRepoRelative(files, repoRoot);
+}
+
+/**
+ * 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).
+ *
+ * @param {string} repoRoot
+ * @returns {string[]} absolute paths
+ */
+export function collectSkillFiles(repoRoot) {
+  return collectUnderRoot(repoRoot, PAYLOAD_SKILLS_SEGMENTS);
+}
+
+/**
+ * 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
+ */
+export function collectLocalSkillFiles(repoRoot) {
+  return collectUnderRoot(repoRoot, LOCAL_SKILLS_SEGMENTS);
+}
+
+/**
+ * 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 `null` 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.
+ *
+ * @param {string} repoRoot
+ * @param {string} skillId Tier-relative id, e.g. `stack/qa/acme-sso`.
+ * @returns {{ path: string, root: string } | null} absolute `SKILL.md`
+ *   path and the POSIX repo-relative root it resolved under.
+ */
+export function resolveSkillFile(repoRoot, skillId) {
+  if (typeof skillId !== 'string' || !SKILL_ID_RE.test(skillId)) return null;
+  for (const segments of [PAYLOAD_SKILLS_SEGMENTS, LOCAL_SKILLS_SEGMENTS]) {
+    const candidate = path.join(repoRoot, ...segments, skillId, 'SKILL.md');
+    try {
+      if (fs.statSync(candidate).isFile()) {
+        return { path: candidate, root: segments.join('/') };
+      }
+    } catch {
+      // Unreadable or 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.
+ */
+export const SKILL_SEARCH_ROOTS = Object.freeze([
+  PAYLOAD_SKILLS_SEGMENTS.join('/'),
+  LOCAL_SKILLS_SEGMENTS.join('/'),
+]);

package/.agents/scripts/plan-persist.js

@@ -124,6 +124,8 @@ const CLI_OPTIONS = {
   'force-review': { type: 'boolean', default: false },
   'allow-over-budget': { type: 'boolean', default: false },
   'allow-large-fan-out': { type: 'boolean', default: false },
+  'epic-title': { type: 'string' },
+  'epic-goal': { type: 'string' },
 };
 
 const USAGE =
@@ -133,7 +135,8 @@ const USAGE =
   '[--source-tickets <ids>] [--no-close-superseded] ' +
   '[--route-downgrade-reason <text>] ' +
   '[--dry-run] [--chain-on-clean] [--force-review] ' +
-  '[--allow-over-budget] [--allow-large-fan-out]';
+  '[--allow-over-budget] [--allow-large-fan-out] ' +
+  '[--epic-title <text> --epic-goal <text>]';
 
 async function readOptional(filePath, { required }) {
   try {
@@ -196,6 +199,32 @@ async function loadArtifacts(paths) {
   };
 }
 
+/**
+ * Resolve the optional container-Epic request from the CLI flags.
+ *
+ * Both halves are required together: an Epic with a title and no goal is a
+ * container with nothing explaining the grouping, and a goal with no title
+ * cannot be opened at all. Supplying exactly one is a **usage error**, not a
+ * silent no-Epic run — the operator asked for a container and would otherwise
+ * never learn they did not get one.
+ *
+ * @param {object} values Parsed `parseArgs` values.
+ * @returns {{ title: string, goal: string }|null} `null` when no Epic was requested.
+ */
+export function resolveEpicRequest(values) {
+  const title = (values['epic-title'] ?? '').trim();
+  const goal = (values['epic-goal'] ?? '').trim();
+  if (title === '' && goal === '') return null;
+  if (title === '' || goal === '') {
+    throw new Error(
+      '[plan-persist] --epic-title and --epic-goal must be supplied together ' +
+        '(a container Epic needs both a name and a one-paragraph reason it ' +
+        'groups these Stories).',
+    );
+  }
+  return { title, goal };
+}
+
 /**
  * Assemble the `runPlanPersist` opts bag from parsed CLI values.
  *
@@ -224,6 +253,7 @@ export function buildPersistOptions(values, paths, planContextEnvelope) {
     sourceTicketIds: source.ids,
     sourceTicketOrigin: source.origin,
     routeDowngradeReason: values['route-downgrade-reason'] ?? null,
+    epic: resolveEpicRequest(values),
     // Default-on: `--no-close-superseded` is the explicit escape and always
     // wins over the (default `true`) `--close-superseded`.
     closeSuperseded:
@@ -468,6 +498,14 @@ runAsCli(import.meta.url, main, {
       ],
       ['--allow-over-budget', 'Permit a Spec over the context budget.'],
       ['--allow-large-fan-out', 'Permit a Story count above the fan-out gate.'],
+      [
+        '--epic-title <text>',
+        'Group the persisted Stories under a container Epic with this title (needs --epic-goal).',
+      ],
+      [
+        '--epic-goal <text>',
+        'The container Epic’s one-paragraph goal (needs --epic-title).',
+      ],
     ],
   },
 });

package/.agents/scripts/providers/github/sub-issue-add.js

@@ -0,0 +1,218 @@
+/**
+ * GitHub Provider — shared "link child issue to a parent" helper.
+ *
+ * Story #5139 — a container Epic holds its children as native GitHub
+ * sub-issue edges. The read side has existed since v1
+ * (`sub-issues.js` → `getNativeSubIssues`, and the three-strategy
+ * aggregator in `issues.js` → `getSubTickets`); this is the missing write.
+ *
+ * API surface used:
+ *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+ *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues
+ *          body: { "sub_issue_id": <integer db id of the CHILD issue> }
+ *
+ * **`sub_issue_id` is the child's database id, not its issue number.** They
+ * are different integers and both are plausible, so a mix-up does not throw
+ * — it silently links the wrong issue, or a nonexistent one. This mirrors
+ * `blocked-by-add.js`, whose `issue_id` carries the same trap.
+ *
+ * Contract (deliberately identical to `blocked-by-add.js`):
+ *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
+ *   - **Non-fatal** — catches all errors per edge, warns, and continues.
+ *     The function never throws; failures are returned in the summary.
+ *     The Epic body's checklist is the durable mirror, so a lost edge
+ *     degrades discoverability rather than losing the child.
+ *   - **No-op on empty input.**
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { paginateRest } from './request-helpers.js';
+
+/**
+ * Bounded concurrency for the sub-issue round-trips. Matches the
+ * dependency-edge writer's cap: modest enough for GitHub's secondary rate
+ * limits while collapsing wall-clock from `sum(round-trips)` toward
+ * `sum(round-trips) / concurrency`.
+ */
+const EDGE_CONCURRENCY = 5;
+
+/**
+ * Fetch the database ids of a parent's existing sub-issues, **paginated to
+ * exhaustion**.
+ *
+ * This read is the idempotency check: an edge it fails to see is re-POSTed.
+ * Reading only the first page would therefore make the writer non-idempotent
+ * past the page boundary — the same defect Story #5046 fixed in
+ * `blocked-by-add.js`.
+ *
+ * Returns `[]` on any error so the caller falls back to posting the full
+ * set. Worst case is a duplicate POST, which GitHub rejects harmlessly and
+ * the per-edge catch absorbs.
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number, paginate?: Function }} opts
+ * @returns {Promise<number[]>} Database ids of the parent's current children.
+ */
+async function fetchExistingSubIssueIds({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  paginate = paginateRest,
+}) {
+  try {
+    const data = await paginate(
+      gh,
+      `/repos/${owner}/${repo}/issues/${issueNumber}/sub_issues`,
+      { label: `[sub-issue-add] sub_issues #${issueNumber}` },
+    );
+    if (!Array.isArray(data)) return [];
+    return data.map((item) => item?.id).filter((id) => typeof id === 'number');
+  } catch (err) {
+    Logger.warn(
+      `[sub-issue-add] Could not fetch existing sub-issues for #${issueNumber}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Link a set of child issues to one parent as native sub-issues.
+ *
+ * For each entry in `childInternalIds`, checks whether the edge already
+ * exists and POSTs only the missing ones. Every individual POST failure is
+ * caught, logged and counted — the function never throws.
+ *
+ * @param {{
+ *   gh: object,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   childInternalIds: number[],
+ *   paginate?: Function,
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+export async function addSubIssueEdges({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  childInternalIds,
+  paginate = paginateRest,
+}) {
+  const ids = Array.isArray(childInternalIds) ? childInternalIds : [];
+  if (ids.length === 0) return { added: 0, skipped: 0, failed: 0 };
+
+  const existing = await fetchExistingSubIssueIds({
+    gh,
+    owner,
+    repo,
+    issueNumber,
+    paginate,
+  });
+  const existingSet = new Set(existing);
+
+  // Partition up front so the skip count is deterministic regardless of the
+  // concurrent POST dispatch order.
+  const missing = ids.filter((id) => !existingSet.has(id));
+  const skipped = ids.length - missing.length;
+
+  const perEdge = await concurrentMap(
+    missing,
+    async (childId) => {
+      try {
+        await gh.api({
+          method: 'POST',
+          endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/sub_issues`,
+          body: { sub_issue_id: childId },
+        });
+        return { added: 1, failed: 0 };
+      } catch (err) {
+        Logger.warn(
+          `[sub-issue-add] Failed to link child(id=${childId}) under #${issueNumber}: ${err.message}`,
+        );
+        return { added: 0, failed: 1 };
+      }
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  let added = 0;
+  let failed = 0;
+  for (const r of perEdge) {
+    added += r.added;
+    failed += r.failed;
+  }
+
+  return { added, skipped, failed };
+}
+
+/**
+ * Link child Stories to a container Epic, resolving each child's **database
+ * id** from its issue number via the injected `getTicket` hook.
+ *
+ * Callers hold issue numbers (that is what `plan-persist` creates and what
+ * an operator types); the API wants database ids. Doing the translation here
+ * keeps that trap in one place instead of at every call site.
+ *
+ * Never throws: a child whose id cannot be resolved is counted as failed and
+ * the remaining edges still go out.
+ *
+ * @param {{
+ *   epicNumber: number,
+ *   childIssueNumbers: number[],
+ *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
+ *   owner: string,
+ *   repo: string,
+ *   gh: object,
+ *   paginate?: Function,
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+export async function linkStoriesToEpic({
+  epicNumber,
+  childIssueNumbers,
+  getTicket,
+  owner,
+  repo,
+  gh,
+  paginate = paginateRest,
+}) {
+  const numbers = Array.isArray(childIssueNumbers) ? childIssueNumbers : [];
+  if (numbers.length === 0) return { added: 0, skipped: 0, failed: 0 };
+
+  let failed = 0;
+  const childInternalIds = [];
+
+  for (const childNumber of numbers) {
+    try {
+      const ticket = await getTicket(childNumber);
+      const internalId = ticket?.internalId;
+      if (typeof internalId !== 'number') {
+        Logger.warn(
+          `[sub-issue-add] Child #${childNumber} has no resolvable database id; skipping edge.`,
+        );
+        failed++;
+        continue;
+      }
+      childInternalIds.push(internalId);
+    } catch (err) {
+      Logger.warn(
+        `[sub-issue-add] Could not resolve child #${childNumber}: ${err.message}`,
+      );
+      failed++;
+    }
+  }
+
+  const summary = await addSubIssueEdges({
+    gh,
+    owner,
+    repo,
+    issueNumber: epicNumber,
+    childInternalIds,
+    paginate,
+  });
+
+  return { ...summary, failed: summary.failed + failed };
+}