@event4u/agent-config 14.20.0 → 14.22.0

package/src/scripts/_lib/release_material.ts

@@ -300,95 +300,45 @@ function _first_diff(a: string, b: string): string {
  * a branch, a PR and a CI run — the exact cost `guard_release_branch_push` was
  * added to avoid for the sibling obligation two releases earlier.
  *
- * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`), which
- * is what lets the writer, the local push guard and the CI gate all reach one
- * definition instead of three copies.
+ * This module has no imports on purpose (see `CURATED_HEAD_INSTRUCTION`).
+ *
+ * **One reader left, as of ADR-261 (2026-09-07).** This paragraph used to say
+ * the definition was shared by "the writer, the local push guard and the CI
+ * gate", which was true while `mix_response_blockers` and
+ * `check_governance_mix_response` scanned a section for this marker. Both are
+ * deleted, and with them every search for it: the only consumer now is
+ * `render_mix_response` in this same file, which WRITES the line. Nothing reads
+ * a changelog looking for it, so do not assume a guard notices when it is
+ * missing — none does.
  */
 export const MIX_RESPONSE_MARKER = '**Governance mix:**';
 
 /**
- * The sentinel that marks an EMITTED-BUT-UNANSWERED response.
- *
- * A generator that emits the measured level alone would satisfy the gate's
- * length floor (`MIX_RESPONSE_MIN_CHARS`, 40) with a number the machine
- * produced, turning a written-answer obligation into a formality the tool
- * discharges for itself. That is a smuggled auto-approval, not a fix.
+ * Render the measured governance-versus-product line the writer emits.
  *
- * So the writer emits the level AND this sentinel, and every gate refuses the
- * sentinel — the same discipline `CURATED_HEAD_INSTRUCTION` and
- * `DERIVED_MARKER` already follow. The net effect is only that the obligation
- * moves from CI to the moment the section is written, where the fix is an edit
- * to a file already open in the working tree.
- */
-export const MIX_RESPONSE_PLACEHOLDER = '<the consumer work>';
-
-/**
- * Every placeholder token the writer emits, so none of them can ship.
+ * ONE line, and machine-written end to end. It reports what the span measured
+ * and asks the releaser for nothing.
  *
- * The block carries two, and refusing only the first would leave
- * `<roadmap or issue>` publishable — `CHANGELOG.md` is in `package.json`
- * `files`, so that is the same "the generator's own scaffolding reached npm"
- * failure `CURATED_HEAD_INSTRUCTION` exists for, one token to the right.
+ * The written-answer obligation is gone (ADR-261). This used to emit a second line — `Next cycle ships <the consumer work>,
+ * tracked in <roadmap or issue>.` — a placeholder no generator was allowed to
+ * fill, backed by four refusals, an interactive prompt, a staging channel under
+ * `## [Unreleased]` and a read-back obligation on the following release. The
+ * releaser had to type prose into a running pipeline to get a version out.
  *
- * A named list rather than a shape match over angle brackets, for the reason
- * that constant already states: a pattern such as `/<[a-z ]+>/` rejects
- * unrelated legitimate prose and misses a reworded placeholder. Adding a token
- * to `render_mix_response` means adding it here.
- */
-export const MIX_RESPONSE_PLACEHOLDERS: readonly string[] = [
-    MIX_RESPONSE_PLACEHOLDER,
-    '<roadmap or issue>',
-];
-
-/**
- * Render the response block the writer emits when the obligation triggers.
+ * The owner ended it: this package exists to make the maintainer's work
+ * cheaper, and a release gate that stops a green pipeline until a human writes
+ * a sentence about a FUTURE cycle is the opposite. The measurement stays
+ * because it is free and true; the homework does not.
  *
- * Two blockquote lines, immediately under the curated head and outside it, per
- * `docs/contracts/CHANGELOG-conventions.md` § Governance-versus-product
- * response — the head's ten-line cap is for product lines, and a sixth label
- * would make every historical section retroactively incomplete.
+ * The removed placeholder constants (`MIX_RESPONSE_PLACEHOLDER(S)`) and promise
+ * sentinels (`PROMISE_PHRASE`, `PROMISE_READBACK_MARKER`, `PROMISE_OUTCOMES`)
+ * are deleted rather than deprecated — a sentinel nothing writes and nothing
+ * refuses is dead weight that reads as live policy.
  */
 export function render_mix_response(level: string): string[] {
-    return [
-        `> ${MIX_RESPONSE_MARKER} ${level}.`,
-        `> ${PROMISE_PHRASE} ${MIX_RESPONSE_PLACEHOLDER}, tracked in <roadmap or issue>.`,
-    ];
+    return [`> ${MIX_RESPONSE_MARKER} ${level}.`];
 }
 
-/**
- * The words that turn a governance response into a PROMISE about a later cycle.
- *
- * Named rather than inlined because two sides now read it: the writer emits it,
- * and the next release reads the previous section for it to decide whether a
- * read-back is owed. A promise nothing reads back costs nothing to restate, so
- * it can be restated for as many cycles as there are cycles — the defect this
- * constant exists to make addressable.
- */
-export const PROMISE_PHRASE = 'Next cycle ships';
-
-/**
- * The marker under which a release head answers the PREVIOUS head's promise.
- *
- * A named sentinel, on the same discipline as `MIX_RESPONSE_MARKER` and
- * `DERIVED_MARKER`: a shape match over prose would accept a sentence that
- * happens to mention last cycle and reject a reworded answer.
- */
-export const PROMISE_READBACK_MARKER = '**Previous cycle:**';
-
-/**
- * The three outcomes a read-back may report, and the reason there are exactly
- * three.
- *
- * `shipped` and `did not ship` are the honest halves of the fact. `withdrawn`
- * exists because a promise the project decided not to keep is a legitimate
- * third state — but only WITH a reason, which is why the answer also has to
- * clear a written-length floor rather than being one of these three words on
- * its own. Without the third state the mechanism would push an author toward
- * restating a dead promise as still-outstanding, which is the failure it is
- * built to stop.
- */
-export const PROMISE_OUTCOMES: readonly string[] = ['shipped', 'did not ship', 'withdrawn'];
-
 /** Every `## X.Y.Z` release version in the file, in document order (newest first). */
 export function changelog_versions(text: string): string[] {
     const out: string[] = [];

package/src/scripts/_lib/retired_status.ts

@@ -0,0 +1,74 @@
+/**
+ * Roadmap `status:` values this repository has RETIRED, and the diagnostic a
+ * reader gets when one survives in a file.
+ *
+ * `status: carrier` was deleted by ADR-262. It had two jobs welded together: a
+ * structural one (this roadmap is the live destination of an archived parent's
+ * `[~]` carries) and an authority one (an autonomous run may not act on it
+ * until a human flips it to `ready`). The second was authored by the repository
+ * about its own maintainer, was enforced by nothing, and contradicted the drain
+ * command's own FORBIDDEN NON-HALT REASONS. The first is a property of the
+ * deferral EDGES, which `lint_deferral_integrity` already verifies from both
+ * ends, so nothing was left for a node-level status to carry.
+ *
+ * Deleting a vocabulary term silently is the failure this module exists to
+ * prevent: an old file would keep a value nothing reads, and the next author
+ * would infer a meaning from its presence. So a retired value is REJECTED with
+ * a migration diagnostic rather than ignored.
+ *
+ * The read is frontmatter-scoped on purpose, and that is inherited rather than
+ * newly decided: a fenced `status: carrier` inside a roadmap documenting the
+ * syntax is not a declaration, and a body-wide match turned exactly that into a
+ * hard failure before a review caught it.
+ */
+
+/** Retired `status:` values, mapped to the record that retired each one. */
+export const RETIRED_STATUS_VALUES: ReadonlyMap<string, string> = new Map([
+    ['carrier', 'ADR-262'],
+]);
+
+/** The leading `---\n…\n---` block, or null when the text carries none. */
+export function frontmatterBlock(text: string): string | null {
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    return m === null ? null : (m[1] ?? '');
+}
+
+/** The frontmatter `status:` value, lower-cased, or null when absent. */
+export function frontmatterStatus(text: string | null | undefined): string | null {
+    if (text === null || text === undefined) {
+        return null;
+    }
+    const fm = frontmatterBlock(text);
+    if (fm === null) {
+        return null;
+    }
+    const m = /^status:[ \t]*([A-Za-z-]+)[ \t]*$/m.exec(fm);
+    return m === null ? null : (m[1] ?? '').toLowerCase();
+}
+
+/**
+ * The retired value this text declares, or null when it declares none.
+ *
+ * Returns the value rather than a boolean so the caller can name it in the
+ * diagnostic — "status: carrier is retired" is actionable, "invalid status" is
+ * not.
+ */
+export function declaresRetiredStatus(text: string | null | undefined): string | null {
+    const status = frontmatterStatus(text);
+    if (status === null) {
+        return null;
+    }
+    return RETIRED_STATUS_VALUES.has(status) ? status : null;
+}
+
+/** The migration diagnostic for a retired value. Names the record and the fix. */
+export function retiredStatusDiagnostic(value: string): string {
+    const record = RETIRED_STATUS_VALUES.get(value) ?? 'a decision record';
+    return (
+        `declares the retired \`status: ${value}\`, deleted by ${record}. ` +
+        'A `status:` value no longer decides whether an autonomous run may act on ' +
+        'a roadmap. Use `status: ready` and put any genuine human-ACTION gate in a ' +
+        '`## Blockers` entry, or park the file under `agents/roadmaps/later/` with ' +
+        'an `entry_condition`. Both are read by a gate; a status is not.'
+    );
+}

package/src/scripts/_lib/skill_catalogue.ts

@@ -75,40 +75,146 @@
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 
-/** Catalogue roots tried in order; the first that exists wins. */
-export const DEFAULT_CATALOGUE_ROOTS = ['.claude/skills', 'src/skills'] as const;
+/**
+ * Catalogue roots under the WORKSPACE, in precedence order.
+ *
+ * `src/skills` is the authored tree and exists only in a maintainer checkout.
+ * `.claude/skills` is the project-scope projection — a consumer's own skills
+ * live there, and so do this repository's flat-command wrappers.
+ */
+export const PROJECT_CATALOGUE_ROOTS = ['src/skills', '.claude/skills'] as const;
+
+/**
+ * The catalogue root under the user's HOME — what the host itself delivers.
+ *
+ * Home-relative rather than workspace-relative, which is why it cannot live in
+ * the list above: `~/.claude/skills` is one directory for every project on the
+ * machine, and on a consumer machine it is where `agent-config install` puts the
+ * shipped skills.
+ */
+export const HOST_CATALOGUE_ROOT = '.claude/skills';
+
+/**
+ * The PROJECTION root, on its own, for the consumers that need exactly it.
+ *
+ * `capture_skill_catalogue` compares what a host DELIVERED against what was
+ * PROJECTED, so the authored tree is the wrong answer for it even though the
+ * ranker wants the authored tree first. Both questions were sharing
+ * `DEFAULT_CATALOGUE_ROOTS` and the 2026-09-07 reorder silently changed the
+ * second one — the finding a neutral review returned the same day. One constant
+ * for two questions is the defect; this is the second question, named.
+ */
+export const PROJECTION_CATALOGUE_ROOT = '.claude/skills';
 
 /**
- * First existing catalogue root under `workspaceRoot`, or `null`.
+ * Every root the resolver looks at, as human-readable LABELS.
+ *
+ * **Labels, never path inputs — this changed on 2026-09-07.**
+ *
+ * It used to be the resolver's own candidate list and callers joined it onto a
+ * root. It now carries a `~/`-prefixed entry, which `path.join(repo, ...)` turns
+ * into `<repo>/~/.claude/skills` — a candidate that can never exist. Use
+ * {@link resolveSkillCatalogueRoots} to RESOLVE and this list only to REPORT
+ * what was searched.
+ *
+ * For the `searched:` / `tried:` fields of the no-catalogue answers only — a
+ * reader needs to know `~` was consulted, and an absolute home path in a
+ * machine-readable payload is both noise and a small privacy leak.
+ */
+export const DEFAULT_CATALOGUE_ROOTS = [
+    ...PROJECT_CATALOGUE_ROOTS,
+    `~/${HOST_CATALOGUE_ROOT}`,
+] as const;
+
+/**
+ * EVERY readable, non-empty catalogue root, in precedence order.
+ *
+ * Shared by the `skill-route` concern and the `suggest_skill_for_task` MCP
+ * handler on purpose: two resolvers over one catalogue is how a ranker and the
+ * tool that exposes it start ranking different trees.
+ *
+ * **Why a LIST, and not the first hit — owner decision, 2026-09-07.**
+ *
+ * This returned one root and stopped at the first match, which made the ranker
+ * see one tree and the session see another. A consumer project can carry its own
+ * skills in `<project>/.claude/skills` while the shipped catalogue sits in
+ * `~/.claude/skills`; first-hit-wins ranked the smaller of the two and reported
+ * the result as if it were the catalogue. Ranking the UNION ranks what the
+ * session can actually reach, which is the only set the answer is about.
+ *
+ * **The order, and what it is for.**
  *
- * `.claude/skills` before `src/skills` because a CONSUMER install carries the
- * former and only a maintainer checkout carries the latter. Shared by the
- * `skill-route` concern and the `suggest_skill_for_task` MCP handler on
- * purpose: two resolvers over one catalogue is how a ranker and the tool that
- * exposes it start ranking different trees.
+ * Precedence applies to a NAME COLLISION, never to which roots are read:
+ *
+ *   1. `src/skills` — the authored tree. In this repository it is the truth, and
+ *      a maintainer editing a skill must see their edit ranked, not the
+ *      projection of the last `generate-tools` run.
+ *   2. `<project>/.claude/skills` — project scope beats machine scope, the same
+ *      direction every other per-project override in this suite takes.
+ *   3. `~/${HOST_CATALOGUE_ROOT}` — the host-global catalogue.
+ *
+ * **The two defects this replaced, both real.**
+ *
+ * It used to try `.claude/skills` FIRST, "because a CONSUMER install carries the
+ * former and only a maintainer checkout carries the latter". The premise was
+ * right and the conclusion did not follow: a consumer has no `src/skills`, so
+ * reading it first costs one `existsSync`.
+ *
+ * The ADR-236 amendment of 2026-09-07 turned that order into a live defect. The
+ * project layer now withholds every skill `~/.claude/skills` carries, so this
+ * repository's `.claude/skills` holds only the ~49 flat-command WRAPPERS —
+ * non-empty, so the old order resolved it, and each wrapper carries a `SKILL.md`,
+ * so nothing downstream could tell it was not the catalogue. Measured the same
+ * day: the `skill-route` hook ranked over 49 command wrappers instead of 299
+ * skills. Under the union those wrappers are still ranked, which is correct —
+ * they are reachable — but they no longer displace the catalogue.
+ *
+ * The non-empty guard keeps its own separate job: an EMPTY root read as a match
+ * made the ranker report an empty catalogue as an empty RESULT, the silent
+ * failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` is about.
+ * Measured in that run: a worktree that had never run `generate-tools` ranked
+ * zero skills and exited 0 on a task that scores 47 against `src/skills`.
+ *
+ * @param home override for the user's home; production callers omit it.
  */
-export function resolveSkillsRoot(workspaceRoot: string): string | null {
-    for (const candidate of DEFAULT_CATALOGUE_ROOTS) {
-        const abs = path.join(workspaceRoot, candidate);
+export function resolveSkillCatalogueRoots(workspaceRoot: string, home?: string): string[] {
+    const userHome = home ?? process.env['HOME'] ?? os.homedir();
+    const candidates = [
+        ...PROJECT_CATALOGUE_ROOTS.map((c) => path.join(workspaceRoot, c)),
+        path.join(userHome, HOST_CATALOGUE_ROOT),
+    ];
+    const roots: string[] = [];
+    const seen = new Set<string>();
+    for (const abs of candidates) {
+        // A workspace that IS the home directory would offer `~/.claude/skills`
+        // twice and rank every skill in it twice. Cheap to exclude, and the
+        // duplicate would be invisible in the output.
+        if (seen.has(abs)) continue;
+        seen.add(abs);
         try {
             if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
-            // NON-EMPTY, and that qualifier is the whole fix. `.claude/skills`
-            // is a gitignored projection, so in a fresh worktree it EXISTS and
-            // holds nothing — and an empty root resolved as a match makes the
-            // ranker report an empty catalogue as an empty RESULT, which is the
-            // silent failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence`
-            // is about, arriving through a second door. Measured in that run: a
-            // worktree that had never run `generate-tools` ranked zero skills
-            // and exited 0 on a task that scores 47 against `src/skills`.
             if (fs.readdirSync(abs).length === 0) continue;
-            return abs;
+            roots.push(abs);
         } catch {
             // Unreadable candidate is not a match; try the next.
         }
     }
-    return null;
+    return roots;
+}
+
+/**
+ * The highest-precedence root, or `null` when none is readable.
+ *
+ * Kept for the surfaces that genuinely name ONE directory — a report line, a
+ * `skills_root` field. Anything that RANKS should take
+ * {@link resolveSkillCatalogueRoots} instead: ranking the first root only is the
+ * defect that function exists to remove.
+ */
+export function resolveSkillsRoot(workspaceRoot: string, home?: string): string | null {
+    return resolveSkillCatalogueRoots(workspaceRoot, home)[0] ?? null;
 }
 
 /** Where observations accumulate. Append-only, one JSON object per line. */
@@ -223,6 +329,35 @@ function descriptionOf(frontmatter: string): string {
  * the order a host listing follows and therefore the order a positional
  * hypothesis is measured against.
  */
+/**
+ * The catalogue as the RANKER sees it — every readable root, first name winning.
+ *
+ * Added 2026-09-07 after a second neutral review. `capture_skill_catalogue`'s D-4
+ * join says it reads "the catalogue the runtime ranker reads", and once the ranker
+ * moved to the union a single-root read stopped being that. Worse, the root the
+ * capture had been pointed at — `.claude/skills` — is the one the ADR-236
+ * amendment EMPTIED of skills: the join then read 49 command wrappers as the
+ * catalogue and published `pointableBare: 0` against `unpointableBare: 16`, a
+ * clean-looking verdict off the wrong tree, with the empty-guard silent because
+ * 49 is not 0.
+ *
+ * Positions are re-derived over the merged list, because a position is a property
+ * of the catalogue the host is shown, not of the root a name came from.
+ */
+export function readCatalogueAcross(roots: readonly string[]): CatalogueEntry[] {
+    const seen = new Set<string>();
+    const merged: CatalogueEntry[] = [];
+    for (const root of roots) {
+        for (const entry of readProjectedCatalogue(root)) {
+            if (seen.has(entry.name)) continue;
+            seen.add(entry.name);
+            merged.push(entry);
+        }
+    }
+    merged.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return merged.map((e, i) => ({ ...e, position: i + 1 }));
+}
+
 export function readProjectedCatalogue(root: string): CatalogueEntry[] {
     // Membership is decided by "does <name>/SKILL.md resolve", never by
     // `Dirent.isDirectory()`. The host-facing projection is a tree of SYMLINKS

package/src/scripts/_lib/structured_ask.ts

@@ -0,0 +1,117 @@
+/**
+ * The structured-ask surface — one shared definition of "a host's own question
+ * tool", read by every consumer that needs it.
+ *
+ * Three consumers exist and they must not each invent their own answer:
+ *
+ *   - `probe_unblocked_ask.ts` partitions hand-back ask turns into `text` and
+ *     `native`, where `native` means the turn carried a call to such a tool.
+ *   - `hooks/one_question_per_ask_hook.ts` denies a call carrying more than one
+ *     question.
+ *   - `_lib/host_capability.ts` carries the boolean `structured_ask` capability;
+ *     the per-host SHAPE lives here rather than in the manifest, because every
+ *     manifest field is a strict boolean that `asBool` coerces — a nested object
+ *     put there would normalize silently to `false`.
+ *
+ * What is observed, and what is a shape guess — the line is drawn explicitly.
+ *
+ * `STRUCTURED_ASK_SHAPES` is **empty**. No host in this repository's registry
+ * carries an observed structured-ask tool, so there is no per-host tool name to
+ * match on, and inventing one from a vendor's documentation is exactly what
+ * `host-capability-manifest.md` § Observation protocol forbids.
+ *
+ * `STRUCTURED_ASK_TOOL_NAME_RE` is therefore a **name-shape pattern, not a host
+ * fact**. It exists so that if such a tool ever appears in a transcript, the
+ * probe MEASURES it rather than missing it — and so the number it reports today
+ * (zero) is a measurement rather than an absence of instrumentation. A reader
+ * must not read a match as evidence that a named host ships that tool; the only
+ * thing that establishes that is an observation written into
+ * `STRUCTURED_ASK_SHAPES` with the protocol's four-part citation.
+ *
+ * Consequence, stated rather than discovered later: `native` is expected to be
+ * **0** on every corpus this repo can scan today. That is the honest reading of
+ * a capability nobody has observed, not a broken detector.
+ */
+
+/** The per-host shape of a structured-ask tool, once one has been OBSERVED. */
+export interface StructuredAskShape {
+    /** The tool name as it appears in a transcript's `tool_use` block. */
+    readonly tool: string;
+    /** How many questions one call may carry. `1` is the shape this repo wants. */
+    readonly max_questions: number;
+    /** How many options one question may offer. */
+    readonly max_options_per_question: number;
+    /** Whether the host's picker admits a free-text answer alongside the options. */
+    readonly free_text: boolean;
+}
+
+/**
+ * Observed per-host structured-ask shapes.
+ *
+ * EMPTY, deliberately. A row is written only from an observation in a real
+ * session under `contexts/execution/host-capability-manifest.md` § Observation
+ * protocol — host · host version · transcript reference · date. Never from a
+ * host's documentation, and never by analogy to another host.
+ */
+export const STRUCTURED_ASK_SHAPES: Readonly<Record<string, StructuredAskShape>> = {};
+
+/** The observed shape for `hostId`, or `undefined` when none has been observed. */
+export function structuredAskShape(
+    hostId: string | null | undefined,
+): StructuredAskShape | undefined {
+    if (hostId === null || hostId === undefined) {
+        return undefined;
+    }
+    return STRUCTURED_ASK_SHAPES[hostId];
+}
+
+/**
+ * Name-SHAPE pattern for a structured-ask tool. See the module header: this is
+ * a matcher, not a claim about any host.
+ */
+export const STRUCTURED_ASK_TOOL_NAME_RE = /^(ask[_-]?user[_-]?question|user[_-]?question|ask[_-]?question)s?$/i;
+
+/**
+ * Is `name` a structured-ask tool call?
+ *
+ * An observed per-host shape wins outright — that is a fact about the host. The
+ * name-shape pattern is the fallback, and it is why the probe can report a
+ * measured zero instead of nothing at all.
+ */
+export function isStructuredAskTool(name: string, hostId?: string | null): boolean {
+    const shape = structuredAskShape(hostId);
+    if (shape !== undefined) {
+        return name === shape.tool;
+    }
+    return STRUCTURED_ASK_TOOL_NAME_RE.test(name);
+}
+
+/**
+ * How many questions a structured-ask tool payload carries.
+ *
+ * Returns `-1` when the payload's shape is not recognised at all — a caller
+ * that gates on this must treat `-1` as "cannot tell", never as "one". The two
+ * recognised shapes are the only ones a picker can plausibly use: an array of
+ * question objects under a `questions`-like key, or a single question field.
+ *
+ * A `questions` array of length 0 is 0, not 1: an empty ask is malformed and a
+ * gate should be able to say so.
+ */
+export function countStructuredAskQuestions(input: unknown): number {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return -1;
+    }
+    const src = input as Record<string, unknown>;
+    for (const key of ['questions', 'question_list', 'items', 'prompts']) {
+        const v = src[key];
+        if (Array.isArray(v)) {
+            return v.length;
+        }
+    }
+    for (const key of ['question', 'prompt', 'header']) {
+        if (typeof src[key] === 'string' && (src[key] as string).trim() !== '') {
+            return 1;
+        }
+    }
+    return -1;
+}