@event4u/agent-config 14.6.0 → 14.7.0

package/src/scripts/lint_framework_leakage_allowlist.json

@@ -88,9 +88,9 @@
       "reason": "Quoted anti-example ('❌ Describing how Laravel middleware works') — the line teaches what NOT to write."
     },
     {
-      "file": "src/skills/skill-writing/SKILL.md",
+      "file": "src/skills/skill-writing/references/procedure.md",
       "anchor": "Use when creating Laravel middleware for request filtering",
-      "reason": "Quoted description examples + the 'too-broad skill (Laravel skill)' anti-pattern — meta content."
+      "reason": "Quoted description examples + the 'too-broad skill (Laravel skill)' anti-pattern — meta content. Repointed 2026-08-20: the K6 router-head retrofit moved the quoted description examples out of the head into references/procedure.md, so the anchor no longer matched its file and the entry exempted nothing. The content is unchanged and still meta."
     },
     {
       "file": "src/skills/supply-chain-intake/SKILL.md",

package/src/scripts/lint_plan_risk_register.ts

@@ -39,6 +39,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { isAcceptanceCriteriaHeading } from './_lib/ac_heading.js';
 import { workspaceIdentity } from './_lib/git_common_dir.js';
 import { gitEnv } from './_lib/git_env.js';
 import { splitMarkdownRow } from './_lib/md_table.js';
@@ -52,7 +53,7 @@ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
  */
 export const RISK_REGISTER_GATE_ACTIVATION = '2026-08-04';
 
-const MARKER_RE =
+export const MARKER_RE =
     /^<!--\s*risk-review:\s*v1\s*\|\s*reviewed:\s*(\d{4}-\d{2}-\d{2})\s*\|\s*reviewer:\s*(.+?)\s*-->\s*$/;
 const HONEST_NULL_RE = /^\*\*Honest-null:\*\*(.*)$/;
 const CHECKBOX_RE = /^\s*- \[( |x|~|-)\]/;
@@ -72,7 +73,7 @@ export interface PlanFeatures {
     phaseHeadings: string[];
     /** Total count of deliverable checkbox lines (state-insensitive). */
     checkboxCount: number;
-    /** sha256 of the `## Acceptance Criteria` section body (checkbox state normalized). */
+    /** sha256 of the acceptance-criteria section body (heading matched per `_lib/ac_heading`; checkbox state normalized). */
     acHash: string;
 }
 
@@ -115,7 +116,7 @@ export function extractFeatures(text: string): PlanFeatures {
         if (CHECKBOX_RE.test(entry.line)) {
             checkboxCount += 1;
         }
-        if (/^##\s+Acceptance Criteria\s*$/.test(entry.line)) {
+        if (isAcceptanceCriteriaHeading(entry.line)) {
             acStart = i;
         }
     }

package/src/scripts/lint_skill_router_head.ts

@@ -59,10 +59,10 @@ export const MODE_BODY_DIRS: readonly string[] = ['tasks', 'references'];
  * Measured, not guessed. REMOVE entries as skills are restructured; never add.
  */
 export const GRANDFATHERED: readonly string[] = [
-    'ai-council',          // 1055
-    'skill-writing',       //  767
-    'roadmap-management',  //  552
-    'quality-tools',       //  445
+    // Emptied 2026-08-20: all four seeded entries were restructured into router
+    // heads (entry head + `references/` mode bodies) under the published K6 cap.
+    // Shrink-only means this list may never grow again — a new oversized
+    // monolith fails the gate instead of joining it.
 ];
 
 export interface Finding {

package/src/scripts/mcp_server/tools.ts

@@ -669,7 +669,7 @@ async function _roadmapProgressHandler(
         };
     }
     const roadmaps = urp.collect(roadmapRoot);
-    const content = urp.render(roadmaps, urp.collect_bundles(root));
+    const content = urp.render(roadmaps, urp.collect_bundles(root), roadmapRoot);
     const stepsDone = roadmaps.reduce((s, r) => s + r.done, 0);
     const stepsTotal = roadmaps.reduce((s, r) => s + r.total_active, 0);
     if (!dryRun) {
@@ -719,7 +719,7 @@ async function _roadmapArchiveHandler(
             const roadmaps = urp.collect(roadmapRoot);
             fs.writeFileSync(
                 path.join(root, 'agents', 'roadmaps-progress.md'),
-                urp.render(roadmaps, urp.collect_bundles(root)),
+                urp.render(roadmaps, urp.collect_bundles(root), roadmapRoot),
                 'utf-8',
             );
             dashboardRegenerated = true;

package/src/scripts/new_roadmap.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env tsx
+/**
+ * Emit a roadmap skeleton that passes every roadmap gate unedited.
+ *
+ * WHY THIS EXISTS. Four authoring conventions are enforced by four different
+ * gates and documented in prose an author has to already know to look for:
+ *
+ *   1. `complexity:` is a two-value enum — `lightweight` | `structural`.
+ *      Measured 2026-08-20 across 88 roadmaps: six DIFFERENT invented values
+ *      were in the tree (`bounded`, `medium`, `moderate`, `small`, `standard`),
+ *      one of them on the active side and reddening the trunk, seven more in
+ *      `later/` where the gate does not scan and which would red on the day
+ *      they are reactivated.
+ *   2. The acceptance heading is matched CASE-INSENSITIVELY and without an end
+ *      anchor — one predicate, `_lib/ac_heading.ts`, shared by the R1 gate and
+ *      the R2 dispatcher. It was not always: an end-anchored, case-sensitive
+ *      copy made 10 of 22 roadmaps writing `Acceptance criteria` invisible to
+ *      the extractor, and a third copy in `lint_plan_risk_register` kept both
+ *      faults until 2026-08-20, hashing the empty string for 8 of the 32 ready
+ *      roadmaps while the gate exited 0. The skeleton still emits the
+ *      capitalised form: it is the shape every reader already recognises, and
+ *      nothing now depends on the case.
+ *   3. The Risk Register needs its `<!-- risk-review: … -->` marker as the
+ *      first non-blank line of the section.
+ *   4. `Risk type` is a two-value enum — `product` | `implementation`. The
+ *      natural third word (`process`) hard-fails at pre-push.
+ *
+ * Every one of those is cheap to satisfy up front and costs a full gate round
+ * to discover. This command satisfies them by construction.
+ *
+ * The skeleton is deliberately MINIMAL: one phase, one step, one risk row. It
+ * is a starting point that is green, not a template to fill in blindly — the
+ * content is the author's, the shape is not worth rediscovering.
+ *
+ * Usage:  ./scripts-run src/scripts/new_roadmap <slug> [--structural] [--stdout]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Today, as the risk-review marker wants it. */
+function today(): string {
+    return new Date().toISOString().slice(0, 10);
+}
+
+/** `road to X` from a kebab slug, for the H1. */
+function titleOf(slug: string): string {
+    return slug.replace(/-/g, ' ');
+}
+
+export function skeleton(slug: string, complexity: 'lightweight' | 'structural', date: string): string {
+    return `---
+complexity: ${complexity}
+status: draft
+execution:
+  mode: phase-checkpoints
+---
+# Road to ${titleOf(slug)}
+
+> **Source:** replace this with where the finding came from — a measurement, a
+> review, an incident. A roadmap whose origin is not stated cannot be checked
+> against it later.
+
+## Goal
+
+One paragraph: what is true when this is finished, phrased so someone else
+could tell whether it happened.
+
+## Phase 1 — <name the first coherent slice>
+
+- [ ] **1.1 <the step, as an imperative>.** What changes, and why it is not
+      already the case.
+      verify: the check that proves it — a command, a test, an observable
+      state. Never "looks right".
+
+## Risk Register
+<!-- risk-review: v1 | reviewed: ${date} | reviewer: claude/host -->
+
+| Rank | Item | Risk type | Description | Mitigation | Anchored under |
+|------|------|-----------|-------------|------------|----------------|
+| 1 | <the way this roadmap most plausibly fails> | implementation | What goes wrong, concretely | What makes it not happen, or what catches it | Phase 1 — <name the first coherent slice> |
+
+## Acceptance Criteria
+
+- [ ] AC-1 — <the residual state, not the activity>. Phrase it on what is true
+      afterwards, so a step that ran but achieved nothing cannot satisfy it.
+`;
+}
+
+function main(argv: readonly string[]): number {
+    const args = argv.filter((a) => !a.startsWith('--'));
+    const structural = argv.includes('--structural');
+    const toStdout = argv.includes('--stdout');
+    const slug = args[0];
+
+    if (slug === undefined || slug.length === 0) {
+        process.stderr.write(
+            'usage: new_roadmap <slug> [--structural] [--stdout]\n' +
+                '  <slug>        kebab-case, without the road-to- prefix\n' +
+                '  --structural  tag structural instead of lightweight (no line/phase cap)\n' +
+                '  --stdout      print instead of writing the file\n',
+        );
+        return 2;
+    }
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+        process.stderr.write(`new_roadmap: slug must be kebab-case, got '${slug}'\n`);
+        return 2;
+    }
+
+    const body = skeleton(slug, structural ? 'structural' : 'lightweight', today());
+    if (toStdout) {
+        process.stdout.write(body);
+        return 0;
+    }
+
+    const rel = path.join('agents', 'roadmaps', `road-to-${slug}.md`);
+    if (fs.existsSync(rel)) {
+        process.stderr.write(`new_roadmap: ${rel} already exists — refusing to overwrite\n`);
+        return 1;
+    }
+    fs.mkdirSync(path.dirname(rel), { recursive: true });
+    fs.writeFileSync(rel, body, 'utf-8');
+    process.stdout.write(
+        `✅  wrote ${rel}\n` +
+            '    It passes the roadmap gates as emitted. Adding a `### blocker:` entry or\n' +
+            '    flipping status to `ready` grows the estate — check_estate_count wants the\n' +
+            '    baseline raised with a reason in the same commit.\n',
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url.endsWith(path.basename(process.argv[1]))) {
+    process.exitCode = main(process.argv.slice(2));
+}
+
+export { main, titleOf, today };

package/src/scripts/pack_mcp_content.ts

@@ -41,11 +41,26 @@ import { scan_contexts, scan_guidelines, scan_rules } from './mcp_server/resourc
 
 const SCHEMA_VERSION = 1;
 const PACKER_VERSION = '1.0.0';
-// Worker bundle is the compact JSON; gzipped copy lives in R2. Cloudflare's
-// condensed-bundle limit is 3 MB (free) / 10 MB (paid); 778 KB gz today
-// (438 entries) leaves ample headroom. Hard-fail at 5 MB uncondensed so
-// the build dies before the Worker upload does.
-const MAX_UNCONDENSED_BYTES = 5 * 1024 * 1024;
+// Worker bundle is the compact JSON; gzipped copy lives in R2. This constant is
+// a PROXY for Cloudflare's condensed-bundle limit (3 MB free / 10 MB paid) — it
+// hard-fails early so the build dies before the Worker upload does. Because it is
+// a proxy, the number that matters is the gz one, and both are restated here as
+// MEASURED values rather than remembered ones.
+//
+// Measured 2026-08-20 on origin/main (770 entries): uncondensed 5,230,537 B,
+// gz 1,793,879 B. So the real constraint sits at 57 % of the free tier with
+// ~1.2 MB of room, while the old 5 MiB proxy had 12,343 B of headroom — a 0.24 %
+// margin on trunk, which made ANY addition above ~12 KB to rules, guidelines or
+// contexts fail here regardless of merit. Raised to 6 MiB, deliberately well
+// above the measurement: a cap pinned just over the current figure reds on the
+// next commit and teaches people to raise it again.
+//
+// The prior comment claimed "778 KB gz today (438 entries)". That was stale by
+// 2.3x on size and 332 entries — the reason the proxy drifted into a blocker
+// without anyone noticing was that its own justification was never re-measured.
+// If this needs raising again, re-measure BOTH numbers and replace them here;
+// the gz figure against 3 MB is the one that decides whether there is a problem.
+const MAX_UNCONDENSED_BYTES = 6 * 1024 * 1024;
 
 /** Sentinel for the early-exit paths (`raise SystemExit(n)` in Python). */
 class SystemExit extends Error {

package/src/scripts/release.ts

@@ -2475,55 +2475,54 @@ export function nothing_to_release_ci(
 
 const _RELEASE_BRANCH_RE = /^release\/(\d+\.\d+\.\d+)$/;
 
+/** `package.json`'s `version`, or null when unreadable, not JSON, or key-less. */
+function _package_version_or_null(): string | null {
+    try {
+        const data = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf-8')) as Record<string, unknown>;
+        return 'version' in data ? (data['version'] as string) : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Observations `_detect_in_flight_target` reads; injected by its tests. */
+export interface InFlightProbes {
+    head_branch?: () => string;
+    package_version?: () => string | null;
+    /** True when the tag is ON THE REMOTE — never merely local. */
+    tag_published?: (tag: string) => boolean;
+}
+
 /**
- * Find the in-flight release target — the SOURCE OF TRUTH is package.json.
- *
- * An "in-flight" release is one whose version was already bumped into `main`'s
- * `package.json` (and possibly merged) but whose tag has not yet been pushed —
- * i.e. the publish step never completed. The canonical anchor is therefore
- * `package.json` version `V` **with no matching tag `V`**, NOT the set of
- * `release/X.Y.Z` branches.
- *
- * Why not the branch set: merged release branches are frequently left
- * undeleted on the remote, so "highest existing release/* branch" can resolve
- * to an OLD, already-published version (e.g. picking 5.4.0 while 5.8.0 is the
- * real in-flight target) and tag a downgrade. The package.json version cannot
- * lie that way — it is the version main currently claims to be, and an
- * untagged claim is exactly an incomplete release.
- *
- * Resolution order:
- *   1. If HEAD is on a `release/X.Y.Z` branch, that explicit checkout wins.
- *   2. Else: read `package.json` version `V`. If tag `V` does not exist
- *      (local or remote), `V` is the in-flight target. If it is already
- *      tagged, the release is complete → return null (regular bump path).
- *
- * Stale `release/*` branches are never used for version detection.
+ * In-flight release target: `package.json` claims `V` while no PUBLISHED tag
+ * `V` exists, so the publish step never completed. HEAD on `release/X.Y.Z`
+ * wins first; stale `release/*` branches are never consulted (a merged one
+ * left undeleted can tag a downgrade). PUBLISHED means on the REMOTE, because
+ * publish-npm.yml triggers on `push: tags:`. Why not a local tag, and the
+ * 14.6.0 release that stranded on the old form: see
+ * `tests/scripts/release.test.ts` § _detect_in_flight_target.
  */
-function _detect_in_flight_target(): string | null {
-    const head = git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true });
-    const m = _RELEASE_BRANCH_RE.exec(head);
+function _detect_in_flight_target(probes: InFlightProbes = {}): string | null {
+    const head_branch =
+        probes.head_branch ?? (() => git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }));
+    const package_version = probes.package_version ?? _package_version_or_null;
+    const tag_published = probes.tag_published ?? _tag_exists_remote;
+
+    const m = _RELEASE_BRANCH_RE.exec(head_branch());
     if (m) {
         return m[1] as string;
     }
-
-    let version: string;
-    try {
-        const data = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf-8')) as Record<string, unknown>;
-        if (!('version' in data)) {
-            return null; // KeyError analogue.
-        }
-        version = data['version'] as string;
-    } catch {
-        return null; // OSError / JSONDecodeError analogue.
+    const version = package_version();
+    if (version === null) {
+        return null;
     }
     try {
         parse_version(version);
     } catch {
         return null;
     }
-
-    // An already-tagged version is a completed release, not in-flight.
-    if (_tag_exists_local(version) || _tag_exists_remote(version)) {
+    // A PUBLISHED tag is a completed release; a local-only tag is not.
+    if (tag_published(version)) {
         return null;
     }
     return version;

package/src/scripts/report_layer_overlap.ts

@@ -26,6 +26,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { warnLayerOverlap } from './_lib/layer_overlap_notice.js';
 
+// ledger-exempt: this is a REPORTER, not a gate — it always exits 0 by construction
+// (see the docstring above), so there is no verdict for a per-target ledger to
+// account for. `_lib/gate_ledger` records why a gate passed over a target; a script
+// that cannot fail passes over nothing. The advisory-only property is asserted by the
+// task step that calls it, not by this marker.
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 

package/src/scripts/self_repair_hook.ts

@@ -38,6 +38,7 @@ import {
 } from './_lib/self_repair.js';
 import { openRecords, upsertFinding } from './_lib/self_repair_store.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
+import { emitDefectShadow } from './hooks/telemetry_self_repair.js';
 
 const EXIT_ALLOW = 0;
 
@@ -130,11 +131,28 @@ export function readTurn(transcriptPath: string, pinned: 'de' | 'en' | null): Tu
     return { prompt, reply, toolCommands, pinnedLanguage: pinned };
 }
 
-/** The queue line injected at prompt time when records are waiting. */
-export function buildQueueLine(count: number, newest: string): string {
+/**
+ * The queue line injected at prompt time when records are waiting.
+ *
+ * `occurrences` is the newest record's own repeat counter, and it is in the line
+ * because the store has always counted while the model never saw the number: a
+ * recurring defect increments one record instead of adding a queue entry, so
+ * `count` stays flat and the recurrence is invisible. Above 1 it is the only
+ * deterministic "this came back" signal an agent gets, which is what makes
+ * `decision-revisit-gate` § Recurrence executable rather than aspirational.
+ * Omitted at 1 — a first sighting has nothing to say.
+ */
+export function buildQueueLine(count: number, newest: string, occurrences = 1): string {
+    const repeat =
+        occurrences > 1
+            ? ` The newest record has recurred ${occurrences} time(s): the earlier ` +
+              `disposition did not hold, so per decision-revisit-gate § Recurrence ` +
+              `reopen it and name which assumption broke — resolve on evidence, ` +
+              `never on the repetition count.`
+            : '';
     return (
         `<self-repair-queue>${count} open agent-config defect record(s) ` +
-        `(newest: ${newest}). These are defects in the AGENT CONFIG, not in this ` +
+        `(newest: ${newest}).${repeat} These are defects in the AGENT CONFIG, not in this ` +
         `project. Per the self-repair rule: analyse the newest record, author the ` +
         `fix against agent-config, and prepare the release — the outward step ` +
         `(push + PR, or an issue) still needs the user's word this turn. ` +
@@ -185,7 +203,17 @@ export function main(): number {
 
     for (const f of findings) {
         try {
-            upsertFinding(root, f, now);
+            const rec = upsertFinding(root, f, now);
+            // The Class-A shadow (road-to-org-telemetry Phase 5, step 5.1).
+            // Structural fields only — the record type has no member able to
+            // hold `f.evidence` or `f.suggested_surface`, which are the
+            // Class-B payload and ship only on per-case approval. Inert unless
+            // the org pack activated telemetry; a refused record (`null` from
+            // the creation cap) emits nothing, because there is no queued
+            // defect to shadow.
+            if (rec !== null) {
+                emitDefectShadow(root, rec, env);
+            }
         } catch {
             // an unwritable store must never cost the user their turn
         }
@@ -208,7 +236,11 @@ export function main(): number {
         `${JSON.stringify({
             decision: 'allow',
             reason: `self-repair: ${open.length} open record(s)`,
-            context: buildQueueLine(open.length, open[0]!.defect_class),
+            context: buildQueueLine(
+                open.length,
+                open[0]!.defect_class,
+                open[0]!.occurrences,
+            ),
         })}\n`,
     );
     return EXIT_ALLOW;

package/src/scripts/session_register_hook.ts

@@ -715,6 +715,17 @@ export function foreign_sessions_block(
                 '',
                 `COLLISION: another live session is on branch \`${here}\` in THIS SAME worktree`,
                 `(${branch_hit.record.worktree}) — the same files and the same git index.`,
+                'What "join anyway" actually costs, because option 1 is chosen routinely and',
+                'the price was not in this text until 2026-08-20 (road-to-session-closeout 6.3):',
+                '  · SHARED INDEX — `git add -A` stages the peer\'s work too. Measured: a peer',
+                '    session\'s untracked roadmap was swept into an unrelated merge commit and',
+                '    surfaced three commits later at an estate gate. Use pathspecs, never -A.',
+                '  · SHARED STASH STACK — `git stash` is repo-wide, so your stash is visible and',
+                '    poppable by the peer, and `stash@{0}` means a different thing to each of you.',
+                '  · PRE-PUSH runs over the shared tree — it sees the peer\'s files, not only',
+                '    yours. `task consistency` is now scoped to the paths it regenerates, so a',
+                '    peer\'s unrelated edit no longer fails it; anything else in that hook still',
+                '    reads one tree written by two sessions.',
                 'Ask the user ONCE PER SESSION, as numbered options, before writing anything:',
                 '  1. Join anyway and coordinate manually (this register is advisory, not a lock)',
                 '  2. Spawn a separate worktree for this session',

package/src/scripts/skill_usage_collect.ts

@@ -31,7 +31,17 @@ const _HERE = fileURLToPath(import.meta.url);
 
 // src/scripts/skill_usage_collect.ts → parents[2] of the .py file is repo root.
 export const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const OUT = path.join(REPO, 'agents', 'metrics', 'skill-usage.jsonl');
+// `agents/metrics/` was retired by the agents/ taxonomy consolidation (the
+// same finding `skill_overlap.ts` records), so this collector was appending to
+// a directory that does not exist while the real record set sat untouched at
+// `agents/runtime/metrics/skill-usage.jsonl` — last written 2026-05-16. The
+// report script read the same dead path, so the pair agreed with each other
+// and with nothing else. road-to-org-telemetry Phase 0 measured the
+// consequence (spike 3: 0 of 89 invocations detected on the set the collector
+// reads) and named the repair a Phase 4 prerequisite. `runtime/` is the typed,
+// gitignored home for a record set nothing tracks, per the agents/ layout
+// contract.
+const OUT = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage.jsonl');
 
 // LISTING_LINE_RE = re.compile(r"^-\s+([a-z0-9][a-z0-9_-]+):\s", re.MULTILINE)
 const LISTING_LINE_RE = /^-\s+([a-z0-9][a-z0-9_-]+):\s/gm;