@event4u/agent-config 14.10.0 → 14.12.0

package/dist/scripts/project_thin_rules.js

@@ -63,6 +63,31 @@ export function kernel_ids() {
     }
     return new Set();
 }
+/**
+ * Tier rules the router gives NO trigger at all.
+ *
+ * These cannot be delivered on a match, so thinning them would remove a body
+ * that nothing can ever put back — a silent hole rather than a saving. They
+ * project full-bodied, and `measure` reports them by name so the residue is
+ * visible instead of being absorbed into the pointer count
+ * (road-to-trigger-delivered-rule-bodies 1.3).
+ */
+export function no_trigger_ids() {
+    const data = JSON.parse(fs.readFileSync(ROUTER, 'utf-8'));
+    const out = new Set();
+    for (const tier of ['tier_1', 'tier_2']) {
+        const entries = data[tier];
+        if (!Array.isArray(entries))
+            continue;
+        for (const e of entries) {
+            const obj = e;
+            const t = obj.triggers;
+            if (!Array.isArray(t) || t.length === 0)
+                out.add(String(obj.id));
+        }
+    }
+    return out;
+}
 /**
  * id → workspaces for every non-kernel router entry (router.json schema v2,
  * road-to-request-scoped-rule-load Phase 1). Rules absent from the map (or
@@ -168,6 +193,7 @@ export function thin_entry(rule_id, text) {
 /** Map {filename: thin_or_full_text} for every rule. Kernel stays full. */
 export function build_thin(rules_dir = RULES_SOURCE, scope = null) {
     const kernel = kernel_ids();
+    const noTrigger = no_trigger_ids();
     const wsMap = scope !== null ? rule_workspaces_map() : new Map();
     const out = new Map();
     for (const p of _globSortedMd(rules_dir)) {
@@ -176,7 +202,8 @@ export function build_thin(rules_dir = RULES_SOURCE, scope = null) {
         if (!id_in_scope(stem, scope, kernel, wsMap, fm_workspaces(text))) {
             continue; // out of workspace scope — no body, no pointer line
         }
-        out.set(path.basename(p), kernel.has(stem) ? text : thin_entry(stem, text));
+        const full = kernel.has(stem) || noTrigger.has(stem);
+        out.set(path.basename(p), full ? text : thin_entry(stem, text));
     }
     return out;
 }
@@ -215,13 +242,22 @@ export function measure(rules_dir = RULES_SOURCE, scope = null) {
             kernelInDir += 1;
         }
     }
+    const noTrigger = no_trigger_ids();
+    const residueIds = [...noTrigger].filter((id) => stemSet.has(id)).sort();
+    const residueBlob = residueIds
+        .map((id) => fs.readFileSync(path.join(rules_dir, `${id}.md`), 'utf-8'))
+        .join('');
+    const residueGpt = residueIds.length === 0 ? 0 : token_count.measure(residueBlob).tokens_gpt;
     const saved_pct = eager.tokens_gpt
         ? _python_round1((100 * (eager.tokens_gpt - thin.tokens_gpt)) / eager.tokens_gpt)
         : 0.0;
     return {
         rules_total: n,
         kernel_full: kernelInDir,
-        non_kernel_thinned: n - kernelInDir,
+        non_kernel_thinned: n - kernelInDir - residueIds.length,
+        no_trigger_full: residueIds.length,
+        no_trigger_ids: residueIds,
+        no_trigger_gpt: residueGpt,
         eager_gpt: eager.tokens_gpt,
         thin_gpt: thin.tokens_gpt,
         saved_gpt: eager.tokens_gpt - thin.tokens_gpt,
@@ -419,6 +455,8 @@ export function main(argv = null) {
         process.stdout.write(`  thin:  ${_rjust6(m.thin_gpt)} GPT tok (${_comma(m.thin_chars)} chars)\n`);
         process.stdout.write(`  saved: ${_rjust6(m.saved_gpt)} GPT tok  (${m.saved_pct}% of the rule layer)\n`);
         process.stdout.write(`  method: ${m.token_method}\n`);
+        process.stdout.write(`  no-trigger residue (kept full-bodied, ${m.no_trigger_full} rules, ` +
+            `${m.no_trigger_gpt} GPT tok): ${m.no_trigger_ids.join(', ')}\n`);
     }
     return 0;
 }

package/dist/server/schemas/settings.js

