@event4u/agent-config 12.0.0 → 13.0.0

package/src/scripts/install.ts

@@ -81,6 +81,12 @@ import * as rule_layer_overlap from './_lib/rule_layer_overlap.js';
 import * as installed_tools from './_lib/installed_tools.js';
 import { collect_drift, format_drift_report } from './_lib/install_drift.js';
 import * as user_global_paths from './_lib/user_global_paths.js';
+// The LIBRARY half, deliberately not `capture_skill_catalogue.js`: that module
+// is a CLI entry with a top-level `process.exit()`, and esbuild would bundle
+// that exit into the installer a consumer loads (`check_installer_import_purity`
+// catches exactly this). The lib has no entry and no exit.
+import * as catalogue from './_lib/skill_catalogue.js';
+import { isInteractiveSession, type SessionProbe } from '../shared/interactiveContext.js';
 import * as claude_desktop_bundler from './_lib/claude_desktop_bundler.js';
 import * as claude_settings_hooks from './_lib/claude_settings_hooks.js';
 import { find_project_root_with_anchor, load_agent_settings } from './_lib/agent_settings.js';
@@ -3899,6 +3905,32 @@ function install_global(
         if (!state.QUIET) warn(`settings-surface snapshot failed — ${String(e)}`);
     }
 
+    // Catalogue-budget warning (road-to-skill-catalogue-budget Phase 1).
+    // Some hosts silently truncate the skill catalogue they were handed: the
+    // deploy reports success, and the model never sees most of what was
+    // deployed. A host that publishes its own dropped count has a MEASURED
+    // ceiling; one that does not gets no warning and no invented number.
+    // Warn only — over-shipping is the safe direction, and a consumer who
+    // accepts truncation is making a legitimate choice.
+    if (!state.QUIET) {
+        try {
+            for (const line of _catalogue_truncation_warnings(deploy_results, project_root)) {
+                warn(line);
+            }
+            const notice = _scoped_migration_notice(deploy_results, project_root, package_root, {
+                env: process.env,
+                stdinTty: process.stdin.isTTY === true,
+                stdoutTty: process.stdout.isTTY === true,
+            });
+            if (notice.length > 0) {
+                process.stdout.write('\n');
+                for (const line of notice) info(line);
+            }
+        } catch {
+            // A measurement must never sink an install that otherwise worked.
+        }
+    }
+
     if (!state.QUIET) {
         process.stdout.write('\n');
         success(`Global install completed (v${installed_version}).`);
@@ -3907,6 +3939,103 @@ function install_global(
     return 0;
 }
 
+/**
+ * One line per deployed host whose catalogue exceeds a ceiling this machine has
+ * actually measured. Empty when nothing has been measured — the observation log
+ * lives where captures accumulate, and an install on a machine that never ran
+ * one has no basis to claim a limit.
+ *
+ * Returns lines rather than printing them so the decision is testable without
+ * capturing stdout.
+ */
+export function _catalogue_truncation_warnings(
+    deploy_results: Record<string, DeployResult>,
+    project_root: string | null,
+): string[] {
+    const log_candidates = [
+        path.join(user_global_paths.event4u_root(), 'state', 'skill-catalogue.jsonl'),
+        ...(project_root ? [path.join(project_root, catalogue.OBSERVATION_LOG)] : []),
+    ];
+    const records = log_candidates.flatMap((p) => catalogue.readObservationLog(p));
+    if (records.length === 0) return [];
+
+    const limits = catalogue.knownHostLimits(records);
+    if (limits.size === 0) return [];
+
+    const lines: string[] = [];
+    for (const tool_id of Object.keys(deploy_results).sort()) {
+        const [, , status] = deploy_results[tool_id] as DeployResult;
+        if (status !== 'deployed') continue;
+        const limit = limits.get(tool_id);
+        if (limit === undefined) continue;
+        const anchor_raw = USER_SCOPE_PATHS[tool_id];
+        if (!anchor_raw) continue;
+
+        const volume = catalogue.measureCatalogueVolume(tool_id, expanduser(anchor_raw));
+        const warning = catalogue.catalogueLimitWarning(volume, limit);
+        if (warning !== null) lines.push(warning);
+    }
+    return lines;
+}
+
+/**
+ * The scoped-projection migration notice for an EXISTING install.
+ *
+ * Shape decided by AI council 2026-08-15 (2/2 converged, both members present):
+ * option B — the existing warning PLUS an interactive notice that persists
+ * NOTHING and names the manual edit and the GUI route. `projection.mode` is
+ * settings class C, so no agent may write it; a notice that offered a CLI
+ * write would send the reader to a command guaranteed to refuse them.
+ *
+ * Eligibility and delivery are separate on purpose. A non-interactive run can
+ * be fully eligible; it simply gets the warning and no notice, and the two
+ * outcomes stay distinguishable instead of collapsing into "nothing printed".
+ *
+ * Known and accepted: with nothing persisted, a qualifying install sees this
+ * on every deploy. The council named that as the strongest argument for doing
+ * nothing at all, and it does not outweigh making a measured, silent
+ * capability loss an explicit human decision.
+ */
+export function _scoped_migration_notice(
+    deploy_results: Record<string, DeployResult>,
+    project_root: string | null,
+    package_root: string,
+    probe: SessionProbe,
+): string[] {
+    if (!isInteractiveSession(probe)) return [];
+
+    const log_candidates = [
+        path.join(user_global_paths.event4u_root(), 'state', 'skill-catalogue.jsonl'),
+        ...(project_root ? [path.join(project_root, catalogue.OBSERVATION_LOG)] : []),
+    ];
+    const limits = catalogue.knownHostLimits(log_candidates.flatMap((p) => catalogue.readObservationLog(p)));
+    if (limits.size === 0) return [];
+
+    const resolved = _resolve_scoped_projection(package_root);
+    const settings_path =
+        _resolve_global_settings_path() ??
+        path.join(user_global_paths.event4u_root(), 'settings', SETTINGS_FILE);
+
+    for (const tool_id of Object.keys(deploy_results).sort()) {
+        const [, , status] = deploy_results[tool_id] as DeployResult;
+        if (status !== 'deployed') continue;
+        const anchor_raw = USER_SCOPE_PATHS[tool_id];
+        if (!anchor_raw) continue;
+
+        const volume = catalogue.measureCatalogueVolume(tool_id, expanduser(anchor_raw));
+        const eligibility = catalogue.migrationEligibility(
+            tool_id,
+            resolved.mode,
+            volume.skillEntries,
+            limits,
+        );
+        if (eligibility.eligible) {
+            return catalogue.migrationPromptLines(tool_id, eligibility, settings_path);
+        }
+    }
+    return [];
+}
+
 const SETTINGS_SURFACE_REL = path.join('state', 'settings-surface.json');
 const SETTINGS_DELTA_REL = path.join('state', 'settings-delta.json');
 

package/src/scripts/janitor.ts

@@ -24,22 +24,82 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.join(path.dirname(_HERE), '..', '..');
 
-// TTL configuration per directory (days)
-const TTL_CONFIG: ReadonlyArray<{ dir: string; ttlDays: number; description: string }> = [
+// TTL configuration per directory (days).
+//
+// `owner` / `reviewBy` (road-to-inbox-harvest-2026-08-d-context-ledger Step
+// 4.1) put every TTL under the same discipline the two budget config files
+// carry: a retention number nobody owns and nobody revisits is a guess that
+// hardens into a fact. The falsifier is printed per run — see the reclaim
+// total in `main` — so a TTL that reclaims nothing over a review window is
+// removed rather than defended.
+const TTL_CONFIG: ReadonlyArray<{
+    dir: string;
+    ttlDays: number;
+    description: string;
+    owner: string;
+    reviewBy: string;
+}> = [
     {
         dir: 'agents/tmp.old',
         ttlDays: 30,
         description: 'Processed inbox archive (consumed agents/tmp/ files)',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
     },
     {
         dir: 'agents/runtime/tmp',
         ttlDays: 7,
         description: 'Agent scratch / runtime tmp',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
     },
     {
         dir: 'agents/runtime/council/responses',
         ttlDays: 7,
         description: 'Council response cache',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
+    // ── Session-scoped runtime state (Step 4.1) ────────────────────────────
+    //
+    // These four directories accrete ONE entry per session behind a
+    // once-per-session latch, and nothing in the tree removed them: writers
+    // and readers existed, no reaper did. They are named INDIVIDUALLY rather
+    // than sweeping `agents/runtime/state` as a whole, and that is the
+    // load-bearing decision in this step.
+    //
+    // `agents/runtime/state` also holds the CUMULATIVE measurement streams —
+    // `audit/`, `injection-census.jsonl`, `tool-result-census.jsonl`,
+    // `ai-video-telemetry.jsonl`, the memory index — and a directory-level
+    // TTL would delete exactly the corpora this roadmap exists to build. A
+    // sweeper that eats the instrument's own data is worse than no sweeper.
+    {
+        dir: 'agents/runtime/state/session-eol',
+        ttlDays: 7,
+        description: 'Per-session end-of-life counters (one file per session)',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
+    {
+        dir: 'agents/runtime/state/reread-guard',
+        ttlDays: 7,
+        description: 'Per-session re-read latch',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
+    {
+        dir: 'agents/runtime/state/end-review-nudge',
+        ttlDays: 7,
+        description: 'Per-session end-review latch',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
+    },
+    {
+        dir: 'agents/runtime/state/probe-throttle',
+        ttlDays: 7,
+        description: 'Per-session probe throttle latch',
+        owner: 'maintainer',
+        reviewBy: '2026-11-10',
     },
 ];
 
@@ -227,6 +287,21 @@ function report(apply: boolean): void {
         );
     } else if (apply && totalExpired > 0) {
         process.stdout.write(`Total deleted: ${totalExpired} file(s), ${_humanSize(totalSize)} freed.\n`);
+    } else {
+        // road-to-inbox-harvest-2026-08-d-context-ledger Step 4.2 — the TTL's
+        // own falsifier, and it only works if a ZERO is printed.
+        //
+        // Until now a run that reclaimed nothing printed no total at all, so
+        // "the sweeper ran and found nothing expired" and "the sweeper did not
+        // run" produced byte-identical output. That is the difference between
+        // evidence that a retention policy is unnecessary and no evidence at
+        // all — and the first is what removes a TTL entry rather than letting
+        // it harden into an unexamined default.
+        process.stdout.write(
+            `Total ${apply ? 'deleted' : 'reclaimable'}: 0 file(s), 0 B — nothing was past its TTL.\n` +
+                `A reclaim that stays at zero across a review window is the signal to drop the ` +
+                `TTL entry, not to keep it: see the owner / reviewBy fields on each entry.\n`,
+        );
     }
 }
 

package/src/scripts/lint_design_antipattern_parity.ts

@@ -29,6 +29,7 @@ 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 { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.includes('--quiet');
@@ -44,6 +45,14 @@ export type Status = (typeof STATUSES)[number];
 export interface ParityFinding {
     kind: string;
     msg: string;
+    /**
+     * The catalog id this finding is about, when it is about one.
+     *
+     * Carried explicitly so the per-target ledger can attribute a failure
+     * without parsing it back out of `msg`. Absent on structural findings
+     * (a missing § Detector status section is about the document, not an id).
+     */
+    id?: string;
 }
 
 const ENTRY_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|/gm;
@@ -89,7 +98,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const entries = catalogEntries(catalogMd);
     const seen = new Set<string>();
     for (const id of entries) {
-        if (seen.has(id)) out.push({ kind: 'duplicate-entry', msg: `${id}: appears more than once in the catalog tables` });
+        if (seen.has(id)) out.push({ kind: 'duplicate-entry', id, msg: `${id}: appears more than once in the catalog tables` });
         seen.add(id);
     }
 
@@ -98,13 +107,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     // A — every catalog entry is classified.
     for (const id of seen) {
         if (!rows.has(id)) {
-            out.push({ kind: 'unclassified', msg: `${id}: catalog entry missing from § Detector status` });
+            out.push({ kind: 'unclassified', id, msg: `${id}: catalog entry missing from § Detector status` });
         }
     }
     // B — every classified row names a real entry.
     for (const id of rows.keys()) {
         if (!seen.has(id)) {
-            out.push({ kind: 'orphan-status', msg: `${id}: § Detector status row names an entry that no catalog table defines` });
+            out.push({ kind: 'orphan-status', id, msg: `${id}: § Detector status row names an entry that no catalog table defines` });
         }
     }
     // D + E — status vocabulary and reasons.
@@ -112,12 +121,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
         if (!(STATUSES as readonly string[]).includes(row.status)) {
             out.push({
                 kind: 'bad-status',
+                id,
                 msg: `${id}: status '${row.status || '(empty)'}' is not one of ${STATUSES.join(', ')}`,
             });
             continue;
         }
         if (row.status !== 'backed' && row.note === '') {
-            out.push({ kind: 'missing-reason', msg: `${id}: status '${row.status}' carries no reason` });
+            out.push({ kind: 'missing-reason', id, msg: `${id}: status '${row.status}' carries no reason` });
         }
     }
 
@@ -126,7 +136,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const registry = new Set(registryCatalogIds(registryTs));
     for (const id of backed) {
         if (!registry.has(id)) {
-            out.push({ kind: 'backed-without-rule', msg: `${id}: marked backed but no registry rule declares that catalogId` });
+            out.push({ kind: 'backed-without-rule', id, msg: `${id}: marked backed but no registry rule declares that catalogId` });
         }
     }
     for (const id of registry) {
@@ -134,6 +144,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
             const known = rows.get(id);
             out.push({
                 kind: 'rule-without-backed',
+                id,
                 msg: known
                     ? `${id}: a registry rule declares this catalogId but § Detector status marks it '${known.status}'`
                     : `${id}: a registry rule declares this catalogId and no catalog entry carries it`,
@@ -167,8 +178,31 @@ export function main(): number {
     const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
     const findings = parityFindings(catalogMd, registryTs);
 
+    const rows = statusRows(catalogMd);
     const entries = catalogEntries(catalogMd).length;
-    const backed = [...statusRows(catalogMd).values()].filter((r) => r.status === 'backed').length;
+    const backed = [...rows.values()].filter((r) => r.status === 'backed').length;
+
+    // Per-target completeness accounting. The target is a catalog ID, and the
+    // planned set is the UNION of the three places an id can appear — catalog
+    // tables, the § Detector status table, and the rule registry — because this
+    // gate's whole subject is parity BETWEEN those sets. Planning only the
+    // catalog would leave an orphan status row or a registry-only id
+    // unaccounted, which is the direction the gate exists to catch.
+    const ledger = new GateLedger('lint_design_antipattern_parity');
+    const targets = [
+        ...new Set([
+            ...catalogEntries(catalogMd),
+            ...rows.keys(),
+            ...registryCatalogIds(registryTs),
+        ]),
+    ].sort();
+    ledger.plan(targets);
+    const failedIds = new Set(findings.map((f) => f.id).filter((v): v is string => v !== undefined));
+    for (const id of targets) {
+        if (failedIds.has(id)) ledger.fail(id, 'parity finding');
+        else ledger.complete(id);
+    }
+    ledger.report();
 
     if (findings.length === 0) {
         _print(`✅  catalog ↔ rule parity OK — ${entries} entries classified, ${backed} detector-backed`);

package/src/scripts/lint_harvest_provenance.ts

@@ -49,6 +49,7 @@ 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 { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
@@ -432,7 +433,40 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const text = fs.readFileSync(ledgerPath, 'utf-8');
     const { records, findings } = lintLedgerText(text, REPO);
     const citations = [...collectCitations(REPO), ...collectPersonaSources(REPO)];
-    const allFindings = [...findings, ...findOrphanCitations(citations, records)];
+    const orphans = findOrphanCitations(citations, records);
+    const allFindings = [...findings, ...orphans];
+
+    // Per-target completeness accounting over the two populations this gate
+    // reasons about: the ledger's own rows, and the citations that point at
+    // them. Both are legitimately EMPTY today, and that is exactly why the
+    // accounting is worth having — a green line over zero rows and a green line
+    // over a hundred checked rows read identically without it, which is the
+    // failure the success message above already tries to talk its way out of in
+    // prose. The ledger states it structurally instead.
+    const ledger = new GateLedger('lint_harvest_provenance');
+    const known = new Set(records.map((r) => r.harvest_id));
+    // The row population is every PARSED ledger line, not `records`: a row that
+    // fails validation or uniqueness is `continue`d and never reaches `records`,
+    // so planning `records` would plan exactly the rows that passed and account
+    // for none of the ones that did not — an accounting that can only ever read
+    // 100 %. Lines are the stable key; a Finding already carries one.
+    const { parsed } = parseLedgerText(text);
+    const badLines = new Set(findings.filter((f) => f.line > 0).map((f) => f.line));
+    ledger.plan([
+        ...parsed.map((r) => `row:${String(r.line)}`),
+        ...citations.map((c) => `citation:${c.id}@${c.file}`),
+    ]);
+    for (const r of parsed) {
+        const id = `row:${String(r.line)}`;
+        if (badLines.has(r.line)) ledger.fail(id, 'ledger-row finding');
+        else ledger.complete(id);
+    }
+    for (const c of citations) {
+        const id = `citation:${c.id}@${c.file}`;
+        if (known.has(c.id)) ledger.complete(id);
+        else ledger.fail(id, 'orphan citation — no ledger row carries this harvest id');
+    }
+    ledger.report();
 
     if (allFindings.length > 0) {
         for (const f of allFindings) {

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 { workspaceIdentity } from './_lib/git_common_dir.js';
 import { gitEnv } from './_lib/git_env.js';
 import { splitMarkdownRow } from './_lib/md_table.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
@@ -505,12 +506,26 @@ interface HistoryEntry {
     date: string; // %cs — YYYY-MM-DD
 }
 
+/**
+ * Repo root containing `dir`, or `null` outside a repository.
+ *
+ * Census rows R5–R7. The three call sites below each spawned
+ * `rev-parse --show-toplevel` through `_git` — already `GIT_DIR`-safe via
+ * `gitEnv()`, so this migration is behaviour-identical by construction and
+ * exists to remove the third, fourth and fifth re-derivation of one question,
+ * not to fix a defect. The resolver reads files instead of spawning, so the
+ * three checks also stop costing three subprocesses.
+ */
+function _repoRootOf(dir: string): string | null {
+    const root = workspaceIdentity(dir).repoRoot;
+    return root.resolved ? root.value : null;
+}
+
 /** Newest-first commit history of a file; empty for untracked / non-repo paths. */
 export function fileHistory(absPath: string): HistoryEntry[] {
     const dir = path.dirname(absPath);
-    const top = _git(dir, ['rev-parse', '--show-toplevel']);
-    if (top === null) return [];
-    const root = top.trim();
+    const root = _repoRootOf(dir);
+    if (root === null) return [];
     // Normalize separators: git pathspecs use `/` on every platform, so a raw
     // Windows `path.relative()` result matches nothing and would silently yield
     // an empty history — which the grandfather clause reads as "no baseline".
@@ -540,9 +555,8 @@ export function fileHistory(absPath: string): HistoryEntry[] {
  */
 export function hasUncommittedChanges(absPath: string): boolean {
     const dir = path.dirname(absPath);
-    const top = _git(dir, ['rev-parse', '--show-toplevel']);
-    if (top === null) return false;
-    const root = top.trim();
+    const root = _repoRootOf(dir);
+    if (root === null) return false;
     const rel = path.relative(root, absPath).split(path.sep).join('/');
     const out = _git(root, ['status', '--porcelain', '--', rel]);
     if (out === null) return false;
@@ -551,9 +565,8 @@ export function hasUncommittedChanges(absPath: string): boolean {
 
 function _blobAt(absPath: string, sha: string): string | null {
     const dir = path.dirname(absPath);
-    const top = _git(dir, ['rev-parse', '--show-toplevel']);
-    if (top === null) return null;
-    const root = top.trim();
+    const root = _repoRootOf(dir);
+    if (root === null) return null;
     const rel = path.relative(root, absPath).split(path.sep).join('/');
     return _git(root, ['show', `${sha}:${rel}`]);
 }

package/src/scripts/lint_roadmap_blockers.ts

@@ -20,6 +20,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -46,6 +47,41 @@ const REQUIRED_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
     ['Resolved when', /^-[ \t]*\*\*Resolved when:\*\*/im],
 ];
 
+/**
+ * The fields that make a blocker DECIDABLE rather than merely described.
+ *
+ * Separated from `REQUIRED_FIELDS` on purpose: the five above are a settled
+ * contract every entry in the tree already satisfies, so a missing one is a
+ * hard failure. These three are new, and 36 open entries predate them — held
+ * to the same bar on day one they would red the whole backlog, which is the
+ * "strict gate fires on ~283 files" failure this repo has already recorded
+ * once. They run through the ratchet instead: the backlog is legal at its
+ * measured size, and every entry added or edited after this must clear them.
+ */
+const DECIDABILITY_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['Recommendation', /^-[ \t]*\*\*Recommendation:\*\*[ \t]*\S/im],
+    ['If you do nothing', /^-[ \t]*\*\*If you do nothing:\*\*[ \t]*\S/im],
+];
+
+/** `What to do:` body — everything up to the next field marker. */
+const WHAT_TO_DO_SLICE_RE =
+    /^-[ \t]*\*\*What to do:\*\*([\s\S]*?)(?=^-[ \t]*\*\*[A-Z]|^###[ \t]|$(?![\s\S]))/im;
+
+/**
+ * Does `What to do` carry anything the owner can actually execute?
+ *
+ * A backticked span (a command, a path, a flag) or an enumerated option set
+ * (`(a)` / `1.`) both count. Bare prose does not: "pick exactly one — accept
+ * the reading, or re-cut the criterion" names no file, no command and no
+ * consequence, and hands the analysis back to the person least equipped to
+ * redo it. Measured 2026-08-15: 14 of 46 entries in this tree are that shape.
+ */
+function _hasExecutableSubstance(body: string): boolean {
+    const m = WHAT_TO_DO_SLICE_RE.exec(body);
+    const slice = m ? (m[1] as string) : '';
+    return /`[^`\n]+`/.test(slice) || /(^|\s)\((?:[a-z]|[0-9]+)\)\s/i.test(slice);
+}
+
 interface Violation {
     line: number;
     message: string;
@@ -68,7 +104,19 @@ function _stripFencedCode(text: string): string {
 }
 
 function _scan(rawText: string): Violation[] {
+    return _scanBoth(rawText).hard;
+}
+
+interface ScanResult {
+    /** Contract violations — always fatal. */
+    hard: Violation[];
+    /** Open entries that are not yet decidable — counted against the ratchet. */
+    decidability: Violation[];
+}
+
+function _scanBoth(rawText: string): ScanResult {
     const violations: Violation[] = [];
+    const decidability: Violation[] = [];
     const text = _stripFencedCode(rawText);
     const declaredIds = new Set<string>();
 
@@ -105,6 +153,23 @@ function _scan(rawText: string): Violation[] {
                     message: `blocker '${cur.id}' missing required field(s): ${missing.join(', ')}`,
                 });
             }
+            // Resolved entries are history — re-litigating a decision already
+            // made would be churn, and the ratchet would never reach zero.
+            const isResolved = /^-[ \t]*\*\*Status:\*\*[ \t]*resolved/im.test(body);
+            if (!isResolved) {
+                const gaps = DECIDABILITY_FIELDS.filter(([, re]) => !re.test(body)).map(
+                    ([name]) => name,
+                );
+                if (!_hasExecutableSubstance(body)) {
+                    gaps.push('What to do (no command, path or option set)');
+                }
+                if (gaps.length) {
+                    decidability.push({
+                        line: _lineAt(text, sectionStart + cur.start),
+                        message: `blocker '${cur.id}' is not decidable yet: ${gaps.join(', ')}`,
+                    });
+                }
+            }
         }
     }
 
@@ -131,7 +196,8 @@ function _scan(rawText: string): Violation[] {
         }
     }
     violations.sort((a, b) => a.line - b.line);
-    return violations;
+    decidability.sort((a, b) => a.line - b.line);
+    return { hard: violations, decidability };
 }
 
 /** Sorted `agents/roadmaps/*.md` (non-recursive — active roadmaps only). */
@@ -206,14 +272,18 @@ function main(): number {
         return 0;
     }
     let failed = 0;
+    const undecidable: Array<{ rel: string; v: Violation }> = [];
     for (const roadmap of roadmaps) {
         const rel = _relPosix(roadmap, REPO_ROOT);
         const text = fs.readFileSync(roadmap, 'utf-8');
-        const violations = _scan(text);
-        if (violations.length) {
+        const { hard, decidability } = _scanBoth(text);
+        for (const v of decidability) {
+            undecidable.push({ rel, v });
+        }
+        if (hard.length) {
             failed += 1;
             process.stderr.write(`❌  ${rel}\n`);
-            for (const v of violations) {
+            for (const v of hard) {
                 process.stderr.write(`    line ${v.line}: ${v.message}\n`);
             }
         } else if (!QUIET) {
@@ -228,8 +298,31 @@ function main(): number {
         );
         return 1;
     }
+
+    // The decidability ratchet. A blocker that names no option, no command and
+    // no recommendation is a research task handed to the person with the least
+    // context — the defect this half of the gate exists to stop growing.
+    const verdict = checkRatchet({
+        gate: 'lint_roadmap_blockers:decidability',
+        actual: undecidable.length,
+        repoRoot: REPO_ROOT,
+    });
+    if (!verdict.ok) {
+        process.stderr.write(`❌  ${verdict.message}\n`);
+        for (const { rel, v } of undecidable) {
+            process.stderr.write(`    ${rel}:${v.line}: ${v.message}\n`);
+        }
+        process.stderr.write(
+            '\n    Every open blocker needs **Recommendation:** (which option, and why),\n' +
+                '    **If you do nothing:** (the cost of the non-decision), and a\n' +
+                '    **What to do:** carrying a command, a path or an enumerated option set.\n' +
+                '    See templates/roadmaps.md rule 20.\n',
+        );
+        return 1;
+    }
     if (!QUIET) {
         process.stdout.write(`\n✅  ${roadmaps.length} roadmap(s) blocker-contract-clean\n`);
+        process.stdout.write(`✅  ${verdict.message}\n`);
     }
     return 0;
 }
@@ -260,5 +353,15 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
     process.exit(main());
 }
 
-export { REPO_ROOT, ROADMAP_GLOB, REQUIRED_FIELDS, _scan, _globRoadmaps, main };
-export type { Violation };
+export {
+    REPO_ROOT,
+    ROADMAP_GLOB,
+    REQUIRED_FIELDS,
+    DECIDABILITY_FIELDS,
+    _hasExecutableSubstance,
+    _scan,
+    _scanBoth,
+    _globRoadmaps,
+    main,
+};
+export type { Violation, ScanResult };