@event4u/agent-config 10.1.0 → 10.3.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,7 +46,9 @@ 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 {
+    isArtifactRead,
     isConsultation,
     isUiWrite,
     type ToolEvent,
@@ -80,6 +82,24 @@ export interface SessionMeasurement {
     consulted: number;
     /** Those turns followed later by opening the review skill. */
     reviewOpenedAfter: number;
+    /**
+     * Those turns that followed reading a provided design artifact.
+     *
+     * Shares this function's denominator on purpose — the two rates answer
+     * different questions over the SAME population ("did it consult the design
+     * surface" vs "did it read the handed-over source"), and measuring them on
+     * separate denominators is how two instruments about one behaviour stop
+     * being comparable.
+     */
+    artifactRead: number;
+    /** True when this session read a provided artifact at any point. */
+    sawArtifact: boolean;
+    /**
+     * True when this session's FIRST UI write came after an artifact read —
+     * the metric named "artifact read before first UI write". Meaningless
+     * unless `sawArtifact`, which is why it is reported over that denominator.
+     */
+    readBeforeFirstWrite: boolean;
 }
 
 export interface RateReport {
@@ -95,6 +115,16 @@ export interface RateReport {
     uiWriteTurns: number;
     consulted: number;
     reviewOpenedAfter: number;
+    /** UI-write turns preceded by reading a provided design artifact. */
+    artifactRead: number;
+    /**
+     * Sessions that read a provided artifact at all — the ONLY honest
+     * denominator for the read-before-write rate. A session with no handover
+     * cannot fail to read one.
+     */
+    handoverSessions: number;
+    /** Of those, the ones whose first UI write came after the read. */
+    handoverReadFirst: number;
 }
 
 /**
@@ -107,7 +137,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));
 }
 
 /**
@@ -138,10 +168,20 @@ export function toolUseToEvent(part: Record<string, unknown>): ToolEvent | null
  * consult for the file it already wrote.
  */
 export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement {
-    const out: SessionMeasurement = { uiWriteTurns: 0, consulted: 0, reviewOpenedAfter: 0 };
+    const out: SessionMeasurement = {
+        uiWriteTurns: 0,
+        consulted: 0,
+        reviewOpenedAfter: 0,
+        artifactRead: 0,
+        sawArtifact: false,
+        readBeforeFirstWrite: false,
+    };
     let consulted = false;
+    let artifactRead = false;
     /** turn -> was the session already consulted when that turn first wrote UI */
     const writeTurns = new Map<number, boolean>();
+    /** turn -> had an artifact been read when that turn first wrote UI */
+    const artifactTurns = new Map<number, boolean>();
     let lastReviewOpenAt = -1;
     const reviewOpenPositions: number[] = [];
     const writePositions: Array<{ position: number; turn: number }> = [];
@@ -150,10 +190,18 @@ export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement
         if (isUiWrite(event)) {
             if (!writeTurns.has(turn)) {
                 writeTurns.set(turn, consulted);
+                artifactTurns.set(turn, artifactRead);
                 writePositions.push({ position, turn });
             }
             return;
         }
+        // Evaluated INDEPENDENTLY of the consultation branch, never as an
+        // early return before it. The two predicates are not disjoint —
+        // `skills/design-review/references/design.html` satisfies both — so a
+        // `return` here would remove such an event from the consultation
+        // numerator and from the discharge-proxy latch. An earlier revision did
+        // exactly that while claiming in its comment to prevent it.
+        if (isArtifactRead(event)) artifactRead = true;
         if (isConsultation(event)) {
             consulted = true;
             if (event.file.replace(/\\/g, '/').toLowerCase().includes(`skills/${REVIEW_SURFACE}/`)) {
@@ -165,6 +213,20 @@ export function measureSession(timed: readonly TimedEvent[]): SessionMeasurement
 
     out.uiWriteTurns = writeTurns.size;
     for (const wasConsulted of writeTurns.values()) if (wasConsulted) out.consulted += 1;
+    for (const wasRead of artifactTurns.values()) if (wasRead) out.artifactRead += 1;
+    out.sawArtifact = artifactRead;
+    // KNOWN IMPRECISION, accepted: ordering inside ONE assistant message comes
+    // from the `tool_use` part index, and parallel tool calls in a single
+    // message carry no real order. A read and a write issued together can
+    // therefore score either way. Not repaired here — a transcript carries no
+    // per-call timestamp, so the fix is a different data source rather than a
+    // different loop, and the error is bounded to same-message pairs. It is a
+    // third reason the published rate is a ceiling.
+    //
+    // The FIRST write's outcome — `artifactTurns` is insertion-ordered on the
+    // first UI write of each turn, so its first value is that write's state.
+    const firstWrite = artifactTurns.values().next();
+    out.readBeforeFirstWrite = firstWrite.done !== true && firstWrite.value === true;
     // A single max comparison, not a scan per write: the proxy asks only whether
     // ANY review-open follows, so the last one decides every earlier write.
     void reviewOpenPositions;
@@ -215,6 +277,9 @@ export function measureStore(store: string, limit: number): RateReport {
         uiWriteTurns: 0,
         consulted: 0,
         reviewOpenedAfter: 0,
+        artifactRead: 0,
+        handoverSessions: 0,
+        handoverReadFirst: 0,
     };
     // A store that is not there and a store with nothing in it are different
     // findings, and only one of them is about the agent. Collapsing them into
@@ -254,6 +319,11 @@ export function measureStore(store: string, limit: number): RateReport {
         report.uiWriteTurns += measured.uiWriteTurns;
         report.consulted += measured.consulted;
         report.reviewOpenedAfter += measured.reviewOpenedAfter;
+        report.artifactRead += measured.artifactRead;
+        if (measured.sawArtifact) {
+            report.handoverSessions += 1;
+            if (measured.readBeforeFirstWrite) report.handoverReadFirst += 1;
+        }
     }
     return report;
 }
@@ -284,6 +354,62 @@ export function render(report: RateReport, threshold: number): string {
     lines.push(
         `  discharge PROXY (review opened)  ${pct(report.reviewOpenedAfter, report.uiWriteTurns)}  (${report.reviewOpenedAfter}/${report.uiWriteTurns})`,
     );
+    lines.push(
+        `  artifact read (all UI turns)     ${pct(report.artifactRead, report.uiWriteTurns)}  (${report.artifactRead}/${report.uiWriteTurns})`,
+    );
+    lines.push(
+        `  READ BEFORE FIRST WRITE          ${pct(report.handoverReadFirst, report.handoverSessions)}  (${report.handoverReadFirst}/${report.handoverSessions} handover session(s))`,
+    );
+    lines.push('');
+    lines.push(
+        '  READ BEFORE FIRST WRITE is the rate to quote. Its denominator is',
+    );
+    lines.push(
+        '  sessions that read a provided artifact at all — a session with no',
+    );
+    lines.push(
+        '  handover cannot fail to read one, so including it would dilute the',
+    );
+    lines.push(
+        '  rate toward the size of the estate rather than the behaviour.',
+    );
+    lines.push(
+        '  That denominator is narrower than it sounds, twice: "artifact" means',
+    );
+    lines.push(
+        '  a path ending design.html or under .claude/design-system/ — a handover',
+    );
+    lines.push(
+        '  under any other name is not counted — and a session that read one but',
+    );
+    lines.push(
+        '  wrote no UI is excluded, since it had nothing to be late for.',
+    );
+    lines.push(
+        '  The line above it shares the consultation denominator and is kept for',
+    );
+    lines.push(
+        '  comparability with that rate only.',
+    );
+    lines.push('');
+    lines.push(
+        '  A CEILING, NOT A MEASUREMENT, for two reasons. A session handed an',
+    );
+    lines.push(
+        '  artifact that NEVER reads it is invisible — nothing in a transcript',
+    );
+    lines.push(
+        '  marks a handover that was ignored, and that case IS the defect. And a',
+    );
+    lines.push(
+        '  search whose path argument happens to be the artifact counts as a read',
+    );
+    lines.push(
+        '  although nothing was read. Both errors point the same way: the true',
+    );
+    lines.push(
+        '  read-before-write rate is at most what is printed here.',
+    );
     lines.push('');
 
     if (report.sessionsWithUiWrite < threshold) {

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/scripts/run_skill_evals.ts

@@ -10,10 +10,13 @@
  * JSON files (json.dumps indent=2 + trailing newline). No behaviour
  * changes.
  *
- * The `.agent-src.uncondensed/skills/` literal below is part of the
- * mirrored .py source — this is a faithful twin, so the legacy path is
- * replicated verbatim, not modernized (ADR-051 carve-out for faithful
- * twins).
+ * SKILLS_ROOT diverges from the mirrored .py source: it resolves the live
+ * skills tree through the shared resolver instead of replicating the retired
+ * container literal. Replicating it made every subcommand fail in
+ * `_skill_dir()` before doing any work — the twin was byte-faithful to a
+ * source that no longer exists and runnable against nothing. Documented per
+ * ADR-200 § 6 in `docs/migration/divergences/src-scripts-run_skill_evals.md`;
+ * an undocumented difference would be a regression by definition.
  *
  * Sub-agent SPAWNING is per-environment (Claude Code, Augment Code,
  * council) and is left as a stub `_spawn_subagent(...)` that authors
@@ -25,11 +28,13 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { SRC_SKILLS } from './_lib/agent_src.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/run_skill_evals.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
-export const SKILLS_ROOT = path.join(REPO_ROOT, '.agent-src.uncondensed', 'skills');
+export const SKILLS_ROOT = SRC_SKILLS();
 
 /** JSON value type for eval specs / grades. */
 type JsonValue =

package/src/scripts/schemas/persona.schema.json

@@ -44,6 +44,14 @@
       "type": "string",
       "enum": ["package", "project"],
       "default": "package"
+    },
+    "sources": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+      },
+      "description": "Optional harvest_id list (provenance/harvests.jsonl) this persona may cite as external doctrine. Three distinct states, and the difference is the point: ABSENT = unscoped, today's behaviour for every persona that does not opt in; [] = explicitly declares it asserts only from its own reasoning, nothing harvested; a non-empty list = scoped to exactly those ids. Every declared id must resolve to a ledger row — checked by lint_harvest_provenance.ts, which treats a persona entry as a citation exactly like an inline harvest marker. Not to be confused with the singular `source` field above, which records package-vs-project origin."
     }
   }
 }

package/src/scripts/schemas/provenance-harvest.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "provenance-harvest.schema.json",
+  "title": "Provenance ledger harvest record",
+  "description": "One line of provenance/harvests.jsonl — a single knowledge claim adopted from an external source into this repo's own artefacts. Sibling of provenance-borrow.schema.json, which covers borrowed CODE; this one covers borrowed IDEAS. Contract: provenance/README.md. Enforced by src/scripts/lint_harvest_provenance.ts (hand-rolled validator, following the provenance-borrow precedent — this file documents the contract; it is not loaded at runtime).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["harvest_id", "stated_in", "source_ref", "evidence_locator", "harvested_at", "verdict"],
+  "properties": {
+    "harvest_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case slug naming the harvested mechanism. This is the id an artefact cites; it must be unique across the ledger."
+    },
+    "stated_in": {
+      "type": "string",
+      "description": "Repo-relative path of the artefact asserting the claim, optionally suffixed ':<line>'. The path must exist."
+    },
+    "source_ref": {
+      "type": "string",
+      "description": "Either a public source pinned to a revision ('<url>@<sha>'), or an opaque token ('opaque:<id>' / 'ENC1:<payload>') when source-confidentiality keeps the source name out of the tracked tree. A bare URL with no revision is rejected — an unpinned reference cannot be re-verified."
+    },
+    "evidence_locator": {
+      "type": "string",
+      "minLength": 3,
+      "description": "Where inside the source the claim was read — a file:line, a section anchor, or an equivalent locator. Free-form because sources differ, but never empty: a claim whose evidence cannot be located again is not a citation."
+    },
+    "harvested_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO-8601 date (YYYY-MM-DD) the harvest landed."
+    },
+    "verdict": {
+      "type": "string",
+      "enum": ["adopt", "adapt"],
+      "description": "How the mechanism entered this repo. Only adopt and adapt produce a row — a rejected, already-present, or unclear finding is recorded in the analysis document, never in the ledger, because nothing in the tree cites it."
+    }
+  }
+}