@@ -266,12 +266,18 @@ export const settingsSchema = z.object({
         design_slop: z.object({
             enabled: z.boolean().default(false).describe('PreToolUse anti-slop nudge (road-to-anti-slop-detector Phase 3). Default off. When on, runs the lint_design_slop registry against about-to-be-written UI content and WARNS (never blocks) on P0/P1 aesthetic tells (side-stripe, gradient-text, magic z-index, …). Flags are rebuttable via DESIGN.md / design-slop-disable. Anti-loop: a file::rule signature surfaced 3x goes silent. Host-limited convenience layer; the universal gate is the lint_design_slop linter/CI.'),
         }).default({}),
+        design_pass: z.object({
+            enabled: z.boolean().default(false).describe('PostToolUse + stop design pass (road-to-frontend-power E1.1/E1.2/E1.3). Default off. One concern on two slots: on post_tool_use a write to a UI surface delivers the design findings as context and never blocks; on stop the same pass runs over every UI file touched this session, deduped against what the post pass surfaced, and a P0 objective floor (contrast, font size, heading skip, focus) blocks with a continuation. P1-P3 never block. post_tool_use rather than pre_tool_use for two measured reasons: pre_tool_use is declared by three hosts and honoured by one while post_tool_use is declared by six, and _lib/ui_surface.ts is a path predicate, so a pre-write gate cannot fire on the first write of a new surface. A pass that could not fully run reports verification: degraded with a reason rather than passing silently. Does not replace design_slop: two design keys is the honest state until the tiering experiment has a number.'),
+        }).default({}),
         ui_route_nudge: z.object({
             enabled: z.boolean().default(false).describe('PreToolUse UI-route nudge (road-to-frontend-skill-application Phase 4). Default off. When on, a Write/Edit to a UI surface with no design consultation latched this session WARNS (never blocks) naming the route — run existing-ui-audit, then the fe-design loop. A read or search touching fe-design / existing-ui-audit / design-review / design-intelligence latches consultation and silences it for the session. Anti-loop: at most 2 nudges per session. It does not read the rules: the UI-surface decision comes from _lib/ui_surface.ts and no code parses rule frontmatter, so this runs parallel to the two UI rules rather than consuming their triggers, and a test keeps the sets from drifting. It is a nudge, so their enforced_by: none stays accurate.'),
         }).default({}),
         code_graph: z.object({
             enabled: z.boolean().default(false).describe('PreToolUse code-graph nudge (ADR-124 Phase 4). Default off. When on AND a native code-graph cache or a consumer-shipped graph.json/SCIP index is present, warns once per session (never blocks) as the agent is about to Grep/Glob or Read a source file — query the graph first for who-calls/where-used/impact questions (or rebuild if stale, build if absent). Source G’s strict block-first-read mode is deliberately un-ported.'),
         }).default({}),
+        suggestion_capture: z.object({
+            enabled: z.boolean().default(false).describe('Suggestion-block capture (road-to-suggestion-block-capture Phase 2). Default off. Two slots: `stop` reads `last_assistant_message` — a payload field, so no transcript file is read — and latches that the assistant turn carried a numbered-options block; `user_prompt_submit` CONSUMES that latch and classifies the answering turn as option_n / as_is / other / stale_block. Consume-once is the correctness guard: the latch is deleted on read, so a bare "1" three turns later meets no latch and classifies `other`, and a latch past its TTL or unparseable is `stale_block` rather than a guess. Writes COUNTS ONLY to agents/runtime/state/audit/suggestion-capture.jsonl — the record type has no field able to hold a prompt, an option label or a command name, and a test asserts the written key set against src/config/suggestion-capture.json. Off by default because this is an INSTRUMENT rather than a feature: it exists so a capture rate can be measured on a maintainer workspace over a fixed soak window, and there is nothing in it for a consumer to gain.'),
+        }).default({}),
         // `turn_end_gate` is deliberately ABSENT. The stop-slot turn-end gate is
         // always armed (2026-08-12) and has no settings surface: whether it
         // fires is decided by each detector's own trigger conditions, not by a

package/dist/shared/skillRanking.js

@@ -0,0 +1,159 @@
+/**
+ * skillRanking — the ONE definition of "how relevant is this skill to this task".
+ *
+ * WHY IT LIVES HERE. Two callers need the identical answer and were about to
+ * grow two implementations of it:
+ *
+ *   - `src/scripts/skill_tools/score_skill_relevance.ts` — the disk-reading
+ *     ranker behind the kernel MCP server's `suggest_skill_for_task` and the
+ *     `skill-route` hook.
+ *   - `src/cli/mcp/dispatch.ts` — the turnkey stdio server, which must stay a
+ *     pure function of its in-memory content tree and therefore cannot call a
+ *     module that walks the file system.
+ *
+ * `road-to-skill-delivery-over-mcp` risk 6 names that fork by name: "two
+ * implementations of `suggest_skill_for_task` diverge silently". The fix is to
+ * put the formula in one Node-free module both can import, which is what this
+ * is. `src/shared/` is the only directory in the tree that both `src/scripts/`
+ * and `src/cli/` already import from, and it is required to stay Node-free —
+ * exactly the constraint the pure dispatcher needs.
+ *
+ * THE FORMULA IS UNCHANGED. It is the Python-parity scorer ported in ADR-200,
+ * moved rather than rewritten: `score = round(term_overlap * 70 + persona_hit *
+ * 30)`, half-to-even, over tokens of the skill's `name + description`. The
+ * `score_skill_relevance` CLI's argparse-parity suite is the check that the move
+ * changed nothing.
+ *
+ * THE ONE ADDITION is `triggerTerms`, off by default. Phase 3.1 of the same
+ * roadmap indexes `triggers.keyword` / `triggers.phrase` text; it is an opt-in
+ * parameter rather than a second function so the two rankers can be measured
+ * against each other on one corpus.
+ *
+ * Pure — no imports, no I/O, no clock.
+ */
+// re.compile(r"[a-z][a-z0-9]+") — applied to the lowercased text.
+const TOKEN_RE = /[a-z][a-z0-9]+/g;
+/** Ported verbatim from the Python scorer. Order is irrelevant; membership is not. */
+export const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'of', 'for', 'with', 'to', 'in',
+    'on', 'at', 'by', 'from', 'as', 'is', 'are', 'was', 'were', 'be', 'been',
+    'this', 'that', 'these', 'those', 'it', 'its', 'use', 'when', 'even',
+    'via', 'via:', 'into', 'onto', 'use:', 'skill', 'skills', 'task', 'tasks',
+    'code', 'file', 'files', 'doing', 'make', 'do', 'go', 'get', 'set',
+    'not', 'no', 'yes', 'any', 'some', 'all', 'one', 'two', 'new', 'old',
+    'user', 'users', 'our', 'your', 'their', 'they', 'we', 'you', 'i', 'me',
+]);
+/** Mirror Python `len(str)` — count Unicode code points, not UTF-16 units. */
+function pyLen(s) {
+    let n = 0;
+    for (const _ of s)
+        n++;
+    return n;
+}
+/** Mirror Python `round(x)` — half-to-even. Exact for integral ndigits. */
+export function roundHalfToEven(x) {
+    if (!Number.isFinite(x))
+        return x;
+    const floor = Math.floor(x);
+    const frac = x - floor;
+    if (frac < 0.5)
+        return floor;
+    if (frac > 0.5)
+        return floor + 1;
+    return floor % 2 === 0 ? floor : floor + 1;
+}
+/** Lowercase, extract `[a-z][a-z0-9]+`, drop stopwords and tokens of ≤2 code points. */
+export function tokenize(text) {
+    const out = new Set();
+    const matches = text.toLowerCase().match(TOKEN_RE) ?? [];
+    for (const t of matches) {
+        if (!STOPWORDS.has(t) && pyLen(t) > 2)
+            out.add(t);
+    }
+    return out;
+}
+/**
+ * Which `triggers[]` keys carry INDEXABLE PROSE.
+ *
+ * `file_pattern`, `path_prefix` and `command` are match *mechanisms*, not text a
+ * prompt is compared against: folding a glob in would put tokens like `blade` and
+ * `php` on every skill that merely watches a path. `reason` documents the trigger
+ * for a human and is not part of what it matches. The policy lives here because
+ * two different readers apply it to two different input shapes — parsed YAML
+ * objects in `src/cli/mcp/content.ts`, flat `key: "value"` lines in the
+ * frontmatter reader of `score_skill_relevance.ts` — and only the DECISION is
+ * shared, not the parsing.
+ */
+export const INDEXED_TRIGGER_KEYS = ['keyword', 'phrase'];
+/**
+ * Trigger prose out of flat `key: "value"` frontmatter lines.
+ *
+ * The stdlib-only frontmatter reader in `score_skill_relevance.ts` flattens
+ *   triggers:
+ *     - phrase: "authorization check"
+ * to the single string `phrase: "authorization check"`, so this takes that shape
+ * rather than an object. Anything whose key is not indexable is dropped.
+ */
+export function triggerTextFromFlatLines(lines) {
+    const out = [];
+    for (const line of lines) {
+        const m = /^([a-zA-Z_][\w-]*)\s*:\s*(.*)$/.exec(String(line).trim());
+        if (!m)
+            continue;
+        if (!INDEXED_TRIGGER_KEYS.includes(m[1]))
+            continue;
+        const value = m[2].trim().replace(/^["']|["']$/g, '');
+        if (value)
+            out.push(value);
+    }
+    return out;
+}
+/** The indexed term set for one skill, under the given options. */
+export function skillTerms(skill, opts = {}) {
+    const parts = [skill.name, skill.description];
+    if (opts.includeTriggers && skill.triggerText)
+        parts.push(...skill.triggerText);
+    return tokenize(parts.join(' '));
+}
+/**
+ * The score. `taskTerms` is `tokenize(task)`; `terms` is `skillTerms(skill)`.
+ *
+ * Both are passed in rather than derived here so a caller ranking N skills
+ * tokenizes the task once and each skill once, which is what makes this usable
+ * on a per-prompt hook path.
+ */
+export function scoreSkill(taskTerms, skill, terms) {
+    if (taskTerms.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of taskTerms)
+        if (terms.has(t))
+            inter++;
+    const overlap = inter / Math.max(taskTerms.size, 1);
+    let personaHit = 0;
+    const taskLower = [...taskTerms].join(' ');
+    for (const persona of skill.personas ?? []) {
+        const slug = String(persona).toLowerCase();
+        if (taskLower.includes(slug) || slug.split('-').some((part) => taskTerms.has(part))) {
+            personaHit = 1;
+            break;
+        }
+    }
+    return roundHalfToEven(overlap * 70 + personaHit * 30);
+}
+/**
+ * Rank an in-memory skill set. Zero scores are dropped; ties break on name, so
+ * the result is a total order and two callers with the same input agree.
+ */
+export function rankSkills(task, skills, opts = {}) {
+    const taskTerms = tokenize(task);
+    const rows = [];
+    for (const skill of skills) {
+        const score = scoreSkill(taskTerms, skill, skillTerms(skill, opts));
+        if (score > 0)
+            rows.push({ name: skill.name, score, personas: [...(skill.personas ?? [])] });
+    }
+    rows.sort((a, b) => (b.score - a.score) || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return rows;
+}
+//# sourceMappingURL=skillRanking.js.map

package/docs/contracts/provider-lifecycle.md

@@ -107,25 +107,54 @@ A Python pre-run gate enumerating tier-by-command rules would either be too coar
 
 The CI guarantee is structural reachability — the linter would fail if a provider was declared in `agents/templates/.ai-video.xml.example` without a lifecycle tag (extension planned). It does not enforce the runtime obligation; the agent does.
 
-## § 5 — Day-one assignment
-
-The five shipped adapters carry the following tiers on the day
-this contract lands (PR `universal-platform-refinement`):
-
-| Adapter | Kind | Tier | Rationale |
+## § 5 — Current tier assignment (generated)
+
+**The previous table here was scoped, not wrong.** It stated the tiers "on the
+day this contract lands", and on that day all five shipped adapters really were
+`experimental`. Seven adapters were promoted on 2026-06-10 and § 5b below
+already deferred promotion to "the commit that records a trace", so the
+snapshot became a stale *reading* of a correct sentence — which a reader still
+trips over, because a table in a contract is read as the current state whatever
+its preamble says. It is now generated, so it cannot drift again.
+
+The evidence column is the reviewer-reachable one:
+`agents/evidence/ai-video/trace-index.json` carries a five-field row per local
+smoke trace (provider · trace_id · captured_at · model · sha256). The raw
+traces stay local-only by the decision in `d7f5d5d3c`, reaffirmed by AI council
+on 2026-08-23; the index is what makes a `stable` claim checkable from a clone
+without publishing one request body. `lint_adapter_tier` fails the build when a
+`stable` header has no row inside its 180-day window.
+
+<!-- DO NOT EDIT BY HAND — generated by `npx tsx src/scripts/lint_adapter_tier.ts --table`.
+     Verified against the tree by `lint_adapter_tier --check-contract`. -->
+<!-- BEGIN GENERATED: adapter-tier-table -->
+| Adapter | Domain | Tier | Freshest reachable trace |
 |---|---|---|---|
-| `openai-images` | image | `experimental` | Structural shape conformant; no maintainer real-API smoke captured yet |
-| `gemini-veo` | video | `experimental` | Default video provider; no real-API smoke captured yet |
-| `kling` | video | `experimental` | Async contract conformant; no maintainer real-API smoke captured yet |
-| `higgsfield` | image+video | `experimental` | Capability-discovery path conformant; no real-API smoke captured yet |
-| `sora` | video | `experimental` | Structural-prompt path conformant; no real-API smoke captured yet |
-
-**All five start as `experimental` on day one.** The promotion to
-`stable` happens per-adapter, on the commit that records the first
-real-API smoke trace. This is conservative by construction: a
-`/video:*` run today resolves to a default that is `experimental`,
-so the agent surfaces the tier and asks before proceeding — the
-human is the policy decision point.
+| `comfyui` | ai-video | `experimental` | — (none in the index) |
+| `fal` | ai-video | `stable` | `2026-06-10T14-59-22Z` (9 row(s)) |
+| `gemini-veo` | ai-video | `stable` | `2026-06-10T20-13-26Z` (18 row(s)) |
+| `higgsfield` | ai-video | `stable` | `2026-06-10T20-39-34Z` (6 row(s)) |
+| `kling` | ai-video | `stable` | `2026-06-10T14-59-22Z` (3 row(s)) |
+| `musetalk` | ai-video | `experimental` | — (none in the index) |
+| `openai-images` | ai-video | `stable` | `2026-06-10T20-39-34Z` (4 row(s)) |
+| `replicate` | ai-video | `stable` | `2026-06-10T14-59-22Z` (15 row(s)) |
+| `sora` | ai-video | `stable` | `2026-06-10T20-39-34Z` (2 row(s)) |
+| `syncso` | ai-video | `experimental` | — (none in the index) |
+| `flux` | ai-image | `experimental` | — (none in the index) |
+| `gemini-image` | ai-image | `experimental` | — (none in the index) |
+| `ideogram` | ai-image | `experimental` | — (none in the index) |
+| `recraft` | ai-image | `experimental` | — (none in the index) |
+<!-- END GENERATED: adapter-tier-table -->
+
+## § 5b — Promotion stays maintainer-authored
+
+The promotion to `stable` happens per-adapter, on the commit that records the
+first real-API smoke trace. This is conservative by construction: a `/video:*`
+run against an `experimental` default makes the agent surface the tier and ask
+before proceeding — the human is the policy decision point. `lint_adapter_tier`
+checks that a claim resolves to dated evidence; it never promotes or demotes an
+adapter, because a tier is a maintainer claim and silently rewriting one would
+be the drift it exists to stop.
 
 The `<default-image-provider>` and `<default-video-provider>`
 entries in `agents/templates/.ai-video.xml.example` remain unchanged

package/docs/contracts/settings-classes.md

@@ -242,8 +242,8 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 26 |
 | B — consent | 3 |
-| C — guarded | 107 |
-| **Total** | **136** |
+| C — guarded | 109 |
+| **Total** | **138** |
 
 The total was 140 until 2026-08-12, when five of the six keys no code path read were
 deleted, minus the one held open (§ The six unread keys, below): one A
@@ -257,6 +257,34 @@ It rose to 136 on 2026-08-20 when `road-to-gate-autonomy`'s
 first keys added to this contract since the deletions above, and both are C on
 test 1 (money).
 
+It rose to 138 on 2026-08-24 when `road-to-suggestion-block-capture` Phase 2
+added `hooks.suggestion_capture.enabled`. C on test 1 — it configures code that
+runs at every turn end and every prompt — and the third `hooks.*` key here.
+
+Its disposition is **`consent`**, and the first draft of this row said
+`derivable`, which was wrong in the way the disposition axis exists to catch. The
+`derivable` argument was that the sink's own line count answers whether the soak
+window is running — true, and it answers the wrong question. What the key
+authorises is *the package observing this operator's turns and writing a record
+of them*, and no predicate computes whether someone consents to that. The
+`derivable-surface` ratchet caught it immediately: it is shrink-only, so a new
+`derivable` key reds by construction, and being unable to add one is the
+mechanism working rather than an obstacle.
+
+The distinction against its `design_pass` neighbour still holds and is the reason
+this is not `policy` either: that concern can **block**, so arming it is a risk
+preference. This one only observes and exits 0 on every path — the question is
+not risk, it is permission.
+
+It rose to 137 on 2026-08-23 when `road-to-frontend-power` E1.1–E1.3 added
+`hooks.design_pass.enabled`. C on test 1 (it configures code that runs on every
+tool call and at every turn end), and the only hook key in this contract whose
+concern can **block** rather than warn — which is why the class matters here
+more than for its two `hooks.*` neighbours. The disposition is `policy`, not
+`derivable`, and the block is why: whether an operator accepts a gate that can
+refuse a turn is a risk preference, and no predicate computes it. Its two
+`hooks.*` neighbours are `derivable` because they only ever warn.
+
 The total is every leaf in the template, where *leaf* means anything that is not
 a **non-empty** map. An empty map (like the former `subagents.host_capabilities: {}`) is a real
 configurable value with a real default, so such keys count as leaves here — one row more than
@@ -305,9 +333,9 @@ the template, which is the drift this contract exists to prevent.
 |---|---|
 | derivable | 83 |
 | un-inferrable | 9 |
-| consent | 39 |
-| policy | 5 |
-| **Total** | **136** |
+| consent | 40 |
+| policy | 6 |
+| **Total** | **138** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -523,7 +551,9 @@ Rows follow template order, so a diff against the template reads straight down.
 | `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call | derivable — the live PATH and identity probe the hook already runs; silent when rtk is absent |
 | `hooks.design_slop.enabled` | C | `false` | configures code that runs on every tool call | derivable — the rule-registry match plus the hook's own per-signature silence cap |
 | `hooks.ui_route_nudge.enabled` | C | `false` | configures code that runs on every tool call | derivable — the UI-surface predicate plus the hook's own two-nudges-per-session cap |
+| `hooks.design_pass.enabled` | C | `false` | C-test 1 — it configures code that runs on every tool call and at every turn end, and unlike its two `hooks.*` neighbours its stop pass can BLOCK rather than warn | policy — whether an operator accepts a gate that can refuse a turn is a risk preference, not a fact the tree can compute. The two neighbours are `derivable` because they only ever warn; the block is the discriminator. `road-to-frontend-power` transfers the default flip to the owner for the same reason |
 | `hooks.code_graph.enabled` | C | `false` | configures code that runs on every tool call | derivable — the index-detection probe the nudge already runs; no index means silence |
+| `hooks.suggestion_capture.enabled` | C | `false` | configures code that runs at every turn end and every prompt | consent |
 | `decision_engine.surface_traces` | C | `false` | the decision engine’s own black box; the agent must not be able to close it | derivable — the engine's own active-gate state; there is nothing to surface when no gate fired |
 | `decision_engine.min_confidence` | C | `"off"` | the confidence gate | derivable — the confidence band the scoring engine already computes at the plan phase |
 | `decision_engine.block_on_risk` | C | `"off"` | the risk-class gate | derivable — the risk class the engine already computes at the implement phase; the Hard Floor covers the irreversible end unconditionally |

package/docs/guidelines/agent-infra/context-hygiene-mechanics.md

@@ -114,3 +114,52 @@ reply. The bug is not the sleep or the grep: **absence of the word `pending`
 was treated as evidence of completion**, and an error is neither settled nor
 pending. The exit condition is the part that is easy to get wrong, so it lives
 in one place rather than in every agent's head.
+
+## Waiting is one waiter — why the loop test misses it
+
+Migrated from [`context-hygiene`](../../../src/rules/context-hygiene.md)
+§ *Waiting is one waiter, never a fleet* under the P4 pattern
+(`road-to-standing-payload-diet` step 1.3). The rule keeps the Iron Law, the
+one-waiter instruction and the enforcement verdict; the argument for them is
+here.
+
+The loop test in that rule fails on waiting in **both** of its clauses:
+
+- **"Same parameters" fails.** A `sleep 240` followed by `sleep 420` followed by
+  `sleep 595` are three different calls by any parameter comparison, so nothing
+  reads them as repetition.
+- **"Repetition without new information" fails too**, and this is the subtler
+  half: the poll genuinely returns a different value each round — 31 green, then
+  34, then 36 — which *feels* like progress. It is not information unless a
+  different digit would make you act differently. It would not: the only actions
+  available were wait, or stop and report, and 34 licensed neither more than 31
+  did. **The discriminator is the decision, not the digits.**
+
+So state it separately: pick **one** waiter for the condition and let it finish.
+Where the harness re-invokes on completion, waiting costs nothing and polling
+costs a turn per expiry — and every stacked waiter is a turn that arrives *after*
+the answer already did. Where it does not, one `until <condition>` loop is still
+one call rather than N.
+
+**Measured once, at n=1, and worth naming for its shape rather than its
+frequency** (2026-08-12): a CI wait started roughly 35 background commands —
+a fresh timer *and* a fresh condition-watcher per round, none cancelled when the
+next pair started. CI settled with about fifteen still live; each then expired
+and produced an empty turn. Nothing was corrupted, which is exactly why it ran
+so long: every individual step looked reasonable.
+
+**Enforcement: none, and the reason is structural.** The `context-hygiene` hook
+counts tool calls; a waiter is indistinguishable from any other call at that
+layer, and nothing in the envelope says two live waiters are watching one
+condition. This is model-carried on every host.
+
+## The declared-protocol cap — why 8, and when it changes
+
+Migrated from [`context-hygiene`](../../../src/rules/context-hygiene.md)
+§ *Declared read protocol* under the same pattern. The rule keeps the cap and the
+three-field declaration contract; the honesty note about the number is here.
+
+> **The 8 is a guess, and specifically a LOWER BOUND.** One observed run — the coherence audit that motivated this clause — needed 8+ read turns and was legibly the protocol working, not a loop. So 8 is "the number that was enough once", not a measured optimum: n=1 says almost nothing about where the tail of the distribution sits, and nobody knows how many sessions silently hit the old 5 and should have continued. Calling this a derivation would be false advertising, which is the same failure class as the "17 rules carry absolutes" figure this rule's own roadmap refuted.
+> **Revisit-if — whichever comes first:** (a) **≥ 10 declared-protocol sessions** have been observed, at which point set the cap from their p95 and delete this note; or (b) **90 days** elapse with fewer than 10, which is itself the answer — declared protocols are rare, the cap is not load-bearing, and it drops back to the undeclared 5. A condition like "once a distribution exists" was rejected as unfalsifiable: it is gradual, never feels urgent, and absence of complaints is indistinguishable from absence of measurement. <!-- enforcement-count-ok: not an enforcement denominator — the 10 is a revisit threshold for observed declared-protocol read sessions and the 90 a calendar deadline; neither is a count of rules, obligations, or covered platforms, so there is no resolver output to cite instead -->
+
+

package/docs/guidelines/agent-infra/downstream-changes-mechanics.md

@@ -0,0 +1,91 @@
+# Downstream-Changes Mechanics — closed-set evolution
+
+> The procedure behind [`downstream-changes`](../../../src/rules/downstream-changes.md)
+> for one change class its table does not reach: a **closed set** whose member
+> list changed. Cited by `skill:code-review` (the propagation dimension) and
+> `skill:code-refactoring` (the reference sweep).
+>
+> It lives here rather than in the rule for a measured reason. Project-scope
+> rules are a gated bucket of the per-spawn standing payload, and that payload
+> currently measures **at** its grace ceiling
+> (`src/config/preamble-payload-budget.json`), so the rule cannot grow by a
+> single line without reddening `check_preamble_payload_budget`. Guidelines are
+> an excluded bucket — read on demand, not re-sent per spawn. The obligation is
+> therefore carried by the two skills that fire at the moment it matters, and
+> the rule keeps its current size until a reduction lands.
+
+## The Iron Law
+
+```
+CHANGING A MEMBER OF A CLOSED SET IS NEVER DONE WHEN THE TYPE COMPILES.
+EVERY CONSUMER IS CLASSIFIED: EXHAUSTIVE, DELIBERATE FALLBACK, OR MISSING CASE.
+A `default` THAT SWALLOWS THE NEW MEMBER IS A MISSING CASE WEARING A BRANCH.
+```
+
+## Why the ordinary sweep misses it
+
+`downstream-changes` enumerates callers, tests, imports, type definitions,
+config bindings, routes and docs — all of which are found by searching for the
+**identifier**. A closed set breaks that assumption: the member list changes,
+the type still compiles, and a serializer, a badge variant, an OpenAPI schema or
+a transition table silently keeps the old set. None of them names the type, so
+no identifier search reaches them. This is the shotgun-surgery shape — one
+conceptual change scattered across many small sites, where forgetting one is the
+default outcome rather than the unlucky one.
+
+## What counts as a closed set
+
+PHP enums · TypeScript enums · discriminated unions · literal-union state types ·
+Rust enums · sealed types · Python `enum` classes · DB enum and check
+constraints · OpenAPI / JSON-Schema `enum` · state machines · role and permission
+sets · finite component variants.
+
+## Discover by shape, not by identifier
+
+- the member name and its **backing value** (the wire value often differs);
+- `match` / `switch` / if-chains over the type;
+- `Record<Member, …>`, lookup tables and maps keyed by it;
+- `cases()` / `values()` iteration;
+- validators and serializers;
+- DB constraints and migrations;
+- API schemas;
+- UI option sources and variant maps;
+- translation keys;
+- tests, factories and fixtures.
+
+## Classify every hit — three outcomes, one defect
+
+| Class | What it means | Action |
+|---|---|---|
+| Exhaustive | The compiler or the data structure forces completeness (a fully-typed `Record<Member, …>`, a `match` with no default) | nothing — this is the outcome to prefer |
+| Deliberate fallback | The fallback is part of the contract: a forward-compatible external value, a protocol unknown, a defensive boundary parse | record why, leave it |
+| Missing case | The new member reaches code written for the old set | fix it |
+
+**There is deliberately no blanket rule that a `default` branch is wrong.** Such
+a rule would be refuted by every protocol parser and boundary parse in the tree.
+What is true is sharper and easier to miss: where an exhaustiveness check exists,
+**a `default` clause suppresses its report entirely**, so adding one to quiet the
+check removes exactly the signal it existed to give.
+<!-- harvest:exhaustiveness-default-clause-masks-the-check -->
+
+Prefer the language-native guarantee over a comment. In TypeScript a
+`Record<Member, T>` where every member needs a value fails to compile on a new
+member, while a partially-typed string-keyed map does not. In PHP an exhaustive
+`match` without a masking `default` throws on an unhandled case.
+
+## Prove the sweep, do not assert it
+
+Add a **synthetic member** to the set, confirm the checks you are relying on go
+red, then update the consumers and confirm they go green. A sweep never seen red
+has unknown coverage — the same sensitivity argument
+[`downstream-changes`](../../../src/rules/downstream-changes.md) § Verification
+makes for tests, applied to the discovery step.
+
+## See also
+
+- [`downstream-changes`](../../../src/rules/downstream-changes.md) — the rule this
+  extends; its § Defect-pattern search is the sibling-occurrence half.
+- [`redundancy-taxonomy`](../redundancy-taxonomy.md) — the naming half: one
+  concept, several terms.
+- [`prefer-enums-over-literals`](../../../src/rules/prefer-enums-over-literals.md)
+  — how a closed set comes to exist in the first place.

package/docs/guidelines/agent-infra/evaluator-independence-mechanics.md

@@ -0,0 +1,92 @@
+# Evaluator independence — enforcement reach and its correction history
+
+> What the `evidence-independence` guard actually does per branch, per host; the
+> limits that were measured rather than assumed; and the two corrections this
+> material has taken. The rule keeps the verdict — this page carries the argument.
+
+_Origin: migrated from [`evaluator-independence`](../../../src/rules/evaluator-independence.md)
+§ *Enforcement — honest scope* under the P4 pattern
+(`road-to-standing-payload-diet` step 1.3). Nothing here is new; the rule was
+re-sending all of it on every session and every spawn, and only the verdict has
+to be._
+
+## The two branches
+
+[`evidence_independence.ts`](../../../src/scripts/hooks/evidence_independence.ts) is a
+`pre_tool_use` concern, and its two branches do **different** things —
+**corrected 2026-08-23**, because this paragraph claimed both of them block:
+
+- **Item 1 BLOCKS.** A dispatch whose prompt carries a pre-loaded verdict returns
+  `EXIT_BLOCK` (`:253`). Mechanically enforced, on the one host that honours a deny.
+- **Item 4 WARNS and does not block.** A second self-scoped evaluation dispatch in the
+  same turn returns **`EXIT_ALLOW`** with `decision: "warn"` (`:301-317`), and so does
+  the first (`:319-324`). That is deliberate, and the code says why at `:296-300`: the
+  internal ladder's `2 = warn` is read as a hard **deny** by this host's native
+  PreToolUse contract, *"which is the defect that made an advisory guard a hard deny
+  once already"*. Exiting 2 here would have kept a legitimate fan-out blocked while
+  claiming to warn.
+
+So the rule's own turn-budget clause is **advisory**, not enforced. It reads the prompt
+the agent is about to send, so item 1 is mechanically enforced and item 4 is surfaced.
+
+The manifest's `severity: blocking` for `evidence-independence`
+(`src/scripts/hook_manifest.yaml:380-385`) is a **third** reading and it is true of the
+item-1 path only: a severity declares the concern, never every branch inside it. A
+reader taking it as "both branches deny" reaches the claim this paragraph used to
+make.
+
+Three limits, stated because they were measured. The pre-loaded-verdict list is
+a **phrase list**, so a paraphrase evades it — it catches recurrences of known
+steering wording, not steering as such. The turn boundary is the
+authorization ledger's `detected_at` stamp, because the envelope carries no turn
+id; with no ledger yet, the counter falls back to session scope. And the guard
+does not deny everywhere it exists: `pre_tool_use` is **bound** on three hosts —
+augment, claude, cowork — and only `claude` honours the deny. Everywhere else,
+augment and cowork included, items 1 and 4 join 2 and 3 as model-carried.
+`agent-config hooks:status` answers it for the host you are on right now.
+
+**Corrected 2026-08-17 — this paragraph was wrong on both sides of the line it
+drew.** It said `pre_tool_use` "exists on three hosts" and that the guard has
+"nowhere to bind" on the other five. Neither half survived a re-read of the
+tree. **Downward:** the manifest's own `native_event_aliases` table already maps
+`preToolUse` (cursor), `PreToolUse` (cline) and `BeforeTool` (gemini) onto
+`pre_tool_use`, so there the guard is **unbound, not unbindable**; only windsurf
+and copilot carry no pre-tool surface at all. **Upward, and worse:**
+`host_semantics.ts` certifies **claude alone**, and the augment and cowork
+trampolines discard dispatcher output and `exit 0` unconditionally — so on two
+of the three "enforcing" hosts this guard runs and is then ignored. Nor may the
+inverse be asserted downward: nothing records whether an unbound host's
+pre-tool event can *deny*, and `severity: blocking` is a property of the concern
+rather than of the host. The four states are tabulated once in
+[`hook-architecture-v1 § Which hosts carry pre_tool_use`](../../contracts/hook-architecture-v1.md).
+
+Stated at this length because this rule exists over a case where a process that
+*looked* followed produced fabricated evidence. An unbacked reason for a real
+gap and an unmeasured claim of enforcement are the same failure in a smaller
+font, and this paragraph had shipped one of each. Note also what the frequency
+join actually reports: `check_enforcement_coverage.ts` skips `fallback_only`
+platforms, so its gap set is **four** — cursor, cline, windsurf, gemini — never
+copilot, which is excluded by declaration rather than measured as a gap.
+
+**Item 2 — an honestly chosen scope — is not enforced by anything.** A narrowed scope
+is not decidable from the prompt alone.
+
+**Item 3 — recording the prompt with the verdict — IS enforced**, and this rule said
+otherwise until 2026-08-23:
+[`check_review_prompt_binding.ts`](../../../src/scripts/check_review_prompt_binding.ts)
+binds a verdict to the prompt it was produced from. Its own header states the limit that
+matters, so citing it does not oversell it: **omission beats substitution** — simply not
+committing `<slug>.review-input/prompt.md` drops the round out of the checkable set with
+**no finding and no signal**, because an artefact without a package is deliberately out
+of scope. Measured on the corpus it shipped against, **11 of 19** artefacts already
+carry a `prompt_hash` with no package, so the bypassed state is the historical norm and
+is indistinguishable from it.
+They are stated here as obligations and are model-carried. Saying so is the
+point: this rule exists because a process that *looked* followed produced
+fabricated evidence, and claiming coverage it does not have would repeat that.
+
+
+## See also
+
+- [`evaluator-independence`](../../../src/rules/evaluator-independence.md) — the rule this page carries the argument for.
+- [`hook-architecture-v1 § Which hosts carry pre_tool_use`](../../contracts/hook-architecture-v1.md) — the four host states, tabulated once.