@event4u/agent-config 9.22.0 → 9.24.0

package/src/scripts/lint_token_budget_discipline.ts

@@ -10,6 +10,27 @@
  * 2. JUSTIFICATION — every `rich`-tagged skill carries a
  *    `## Why this skill is rich` section explaining the irreducible
  *    complexity.
+ * 3. SIZE — a `rich`-tagged skill stays under the declared ceiling
+ *    (3,500 tokens, ADR-217). Measured with the exact BPE tokenizer
+ *    where `js-tiktoken` resolves and with the character proxy where it does
+ *    not; the gate says which. A proxy measurement sitting within its own
+ *    error margin of the ceiling is reported UNRESOLVED rather than silently
+ *    classified — the proxy runs ~5 % off per file IN EITHER DIRECTION, and a
+ *    reading whose error band straddles the ceiling has not decided anything.
+ *
+ * The band was documentation until ADR-217: the ceiling described no artifact
+ * that existed (measured max 3,331 of a declared 5,000), so nothing ever
+ * noticed that its top half was unused. An unused permission costs nothing
+ * until someone uses it.
+ *
+ * The band's FLOOR is documented and deliberately NOT gated. Running the check
+ * once found `accessibility-auditor` at 1,931 tokens — under the 2,000 floor
+ * while legitimately holding the class, because `rich` buys exemption from
+ * condensation and that is a claim about what compression would LOSE, not
+ * about how large the file is. The published measurement supplies a
+ * degradation threshold, which is a ceiling; nothing measures a minimum. A
+ * floor gate would have forced a WCAG-criteria skill out of the exemption on a
+ * number with no evidence behind it.
  *
  * Additionally, any `token_budget_class` value outside
  * `lean | standard | rich` is a finding (schema drift).
@@ -20,6 +41,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { gpt_tokens } from './_lib/token_count.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -32,6 +55,17 @@ export const VALID_CLASSES = ['lean', 'standard', 'rich'] as const;
 
 export const RICH_SECTION_HEADING = '## Why this skill is rich';
 
