@event4u/agent-config 16.0.0 → 16.2.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/schemas/agent-settings.schema.json

@@ -101,6 +101,29 @@
         }
       }
     },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "merge": {
+          "type": "string",
+          "enum": ["off", "on-green"],
+          "default": "off",
+          "description": "Whether a run may merge the pull request it produced. off (default) = the run ends at mergeable-green-and-open and says so. on-green = merge is permitted, and only when an object-bound grant covering {op: prod_merge, target: <base>} exists and the final head is required-check-green, target-current and tamper-checked (ADR-268 section 3). A precondition, never the authorisation by itself; forge auto-merge is the mechanism, so branch protection stays the gate."
+        },
+        "wait_for_ci": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the run stays alive until the required checks settle. true (default) = the run drives CI and reports the settled verdict. false = the run ends once the branch is pushed and the PR is open. Independent of merge: a run may wait for CI without being allowed to merge."
+        },
+        "pr_topology": {
+          "type": "string",
+          "enum": ["single", "stacked"],
+          "default": "single",
+          "description": "How a mission's work is shaped into pull requests. single (default) = one branch, one pull request. stacked = a dependent series. stacked is never chosen by the agent and never asked about at roadmap creation — the owner plans it in roadmap frontmatter or it does not happen."
+        }
+      }
+    },
     "screenshots": {
       "type": "object",
       "additionalProperties": true,

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]+)*$",
@@ -103,6 +147,10 @@
       "pattern": "^[a-z][a-z0-9-]*$",
       "description": "Sub-command identifier within the cluster (e.g. `ci` for `/fix ci`)."
     },
+    "produces_roadmap": {
+      "type": "boolean",
+      "description": "This command produces a roadmap, so it ends in the plan-closure pass (`/challenge-me closure`). The declaration replaces the hard-coded entrance list that lived inside three command bodies and left the other five producers uncovered with nothing saying so. `lint_roadmap_producers` reds a command that declares it and carries no reference to the closure pass. Omit the key for commands that produce no plan."
+    },
     "superseded_by": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*( (--[a-z][a-z0-9-]*|[a-z][a-z0-9-]*))?$",

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

@@ -127,6 +127,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/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-]*$",

