session-orchestrator 3.24.0 → 4.0.1

package/scripts/lib/telemetry-flush-health-banner.mjs

@@ -0,0 +1,211 @@
+/**
+ * telemetry-flush-health-banner.mjs — #1255
+ *
+ * Surfaces the ONE telemetry-flush outcome nobody could see: a flush the
+ * sandbox guard refused.
+ *
+ * ## Why this module exists
+ *
+ * `scripts/lib/telemetry/sync.mjs` fails CLOSED since 4.0.0 — when its
+ * environment probe cannot complete its checks it returns
+ * `{ sandbox: true, reason: 'sandbox:probe-failed' }` and sends nothing. That
+ * is the right default, and `sync.mjs` stays deliberately SILENT about it (it
+ * runs inside the SessionEnd teardown budget, where a banner has no reader).
+ *
+ * The refusal therefore reaches exactly one sink: `hooks/on-session-end.mjs`
+ * emits `orchestrator.telemetry.flush` with `{ outcome, reason }` into
+ * `.orchestrator/metrics/events.jsonl`. Measured 2026-09-07 (W1-D6 census):
+ * NO consumer read that reason back out — a repo could refuse every flush for
+ * weeks and the only visible difference from a healthy repo was an absence.
+ * That is `.claude/rules/host-resources.md` § HR-105 ("a rule you cannot
+ * falsify is not a rule") applied to the flush path.
+ *
+ * This probe closes the loop on the NEXT session start, which is the first
+ * moment a human is actually looking: it reads the LAST flush record and warns
+ * when that record is a sandbox refusal. Newest-wins by construction — a later
+ * successful flush silently clears the warning, so the banner reports the
+ * CURRENT state of the channel, never its history.
+ *
+ * Never throws. Never mutates input. No network.
+ *
+ * @module scripts/lib/telemetry-flush-health-banner
+ */
+
+import { existsSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Bytes of `events.jsonl` read from the END of the file.
+ *
+ * The ledger is append-only and grows without bound (33k+ records in this repo
+ * alone), so a full `readFileSync` on a SessionStart hook's critical path is
+ * the wrong shape — this probe shares a 2s budget with ~18 siblings.
+ *
+ * NAMED CEILING (BV-004): a flush record older than the last 64 KB of the
+ * ledger is invisible to this probe and reads as "no flush recorded" → `null`
+ * (silent). At the observed record width (~120-400 bytes) that window holds
+ * roughly 150-500 events, and a flush is emitted once per session close — so
+ * the window covers the last flush unless ~150+ events landed after it without
+ * one, which cannot happen inside a single session's teardown.
+ * REVISIT TRIGGER: if the per-session event volume ever exceeds ~150 records
+ * between two session ends, raise this or index the ledger — do not silently
+ * accept the truncation.
+ */
+export const TAIL_BYTES = 64 * 1024;
+
+/** The event name `hooks/on-session-end.mjs` emits for every flush attempt. */
+const FLUSH_EVENT = 'orchestrator.telemetry.flush';
+
+/**
+ * Bound an untrusted ledger `reason` before it is interpolated into a terminal
+ * banner: strip C0/DEL control bytes (a record could carry an ANSI escape) and
+ * cap the length. Mirrors the sibling bound in
+ * `scripts/lib/session-start-probes.mjs` (`.slice(0, 200)` on a probe error).
+ *
+ * @param {unknown} reason
+ * @returns {string}
+ */
+function sanitizeReason(reason) {
+  // eslint-disable-next-line no-control-regex -- stripping control bytes IS the job
+  return String(reason).replace(/[\x00-\x1f\x7f]/g, '').slice(0, 120);
+}
+
+/**
+ * Read the last `TAIL_BYTES` of a file as UTF-8.
+ *
+ * Returns a DISCRIMINATED result rather than `string|null`, because "the
+ * ledger could not be read" and "the ledger holds nothing alarming" are the
+ * two states this probe exists to keep apart (HR-105): collapsing an EACCES
+ * onto `null` renders an unreadable channel as a healthy one.
+ *
+ * @param {string} file
+ * @returns {{text: string} | {missing: true} | {error: string}}
+ */
+function readTail(file) {
+  let fd;
+  try {
+    fd = openSync(file, 'r');
+    const { size } = fstatSync(fd);
+    const length = Math.min(size, TAIL_BYTES);
+    const start = size - length;
+    const buf = Buffer.allocUnsafe(length);
+    let read = 0;
+    while (read < length) {
+      const n = readSync(fd, buf, read, length - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return { text: buf.subarray(0, read).toString('utf8') };
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { missing: true };
+    return { error: typeof err?.code === 'string' ? err.code : 'EUNKNOWN' };
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}
+
+/**
+ * Classify the telemetry-flush channel from the LAST recorded flush event.
+ *
+ * Scans the ledger tail BACKWARDS and stops at the first
+ * `orchestrator.telemetry.flush` record it can parse — newest wins, so an
+ * older refusal followed by a successful flush produces no banner.
+ *
+ * Returns `null` (silent) when: `repoRoot` is not a string, the ledger is
+ * ABSENT, no flush record sits in the tail window, or the newest flush
+ * record's `reason` does not start with `sandbox:`. A malformed line is
+ * SKIPPED (it is not a flush record we can read), never a throw — the ledger's
+ * last line is routinely a partial write when another process is appending.
+ *
+ * An UNREADABLE ledger (EACCES/EIO/…, i.e. anything other than "not there") is
+ * NOT silent: it returns a `ledger-unreadable` warning. "The guard state
+ * cannot be confirmed" must not display like "the last flush was fine" — that
+ * collapse is the exact HR-105 defect this module's header cites as its reason
+ * to exist, one layer down.
+ *
+ * This probe reports the LAST outcome regardless of its age (no clock seam):
+ * a refusal does not expire on its own — only a later successful flush clears
+ * it.
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {null | {severity: 'warn', reason: string, message: string}}
+ */
+export function checkTelemetryFlushHealth({ repoRoot } = {}) {
+  try {
+    if (!repoRoot || typeof repoRoot !== 'string') return null;
+
+    const file = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+    if (!existsSync(file)) return null;
+
+    const tail = readTail(file);
+    if (tail.missing) return null;
+    if (tail.error) {
+      return {
+        severity: 'warn',
+        reason: 'ledger-unreadable',
+        message:
+          '⚠ Telemetry: flush-health unknown — .orchestrator/metrics/events.jsonl ' +
+          `could not be read (${sanitizeReason(tail.error)}); ` +
+          'the sandbox guard state cannot be confirmed.',
+      };
+    }
+    if (!tail.text) return null;
+
+    const lines = tail.text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        // Malformed (or a tail-truncated first line) — not readable as a flush
+        // record, so it cannot be the newest one. Keep scanning backwards.
+        continue;
+      }
+      if (!record || typeof record !== 'object') continue;
+      if (record.event !== FLUSH_EVENT) continue;
+
+      // First flush record found scanning backwards = the newest one.
+      const rawReason = record.reason;
+      if (typeof rawReason !== 'string' || !rawReason.startsWith('sandbox:')) return null;
+
+      // The ledger is an untrusted string source for banner purposes: bound the
+      // reason on BOTH surfaces (the field a consumer may render itself, and
+      // the message we render) rather than only on the one we happen to own.
+      const reason = sanitizeReason(rawReason);
+
+      return {
+        severity: 'warn',
+        reason,
+        message:
+          `⚠ Telemetry: last flush refused by the sandbox guard (${reason}) — ` +
+          'the guard could not complete its checks and failed closed; no ping was sent. ' +
+          'See docs/telemetry.md § Sandbox guard.',
+      };
+    }
+
+    return null;
+  } catch {
+    // Defensive catch-all — a banner probe must never throw (fail-open).
+    return null;
+  }
+}
+
+/**
+ * Convenience renderer: the banner message string, or `''` when silent.
+ *
+ * @param {{repoRoot: string}} opts
+ * @returns {string}
+ */
+export function renderBanner({ repoRoot } = {}) {
+  const result = checkTelemetryFlushHealth({ repoRoot });
+  return result ? result.message : '';
+}

package/scripts/lib/validate/check-agents-skills.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * check-agents-skills.mjs — validate the CROSS-HARNESS PORTABLE SURFACE.
+ *
+ * Scope note on the name: "agents-skills" is the `.agents`/`AGENTS`-family
+ * surface, not just the skill mirror. Three artefacts are checked, because
+ * they are one feature — the set of files a NON-Claude harness (Codex CLI,
+ * Cursor, Amp, Copilot CLI, OpenCode, Kiro) reads when it opens this repo:
+ *
+ *   A. root `AGENTS.md` — must be an alias of `CLAUDE.md` (symlink to the same
+ *      inode, or byte-identical).
+ *   B. root `plugin.json` — the agent-plugins.org 1.0.0 manifest; its `version`
+ *      must equal `package.json`'s and the two existing plugin manifests'.
+ *   C. `.agents/skills/<name>/SKILL.md` — one spec-legal mirror per source
+ *      skill, no orphans, agentskills.io field list only, description ≤ 1024.
+ *
+ * INDEPENDENCE (load-bearing). This checker deliberately imports NOTHING from
+ * `scripts/generate-agents-skills.mjs` and re-derives the spec field list, the
+ * 1024 cap and the alias rule from the spec, not from the generator. A
+ * generator-vs-generator check only proves the generator is self-consistent —
+ * that is how the Cursor `argument-hint` defect survived. The oracles here are
+ * the repository's own filesystem (`skills/`, `CLAUDE.md`, `package.json`) and
+ * the published field list.
+ *
+ * Usage: node scripts/lib/validate/check-agents-skills.mjs <plugin-root>
+ * Exit codes: 0 — all checks passed · 1 — one or more failures.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync, lstatSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-agents-skills.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+const pass = (msg) => { console.log(`  PASS: ${msg}`); passed += 1; };
+const fail = (msg) => { console.log(`  FAIL: ${msg}`); failed += 1; };
+
+/**
+ * The complete agentskills.io field list permitted outside Claude Code.
+ * Re-derived from the spec here on purpose — see INDEPENDENCE above.
+ */
+const SPEC_KEYS = new Set(['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools']);
+const DESCRIPTION_MAX = 1024;
+
+/**
+ * Per-mirror byte ceiling. A mirror is a frontmatter block plus a 6-line
+ * pointer; the largest one measured 2026-09-06 was ~1.9 KB (its description is
+ * 1012 chars). The ceiling exists to catch the failure this design prevents —
+ * a mirror that starts duplicating the canonical body, which would double the
+ * instruction corpus a foreign harness loads. Revisit trigger: raise it only
+ * together with a re-measurement of `.agents/skills/` total bytes, never to
+ * accommodate a body that was pasted in.
+ */
+const MIRROR_MAX_BYTES = 4096;
+
+const AGENT_PLUGINS_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';
+
+/** Read + parse a JSON file; null on missing or malformed. */
+function readJson(absPath) {
+  if (!existsSync(absPath)) return null;
+  try { return JSON.parse(readFileSync(absPath, 'utf8')); } catch { return null; }
+}
+
+/** Split a Markdown file into `{ frontmatter, body }`; frontmatter null when absent/unparseable. */
+function splitFrontmatter(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(content);
+  if (!m) return { frontmatter: null, body: content };
+  try {
+    const parsed = yaml.load(m[1]);
+    return {
+      frontmatter: parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null,
+      body: m[2],
+    };
+  } catch {
+    return { frontmatter: null, body: m[2] };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// A. root AGENTS.md is an alias of CLAUDE.md
+// ---------------------------------------------------------------------------
+
+console.log('--- Check A: root AGENTS.md ↔ CLAUDE.md alias ---');
+{
+  const claudePath = join(pluginRoot, 'CLAUDE.md');
+  const agentsPath = join(pluginRoot, 'AGENTS.md');
+  if (!existsSync(claudePath)) {
+    pass('no CLAUDE.md at plugin root — alias check not applicable');
+  } else if (!existsSync(agentsPath)) {
+    fail('CLAUDE.md exists but AGENTS.md does not — Codex CLI, OpenCode, Kiro and Amp '
+      + 'read AGENTS.md and never CLAUDE.md, so this repo would ship without a Session Config for them '
+      + '(remedy: node scripts/generate-agents-skills.mjs)');
+  } else {
+    let aliased = false;
+    let how = '';
+    try {
+      if (lstatSync(agentsPath).isSymbolicLink()) {
+        aliased = realpathSync(agentsPath) === realpathSync(claudePath);
+        how = 'symlink';
+      } else {
+        const a = statSync(agentsPath);
+        const c = statSync(claudePath);
+        if (a.ino !== 0 && a.ino === c.ino && a.dev === c.dev) { aliased = true; how = 'same inode'; }
+      }
+    } catch { /* fall through to the byte comparison */ }
+    if (!aliased) {
+      aliased = readFileSync(agentsPath).equals(readFileSync(claudePath));
+      how = 'byte-identical';
+    }
+    if (aliased) {
+      pass(`AGENTS.md is an alias of CLAUDE.md (${how})`);
+    } else {
+      fail('AGENTS.md and CLAUDE.md are two independent files that disagree — AGENTS.md is GENERATED; '
+        + 'put the change in CLAUDE.md and run `node scripts/generate-agents-skills.mjs`');
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// B. root plugin.json (agent-plugins.org 1.0.0)
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check B: root plugin.json (agent-plugins.org 1.0.0) ---');
+{
+  const rootManifest = readJson(join(pluginRoot, 'plugin.json'));
+  if (rootManifest === null) {
+    if (existsSync(join(pluginRoot, 'plugin.json'))) {
+      fail('plugin.json exists but is not valid JSON');
+    } else {
+      pass('no root plugin.json — vendor-neutral manifest not shipped');
+    }
+  } else {
+    if (rootManifest.$schema === AGENT_PLUGINS_SCHEMA) {
+      pass('plugin.json declares the agent-plugins.org 1.0.0 $schema');
+    } else {
+      fail(`plugin.json $schema is '${rootManifest.$schema ?? '(unset)'}', expected '${AGENT_PLUGINS_SCHEMA}'`);
+    }
+
+    for (const field of ['name', 'version', 'description', 'license']) {
+      if (typeof rootManifest[field] === 'string' && rootManifest[field].trim()) {
+        pass(`plugin.json has a non-empty '${field}'`);
+      } else {
+        fail(`plugin.json is missing required field '${field}'`);
+      }
+    }
+
+    // Version parity across ALL manifests. Three manifests now carry a version
+    // and only `package.json` is bumped by the release script — a third copy
+    // that drifts silently is the whole reason this case exists.
+    const pkg = readJson(join(pluginRoot, 'package.json'));
+    const pkgVersion = pkg?.version ?? null;
+    if (!pkgVersion) {
+      fail('package.json has no version — cannot verify manifest version parity');
+    } else if (rootManifest.version === pkgVersion) {
+      pass(`plugin.json version matches package.json (${pkgVersion})`);
+    } else {
+      fail(`plugin.json version '${rootManifest.version}' != package.json version '${pkgVersion}' `
+        + '— the release script bumps package.json only');
+    }
+
+    const claudeManifest = readJson(join(pluginRoot, '.claude-plugin', 'plugin.json'));
+    if (claudeManifest?.version && rootManifest.version !== claudeManifest.version) {
+      fail(`plugin.json version '${rootManifest.version}' != .claude-plugin/plugin.json version '${claudeManifest.version}'`);
+    } else if (claudeManifest?.version) {
+      pass('plugin.json version matches .claude-plugin/plugin.json');
+    }
+
+    // Declared component paths must exist — a manifest may not advertise a
+    // component this repo does not ship.
+    let componentFail = 0;
+    for (const [key, value] of Object.entries(rootManifest)) {
+      if (typeof value !== 'string' || !value.startsWith('./')) continue;
+      if (key === '$schema') continue;
+      if (!existsSync(join(pluginRoot, value))) {
+        fail(`plugin.json component '${key}' points at '${value}' which does not exist`);
+        componentFail += 1;
+      }
+    }
+    if (componentFail === 0) pass('all plugin.json component paths resolve on disk');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// C. .agents/skills/ portable mirror
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check C: .agents/skills/ portable mirror ---');
+{
+  const skillsDir = join(pluginRoot, 'skills');
+  const mirrorDir = join(pluginRoot, '.agents', 'skills');
+
+  const sourceSkills = existsSync(skillsDir) && statSync(skillsDir).isDirectory()
+    ? readdirSync(skillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !e.name.startsWith('_'))
+      .map((e) => e.name)
+      .filter((n) => existsSync(join(skillsDir, n, 'SKILL.md')))
+      .sort()
+    : [];
+
+  if (!existsSync(mirrorDir)) {
+    if (sourceSkills.length === 0) {
+      pass('no skills/ and no .agents/skills/ — nothing to mirror');
+    } else {
+      fail(`.agents/skills/ is missing but ${sourceSkills.length} source skill(s) exist `
+        + '(remedy: node scripts/generate-agents-skills.mjs)');
+    }
+  } else {
+    const mirrored = readdirSync(mirrorDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+      .map((e) => e.name)
+      .sort();
+
+    const missing = sourceSkills.filter((n) => !mirrored.includes(n));
+    const orphans = mirrored.filter((n) => !sourceSkills.includes(n));
+    if (missing.length === 0) pass(`every source skill has a mirror (${sourceSkills.length})`);
+    else fail(`${missing.length} source skill(s) have no mirror: ${missing.join(', ')}`);
+    if (orphans.length === 0) pass('no orphan mirrors');
+    else fail(`${orphans.length} orphan mirror(s) with no source skill: ${orphans.join(', ')}`);
+
+    let fmFail = 0;
+    let keyFail = 0;
+    let descFail = 0;
+    let sizeFail = 0;
+    let pointerFail = 0;
+    let totalBytes = 0;
+
+    for (const name of mirrored) {
+      const file = join(mirrorDir, name, 'SKILL.md');
+      if (!existsSync(file)) {
+        fail(`.agents/skills/${name}/ has no SKILL.md`);
+        fmFail += 1;
+        continue;
+      }
+      const raw = readFileSync(file, 'utf8');
+      totalBytes += Buffer.byteLength(raw, 'utf8');
+
+      if (Buffer.byteLength(raw, 'utf8') > MIRROR_MAX_BYTES) {
+        fail(`.agents/skills/${name}/SKILL.md is ${Buffer.byteLength(raw, 'utf8')} bytes `
+          + `(> ${MIRROR_MAX_BYTES}) — the mirror must point at the canonical body, never duplicate it`);
+        sizeFail += 1;
+      }
+
+      const { frontmatter, body } = splitFrontmatter(raw);
+      if (!frontmatter) {
+        fail(`.agents/skills/${name}/SKILL.md has no parseable YAML frontmatter`);
+        fmFail += 1;
+        continue;
+      }
+
+      for (const key of Object.keys(frontmatter)) {
+        if (!SPEC_KEYS.has(key)) {
+          fail(`.agents/skills/${name}/SKILL.md frontmatter carries non-spec key '${key}' `
+            + `(agentskills.io permits only: ${[...SPEC_KEYS].join(', ')})`);
+          keyFail += 1;
+        }
+      }
+
+      if (frontmatter.name !== name) {
+        fail(`.agents/skills/${name}/SKILL.md declares name '${frontmatter.name}' != directory '${name}'`);
+        keyFail += 1;
+      } else if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) {
+        fail(`.agents/skills/${name}/SKILL.md name is not kebab-case`);
+        keyFail += 1;
+      }
+
+      const desc = frontmatter.description;
+      if (typeof desc !== 'string' || !desc.trim()) {
+        fail(`.agents/skills/${name}/SKILL.md has an empty description`);
+        descFail += 1;
+      } else if (desc.length > DESCRIPTION_MAX) {
+        fail(`.agents/skills/${name}/SKILL.md description is ${desc.length} chars (> ${DESCRIPTION_MAX})`);
+        descFail += 1;
+      }
+
+      if ('metadata' in frontmatter) {
+        const md = frontmatter.metadata;
+        if (!md || typeof md !== 'object' || Array.isArray(md)) {
+          fail(`.agents/skills/${name}/SKILL.md metadata is not a string map`);
+          keyFail += 1;
+        } else {
+          for (const [mk, mv] of Object.entries(md)) {
+            if (typeof mv !== 'string') {
+              fail(`.agents/skills/${name}/SKILL.md metadata.${mk} is ${typeof mv}, expected string`);
+              keyFail += 1;
+            }
+          }
+        }
+      }
+
+      if ('allowed-tools' in frontmatter) {
+        const tools = frontmatter['allowed-tools'];
+        if (!Array.isArray(tools) || tools.some((t) => typeof t !== 'string' || !t.trim())) {
+          fail(`.agents/skills/${name}/SKILL.md allowed-tools is not an array of non-empty strings`);
+          keyFail += 1;
+        }
+      }
+
+      if (!body.includes(`skills/${name}/SKILL.md`)) {
+        fail(`.agents/skills/${name}/SKILL.md body does not cite the canonical skills/${name}/SKILL.md `
+          + '— the mirror is a pointer, and a pointer with no target is dead weight');
+        pointerFail += 1;
+      }
+    }
+
+    if (fmFail === 0 && mirrored.length > 0) pass(`all ${mirrored.length} mirrors have parseable frontmatter`);
+    if (keyFail === 0 && mirrored.length > 0) pass('all mirrors use only agentskills.io spec fields');
+    if (descFail === 0 && mirrored.length > 0) pass(`all mirror descriptions are non-empty and ≤ ${DESCRIPTION_MAX} chars`);
+    if (sizeFail === 0 && mirrored.length > 0) pass(`all mirrors ≤ ${MIRROR_MAX_BYTES} bytes (total ${totalBytes} bytes)`);
+    if (pointerFail === 0 && mirrored.length > 0) pass('all mirrors cite their canonical SKILL.md');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Results
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-agents.mjs

@@ -547,7 +547,7 @@ if (existsSync(agentsDir)) {
 //   agents at a glance). With more than 9 agents, colors are deliberately
 //   shared — but two DISPATCHABLE agents sharing a color is a likely
 //   same-wave collision and surfaces as a WARN (not FAIL: deliberate
-//   cross-phase shares are legitimate — see agents/AGENTS.md § Color
+//   cross-phase shares are legitimate — see docs/agent-authoring.md § Color
 //   Allocation Strategy).
 //   Non-dispatchable reference docs (description contains "NOT a dispatchable"
 //   or "Reference documentation") are excluded from the aggregation: they
@@ -581,7 +581,7 @@ if (existsSync(agentsDir)) {
   for (const [color, names] of colorMap) {
     if (names.length > 1) {
       collisions++;
-      warn(`color collision: ${color} shared by dispatchable agents ${names.sort().join(', ')} — confirm they never co-run in one wave (agents/AGENTS.md § Color Allocation Strategy)`);
+      warn(`color collision: ${color} shared by dispatchable agents ${names.sort().join(', ')} — confirm they never co-run in one wave (docs/agent-authoring.md § Color Allocation Strategy)`);
     }
   }
   if (collisions === 0) {
@@ -632,7 +632,7 @@ if (existsSync(agentsDir)) {
     if (missing.length > 0) {
       fail(
         `${agentFile}: repo-write agent (Edit+Write) is missing ${missing.join(' and ')} ` +
-          '— see .claude/rules/parallel-sessions.md § PSA-007 and agents/AGENTS.md § Authoring Convention',
+          '— see .claude/rules/parallel-sessions.md § PSA-007 and docs/agent-authoring.md § Git-Write Ban Requirement',
       );
     } else {
       pass(`${agentFile}: PSA-007 git-write ban present`);