package/src/scripts/sweep_dead_scan_roots.ts

@@ -148,6 +148,36 @@ export function classify(rel: string): TriageClass {
     return 'C';
 }
 
+/**
+ * Non-gate scripts eligible for the Class-A advisory pass.
+ *
+ * WHY A SECOND POPULATION EXISTS AT ALL. The gate population above is
+ * deliberately shared with the ratchet and the registration test, because three
+ * sites once carried their own regex and disagreed. That sharing is worth
+ * keeping — but it means the sweep's reach is a FILENAME PREFIX, and a script
+ * reading a retired container is dead whether or not its name starts with one
+ * of five words. Measured: `run_skill_evals.ts` roots its `SKILLS_ROOT` at the
+ * skills subtree of the container ADR-051 retired (see `CLASS_A_RETIRED`), and
+ * every subcommand fails in `_skill_dir()` before doing any work — while its
+ * sibling `skill_trigger_eval.ts`, same retired root and a `skill_` prefix, is
+ * reported. One visible, one not, on the prefix alone.
+ *
+ * So this pass widens the READING, never the shared population: it is
+ * Class-A-only (a closed set of retired containers, needing no allowlist to stay
+ * honest), it is advisory, and it feeds neither the ratchet count nor the exit
+ * code. Widening `matchesGatePattern` instead would move the ratchet base for a
+ * reason unrelated to any gate.
+ */
+export function isNonGateScript(filename: string): boolean {
+    if (!filename.endsWith('.ts')) return false;
+    if (filename.endsWith('.d.ts') || filename.endsWith('.test.ts')) return false;
+    // This file declares the retired containers as a classification table
+    // (`CLASS_A_RETIRED`); reading its own constant back as a dead root is a
+    // self-report, not a finding.
+    if (filename === 'sweep_dead_scan_roots.ts') return false;
+    return !isGateFile(filename);
+}
+
 export interface Finding {
     rel: string;
     names: string;
@@ -827,6 +857,20 @@ export function main(argv: string[]): number {
         if (r.confirmed.length || r.unproven.length) results.set(f, r);
     }
 
+    // Class-A advisory over the scripts the shared gate population cannot reach.
+    // Reuses the same extractor, so a prose mention or a report string is not a
+    // finding — only a literal join over a recognised root base is.
+    const advisory: string[] = [];
+    const advisoryPop = fs.existsSync(args.scripts)
+        ? fs.readdirSync(args.scripts).filter(isNonGateScript).sort()
+        : [];
+    for (const f of advisoryPop) {
+        const r = analyze(fs.readFileSync(path.join(args.scripts, f), 'utf-8'), repoRoot);
+        for (const h of [...r.confirmed, ...r.unproven]) {
+            if (classify(h.rel) === 'A') advisory.push(`  advisory  [A] ${f}: ${h.rel} (${h.names})`);
+        }
+    }
+
     const used = new Set<Disposition>();
     const disposed = (script: string, rel: string): Disposition | undefined => {
         const hit = ledger.find((l) => l.script === script && l.rel === rel);
@@ -899,6 +943,13 @@ export function main(argv: string[]): number {
     if (!args.quiet) {
         process.stdout.write(`sweep_dead_scan_roots: ${pop.length} gate script(s) scanned\n`);
         for (const l of lines) process.stdout.write(`${l}\n`);
+        if (advisory.length) {
+            process.stdout.write(
+                `sweep_dead_scan_roots: ${advisoryPop.length} non-gate script(s) scanned ` +
+                    '(Class-A advisory — not counted, not gated)\n',
+            );
+            for (const l of advisory) process.stdout.write(`${l}\n`);
+        }
     }
 
     if (stale.length) {

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. */