@event4u/agent-config 14.5.0 → 14.7.0

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

@@ -0,0 +1,78 @@
+/**
+ * report_layer_overlap — print what writing the project layer costs, if anything.
+ *
+ * Runs as its own step of `task generate-tools` rather than as a call inside
+ * `condense.ts`, and the reason is a gate rather than taste: `condense.ts` is
+ * already over `check_source_size_budget`'s 1500-line ceiling, and that ratchet is
+ * shrink-only — an import plus a call there is +2 lines it refuses, and re-pinning
+ * the baseline is named a defect in the gate's own message. So the notice lives
+ * beside the task it belongs to.
+ *
+ * WHY THE NOTICE EXISTS. `generate-tools` writes ONE of the two layers Claude Code
+ * loads and was silent about the other existing, while the installer's overlap gate
+ * runs at install time and cannot see a layer written afterwards. The overlap is
+ * therefore created by whichever producer runs LAST, and neither said so.
+ *
+ * ADVISORY BY CONSTRUCTION: always exits 0. The build must not fail on a topology
+ * the operator may not be able to change today — that would make the build unusable
+ * rather than the duplication visible. The check that can refuse is
+ * `check_single_delivery --enforce`. Invariant: ADR-236.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+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), '..', '..');
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let projectRoot = REPO_ROOT;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === '--project') {
+            const v = args[i + 1];
+            if (v === undefined || v.startsWith('-')) {
+                process.stderr.write('report_layer_overlap: --project needs a directory\n');
+                return 1;
+            }
+            projectRoot = path.resolve(v);
+            i += 1;
+        } else if (a === '--help' || a === '-h') {
+            process.stdout.write('usage: report_layer_overlap [--project DIR]\n');
+            return 0;
+        } else if (a !== undefined) {
+            // Unrecognised arguments are an error even here, where the exit code is
+            // otherwise always 0: a silently ignored typo in a build step is how a
+            // notice stops firing without anyone noticing.
+            process.stderr.write(`report_layer_overlap: unexpected argument ${a}\n`);
+            return 1;
+        }
+    }
+    warnLayerOverlap(projectRoot, (m) => process.stdout.write(`${m}\n`));
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}