mandrel 2.59.0 → 2.61.0

package/.agents/scripts/nav-registry-diff.js

@@ -1,50 +1,18 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/nav-registry-diff.js — the deterministic route ↔ nav-registry
- * cross-check the navigability lens (`audit-navigability.md`) runs and triages.
- *
- * The navigability lens asserts two symmetric invariants over a consumer's web
- * surface:
- *
- *   1. **Every route has a persona nav door** — a route registered in the route
- *      tree that no nav-registry entry surfaces for an entitled persona is an
- *      **orphaned route**.
- *   2. **No nav href is dead** — a nav-registry door whose target does not
- *      resolve to a real route is a **dead nav href**.
- *
- * Both invariants are a set-difference over two identifier lists, not a
- * judgement call, so they belong in a script rather than in lens prose that
- * asks the agent to eyeball the two files. The lens enumerates the route tree
- * (from `planning.navigation.routeGlobs`) and the nav registry (from
- * `planning.navigation.navRegistry`), hands both to this tool, and triages the
- * structured diff it prints.
- *
- * The one subtlety a naive set-difference gets wrong is **false orphans**: a
- * dynamic detail route (`/users/:id`) is reachable through its surfaced parent,
- * a system route (`/login`, `/404`) is reachable by construction, and a route
- * reached only by an in-app link is not orphaned either. This tool applies that
- * **orphan-verification exemption taxonomy** so the lens reports only genuine
- * orphans (Story #4630, AC-5).
- *
- * Input is two JSON files (route tree + nav registry); a third optional file
- * lists in-app inbound references. Route and door **identifiers only** are read
- * — never route bodies or persona PII (the navigability lens's logging
- * constraint). The tool prints the diff and exits 0 on a successful run; pass
- * `--strict` to exit non-zero when genuine findings remain (a CI gate posture).
- *
- * This is a one-shot deterministic reporter, not an orchestrator: it takes no
- * ticket, mutates no state, and spawns no process.
+ * nav-registry-diff.js — route ↔ nav-registry cross-check for the
+ * navigability lens: reports orphaned routes (no persona nav door) and dead
+ * nav hrefs. System routes, dynamic children of a surfaced parent, explicit
+ * exemptions, and routes with an in-app inbound link are not orphans. Reads
+ * identifiers only, never route bodies or persona PII. `--strict` exits
+ * non-zero on findings.
  */
 
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 
-/**
- * Last-segment tokens (or whole-path tokens) that mark a **system route** —
- * reachable by construction (auth walls, error pages) rather than through a
- * persona nav door, so their absence from the nav registry is never an orphan.
- */
+/** Last-segment tokens of routes reachable by construction (auth, errors). */
 const SYSTEM_ROUTE_TOKENS = Object.freeze([
   'login',
   'logout',
@@ -69,7 +37,6 @@ const SYSTEM_ROUTE_TOKENS = Object.freeze([
   'maintenance',
 ]);
 
-/** The exemption reasons a verified non-orphan can carry, for triage clarity. */
 const EXEMPTION_REASONS = Object.freeze({
   EXPLICIT: 'explicit-exempt',
   SYSTEM: 'system-route',
@@ -78,10 +45,7 @@ const EXEMPTION_REASONS = Object.freeze({
 });
 
 /**
- * Normalize a route or href path for comparison: coerce to string, trim, force
- * a single leading slash, collapse duplicate slashes, and drop a trailing slash
- * (except for the root `/`). Returns `''` for a nullish or empty input so the
- * caller can reject it.
+ * `''` for a non-string or empty input so the caller can reject it.
  *
  * @param {unknown} p
  * @returns {string}
@@ -96,8 +60,6 @@ export function normalizePath(p) {
 }
 
 /**
- * Split a normalized path into its non-empty segments (`'/'` → `[]`).
- *
  * @param {string} normalized
  * @returns {string[]}
  */
@@ -106,9 +68,7 @@ function segmentsOf(normalized) {
 }
 
 /**
- * True when a single path segment is a **dynamic** segment: an Express/React
- * Router `:param`, a Next.js `[param]` / `[...catchAll]`, a bare wildcard `*`,
- * or a `{param}` template.
+ * `:param`, `[param]` / `[...catchAll]`, `*`, or `{param}`.
  *
  * @param {string} segment
  * @returns {boolean}
@@ -122,14 +82,11 @@ export function isDynamicSegment(segment) {
   );
 }
 
-/** True when the segment is a catch-all (`[...slug]` / `*`) that eats the rest. */
 function isCatchAllSegment(segment) {
   return segment === '*' || segment.startsWith('[...');
 }
 
 /**
- * True when a normalized route path contains at least one dynamic segment.
- *
  * @param {string} normalized
  * @returns {boolean}
  */
@@ -138,9 +95,6 @@ export function isDynamicPath(normalized) {
 }
 
 /**
- * True when a normalized route path is a system route (its last segment, or the
- * whole path, is a recognized system token).
- *
  * @param {string} normalized
  * @returns {boolean}
  */
@@ -152,9 +106,6 @@ export function isSystemRoute(normalized) {
 }
 
 /**
- * The parent of a normalized path — the path with its last segment removed
- * (`/users/:id` → `/users`, `/users` → `/`, `/` → `/`).
- *
  * @param {string} normalized
  * @returns {string}
  */
@@ -165,13 +116,10 @@ export function parentPath(normalized) {
 }
 
 /**
- * True when a **route template** (which may contain dynamic segments) matches a
- * concrete **href**. A dynamic segment matches any single href segment; a
- * catch-all matches one-or-more trailing href segments. A template with no
- * dynamic segment matches only an identical href.
+ * A dynamic segment matches one href segment; a catch-all matches one or more.
  *
- * @param {string} routeNorm normalized route path (the template)
- * @param {string} hrefNorm normalized href (the concrete target)
+ * @param {string} routeNorm
+ * @param {string} hrefNorm
  * @returns {boolean}
  */
 export function routeTemplateMatchesHref(routeNorm, hrefNorm) {
@@ -180,21 +128,17 @@ export function routeTemplateMatchesHref(routeNorm, hrefNorm) {
   for (let i = 0; i < routeSegs.length; i += 1) {
     const rSeg = routeSegs[i];
     if (isCatchAllSegment(rSeg)) {
-      // A catch-all consumes every remaining href segment (>= 1).
       return hrefSegs.length >= i + 1;
     }
     if (i >= hrefSegs.length) return false;
-    if (isDynamicSegment(rSeg)) continue; // matches any one segment
+    if (isDynamicSegment(rSeg)) continue;
     if (rSeg !== hrefSegs[i]) return false;
   }
   return routeSegs.length === hrefSegs.length;
 }
 
 /**
- * Coerce a route-tree entry (a bare path string or a `{ path, personas, exempt,
- * kind }` object) into the internal route shape. Throws on an entry with no
- * usable path so a malformed fixture fails loudly rather than silently
- * dropping a route.
+ * Throws on a pathless entry rather than silently dropping a route.
  *
  * @param {unknown} entry
  * @returns {{ path: string, personas: string[], exempt: boolean }}
@@ -214,9 +158,6 @@ export function toRoute(entry) {
 }
 
 /**
- * Coerce a nav-registry entry (a bare href string or a `{ href, persona }`
- * object) into the internal door shape. Throws on an entry with no usable href.
- *
  * @param {unknown} entry
  * @returns {{ href: string, persona: string|null }}
  */
@@ -236,11 +177,8 @@ export function toDoor(entry) {
 }
 
 /**
- * True when a nav door surfaces a route: the door's href resolves to the route
- * (identical path, or the route template matches the concrete href), AND — when
- * both sides name personas — the door renders in a persona entitled to the
- * route. A route with no declared personas is surfaced by any resolving door; a
- * door with no persona surfaces for any entitled persona.
+ * The door resolves to the route and, when both name personas, the door's
+ * persona is entitled to it.
  *
  * @param {{ path: string, personas: string[] }} route
  * @param {{ href: string, persona: string|null }} door
@@ -255,15 +193,10 @@ function doorSurfacesRoute(route, door) {
 }
 
 /**
- * Resolve why an unsurfaced route is exempt from the orphan report, or `null`
- * when it is a genuine orphan. The taxonomy (Story #4630, AC-5): an explicitly
- * exempt route, a system route, a dynamic-segment child of a surfaced parent,
- * or a route reached by an in-app inbound reference.
- *
  * @param {{ path: string, exempt: boolean }} route
- * @param {Set<string>} surfacedPaths route paths a door surfaces
- * @param {Set<string>} inboundRefs normalized in-app referenced paths
- * @returns {string|null} an {@link EXEMPTION_REASONS} value, or null
+ * @param {Set<string>} surfacedPaths
+ * @param {Set<string>} inboundRefs
+ * @returns {string|null} an {@link EXEMPTION_REASONS} value, or null for a genuine orphan
  */
 function orphanExemption(route, surfacedPaths, inboundRefs) {
   if (route.exempt) return EXEMPTION_REASONS.EXPLICIT;
@@ -276,8 +209,6 @@ function orphanExemption(route, surfacedPaths, inboundRefs) {
 }
 
 /**
- * Compute the two-way route ↔ nav-registry diff with orphan verification.
- *
  * @param {{
  *   routes?: unknown[],
  *   nav?: unknown[],
@@ -295,7 +226,6 @@ export function computeNavDiff({ routes = [], nav = [], refs = [] } = {}) {
   const doorList = nav.map(toDoor);
   const inboundRefs = new Set(refs.map(normalizePath).filter((p) => p !== ''));
 
-  // Which route paths does at least one door surface (persona-aware)?
   const surfacedPaths = new Set();
   for (const route of routeList) {
     if (doorList.some((door) => doorSurfacesRoute(route, door))) {
@@ -315,7 +245,6 @@ export function computeNavDiff({ routes = [], nav = [], refs = [] } = {}) {
     }
   }
 
-  // A door is dead when its href resolves to no route (identical or template).
   const deadHrefs = [];
   for (const door of doorList) {
     const resolves = routeList.some(
@@ -335,12 +264,9 @@ export function computeNavDiff({ routes = [], nav = [], refs = [] } = {}) {
 }
 
 /**
- * Read and parse a JSON array from a file, throwing a clear error when the file
- * is unreadable, not JSON, or not an array.
- *
- * @param {string} label human-readable role for the error message
+ * @param {string} label
  * @param {string} file
- * @param {typeof fs} [fsImpl] filesystem seam; defaults to the real `node:fs`.
+ * @param {typeof fs} [fsImpl]
  * @returns {unknown[]}
  */
 function readJsonArray(label, file, fsImpl = fs) {
@@ -373,8 +299,6 @@ function readJsonArray(label, file, fsImpl = fs) {
 }
 
 /**
- * Render the diff as a human-readable, triage-friendly text report.
- *
  * @param {ReturnType<typeof computeNavDiff>} diff
  * @returns {string}
  */
@@ -401,15 +325,6 @@ export function formatDiffText(diff) {
 }
 
 /**
- * The reporter core, extracted from the CLI shell so the argv → read → diff →
- * render → exit-code path is reachable without touching the real filesystem or
- * the real stdout.
- *
- * Both seams on the optional final `deps` parameter default to the real
- * implementation (`.agents/rules/test-seams.md` rules 1-2, 4 — `readJsonArray`
- * forwards `fsImpl` rather than re-acquiring `fs`), so `main` and every
- * production invocation are unchanged.
- *
  * @param {string[]} [argv]
  * @param {{ fsImpl?: typeof fs, stdout?: { write: (s: string) => void } }} [deps]
  * @returns {Promise<number>} process exit code
@@ -443,8 +358,7 @@ export async function runNavRegistryDiff(
 
   const diff = computeNavDiff({ routes, nav, refs });
 
-  // Written straight to stdout (not the orchestrator Logger) so the output is a
-  // clean, machine-parseable report the lens can pipe or `JSON.parse`.
+  // Straight to stdout (not Logger) so the report stays machine-parseable.
   const rendered = values.json
     ? JSON.stringify(diff, null, 2)
     : formatDiffText(diff);

package/.agents/scripts/notify.js

@@ -2,41 +2,11 @@
 /* node:coverage ignore file */
 
 /**
- * notify.js
- *
- * Single dispatch entry point for runtime notifications across two
- * independent channels.
- *
- * Direct inline calls at phase boundaries are the only path: `notify()`
- * is invoked from the caller that has something to say. Direct CLI /
- * library invocations are equally supported, for one-shot operator
- * commands and the structured-comment back-channel.
- *
- * Channels:
- *
- *   1. GITHUB COMMENT — gated by `notifications.commentEvents` (event
- *      allowlist). Only dispatches whose `event` name appears in the
- *      allowlist reach the ticket. @mentions operator on `high` severity;
- *      on `medium` when `mentionOperator` is set. Callers may pass
- *      `opts.skipComment: true` to suppress the comment for a single
- *      dispatch while still firing the webhook (used for structured-
- *      comment writers that already posted the ticket-side body themselves).
- *   2. WEBHOOK — gated by `notifications.webhookEvents` (event allowlist).
- *      Only dispatches whose `event` name appears in the allowlist reach
- *      the webhook. The webhook channel is curated for the epic narrative
- *      (% progress + blockers), not the firehose of per-story transitions;
- *      the default allowlist is the five `epic-*` events. Payload envelope:
- *      `{ text, severity, event?, level?, ticketId?, epicId?, phase? }` —
- *      `text` is the primary human-readable body (Slack-style incoming
- *      webhooks read this field).
- *
- * Each channel filters independently — no fallback chain. Severity is
- * carried as envelope metadata (so Slack consumers can color-code by it
- * and high-severity comments still `@mention` the operator) but is no
- * longer a routing factor for either channel.
- *
- * Severity vocabulary: low | medium | high. See `lib/notifications/notifier.js`
- * for the `eventSeverity()` helper used by ticket-state-transition events.
+ * notify.js — dispatch a notification to two independently gated channels:
+ * a GitHub comment (`notifications.commentEvents` allowlist) and a webhook
+ * (`notifications.webhookEvents` allowlist; `text` is the body Slack-style
+ * hooks read). Severity never routes; it only drives @mentions and rides the
+ * webhook envelope as metadata.
  */
 
 import { createHmac } from 'node:crypto';
@@ -49,18 +19,13 @@ import {
 } from './lib/notifications/notifier.js';
 import { createProvider } from './lib/provider-factory.js';
 
-/** Map notification severity to a `postComment` badge style. */
 const SEVERITY_TO_COMMENT_TYPE = {
   low: 'progress',
   medium: 'notification',
   high: 'friction',
 };
 
-/**
- * Resolve a channel's event allowlist. Returns a `Set<string>` for O(1)
- * membership lookups. An absent/empty allowlist suppresses the channel
- * entirely — there is no implicit fallback to a severity-based gate.
- */
+/** An absent or empty allowlist suppresses the channel entirely. */
 function resolveEventAllowlist(notifications, key) {
   const list = notifications?.[key];
   if (!Array.isArray(list)) return new Set();
@@ -88,8 +53,6 @@ function buildWebhookPayload({
       : '';
   const text = `${prefix}${ticketPart}: ${cleanMessage}`;
 
-  // `text` is the primary human-readable body; typed fields follow for
-  // routable subscribers.
   const envelope = { text, severity };
   if (Number.isFinite(numericTicketId) && numericTicketId > 0) {
     envelope.ticketId = numericTicketId;
@@ -127,11 +90,7 @@ async function sendWebhook(url, payloadBody, fetchImpl = globalThis.fetch) {
 }
 
 /**
- * Dispatch a notification across the two channels.
- *
- * @param {number} ticketId - GitHub Issue number to post the notification on.
- *   Pass 0 (or any non-positive) to skip the GitHub comment and fire the
- *   webhook only.
+ * @param {number} ticketId - Non-positive skips the comment (webhook only).
  * @param {{
  *   severity?: 'low'|'medium'|'high',
  *   message: string,
@@ -139,21 +98,15 @@ async function sendWebhook(url, payloadBody, fetchImpl = globalThis.fetch) {
  *   level?: 'task'|'story'|'wave'|'epic',
  *   epicId?: number,
  *   phase?: string,
- * }} payload - `severity` defaults to `medium` when omitted; it controls
- *   @mention behavior on the comment channel and is carried as webhook
- *   envelope metadata, but does not gate either channel. `event` is
- *   required for any channel to fire — event-less dispatches are no-ops.
+ * }} payload - Without `event` no channel fires.
  * @param {{
  *   config?: object,
  *   provider?: object,
  *   webhookUrl?: string|null,
  *   skipComment?: boolean,
  *   fetchImpl?: typeof fetch,
- * }} [opts] - `fetchImpl` is injected into the webhook POST in place of
- *   `globalThis.fetch`; it defaults to the global, so production callers
- *   never pass it. Tests inject a fake to assert the request body,
- *   `X-Signature-256` header, and the 4xx/5xx response branches without a
- *   live network call or a global monkeypatch.
+ * }} [opts] - `skipComment` suppresses the comment for writers that already
+ *   posted the ticket-side body.
  */
 export async function notify(ticketId, payload, opts = {}) {
   const config = opts.config || resolveConfig();
@@ -177,8 +130,6 @@ export async function notify(ticketId, payload, opts = {}) {
   const fireComment = !noTicket && !callerSuppressed && eventAllowedOnComments;
 
   if (fireComment) {
-    // High always @mentions; medium @mentions when `mentionOperator` is set;
-    // low never @mentions.
     const mention =
       severity === 'high' ||
       (severity === 'medium' && notifications?.mentionOperator);
@@ -190,12 +141,8 @@ export async function notify(ticketId, payload, opts = {}) {
     });
   }
 
-  // Webhook channel: gated by event-name allowlist. A dispatch without an
-  // `event` field can never reach the webhook — there is no implicit
-  // category for unlabelled notifications.
   if (event && webhookEvents.has(event)) {
-    // `opts.webhookUrl === undefined` → resolve from process env.
-    // Explicit `null` or string → caller was explicit; don't resolve.
+    // Only `undefined` resolves from env; an explicit `null` means none.
     const webhookUrl =
       opts.webhookUrl === undefined ? resolveWebhookUrl() : opts.webhookUrl;
     if (webhookUrl) {
@@ -213,9 +160,7 @@ export async function notify(ticketId, payload, opts = {}) {
       });
       await sendWebhook(webhookUrl, payloadBody, opts.fetchImpl);
     } else {
-      // Event was on the allowlist but no URL is available — surface this
-      // so the operator notices a missing/empty NOTIFICATION_WEBHOOK_URL
-      // instead of silently dropping the dispatch.
+      // Allowlisted but no URL: warn rather than drop silently.
       Logger.warn(
         `[Notify] Webhook event (${event}) suppressed — no webhook URL resolved (NOTIFICATION_WEBHOOK_URL unset or empty).`,
       );
@@ -290,8 +235,6 @@ async function main() {
   const args = process.argv.slice(2);
   const { ticketId, message, severity } = parseNotifyArgs(args);
 
-  // CLI fires always carry the `operator-message` event so they route
-  // through the same event-name allowlist as the rest of the system.
   await notify(ticketId, {
     severity,
     message,