@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/roadmap_verify_share.ts

@@ -0,0 +1,213 @@
+#!/usr/bin/env tsx
+/**
+ * The runnable share of `verify:` clauses, per roadmap.
+ *
+ * A `verify:` clause names a command and never names what the command must
+ * produce, so a step can be flipped on a command that cannot fail. Two numbers
+ * say how bad that is, and neither had a producing command before this script:
+ * how many clauses name a COMMAND at all (the runnable share), and how many
+ * name an EXPECTATION (the falsifiable share).
+ *
+ * THIS IS A READER, NOT A GATE. It exits 0 on every corpus, including one where
+ * both shares are zero. That is a property of the reader, not a description of
+ * the tree: measured 2026-09-29, the tree carried 230 clauses, 93 naming a
+ * command and 6 naming an expectation — neither share is zero, and the
+ * commissioning roadmap's claim that the second one was is the first thing this
+ * script refuted. A ratchet needs a false-positive rate and two readings a
+ * quarter apart; it has neither, and a gate that reds all but a handful of
+ * roadmaps at once gets weakened until it finds nothing. What it buys instead
+ * is that the NEXT reading is a delta rather than a re-derivation.
+ *
+ * THE UNIT, stated because the figure is meaningless without it. One unit is
+ * one STEP BLOCK (`- [ ]`, `- [x]`, `- [~]`, `- [-]`, plus its continuation
+ * lines) that carries a `verify:` clause. Not one line: a clause wraps, and a
+ * line count would double-count a wrapped clause and count prose that merely
+ * mentions the token. Step blocks come from `closure_scan`'s own `units()`, so
+ * the two instruments agree on what a step is; that also inherits its
+ * exclusions — fenced code, and the `## Decisions` / `## Blockers` /
+ * `## Kill register` / `## Risk Register` discharge sections, where a mention
+ * of `verify:` is commentary rather than a step's oracle.
+ *
+ * Closed steps are counted. A `[x]` flipped on a clause that could not fail is
+ * the defect in its completed form, and excluding them would report the
+ * backlog as smaller every time someone closed one.
+ *
+ * CLI:
+ *   ./scripts-run src/scripts/roadmap_verify_share
+ *   ./scripts-run src/scripts/roadmap_verify_share --json
+ *   ./scripts-run src/scripts/roadmap_verify_share --root <dir> [--recursive]
+ *
+ * Exit codes: 0 always, except 2 for bad argv or a dead scan root.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { units } from './closure_scan.js';
+import { DeadScopeError, assertScanned } from './_lib/scan_scope.js';
+import { parseVerifyClause } from './_lib/verify_clause.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'roadmap_verify_share';
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const DEFAULT_ROOT = 'agents/roadmaps';
+
+export interface FileShare {
+    readonly file: string;
+    /** Step blocks carrying a `verify:` clause. */
+    readonly clauses: number;
+    /** Of those, the ones naming a command — the runnable share. */
+    readonly withCommand: number;
+    /** Of those, the ones naming an expectation — the falsifiable share. */
+    readonly withExpectation: number;
+}
+
+export interface ShareReport {
+    readonly root: string;
+    readonly files: number;
+    readonly clauses: number;
+    readonly withCommand: number;
+    readonly withExpectation: number;
+    readonly perFile: readonly FileShare[];
+}
+
+/** Count the clauses in one roadmap's text. */
+export function shareOf(file: string, text: string): FileShare {
+    let clauses = 0;
+    let withCommand = 0;
+    let withExpectation = 0;
+    for (const u of units(text.split('\n'))) {
+        if (!u.hasVerify) continue;
+        const clause = parseVerifyClause(u.blockText);
+        if (clause === null) continue;
+        clauses += 1;
+        if (clause.command !== null) withCommand += 1;
+        if (clause.expect !== null) withExpectation += 1;
+    }
+    return { file, clauses, withCommand, withExpectation };
+}
+
+function markdownFiles(root: string, recursive: boolean): string[] {
+    const out: string[] = [];
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (recursive) walk(full);
+                continue;
+            }
+            if (e.name.endsWith('.md')) out.push(full);
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+
+export function report(rootAbs: string, rootLabel: string, recursive: boolean): ShareReport {
+    const files = markdownFiles(rootAbs, recursive);
+    // A root that resolved to nothing is blindness, not cleanliness: the share
+    // would read as a clean 0/0 and the reader would believe it.
+    assertScanned({ gate: _PROG, scanned: files.length, units: 'roadmap(s)', roots: [rootLabel] });
+    const perFile = files
+        .map((f) => shareOf(path.relative(REPO_ROOT, f), fs.readFileSync(f, 'utf-8')))
+        .filter((s) => s.clauses > 0);
+    return {
+        root: rootLabel,
+        files: files.length,
+        clauses: perFile.reduce((n, s) => n + s.clauses, 0),
+        withCommand: perFile.reduce((n, s) => n + s.withCommand, 0),
+        withExpectation: perFile.reduce((n, s) => n + s.withExpectation, 0),
+        perFile,
+    };
+}
+
+function pct(n: number, of: number): string {
+    return of === 0 ? 'n/a' : `${((n / of) * 100).toFixed(1)}%`;
+}
+
+export function render(r: ShareReport): string {
+    const lines: string[] = [];
+    lines.push(`root: ${r.root}`);
+    lines.push(`roadmaps scanned: ${String(r.files)}`);
+    lines.push(`verify clauses: ${String(r.clauses)}`);
+    lines.push(`  naming a command:     ${String(r.withCommand)} (${pct(r.withCommand, r.clauses)})`);
+    lines.push(`  naming an expectation: ${String(r.withExpectation)} (${pct(r.withExpectation, r.clauses)})`);
+    lines.push('');
+    lines.push('| roadmap | clauses | command | expectation |');
+    lines.push('|---|---:|---:|---:|');
+    for (const s of r.perFile) {
+        lines.push(
+            `| \`${path.basename(s.file)}\` | ${String(s.clauses)} | ${String(s.withCommand)} | ${String(s.withExpectation)} |`,
+        );
+    }
+    return lines.join('\n') + '\n';
+}
+
+function _usage(): string {
+    return (
+        `usage: ${_PROG} [-h] [--json] [--root <dir>] [--recursive]\n\n` +
+        `Report the runnable and falsifiable share of \`verify:\` clauses. Gates nothing.\n`
+    );
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    let recursive = false;
+    let root = DEFAULT_ROOT;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i] as string;
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        } else if (a === '--json') json = true;
+        else if (a === '--recursive') recursive = true;
+        else if (a === '--root') {
+            const next = args[i + 1];
+            if (next === undefined) {
+                process.stderr.write(`${_usage()}${_PROG}: error: --root needs a directory\n`);
+                return 2;
+            }
+            root = next;
+            i += 1;
+        } else {
+            process.stderr.write(`${_usage()}${_PROG}: error: unrecognized arguments: ${a}\n`);
+            return 2;
+        }
+    }
+
+    const rootAbs = path.isAbsolute(root) ? root : path.join(REPO_ROOT, root);
+    let r: ShareReport;
+    try {
+        r = report(rootAbs, root, recursive);
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`${e.message}\n`);
+            return 2;
+        }
+        throw e;
+    }
+
+    process.stdout.write(json ? JSON.stringify(r, null, 2) + '\n' : render(r));
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/rule_activation_census.ts

