@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/preamble_byte_census.ts

@@ -48,6 +48,7 @@ import { censusRuleDir, type RuleDirCensus } from './_lib/carrier_divergence.js'
 import { DEFAULT_PROJECTS_ROOT, scanTranscripts } from './_lib/cc_transcript.js';
 import { censusDuplicateScope } from './_lib/duplicate_scope_census.js';
 import { computeColdStarts } from './cache_realization_report.js';
+import type { EvidenceBasis } from './_lib/evidence_basis.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -81,6 +82,72 @@ function readCharsIfExists(p: string): number {
 // scope, and this file uses both below.
 export { censusRuleDir, type RuleDirCensus };
 
+/**
+ * The user-scope rule payload, DERIVED from the projection instead of read off
+ * the developer's machine.
+ *
+ * `road-to-agent-turnaround` 4.1. `src/config/preamble-payload-budget.json`
+ * excludes the user-scope bucket as *"machine-dependent, not CI-checkable"*.
+ * That reason is falsifiable and this function falsifies it: the layer is
+ * written by this package's own installer out of `dist/agent-src/rules/`, and
+ * which rules go to the GLOBAL layer rather than the project one is decided by
+ * frontmatter — `workspaces:` naming the package's own maintainer workspace —
+ * not by anything on the machine.
+ *
+ * Verified exactly on 2026-08-30, which is why this is a partition and not an
+ * estimate: 119 projected rules, 15 carrying `workspaces: [agent-config-maintainer]`,
+ * and 119 − 15 = 104 = the file count of the installed `~/.claude/rules/`. The
+ * 15 split further into 13 written to the project `.claude/rules/` and 2 that
+ * are `type: manual` and written nowhere — which is why `packageOnly` is
+ * reported rather than folded away.
+ *
+ * The predicate is deliberately narrow: a rule is package-only when its
+ * `workspaces:` list exists and contains ONLY the maintainer workspace. A rule
+ * with no `workspaces:` key ships everywhere, which is the common case.
+ */
+export interface DeliveredRuleCensus {
+    /** Rules the global layer receives — the machine-independent user-scope figure. */
+    delivered: RuleDirCensus;
+    /** Rules restricted to this package's own workspace. */
+    packageOnly: RuleDirCensus;
+}
+
+const MAINTAINER_WORKSPACE = 'agent-config-maintainer';
+
+export function censusDeliveredRulePayload(projectionDir: string): DeliveredRuleCensus {
+    const empty = (): RuleDirCensus => ({ files: 0, chars: 0 });
+    const delivered = empty();
+    const packageOnly = empty();
+    let names: string[];
+    try {
+        names = fs.readdirSync(projectionDir).filter((f) => f.endsWith('.md'));
+    } catch {
+        return { delivered, packageOnly };
+    }
+    for (const name of names) {
+        const abs = path.join(projectionDir, name);
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf8');
+        } catch {
+            continue;
+        }
+        const m = /^workspaces:\s*\[([^\]]*)\]/m.exec(text);
+        const listed =
+            m === null
+                ? []
+                : m[1]!
+                      .split(',')
+                      .map((x) => x.trim())
+                      .filter((x) => x !== '');
+        const isPackageOnly = listed.length > 0 && listed.every((w) => w === MAINTAINER_WORKSPACE);
+        const bucket = isPackageOnly ? packageOnly : delivered;
+        bucket.files += 1;
+        bucket.chars += Buffer.byteLength(text, 'utf8');
+    }
+    return { delivered, packageOnly };
+}
+
 export interface PerRuleCost {
     file: string;
     chars: number;
@@ -187,12 +254,19 @@ export interface SkillsCatalogCensus {
     chars: number;
 }
 
-interface RawSkillFrontmatter {
+export interface RawSkillFrontmatter {
     name?: unknown;
     description?: unknown;
 }
 
-function parseFrontmatter(text: string): RawSkillFrontmatter {
+/**
+ * Exported since `road-to-delivered-cost-truth` 2.1: the per-asset ledger must
+ * build the catalogue line the SAME way this census does, or the two disagree
+ * about the same corpus. A second regex-based reader was tried and reconciled
+ * 17.1 % low, because a `[^\n]+` capture truncates every folded multi-line
+ * `description:` — the reconciliation caught it, which is what it is for.
+ */
+export function parseFrontmatter(text: string): RawSkillFrontmatter {
     if (!text.startsWith('---')) return {};
     const end = text.indexOf('\n---', 3);
     if (end === -1) return {};
@@ -242,14 +316,40 @@ export interface ByteCensusSource {
     files: number;
     chars: number;
     tokens_estimate: number;
-    /** Estimate vs residual — see module doc comment. */
-    provenance: 'measured_local_file' | 'residual';
+    /**
+     * Migrated onto the shared evidence-basis vocabulary
+     * (`road-to-delivered-cost-truth` 4.1). `measured_local_file` was this
+     * file's private spelling of `measured`, and `residual` was its spelling of
+     * a figure derived by subtraction — which the contract calls `estimated`.
+     * Two names for one idea is how a vocabulary forks; the old literals are
+     * gone rather than aliased.
+     */
+    provenance: Extract<EvidenceBasis, 'measured' | 'estimated'>;
     /** How this figure was derived — mandatory for anything not a plain file-size sum. */
     basis: string;
 }
 
 export interface ByteCensus {
     sources: ByteCensusSource[];
+    /**
+     * The projection-derived view of the user-scope bucket — road-to-agent-turnaround 4.1.
+     *
+     * DELIBERATELY NOT IN `sources`, and the reason is a defect this change made
+     * and caught: `sources` is SUMMED into `measurable_tokens_total`, and this is
+     * a second VIEW of the user-scope row already in it, not additional payload.
+     * Putting it there added ~123k phantom tokens to the total and reddened
+     * `check_preamble_payload_budget` on the first run. A non-additive figure
+     * belongs beside the sum, never inside it.
+     */
+    derived_user_scope: {
+        delivered_files: number;
+        delivered_chars: number;
+        delivered_tokens: number;
+        package_only_files: number;
+        package_only_chars: number;
+        package_only_tokens: number;
+        basis: string;
+    };
     measurable_tokens_total: number;
     /** Includes the residual bucket — always ≈ measured_cold_start_median by construction (see module doc comment). */
     grand_total_tokens: number;
@@ -338,6 +438,7 @@ export function buildByteCensus(opts: {
     skillsCatalog: SkillsCatalogCensus;
     topRules: PerRuleCost[];
     duplicateScope: ReturnType<typeof censusDuplicateScope>;
+    deliveredRules: DeliveredRuleCensus;
     measuredColdStartMedian: number | null;
     coldStartLegs: number;
 }): ByteCensus {
@@ -358,7 +459,7 @@ export function buildByteCensus(opts: {
             files: opts.userRules.files,
             chars: opts.userRules.chars,
             tokens_estimate: tokensFromChars(opts.userRules.chars),
-            provenance: 'measured_local_file',
+            provenance: 'measured',
             basis: 'Σ byte size of every .md file in the user-scope rules directory, chars/4.',
         },
         {
@@ -366,7 +467,7 @@ export function buildByteCensus(opts: {
             files: opts.projectRules.files,
             chars: opts.projectRules.chars,
             tokens_estimate: tokensFromChars(opts.projectRules.chars),
-            provenance: 'measured_local_file',
+            provenance: 'measured',
             basis: 'Σ byte size of every .md file in the project-scope rules directory, chars/4.',
         },
         {
@@ -374,7 +475,7 @@ export function buildByteCensus(opts: {
             files: claudeMdFiles,
             chars: claudeMdChars,
             tokens_estimate: tokensFromChars(claudeMdChars),
-            provenance: 'measured_local_file',
+            provenance: 'measured',
             basis:
                 'Byte size of project CLAUDE.md + project CLAUDE.local.md (if present) + user ~/.claude/CLAUDE.md ' +
                 '+ every file pulled in by a top-level "@<path>" import line in the user CLAUDE.md, chars/4.',
@@ -384,7 +485,7 @@ export function buildByteCensus(opts: {
             files: opts.globalProfile.present ? 1 : 0,
             chars: opts.globalProfile.chars,
             tokens_estimate: tokensFromChars(opts.globalProfile.chars),
-            provenance: 'measured_local_file',
+            provenance: 'measured',
             basis: opts.globalProfile.present
                 ? `Byte size of ${opts.globalProfile.path as string}, chars/4.`
                 : 'Layer not written yet on this machine (resolveGlobalProfilePath() returned null) — treated as 0, per the roadmap\'s own honesty caveat.',
@@ -394,7 +495,7 @@ export function buildByteCensus(opts: {
             files: opts.skillsCatalog.skills,
             chars: opts.skillsCatalog.chars,
             tokens_estimate: tokensFromChars(opts.skillsCatalog.chars),
-            provenance: 'measured_local_file',
+            provenance: 'measured',
             basis:
                 'Σ "- <name>: <description>\\n" over every SKILL.md frontmatter, chars/4 — the description-text ' +
                 'component only; the host\'s exact on-wire catalog format is not independently file-measurable.',
@@ -411,7 +512,7 @@ export function buildByteCensus(opts: {
             files: 0,
             chars: 0,
             tokens_estimate: residualTokens,
-            provenance: 'residual',
+            provenance: 'estimated',
             basis:
                 'measured_cold_start_median minus the sum of the file-measurable buckets above. No local transcript ' +
                 'or file carries the request\'s raw tool-definition JSON or the per-spawn dispatch-prompt text ' +
@@ -441,6 +542,21 @@ export function buildByteCensus(opts: {
 
     return {
         sources,
+        derived_user_scope: {
+            delivered_files: opts.deliveredRules.delivered.files,
+            delivered_chars: opts.deliveredRules.delivered.chars,
+            delivered_tokens: tokensFromChars(opts.deliveredRules.delivered.chars),
+            package_only_files: opts.deliveredRules.packageOnly.files,
+            package_only_chars: opts.deliveredRules.packageOnly.chars,
+            package_only_tokens: tokensFromChars(opts.deliveredRules.packageOnly.chars),
+            basis:
+                'Σ byte size of every dist/agent-src/rules/*.md whose `workspaces:` does not restrict it to ' +
+                `the ${MAINTAINER_WORKSPACE} workspace, chars/4 — computed without reading ~/.claude at all. ` +
+                'This is the bucket src/config/preamble-payload-budget.json excludes as "machine-dependent, ' +
+                'not CI-checkable", and computing it here is what falsifies that reason. A gap against the ' +
+                'measured user-scope row is INSTALL DRIFT (the machine carries an older release), never a ' +
+                'defect in either number.',
+        },
         measurable_tokens_total: measurableTokensTotal,
         grand_total_tokens: grandTotal,
         measured_cold_start_median: median,
@@ -471,6 +587,7 @@ export function buildReport(opts: Options): ByteCensus {
     const skillsCatalog = censusSkillsCatalog(opts.skillsDir);
     const topRules = topRulesByCost(opts.projectRulesDir, 10);
     const duplicateScope = censusDuplicateScope(opts.userRulesDir, opts.projectRulesDir);
+    const deliveredRules = censusDeliveredRulePayload(opts.projectRulesDir);
 
     const scan = scanTranscripts({ root: opts.root, maxAgeDays: opts.maxAgeDays });
     const coldStart = computeColdStarts(scan.records);
@@ -484,6 +601,7 @@ export function buildReport(opts: Options): ByteCensus {
         skillsCatalog,
         topRules,
         duplicateScope,
+        deliveredRules,
         measuredColdStartMedian,
         coldStartLegs: coldStart.legs,
     });
@@ -504,6 +622,17 @@ export function renderText(r: ByteCensus): string {
         out.push(`    basis: ${s.basis}`);
     }
     out.push('');
+    const d = r.derived_user_scope;
+    out.push('');
+    out.push('User-scope bucket, DERIVED from the projection (NOT summed — a second view of a row above):');
+    out.push(
+        `  delivered to the global layer: files=${String(d.delivered_files)} chars=${String(d.delivered_chars)} tokens_estimate=${String(d.delivered_tokens)}`,
+    );
+    out.push(
+        `  package-only (never delivered): files=${String(d.package_only_files)} chars=${String(d.package_only_chars)} tokens_estimate=${String(d.package_only_tokens)}`,
+    );
+    out.push(`  basis: ${d.basis}`);
+    out.push('');
     out.push(`measurable_tokens_total (excludes residual): ${Math.round(r.measurable_tokens_total)}`);
     out.push(`grand_total_tokens (includes residual): ${Math.round(r.grand_total_tokens)}`);
     if (r.measured_cold_start_median !== null) {

package/src/scripts/prepack-check.mjs

@@ -76,6 +76,8 @@ process.stderr.write(`prepack-check: ${BIN} OK\n`);
 // the shipped set is derived from the package.json `files` whitelist.
 // ---------------------------------------------------------------------------
 import { readdirSync } from 'node:fs';
+
+import { stripCommentsMjs } from './_lib/strip_comments.mjs';
 import { dirname, join, relative, sep } from 'node:path';
 
 const pkg = JSON.parse(readFileSync(resolve('package.json'), 'utf8'));
@@ -109,6 +111,7 @@ function* walk(dir) {
 
 const IMPORT_RE = /(?:from\s+|import\s*\(\s*|require\s*\(\s*)['"](\.\.?\/[^'"]+)['"]/g;
 
+
 function resolveCandidates(fromDir, spec) {
     const base = join(fromDir, spec);
     return [
@@ -126,7 +129,7 @@ const importErrors = [];
 const scanRoots = shippedPrefixes.filter((p) => p.startsWith('src/'));
 for (const root of scanRoots) {
     for (const file of walk(resolve(root))) {
-        const text = readFileSync(file, 'utf8');
+        const text = stripCommentsMjs(readFileSync(file, 'utf8'));
         for (const m of text.matchAll(IMPORT_RE)) {
             const spec = m[1];
             const candidates = resolveCandidates(dirname(file), spec);