@event4u/agent-config 14.12.0 → 14.13.0

package/dist/agent-src/scripts/stubs_due.ts

@@ -0,0 +1,400 @@
+#!/usr/bin/env node
+/**
+ * Read-only query: which roadmap stubs are overdue for a read, and which
+ * decisions are sitting on the owner.
+ *
+ * WHY THIS EXISTS, AND WHY IT LANDS BEFORE THE DATES DO.
+ * `agents/roadmaps/stubs/` holds 77 files that are, by construction, not active
+ * work — the directory listing IS the inventory (the index tables were deleted
+ * on 2026-08-21 and `check_no_stub_inventory_table` keeps them deleted). Giving
+ * each stub a `review_by:` date without giving anyone a way to READ those dates
+ * would be strictly worse than adding nothing: the repository would carry a
+ * field certifying attention it does not pay, and a stale date reads as
+ * evidence. An AI council (2026-08-26, 2/2) made the ordering a rule — the
+ * reader lands first, the backfill second. This is the reader.
+ *
+ * WHAT IT IS NOT. It is not a gate: it always exits 0, because "three stubs are
+ * overdue" is a state of the world, not a defect in a diff. It is not an
+ * inventory table: it prints to stdout on demand and writes nothing, least of
+ * all into `agents/roadmaps/stubs/`, so the guard that deleted the tables stays
+ * green and un-weakened. `agent-config roadmap:progress` consumes only its two
+ * COUNTS for the dashboard header — two integers, no rows, nothing to grow an
+ * index back from.
+ *
+ * THE TWO SHAPES HAVE DIFFERENT CLOCKS, and the cadence follows the shape, not
+ * the file. A drain-run transfer is capability-gated: an environment can appear
+ * at any moment, so it is re-probed every 30 days. An org-mode stub is
+ * demand-gated: customer recruitment and audit funding move slowly, so its
+ * demand question is re-asked every 120 days. Both numbers, and the reason 120
+ * was taken over 180, are recorded in `agents/roadmaps/stubs/README.md`
+ * § Frontmatter contract.
+ *
+ * OWNER DECISIONS are counted from two deterministic markers, because "the text
+ * routes a decision to the owner" needs to be readable by a script and not only
+ * by a person: an `## Unresolved decision` heading, and an open `### blocker:`
+ * whose owner is the maintainer. A stub can carry both.
+ *
+ * CLI contract: always exit 0.
+ *   ./scripts-run src/scripts/stubs_due
+ *   ./scripts-run src/scripts/stubs_due --json
+ *   ./scripts-run src/scripts/stubs_due --counts   # the two integers only
+ *   ./scripts-run src/scripts/stubs_due --today 2026-12-01   # pin "now"
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const STUB_DIR = path.join('agents', 'roadmaps', 'stubs');
+
+/** Cadence in days, per stub shape. Source of truth: the README section above. */
+export const CADENCE_DAYS = { transfer: 30, orgmode: 120 } as const;
+
+/** The marker that identifies a drain-run transfer in a stub body. */
+const TRANSFER_MARKER = 'drain-run transfer';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+
+export type StubShape = 'transfer' | 'orgmode';
+
+export interface StubRecord {
+    file: string;
+    shape: StubShape;
+    review_by: string | null;
+    reviewed_at: string | null;
+    probe_none: boolean;
+    has_probe_heading: boolean;
+    owner_decisions: number;
+    overdue: boolean;
+    days_overdue: number | null;
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/** Walk up from CWD until a dir containing `agents/roadmaps/stubs` is found. */
+export function repo_root(start?: string): string {
+    let cur = start ?? process.cwd();
+    const chain = [cur];
+    for (;;) {
+        const parent = path.dirname(cur);
+        if (parent === cur) break;
+        chain.push(parent);
+        cur = parent;
+    }
+    for (const candidate of chain) {
+        if (_isDir(path.join(candidate, STUB_DIR))) {
+            return candidate;
+        }
+    }
+    return start ?? process.cwd();
+}
+
+/**
+ * The frontmatter block, as raw lines. Returns [] when the file does not open
+ * with `---` — a stub without frontmatter simply has no fields, which the
+ * caller reports rather than crashing on.
+ */
+function _frontmatter(text: string): string[] {
+    const lines = text.split('\n');
+    if (lines[0]?.trim() !== '---') {
+        return [];
+    }
+    const out: string[] = [];
+    for (const line of lines.slice(1)) {
+        if (line.trim() === '---') {
+            return out;
+        }
+        out.push(line);
+    }
+    return [];
+}
+
+function _scalar(front: string[], key: string): string | null {
+    const prefix = `${key}:`;
+    for (const line of front) {
+        if (line.startsWith(prefix)) {
+            return line.slice(prefix.length).trim().replace(/^["']|["']$/g, '');
+        }
+    }
+    return null;
+}
+
+/**
+ * Owner-routed decisions in one stub body. Two markers, unioned:
+ *  - an `## Unresolved decision …` heading — the shape
+ *    `road-to-owner-authority-decisions.md` already uses;
+ *  - an open `### blocker:` whose Owner line names the maintainer.
+ * Counting the union rather than one of them is deliberate: a stub can carry
+ * both, and either alone would under-report.
+ */
+export function count_owner_decisions(text: string): number {
+    const lines = text.split('\n');
+    let n = 0;
+    for (const line of lines) {
+        if (/^#{2,4}\s+Unresolved decision\b/.test(line)) {
+            n += 1;
+        }
+    }
+    // Open maintainer-owned blockers. Scan each `### blocker:` section for the
+    // two field lines; a blocker missing either is not counted, because an
+    // unstated owner is not an owner decision.
+    let inBlocker = false;
+    let ownerIsMaintainer = false;
+    let statusOpen = false;
+    const flush = (): void => {
+        if (inBlocker && ownerIsMaintainer && statusOpen) {
+            n += 1;
+        }
+        inBlocker = false;
+        ownerIsMaintainer = false;
+        statusOpen = false;
+    };
+    for (const line of lines) {
+        if (/^#{2,4}\s+(blocker:|b-)/.test(line.trim()) || /^#{2,4}\s+\S+ — /.test(line)) {
+            if (/blocker:/.test(line) || /^#{2,4}\s+b-/.test(line.trim())) {
+                flush();
+                inBlocker = true;
+                continue;
+            }
+        }
+        if (!inBlocker) continue;
+        if (/^#{1,4}\s/.test(line)) {
+            flush();
+            continue;
+        }
+        if (/^-\s+\*\*Owner:\*\*\s*maintainer\b/i.test(line)) ownerIsMaintainer = true;
+        if (/^-\s+\*\*Status:\*\*\s*open\b/i.test(line)) statusOpen = true;
+    }
+    flush();
+    return n;
+}
+
+/** ISO date (UTC) N days after `from`. */
+function _addDays(from: Date, days: number): string {
+    const d = new Date(from.getTime() + days * 86_400_000);
+    return d.toISOString().slice(0, 10);
+}
+
+function _parseIso(s: string): Date | null {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(s)) return null;
+    const d = new Date(`${s}T00:00:00Z`);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Read every stub and classify it. `today` is injectable so tests are stable. */
+export function scan(root: string, today: string): StubRecord[] {
+    return scan_dir(path.join(root, STUB_DIR), today);
+}
+
+/**
+ * Same, but addressed by the stub DIRECTORY rather than the repo root.
+ * `update_roadmap_progress` already holds `agents/roadmaps` and would otherwise
+ * have to walk back up two levels to hand this function a root it would
+ * immediately re-join — a fragile round trip past exactly the directory both
+ * callers care about.
+ */
+export function scan_dir(base: string, today: string): StubRecord[] {
+    if (!_isDir(base)) return [];
+    const now = _parseIso(today);
+    const out: StubRecord[] = [];
+    let names: string[];
+    try {
+        names = fs
+            .readdirSync(base)
+            .filter((n) => n.endsWith('.md') && n !== 'README.md')
+            .sort();
+    } catch {
+        return [];
+    }
+    for (const name of names) {
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(base, name), 'utf8');
+        } catch {
+            continue;
+        }
+        const front = _frontmatter(text);
+        const review_by = _scalar(front, 'review_by');
+        const reviewed_at = _scalar(front, 'reviewed_at');
+        const probeVal = _scalar(front, 'probe');
+        const shape: StubShape = text.includes(TRANSFER_MARKER) ? 'transfer' : 'orgmode';
+        let overdue = false;
+        let days_overdue: number | null = null;
+        if (review_by !== null && now !== null) {
+            const due = _parseIso(review_by);
+            if (due !== null && due.getTime() < now.getTime()) {
+                overdue = true;
+                days_overdue = Math.round((now.getTime() - due.getTime()) / 86_400_000);
+            }
+        }
+        out.push({
+            file: `${STUB_DIR}/${name}`,
+            shape,
+            review_by,
+            reviewed_at,
+            probe_none: probeVal === 'none',
+            has_probe_heading: /^#{1,4} *(Probe|Promotion)/m.test(text),
+            owner_decisions: count_owner_decisions(text),
+            overdue,
+            days_overdue,
+        });
+    }
+    return out;
+}
+
+export interface Counts {
+    overdue: number;
+    owner_decisions: number;
+    missing_review_by: number;
+    total: number;
+}
+
+export function counts(records: StubRecord[]): Counts {
+    return {
+        overdue: records.filter((r) => r.overdue).length,
+        owner_decisions: records.reduce((s, r) => s + r.owner_decisions, 0),
+        missing_review_by: records.filter((r) => r.review_by === null).length,
+        total: records.length,
+    };
+}
+
+/** Suggested `review_by:` for a stub of this shape, dated from `from`. */
+export function due_date(shape: StubShape, from: string): string {
+    const d = _parseIso(from) ?? new Date();
+    return _addDays(d, CADENCE_DAYS[shape]);
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const asJson = argv.includes('--json');
+    const countsOnly = argv.includes('--counts');
+    const todayIdx = argv.indexOf('--today');
+    const today =
+        todayIdx >= 0 && argv[todayIdx + 1] !== undefined
+            ? (argv[todayIdx + 1] as string)
+            : new Date().toISOString().slice(0, 10);
+
+    const root = repo_root();
+    const records = scan(root, today);
+    const c = counts(records);
+
+    if (countsOnly) {
+        process.stdout.write(`${c.overdue} ${c.owner_decisions}\n`);
+        return 0;
+    }
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ today, counts: c, stubs: records }, null, 2)}\n`);
+        return 0;
+    }
+
+    process.stdout.write(`stubs:due · ${today} · ${c.total} stub(s) under ${STUB_DIR}/\n\n`);
+
+    const overdue = records.filter((r) => r.overdue).sort((a, b) => (b.days_overdue ?? 0) - (a.days_overdue ?? 0));
+    if (overdue.length === 0) {
+        process.stdout.write('  ✅  no stub is past its review date.\n');
+    } else {
+        process.stdout.write(`  ⚠️   ${overdue.length} overdue:\n`);
+        for (const r of overdue) {
+            process.stdout.write(
+                `      ${r.file}  (${r.shape}, due ${r.review_by}, ${r.days_overdue}d late)\n`,
+            );
+        }
+    }
+
+    if (c.missing_review_by > 0) {
+        process.stdout.write(
+            `\n  ⚠️   ${c.missing_review_by} stub(s) carry no \`review_by:\` — see ` +
+                `${STUB_DIR}/README.md § Frontmatter contract:\n`,
+        );
+        for (const r of records.filter((x) => x.review_by === null)) {
+            process.stdout.write(
+                `      ${r.file}  (${r.shape}, suggested ${due_date(r.shape, today)})\n`,
+            );
+        }
+    }
+
+    const withDecisions = records.filter((r) => r.owner_decisions > 0);
+    process.stdout.write(`\n  ${c.owner_decisions} decision(s) routed to the owner`);
+    if (withDecisions.length === 0) {
+        process.stdout.write('.\n');
+    } else {
+        process.stdout.write(':\n');
+        for (const r of withDecisions) {
+            process.stdout.write(`      ${r.file}  (${r.owner_decisions})\n`);
+        }
+    }
+
+    const noProbe = records.filter((r) => !r.probe_none && !r.has_probe_heading);
+    if (noProbe.length > 0) {
+        process.stdout.write(
+            `\n  ⚠️   ${noProbe.length} stub(s) name no promoting probe and do not say ` +
+                '`probe: none`:\n',
+        );
+        for (const r of noProbe) {
+            process.stdout.write(`      ${r.file}\n`);
+        }
+    }
+
+    process.stdout.write('\n  Read-only. This command writes nothing.\n');
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}
+
+/**
+ * The dashboard header fragment: two integers and a pointer, or `''` when both
+ * are zero.
+ *
+ * Lives here rather than in `update_roadmap_progress` deliberately. That file
+ * sits on the wrong side of the 1,500-line source-size ratchet, so every line
+ * added to it is charged; this one is 365 lines and is charged nothing. The
+ * generator gets a one-line call, and the rule that a count is not an inventory
+ * — no row, no per-stub link, nothing for the deleted index tables to grow back
+ * from — is enforced in one place instead of two.
+ *
+ * Failure-tolerant by construction: a tree with no `agents/roadmaps/stubs/`
+ * yields `''` rather than throwing. This runs in consumer installs that carry no
+ * stub directory at all, so a throwing read here would break their dashboard.
+ */
+export function headerFragment(stubsDir: string, today?: string): string {
+    let overdue = 0;
+    let decisions = 0;
+    try {
+        const c = counts(scan_dir(stubsDir, today ?? new Date().toISOString().slice(0, 10)));
+        overdue = c.overdue;
+        decisions = c.owner_decisions;
+    } catch {
+        return '';
+    }
+    if (overdue === 0 && decisions === 0) {
+        return '';
+    }
+    return (
+        ` · **${overdue}** overdue stub${overdue !== 1 ? 's' : ''}` +
+        `, **${decisions}** owner decision${decisions !== 1 ? 's' : ''}` +
+        ' → `agent-config stubs:due`'
+    );
+}

