@event4u/agent-config 10.1.0 → 10.2.0

package/src/scripts/lint_settings_classes.ts

@@ -15,7 +15,9 @@
  *   4. every B row's template default is a conservative value
  *      (`false` / `""` / `0` / `[]` / `null` / `{}`) — the invariant that makes
  *      "absent" and "declined" the same outcome in a sparse settings file;
- *   5. the contract's own Counts table matches the tallies computed here.
+ *   5. the contract's own Counts table matches the tallies computed here;
+ *   6. every `REMOVED_KEYS` entry names what decides instead, and no key is
+ *      both removed and live in the template.
  *
  * **Landed at error, not advisory.** The authoring guideline's advisory-first
  * rule exists so a gate cannot be wired to error over a corpus whose hits are
@@ -48,16 +50,24 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { load as parseYaml } from 'js-yaml';
 
 import {
+    dispositionOf,
     getSettingsLeaf,
     isConservativeDefault,
     isSettingsClass,
+    isSettingsDisposition,
     parseDeclaredClassCounts,
+    parseDeclaredDispositionCounts,
     parseSettingsClassRows,
+    replacementOf,
     SETTINGS_CLASSES,
+    SETTINGS_DISPOSITIONS,
     type SettingsClass,
     type SettingsClassRow,
+    type SettingsDisposition,
     settingsLeafPaths,
 } from '../shared/settingsClasses.js';