package/src/scripts/scope_growth.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Who owns a piece of scope growth discovered mid-mission.
+ *
+ * The size question — *is this small and aligned enough to do now* — already
+ * has an answer in the remediation ladder. This is the other axis, and the two
+ * are independent: something small and council-owned is still not the agent's
+ * to decide, and something agent-owned and large is still bounded by the
+ * smallest-diff rule.
+ *
+ * Four verdicts, and the last one is the important one:
+ *
+ *   `agent`      done inline, recorded as a scope delta in the PR body, never
+ *                asked about.
+ *   `council`    routed through the ownership ladder; the verdict becomes a
+ *                `## Decisions` row. It does NOT reach the owner, however
+ *                consequential — a technical decision does not become
+ *                owner-owned because it is hard.
+ *   `owner`      the work changes what the product or the business does, or it
+ *                needs a typed op for which no grant exists. Two rows, closed.
+ *   `follow-up`  not scope growth at all. A larger unrelated opportunity
+ *                becomes its own artifact and the mission does not expand to
+ *                hold it — the failure that looks like diligence is a mission
+ *                that absorbs every good idea it meets and delivers none.
+ *
+ * `unknown` is a real verdict and is deliberately NOT folded into `agent`:
+ * growth nothing classifies is growth nobody decided, and defaulting it to the
+ * cheapest rung is how an owner question becomes an agent one silently.
+ *
+ * Exit codes: 0 classified · 1 unknown · 2 bad argv.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'scope_growth';
+
+export type Verdict = 'agent' | 'council' | 'owner' | 'follow-up' | 'unknown';
+
+export interface Rule {
+    readonly verdict: Verdict;
+    readonly kind: string;
+    readonly re: RegExp;
+}
+
+/**
+ * Ordered, and the order is the contract: `owner` and `follow-up` are tested
+ * BEFORE `agent`, so a row that matches both ("a missing test — in a subsystem
+ * this mission never touched") resolves to the more conservative rung rather
+ * than to the first cheap match.
+ */
+export const RULES: readonly Rule[] = [
+    // --- owner: two rows, closed ------------------------------------------
+    {
+        verdict: 'owner',
+        kind: 'product-or-business-change',
+        re: /\b(?:new user-visible|changes what the product|changes what the business|a price|pricing|a public commitment|a policy change)\b/i,
+    },
+    {
+        verdict: 'owner',
+        kind: 'typed-op-without-grant',
+        re: /\b(?:needs a typed op|no grant exists|merge to main|force-push|deploy to prod(?:uction)?|rotate the secret)\b/i,
+    },
+    // --- follow-up: unrelated, however good -------------------------------
+    {
+        verdict: 'follow-up',
+        kind: 'larger-unrelated',
+        re: /\b(?:unrelated|another subsystem|a subsystem this .{0,30}never touched|out of scope|deserves its own)\b/i,
+    },
+    // --- council: technical, contested ------------------------------------
+    {
+        verdict: 'council',
+        kind: 'larger-internal-re-cut',
+        re: /\b(?:re-?cut|restructure the module|reshape the boundary)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'two-equal-strategies',
+        re: /\b(?:two equal|two valid|either strategy|no evidence between them)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'risky-compatibility-design',
+        re: /\b(?:compatibility risk|backwards[- ]incompat|breaking change)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'unclear-boundary',
+        re: /\b(?:unclear boundary|where the boundary)\b/i,
+    },
+    // --- agent: six rows, closed ------------------------------------------
+    {
+        verdict: 'agent',
+        kind: 'necessary-internal-refactor',
+        re: /\b(?:necessary (?:internal )?refactor|cannot land (?:correctly )?without)\b/i,
+    },
+    { verdict: 'agent', kind: 'missing-test', re: /\bmissing test\b/i },
+    {
+        verdict: 'agent',
+        kind: 'regression-on-touched-path',
+        re: /\bregression\b[^.]{0,60}\btouched\b|\btouched\b[^.]{0,60}\bregression\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'small-dependency-adjustment',
+        re: /\b(?:small dependency adjustment|patch bump|minor bump)\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'local-api-inside-defined-semantics',
+        re: /\b(?:inside (?:the )?(?:already-)?defined semantics|the contract does not move)\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'boy-scout-cleanup',
+        re: /\bboy[- ]scout\b/i,
+    },
+];
+
+export interface Classification {
+    readonly verdict: Verdict;
+    readonly kind: string;
+    /** True when the verdict is done inline and recorded rather than asked. */
+    readonly records_scope_delta: boolean;
+    /** True when a person is reached at all. */
+    readonly asks: boolean;
+}
+
+export function classifyGrowth(text: string): Classification {
+    for (const r of RULES) {
+        if (r.re.test(text)) {
+            return {
+                verdict: r.verdict,
+                kind: r.kind,
+                records_scope_delta: r.verdict === 'agent',
+                asks: r.verdict === 'owner',
+            };
+        }
+    }
+    return { verdict: 'unknown', kind: 'unclassified', records_scope_delta: false, asks: false };
+}
+
+function _usage(): string {
+    return `usage: ${_PROG} [-h] [--self-test] [--json] <description...>\n`;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    const words: string[] = [];
+    for (const a of args) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        }
+        if (a === '--self-test') return _selfTest();
+        if (a === '--json') {
+            json = true;
+            continue;
+        }
+        words.push(a);
+    }
+    if (!words.length) {
+        process.stderr.write(`${_usage()}${_PROG}: error: a description is required\n`);
+        return 2;
+    }
+    const c = classifyGrowth(words.join(' '));
+    if (json) {
+        process.stdout.write(JSON.stringify(c, null, 2) + '\n');
+    } else {
+        process.stdout.write(
+            `${c.verdict}  (${c.kind})  scope-delta=${String(c.records_scope_delta)}  asks=${String(c.asks)}\n`,
+        );
+    }
+    return c.verdict === 'unknown' ? 1 : 0;
+}
+
+function _selfTest(): number {
+    const cases: ReadonlyArray<readonly [string, Verdict]> = [
+        ['a missing test on a path this change touched', 'agent'],
+        ['a boy-scout cleanup, small and local', 'agent'],
+        ['two equal technical strategies with no evidence between them', 'council'],
+        ['this introduces a compatibility risk', 'council'],
+        ['it needs a typed op and no grant exists', 'owner'],
+        ['this adds new user-visible semantics', 'owner'],
+        ['an unrelated refactor that deserves its own roadmap', 'follow-up'],
+        ['something nobody wrote a rule for', 'unknown'],
+        // The ordering case: matches `missing test` AND `unrelated`, and the
+        // conservative rung must win or a follow-up silently becomes agent work.
+        ['a missing test in an unrelated subsystem', 'follow-up'],
+    ];
+    const failures: string[] = [];
+    for (const [text, want] of cases) {
+        const got = classifyGrowth(text).verdict;
+        if (got !== want) failures.push(`"${text}" → ${got}, wanted ${want}`);
+    }
+    if (failures.length) {
+        for (const f of failures) process.stderr.write(`❌  ${_PROG} --self-test: ${f}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  ${_PROG} --self-test: ${String(cases.length)} case(s) behaved\n`);
+    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();
+}