package/dist/agent-src/scripts/ticket_bundles.ts

@@ -0,0 +1,84 @@
+/**
+ * Ticket bundles, read from `agents/tickets/_registry.yml` for the dashboard.
+ *
+ * Extracted from `update_roadmap_progress.ts` and imported back, so behaviour is
+ * unchanged. The move is mechanical: that file sits above the 1500-line ceiling
+ * `check_source_size_budget` charges, and a run that adds lines there pays for
+ * them by extraction rather than by raising a baseline.
+ */
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type * as YamlModule from 'yaml';
+
+const _require = createRequire(import.meta.url);
+
+/** Local copy: the parent keeps its own, and one tiny predicate is cheaper than
+ * an export cycle between two scripts in the same directory. */
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+export interface Bundle {
+    slug: string;
+    tickets: number;
+    status: string;
+    roadmap: string;
+}
+
+export function collect_bundles(repo_root: string): Bundle[] {
+    const reg = path.join(repo_root, 'agents', 'tickets', '_registry.yml');
+    if (!fs.existsSync(reg)) {
+        return [];
+    }
+    let YAML: typeof YamlModule;
+    try {
+        YAML = _require('yaml') as typeof YamlModule;
+    } catch {
+        return [];
+    }
+    let data: unknown;
+    try {
+        // yaml.safe_load(...) or {} — PyYAML 1.1 semantics; graceful on malformed.
+        data = YAML.parse(fs.readFileSync(reg, { encoding: 'utf-8' }), { version: '1.1' }) ?? {};
+    } catch {
+        return [];
+    }
+    const out: Bundle[] = [];
+    const bundles =
+        data && typeof data === 'object' && !Array.isArray(data)
+            ? ((data as Record<string, unknown>)['bundles'] ?? null)
+            : null;
+    const bundleMap =
+        bundles && typeof bundles === 'object' && !Array.isArray(bundles)
+            ? (bundles as Record<string, unknown>)
+            : {};
+    for (const slug of Object.keys(bundleMap).sort()) {
+        const metaRaw = bundleMap[slug];
+        const meta =
+            metaRaw && typeof metaRaw === 'object' && !Array.isArray(metaRaw)
+                ? (metaRaw as Record<string, unknown>)
+                : {};
+        const bdir = path.join(repo_root, 'agents', 'tickets', slug);
+        let n = 0;
+        if (_isDir(bdir)) {
+            try {
+                n = fs.readdirSync(bdir).filter((f) => f.startsWith('T-') && f.endsWith('.md')).length;
+            } catch {
+                n = 0;
+            }
+        }
+        out.push({
+            slug,
+            tickets: n,
+            status: (meta['status'] as string) ?? '?',
+            roadmap: (meta['source_roadmap'] as string) ?? '',
+        });
+    }
+    return out;
+}

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -71,6 +71,8 @@ import {
     type DashboardMode,
 } from './dashboard_mode.js';
 import type * as YamlModule from 'yaml';
