@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/_lib/design_tolerance.ts

@@ -0,0 +1,281 @@
+/**
+ * Value reconciliation between a provided design artifact and a project's own
+ * tokens — the MEASUREMENT half, shipped; the BEHAVIOURAL half, deliberately
+ * not.
+ *
+ * WHAT THE COUNCIL DECIDED, and why this module is shaped this way.
+ *
+ * `road-to-design-intent-conformance` put `blocker: approximation-tolerance` to
+ * the AI council (anthropic + openai, 2/2, 2026-09-09). Neither member accepted
+ * any of the three options as written. Both split step 3.2 the same way: build
+ * the metric, the collection and the reporting now; ship **no tolerance
+ * constant at all**; defer the behaviour that would let a value change without
+ * being asked about.
+ *
+ * The argument that decided it, and it is the one to re-read before adding a
+ * number here: *"a number in a config file, even flagged unmeasured, shapes
+ * behaviour and creates path dependency."* Zero of seven design-to-code
+ * benchmarks in the evidence set score token conformance, so a shipped
+ * threshold would be a guess acquiring the authority of a default. Both
+ * `design.tolerance.*` keys therefore ship `null`, and `null` means **preserve
+ * and report**, never "reconcile freely".
+ *
+ * THE METRIC IS A PREREQUISITE the roadmap never named.
+ *
+ * The council added it: no colour tolerance is meaningful before the distance
+ * METHOD is fixed, because RGB Euclidean, ΔE LAB, CIEDE2000 and OKLab/ΔEOK give
+ * different numbers for the same pair. `openai` rejected the round's proposed
+ * `±5 per RGB channel` on exactly this ground — RGB channel distance is not
+ * perceptually uniform, so "likely imperceptible" is an unsupported conclusion.
+ *
+ * This module fixes the method as **OKLab ΔEOK** (a plain Euclidean distance in
+ * OKLab, the metric OKLab was designed to make meaningful) and leaves the
+ * threshold empty. Method without threshold is the honest state: the distance
+ * on every row is a real, comparable number, and nothing yet says which
+ * distances are small enough to act on.
+ *
+ * LENGTH CARRIES NO SHIPPED NUMBER either.
+ *
+ * Primer's spacing plugin widens each token's accepted set by ±1px and
+ * autofixes. That is the one real measurement in the evidence set and it is
+ * recorded as an **externally observed candidate**, not adopted:
+ * `OBSERVED_LENGTH_CANDIDATE_PX` exists to be cited, and no code path reads it
+ * as a threshold. The round's other proposal, `max(1px, 2%)`, was rejected for
+ * growing steadily more permissive at large dimensions with no evidence that
+ * this is wanted.
+ *
+ * EVERY ROW CARRIES ITS DISTANCE, even when the value is preserved.
+ *
+ * That is the step's own verify clause and it is the property that makes the
+ * deferred half decidable later: a shadow window over rows that report
+ * distances can produce a distribution, where a window over rows that report
+ * only "kept" or "changed" cannot.
+ */
+
+/** Fixed method. See the header: the threshold is absent, the metric is not. */
+export const COLOR_DISTANCE_METRIC = 'oklab-deltaEOK' as const;
+/** Fixed method for lengths: absolute difference in CSS pixels. */
+export const LENGTH_DISTANCE_METRIC = 'abs-px' as const;
+
+/**
+ * GitHub Primer's spacing plugin widens each token's accepted set by ±1px.
+ * Recorded as an externally observed candidate for a future threshold; **no
+ * code path reads this as one**, and a test pins that it never becomes the
+ * shipped default without a decision.
+ */
+export const OBSERVED_LENGTH_CANDIDATE_PX = 1;
+
+export interface ToleranceConfig {
+    /** Master switch. Ships `false`; `blocker: fidelity-default-flip` → (a). */
+    enabled: boolean;
+    /** ΔEOK below which a colour may be reconciled. `null` ships. */
+    color: number | null;
+    /** Pixels below which a length may be reconciled. `null` ships. */
+    length: number | null;
+}
+
+/** The shipped configuration. Both thresholds absent, mechanism off. */
+export const SHIPPED_TOLERANCE: ToleranceConfig = { enabled: false, color: null, length: null };
+
+export type ReconcileOutcome =
+    /** Inside tolerance: the project token wins, and the change is reported. */
+    | 'reconciled'
+    /** Outside tolerance: the artifact's value is preserved, gap reported. */
+    | 'preserved-outside-tolerance'
+    /** The mechanism is off, or no threshold is configured: preserve, report. */
+    | 'preserved-mechanism-off'
+    /** No project token to compare against: nothing to reconcile onto. */
+    | 'no-candidate';
+
+export interface TokenCandidate {
+    name: string;
+    value: string;
+}
+
+export interface ValueRow {
+    /** The artifact's own value, verbatim. */
+    artifact: string;
+    /** Nearest project token, or null when the project has none of this kind. */
+    nearest: TokenCandidate | null;
+    /** Distance to `nearest` in the metric named below. Null iff no candidate. */
+    distance: number | null;
+    metric: typeof COLOR_DISTANCE_METRIC | typeof LENGTH_DISTANCE_METRIC | null;
+    /** The value actually written. Equals `artifact` unless reconciled. */
+    resolved: string;
+    outcome: ReconcileOutcome;
+}
+
+// ------------------------------------------------------------------ colour
+
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+
+/**
+ * `#rgb` / `#rrggbb` → 0–1 channels, or null when unparseable.
+ *
+ * An 8-digit `#rrggbbaa` returns NULL rather than its opaque prefix. ΔEOK is a
+ * three-channel metric and has nothing to say about alpha, so truncating made
+ * `#ff000080` and `#ff0000` measure distance 0 — "identical" for two values a
+ * designer chose to differ. Found by a blind review. Null is the honest answer:
+ * the row is reported as unmeasured, which is what it is.
+ */
+export function parseHex(value: string): Rgb | null {
+    const m = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(value.trim());
+    if (!m) return null;
+    let hex = m[1] as string;
+    if (hex.length === 3) {
+        hex = hex
+            .split('')
+            .map((c) => c + c)
+            .join('');
+    }
+    return {
+        r: parseInt(hex.slice(0, 2), 16) / 255,
+        g: parseInt(hex.slice(2, 4), 16) / 255,
+        b: parseInt(hex.slice(4, 6), 16) / 255,
+    };
+}
+
+/** sRGB transfer function, inverted — required before the OKLab matrices. */
+function toLinear(c: number): number {
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/** sRGB → OKLab (Björn Ottosson's published matrices). */
+export function srgbToOklab(rgb: Rgb): { L: number; a: number; b: number } {
+    const r = toLinear(rgb.r);
+    const g = toLinear(rgb.g);
+    const b = toLinear(rgb.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+
+/**
+ * ΔEOK — Euclidean distance in OKLab. Null when either value is not a hex
+ * colour this module can parse; an unparseable value is reported as unmeasured
+ * rather than assigned a distance of zero, which would read as "identical".
+ */
+export function deltaEOK(a: string, b: string): number | null {
+    const ra = parseHex(a);
+    const rb = parseHex(b);
+    if (!ra || !rb) return null;
+    const la = srgbToOklab(ra);
+    const lb = srgbToOklab(rb);
+    return Math.sqrt((la.L - lb.L) ** 2 + (la.a - lb.a) ** 2 + (la.b - lb.b) ** 2);
+}
+
+// ------------------------------------------------------------------ length
+
+/** `16px` / `1rem` / `0.5rem` → pixels at a 16px root, or null. */
+export function parseLengthPx(value: string, rootPx = 16): number | null {
+    const m = /^(-?\d*\.?\d+)(px|rem|em)$/.exec(value.trim());
+    if (!m) return null;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n)) return null;
+    return m[2] === 'px' ? n : n * rootPx;
+}
+
+/** Absolute pixel difference, or null when either side is unparseable. */
+export function lengthDistancePx(a: string, b: string, rootPx = 16): number | null {
+    const pa = parseLengthPx(a, rootPx);
+    const pb = parseLengthPx(b, rootPx);
+    if (pa === null || pb === null) return null;
+    return Math.abs(pa - pb);
+}
+
+// ------------------------------------------------------------- reconcile
+
+export type ValueKind = 'color' | 'length';
+
+function distanceFor(kind: ValueKind, a: string, b: string): number | null {
+    return kind === 'color' ? deltaEOK(a, b) : lengthDistancePx(a, b);
+}
+
+/** Nearest candidate by the kind's own metric. Ties break on first-listed. */
+export function nearestToken(
+    kind: ValueKind,
+    artifact: string,
+    candidates: readonly TokenCandidate[],
+): { candidate: TokenCandidate; distance: number } | null {
+    let best: { candidate: TokenCandidate; distance: number } | null = null;
+    for (const candidate of candidates) {
+        const d = distanceFor(kind, artifact, candidate.value);
+        if (d === null) continue;
+        if (best === null || d < best.distance) best = { candidate, distance: d };
+    }
+    return best;
+}
+
+/**
+ * Reconcile one artifact value against the project's tokens.
+ *
+ * **The distance is computed and reported on every path**, including every path
+ * that preserves the artifact's value — that is the step's verify clause, and
+ * it is what makes a later shadow distribution possible.
+ */
+export function reconcileValue(
+    kind: ValueKind,
+    artifact: string,
+    candidates: readonly TokenCandidate[],
+    config: ToleranceConfig = SHIPPED_TOLERANCE,
+): ValueRow {
+    const metric = kind === 'color' ? COLOR_DISTANCE_METRIC : LENGTH_DISTANCE_METRIC;
+    const best = nearestToken(kind, artifact, candidates);
+
+    if (best === null) {
+        return {
+            artifact,
+            nearest: null,
+            distance: null,
+            metric: null,
+            resolved: artifact,
+            outcome: 'no-candidate',
+        };
+    }
+
+    const base = {
+        artifact,
+        nearest: best.candidate,
+        distance: best.distance,
+        metric,
+    } as const;
+
+    const threshold = kind === 'color' ? config.color : config.length;
+
+    // Off, or no threshold configured. These are ONE outcome on purpose: a
+    // mechanism with no threshold cannot act, so reporting it as anything but
+    // "off" would imply a decision nobody made.
+    if (!config.enabled || threshold === null) {
+        return { ...base, resolved: artifact, outcome: 'preserved-mechanism-off' };
+    }
+
+    if (best.distance <= threshold) {
+        return { ...base, resolved: best.candidate.value, outcome: 'reconciled' };
+    }
+    return { ...base, resolved: artifact, outcome: 'preserved-outside-tolerance' };
+}
+
+/** One human-readable row. Always names the distance, never only the verdict. */
+export function formatRow(row: ValueRow): string {
+    if (row.nearest === null || row.distance === null) {
+        return `${row.artifact} → kept (no project token of this kind to compare against)`;
+    }
+    const d = `${row.metric ?? '?'} ${row.distance.toFixed(4)}`;
+    switch (row.outcome) {
+        case 'reconciled':
+            return `${row.artifact} → ${row.nearest.name} (${row.nearest.value}); reconciled, distance ${d}`;
+        case 'preserved-outside-tolerance':
+            return `${row.artifact} → kept; nearest ${row.nearest.name} (${row.nearest.value}) is outside tolerance, distance ${d}`;
+        default:
+            return `${row.artifact} → kept; nearest ${row.nearest.name} (${row.nearest.value}), distance ${d} (reconciliation off)`;
+    }
+}

package/src/scripts/_lib/dropped_decision.ts

@@ -0,0 +1,142 @@
+/**
+ * Detector E of `turn-end-gate`, extracted so its prose costs nothing.
+ *
+ * It lives here rather than in the hook for one mechanical reason and one real
+ * one. The mechanical one: `turn_end_gate_hook.ts` sits past the 1500-line
+ * source ceiling, where every line is one unit of ratchet debt, and this module
+ * is under it. The real one: E is the only detector that reads a LIST of the
+ * turn's assistant texts rather than the single closing one, so it shares no
+ * input with A-D and F, and its dependencies are the reply-consistency parser
+ * rather than anything the hook owns.
+ */
+import {
+    find_option_blocks,
+    recommendationsUnder,
+    splitAndMask,
+} from '../check_reply_consistency.js';
+import type { RefusalDetectorId } from './turn_end_refusals.js';
+
+/** The shape the gate collects. Kept structural so this module imports no hook. */
+export interface DroppedDecisionFinding {
+    detector: RefusalDetectorId;
+    evidence: string;
+    reason: string;
+}
+
+/**
+ * Detector E — a decision put to the user in this turn, dropped before the turn
+ * ended.
+ *
+ * THE MEASURED FAILURE. An assistant turn put three numbered options and a
+ * recommendation line to the user. The `end-review-nudge` stop concern then
+ * produced a SECOND assistant execution with no intervening user message, and
+ * that second reply handled the nudge while demoting the open question to a
+ * subordinate clause — "bleibt davon unberührt und liegt bei Dir". From the
+ * user's side the conversation ended without a question. No rule stated this
+ * when the detector was written: `user-interaction` Iron Law 1 inspects a reply
+ * that HAS an options block, `check_reply_consistency` receives a draft and not
+ * a transcript, `active-remediation` governs findings rather than issued
+ * decisions, and `no-cheap-questions` guards the opposite direction. That gap
+ * is now closed from the other side — `user-interaction` Iron Law 3 states the
+ * continuity obligation, and the refusal below cites it — so this paragraph
+ * records why the detector exists, not a gap that is still open.
+ *
+ * WHAT IT READS. `assistantTurnTexts` — the assistant texts since the last
+ * GENUINE user prompt, with synthetic prompts and sidechain entries already
+ * filtered by `readTranscriptTail`. So a task notification, a system reminder or
+ * a subagent's own prompt does not read as an answer, which is the whole point:
+ * the failure is defined by the absence of a real user turn.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It does not model the decision — no id, no
+ * `pending → answered` lifecycle, no semantic matching of a free-text reply
+ * against an option. That object is grant-shaped and
+ * `road-to-decision-closure` owns its ownership routing; a second obligation
+ * ledger here would be the parallel taxonomy that roadmap exists to prevent.
+ * This is transcript adjacency and nothing above it.
+ *
+ * AN ASK IS A BLOCK **PLUS** ITS RECOMMENDATION LINE, and that qualifier is
+ * load-bearing rather than pedantic. `find_option_blocks` calls any run of two
+ * or more consecutive numbered lines a block — a plan, a findings list, an
+ * ordinary enumeration. Keyed on the block alone this detector fired on 29 of
+ * this repository's own 592 assistant turns, and 8 of those blocks carried no
+ * recommendation line anywhere near them: pure false positives on narrative
+ * lists, in a detector that can REFUSE a turn. `user-interaction` Iron Law 1
+ * already says the recommendation line is the ask, so requiring it removes that
+ * whole class by applying the rule this refusal cites rather than by bolting a
+ * heuristic beside it.
+ *
+ * The cost, stated rather than discovered: an options block whose recommendation
+ * line was omitted is invisible here. That reply is ALREADY a
+ * `check_reply_consistency` finding and a stated Iron Law 1 violation, so it is
+ * the malformed-ask problem rather than the dropped-ask problem — a different
+ * defect with a different owner.
+ *
+ * REUSE. `find_option_blocks` and `recommendationsUnder` are both the
+ * spec-backed readings behind `check_reply_consistency`, extracted rather than
+ * copied. `interruption_ledger_hook` carries its own `hasNumberedOptions` for
+ * the capture-only ledger; a third reading of the same rule would drift from
+ * both.
+ *
+ * TWO KNOWN FALSE-POSITIVE PATHS, named because a refusing detector owes its
+ * residual rather than only its fix:
+ *
+ *   · A BLOCKQUOTED illustration of an ask — `> 1.` / `> 2.` plus a quoted
+ *     recommendation line — reads as live. `OPTION_LINE_RE` accepts a leading
+ *     `>` deliberately, because this suite's own documented ask shape is often
+ *     blockquoted, so excluding it would miss real asks to avoid a quoted one.
+ *     Fenced illustrations ARE excluded and tested; blockquoted ones are not,
+ *     and narrowing the shared parser to fix that would change what
+ *     `check_reply_consistency` enforces about Iron Law 1.
+ *   · A genuine user turn carrying NO `type: 'text'` block — an image-only
+ *     message — does not reset the turn, because `readTranscriptTail` skips an
+ *     entry with no text before reaching the reset. Changing that would move
+ *     `turnOrdinal` for all four other detectors on a shape none of them has
+ *     been measured against.
+ *
+ * Both cost one extra line in a reply, once: the re-entrancy layers cap a turn
+ * at ONE refusal, so neither can wedge a session.
+ */
+export function detectDroppedDecision(
+    assistantTurnTexts: readonly string[],
+    closingFromPayload = false,
+): DroppedDecisionFinding | null {
+    if (assistantTurnTexts.length < 2) return null;
+    // Masked once per text, not once per block: this runs on the stop path over
+    // every assistant text of the turn, and a reply with four numbered blocks
+    // would otherwise split and fence-mask the whole reply four times.
+    const asksIn = (text: string): ReturnType<typeof find_option_blocks> => {
+        const blocks = find_option_blocks(text);
+        if (blocks.length === 0) return blocks;
+        const masked = splitAndMask(text);
+        return blocks.filter((b) => recommendationsUnder(text, b, masked).length > 0);
+    };
+    const closing = assistantTurnTexts[assistantTurnTexts.length - 1]!;
+    if (asksIn(closing).length > 0) return null;
+    for (let i = assistantTurnTexts.length - 2; i >= 0; i -= 1) {
+        const earlier = assistantTurnTexts[i]!;
+        const blocks = asksIn(earlier);
+        if (blocks.length === 0) continue;
+        const block = blocks[blocks.length - 1]!;
+        return {
+            detector: 'pending-decision',
+            // The option NUMBERS and the line span, never the option text: the
+            // evidence is quoted into a refusal that reaches the transcript, and
+            // an options block can carry anything the reply carried.
+            evidence:
+                `options ${block.numbers.join('/')} at lines ${block.startLine}-${block.endLine} ` +
+                `of an earlier reply this turn (closing reply read from ` +
+                `${closingFromPayload ? 'the stop payload' : 'the transcript'})`,
+            reason:
+                'an earlier reply in THIS turn put numbered options to the user ' +
+                'and no user answer followed — this closing reply carries no ' +
+                'options block, so the decision disappeared without being ' +
+                'answered, cancelled or superseded. A hook nudge, a reviewer ' +
+                'result or a task notification may ADD to a turn; it may not ' +
+                'displace a question already asked (user-interaction Iron Law 3: ' +
+                'a decision handed to the user outlives the turn). ' +
+                'Re-present the block and its recommendation line at the end of ' +
+                'this reply',
+        };
+    }
+    return null;
+}

package/src/scripts/_lib/guidelines_lane.ts

@@ -0,0 +1,164 @@
+/**
+ * The `docs/guidelines/` → `dist/agent-src/guidelines/` projection lane.
+ *
+ * Why this exists at all: the projected rules declare `routes_to:
+ * guideline:<slug>` against **22 distinct targets** and link
+ * `../../docs/guidelines/<slug>.md`, and until this lane shipped
+ * `dist/agent-src/` carried no `guidelines/` directory — so every one of those
+ * routes was declared and dead in a consumer install. (The figure is the gate's own reading. An
+ * earlier draft here said "31 rules", which reproduced on nothing: `grep -l`
+ * returns 22 in both trees. A blind review checked it; the number is now the
+ * one `check_projected_rule_routes` prints.) `AUGMENT_SYMLINK_DIRS`
+ * in `condense.ts` has listed `guidelines` since before the lane existed; the
+ * symlink simply had nothing to point at.
+ *
+ * Shape, and why it is a lane rather than a source root: the multi-root
+ * resolver in `agent_src.ts` derives an artefact's *identity* from
+ * `_root_specs()`, and everything that scans the artefact estate — the
+ * discovery manifest, the skill linter, the size and count ratchets — walks
+ * that same list. Adding `docs/guidelines` there would reclassify 119
+ * guidelines as estate artefacts and move every one of those numbers. So the
+ * lane is appended only where the *projection* reads (`iter_all_sources` and
+ * `resolve_logical`), exactly as `_iter_domains_commands` already is, and the
+ * estate view is left alone.
+ *
+ * Identity: `docs/guidelines/<subpath>.md` is logical `guidelines/<subpath>.md`
+ * — one directory deep in the projection, the same depth as `rules/` and
+ * `skills/`, which is what makes the existing `../guidelines/…` rewrite in
+ * `condense.ts::_rewrite_body_links` resolve from a projected rule.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Logical-path prefix every guideline is projected under. */
+export const GUIDELINES_LOGICAL_PREFIX = 'guidelines/';
+
+/** Physical source directory, relative to the repo root. */
+export const GUIDELINES_SOURCE_REL = path.join('docs', 'guidelines');
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** Recursive, name-sorted at every level so the walk order is deterministic. */
+function* _walkSorted(dir: string): Generator<string> {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir).sort();
+    } catch {
+        return;
+    }
+    for (const name of entries) {
+        const full = path.join(dir, name);
+        if (_isDir(full)) {
+            yield* _walkSorted(full);
+        } else if (_isFile(full)) {
+            yield full;
+        }
+    }
+}
+
+/**
+ * Yield `[physical_path, logical_relpath]` for every file under
+ * `<root>/docs/guidelines/`. Deterministic order; yields nothing when the
+ * directory is absent, which is the normal state of a consumer checkout.
+ */
+export function* iter_guidelines(root: string): Generator<[string, string]> {
+    const base = path.join(root, GUIDELINES_SOURCE_REL);
+    if (!_isDir(base)) {
+        return;
+    }
+    for (const p of _walkSorted(base)) {
+        const rel = path.relative(base, p).split(path.sep).join('/');
+        yield [p, GUIDELINES_LOGICAL_PREFIX + rel];
+    }
+}
+
+/**
+ * Physical path backing a logical `guidelines/<subpath>`, or `null` when the
+ * logical path is not a guideline or the file does not exist.
+ */
+export function resolve_guideline(root: string, logical_rel: string): string | null {
+    const rel = logical_rel.replaceAll('\\', '/').replace(/^\/+/, '');
+    if (!rel.startsWith(GUIDELINES_LOGICAL_PREFIX)) {
+        return null;
+    }
+    const suffix = rel.slice(GUIDELINES_LOGICAL_PREFIX.length);
+    if (suffix.length === 0 || suffix.split('/').includes('..')) {
+        return null;
+    }
+    const candidate = path.join(root, GUIDELINES_SOURCE_REL, suffix);
+    return _isFile(candidate) ? candidate : null;
+}
+
+/**
+ * Rewrite a projected body's relative `.md` links onto the projection.
+ *
+ * Lives here rather than in `condense.ts` for two reasons, and the second is
+ * the load-bearing one. It is this lane's own subject: every rule it applies is
+ * a statement about which source trees project where, which is what this module
+ * exists to know. And `condense.ts` sits ~1,200 lines past the 1,500-line
+ * ceiling `check_source_size_budget` ratchets, so every line there costs one
+ * unit of excess while every line here costs zero — the doctrine that file's
+ * own baseline note prescribes for exactly this case.
+ *
+ * `prefix` is the caller's depth prefix (`../` per level below
+ * `dist/agent-src/`), so a rule at depth 1 and a guideline at depth 2 both
+ * resolve.
+ */
+export function rewriteProjectedBodyLinks(body: string, prefix: string): string {
+    return body
+        .replace(BODY_DOCS_RE, (_m, t: string) => prefix + t.replace(/^docs\/guidelines\//, 'guidelines/'))
+        .replace(BODY_SRC_FLAT_RE, (_m, t: string) => prefix + t)
+        .replace(BODY_SRC_AGENT_RE, (_m, t: string) => prefix + t);
+}
+
+/**
+ * `docs/guidelines/` is projected and loses its `docs/` segment;
+ * `docs/contracts/` is NOT projected and keeps its path unchanged.
+ *
+ * One-or-more `../` rather than a literal `../../`: the dominant convention in
+ * `src/rules/` is a single `../` — 26 sites across 18 rules — so a literal
+ * two-level pattern matched only the minority spelling.
+ */
+const BODY_DOCS_RE = /(?:\.\.\/)+(docs\/(?:guidelines|contracts)\/[^)\s]+\.md)/g;
+
+/**
+ * Source trees that project into `dist/agent-src/`, losing their `src/` (and
+ * `agent-src/`) segment.
+ *
+ * Until the guidelines lane shipped, no PROJECTED file linked into `src/`, so
+ * this rewrite had nothing to do and did not exist. A guideline does it 209
+ * times — a blind review measured 253 of 268 links under
+ * `dist/agent-src/guidelines/` resolving to nothing before this was added.
+ *
+ * TWO patterns, not one, and the difference is load-bearing. `rules` and
+ * `skills` are FLAT library roots directly under `src/`; `commands`,
+ * `contexts`, `personas`, `user-types`, `templates` and `scripts` exist only
+ * under `src/agent-src/`. A single pattern with an optional `agent-src/` group
+ * conflates them, and the conflation is not theoretical: it folded
+ * `../../src/scripts/media/lib/adapter-contract.md` — a real link in
+ * `provider-lifecycle-discipline.md` — onto `../scripts/…`, which resolves to
+ * `dist/agent-src/scripts/`, a projection of `src/agent-src/scripts/` and a
+ * different tree entirely. `check_condensed_paths` caught it; the first version
+ * of this regex turned one resolving link into a broken one.
+ *
+ * `src/domains` is deliberately absent from both: a domains command projects to
+ * `commands/<subpath>.md`, which is a re-shaping rather than a prefix strip,
+ * and guessing it would produce a link that looks right and is wrong.
+ */
+const BODY_SRC_FLAT_RE = /(?:\.\.\/)+src\/((?:rules|skills)\/[^)\s]+\.md)/g;
+const BODY_SRC_AGENT_RE =
+    /(?:\.\.\/)+src\/agent-src\/((?:commands|contexts|personas|user-types|templates|scripts)\/[^)\s]+\.md)/g;

package/src/scripts/_lib/installed_lock.ts

@@ -200,7 +200,7 @@ function splitlines(text: string): string[] {
   return parts;
 }
 
-function _render(
+export function _render(
   version: string,
   tools: string[],
   installed_at: string,