+/** Declared band for the rich class (ADR-217). Floor unchanged; ceiling 5,000 → 3,500. */
+export const RICH_MIN_TOKENS = 2000;
+export const RICH_MAX_TOKENS = 3500;
+
+/**
+ * Worst-case per-file error of the character proxy, measured over the four
+ * rich artifacts on 2026-08-06 (−5.3 % on the largest). A proxy measurement
+ * inside this margin of a boundary is not a verdict.
+ */
+export const PROXY_ERROR_MARGIN = 0.06;
+
 export interface Finding {
     /** repo-relative path */
     file: string;
@@ -44,6 +78,45 @@ export interface ScanResult {
     scanned: number;
     /** Skills declaring token_budget_class: rich. */
     richCount: number;
+    /** Per-rich-skill size measurements, for the report line. */
+    sizes: RichSize[];
+    /** True when every size came from the exact BPE tokenizer. */
+    exactThroughout: boolean;
+}
+
+export interface RichSize {
+    file: string;
+    tokens: number;
+    exact: boolean;
+    /** Set when a proxy measurement lands inside its own error margin of a boundary. */
+    unresolved: boolean;
+}
+
+/**
+ * Measure one artifact, exact where the tokenizer resolved.
+ *
+ * Split out so the size rule is testable without a filesystem: the boundary
+ * cases that matter (exactly at the cap, one token over, a proxy reading a
+ * hair under) are the ones a fixture tree makes awkward and a function call
+ * makes trivial.
+ */
+export function classify_size(tokens: number, exact: boolean): { over: boolean; unresolved: boolean } {
+    if (exact) {
+        return { over: tokens > RICH_MAX_TOKENS, unresolved: false };
+    }
+    // A proxy reading is a band around the truth, and the band is SYMMETRIC.
+    // The first version applied the margin upward only — guarding a proxy that
+    // reads low — while the measured error on the largest artifact runs the
+    // other way: 3,518 by proxy against 3,331 exact, reading 5.3 % HIGH. That
+    // version therefore hard-failed the one artifact ADR-217 rules in-band,
+    // on any machine without the tokenizer (`js-tiktoken` is a devDependency).
+    //
+    // So: a proxy verdict counts only when the WHOLE band falls on one side of
+    // the ceiling. A band straddling it is `unresolved` — which is a finding,
+    // but one that says "measure properly" rather than "this is too big".
+    const margin = Math.ceil(tokens * PROXY_ERROR_MARGIN);
+    const straddles = tokens - margin <= RICH_MAX_TOKENS && tokens + margin > RICH_MAX_TOKENS;
+    return { over: !straddles && tokens - margin > RICH_MAX_TOKENS, unresolved: straddles };
 }
 
 /** `token_budget_class` value from a SKILL.md's YAML frontmatter, or null. */
@@ -63,6 +136,7 @@ export function frontmatter_class(content: string): string | null {
 /** Scan one skills root (directory of `<skill>/SKILL.md`). */
 export function scan_skills(skillsRoot: string): ScanResult {
     const findings: Finding[] = [];
+    const sizes: RichSize[] = [];
     let scanned = 0;
     let richCount = 0;
     const entries = fs
@@ -97,6 +171,28 @@ export function scan_skills(skillsRoot: string): ScanResult {
                     message: `rich-tagged skill missing the '${RICH_SECTION_HEADING}' justification section`,
                 });
             }
+            const measured = gpt_tokens(content);
+            const verdict = classify_size(measured.tokens, measured.exact);
+            sizes.push({ file: rel, tokens: measured.tokens, exact: measured.exact, unresolved: verdict.unresolved });
+            const how = measured.exact ? 'exact BPE' : 'chars/4 proxy';
+            if (verdict.over) {
+                findings.push({
+                    file: rel,
+                    message:
+                        `rich-class size band exceeded: ${String(measured.tokens)} tokens (${how}) > ` +
+                        `${String(RICH_MAX_TOKENS)} (ADR-217). Split by responsibility, or argue the ` +
+                        'ceiling in a decision record — not in this file.',
+                });
+            } else if (verdict.unresolved) {
+                findings.push({
+                    file: rel,
+                    message:
+                        `rich-class size UNRESOLVED: ${String(measured.tokens)} tokens (${how}) sits within the ` +
+                        `${String(PROXY_ERROR_MARGIN * 100)} % proxy margin of a band boundary. Install the exact ` +
+                        'tokenizer (js-tiktoken is a declared dependency) and re-run — a proxy reading this ' +
+                        'close has not decided anything.',
+                });
+            }
         }
     }
     if (scanned > 0 && richCount > scanned * RICH_RATIO_CAP) {
@@ -108,7 +204,7 @@ export function scan_skills(skillsRoot: string): ScanResult {
                 `max ${String(Math.floor(scanned * RICH_RATIO_CAP))})`,
         });
     }