+import { headerFragment as stubHeaderFragment } from './stubs_due.js';
+import { reportGuardedBaselines } from './guarded_baseline.js'; // third step state; contract lives there
 
 const _HERE = fileURLToPath(import.meta.url);
 const _require = createRequire(import.meta.url);
@@ -995,6 +997,8 @@ function render(roadmaps: RoadmapStats[], bundles: Bundle[] | null, roadmap_root
                   ? `, **${user_open_blockers}** need you → \`agent-config gates\``
                   : '')
             : '') +
+        // Two integers, never a row — see `stubs_due.headerFragment`.
+        stubHeaderFragment(path.join(roadmap_root, 'stubs')) +
         '\n';
     lines.push(
         // Honest provenance (road-to-roadmap-archival-robustness, gap C): name a
@@ -1362,8 +1366,8 @@ function main(argv?: readonly string[]): number {
             return 1;
         }
     }
-    const roadmaps = collect(roadmap_root);
-    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root);
+    const roadmaps = collect(roadmap_root), guarded = reportGuardedBaselines(roadmaps, repo_root);
+    const new_text = render(roadmaps, collect_bundles(repo_root), roadmap_root) + guarded.section;
     const complete = unarchived_complete(roadmaps);
     const pending = pending_iron_law_3(roadmaps);
     const gated = merge_gated_pending(roadmaps);