@@ -131,8 +131,11 @@ export function classify_rule(
     const type = typeof meta['type'] === 'string' ? (meta['type'] as string) : 'unknown';
     const always = Boolean(meta['alwaysApply'] || type === 'always');
 
-    // `_has_non_path_trigger` is the guard's own predicate and is deliberately
-    // narrower than `has_text_trigger` looks: it ignores `command:` triggers.
+    // `_has_non_path_trigger` is the guard's own predicate, and it is BROADER
+    // than `has_text_trigger`: it counts every match key that is not
+    // path-shaped, so `command:` triggers count too. It used to enumerate
+    // `keyword` and `phrase` and therefore missed them — `roadmap-progress-sync`
+    // read as path-only here while losing three command routes on Claude.
     // Reported separately rather than conflated, because a rule that is mixed by
     // the guard's definition is the one that flipped.
     const mixed = has_path_trigger && _has_non_path_trigger(meta);

package/src/scripts/rule_trigger_eval.ts

@@ -51,6 +51,7 @@ import {
 } from './skill_trigger_eval.js';
 import { AnthropicFetchRouter, loadKeyFromFile } from './_lib/trigger_routers.js';
 import { RULES_MODE_FLOOR } from './_lib/trigger_eval_floors.js';
+import { fnv1a } from './_lib/fnv.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(_HERE, '..', '..');
@@ -144,15 +145,14 @@ export interface RuleCase {
     expected: boolean;
 }
 
-/** FNV-1a 32-bit — deterministic sampling key (no Math.random). */
-export function fnv1a(s: string): number {
-    let h = 0x811c9dc5;
-    for (let i = 0; i < s.length; i += 1) {
-        h ^= s.charCodeAt(i);
-        h = Math.imul(h, 0x01000193) >>> 0;
-    }
-    return h >>> 0;
-}
+/**
+ * FNV-1a 32-bit — deterministic sampling key (no Math.random).
+ *
+ * Moved to `_lib/fnv.ts` when the held-out partition in
+ * `measure_skill_ranker_baseline` became its second caller; re-exported here
+ * because this module's own suite imports the name from this file.
+ */
+export { fnv1a };
 
 /**
  * Derive the eval suite from the routing-matrix fixtures: positive →

package/src/scripts/schemas/command.schema.json

@@ -8,6 +8,50 @@
   "additionalProperties": false,
   "required": ["name", "description", "disable-model-invocation"],
   "properties": {
+    "inputs": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Structured declaration of the parameters this artifact takes. OPTIONAL on every artifact: one with no block validates unchanged, so nothing existing breaks and no migration is owed. Where the block IS present it is the single authority — the argument-hint and the MCP `arguments` set are derived from it, and a hand-written hint on the same artifact is a conflict rather than a merge (road-to-an-invocation-contract-that-reaches-the-wire).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "type"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "Parameter name. Lowercase snake_case, so it is safe both as a wire key and as an in-body ${name} reference."
+          },
+          "type": {
+            "enum": ["string", "number", "boolean", "enum", "path"],
+            "description": "Closed set on purpose: an unknown type must FAIL validation rather than reach a host that cannot interpret it."
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Absent means optional."
+          },
+          "default": {
+            "description": "Value used when the caller supplies none. Any JSON type — it is checked against `type` by the consuming generator, not here."
+          },
+          "enum": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[^|\\]>]+$",
+              "description": "A value. `|`, `]` and `>` are excluded because they are the delimiters of the derived argument-hint — permitting them would make the hint ambiguous and break the round-trip the hint gate asserts."
+            },
+            "description": "Allowed values. Only meaningful when `type` is `enum`."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "One line, shown to a caller choosing a value."
+          }
+        }
+      }
+    },
     "name": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",

package/src/scripts/schemas/review-findings.schema.json

@@ -111,9 +111,10 @@
               "open",
               "fixed",
               "accepted_risk",
-              "false_positive"
+              "false_positive",
+              "still_open"
             ],
-            "description": "Disposition. `fixed` / `false_positive` / `accepted_risk` are the three terminal states check_finding_dispositions accepts; `open` is the initial state. NOTE the underscore spelling — the Markdown track writes `accepted-risk` with a hyphen in its Status cell, and the two vocabularies are deliberately not unified here: renaming either would break committed artefacts on that track."
+            "description": "Disposition. `fixed` / `false_positive` / `accepted_risk` are the three terminal states check_finding_dispositions accepts ON A BLOCKING ROW; `open` is the initial state, meaning nobody has looked yet. `still_open` is a fourth TERMINAL state: a row somebody re-read against a named head, confirmed as a real unfixed issue, and recorded as such. It is deliberately distinct from `open`, which the two look identical to a reader checking only for a non-empty field while being opposites — nobody looked, versus somebody looked and this is the answer. `check_finding_dispositions.TERMINAL_STATUSES` carries all four and `DISPOSITION_STATUSES` only the first three, so a BLOCKING row marked `still_open` reports as an unknown status and keeps the gate red, which is the behaviour a blocking finding that is still open should have. NOTE the underscore spelling — the Markdown track writes `accepted-risk` with a hyphen in its Status cell, and the two vocabularies are deliberately not unified here: renaming either would break committed artefacts on that track."
           },
           "rationale": {
             "type": "string",
@@ -127,6 +128,10 @@
             "type": "string",
             "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
             "description": "ISO calendar date of the disposition."
+          },
+          "contradicted": {
+            "type": "string",
+            "description": "The tree's mechanical disproof of the finding's premise, written by self_review_gate.annotateContradicted when a deletion claim names an artifact the range does not delete and the working tree still holds. A finding carrying this is NOT merge-blocking in either gate (self_review_gate.classifyBlocking and check_finding_dispositions.isBlocking both read it), and it is still reported so a human sees what was claimed and why it was set aside."
           }
         }
       }

package/src/scripts/schemas/rule.schema.json

@@ -212,6 +212,11 @@
       },
       "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `instruction-only: <reason>` declares an honestly model-carried obligation and is counted as a recorded gap — the reason is MANDATORY in the pattern, because a bare marker is a claim with no triage record behind it and resolves to `missing`, which the --check ratchet reds on. The bare `none` spelling it replaces stays legal for exactly one reason: `non-destructive-by-default` still carries it and is a kernel rule that block_kernel_rule_writes denies agent writes to, so retiring the value outright would make a CI-green tree unreachable for any agent. Resolved, not trusted, by check_enforcement_coverage.ts."
     },
+    "consequence_class": {
+      "type": "string",
+      "enum": ["irreversible-external", "security-boundary", "authority-bypass"],
+      "description": "Which clause of the high-consequence criterion this rule meets, declared only by rules that meet one (road-to-rule-laws-that-can-stand Phase 2). THE CRITERION, and it is meant to be applied by reading the rule's own law section rather than its name: a rule is high-consequence when violating the obligation its law states would (a) `irreversible-external` \u2014 perform an action that leaves this repository and that this agent cannot undo: a deploy, a published egress, a paid render, a rewrite of published history, a destroyed record; or (b) `security-boundary` \u2014 cross a security or data-exposure boundary: authorization, secrets, private or personal data, confidentiality, or untrusted content reaching a privileged path; or (c) `authority-bypass` \u2014 take, or let the agent take, a decision reserved to the user, the owner, or an independent evaluator. A rule whose violation costs quality, tokens, consistency, consistency of style, or rework is NOT high-consequence however important it is \u2014 that reading is what makes the class a measurement rather than a list of favourites. Exactly one clause per rule: where two apply, the declared one is the clause the rule's own law text names. The class is what the criterion produces: every member, every near-miss considered and rejected with its reason, and every member whose law cannot yet stand in a stub are all recorded in src/config/rule-consequence-class.json and checked by tests/scripts/rule_consequence_class.test.ts. Consumed by project_thin_rules, which ships a class member as a stub plus its own law section, byte-copied and digest-checked."
+    },
     "obligation_frequency": {
       "type": "string",
       "enum": ["per-edit", "per-turn", "per-task", "per-session", "per-event", "per-commit", "per-file-write", "none"],

package/src/scripts/schemas/skill.schema.json

@@ -13,6 +13,50 @@
     "domain"
   ],
   "properties": {
+    "inputs": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Structured declaration of the parameters this artifact takes. OPTIONAL on every artifact: one with no block validates unchanged, so nothing existing breaks and no migration is owed. Where the block IS present it is the single authority — the argument-hint and the MCP `arguments` set are derived from it, and a hand-written hint on the same artifact is a conflict rather than a merge (road-to-an-invocation-contract-that-reaches-the-wire).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "type"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]*$",
+            "description": "Parameter name. Lowercase snake_case, so it is safe both as a wire key and as an in-body ${name} reference."
+          },
+          "type": {
+            "enum": ["string", "number", "boolean", "enum", "path"],
+            "description": "Closed set on purpose: an unknown type must FAIL validation rather than reach a host that cannot interpret it."
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Absent means optional."
+          },
+          "default": {
+            "description": "Value used when the caller supplies none. Any JSON type — it is checked against `type` by the consuming generator, not here."
+          },
+          "enum": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^[^|\\]>]+$",
+              "description": "A value. `|`, `]` and `>` are excluded because they are the delimiters of the derived argument-hint — permitting them would make the hint ambiguous and break the round-trip the hint gate asserts."
+            },
+            "description": "Allowed values. Only meaningful when `type` is `enum`."
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "One line, shown to a caller choosing a value."
+          }
+        }
+      }
+    },
     "name": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*$",