@event4u/agent-config 14.6.0 → 14.8.0

package/dist/agent-src/templates/roadmaps.md

@@ -4,6 +4,25 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
 
 ---
 
+## Start from the skeleton, not from this page
+
+```bash
+./scripts-run src/scripts/new_roadmap <slug>            # lightweight
+./scripts-run src/scripts/new_roadmap <slug> --structural
+./scripts-run src/scripts/new_roadmap <slug> --stdout   # print, do not write
+```
+
+It emits a file that passes every roadmap gate **unedited** — the complexity
+enum, the acceptance heading in the exact form the extractor matches, the
+risk-review marker, a legal risk type, and an anchor that resolves. Those four
+conventions live in four different gates, and each one costs a full gate round
+to discover by failing it. Measured 2026-08-20 across 88 roadmaps: **six
+different invented `complexity:` values** were in the tree, and **10 of 22**
+roadmaps wrote an acceptance heading the extractor cannot see.
+
+The rules below still govern the content. The skeleton only removes the part
+that was never a judgement call.
+
 ## Rules for Roadmaps
 
 1. **Be precise and concise.** Lightweight default: ≤ 600 lines (see rule 15). Only a declared `complexity: structural` roadmap may exceed that, capped at 1000 lines — if larger, split into multiple files.
@@ -89,8 +108,8 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     - `interactive` — every gate fires as authored by its owning rule.
       **Not what an absent field means.** When the field is absent the mode is
       DERIVED from the invocation form (`roadmap-process-loop § 3a`):
-      `process-full` and `/roadmap:next` derive `autonomous`, `process-phase`
-      derives `phase-checkpoints`, `process-step` runs without a contract. The
+      `process-full` derives `autonomous`; `/roadmap:next` and `process-phase`
+      derive `phase-checkpoints`; `process-step` runs without a contract. The
       contract screen is still shown once and still carries "run interactive
       instead", so declaring nothing costs a keystroke, never control.
     - `phase-checkpoints` — the run halts at each phase boundary with a
@@ -110,6 +129,24 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     lint. Follow-up roadmaps (rule 17) inherit the parent's mode as the
     *suggested* option during creation but the question is always asked
     again.