@@ -1395,7 +1399,7 @@ function main(argv?: readonly string[]): number {
         });
         if (r.stderr) process.stderr.write(r.stderr);
         if (r.stdout) process.stdout.write(r.stdout);
-        return r.rc;
+        return guarded.problems > 0 ? 1 : r.rc;
     }
     fs.writeFileSync(target, new_text, { encoding: 'utf-8' });
     process.stdout.write(
@@ -1431,7 +1435,7 @@ function main(argv?: readonly string[]): number {
     if (gated.length) {
         _warn_merge_gated();
     }
-    return 0;
+    return guarded.problems > 0 ? 1 : 0;
 }
 
 function _isCliEntry(): boolean {

package/dist/agent-src/skills/brand-asset-generation/SKILL.md

@@ -28,16 +28,29 @@ adapters — not a second image-gen stack.
 
 ## When to use
 
-- User asks to generate a banner, social card, header image, or CIP (corporate identity) element.
+- User asks to generate a banner, social card, header image, **platform profile
+  or cover image** (a LinkedIn cover, an X header, a YouTube channel art), or a
+  CIP (corporate identity) element.
 - Branded asset production where palette, typography, or voice must stay consistent.
 - When brand tokens are available and should drive the visual output.
 - When a brief alone (no tokens) still needs a governance-aware image output.
 
 ## Procedure
 
-1. **Identify asset type and spec** — determine format (banner, social card, CIP element),
-   output dimensions (e.g. 1200×630 for Open Graph, 1080×1080 for square social),
-   and target channel (web, print, social platform).
+1. **Identify asset type and spec** — determine format (banner, social card,
+   platform profile/cover image, CIP element), output dimensions (e.g. 1200×630
+   for Open Graph, 1080×1080 for square social), and target channel (web, print,
+   social platform).
+
+   **A platform cover is a dimension constraint, not a new asset class**, and it
+   is the one case where guessing the number is the whole failure: a cover
+   rendered at the wrong aspect ratio is cropped by the platform, so the brand
+   marks land outside the visible area and the asset is unusable rather than
+   merely off-brand. Take the required dimensions from the platform's own
+   current spec at generation time — never from memory, and never from a number
+   written here, because these change without notice. If the spec cannot be
+   established, say so and ask rather than emitting an asset that will be
+   cropped.
 2. **Inject brand tokens when present** — if `pack-brand` is installed, load `.tokens.json`
    (colors, typography, voice). Feed hex values, font names, and tone keywords directly
    into the prompt. Without tokens, derive palette and type from the brief itself;

package/dist/agent-src/skills/brand-audit/SKILL.md

@@ -35,6 +35,23 @@ Method skill. Inventories current brand expression across touchpoints and flags
 
 1. **Gather the source of truth.** Collect the consumer brand's defined tokens (palette, type scale, logo rules), voice profile, and strategy doc if they exist. Consumer brand definition is authoritative; corpus defaults are gap-fill only.
 2. **Inventory current expression per touchpoint.** Cover logo usage, colour palette, typography, voice/copy tone, imagery style, and iconography across the relevant surfaces (site, app, decks, marketing, docs).
+
+   **Personal and company profile surfaces, including LinkedIn, X, and GitHub
+   organization profiles, are deliberately excluded regardless of whether their
+   content is fetched, pasted, or supplied as a file, pending a written
+   public-profile-field privacy floor defining what may be processed.**
+
+   Recorded so the next reader does not re-derive the gap, which has already
+   happened once. The exclusion is about **handling**, not retrieval: a pasted
+   profile is mechanically a different thing from a network fetch, but the
+   missing artefact is a field-level classification saying which profile fields
+   are brand surface (logo, palette, bio messaging) and which are PII-adjacent
+   (employment history, contributor names, location). A profile's About text
+   carries both in one field. Without that classification the skill cannot
+   distinguish them, and no test can assert that it did. AI council 2/2,
+   2026-08-25. Include user-supplied profile inputs once a written, testable
+   field-level privacy floor exists; include fetched inputs only after both that
+   floor and a host-agent fetch contract exist.
 3. **UI surface.** Invoke `existing-ui-audit` for UI component inventory. Do not re-implement it here — take its output as an input to this audit.
 4. **Compare observed vs. defined.** For each touchpoint value, check it against the matching token or voice rule.
 5. **Classify each finding.** Three buckets: `on-brand` (matches the defined token), `drift` (observed value diverges from the token), `undefined` (no token exists to audit against — this is a governance gap, not automatically wrong).
@@ -42,6 +59,22 @@ Method skill. Inventories current brand expression across touchpoints and flags
 7. **Verify completeness.** Confirm every inventoried touchpoint is classified (`on-brand` / `drift` / `undefined`) — the audit is complete only when the classified count equals the inventoried count, and `existing-ui-audit` has run for every in-scope UI surface. Ensure each drift finding cites BOTH the defined value and the observed value; a finding missing either side is not yet verified.
 8. **Output the findings list** (see Output format). Do not redesign or author replacements — hand drift findings to `brand-identity` or `brand-strategy`.
 
+## Two constraints on platform-specific guidance
+
+Both are constraints on what this skill may assert, not machinery, and neither
+is a registry.
+
+- **Any platform-specific guidance carries a source tier and a review date.**
+  Platform conventions — an image aspect ratio, a character limit, where a
+  profile crops a banner — change without notice, so a number stated here
+  without a date and a source is a claim that quietly stops being true. Tier it
+  (`platform-doc` / `observed` / `inferred`) and date it, or take it from the
+  platform's own current spec at audit time instead of stating it.
+- **No engagement metric is stated as fact.** Reach, impression and
+  best-time-to-post figures are platform- and account-specific and are not
+  auditable from a brand token. Where such a figure is load-bearing to a
+  finding, attribute it; never assert it as a general truth.
+
 ## Output format
 
 1. **Source-of-truth summary** — what brand tokens, voice rules, and strategy exist and where they were found (or "none defined" if absent).

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -77,6 +77,63 @@ Every answer built with this skill MUST:
   That is the engine being honest, not broken — do not "resolve" them yourself
   by guessing.
 
+## Measured twice, and it has not won (v2, 2026-08-29)
+
+Pre-registered, published whichever way it landed:
+`internal/bench/reports/code-graph-vs-grep-inrepo-v2-2026-08-29.md`. The native
+engine scored against disciplined `git grep` over three in-repo TypeScript
+roots, 19 questions, per-class bars fixed before the run and unchanged from v1.
+
+| Class | grep R | graph R | Δ pp | grep P | graph P | verdict |
+|---|---|---|---|---|---|---|
+| `callers` | 1.000 | 1.000 | +0.0 | 0.611 | 0.667 | TIE |
+| `transitive-impact` | 0.611 | 0.500 | −11.1 | 1.000 | 0.667 | NULL |
+| `path-between` | 0.917 | **1.000** | +8.3 | 0.778 | **1.000** | TIE |
+| `references` | 1.000 | 0.333 | −66.7 | 0.833 | 0.333 | NULL |
+
+**Zero classes met the win bar.** On `path-between` the graph is exact and is the
+only class where it out-precises grep; it still ties, because the delta is +8.3 pp
+against a +10 pp bar that was fixed before the run.
+
+**The v1 run of 2026-08-28 published a false root cause, corrected 2026-08-29.**
+It reported `path-between` as `VOID` because *"both arms measured nothing"*. Only
+the grep arm did. The graph answered all three questions and v1's scorer discarded
+the answer — it compared each returned symbol against the whole probe string
+`"cmdBuild -> getParser"`. v1 also never invoked the shipped `path <a> <b>` verb,
+and counted unresolved `symbol:` pseudo-nodes as files, which is the sole reason
+its `callers` verdict was NULL with recall tied. v1's numbers are not retro-edited
+— they were faithful to v1's own registration — and v1's report now carries the
+correction. Do not quote a `path-between` delta near +89 pp: that figure comes
+from repairing the graph arm and leaving grep on the broken probe.
+
+**The rule's own wording was corrected by this result.** `external-code-graph-interop`
+used to open by saying a committed index answers "far more precisely than a fresh
+`grep`". That was never measured, and when it was, it was false for the native
+engine on this repository's own code. The rule now gives the reasons that survive
+measurement — an index that exists is already built and structured, so it is the
+cheap first question — and drops the precision claim its own benchmark refuted.
+
+**No class is graph-first.** Query the index first because an index that already
+exists is cheap to ask and its answer is structured — not because it answers
+better. When it returns nothing, that is the common case, and grep remains the
+arm to fall back to rather than a grudging afterthought.
+
+The sentence that stood here — *"the arm that won every valid class on this
+corpus"* — is withdrawn. It is the framing v1's own report forbids: that report
+says the defensible statement is *"zero classes met the pre-registered win
+criterion"*, **not** that grep proved superior. It was also false on its own
+terms under v2: grep wins two classes, ties two, and is out-precised on both
+ties.
+
+Scope, stated so this table is not over-read: it measured the **native** engine
+on **this repository's TypeScript**, with a corpus of 19 questions. It is not
+comparable to the 2026-07-28 external-corpus run, it is not comparable to v1
+either (corpus, arm-B verb set and scorer all moved), and it says nothing about a
+consumer-shipped SCIP index. Literal-string probes are reported as a separate
+`capability-boundary` class with no floor derived from them: a symbol index
+cannot answer them at all, which is where grep stays necessary rather than a
+defect in the engine.
+
 ## Do NOT
 
 - Do NOT rebuild a **fresh** consumer-shipped index — query it (interop