-    return { findings, scanned, richCount };
+    return { findings, scanned, richCount, sizes, exactThroughout: sizes.every((s) => s.exact) };
 }
 
 export function main(argv?: readonly string[]): number {
@@ -134,9 +230,21 @@ export function main(argv?: readonly string[]): number {
         process.stdout.write(`❌  ${f.file}  ${f.message}\n`);
     }
     if (result.findings.length === 0 && !quiet) {
+        const how = result.exactThroughout ? 'exact BPE' : 'chars/4 proxy (js-tiktoken did not resolve)';
+        const largest = result.sizes.reduce((max, s) => (s.tokens > max ? s.tokens : max), 0);
         process.stdout.write(
             `✅  token-budget discipline: ${String(result.richCount)} rich of ${String(result.scanned)} skills within the ${String(RICH_RATIO_CAP * 100)} % cap; every rich skill justifies itself\n`,
         );
+        // Publish the sizes on the GREEN path too. A band nobody sees the
+        // numbers for is how this one spent months describing no artifact
+        // that existed.
+        process.stdout.write(
+            `    size ceiling ${String(RICH_MAX_TOKENS)} (ADR-217; the ${String(RICH_MIN_TOKENS)} floor is documented, not gated), ` +
+                `measured ${how}; largest ${String(largest)}\n`,
+        );
+        for (const s of result.sizes) {
+            process.stdout.write(`    ${String(s.tokens).padStart(5)}  ${s.file}\n`);
+        }
     }
     // gate-coverage contract (src/config/gate-coverage.yml): files inspected.
     process.stdout.write(`scanned: ${String(result.scanned)}\n`);

package/src/scripts/measure_rule_absoluta.ts

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * Measure how many rules carry an imperative ABSOLUTE, and which terms.
+ *
+ * WHY THIS EXISTS. `road-to-rule-coherence` was designed around the figure
+ * "17 rules carry competing absolutes". A scratch census during that roadmap
+ * refuted it and reported 97 of 111 — and that refutation is what killed the
+ * precedence lattice and the coverage ratchet: a governance mechanism over 17
+ * outliers is proportionate, the same mechanism over ~90% of the corpus is
+ * declaration debt across almost all of it.
+ *
+ * But the 97 came from a throwaway script in a scratch directory, so it was an
+ * unverified number replacing an unverified number — the exact failure class it
+ * had just exposed. Re-deriving it here shows BOTH prior figures were lexicon
+ * artifacts:
+ *
+ *   strict (ALL-CAPS imperatives only)        79 / 111  (71.2%)
+ *   same lexicon, case-insensitive            97 / 111  (87.4%)  <- the prior 97
+ *   carries an Iron Law block (structural)    94 / 111  (84.7%)
+ *
+ * The 97 is reproducible — it is the case-insensitive reading, which counts
+ * lowercase "must"/"never" in explanatory prose as mandates. The strict reading
+ * is the better proxy for an imperative, but it has false negatives of its own:
+ * `downstream-changes` carries a full Iron Law block ("EVERY EDIT IS INCOMPLETE
+ * ... IS A CRITICAL FAILURE") using none of the lexicon terms, and scores 0.
+ *
+ * So no single number is defensible, and the third row is why that does not
+ * matter: the structural count needs no lexicon at all, and all three readings
+ * land at 71-87%. The conclusion the roadmap actually rests on — absolutes are
+ * the house style, not 17 outliers — is invariant to the method. Cite the range
+ * and the structural figure; do not cite a point estimate.
+ *
+ * NOT A GATE, deliberately. The `measure_` prefix keeps it out of
+ * `_lib/gate_population`'s gate set, and it emits no `scanned:` contract line,
+ * so it carries no `gate-coverage.yml` registration duty. There is nothing here
+ * to enforce: "how many rules speak in absolutes" is a property of the house
+ * writing style, not a defect with a threshold. Adding a threshold would
+ * recreate the ratchet the measurement itself argued against.
+ *
+ * Frontmatter is excluded — `description:` routinely contains trigger words
+ * that are not imperatives addressed to the agent.
+ *
+ * Output: default table, `--json` for the deterministic record.
+ *
+ * SCOPE: this is a CLOSED decision input, not ongoing instrumentation — see
+ * docs/decisions/ADR-218-absoluta-census-is-a-closed-decision-input.md. Nothing
+ * consumes the number; it exists so the figures in that record can be
+ * re-derived instead of cited from a commit message. A future "did this PR
+ * introduce a new absolute?" check is a DIFFERENT tool that watches diffs.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { SRC_RULES } from './_lib/agent_src.js';
+
+/**
+ * The lexicon IS the measurement — enumerated here rather than described, so a
+ * re-run reproduces the number exactly and a disagreement about the number is a
+ * disagreement about this list.
+ *
+ * Case-sensitive where the term is an ALL-CAPS imperative (`NEVER`, `ALWAYS`,
+ * `STOP`, `MUST`, `FORBIDDEN`): lowercase "never" appears in ordinary prose
+ * ("never mind that") and is not a mandate. Case-insensitive where the phrase
+ * is a mandate in any casing (`non-bypassable`, `Hard Floor`, `no exceptions`)
+ * or a verb stem (`refuse`, `abort`).
+ */
+export const ABSOLUTA_LEXICON: ReadonlyArray<{
+    term: string;
+    pattern: RegExp;
+    note: string;
+}> = [
+    { term: 'NEVER', pattern: /\bNEVER\b/g, note: 'ALL-CAPS only — lowercase "never" is ordinary prose' },
+    { term: 'ALWAYS', pattern: /\bALWAYS\b/g, note: 'ALL-CAPS only' },
+    { term: 'STOP', pattern: /\bSTOP\b/g, note: 'ALL-CAPS only' },
+    { term: 'MUST', pattern: /\bMUST\b/g, note: 'ALL-CAPS only — lowercase "must" is common in explanatory prose' },
+    { term: 'FORBIDDEN', pattern: /\bFORBIDDEN\b/g, note: 'ALL-CAPS only' },
+    { term: 'non-bypassable', pattern: /non-bypassable/gi, note: 'any casing — always a mandate' },
+    { term: 'Hard Floor', pattern: /hard floor/gi, note: 'any casing — names the supremacy tier' },
+    { term: 'no exceptions', pattern: /no exceptions/gi, note: 'any casing' },
+    { term: 'refuse', pattern: /\brefuses?\b|\brefusal\b/gi, note: 'verb stem, any casing' },
+    { term: 'abort', pattern: /\baborts?\b/gi, note: 'verb stem, any casing' },
+];
+
+export interface RuleAbsoluta {
+    rule: string;
+    total: number;
+    perTerm: Record<string, number>;
+    /** True when the file has a body but no absolute — the pointer-stub class. */
+    stub: boolean;
+}
+
+export interface AbsolutaCensus {
+    rules_scanned: number;
+    rules_with_absolute: number;
+    rules_without_absolute: number;
+    share_with_absolute: number;
+    occurrences_total: number;
+    per_term: Record<string, { occurrences: number; rules: number }>;
+    without_absolute: string[];
+    per_rule: RuleAbsoluta[];
+    /** Case-insensitive reading of the same lexicon — the upper bound. */
+    rules_with_absolute_loose: number;
+    /**
+     * Structural, lexicon-independent signal: rules carrying an `Iron Law`
+     * heading or a `**Iron Law` marker. This is the number that does NOT move
+     * when the lexicon is argued about, which is why it is reported alongside.
+     */
+    rules_with_iron_law: number;
+}
+
+/** `## Iron Law`, `### Iron Laws`, `**Iron Law.**`, `Iron Law 1`, … */
+const IRON_LAW_MARKER = /^#{1,6}\s+.*Iron Law|^\*\*Iron Law/im;
+
+/** Strip YAML frontmatter; return the body only. */
+export function stripFrontmatter(text: string): string {
+    if (!text.startsWith('---\n')) return text;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return text;
+    return text.slice(end + '\n---\n'.length);
+}
+
+export function censusAbsoluta(rulesDir: string): AbsolutaCensus {
+    const files = fs
+        .readdirSync(rulesDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+
+    const perRule: RuleAbsoluta[] = [];
+    const perTerm: Record<string, { occurrences: number; rules: number }> = {};
+    for (const { term } of ABSOLUTA_LEXICON) perTerm[term] = { occurrences: 0, rules: 0 };
+
+    let occurrences = 0;
+    let looseHits = 0;
+    let ironLawHits = 0;
+    for (const file of files) {
+        const body = stripFrontmatter(fs.readFileSync(path.join(rulesDir, file), 'utf-8'));
+        const counts: Record<string, number> = {};
+        let total = 0;
+        let looseTotal = 0;
+        for (const { term, pattern } of ABSOLUTA_LEXICON) {
+            // Fresh regex per file: /g patterns carry lastIndex across calls.
+            const n = (body.match(new RegExp(pattern.source, pattern.flags)) ?? []).length;
+            counts[term] = n;
+            total += n;
+            if (n > 0) {
+                perTerm[term]!.occurrences += n;
+                perTerm[term]!.rules += 1;
+            }
+            // Loose reading: same lexicon, case-insensitive throughout. This is
+            // the upper bound, and it is the reading a prior scratch census
+            // used — reproducing it here is what identifies that method.
+            looseTotal += (body.match(new RegExp(pattern.source, 'gi')) ?? []).length;
+        }
+        occurrences += total;
+        if (looseTotal > 0) looseHits += 1;
+        if (IRON_LAW_MARKER.test(body)) ironLawHits += 1;
+        perRule.push({ rule: path.basename(file, '.md'), total, perTerm: counts, stub: total === 0 });
+    }
+
+    const withAbs = perRule.filter((r) => r.total > 0).length;
+    return {
+        rules_scanned: perRule.length,
+        rules_with_absolute: withAbs,
+        rules_without_absolute: perRule.length - withAbs,
+        share_with_absolute: perRule.length === 0 ? 0 : Number((withAbs / perRule.length).toFixed(4)),
+        occurrences_total: occurrences,
+        per_term: perTerm,
+        without_absolute: perRule.filter((r) => r.stub).map((r) => r.rule),
+        per_rule: perRule,
+        rules_with_absolute_loose: looseHits,
+        rules_with_iron_law: ironLawHits,
+    };
+}
+
+function render(c: AbsolutaCensus): string {
+    const lines: string[] = [];
+    lines.push('Rule absoluta census');
+    lines.push('');
+    lines.push(
+        `  rules scanned          ${c.rules_scanned}`,
+    );
+    lines.push(
+        `  carry >=1 absolute     ${c.rules_with_absolute}  (${(c.share_with_absolute * 100).toFixed(1)}%)`,
+    );
+    lines.push(`  carry none             ${c.rules_without_absolute}`);
+    lines.push(
+        `  same lexicon, loose    ${c.rules_with_absolute_loose}  (${((c.rules_with_absolute_loose / c.rules_scanned) * 100).toFixed(1)}%)  <- case-insensitive upper bound`,
+    );
+    lines.push(
+        `  carry an Iron Law      ${c.rules_with_iron_law}  (${((c.rules_with_iron_law / c.rules_scanned) * 100).toFixed(1)}%)  <- structural, lexicon-free`,
+    );
+    lines.push(`  total occurrences      ${c.occurrences_total}  (strict)`);
+    lines.push('');
+    lines.push('  per term (occurrences / rules):');
+    for (const { term } of ABSOLUTA_LEXICON) {
+        const e = c.per_term[term]!;
+        lines.push(`    ${term.padEnd(16)} ${String(e.occurrences).padStart(4)} / ${e.rules}`);
+    }
+    if (c.without_absolute.length > 0) {
+        lines.push('');
+        lines.push('  rules with NO absolute (expected: migrated pointer stubs):');
+        for (const r of c.without_absolute) lines.push(`    ${r}`);
+    }
+    return lines.join('\n');
+}
+
+export function main(argv: string[]): number {
+    const json = argv.includes('--json');
+    const dir = SRC_RULES();
+    if (!fs.existsSync(dir)) {
+        process.stderr.write(`measure_rule_absoluta: rules dir missing: ${dir}\n`);
+        return 1;
+    }
+    const c = censusAbsoluta(dir);
+    if (c.rules_scanned === 0) {
+        // A census over zero files would print a confident 0% — the
+        // scan-nothing-and-look-green shape this repo has been burned by.
+        process.stderr.write(`measure_rule_absoluta: scanned 0 rules under ${dir}\n`);
+        return 1;
+    }
+    process.stdout.write((json ? JSON.stringify(c, null, 2) : render(c)) + '\n');
+    return 0;
+}
+
+/* c8 ignore start */
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exitCode = main(process.argv.slice(2));
+}
+/* c8 ignore stop */

package/src/scripts/report_imperative_density.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env tsx
+/**
+ * report_imperative_density.ts — an advisory number whose direction is unknown.
+ *
+ * Prints the ratio of imperative-marker lines to prose lines across the
+ * authored rules and skills. **It gates on nothing, and it must not acquire a
+ * threshold without the measurement that would justify one.**
+ *
+ * WHY THIS IS NOT A GATE, AND MUST NOT BECOME ONE
+ * -----------------------------------------------
+ * Three external sources disagree about which direction is better. One asserts
+ * reasoning-based phrasing outperforms rigid directives. One ships a metric
+ * that scores instruction files HIGHER for imperative-marker density — the
+ * opposite ranking from the same observation. A third sits between them and
+ * supplies the only part all three can live with: a rule the agent consistently
+ * fails to follow needs structural enforcement or deletion, not a louder rule.
+ *
+ * This suite's house style sits at the imperative end and has no measurement
+ * either way. A gate would prejudge exactly the question the sweep left open
+ * (`skill-ecosystem-sweep-2026-08.md` § R2). An advisory number is the input a
+ * future decision needs; a target is the thing that would corrupt it, because
+ * the moment a number is optimised it stops measuring what it measured.
+ *
+ * So: no exit-2, no baseline entry, no `gate-coverage.yml` row, and the header
+ * of every run says the direction is unsettled. Read it as a description, not
+ * as a score.
+ *
+ * Exit: 0 always (except a usage/IO error, which is 1). That is deliberate.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+export const RULES_ROOT = 'src/rules';
+export const SKILLS_ROOT = 'src/skills';
+
+/**
+ * Lines counted as imperative markers.
+ *
+ * Deliberately narrow and stated: an all-caps directive line, a bullet opening
+ * with a modal or a bare imperative verb, and the fenced Iron-Law blocks this
+ * suite uses. A broader net would inflate the number without making it mean
+ * more, and the number's meaning is already the open question.
+ */
+const IMPERATIVE_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['all-caps directive', /^[^a-z]*\b(NEVER|ALWAYS|MUST|DO NOT|STOP|REFUSE|FORBIDDEN)\b[^a-z]*$/],
+    ['inline modal', /\b(MUST|NEVER|ALWAYS|DO NOT|SHALL)\b/],
+    ['imperative bullet', /^\s*[-*]\s+(Always|Never|Do not|Don't|Use|Run|Check|Verify|Refuse|Stop|Add|Remove|Keep|Prefer|Avoid)\b/],
+];
+
+export interface FileDensity {
+    file: string;
+    prose: number;
+    imperative: number;
+    ratio: number;
+}
+
+export interface DensityReport {
+    files: FileDensity[];
+    totalProse: number;
+    totalImperative: number;
+    /** Ratio over the whole corpus, or null when nothing was counted. */
+    ratio: number | null;
+}
+
+/**
+ * Lines that carry prose. Fenced code, frontmatter, table rows, and blanks are
+ * excluded — counting them would make the ratio a function of how much YAML a
+ * file happens to carry.
+ */
+export function proseLines(text: string): string[] {
+    const lines = text.split('\n');
+
+    // Frontmatter only when the opening `---` actually CLOSES. A file whose
+    // first line is a horizontal rule used to swallow everything to the next
+    // `---`, and a file with an unterminated opener swallowed all of it.
+    let start = 0;
+    if (lines[0]?.trim() === '---') {
+        const close = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+        // …and only when the block LOOKS like YAML. `---` opening a document
+        // that then reads as prose is a horizontal rule, and treating it as
+        // frontmatter silently ate everything up to the next one.
+        const looksYaml = close > 0 && lines.slice(1, close).some((l) => /^\s*[\w.-]+:\s/.test(l));
+        if (close !== -1 && looksYaml) start = close + 1;
+    }
+
+    // Fences are matched BY CHARACTER, so `~~~` cannot close a ```-opened
+    // block, and an opener that never closes is treated as though it never
+    // opened — dropping the rest of a file silently is worse than counting a
+    // few code lines as prose, because the denominator is the thing this
+    // report publishes.
+    const openers: Array<{ index: number; marker: string }> = [];
+    const fenced = new Set<number>();
+    let open: { index: number; marker: string } | null = null;
+    for (let i = start; i < lines.length; i++) {
+        const m = /^\s*(`{3,}|~{3,})/.exec(lines[i] ?? '');
+        if (m === null) continue;
+        const marker = (m[1] as string)[0] as string;
+        if (open === null) {
+            open = { index: i, marker };
+            openers.push(open);
+        } else if (open.marker === marker) {
+            for (let j = open.index; j <= i; j++) fenced.add(j);
+            open = null;
+        }
+    }
+
+    const out: string[] = [];
+    for (let i = start; i < lines.length; i++) {
+        if (fenced.has(i)) continue;
+        const line = (lines[i] ?? '').trimEnd();
+        if (line.trim() === '') continue;
+        if (/^\s*\|/.test(line)) continue;
+        out.push(line);
+    }
+    return out;
+}
+
+export function countImperative(lines: readonly string[]): number {
+    let n = 0;
+    for (const line of lines) {
+        if (IMPERATIVE_PATTERNS.some(([, re]) => re.test(line))) n += 1;
+    }
+    return n;
+}
+
+function _walkMarkdown(dir: string): string[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const out: string[] = [];
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) out.push(..._walkMarkdown(full));
+        else if (e.name.endsWith('.md')) out.push(full);
+    }
+    return out.sort();
+}
+
+export function buildReport(root: string): DensityReport {
+    const files: FileDensity[] = [];
+    let totalProse = 0;
+    let totalImperative = 0;
+    for (const dir of [RULES_ROOT, SKILLS_ROOT]) {
+        for (const abs of _walkMarkdown(path.join(root, dir))) {
+            const lines = proseLines(fs.readFileSync(abs, 'utf-8'));
+            if (lines.length === 0) continue;
+            const imperative = countImperative(lines);
+            totalProse += lines.length;
+            totalImperative += imperative;
+            files.push({
+                file: path.relative(root, abs).split(path.sep).join('/'),
+                prose: lines.length,
+                imperative,
+                ratio: imperative / lines.length,
+            });
+        }
+    }
+    return {
+        files,
+        totalProse,
+        totalImperative,
+        ratio: totalProse === 0 ? null : totalImperative / totalProse,
+    };
+}
+
+const HEADER = [
+    'imperative-density report — ADVISORY, and the direction of this number is UNSETTLED.',
+    '',
+    'Three sources disagree on whether higher is better. One prefers reasoning-based',
+    'phrasing; one scores instruction files higher for imperative density; the third',
+    'declines the question and supplies the operational fork instead. This suite has',
+    'no measurement either way — see skill-ecosystem-sweep-2026-08.md § R2.',
+    '',
+    'Do not read this as a score, and do not optimise it. It gates nothing on purpose:',
+    'a threshold here would prejudge the open question, and a number that gets',
+    'optimised stops measuring what it measured.',
+].join('\n');
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const top = argv.includes('--top') ? Number.parseInt(argv[argv.indexOf('--top') + 1] ?? '10', 10) : 10;
+    const json = argv.includes('--json');
+
+    const report = buildReport(REPO_ROOT);
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ note: 'advisory; direction unsettled (§ R2)', ...report }, null, 2)}\n`);
+        return 0;
+    }
+
+    process.stdout.write(`${HEADER}\n\n`);
+    if (report.ratio === null) {
+        // `renderShare`'s rule, applied by hand: an empty denominator renders as
+        // "not measured", never as 0.0 %.
+        process.stdout.write('corpus ratio: not measured — zero prose lines found under the scanned roots\n');
+        process.stdout.write(`files: ${String(report.files.length)}\n`);
+        return 0;
+    }
+    process.stdout.write(
+        `corpus ratio: ${(report.ratio * 100).toFixed(1)} % ` +
+            `(${String(report.totalImperative)} imperative lines of ${String(report.totalProse)} prose lines, ` +
+            `${String(report.files.length)} files)\n\n`,
+    );
+    const ranked = [...report.files].sort((a, b) => b.ratio - a.ratio).slice(0, top);
+    process.stdout.write(`densest ${String(ranked.length)}:\n`);
+    for (const f of ranked) {
+        process.stdout.write(
+            `  ${(f.ratio * 100).toFixed(1).padStart(5)} %  ${String(f.imperative).padStart(4)}/${String(f.prose).padEnd(5)}  ${f.file}\n`,
+        );
+    }
+    // `files:` and not `scanned:` on purpose. The latter is the machine-read
+    // coverage signal `check_gate_coverage` parses, and emitting it would
+    // enlist an advisory report as a gate with a coverage floor — the exact
+    // promotion this report must not undergo.
+    process.stdout.write(`\nfiles: ${String(report.files.length)}\n`);
+    return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main());
+}
+
+export { REPO_ROOT };

package/src/scripts/verify_physical_move.ts

@@ -179,7 +179,16 @@ export function _diff_tree(
 
 export function _diff_manifest(before: Obj | null, after: Obj | null): string[] {
     if (before === null && after === null) {
-        return [];
+        // Equality without validity — the literal `diff a b` where NEITHER side
+        // exists and the answer comes back "equal". An empty issue list means
+        // clean to every caller, so both-absent used to certify a move that was
+        // never compared. Two absent sides are the absence of a comparison, not
+        // the presence of a match. (Audited estate-wide in
+        // `docs/guidelines/agent-infra/false-green.md § The audited sync/parity gates`.)
+        return [
+            '  manifest: BOTH the pre-move snapshot and the post-move manifest are missing — ' +
+                'nothing was compared, so nothing is verified',
+        ];
     }
     if (before === null) {
         return ['  manifest: pre-move snapshot missing'];