+
+    **Companion field, same block — `depends:`.** Optional, and only
+    meaningful for a set run:
+
+    ```yaml
+    depends: [road-to-other-thing]   # slugs, not paths
+    ```
+
+    A declared edge is authoritative and is never overridden by the
+    file-overlap heuristic the set contract also computes
+    ([`roadmap-process-loop § 3d`](../contexts/execution/roadmap-process-loop.md)).
+    The union of declared and inferred edges feeds exactly two decisions —
+    the order members run in, and whether two members may share a lane —
+    and nothing else. Declaring an edge that is not real costs serial
+    execution; missing a real one costs a collision, so the heuristic
+    resolves toward serial and a declaration is the cheap way to be right.
+    Absent means no declared dependency, never “independent”: the overlap
+    heuristic still runs.
 19. **Source-derived roadmaps carry a gap-table + provenance; internally
     originated roadmaps carry neither.** This rule fires **only** when a
     roadmap originates from an external input (a suggestion, a competitive
@@ -203,16 +240,40 @@ Templates for roadmap files stored in `agents/roadmaps/` or `{module_root}/{Modu
     | `0` | auto-run — deterministic, free, reversible | the agent runs `Run:`; the output IS the unblock |
     | `1` | budget-preauthorized — billable but reversible | the agent runs `Run:` under a standing budget and logs a receipt |
     | `2` | consent-once — a real preference call, reversible | one line with the recommendation and a default |
-    | `3` | human-only — irreversible, legal, or Hard Floor | unchanged: the human IS the content |
+    | `3` | human-only — the human IS the content: externally impossible for the agent, or an explicitly excluded action | a person, because nobody else can |
+
+    **CAPABILITY BEFORE ROLE (ADR-237).** `3` means *a human is the
+    content of this gate*, never *a human usually does this*. Before
+    authoring `3`, ask one question: **can the agent execute this at all**
+    — through the filesystem, git, `gh`, an API, a CLI, a tool, a model, a
+    council? If yes, it is **not** class 3, whoever conventionally
+    performs it. A branch to create, a push, a PR to open, a repository or
+    branch setting the agent can change, a workflow to start, CI to
+    re-run, a merge base to update, conflicts, failing tests, local
+    configuration, a paid call inside the run's budget — all of these are
+    **work**, and authoring `3` on any of them is a defect a
+    `process-full` run repairs rather than obeys.
+
+    What legitimately remains `3`: a credential that does not exist and
+    the agent cannot create · a purchase beyond the delegated budget ·
+    physical hardware access · another person or organisation must act · a
+    wait that is factually mandatory and cannot be simulated or verified ·
+    an action on the Hard Floor's EXCLUDED list (production-trunk merge,
+    deploy, prod data / secrets / IAM / DNS, an irreversible external
+    action).
 
     Three properties are load-bearing. **`Class:` is optional and its
     absence means 3**, so nothing becomes executable because an author
-    forgot a field. **A class-0 or class-1 entry MUST carry `Run:`** —
+    forgot a field — but an absent class is a *default*, not a finding,
+    and the capability question above still decides whether the step is
+    really blocked. **A class-0 or class-1 entry MUST carry `Run:`** —
     `lint_roadmap_blockers` fails otherwise, because a gate that claims
     to be runnable without naming the command reads as actionable and is
     not. And **class is authored, never inferred**: promoting a gate is
     a reviewed edit, which is what keeps a Hard-Floor gate
     (`non-destructive-by-default`) out of reach of a runtime judgment.
+    Repairing a `3` that fails the capability test is such an edit — it is
+    recorded at the blocker with the reason, not applied silently.
 
     Only the leading token of `Class:` is read, so
     `- **Class:** 1 — budget-preauthorized` is valid; the taxonomy name

package/dist/agent-src/templates/scripts/telemetry/flush_sender.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * The detached Class-A sender (road-to-org-telemetry Phase 2, step 2.1).
+ *
+ * Spawned by `spawn_detached_sender` and never by a human. It is the ONLY
+ * code in this tree that makes an outbound telemetry call, which is why it is
+ * one small file with no imports beyond node builtins: the egress surface
+ * should be readable end to end in one screen by anyone auditing what leaves
+ * a machine.
+ *
+ * PLAIN JS, DELIBERATELY. Its siblings here are TypeScript resolved by `tsx`
+ * at import time. A detached child inherits no such resolution, so a `.ts`
+ * sender would depend on finding a `tsx` binary in a consumer install at
+ * session teardown. `process.execPath` — plain node — exists by construction.
+ * The cost of that choice is that this file cannot import the sibling
+ * modules, so the drain algorithm lives HERE and nowhere else; the TypeScript
+ * side owns enqueue and spawn only, and there is no second copy to drift.
+ *
+ * CLAIM-BY-RENAME, NOT READ-THEN-TRUNCATE. `rename` is atomic within a
+ * filesystem, so a session that appends a record while this process is
+ * sending writes to a fresh spool rather than into bytes about to be deleted.
+ * Read-then-truncate loses exactly those records, silently, and only under
+ * concurrency — the failure shape that never shows up in a single-session
+ * test.
+ *
+ * FAILURE KEEPS THE DATA. A non-2xx, a timeout, a DNS failure, a thrown
+ * anything: the claimed lines go back in front of the spool and the next
+ * session's flush tries again. "Local retention for the next flush" is the
+ * step's own wording and this is it. Exit code is always 0 — nothing reads it
+ * (`stdio: 'ignore'`), and a non-zero from a detached child is a log line
+ * nobody will ever see.
+ */
+import * as fs from 'node:fs';
+
+const DEFAULT_TIMEOUT_MS = 1000;
+
+function parse_args(argv) {
+    const out = { spool: '', endpoint: '', timeout_ms: DEFAULT_TIMEOUT_MS };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--spool') {
+            out.spool = argv[i + 1] ?? '';
+            i += 1;
+        } else if (a === '--endpoint') {
+            out.endpoint = argv[i + 1] ?? '';
+            i += 1;
+        } else if (a === '--timeout') {
+            const n = Number.parseInt(argv[i + 1] ?? '', 10);
+            if (Number.isFinite(n) && n > 0) out.timeout_ms = n;
+            i += 1;
+        }
+    }
+    return out;
+}
+
+/**
+ * Take the spool by rename. Returns the claim path, or `null` when there is
+ * nothing to send — including the race where a sibling sender claimed it
+ * first, which is a no-op rather than an error.
+ */
+export function claim_spool(spool_path) {
+    let size = 0;
+    try {
+        size = fs.statSync(spool_path).size;
+    } catch {
+        return null;
+    }
+    if (size === 0) return null;
+    const claim = `${spool_path}.sending.${process.pid}.${Date.now()}`;
+    try {
+        fs.renameSync(spool_path, claim);
+    } catch {
+        return null;
+    }
+    return claim;
+}
+
+/** Put the claimed lines back in FRONT of whatever arrived meanwhile. */
+export function restore_claim(claim_path, spool_path) {
+    try {
+        const claimed = fs.readFileSync(claim_path, 'utf-8');
+        let current = '';
+        try {
+            current = fs.readFileSync(spool_path, 'utf-8');
+        } catch {
+            current = '';
+        }
+        fs.writeFileSync(spool_path, claimed + current, { encoding: 'utf-8' });
+        fs.unlinkSync(claim_path);
+        return true;
+    } catch {
+        // The claim file survives under its own name; the next sender's
+        // `claim_spool` will not see it, so it is recoverable by hand rather
+        // than lost. Better than a partial write over the live spool.
+        return false;
+    }
+}
+
+/**
+ * POST the batch as NDJSON. Returns true only on a 2xx.
+ *
+ * The body is the spooled bytes verbatim — every line is a Class-A record
+ * whose fields are all structural (see `remote.ts`), so there is no
+ * serialisation step here that could introduce a field the record type does
+ * not have.
+ */
+export async function post_batch(endpoint, body, timeout_ms) {
+    try {
+        const res = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-ndjson' },
+            body,
+            signal: AbortSignal.timeout(timeout_ms),
+        });
+        return res.ok === true;
+    } catch {
+        return false;
+    }
+}
+
+export async function run(args) {
+    if (!args.spool || !args.endpoint) return 'no-op';
+    const claim = claim_spool(args.spool);
+    if (claim === null) return 'no-op';
+
+    let body = '';
+    try {
+        body = fs.readFileSync(claim, 'utf-8');
+    } catch {
+        return 'read-failed';
+    }
+    if (body.length === 0) {
+        try {
+            fs.unlinkSync(claim);
+        } catch {
+            /* nothing to clean */
+        }
+        return 'no-op';
+    }
+
+    const ok = await post_batch(args.endpoint, body, args.timeout_ms);
+    if (ok) {
+        try {
+            fs.unlinkSync(claim);
+        } catch {
+            /* sent; a stale claim is harmless */
+        }
+        return 'sent';
+    }
+    restore_claim(claim, args.spool);
+    return 'retained';
+}
+
+const _entry = process.argv[1] ?? '';
+const _invoked_directly = _entry !== '' && import.meta.url === new URL(`file://${_entry}`).href;
+
+if (_invoked_directly) {
+    run(parse_args(process.argv.slice(2)))
+        .then(() => process.exit(0))
+        .catch(() => process.exit(0));
+}
+
+export { parse_args };

package/dist/agent-src/templates/scripts/telemetry/remote.ts

@@ -35,8 +35,14 @@ import { check_id_redaction, py_json_dumps_compact_sorted } from './engagement.j
 
 export const CLASS_A_SCHEMA_VERSION = 1;
 
-/** Usage classes. Phase 5 adds the self-repair class; Phase 1 emits one. */
-export const ALLOWED_RECORD_CLASSES = ['usage'] as const;
+/**
+ * Record classes. `usage` is Phase 1; `self-repair` is Phase 5 step 5.1.
+ *
+ * Both are Class A — structural fields only — and both travel the same log,
+ * spool and transport, discriminated by this field. `skill_usage_report`
+ * filters on it so a defect report can never be counted as an invocation.
+ */
+export const ALLOWED_RECORD_CLASSES = ['usage', 'self-repair'] as const;
 
 /**
  * Discipline-profile values, the knob that actually decides which rule
@@ -279,6 +285,122 @@ export function build_class_a_record(input: BuildClassAInput): ClassARecord {
     };
 }
 
+/**
+ * One Class-A SELF-REPAIR record (Phase 5, step 5.1).
+ *
+ * The shadow of a queued defect: it says a defect of a named class occurred,
+ * on which host, at which package version, under which declared profile, for
+ * which pseudonymous user. It says nothing about WHAT happened.
+ *
+ * A SEPARATE TYPE, NOT A WIDENED `ClassARecord`, AND THAT IS THE WHOLE POINT.
+ * `DefectFinding` carries `evidence` (a quoted span of the offending text) and
+ * `suggested_surface` (a free sentence). Those are the Class-B payload and
+ * they ship only on explicit per-case approval. Adding either to a
+ * telemetry record type — even optionally, even "sanitized" — would give this
+ * type a field capable of holding project content, and the privacy property
+ * this whole surface rests on is that no such field exists. There is then no
+ * scrubber to fail. Keeping the automatic class in its own interface is how
+ * that stays checkable by reading the type instead of auditing every writer.
+ *
+ * WHAT IS DELIBERATELY ABSENT: an enumerated active-rule / active-skill list.
+ * The roadmap Context asks Class A to carry "the active rule and skill
+ * snapshot" so that "this rule was loaded in six of seven reports of this
+ * class" localizes an artefact. No producer for that exists on a hook path:
+ * `match_prompt` needs the compiled router, which nothing in the hook surface
+ * loads today and which is not established as present in a consumer install.
+ * `discipline_profile` is recorded instead — the knob that decides which rule
+ * surfaces load at all — and it is a profile-level snapshot, NOT the
+ * per-artefact attribution key. That attribution claim stays unavailable, and
+ * saying so here is cheaper than a reader inferring it from a field name.
+ */
+export interface ClassADefectRecord {
+    schema_version: number;
+    record_class: string;
+    ts_bucket: string;
+    /** Detector / intake class — a closed vocabulary owned by the caller. */
+    defect_class: string;
+    /** Which intake produced it — also a closed vocabulary. */
+    defect_source: string;
+    /** How many times this fingerprint has been seen. A counter, not content. */
+    occurrences: number;
+    host: string | null;
+    package_version: string | null;
+    discipline_profile: string | null;
+    org_id: string;
+    user_hash: string;
+    session_hash: string | null;
+}
+
+export interface BuildClassADefectInput {
+    defect_class: string;
+    defect_source: string;
+    occurrences: number;
+    host: string | null;
+    org_id: string;
+    salt: string;
+    hostname: string;
+    username: string;
+    session_id: string;
+    package_version?: string | null;
+    discipline_profile?: string | null;
+    now?: Date;
+}
+
+/**
+ * Build one validated Class-A self-repair record. Pure, and throws rather
+ * than returning a partial record — same contract as its usage sibling.
+ *
+ * `defect_class` and `defect_source` go through the same id-redaction floor as
+ * every other id here, so a caller that ever passed a path, an extension or
+ * an over-long free string gets an exception instead of an egress.
+ */
+export function build_class_a_defect_record(
+    input: BuildClassADefectInput,
+): ClassADefectRecord {
+    check_id_redaction('defect_class', input.defect_class);
+    check_id_redaction('defect_source', input.defect_source);
+    check_id_redaction('org_id', input.org_id);
+
+    const host = input.host ?? null;
+    if (host !== null) {
+        check_id_redaction('host', host);
+    }
+
+    const discipline_profile = input.discipline_profile ?? null;
+    if (
+        discipline_profile !== null
+        && !(ALLOWED_DISCIPLINE_PROFILES as readonly string[]).includes(discipline_profile)
+    ) {
+        throw new ClassARecordError(
+            `discipline_profile must be one of ${ALLOWED_DISCIPLINE_PROFILES.join(', ')} or null`,
+        );
+    }
+
+    const package_version = input.package_version ?? null;
+    if (package_version !== null) {
+        check_id_redaction('package_version', package_version);
+    }
+
+    if (!Number.isInteger(input.occurrences) || input.occurrences < 1) {
+        throw new ClassARecordError('occurrences must be a positive integer');
+    }
+
+    return {
+        schema_version: CLASS_A_SCHEMA_VERSION,
+        record_class: 'self-repair',
+        ts_bucket: hour_bucket(input.now ?? new Date()),
+        defect_class: input.defect_class,
+        defect_source: input.defect_source,
+        occurrences: input.occurrences,
+        host,
+        package_version,
+        discipline_profile,
+        org_id: input.org_id,
+        user_hash: derive_user_hash(input.salt, input.hostname, input.username),
+        session_hash: derive_session_hash(input.salt, input.session_id),
+    };
+}
+
 // ── Retention — the growth budget for the local record log ──────────────
 //
 // Phase 1 shipped this file as append-only with no cap and no pruning, and
@@ -544,6 +666,20 @@ export function enforce_retention(
     return { kept: kept_lines.length, dropped_by_age, dropped_by_size };
 }
 
+/** Append one line to one bounded JSONL file. Both targets share it. */
+function _append_and_bound(
+    target: string,
+    payload: string,
+    policy: RetentionPolicy,
+    now: Date,
+): void {
+    fs.mkdirSync(path.dirname(target) || '.', { recursive: true });
+    fs.appendFileSync(target, payload, { encoding: 'utf-8' });
+    if (retention_due(target, policy, now)) {
+        enforce_retention(target, policy, now);
+    }
+}
+
 /**
  * Append one record as a JSONL line, then enforce the retention policy.
  *
@@ -555,17 +691,34 @@ export function enforce_retention(
  * which makes the common append one extra `stat` plus one bounded read. It
  * lives here rather than in a separate sweep because this is the only writer:
  * a policy a caller has to remember to run is a policy that stops running.
+ *
+ * THE SPOOL IS WRITTEN HERE, IN THE SAME CALL (Phase 2, step 2.1). When
+ * `spool_path` is given, the SAME bytes are appended to the outbound spool
+ * under the SAME retention policy, and the session-end flush then only has
+ * to drain a file. The alternative — a flush that works out for itself which
+ * logged records are still unsent — needs a byte watermark into a file that
+ * `enforce_retention` rewrites in place, and a watermark over a compacting
+ * file is a silent-corruption pair: the offset survives the prune, the
+ * records it points at do not. Enqueue-at-write has no watermark to
+ * invalidate and spools each record exactly once, by the only writer.
+ *
+ * The spool inherits the log's growth budget rather than getting its own,
+ * which is what answers Phase 0's unmeasured "queue growth bound across a
+ * multi-day outage": a sink that is down for days cannot push the spool past
+ * `max_bytes`. The cost of that bound is that the oldest UNSENT records are
+ * dropped rather than kept — the same trade the log already makes, stated
+ * here rather than discovered later in a truncated file.
  */
 export function append_class_a_record(
     log_path: string,
-    record: ClassARecord,
+    record: ClassARecord | ClassADefectRecord,
     policy: RetentionPolicy = DEFAULT_RETENTION_POLICY,
     now: Date = new Date(),
+    spool_path: string | null = null,
 ): void {
     const payload = `${py_json_dumps_compact_sorted(record as unknown as Record<string, unknown>)}\n`;
-    fs.mkdirSync(path.dirname(log_path) || '.', { recursive: true });
-    fs.appendFileSync(log_path, payload, { encoding: 'utf-8' });
-    if (retention_due(log_path, policy, now)) {
-        enforce_retention(log_path, policy, now);
+    _append_and_bound(log_path, payload, policy, now);
+    if (spool_path !== null && spool_path !== '') {
+        _append_and_bound(spool_path, payload, policy, now);
     }
 }

package/dist/agent-src/templates/scripts/telemetry/transport.ts

@@ -0,0 +1,169 @@
+/**
+ * Class-A transport — the enqueue half (road-to-org-telemetry Phase 2, step 2.1).
+ *
+ * WHY THIS IS NOT AN INLINE `fetch` AT SESSION END. Phase 0's second spike
+ * pre-registered "added latency at or below one second at p95" for an inline
+ * flush and measured it FAILING: a healthy sink costs 0.4 ms p95 and a
+ * refused connection 0.3 ms, but a BLACKHOLE — a socket that accepts and
+ * never answers, the shape a wedged sink actually takes — costs 1002 ms p95
+ * against a 1000 ms bar, because the timeout IS the cost. The step's own text
+ * defers to that result ("per the second spike's result"), and the result is:
+ * session end ENQUEUES ONLY, a detached sender flushes, and local retention
+ * carries what did not go out. The same spike measured that fallback at
+ * 20.5 ms p95 against the same blackhole — dominated by process spawn — and
+ * that is the number this module must not regress.
+ *
+ * SO THE SPOOL IS WRITTEN BY THE APPENDER, NOT BY THE FLUSH. A session-end
+ * flush that had to work out which records were already sent would need a
+ * byte watermark into the log, and the log is rewritten in place by
+ * `enforce_retention` — a watermark and a compacting file are a
+ * silent-corruption pair (offsets survive the prune; the records they point
+ * at do not). Enqueue-at-write has no watermark to invalidate: a record is
+ * spooled exactly once, by the only writer, in the same call that logs it.
+ *
+ * TWO PROPERTIES PHASE 0 SAID PHASE 2 MUST MEASURE, AND WHERE THEY LANDED.
+ * (1) Does a detached child survive teardown of the session process group —
+ * measured, see `agents/evidence/eval-findings/org-telemetry-p2-transport.md`.
+ * (2) The queue's growth bound across a multi-day outage — answered by
+ * construction here: the spool carries the SAME `RetentionPolicy` as the log,
+ * enforced by the same code, so a sink that is down for days cannot grow it
+ * past `max_bytes`. That bound is a decision to drop the oldest unsent
+ * records rather than to keep all of them, and it is stated rather than left
+ * for an operator to find in a truncated file.
+ *
+ * NO SINK EXISTS YET. `sink-choice` is transferred (a private repository is
+ * the council's preferred architecture, but creating it is an org-admin
+ * action outside this repository), so nothing in this tree can name a real
+ * endpoint. What ships here is the transport an org's own endpoint value
+ * activates; with no endpoint the settings never resolve `active` and not a
+ * byte moves.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    DEFAULT_RETENTION_POLICY,
+    enforce_retention,
+    retention_due,
+    type RetentionPolicy,
+} from './remote.js';
+
+/**
+ * The outbound-flush timeout, in ms.
+ *
+ * The step says "at or below one second"; this is the bar itself rather than
+ * a value under it, because the spike measured the timeout as the dominant
+ * cost only for an INLINE flush. In the detached child the wait costs the
+ * session nothing, so shortening it would only turn recoverable slow sinks
+ * into dropped batches.
+ */
+export const DEFAULT_FLUSH_TIMEOUT_MS = 1000;
+
+/** `never` means no transport at all — no spool is written. */
+export const FLUSH_NEVER = 'never';
+
+/** The one flush policy that spools and sends. */
+export const FLUSH_SESSION_END = 'session-end';
+
+/**
+ * The spool that sits beside a record log.
+ *
+ * Derived rather than configured: a second path key would let an install
+ * point the spool somewhere the appender does not write, and the failure —
+ * records logged locally, nothing ever sent — is invisible. `.jsonl` is
+ * replaced rather than appended to so the spool is not itself picked up by a
+ * reader globbing `*.jsonl` for records.
+ */
+export function spool_path_for(log_path: string): string {
+    const dir = path.dirname(log_path);
+    const base = path.basename(log_path).replace(/\.jsonl$/u, '');
+    return path.join(dir, `${base}.spool.jsonl`);
+}
+
+/**
+ * Append one already-serialised record line to the spool and bound it.
+ *
+ * The line is passed in rather than re-serialised so the spooled bytes are
+ * byte-identical to the logged bytes: a sink and a local inspection of the
+ * same record must not be able to disagree.
+ */
+export function enqueue_line(
+    spool_path: string,
+    line: string,
+    policy: RetentionPolicy = DEFAULT_RETENTION_POLICY,
+    now: Date = new Date(),
+): void {
+    fs.mkdirSync(path.dirname(spool_path) || '.', { recursive: true });
+    fs.appendFileSync(spool_path, line, { encoding: 'utf-8' });
+    if (retention_due(spool_path, policy, now)) {
+        enforce_retention(spool_path, policy, now);
+    }
+}
+
+export interface SpawnSenderInput {
+    /** Absolute path to `flush_sender.mjs`. */
+    readonly sender_script: string;
+    readonly spool_path: string;
+    readonly endpoint: string;
+    readonly timeout_ms?: number;
+    /** Node binary. Defaults to the one running this process. */
+    readonly node_path?: string;
+}
+
+/**
+ * Spawn the detached sender and return immediately.
+ *
+ * `detached: true` + `stdio: 'ignore'` + `unref()` is the exact shape the
+ * spike measured at 20.5 ms p95, and all three are load-bearing: without
+ * `detached` the child dies with the session's process group, without
+ * `ignore` the parent holds pipe fds open, and without `unref` the parent's
+ * event loop waits for the child — which would reintroduce the very latency
+ * the spool exists to remove.
+ *
+ * The sender is a PLAIN-NODE `.mjs` on purpose. Its siblings in this
+ * directory are TypeScript resolved by `tsx` at import time; a detached child
+ * has no such resolution to inherit, so a `.ts` sender would depend on a
+ * `tsx` binary being findable in a consumer install at teardown — the least
+ * observable moment there is. `process.execPath` is the node already running
+ * this hook, so it exists by construction.
+ *
+ * Returns `true` when the child was spawned. Never throws: a transport that
+ * can fail a session is worse than a transport that loses a batch, and the
+ * batch is not lost — it stays in the spool for the next flush.
+ */
+export function spawn_detached_sender(input: SpawnSenderInput): boolean {
+    try {
+        const child = spawn(
+            input.node_path ?? process.execPath,
+            [
+                input.sender_script,
+                '--spool',
+                input.spool_path,
+                '--endpoint',
+                input.endpoint,
+                '--timeout',
+                String(input.timeout_ms ?? DEFAULT_FLUSH_TIMEOUT_MS),
+            ],
+            { detached: true, stdio: 'ignore' },
+        );
+        child.unref();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Is there anything to send?
+ *
+ * Checked before the spawn so an idle session pays a `stat` rather than a
+ * process. Most sessions invoke no skill at all.
+ */
+export function spool_has_work(spool_path: string): boolean {
+    try {
+        return fs.statSync(spool_path).size > 0;
+    } catch {
+        return false;
+    }
+}

package/dist/cli/registry.js

@@ -59,11 +59,12 @@ export const REGISTRY = [
     { name: 'sessions:list', disposition: 'delegate', synopsis: 'List live agent sessions plus unmerged branches held by other worktrees; --json, --branches.' },
     { name: 'sessions:claim', disposition: 'delegate', synopsis: 'Claim a roadmap for this session so other sessions skip it; --release clears it.' },
     { name: 'session:recycle', disposition: 'delegate', synopsis: 'Validate + write the main-session recycle envelope (--verify validates only, --project names the repo); the successor resumes from it after /clear.' },
-    { name: 'roadmap:progress', disposition: 'delegate', synopsis: 'Regenerate agents/roadmaps-progress.md from open roadmaps.' },
+    { name: 'roadmap:progress', disposition: 'delegate', synopsis: 'Regenerate agents/roadmaps-progress.md from open roadmaps; archives completed ones (--no-archive to skip).' },
     { name: 'roadmap:progress-check', disposition: 'delegate', synopsis: 'Fail if agents/roadmaps-progress.md is stale (for CI).' },
     { name: 'roadmap:archive', disposition: 'delegate', synopsis: 'Archive completed roadmaps (PR-gate sweep).' },
     { name: 'gates', disposition: 'delegate', synopsis: 'Open decisions that need you, as actions — owner-filtered roadmap blockers; --all, --json, --reply, --pending (staged requires_confirmation actions).' },
     { name: 'capabilities:index', disposition: 'delegate', synopsis: 'Regenerate CAPABILITIES.yaml (the package coverage index); --check for CI.' },
+    { name: 'adr:effective', disposition: 'delegate', synopsis: "Effective state of one ADR: status, Decision verbatim, clauses its own amendments superseded, active amendments, axes, trigger state. Authorizes nothing." },
     { name: 'affected', disposition: 'delegate', synopsis: 'Artefacts related to <artefact> via the discovery relation-graph (BFS).' },
     { name: 'graph-explain', disposition: 'delegate', synopsis: 'Seed on a <concept>, expand 2 hops over the discovery relation-graph with a node budget.' },
     { name: 'benchmark', disposition: 'delegate', synopsis: 'Report context-token reduction vs the full always-loaded projection.' },