mandrel 2.38.0 → 2.39.0

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -26,11 +26,25 @@
  * harness invocation — by exact name or by raw-URL origin match against each
  * environment's `baseUrl` — and throws loudly (naming the known environments)
  * on an unknown name or unmatched URL.
+ *
+ * It also **resolves the selected environment's `signInSeam`** (Story #5135).
+ * A `{ skill }` seam naming an id that resolves to no readable `SKILL.md`
+ * under either skills root used to fail silently: the contract validated, the
+ * seam was returned unread, and the dangling pointer only surfaced much later
+ * when a sweep reached its sign-in step — after the harness had already
+ * driven a browser. Resolution now happens here, at config-resolution time,
+ * so the failure lands where the operator can fix `.agentrc.json`. A seam
+ * that is absent entirely is a legitimate, declarable state (the workflows
+ * drive the unauthenticated surface and record the gap), not an error.
  */
 
 import Ajv from 'ajv';
-
 import { QA_SCHEMA } from '../config-settings-schema.js';
+import { PROJECT_ROOT } from '../project-root.js';
+import {
+  resolveSkillFile,
+  SKILL_SEARCH_ROOTS,
+} from '../skills/walk-skill-files.js';
 
 /**
  * The harness-required fields. The AJV `QA_SCHEMA` keeps these optional so
@@ -242,6 +256,40 @@ function toOrigin(value) {
   }
 }
 
+/**
+ * Normalize and verify one environment's `signInSeam`.
+ *
+ * An absent seam normalizes to `null` — a declarable state, not an error.
+ * A `{ skill }` seam is resolved against both skills roots and throws when
+ * it resolves under neither, so a dangling pointer is caught here rather
+ * than mid-sweep. The resolved `SKILL.md` path is attached as
+ * `skillPath` so the harness reads the file the check actually found.
+ *
+ * @param {object | undefined} seam
+ * @param {string} envName Environment name, for the error message.
+ * @param {{ repoRoot?: string }} options
+ * @returns {object | null}
+ */
+function resolveSignInSeam(seam, envName, options) {
+  if (seam == null) return null;
+  if (typeof seam.skill !== 'string') return seam;
+
+  const repoRoot = options.repoRoot ?? PROJECT_ROOT;
+  const found = resolveSkillFile(repoRoot, seam.skill);
+  if (found === null) {
+    throw new Error(
+      `qa: environment \`${envName}\` declares signInSeam.skill ` +
+        `\`${seam.skill}\`, which resolves to no readable SKILL.md. ` +
+        `Searched ${SKILL_SEARCH_ROOTS.map((r) => `\`${r}/<skill>/SKILL.md\``).join(' and ')}. ` +
+        'Author the skill under the consumer-writable `.agents/local/skills/` ' +
+        'zone (it is never pruned by `mandrel sync` and never flagged as ' +
+        'payload drift), correct the id, or omit `signInSeam` entirely if ' +
+        'this target genuinely has no sign-in seam.',
+    );
+  }
+  return { ...seam, skillPath: found.path };
+}
+
 /**
  * Resolve a single QA environment for one harness invocation.
  *
@@ -262,13 +310,17 @@ function toOrigin(value) {
  * Fails **loudly**: an unknown name or an unmatched URL throws an error that
  * names the known environments so the operator can correct the invocation.
  *
- * @param {{ environments: Record<string, { baseUrl: string, signInSeam: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
+ * @param {{ environments: Record<string, { baseUrl: string, signInSeam?: object, allowWrites?: boolean }>, defaultEnvironment: string }} contract
  *   A contract returned by `resolveQaContract`.
  * @param {string} [target] Environment name or raw URL. Omit for the default.
- * @returns {{ name: string, baseUrl: string, signInSeam: object, allowWrites: boolean }}
- * @throws {Error} on an unknown name or unmatched URL.
+ * @param {{ repoRoot?: string }} [options] `repoRoot` roots skill-seam
+ *   resolution; defaults to the project root. Injected by tests.
+ * @returns {{ name: string, baseUrl: string, signInSeam: object | null, allowWrites: boolean }}
+ *   `signInSeam` is `null` when the environment declares none.
+ * @throws {Error} on an unknown name, an unmatched URL, or a `{ skill }` seam
+ *   that resolves under no skills root.
  */
-export function resolveQaEnvironment(contract, target) {
+export function resolveQaEnvironment(contract, target, options = {}) {
   const environments = contract?.environments;
   if (
     environments == null ||
@@ -320,7 +372,7 @@ export function resolveQaEnvironment(contract, target) {
   return {
     name: resolvedName,
     baseUrl: env.baseUrl,
-    signInSeam: env.signInSeam,
+    signInSeam: resolveSignInSeam(env.signInSeam, resolvedName, options),
     allowWrites,
   };
 }

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/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,