@event4u/agent-config 10.2.0 → 10.4.0

package/src/scripts/report_consultation_rate.ts

@@ -48,6 +48,7 @@ import { fileURLToPath } from 'node:url';
 
 import { projectStoreSlug } from './_lib/cc_transcript.js';
 import {
+    isArtifactRead,
     isConsultation,
     isUiWrite,
     type ToolEvent,
@@ -81,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 {
@@ -96,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;
 }
 
 /**
@@ -139,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 }> = [];
@@ -151,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}/`)) {
@@ -166,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;
@@ -216,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
@@ -255,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;
 }
@@ -285,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/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/tests/fixtures/hooks/subagent_start.json

@@ -0,0 +1,7 @@
+{
+  "session_id": "fixture-subagent-start-001",
+  "agent_id": "fixture-agent-0001",
+  "agent_type": "Explore",
+  "cwd": "/workspace",
+  "platform_hint": "claude"
+}

package/tests/fixtures/hooks/subagent_stop.json

@@ -0,0 +1,8 @@
+{
+  "session_id": "fixture-subagent-stop-001",
+  "agent_id": "fixture-agent-0001",
+  "agent_type": "Explore",
+  "last_assistant_message": "{\"summary\":\"fixture envelope\",\"handoff\":\"none\",\"confidence\":\"high\",\"findings\":[],\"risks\":[]}",
+  "cwd": "/workspace",
+  "platform_hint": "claude"
+}