@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/lint_plan_risk_register.ts

@@ -9,10 +9,10 @@
  *
  * Corpus: ready (non-draft) roadmap files directly under `agents/roadmaps/`  code-comment-allow provenance-comment -- the path is this script's operand, not where the code came from
  * (top level only — `archive/`, `skipped/`, `later/`, `stubs/` excluded, as
- * are `template.md` and `dashboard*`). `status: draft` and `status: carrier`
- * frontmatter exempt a file, each reported under its own name (`draft-exempt`
- * / `carrier-exempt`) and still counted as scanned — one label for two states
- * made the gate's own output name a state it had not acted on.
+ * are `template.md` and `dashboard*`). `status: draft` frontmatter exempts a
+ * file, reported as `draft-exempt` and still counted as scanned. A second
+ * exempting status, `carrier`, was deleted by ADR-262: a receiver of deferred
+ * work is an ordinary plan and carries a real risk register like any other.
  *
  * Checks per ready file:
  *   1. `## Risk Register` section exists — missing = fail unless the
@@ -329,20 +329,16 @@ export function validateTable(
 }
 
 /** A frontmatter status that exempts the file, or `null` when none does. */
-export type ExemptingStatus = 'draft' | 'carrier';
+export type ExemptingStatus = 'draft';
 
 /**
  * Which frontmatter status exempts this file, per contract § 1.
  *
- * `draft` and `carrier` both exempt, and WHICH one is returned rather than a
- * bare boolean: the previous predicate answered "is this exempt" and the gate
- * then printed `draft-exempt` for a carrier, so its own output named a state it
- * had not acted on.
- *
- * A carrier is not a plan. It holds obligations deferred out of an archived
- * parent, each with an unmet resumption trigger, so a plan risk register for it
- * would be manufactured rather than reported. Same category reason that exempts
- * it from `check_roadmap_trackable`'s `## Phase` requirement.
+ * The status is returned rather than a bare boolean so the gate's own output
+ * names the state it acted on. That mattered while `carrier` was a second
+ * exempting value and the predicate printed `draft-exempt` for it; ADR-262
+ * deleted that value, and the shape is kept so a future exemption is one enum
+ * member rather than a re-argued boolean.
  */
 export function exemptingStatus(text: string): ExemptingStatus | null {
     const lines = _splitLines(text);
@@ -350,7 +346,7 @@ export function exemptingStatus(text: string): ExemptingStatus | null {
     for (let i = 1; i < lines.length; i++) {
         const line = lines[i] as string;
         if (line.trim() === '---') return null;
-        const m = /^status:\s*(draft|carrier)\s*$/.exec(line);
+        const m = /^status:\s*(draft)\s*$/.exec(line);
         if (m !== null) return m[1] as ExemptingStatus;
     }
     return null;
@@ -592,7 +588,7 @@ function _blobAt(absPath: string, sha: string): string | null {
     return _git(root, ['show', `${sha}:${rel}`]);
 }
 
-export type FileStatus = 'ok' | 'draft-exempt' | 'carrier-exempt' | 'grandfathered' | 'fail';
+export type FileStatus = 'ok' | 'draft-exempt' | 'grandfathered' | 'fail';
 
 export interface FileResult {
     file: string;
@@ -879,7 +875,7 @@ export function main(argv?: readonly string[]): number {
         for (const p of targets) {
             const result = checkFile(p);
             scanned += 1;
-            if (result.status === 'draft-exempt' || result.status === 'carrier-exempt') {
+            if (result.status === 'draft-exempt') {
                 statusLines.push(`  ${result.status}: ${p}`);
             } else if (result.status === 'grandfathered') {
                 statusLines.push(`  grandfathered: ${p}`);

package/src/scripts/lint_roadmap_blockers.ts

@@ -14,6 +14,19 @@
  *      (`- **Run:**`). A gate that claims to be executable without naming the
  *      command is the same defect as a decision with no option set: it reads
  *      as actionable and is not.
+ *   4. An annotation pointing at a USER-DECISION blocker (one whose `Owner:`
+ *      is the maintainer, the user, or the owner) carries an `asked:` field
+ *      recording whether the question was put and, when it was not, why —
+ *      `<!-- blocked-by: <id> | asked: no — <reason> -->`. A decision only the
+ *      user can make, filed in a roadmap without ever being put, is the defect
+ *      road-to-asked-not-parked exists to stop; without this field a marker
+ *      cannot distinguish a declined decision from an unoffered one.
+ *
+ *      HARD, not ratcheted, and it can be: no active roadmap carries a real
+ *      checkbox annotation today, so on the day it ships the rule fires on
+ *      nothing — the same "no backlog to grandfather" argument the `Class:`
+ *      contract above makes. `later/` and `archive/` are outside this gate's
+ *      glob and are untouched by it.
  *
  * Fenced code blocks are stripped before scanning so a roadmap that shows
  * the `## Blockers` shape as a documentation example is not flagged.
@@ -42,7 +55,19 @@ const BLOCKER_HEADING_RE = /^###[ \t]+blocker:[ \t]*(.+?)[ \t]*$/gim;
 // wrapped continuation line or inline-code documentation example of the
 // syntax (as this very lint script's own roadmap step describes it) must
 // not be mistaken for a live cross-reference.
-const BLOCKED_BY_LINE_RE = /^-[ \t]*\[[ xX~-]\].*<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*-->/i;
+const BLOCKED_BY_LINE_RE =
+    /^-[ \t]*\[[ xX~-]\].*<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[\u2014-][ \t]*([^>]*?))?[ \t]*)?-->/i;
+
+/**
+ * The owners whose blockers are the USER-DECISION class.
+ *
+ * Read off `Owner:` rather than guessed from prose: `terminal-states.md`
+ * defines `blocked` to include "a decision only the user can make", and the
+ * owner field is the only place a roadmap says which blockers those are.
+ * `council`, `implementer` and `agent` are deliberately outside the class —
+ * those are not decisions the user is waiting to be asked.
+ */
+const USER_DECISION_OWNER_RE = /^-[ \t]*\*\*Owner:\*\*[ \t]*(maintainer|user|owner)\b/im;
 
 const REQUIRED_FIELDS: ReadonlyArray<readonly [string, RegExp]> = [
     ['Status', /^-[ \t]*\*\*Status:\*\*/im],
@@ -154,6 +179,7 @@ function _scanBoth(rawText: string): ScanResult {
     const decidability: Violation[] = [];
     const text = _stripFencedCode(rawText);
     const declaredIds = new Set<string>();
+    const userDecisionIds = new Set<string>();
 
     const sectionMatch = BLOCKERS_SECTION_RE.exec(text);
     if (sectionMatch) {
@@ -181,6 +207,9 @@ function _scanBoth(rawText: string): ScanResult {
             declaredIds.add(cur.id);
             const bodyEnd = i + 1 < heads.length ? (heads[i + 1] as { start: number }).start : section.length;
             const body = section.slice(cur.end, bodyEnd);
+            if (USER_DECISION_OWNER_RE.test(body)) {
+                userDecisionIds.add(cur.id);
+            }
             const missing = REQUIRED_FIELDS.filter(([, re]) => !re.test(body)).map(([name]) => name);
             if (missing.length) {
                 violations.push({
@@ -256,6 +285,27 @@ function _scanBoth(rawText: string): ScanResult {
                     `(no matching '### blocker: ${id}' in this file)`,
             });
         }
+        if (userDecisionIds.has(id)) {
+            const asked = m[2] === undefined ? null : (m[2] as string).toLowerCase();
+            const reason = ((m[3] as string | undefined) ?? '').trim();
+            if (asked === null) {
+                violations.push({
+                    line: i + 1,
+                    message:
+                        `blocked-by '${id}' is a user-decision blocker and carries no ` +
+                        'asked: field — write `| asked: yes` when the question was put, ' +
+                        'or `| asked: no — <reason>` when it was not',
+                });
+            } else if (asked === 'no' && reason === '') {
+                violations.push({
+                    line: i + 1,
+                    message:
+                        `blocked-by '${id}' says asked: no with no reason — a marker that ` +
+                        'does not say why the question was never put is the parking lot ' +
+                        'this field exists to end',
+                });
+            }
+        }
     }
     violations.sort((a, b) => a.line - b.line);
     decidability.sort((a, b) => a.line - b.line);

package/src/scripts/mcp_server/suggest_skill.ts

@@ -0,0 +1,72 @@
+/**
+ * The `suggest_skill_for_task` MCP handler, extracted from `tools.ts`.
+ *
+ * `tools.ts` sits ~580 lines past the 1,500-line ceiling `check_source_size_budget`
+ * enforces as a shrink-only ratchet, so every line there costs one unit of excess
+ * and the gate names re-pinning the baseline a defect rather than a fix. Adding a
+ * `skills_roots` field to this handler's answer cost four; extracting the handler
+ * pays that back many times over and puts it in a file where its prose is free.
+ *
+ * Cohesive on its own terms too: this is the one handler in the allowlist that
+ * owns a ranking policy rather than reading a file, and it is the only consumer
+ * of the skill-catalogue resolver on the server side.
+ */
+
+/**
+ * `suggest_skill_for_task` — the recovery path for a truncated catalogue.
+ *
+ * Promoted from a discovery stub because the defect it answers is measured, not
+ * hypothetical: on the one host that publishes its own truncation, a default
+ * install had 402 entries dropped from the model-visible skills list — the
+ * host's own count against its own denominator, not a subtraction over ours.
+ * An agent
+ * that cannot see a skill also cannot ask for it by name, so the only reachable
+ * question is "what fits this task" — which is what the deterministic ranker
+ * answers, over the TREE rather than over the host's catalogue.
+ *
+ * Read-only and shell-free by construction: it reads SKILL.md frontmatter and
+ * returns names, scores and declared personas. No skill BODY is returned — the
+ * caller opens what it picked, so a wrong rank costs one read rather than a
+ * context payload.
+ */
+export async function suggestSkillForTask(
+    args: Record<string, unknown>,
+    consumerRoot: string,
+): Promise<Record<string, unknown>> {
+    const task = typeof args['task'] === 'string' ? args['task'] : '';
+    if (task.trim() === '') {
+        return { status: 'error', error: 'task must be a non-empty string', suggestions: [] };
+    }
+    // `limit`, not `top` — the stub published `limit` and a consumer may have
+    // read that contract already. Renaming it on promotion would break a
+    // caller for cosmetic reasons.
+    const limitRaw = args['limit'];
+    const limit =
+        typeof limitRaw === 'number' && Number.isFinite(limitRaw) ? Math.floor(limitRaw) : 5;
+
+    const catalogue = await import('../_lib/skill_catalogue.js');
+    // EVERY readable root — see `resolveSkillCatalogueRoots` on why not the first.
+    const roots = catalogue.resolveSkillCatalogueRoots(consumerRoot);
+    if (roots.length === 0) {
+        // A missing catalogue is UNKNOWN, never "no skill fits this task". The
+        // second reads as a ranked answer and would be a confident empty list —
+        // the same zero-from-silence failure `capture_skill_catalogue` refuses.
+        return {
+            status: 'no_catalogue',
+            searched: [...catalogue.DEFAULT_CATALOGUE_ROOTS],
+            consumer_root: consumerRoot,
+            suggestions: [],
+        };
+    }
+
+    const { rank } = await import('../skill_tools/score_skill_relevance.js');
+    const rows = rank(task, roots).slice(0, Math.max(1, limit));
+    return {
+        status: 'ok',
+        // `skills_root` kept verbatim (a consumer may read it); `skills_roots` is
+        // the additive truth about what was actually ranked.
+        skills_root: roots[0] as string,
+        skills_roots: roots,
+        suggestions: rows.map(([name, score, personas]) => ({ skill: name, score, personas })),
+    };
+}

package/src/scripts/mcp_server/tools.ts

@@ -47,6 +47,7 @@ import {
     slice_around as _chSliceAround,
     read_header as _chReadHeaderImpl,
 } from '../chat_history.js';
+import { suggestSkillForTask } from './suggest_skill.js';
 import {
     type CatalogEntry,
     install_hint as _catalog_install_hint,
@@ -1210,61 +1211,6 @@ async function _readResourceBodyHandler(
 // unlisted tool. Boot-time stderr log enumerates the registered set.
 // ---------------------------------------------------------------------
 
-/**
- * `suggest_skill_for_task` — the recovery path for a truncated catalogue.
- *
- * Promoted from a discovery stub because the defect it answers is measured, not
- * hypothetical: on the one host that publishes its own truncation, a default
- * install had 402 entries dropped from the model-visible skills list — the
- * host's own count against its own denominator, not a subtraction over ours
- * (`agents/evidence/analysis/scoped-projection-host-delivery.md`). An agent
- * that cannot see a skill also cannot ask for it by name, so the only reachable
- * question is "what fits this task" — which is what the deterministic ranker
- * answers, over the TREE rather than over the host's catalogue.
- *
- * Read-only and shell-free by construction: it reads SKILL.md frontmatter and
- * returns names, scores and declared personas. No skill BODY is returned — the
- * caller opens what it picked, so a wrong rank costs one read rather than a
- * context payload.
- */
-async function _suggestSkillForTaskHandler(
-    args: Record<string, unknown>,
-    consumerRoot: string,
-): Promise<Record<string, unknown>> {
-    const task = typeof args['task'] === 'string' ? args['task'] : '';
-    if (task.trim() === '') {
-        return { status: 'error', error: 'task must be a non-empty string', suggestions: [] };
-    }
-    // `limit`, not `top` — the stub published `limit` and a consumer may have
-    // read that contract already. Renaming it on promotion would break a
-    // caller for cosmetic reasons.
-    const limitRaw = args['limit'];
-    const limit =
-        typeof limitRaw === 'number' && Number.isFinite(limitRaw) ? Math.floor(limitRaw) : 5;
-
-    const catalogue = await import('../_lib/skill_catalogue.js');
-    const skillsDir = catalogue.resolveSkillsRoot(consumerRoot);
-    if (skillsDir === null) {
-        // A missing catalogue is UNKNOWN, never "no skill fits this task". The
-        // second reads as a ranked answer and would be a confident empty list —
-        // the same zero-from-silence failure `capture_skill_catalogue` refuses.
-        return {
-            status: 'no_catalogue',
-            searched: [...catalogue.DEFAULT_CATALOGUE_ROOTS],
-            consumer_root: consumerRoot,
-            suggestions: [],
-        };
-    }
-
-    const { rank } = await import('../skill_tools/score_skill_relevance.js');
-    const rows = rank(task, skillsDir).slice(0, Math.max(1, limit));
-    return {
-        status: 'ok',
-        skills_root: skillsDir,
-        suggestions: rows.map(([name, score, personas]) => ({ skill: name, score, personas })),
-    };
-}
-
 export const ALLOWLIST: Record<string, BuiltinTool> = {
     suggest_skill_for_task: {
         name: 'suggest_skill_for_task',
@@ -1296,7 +1242,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
             },
             additionalProperties: false,
         },
-        handler: _suggestSkillForTaskHandler,
+        handler: suggestSkillForTask,
     },
     lint_skills: {
         name: 'lint_skills',

package/src/scripts/media/lib/adapter-contract.md

@@ -355,8 +355,13 @@ the explicit `dry-run` subcommand:
   `scripts/media/lib/fixtures/<adapter-id>/`.
 - Exit code 0.
 
-Fixtures are committed and cover one happy path per adapter.
-Phase 6 golden runs assert byte-identical stdout under
+Fixtures are committed and cover one happy path per adapter;
+committed media assets are **non-decodable ASCII placeholders**
+whose documented paths and presence, rather than encoded-media
+validity, form the fixture contract. The placeholder literal is
+`FIXTURE-<adapter-id>-<ext>`. A test that needs decodable media
+generates it at runtime — it must not read a fixture expecting
+one. Phase 6 golden runs assert byte-identical stdout under
 `AIV_DRYRUN=true`.
 
 ## Logging & redaction

package/src/scripts/migrate_command_suggestions.ts

@@ -73,7 +73,7 @@ export const ELIGIBLE: Record<string, [string, string]> = {
         'audit my agent docs, check the state of the agents/ directory',
         'stale files under agents/ or recent edits to .augment/ without doc updates',
     ],
-    'analyze-reference-repo': [
+    'analyze-repo': [
         "look at how X does this, compare with that other repo, study this competitor's approach",
         'external repo URL or path mentioned in the prompt',
     ],

package/src/scripts/probe_unblocked_ask.ts

@@ -47,18 +47,40 @@
  * Both edges are printed. A reader who cannot see the bracket cannot judge the
  * number.
  *
+ * The `form` dimension (road-to-asked-not-parked 1.1)
+ *
+ * Every unblocked ask is additionally partitioned by the FORM the ask took:
+ *
+ *   - `native` — the same assistant turn carries a tool call whose name is a
+ *     structured-ask tool (`_lib/structured_ask.ts`, `isStructuredAskTool`).
+ *   - `text`   — everything else, i.e. the ask was prose.
+ *
+ * The two are exhaustive and disjoint by construction, so `text + native`
+ * always equals `unblockedAsks`. That identity is asserted in `--self-test`
+ * rather than left to a reader to check.
+ *
+ * Expect `native` to be **0** on every corpus this repo can scan today: no host
+ * in the capability registry carries an observed structured-ask tool, and
+ * `structured_ask.ts` states why matching on a name-shape pattern is not a claim
+ * that any host ships one. A measured zero and an uninstrumented zero look the
+ * same in a report and are not the same fact — this axis is what makes them
+ * distinguishable later.
+ *
  * Usage:
  *   ./scripts-run src/scripts/probe_unblocked_ask [--limit N] [--store PATH] [--json]
  *   ./scripts-run src/scripts/probe_unblocked_ask --self-test
+ *   ./scripts-run src/scripts/probe_unblocked_ask --help
  *
  * Exit codes: 0 always — a measurement, not a gate. `--self-test` exits 1 when
  * the detector fails to fire on its fixtures.
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { defaultStore, HARNESS_TEXT, isInjectedBody } from './conformance_scan.js';
+import { isStructuredAskTool } from './_lib/structured_ask.js';
 import { isSyntheticPrompt } from './_lib/prompt_shape.js';
 
 /** A numbered-options block — the surface `check_reply_consistency` already reads. */
@@ -88,6 +110,8 @@ interface Turn {
     role: 'user' | 'assistant';
     text: string;
     at: string;
+    /** Tool names invoked in this turn — empty for a user turn. */
+    tools: string[];
 }
 
 function turns(lines: string[]): Turn[] {
@@ -116,10 +140,16 @@ function turns(lines: string[]): Turn[] {
                         .map((b: { text?: string }) => b.text ?? '')
                         .join('\n')
                   : '';
+        const tools = Array.isArray(c)
+            ? c
+                  .filter((b: { type?: string }) => b?.type === 'tool_use')
+                  .map((b: { name?: string }) => String(b?.name ?? ''))
+                  .filter((n: string) => n !== '')
+            : [];
         if (!text.trim()) continue;
         if (role === 'assistant' && HARNESS_TEXT.test(text.trim())) continue;
         if (role === 'user' && (isSyntheticPrompt(text) || isInjectedBody(text))) continue;
-        out.push({ role, text, at: String(e['timestamp'] ?? '') });
+        out.push({ role, text, at: String(e['timestamp'] ?? ''), tools });
     }
     return out;
 }
@@ -139,16 +169,39 @@ export function classifyTail(tail: string): AskVerdict {
     return { unblockedAsk: true, malformed: !RECOMMENDATION.test(tail) };
 }
 
+/** The ask FORM partition. Exhaustive and disjoint: `text + native === unblockedAsks`. */
+export interface FormBreakdown {
+    text: number;
+    native: number;
+}
+
+/**
+ * Which FORM an ask took. `native` iff the turn carried a structured-ask tool
+ * call; `text` otherwise. Exported so the partition is one function rather than
+ * an inline condition a later edit can quietly make non-exhaustive.
+ */
+export function askForm(tools: readonly string[]): 'text' | 'native' {
+    return tools.some((n) => isStructuredAskTool(n)) ? 'native' : 'text';
+}
+
 export interface Result {
     handbacks: number;
     withBlock: number;
     unblockedAsks: number;
     malformed: number;
+    form: FormBreakdown;
     samples: { session: string; at: string; span: string }[];
 }
 
 export function measure(store: string, limit: number): Result {
-    const r: Result = { handbacks: 0, withBlock: 0, unblockedAsks: 0, malformed: 0, samples: [] };
+    const r: Result = {
+        handbacks: 0,
+        withBlock: 0,
+        unblockedAsks: 0,
+        malformed: 0,
+        form: { text: 0, native: 0 },
+        samples: [],
+    };
     let files: string[];
     try {
         files = fs.readdirSync(store).filter((f) => f.endsWith('.jsonl'));
@@ -179,6 +232,7 @@ export function measure(store: string, limit: number): Result {
             const v = classifyTail(tail);
             if (!v.unblockedAsk) continue;
             r.unblockedAsks += 1;
+            r.form[askForm(t.tools)] += 1;
             if (v.malformed) {
                 r.malformed += 1;
                 if (r.samples.length < 5) {
@@ -221,6 +275,52 @@ export function selfTest(): number {
         );
         if (!ok) failed += 1;
     }
+    for (const [tools, want] of [
+        [[], 'text'],
+        [['Bash', 'Read'], 'text'],
+        [['AskUserQuestion'], 'native'],
+        [['ask_user_question'], 'native'],
+    ] as Array<[string[], 'text' | 'native']>) {
+        const got = askForm(tools);
+        const ok = got === want;
+        process.stdout.write(
+            `${ok ? '✅' : '❌'}  form of [${tools.join(', ')}] — ${got}` +
+                (ok ? '\n' : ` (wanted ${want})\n`),
+        );
+        if (!ok) failed += 1;
+    }
+    const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'probe-ask-form-'));
+    try {
+        const mk = (role: string, blocks: unknown): string =>
+            JSON.stringify({ type: role, timestamp: '2026-01-01T00:00:00Z', message: { role, content: blocks } });
+        fs.writeFileSync(
+            path.join(fx, 'fixture.jsonl'),
+            [
+                mk('assistant', [{ type: 'text', text: 'Done.\n\nSoll ich das so umsetzen?' }]),
+                mk('user', 'ja'),
+                mk('assistant', [
+                    { type: 'text', text: 'Done.\n\nShall I take the second half too?' },
+                    { type: 'tool_use', name: 'AskUserQuestion' },
+                ]),
+                mk('user', 'ja'),
+            ].join('\n'),
+            'utf8',
+        );
+        const r = measure(fx, 10);
+        const sums = r.form.text + r.form.native === r.unblockedAsks;
+        process.stdout.write(
+            `${sums ? '✅' : '❌'}  form partition is exhaustive — text ${String(r.form.text)} + ` +
+                `native ${String(r.form.native)} = unblocked ${String(r.unblockedAsks)}\n`,
+        );
+        if (!sums) failed += 1;
+        const split = r.form.text === 1 && r.form.native === 1;
+        process.stdout.write(
+            `${split ? '✅' : '❌'}  the fixture's two asks split one per class\n`,
+        );
+        if (!split) failed += 1;
+    } finally {
+        fs.rmSync(fx, { recursive: true, force: true });
+    }
     const positives = cases.filter((c) => c[3]).length;
     if (positives < 3) {
         process.stderr.write('❌  probe_unblocked_ask --self-test: fewer than 3 positive cases — a truncated suite must fail.\n');
@@ -233,6 +333,32 @@ export function selfTest(): number {
     return failed > 0 ? 1 : 0;
 }
 
+const HELP = `probe_unblocked_ask — the unblocked-ask rate, and the FORM each ask took.
+
+Usage:
+  probe_unblocked_ask [--limit N] [--store PATH] [--json]
+  probe_unblocked_ask --self-test
+  probe_unblocked_ask --help
+
+Dimensions reported:
+  hand-back turns    assistant turns immediately followed by a user turn
+  unblocked asks     …that hand a decision with no numbered-options block
+  malformed          …of those, carrying no Recommendation:/Empfehlung: label
+  form               the ask FORM partition of the unblocked asks:
+                       native  the turn carried a structured-ask tool call
+                       text    the ask was prose
+                     text + native always equals the unblocked-ask total.
+                     native is 0 wherever no host has an observed structured-ask
+                     tool — a measured zero, not an uninstrumented one.
+
+Options:
+  --limit N     most recent N sessions (default 60)
+  --store PATH  transcript store (default: the host's own)
+  --json        emit the Result object instead of the report
+  --self-test   run the detector fixtures, incl. the form-partition identity
+  --help        this text
+`;
+
 export function main(argv: string[]): number {
     let limit = 60;
     let storeArg: string | null = null;
@@ -246,6 +372,10 @@ export function main(argv: string[]): number {
         // in-process, and resolving a transcript store that may not exist here
         // would make the sensitivity proof depend on the host having one.
         else if (a === '--self-test') return selfTest();
+        else if (a === '--help' || a === '-h') {
+            process.stdout.write(HELP);
+            return 0;
+        }
         else {
             process.stderr.write(`probe_unblocked_ask: unrecognized argument: ${a}\n`);
             return 0;
@@ -264,6 +394,9 @@ export function main(argv: string[]): number {
             `  …with a numbered block   ${String(r.withBlock)}  (excluded — check_reply_consistency reads that surface)\n` +
             `  …unblocked asks          ${String(r.unblockedAsks)}  ${pct(r.unblockedAsks, r.handbacks)} of hand-backs\n` +
             `  …of those, malformed     ${String(r.malformed)}  ${pct(r.malformed, r.unblockedAsks)} of unblocked asks\n` +
+            `  form: text               ${String(r.form.text)}  ${pct(r.form.text, r.unblockedAsks)} of unblocked asks\n` +
+            `  form: native             ${String(r.form.native)}  ${pct(r.form.native, r.unblockedAsks)} of unblocked asks\n` +
+            `  form: text + native      ${String(r.form.text + r.form.native)}  (must equal unblocked asks: ${String(r.unblockedAsks)})\n` +
             '\n  CEILING, not a point estimate: "hands a decision" is a heuristic and a\n' +
             '  rhetorical question can match it. A recommendation is matched on its LABEL,\n' +
             '  which is the rule\'s own bar but a bar on form.\n',