mandrel 2.30.0 → 2.32.0

package/.agents/scripts/validate-docs-freshness.js

@@ -1,314 +0,0 @@
-#!/usr/bin/env node
-/* node:coverage ignore file -- top-level docs-freshness gate shell; the tested logic lives in lib/docs-freshness.js */
-
-/**
- * .agents/scripts/validate-docs-freshness.js — Documentation Freshness Gate
- *
- * For each doc in `delivery.docsFreshness.paths` + `project.docsContextFiles`, verify
- * that the file was meaningfully updated during this Epic's lifecycle. A
- * file passes when **either** of the following holds:
- *
- *   1. `git log --all --grep="#<epicId>" -- <file>` returns a commit —
- *      the Epic ID was referenced in a commit message that touched the
- *      file. This is the pass path for **every** doc.
- *   2. The file's current body contains `#<epicId>` — but this
- *      body-annotation path is accepted **only for changelog-class files**
- *      (basename matches `/changelog/i`), where an appended release note
- *      keyed to the Epic is the legitimate, expected update. Any other doc
- *      (architecture, decisions, README, …) MUST pass via condition 1: the
- *      living doc has to be **rewritten in an Epic-referencing commit**, not
- *      merely annotated with `#<epicId>`.
- *
- * The prior gate accepted any diff against the base branch — a stray
- * whitespace edit or a one-line unrelated cleanup passed, defeating the
- * purpose of the check. Requiring an Epic-ID reference makes "did you
- * update the docs for this Epic?" a falsifiable question instead of a
- * checkbox. The changelog-only restriction on condition 2 closes the
- * follow-on perverse incentive: without it, the gate rewarded appending
- * `#<epicId>` history into living docs (manufacturing fake provenance) to
- * satisfy the check. Restricting the annotation path to changelog files
- * makes the gate ask "was this doc rewritten for the Epic?" rather than
- * "does it mention the Epic?".
- *
- * Usage:
- *   node .agents/scripts/validate-docs-freshness.js --epic <EPIC_ID> [--docs <comma-separated>] [--json]
- *
- * `--json` emits a single JSON object on stdout with
- *   { ok, epicId, results: [{ file, pass, reason }, ...] }
- * and suppresses the human-readable log lines. Intended for LLM/tool consumers
- * that need to enumerate failing files without parsing log output.
- *
- * Exit codes:
- *   0 — every doc has an Epic-ID reference.
- *   1 — one or more docs have no reference.
- *   2 — configuration error.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { parseArgs } from 'node:util';
-import { runAsCli } from './lib/cli-utils.js';
-import {
-  getPaths,
-  PROJECT_ROOT,
-  resolveConfig,
-} from './lib/config-resolver.js';
-import { gitSpawn } from './lib/git-utils.js';
-import { Logger } from './lib/Logger.js';
-
-/**
- * Resolve the canonical doc list for a release: `delivery.docsFreshness.paths`
- * entries plus `project.docsContextFiles` prefixed by `project.paths.docsRoot`.
- * Expects the full resolved config (`{ project, delivery, ... }`).
- *
- * @param {object} config
- * @returns {string[]}
- */
-export function resolveDocList(config) {
-  // Read from new shape first; fall back to the legacy shim/bag.
-  const project = config?.project ?? config;
-  const delivery = config?.delivery ?? null;
-  const docsFreshnessPaths = Array.isArray(delivery?.docsFreshness?.paths)
-    ? delivery.docsFreshness.paths
-    : Array.isArray(config?.release?.docs)
-      ? config.release.docs
-      : [];
-  const contextDocs = Array.isArray(project?.docsContextFiles)
-    ? project.docsContextFiles
-    : Array.isArray(config?.docsContextFiles)
-      ? config.docsContextFiles
-      : [];
-  const docsRoot = getPaths(config).docsRoot ?? 'docs';
-  const resolved = [
-    ...docsFreshnessPaths,
-    ...contextDocs.map((f) => path.posix.join(docsRoot, f)),
-  ];
-  return Array.from(new Set(resolved));
-}
-
-/**
- * A doc is "changelog-class" when its basename matches `/changelog/i`
- * (e.g. `CHANGELOG.md`, `docs/CHANGELOG.md`, `changelog.mdx`). Only these
- * files may satisfy the freshness gate via a body annotation (pass
- * condition 2); every other doc must pass via an Epic-referencing commit
- * (pass condition 1).
- *
- * @param {string} file
- * @returns {boolean}
- */
-export function isChangelogClass(file) {
-  return /changelog/i.test(path.basename(file));
-}
-
-function epicRefMatcher(epicId) {
-  // Match `#N` as a standalone token. `(?!\d)` prevents `#10` from
-  // satisfying a search for `#1` — a subtle bug the prior diff-only gate
-  // never had to guard against.
-  return new RegExp(`#${epicId}(?!\\d)`);
-}
-
-/* node:coverage disable -- real `git log` shell-out; exercised via the
-   injectable `commitsForFile` seam in runFreshnessGate, not directly. */
-function commitsMentioningEpic(docPath, epicId, cwd = PROJECT_ROOT) {
-  const res = gitSpawn(
-    cwd,
-    'log',
-    '--all',
-    `--grep=#${epicId}`,
-    '--pretty=format:%H',
-    '--',
-    docPath,
-  );
-  if (res.status !== 0) return [];
-  return (res.stdout ?? '')
-    .split('\n')
-    .map((s) => s.trim())
-    .filter(Boolean);
-}
-/* node:coverage enable */
-
-function fileBodyMentionsEpic(
-  docPath,
-  epicId,
-  cwd = PROJECT_ROOT,
-  readFileImpl = fs.readFileSync,
-) {
-  const abs = path.isAbsolute(docPath) ? docPath : path.join(cwd, docPath);
-  let body;
-  try {
-    body = readFileImpl(abs, 'utf8');
-  } catch {
-    return false;
-  }
-  return epicRefMatcher(epicId).test(body);
-}
-
-/**
- * Run the freshness gate against every resolved doc. Pure; takes
- * everything it needs as inputs so tests don't need a worktree.
- *
- * @param {{
- *   epicId: number,
- *   docs: string[],
- *   cwd?: string,
- *   readFileImpl?: typeof fs.readFileSync,
- *   commitsForFile?: (doc: string, epicId: number, cwd: string) => string[],
- * }} opts
- * @returns {{ ok: boolean, results: Array<{ file: string, pass: boolean, reason: string }> }}
- */
-export function runFreshnessGate({
-  epicId,
-  docs,
-  cwd = PROJECT_ROOT,
-  readFileImpl = fs.readFileSync,
-  commitsForFile = commitsMentioningEpic,
-}) {
-  const results = docs.map((file) => {
-    const commits = commitsForFile(file, epicId, cwd);
-    if (commits.length > 0) {
-      return {
-        file,
-        pass: true,
-        reason: `${commits.length} commit(s) reference Epic #${epicId}`,
-      };
-    }
-    // Pass condition 2 (body annotation) is restricted to changelog-class
-    // files. For every other doc, an appended `#<epicId>` no longer passes —
-    // the living doc must be rewritten in an Epic-referencing commit.
-    const changelogClass = isChangelogClass(file);
-    if (
-      changelogClass &&
-      fileBodyMentionsEpic(file, epicId, cwd, readFileImpl)
-    ) {
-      return {
-        file,
-        pass: true,
-        reason: `changelog body annotation references #${epicId}`,
-      };
-    }
-    return {
-      file,
-      pass: false,
-      reason: changelogClass
-        ? `no commit message or changelog body reference to #${epicId}`
-        : `${file} was not rewritten in an Epic-referencing commit for #${epicId} — ` +
-          `living docs must be REWRITTEN in a commit whose message references ` +
-          `#${epicId} (not annotated with #${epicId}); the body-annotation path ` +
-          `passes only for changelog-class files`,
-    };
-  });
-  return { ok: results.every((r) => r.pass), results };
-}
-
-/**
- * Pure: parse argv into the normalized CLI option bag.
- *
- * @param {string[]} argv
- * @returns {{ epicId: number|null, json: boolean, docsList: string[]|null }}
- */
-export function parseFreshnessArgs(argv) {
-  const { values } = parseArgs({
-    args: argv,
-    options: {
-      epic: { type: 'string' },
-      docs: { type: 'string' },
-      json: { type: 'boolean', default: false },
-    },
-    strict: false,
-  });
-  const parsed = Number.parseInt(values.epic ?? '', 10);
-  return {
-    epicId: Number.isNaN(parsed) || parsed <= 0 ? null : parsed,
-    json: values.json === true,
-    docsList: values.docs
-      ? values.docs
-          .split(',')
-          .map((s) => s.trim())
-          .filter(Boolean)
-      : null,
-  };
-}
-
-/** Pure: render a per-doc "ok / fail" line. */
-export function renderFreshnessLine(result) {
-  return `[docs-freshness] ${result.pass ? '✅' : '❌'} ${result.file} — ${result.reason}`;
-}
-
-/**
- * Pure: build the failure message for the operator. Names the failing
- * file(s) and states the rewrite-not-append contract explicitly.
- *
- * @param {number} epicId
- * @param {Array<{ file: string, pass: boolean }>} [results]
- */
-export function renderFreshnessFailureMessage(epicId, results = []) {
-  const failing = results.filter((r) => !r.pass).map((r) => r.file);
-  const fileList = failing.length > 0 ? failing.join(', ') : '(see rows above)';
-  return (
-    `[docs-freshness] ❌ Documentation freshness gate FAILED for Epic #${epicId}.\n\n` +
-    `Failing file(s): ${fileList}\n\n` +
-    `Living docs satisfy this gate by being REWRITTEN in an Epic-referencing ` +
-    `commit — a commit whose message references #${epicId} and touches the ` +
-    `file — NOT by appending a #${epicId} annotation to the body. The ` +
-    `body-annotation path passes ONLY for changelog-class files (basename ` +
-    `matches /changelog/i). Rewrite each failing file for the Epic, then ` +
-    `re-run /deliver.`
-  );
-}
-
-/** Pure: success message. */
-export function renderFreshnessSuccessMessage(epicId, count) {
-  return `[docs-freshness] ✅ All ${count} doc(s) reference Epic #${epicId}.`;
-}
-
-/* node:coverage disable -- process I/O + real config/git wiring (stdout,
-   process.exit, resolveConfig, runAsCli); the pure logic these thin wrappers
-   call is covered directly above. */
-function reportEmptyDocs(epicId, json) {
-  if (json) {
-    process.stdout.write(
-      `${JSON.stringify({ ok: true, epicId, results: [] })}\n`,
-    );
-    return;
-  }
-  Logger.info(
-    `[docs-freshness] ⏭  No docs configured under delivery.docsFreshness.paths or ` +
-      `project.docsContextFiles — nothing to check.`,
-  );
-}
-
-function reportGateOutcome({ epicId, json, ok, results }) {
-  if (json) {
-    process.stdout.write(`${JSON.stringify({ ok, epicId, results })}\n`);
-    if (!ok) process.exit(1);
-    return;
-  }
-  for (const r of results) Logger.info(renderFreshnessLine(r));
-  if (ok) {
-    Logger.info(renderFreshnessSuccessMessage(epicId, results.length));
-    return;
-  }
-  Logger.error(renderFreshnessFailureMessage(epicId, results));
-  process.exit(1);
-}
-
-async function main() {
-  const args = parseFreshnessArgs(process.argv.slice(2));
-  if (args.epicId === null) {
-    throw new Error(
-      'Usage: node validate-docs-freshness.js --epic <EPIC_ID> [--docs a.md,b.md] [--json]',
-    );
-  }
-  const { epicId, json, docsList } = args;
-  const config = resolveConfig();
-  const docs = docsList ?? resolveDocList(config);
-  if (docs.length === 0) {
-    reportEmptyDocs(epicId, json);
-    return;
-  }
-  const { ok, results } = runFreshnessGate({ epicId, docs });
-  reportGateOutcome({ epicId, json, ok, results });
-}
-
-runAsCli(import.meta.url, main, { source: 'validate-docs-freshness' });
-/* node:coverage enable */