+import { REMOVED_KEYS } from './_lib/agent_settings.js';
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
@@ -117,15 +127,27 @@ export function selfTest(): number {
         `\n## Counts\n\n| Class | Keys |\n|---|---|\n| A — preference | ${String(a)} |\n` +
         `| B — consent | ${String(b)} |\n| C — guarded | ${String(c)} |\n` +
         `| **Total** | **${String(total)}** |\n`;
-    const table = (rows: string): string => `# Fixture\n${counts(0, 1, 1, 2)}\n## The table\n\n| Key | Class | Default | Why |\n|---|---|---|---|\n${rows}`;
+    // The disposition tallies, in the section the parser scopes to. Defaulted to
+    // the clean fixture's shape so a case that does not care about them says so
+    // by omission rather than by restating four rows.
+    const dispositions = (d: number, u: number, co: number, p: number, total: number): string =>
+        `\n## Dispositions\n\n| Disposition | Keys |\n|---|---|\n| derivable | ${String(d)} |\n` +
+        `| un-inferrable | ${String(u)} |\n| consent | ${String(co)} |\n| policy | ${String(p)} |\n` +
+        `| **Total** | **${String(total)}** |\n`;
+    const table = (rows: string, disp = dispositions(0, 1, 1, 0, 2)): string =>
+        `# Fixture\n${counts(0, 1, 1, 2)}\n${disp}\n## The table\n\n` +
+        `| Key | Class | Default | Why | Disposition |\n|---|---|---|---|---|\n${rows}`;
 
-    const clean = table('| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n');
+    const clean = table(
+        '| `alpha.one` | B | `false` | fixture | consent |\n' +
+            '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+    );
 
     try {
         return runSelfTest({
             gate: GATE,
-            minCases: 6,
-            minRejectCases: 5,
+            minCases: 12,
+            minRejectCases: 10,
             cases: [
                 {
                     name: 'a template whose every leaf is classified passes',
@@ -140,7 +162,7 @@ export function selfTest(): number {
                             seed(
                                 'unclassified',
                                 template,
-                                table('| `beta` | C | `"keep"` | fixture |\n') + counts(0, 0, 1, 1),
+                                table('| `beta` | C | `"keep"` | fixture | un-inferrable |\n') + counts(0, 0, 1, 1),
                             ),
                         ),
                 },
@@ -153,8 +175,9 @@ export function selfTest(): number {
                                 'stale-row',
                                 template,
                                 table(
-                                    '| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n' +
-                                        '| `gamma.gone` | A | `1` | fixture |\n',
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n' +
+                                        '| `gamma.gone` | A | `1` | fixture | policy |\n',
                                 ),
                             ),
                         ),
@@ -167,7 +190,90 @@ export function selfTest(): number {
                             seed(
                                 'bad-class',
                                 template,
-                                table('| `alpha.one` | D | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n'),
+                                table(
+                                    '| `alpha.one` | D | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a leaf with a class but no disposition is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'no-disposition',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture |\n',
+                                    dispositions(0, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a disposition outside the closed vocabulary is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'bad-disposition',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | obsolete |\n',
+                                    dispositions(0, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a `derivable` row that names no replacement is rejected — the clause IS the falsifier',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'derivable-without-replacement',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | derivable |\n',
+                                    dispositions(1, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a `derivable` row that names its replacement passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            seed(
+                                'derivable-with-replacement',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | derivable — the probe reads it |\n',
+                                    dispositions(1, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a Dispositions table that disagrees with the rows is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'bad-disposition-counts',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                    dispositions(7, 7, 7, 7, 28),
+                                ),
                             ),
                         ),
                 },
@@ -191,8 +297,10 @@ export function selfTest(): number {
                             seed(
                                 'bad-counts',
                                 template,
-                                `# Fixture\n${counts(9, 9, 9, 27)}\n## The table\n\n| Key | Class | Default | Why |\n|---|---|---|---|\n` +
-                                    '| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n',
+                                `# Fixture\n${counts(9, 9, 9, 27)}\n${dispositions(0, 1, 1, 0, 2)}\n` +
+                                    '## The table\n\n| Key | Class | Default | Why | Disposition |\n|---|---|---|---|---|\n' +
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                    '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
                             ),
                         ),
                 },
@@ -201,6 +309,29 @@ export function selfTest(): number {
                     expect: 'reject',
                     run: () => run(seed('dead-root', null, clean)),
                 },
+                {
+                    name: 'a template leaf that is also a REMOVED_KEYS entry is rejected (check 6)',
+                    expect: 'reject',
+                    // `REMOVED_KEYS` is compiled into the loader, so a fixture root
+                    // cannot seed it — but it can seed the other side of the
+                    // contradiction. A fixture that declares `quality.wait_for_remote_ci`
+                    // as a live, fully classified leaf is a tree where the loader
+                    // would warn "ignored" about a value the schema honours, which
+                    // is exactly the state check 6 exists to refuse. Classified and
+                    // counted correctly on purpose: every other check passes here,
+                    // so a rejection can only come from check 6.
+                    run: () =>
+                        run(
+                            seed(
+                                'removed-and-live',
+                                'quality:\n  wait_for_remote_ci: false\nbeta: "keep"\n',
+                                table(
+                                    '| `quality.wait_for_remote_ci` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                ),
+                            ),
+                        ),
+                },
             ],
         });
     } finally {
@@ -331,6 +462,98 @@ function main(): number {
         ledger.complete(target);
     }
 
+    // --- the disposition axis -------------------------------------------------
+    // Orthogonal to A/B/C: that answers who may WRITE a key, this answers whether
+    // the key should EXIST. Checked against the same leaf set, in the same gate,
+    // so a key with no disposition fails the mechanism that already counts it —
+    // rather than sitting in a second artefact that can drift from the template.
+    const dispositionTally: Record<SettingsDisposition, number> = {
+        derivable: 0,
+        'un-inferrable': 0,
+        consent: 0,
+        policy: 0,
+    };
+    for (const leaf of leaves) {
+        const row = rowByKey.get(leaf);
+        if (row === undefined) {
+            continue; // already reported as unclassified above
+        }
+        const label = dispositionOf(row.disposition);
+        if (label === null || label === '') {
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` has no disposition — add one of ` +
+                    `${SETTINGS_DISPOSITIONS.join(' | ')}. A key with no disposition is the finding: ` +
+                    'nobody has said whether it should exist.',
+            );
+            continue;
+        }
+        if (!isSettingsDisposition(label)) {
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` has disposition '${label}' — ` +
+                    `allowed: ${SETTINGS_DISPOSITIONS.join(' | ')}.`,
+            );
+            continue;
+        }
+        dispositionTally[label] += 1;
+        if (label === 'derivable' && replacementOf(row.disposition) === '') {
+            // The replacement clause is what makes `derivable` falsifiable. Without
+            // it the label degrades into a synonym for "inconvenient to keep", and
+            // the direction of this axis pushes every borderline row toward it.
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` is \`derivable\` but names no ` +
+                    'replacement — write `derivable — <what decides instead>`. A derivable row that ' +
+                    'cannot name its replacement is reclassified, not deleted.',
+            );
+        }
+    }
+
+    // The anti-regrowth ratchet. `derivable` is a deletion queue, so its size is
+    // a debt count and may only fall: a NEW key classified `derivable` is a key
+    // that should not have been added, and it raises the number. The 56-day
+    // non-stagnation clause in the shared baseline mechanism is the other half —
+    // a queue that never drains is a direction nobody is walking.
+    //
+    // Deliberately scoped to the real repo root. Under `--root` (self-test
+    // fixtures) the baseline describes a different tree entirely, and judging a
+    // two-key fixture against this repository's surface would make every fixture
+    // report a loose ratchet.
+    if (_rootOverride(process.argv.slice(2)) === null) {
+        const verdict = checkRatchet({
+            gate: `${GATE}:derivable-surface`,
+            actual: dispositionTally.derivable,
+            repoRoot: REPO_ROOT,
+        });
+        if (!verdict.ok) {
+            findings.push(verdict.message);
+        } else if (verdict.status === 'improved' && !QUIET) {
+            process.stdout.write(`ℹ️  ${verdict.message}\n`);
+        }
+    }
+
+    const declaredDisposition = parseDeclaredDispositionCounts(contractText);
+    const dispositionExpected: Array<[string, number | null, number]> = [
+        ['derivable', declaredDisposition.derivable, dispositionTally.derivable],
+        ['un-inferrable', declaredDisposition['un-inferrable'], dispositionTally['un-inferrable']],
+        ['consent', declaredDisposition.consent, dispositionTally.consent],
+        ['policy', declaredDisposition.policy, dispositionTally.policy],
+        ['Total', declaredDisposition.total, leaves.length],
+    ];
+    for (const [label, stated, actual] of dispositionExpected) {
+        if (stated === null) {
+            findings.push(
+                `${CONTRACT_RELATIVE}  the Dispositions table has no '${label}' row — a published count ` +
+                    'with no row is a count nothing can check.',
+            );
+            continue;
+        }
+        if (stated !== actual) {
+            findings.push(
+                `${CONTRACT_RELATIVE}  Dispositions says ${label} = ${String(stated)}, the table holds ` +
+                    `${String(actual)} — a derived number beside a mechanism that can compute it.`,
+            );
+        }
+    }
+
     const declared = parseDeclaredClassCounts(contractText);
     const expected: Array<[string, number | null, number]> = [
         ['A', declared.A, tally.A],
@@ -354,6 +577,45 @@ function main(): number {
         }
     }
 
+    // Check 6 — the DELETION side of the surface.
+    //
+    // Checks 1-5 all police what is added: a new leaf needs a row, a class, a
+    // disposition, a conservative default. Nothing policed what is removed, and
+    // that is the asymmetry this axis lives on — the whole direction of the
+    // roadmap behind it is deletion, so the un-gated half was the half doing the
+    // work. Two contradictions are decidable here and neither is visible to the
+    // loader that prints the warning:
+    //
+    //   a. a reason that names no replacement. The `derivable` rows above are
+    //      already held to "name what decides instead" because that clause is the
+    //      falsifier; a deleted key is the same claim after the fact, and a
+    //      warning that says only "removed" sends the reader looking for a
+    //      successor key that does not exist.
+    //   b. a key that is BOTH removed and live. Re-adding a leaf while its
+    //      `REMOVED_KEYS` entry stands makes the loader warn "ignored" about a
+    //      value the schema now honours — the reader is told the opposite of what
+    //      happens.
+    //
+    // What this does NOT check, stated because the step it serves asks for it:
+    // that the replacement mechanism actually EXISTS, and that its commit
+    // precedes the deletion. Neither is decidable from these two files; both stay
+    // model-carried, exactly as the A/B/C judgement itself does.
+    const liveLeaves = new Set(leaves);
+    for (const [removedKey, reason] of REMOVED_KEYS) {
+        if (reason.trim() === '') {
+            findings.push(
+                `src/scripts/_lib/agent_settings.ts  \`${removedKey}\` is in REMOVED_KEYS with an empty ` +
+                    'reason — name what decides instead, not that it is gone.',
+            );
+        }
+        if (liveLeaves.has(removedKey)) {
+            findings.push(
+                `${TEMPLATE_RELATIVE}  \`${removedKey}\` is a live template leaf AND a REMOVED_KEYS ` +
+                    'entry — the loader would warn that a honoured value is ignored. Drop one side.',
+            );
+        }
+    }
+
     ledger.report();
 
     if (findings.length > 0) {

package/src/scripts/lint_symptom_intake.ts

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+/**
+ * Warn-only gate: operator symptom entries under `agents/tickets/symptoms/`
+ * must be resolved within 30 days of the reported date.
+ *
+ * "Resolved" means the entry carries exactly one of the two blocks the
+ * directory's `README.md` defines — `## confirmed:` (a defect with `file:line`
+ * at a pinned commit) or `## null:` (checked, not reproducible, with evidence).
+ * A `null:` is a first-class outcome: the point of the gate is that somebody
+ * looked, not that a defect was found.
+ *
+ * **Warn-only by design, and the design is the load-bearing part.** Intake has
+ * to stay cheaper than the work it triggers, so an unresolved report is a
+ * reminder, never a build failure — a gate that reds CI because a human has not
+ * yet investigated a symptom would train people to stop filing symptoms, which
+ * is the exact opposite of what the surface is for
+ * (`agents/roadmaps/archive/road-to-symptom-driven-harvest-loop.md` Phase 1 Step 2).
+ * The only exit-1 path is a dead scan scope.
+ *
+ * Scope: `agents/tickets/symptoms/*.md`, one level, no recursion.
+ * `README.md` and `_`-prefixed files (the template) are counted as scanned but
+ * never evaluated — so the gate keeps a non-zero denominator while the surface
+ * exists, and does not red the moment the last entry is resolved away.
+ *
+ * Exit codes: 0 = clean or warnings only, 1 = dead scan scope.
+ * `--quiet` is a bare argv membership check, matching the sibling roadmap gates.
+ * `--now=YYYY-MM-DD` overrides today (tests and reproducible runs only).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+
+const QUIET = process.argv.slice(2).includes('--quiet');
+
+const SYMPTOM_DIR = path.join('agents', 'tickets', 'symptoms');
+
+/** Days after `reported:` at which an unresolved entry starts warning. */
+export const STALE_AFTER_DAYS = 30;
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+
+const REPORTED_RE = /^reported:\s*(\d{4}-\d{2}-\d{2})\s*$/m;
+const CONFIRMED_RE = /^##\s+confirmed:\s*$/m;
+const NULL_RE = /^##\s+null:\s*$/m;
+
+export interface SymptomFinding {
+    readonly file: string;
+    readonly kind: 'unresolved' | 'no-reported-date';
+    readonly ageDays: number | null;
+}
+
+/** Walk up from CWD until a dir containing `agents/tickets` is found. */
+function _repoRoot(): string {
+    let cur = 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) {
+        try {
+            if (fs.statSync(path.join(candidate, 'agents', 'tickets')).isDirectory()) {
+                return candidate;
+            }
+        } catch {
+            // keep walking
+        }
+    }
+    return process.cwd();
+}
+
+function _isDir(p: string): boolean {
+    try {
+        return fs.statSync(p).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/** Every `*.md` directly under the symptoms dir, sorted. */
+export function listMarkdown(base: string): string[] {
+    if (!_isDir(base)) return [];
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => e.name)
+        .sort();
+}
+
+/** An entry is a report; `README.md` and `_`-prefixed files are not. */
+export function isEntry(name: string): boolean {
+    return name.endsWith('.md') && name !== 'README.md' && !name.startsWith('_');
+}
+
+function _daysBetween(fromIso: string, now: Date): number | null {
+    const parsed = Date.parse(`${fromIso}T00:00:00Z`);
+    if (Number.isNaN(parsed)) return null;
+    return Math.floor((now.getTime() - parsed) / 86_400_000);
+}
+
+export function evaluate(text: string, name: string, now: Date): SymptomFinding | null {
+    const reported = REPORTED_RE.exec(text);
+    if (reported === null) {
+        return { file: name, kind: 'no-reported-date', ageDays: null };
+    }
+    if (CONFIRMED_RE.test(text) || NULL_RE.test(text)) {
+        return null;
+    }
+    const age = _daysBetween(reported[1] as string, now);
+    if (age === null) {
+        return { file: name, kind: 'no-reported-date', ageDays: null };
+    }
+    if (age <= STALE_AFTER_DAYS) {
+        return null;
+    }
+    return { file: name, kind: 'unresolved', ageDays: age };
+}
+
+function _now(): Date {
+    const flag = process.argv.slice(2).find((a) => a.startsWith('--now='));
+    if (flag !== undefined) {
+        const parsed = Date.parse(`${flag.slice('--now='.length)}T00:00:00Z`);
+        if (!Number.isNaN(parsed)) return new Date(parsed);
+    }
+    return new Date();
+}
+
+function main(): number {
+    const root = _repoRoot();
+    const base = path.join(root, SYMPTOM_DIR);
+    const names = listMarkdown(base);
+
+    try {
+        // The scanned unit counts README + template too, deliberately: this gate
+        // must not go dead the moment the last open entry is resolved, and the
+        // directory always carries its convention file while the surface exists.
+        assertScanned({
+            gate: 'lint_symptom_intake',
+            scanned: names.length,
+            units: 'symptom file(s)',
+            roots: [SYMPTOM_DIR],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    const now = _now();
+    const findings: SymptomFinding[] = [];
+    let entryCount = 0;
+
+    // Per-target accounting: README.md and the template are planned too, so the
+    // ledger states out loud that they were seen and deliberately not evaluated
+    // — an unaccounted `continue` is the silent-skip defect this module catches.
+    const ledger = new GateLedger('lint_symptom_intake');
+    ledger.plan(names);
+
+    for (const name of names) {
+        if (!isEntry(name)) {
+            ledger.outOfScope(name, 'not_applicable_kind');
+            continue;
+        }
+        entryCount += 1;
+        let text: string;
+        try {
+            text = fs.readFileSync(path.join(base, name), 'utf-8');
+        } catch {
+            ledger.skip(name, 'binary_content');
+            continue;
+        }
+        const finding = evaluate(text, name, now);
+        if (finding !== null) {
+            findings.push(finding);
+            ledger.fail(name, finding.kind);
+        } else {
+            ledger.complete(name);
+        }
+    }
+
+    if (findings.length === 0) {
+        ledger.report();
+        if (!QUIET) {
+            process.stdout.write(
+                `✅  lint-symptom-intake: ${entryCount} entry(ies) resolved or within ` +
+                    `${STALE_AFTER_DAYS} days.\n`,
+            );
+        }
+        return 0;
+    }
+
+    ledger.report();
+    process.stdout.write(`⚠️  lint-symptom-intake: ${findings.length} unresolved symptom entry(ies):\n`);
+    for (const f of findings) {
+        if (f.kind === 'no-reported-date') {
+            process.stdout.write(`      ${SYMPTOM_DIR}/${f.file} — no valid \`reported: YYYY-MM-DD\` in frontmatter\n`);
+        } else {
+            process.stdout.write(
+                `      ${SYMPTOM_DIR}/${f.file} — reported ${String(f.ageDays)} days ago, ` +
+                    'no `## confirmed:` or `## null:` block\n',
+            );
+        }
+    }
+    process.stdout.write('\n');
+    process.stdout.write('   Add whichever block is true (see agents/tickets/symptoms/README.md):\n');
+    process.stdout.write('     • `## confirmed:` — defect + file:line at a pinned commit + owning roadmap\n');
+    process.stdout.write('     • `## null:` — what was checked, and why it does not reproduce\n');
+    process.stdout.write('   A null is a result, not a failure to act. This gate never fails the build.\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();
+}
+
+export { QUIET, SYMPTOM_DIR, main };

package/src/scripts/report_consultation_rate.ts

@@ -46,6 +46,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { projectStoreSlug } from './_lib/cc_transcript.js';
 import {
     isConsultation,
     isUiWrite,
@@ -107,7 +108,7 @@ export interface RateReport {
  * reads a clean zero out of a store it never found.
  */
 export function defaultStore(cwd: string): string {
-    return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/[/.]/g, '-'));
+    return path.join(os.homedir(), '.claude', 'projects', projectStoreSlug(cwd));
 }
 
 /**

package/src/scripts/report_skill_activation.ts

@@ -52,6 +52,8 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { projectStoreSlug } from './_lib/cc_transcript.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
@@ -114,11 +116,11 @@ export interface UsageReport {
 
 /** Default store for the current working directory, mangled the way the host does. */
 export function defaultStore(cwd: string): string {
-  // Dots are flattened too, not only separators: a worktree at
-  // `<repo>/.claude/worktrees/x` lands in `…-agent-config--claude-worktrees-x`.
-  // Replacing only `/` returns a directory that does not exist, and the caller
+  // Every non-alphanumeric is flattened, not only separators: a worktree at
+  // `<repo>/.claude/worktrees/x+y` lands in `…-agent-config--claude-worktrees-x-y`.
+  // A narrower class returns a directory that does not exist, and the caller
   // then reads a clean zero out of a store it never found.
-  return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/[/.]/g, '-'));
+  return path.join(os.homedir(), '.claude', 'projects', projectStoreSlug(cwd));
 }
 
 export function measureUsage(store: string, limit: number): UsageReport {

package/src/scripts/report_skill_obligation_violations.ts

@@ -59,6 +59,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { projectStoreSlug } from './_lib/cc_transcript.js';
 import { entryText, isSidechain, toolUses as _toolUses } from './_lib/transcript_entry.js';
 import { censusSkills, DETERMINISTIC_RE, SKILLS_ROOT } from './report_skill_activation.js';
 
@@ -408,7 +409,7 @@ export interface Sk2Report {
 }
 
 export function defaultStore(cwd: string): string {
-    return path.join(os.homedir(), '.claude', 'projects', cwd.replace(/[/.]/g, '-'));
+    return path.join(os.homedir(), '.claude', 'projects', projectStoreSlug(cwd));
 }
 
 export function scanStore(repoRoot: string, store: string, limit: number): Sk2Report {

package/src/server/io/yamlIO.ts

@@ -144,8 +144,6 @@ export const TEMPLATE_PLACEHOLDER_DEFAULTS: Readonly<Record<string, string>> = {
     __DISCIPLINE_PROFILE__: 'auto',
     __USER_TYPE__: '',
     __CHAT_HISTORY_FREQUENCY__: 'per_turn',
-    __CHAT_HISTORY_MAX_SIZE_KB__: '2048',
-    __CHAT_HISTORY_ON_OVERFLOW__: 'rotate',
 };
 
 /** Replace every known template placeholder with its default value. */