package/.agents/skills/core/diagnose-friction/SKILL.md

@@ -1,78 +0,0 @@
----
-name: diagnose-friction
-description: >-
-  Wrap a shell command with diagnostic capture. On failure, print static
-  suggestions and append a structured `friction` record to the per-Story
-  signals.ndjson stream. Use whenever a script in the orchestration loop
-  invokes a tool whose failure shape we want the analyzer to attribute.
-allowed_tools:
-  - Bash
-  - Read
----
-
-# diagnose-friction
-
-## Policy Capsule
-
-- Invoke via the wrapping CLI `node .agents/scripts/diagnose-friction.js --story <id> [--epic <id>] --cmd <command args...>`; this is the single supported entry point.
-- `--cmd` takes the command as **separate argv words** — the CLI spawns them with no shell. Quoting the whole command as one string (`--cmd "npm run lint"`) makes the entire string the executable name, so the spawn fails ENOENT. That is a usage error in your own invocation, not friction: the CLI refuses it with a usage message and appends **no** ledger row. Re-run it unquoted.
-- Pass the wrapped command's stdout and stderr through **unchanged** — never reformat, redact, or buffer in a way that loses the original failure shape.
-- Never mutate the wrapped command's exit code. The Skill observes; the caller decides whether the failure is fatal.
-- Operate as **best-effort observation**: a write failure on the signals stream MUST NOT halt the runner. A missing signal is preferable to a stalled wave.
-- On non-zero exit append a `friction` NDJSON record (`kind`, `ts`, `category`, `detail`, `exitCode`) only through the signals writer helper — never open `signals.ndjson` directly.
-- Resolve Story context from `--story` (and `--epic` when a run id applies); there is no body-parsing fallback — pass the flags explicitly.
-- Do **not** post GitHub comments from this Skill. Friction is local NDJSON: the retro is what aggregates the stream and routes recurring friction into proposals (Story #4545 deleted `analyze-execution`, the perf-summary comment surface).
-- Categorize failures deterministically (rebase abort, test-suite name, lint category, etc.) so the retro can attribute friction without re-running the command.
-
-## Role
-
-Diagnostic interceptor. Captures the failure shape of a wrapped command
-and persists it as a structured signal so the retro can attribute friction
-back to the Story without re-running the command.
-
-## When to use
-
-Any orchestration call site whose failure mode is informative
-(rebase aborts, test failures with classifiable suite names, lint
-errors with stable categories). The wrapping script today is
-`diagnose-friction.js`; this Skill documents the contract for callers
-that want to dispatch via the Skill tool rather than spawn the CLI.
-
-## Inputs
-
-- `--cmd <command args...>` — the command to invoke and observe, passed as
-  separate argv words. A single whitespace-containing argument is rejected as
-  a quoting mistake before anything is spawned or recorded.
-- `--story <id>` / `--epic <id>` (optional) — when resolved, the Skill
-  appends a `friction` signal to
-  `temp/run-<eid>/stories/story-<sid>/signals.ndjson` on non-zero exit
-  (standalone Stories: `temp/standalone/stories/story-<sid>/`).
-
-## Outputs
-
-- The wrapped command's stdout / stderr is passed through unchanged.
-- On non-zero exit: a `friction` NDJSON record (kind, ts, category,
-  detail, exitCode) is appended via the signals writer.
-- No GitHub comments are posted — friction is a local NDJSON signal. The
-  retro reads the stream out-of-band.
-
-## Procedure
-
-```bash
-node .agents/scripts/diagnose-friction.js \
-  --story <id> [--epic <id>] \
-  --cmd <command args...>
-```
-
-The Skill's contract is "best-effort observation" — the wrapping
-script never halts the runner because of a write failure. A missing
-signal is preferable to a halted runner.
-
-## Constraints
-
-- Do **not** post GitHub comments from this Skill. Friction is local
-  NDJSON; the retro owns the aggregate surface.
-- Do **not** mutate the wrapped command's exit code. The Skill's job
-  is observation; the caller decides whether the failure is fatal.
-- Do **not** open `signals.ndjson` directly — use the signals writer
-  helper so the file format and warn-once policy stay consistent.

package/.agents/workflows/helpers/signals.md

@@ -1,112 +0,0 @@
----
-description: >-
-  Helper doc for the signals-view.js debug viewer. Renders the signals
-  span-tree for a run (and optionally a single Story) to the terminal.
-  Read-only over `lib/signals/` — no remote writes, no state mutation, no
-  auto-fixes. Dumb-terminal-safe (`console.log` only). Not a slash command —
-  invoke the script directly when needed.
----
-
-# signals span-tree viewer (helper)
-
-> **Helper, not a slash command.** Files under `workflows/helpers/` are not
-> projected into the mandrel plugin command tree. The signals subsystem itself
-> (`lib/signals/`, writer, schema, detectors, NDJSON listeners) runs as
-> part of the normal `/deliver` machinery — this viewer is for
-> ad-hoc debugging when you need to inspect the span-tree directly.
-> Invoke the backing script: `node .agents/scripts/signals-view.js <run-id> [--story <id>]`.
-
-## Overview
-
-`signals-view.js` is the operator-facing viewer for the consolidated
-signals stream. It reads `temp/run-<id>/stories/story-<sid>/signals.ndjson` via
-[`lib/signals/read`](../../scripts/lib/signals/read.js), builds an
-in-memory span-tree via
-[`lib/signals/buildSpanTree`](../../scripts/lib/signals/span-tree.js), and
-prints a run → Story → events tree to stdout.
-
-It is distinct from `diagnose-friction.js` (per-Story signal capture that
-wraps a shell command) and from `diagnose.js` (read of the checks
-registry). This viewer is purely a formatter over an iterator — no
-GitHub I/O, no commit creation, no label transitions.
-
-```text
-node .agents/scripts/signals-view.js <run-id> [--story <id>]
-  → signals.read({ run, story? })
-  → buildSpanTree(asyncIterator)
-  → console.log lines (run → Story → events)
-  → exit 0 (always; missing-file path prints a friendly message)
-```
-
-## Arguments
-
-| Argument         | Required | Description                                                                                                                            |
-| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `<run-id>`       | yes      | Positive integer run ID. The viewer resolves `temp/run-<id>/` under the configured `project.paths.tempRoot`.                         |
-| `--story <id>`   | no       | Positive integer Story ID. When set, the printed tree is narrowed to a single Story subtree under the run.                            |
-
-## Flags (test-only)
-
-| Flag                  | Description                                                                                                                                  |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--temp-root <path>`  | Override the resolved `tempRoot`. Reserved for fixture-driven tests (see `tests/signals-view.test.js`); production callers omit this flag.   |
-
-## Exit codes
-
-| Code | Meaning                                                                                       |
-| ---- | --------------------------------------------------------------------------------------------- |
-| `0`  | Happy path **or** missing signals file. The missing-file path prints a friendly message ("No signals found for run #N"), never a stack trace. |
-| `1`  | Bad arguments (non-integer `<run-id>`, missing positional, malformed `--story`).              |
-
-## Examples
-
-```bash
-# Render every Story under run #1181.
-node .agents/scripts/signals-view.js 1181
-
-# Narrow to a single Story subtree.
-node .agents/scripts/signals-view.js 1181 --story 1438
-
-# No signals yet — friendly message, exit 0.
-node .agents/scripts/signals-view.js 9999
-# → No signals found for run #9999.
-```
-
-## Phase steps
-
-1. Parse `<run-id>` and optional `--story <id>` from the CLI
-   arguments. Reject non-integer or non-positive inputs with exit 1 and
-   the canonical usage line.
-2. Invoke `node .agents/scripts/signals-view.js <run-id> [--story <id>]`
-   from the operator's working directory. The script resolves
-   `tempRoot` from the project's `.agentrc.json` (or the framework
-   default `'temp'`).
-3. Read the Story-tree output as the canonical surface — no further
-   parsing is needed; the script's stdout is the deliverable.
-
-## Constraints
-
-- **Never** writes to GitHub state (no label transitions, no comments).
-  The viewer is purely read-side.
-- **Never** mutates the working tree, including `temp/`. The on-disk
-  signals files are owned by `signals-writer.js`; this viewer only
-  reads them.
-- **Never** uses Ink, blessed, or terminal-control escape sequences.
-  Output goes through `console.log` exclusively so the viewer works on
-  Windows + bash hosts (see [`helpers/parallel-tooling.md`](parallel-tooling.md)).
-- **Always** honours the configured `project.paths.tempRoot`.
-  Earlier post-merge work leaked to the real repo root regardless of
-  test sandbox `tempRoot` (project memory: `phase_timings_uses_project_root`) —
-  this viewer reads via [`lib/config/temp-paths.js`](../../scripts/lib/config/temp-paths.js)
-  so the sandbox path always wins.
-
-## See also
-
-- [`.agents/scripts/signals-view.js`](../../scripts/signals-view.js) — the
-  CLI implementation backing this helper.
-- [`.agents/scripts/lib/signals/`](../../scripts/lib/signals/) — the
-  shared reader + schema + span-tree barrel.
-- [`tests/signals-view.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/signals-view.test.js) —
-  pinned output and tempRoot-honour contracts.
-- [`tests/lib/signals/span-tree.test.js`](https://github.com/dsj1984/mandrel/blob/main/tests/lib/signals/span-tree.test.js) —
-  pure-function contract for the span-tree builder.