@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/emphasis-budget.md

@@ -0,0 +1,45 @@
+# Emphasis budget
+
+Authoring guideline. **This is a review-time discipline, NOT a merge-blocking
+linter** — there is no CI gate; PR review owns the judgment.
+
+## The principle
+
+Emphasis is a currency, and inflation debases it. Reserve the loud channels —
+ALL-CAPS, `## Iron Law` fences, spaced repetition of the same imperative — for
+**asymmetric, irreversible harm**: data loss, credential/secret exposure, a
+safety floor, a legal/compliance breach. When everything shouts, nothing does:
+an over-emphasized doc trains the reader to skim past the caps, so the one caps
+line that guards a `DROP TABLE` loses its signal.
+
+## The discipline
+
+When you add emphasis, be able to answer — in the artifact or the PR — two
+questions:
+
+1. **What specific harm does this prevent?** Name it (not "this is
+   important" — *what* goes wrong, to *whom*, how badly).
+2. **Why is post-hoc correction insufficient?** Emphasis is justified when the
+   harm is irreversible or asymmetric (a wrong send/delete/charge can't be
+   taken back). If a normal-weight sentence + a later fix would do, use normal
+   weight.
+
+If you cannot answer both, down-weight to plain prose.
+
+## Why not a linter
+
+A mechanical caps-quota is unenforceable — semantic substitution ("Critically:
+never…", bold, block quotes) defeats a caps count while keeping the shout — and
+it blocks ready work on a cosmetic metric. The Iron-Law *count* is also a
+denominator artifact: most existing Iron Laws already guard data-loss /
+credential / safety domains, so the raw number is not evidence of inflation.
+Judgment at review time, keyed to the harm-asymmetry test above, is the control.
+
+## Overlap (why a separate guideline)
+
+Distinct from [`preservation-guard`](../../rules/preservation-guard.md)
+(preserve existing emphasis through a transform — this governs *adding* it),
+[`size-enforcement`](../../rules/size-enforcement.md) (line budgets, not
+emphasis weight), and [`token-budget-discipline`](../../rules/token-budget-discipline.md)
+(load cost, not signal-to-noise). None owns the emphasis-rationing judgment;
+this guideline does.

package/dist/agent-src/guidelines/agent-infra/engineering-memory-data-format.md

@@ -0,0 +1,210 @@
+# Engineering Memory Data Format
+
+Schema and conventions for the four project-local YAML files that
+extend the memory layer beyond `ownership-map` and
+`historical-bug-patterns` (those are covered in
+[`review-routing-data-format`](review-routing-data-format.md)).
+
+All four files are **optional** and live in the consumer repository —
+never in package-shipped artifacts. Absence is handled gracefully:
+consulting skills fall through to their generic behaviour.
+
+This guideline replaces the *"one guideline per schema"* plan from
+`road-to-engineering-memory.md` with a single consolidated reference,
+matching the existing pattern established by `review-routing-data-format`.
+
+## File locations
+
+Each schema lives under `agents/memory/<type>/<hash>.yml` (content-addressed,
+merge-safe) **or** in a single `agents/memory/<type>.yml` file for projects
+that prefer one file per type.
+
+| Type | Single-file path | Sharded path |
+|---|---|---|
+| Domain invariants | `agents/memory/domain-invariants.yml` | `agents/memory/domain-invariants/<hash>.yml` |
+| Incident learnings | `agents/memory/incident-learnings.yml` | `agents/memory/incident-learnings/<hash>.yml` |
+| Product rules | `agents/memory/product-rules.yml` | `agents/memory/product-rules/<hash>.yml` |
+
+Choose one layout per type and stick with it. `scripts/check_memory.ts`
+warns if both exist for the same type.
+
+## Shared frontmatter fields
+
+Every entry across all four types MUST carry these keys. The gate
+rejects entries missing any required field.
+
+| Key | Required | Type | Notes |
+|---|---|---|---|
+| `id` | yes | kebab-case slug | unique within the type |
+| `status` | yes | `active` \| `deprecated` \| `archived` | lifecycle |
+| `confidence` | yes | `low` \| `medium` \| `high` | reader weights accordingly |
+| `source` | yes | list of URLs / ADR refs | ≥1 entry |
+| `owner` | yes | team slug | who keeps this entry fresh |
+| `last_validated` | yes | ISO date | stale check per type |
+| `review_after_days` | yes | integer | triggers staleness warning |
+| `priority` | no | `critical` \| `normal` \| `low` | tier-0 surfacing; defaults to `normal` |
+| `ts_week` | no | ISO-week string `YYYY-Www` | promotion week stamp; convention, not enforced |
+| `verified_at_commit` | no | 7-40 char lowercase hex | the tree revision the entry was **semantically verified against** — not the commit that last edited the YAML |
+| `semantic_verdict` | no | `still-true` \| `stale` \| `unverifiable` | a recorded **human** reading of the entry against that tree |
+| `semantic_verdict_at` | no | ISO date | when that reading was taken |
+
+### Verification stamps (`verified_at_commit` / `semantic_verdict`)
+
+A date alone cannot be tied to a tree state, and that gap is not theoretical:
+spike cf02 measured the curated store at **21.5 % stale against the tree** while
+the shipped instrument reported **0.0 %**, because all 107 entries carried one
+`last_validated` and one 365-day window, so the check could not fire before
+2027. `verified_at_commit` is what makes a stamp falsifiable — with it, a reader
+can ask whether anything the entry cites has changed since it was last read.
+
+`semantic_verdict` records the outcome of that read. It is **human-written**,
+deliberately: no mechanical signal predicts it. Pointer liveness was built and
+measured for exactly this job and came in at 0.00x lift over the base rate
+(cf04) — a dead citation is documentation debt, not a false claim.
+
+A `stale` verdict demotes the entry immediately, regardless of age
+(`memory_eviction.ts`, "contradiction outranks retention"). An `unverifiable`
+entry — one about an external system, a past event, or a recorded preference —
+is surfaced on age but never quarantined on it, because the tree can never
+discharge the reason.
+
+### Priority semantics (`critical` / `normal` / `low`)
+
+The `priority` field controls how aggressively `/memory:load` surfaces
+an entry. The three-tier enum is intentional — see
+an internal roadmap (local-only) § B2 and the Phase 2 council brief
+for why a fourth `high` tier was rejected.
+
+| Value | Meaning | Reader behaviour |
+|---|---|---|
+| `critical` | Tier-0 — always surface regardless of query | `/memory:load` injects on every load, irrespective of key/query match |
+| `normal` (default) | Standard query-matched retrieval | Surfaced when the lookup key/query matches the entry |
+| `low` | Background — only surface on explicit full load | Skipped by query-matched retrieval; visible only via `/memory:load --type` full sweep |
+
+**Tier-0 governance.**
+`scripts/check_memory.ts` enforces two soft guards on `critical` entries:
+
+- **Critical-stale warning** — a `priority: critical` entry whose
+  `last_validated` is older than 90 days emits a `critical-stale` warning
+  during validation (still exit 0; the curator decides whether to
+  re-validate or downgrade).
+- **Tier-0 inflation warning** — when a memory type accumulates more
+  than 10 active `critical` entries, the validator warns. The intent is
+  to keep the always-surface slice small enough to remain signal, not to
+  block writes; raise the threshold deliberately if the project's domain
+  genuinely needs more.
+
+Both are warnings, never errors. The curator stays in charge.
+
+### Temporal jitter (`ts_week`)
+
+`ts_week` stamps a curated entry with the **ISO week** it was promoted
+(`YYYY-Www`, e.g. `2026-W17`). It is optional and **convention-only** —
+the validator does not require it and does not reject entries without
+it. Promotion tooling (`/memory:promote`) writes it; manual edits are
+free to set or omit.
+
+**Why ISO-week, not date-time.** Curated YAML lives in the repo and is
+reviewable by anyone with access. A precise timestamp on every entry
+leaks session timing — "this rule appeared Tuesday 3pm" correlates with
+"the incident hit Tuesday 3pm". ISO-week granularity preserves long-
+term ordering (useful for audit) while removing intra-week inference.
+
+**When to use it.** Stamp on every promotion. Do not retroactively
+backfill — empty `ts_week` for older entries is fine and a deliberate
+non-signal.
+
+**Privacy carve-outs.** Highly sensitive entries (incident-learnings
+tied to active investigations) may omit `ts_week` entirely; the field
+is not a forensic record.
+
+## Type-specific required fields
+
+Each file also carries the template-specific body. See the example
+templates for the full shape:
+
+- [`domain-invariants.example.yml`](../../../src/agent-src/templates/agents/memory/domain-invariants.example.yml)
+  adds `rule`, `boundary`, `scope.paths`, `violation_contract`.
+- [`incident-learnings.example.yml`](../../../src/agent-src/templates/agents/memory/incident-learnings.example.yml)
+  adds `pattern`, `trigger_conditions`, `consequence`, `guardrail`,
+  `enforcement`, `severity`.
+- [`product-rules.example.yml`](../../../src/agent-src/templates/agents/memory/product-rules.example.yml)
+  adds `rule`, `applies_to`, `enforcement`, `error_contract`, `version`.
+
+## Ownership (who writes, who reads)
+
+| Type | Writer | Reader (skill/role) | Expiry |
+|---|---|---|---|
+| Domain invariants | senior engineer / architect | `developer-like-execution`, `php-coder`, `laravel` | reviewed at major version bump |
+| Architecture decisions | decision author at ADR time | `feature-plan`, `api-design`, `blast-radius-analyzer` | `deprecated` on reversal; never deleted |
+| Incident learnings | incident commander post-resolution | `Incident` role, `bug-investigate`, `bug-analyzer` | archived when guardrail lands + verified in prod |
+| Product rules | PO or tech lead post-decision | `PO` role, `validate-feature-fit`, `laravel-validation` | version-stamped; old versions archived |
+
+## Redaction rules (hard)
+
+Enforced by `scripts/check_memory.ts`. Reject on match:
+
+- **No secrets.** API keys, tokens, credentials, private URLs with
+  credentials, internal hostnames that expose infrastructure.
+- **No customer names.** ACME Corp, specific account IDs, domain
+  names of real customers. Rephrase to the pattern.
+- **No PII.** Names, emails, phone numbers, IP addresses tied to
+  real users. Incident-learnings is tempting here — resist.
+- **No ticket IDs that identify the incident** in
+  `incident-learnings.yml`. Link the guardrail PR instead.
+
+## Reader contract
+
+Consuming skills read an entry and expose its `status` + `confidence`
+to the agent. A `confidence: low` domain invariant informs, it does not
+dictate. A `confidence: high` incident learning blocks the generation
+path if the guardrail is absent.
+
+## Staleness
+
+`check_memory.ts` runs weekly (not per-PR). It reports entries where
+`(today - last_validated) > review_after_days`. Stale entries stay
+active — the report is informational, not a gate.
+
+**The window is per store, and the numbers are derived rather than chosen.**
+cf02 measured decay over the same 39-day span in three stores:
+`historical-patterns` 45.8 %, `incident-learnings` 17.6 %, `product-rules`
+13.6 % — a 3.4× spread that one uniform window cannot serve. Extrapolated
+linearly, the days each store needs to reach the 10 % threshold are 9, 22 and
+29. The shipped windows are **30 / 90 / 90**: the same ratio, rounded to
+operational units, because cf02 also showed decay arrives in *batches* (two
+upstream changes caused 11 of 22 stale entries), which makes a linear day count
+the wrong shape for a deadline even though it is the right shape for a ratio.
+
+## Eviction ladder
+
+`memory_eviction.ts` acts on two signals and no others:
+
+| State | Trigger | Effect |
+|---|---|---|
+| `due` | past `last_validated + review_after_days` | surfaced, stays in the store |
+| `quarantine` | `semantic_verdict: stale`, **or** past two windows unverified | moved to `agents/memory-quarantine/<type>.yml`, no longer injected, still readable |
+| `delete` | three windows while in quarantine | removed |
+
+Quarantine is a **move between tracked files**, never an in-place status flip:
+an entry has to leave the injected store to stop being read as fact, and it has
+to stay readable to be appealable. Re-verify an entry and it returns.
+
+Dry-run by default; `--apply` is the only path that writes.
+
+## Anti-patterns
+
+- **Do NOT** merge `ownership-map.yml` semantics into these files.
+  Ownership is a separate concern; mixing them doubles the staleness
+  surface.
+- **Do NOT** generate entries via LLM in bulk. Curated is the point.
+  The point of a `confidence: high` entry is human-verified claim,
+  not high-volume output.
+- **Do NOT** delete `deprecated` or `archived` entries. History is
+  the value of memory; deletion is amnesia.
+- **Do NOT** ship this file pre-populated. Each consumer starts
+  empty and fills as decisions and incidents accumulate.
+
+## See also
+
+- [`review-routing-data-format.md`](review-routing-data-format.md) — sibling format for ownership + bug patterns

package/dist/agent-src/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`](../../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 alias row 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`](../../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.

package/dist/agent-src/guidelines/agent-infra/existence-question-verdicts.md

@@ -0,0 +1,80 @@
+# The existence question — its verdict set, its cost, and why it is not TDD
+
+Depth for [`improve-before-implement`](../../rules/improve-before-implement.md)
+§ The solution-size ladder, migrated out of
+[`agent-interaction-and-decision-quality`](agent-interaction-and-decision-quality.md)
+§ 8b.
+
+**Why it moved.** That guideline crossed `check_depth_budget`'s 16,000-character
+ceiling when this depth landed in it, becoming a fifth over-ceiling file against
+a baseline of four. The ratchet turns one way, so the fix is extraction rather
+than a raised baseline — and these three sections are the natural unit: they
+answer what the ladder RETURNS, what it costs, and which cluster it does not
+belong to, none of which the surrounding interaction guideline needs in order to
+be read.
+
+The ladder itself — the rungs, the shape axis and their precedence — stays at
+§ 8b-ladder / 8b-shape / 8b-precedence, because the rule routes there.
+
+#### 8b-verdict. The verdict set, and what `new` owes
+
+The ladder's answer is a **named verdict, never a yes/no**:
+
+| verdict | meaning |
+|---|---|
+| `reuse` | the existing thing carries the requirement as-is |
+| `extract` | it carries it once a shared part is pulled out |
+| `refactor` | it carries it once reshaped, same responsibility |
+| `extend` | it carries it with an added, non-distorting case |
+| `migrate` | it should carry it, and the move is the work |
+| `new` | nothing carries it, and the search that establishes that is the evidence |
+
+**`new` owes negative evidence** — the closest existing candidate **by name and
+path**, and why it does not carry the requirement. *"Nothing similar exists"*
+naming no candidate is an unrun search, not an answer, and it is the shape this
+verdict set exists to make visible.
+
+Two clauses hold the set honest, and both cut against reading it as a ranking:
+
+- **The order is a thinking preference, not a ranking.** A `new` after a real
+  search beats an `extend` that bends a helper out of shape. Preferring reuse is
+  not preferring reuse *at any cost*.
+- **Textual similarity alone is never grounds for an abstraction.** Two blocks
+  that read alike and change for different reasons are two blocks — the
+  per-class bars are in [`abstraction-thresholds`](../abstraction-thresholds.md).
+
+**Reach the verdict with the engine, not a fresh grep protocol.** `agent-config
+code-graph query` and `code-graph affected`;
+[`external-code-graph-interop`](../../rules/external-code-graph-interop.md)
+already mandates query-before-grep and names grep the fallback, so a second
+search specification here would contradict it rather than add to it.
+
+#### 8b-cheap. Why the exclusions buy the checks and never the question
+
+The rule excludes bug fixes, config changes, user-fenced tasks and trivial
+changes from the **three heavy checks**. The one cheap question — *does this
+already exist in the tree* — fires on all four rows anyway.
+
+The reason is empirical rather than tidy: **bug fixes and renames re-add an
+existing helper more often than features do**, because the author is inside one
+file and reaching for something small. Switching the reuse rung off there
+switches it off where it pays most.
+
+Cheap means cheap, on the [`ui-audit-gate`](../../rules/ui-audit-gate.md)
+precedent: one `code-graph query`, one named verdict, no interview.
+
+**The skip is decidable from the diff alone** — ≤ 1 file, ≤ 5 changed lines, no
+new symbol, no new dependency. A typo satisfies all four with no state to
+consult; an added symbol never does.
+
+#### 8b-routing. Why this is not routed through the TDD cluster
+
+Two source proposals put the existence question in `/tdd`'s design mode, as the
+one point every behaviour passes through. **It cannot live there, and the reason
+is delivery rather than design:**
+`src/domains/engineering-base/tdd/command.md` carries `visibility: internal` and
+`disable-model-invocation: true`, so **a consumer cannot reach it.** The routing
+is undeliverable, not merely unwanted.
+
+Recorded here so the next author does not re-derive the proposal and re-propose
+it.

package/dist/agent-src/guidelines/agent-infra/failure-signatures.md

@@ -0,0 +1,70 @@
+# Failure signatures — symptom → likely cause → first check
+
+A file-first lookup the [`systematic-debugging`](../../skills/systematic-debugging/SKILL.md)
+skill reads when a failure shows a recognisable signature. It does **not**
+replace the 6-phase loop — it shortcuts **Phase 2 (Isolate)** by pointing at the
+*first* check for a known shape, so you stop guessing and start with the highest-
+probability cause.
+
+> File-first by design (council 2026-06-15): kept as a reference table the skill
+> reads, **not** hardcoded into the skill body — so it grows without bloating the
+> always-loaded skill and stays one edit away from current.
+
+## Lookup
+
+| ID | Signature (what you see) | Likely cause | First check |
+|---|---|---|---|
+| `tool-loop` | **Tool/agent loop** — same tool called >2× with near-identical args, no progress | Missing stop condition; reading without acting; ambiguous state | Stop. State the hypothesis in one line. Act or ask — do not re-read. (`context-hygiene` 15/25 rule) |
+| `rate-limited` | **HTTP 429 / "rate limit" / "quota"** | Too-frequent calls; shared quota; missing backoff | Inspect response headers (`Retry-After`, `X-RateLimit-*`); add exponential backoff; check if a loop is firing the calls |
+| `connection-refused` | **`ECONNREFUSED` / connection refused** | Service not up; wrong host/port; container not started | Is the service running? (`docker compose ps`, health endpoint); is the port right? (`lsof -i :PORT`); is it bound to `127.0.0.1` vs `0.0.0.0`? |
+| `path-not-found` | **`ENOENT` / "no such file or directory"** | Wrong cwd; path relative vs absolute; file not generated yet | Print the *resolved absolute* path; check cwd; confirm a prior step actually wrote the file |
+| `hang` | **Timeout / hang** | Blocking I/O; deadlock; awaiting a condition that never holds | What is it waiting on? Add a log right before the blocking call; bound the wait; check for a missing `await`/`return` |
+| `out-of-memory` | **`OOM` / killed (137) / heap out of memory** | Unbounded collection; loading all rows; leak in a loop | What grows per iteration? Stream/paginate instead of loading all; check `--max-old-space-size` only after finding the growth |
+| `permission-denied` | **`EACCES` / permission denied** | Wrong file mode; running as wrong user; read-only mount | `ls -l` the target; check the process user; is the path a read-only volume? |
+| `order-dependent-test` | **Flaky test (passes alone, fails in suite)** | Shared state; order dependence; real clock/random; unawaited async | Run the test in isolation vs in suite; look for shared fixtures, global state, `Date.now()`/random, missing `await` |
+| `local-ci-drift` | **Works locally, fails in CI** | Env/config drift; missing service; absent secret; path/case sensitivity | Diff env (`printenv`); is the service/secret present in CI? Linux is case-sensitive — check filename casing |
+| `race` | **Intermittent / "sometimes"** | Race; timing; network; non-deterministic order | Reproduce with condition-based waiting, not fixed sleeps (`systematic-debugging` § Condition-based waiting); log timestamps |
+| `stale-capability-claim` | **Budget exhausted plus repeated attempts at a tool that is not available** | A capability the session claimed for itself instead of resolving — the council, a hook slot, a subagent primitive, an MCP server assumed present | Ask the live verb, not the tree: `agent-config hooks:status` for slot bindings, `agent-config routing:doctor` for per-field capability **provenance** (`registry` / `live-probe` / `default`), `agent-config council:status` for council availability. A `false` from `default` records that nobody answered, not that the host cannot |
+
+### Naming convention for IDs
+
+An id is a short kebab handle so a signature can be **cited by name** — the
+first column was prose, so nothing could reference a row.
+
+One rule governs new ids: **where a row's signature is a stable string the
+tooling already prints, the id is that string verbatim** rather than a kebab
+synonym. `skill_linter.ts` emits a closed set of `Issue` codes —
+`missing_section`, `missing_conditional_section`, `invalid_execution_handler` —
+and a row about one of those is looked up by the code the reader just saw in the
+output. No current row is of that class; the convention is stated for the next
+one, so the table does not accumulate two names for the same failure.
+
+## Discrimination drills
+
+A row's "first check" is only worth following if the documented signature is what
+actually appears. Each drill breaks the named layer and asserts the documented
+symptom — run it once when you doubt a row, or when adding one. They are text a
+human runs; nothing here is a CI gate.
+
+| ID | Drill — break this, expect that |
+|---|---|
+| `tool-loop` | Ask for a fact that is genuinely absent from the tree (a config key nothing defines). Expect repeated searches with shrinking variation and no edit — that shape, not an error message, is the signature. |
+| `rate-limited` | Fire the provider's own rate limit with a tight loop against a cheap endpoint. Expect `429` **plus** `Retry-After`; a `429` with no such header is a different failure (a gateway, not the API). |
+| `connection-refused` | Stop the service and call it (`docker compose stop <svc>`). Expect `ECONNREFUSED` immediately. If it hangs instead, the host resolves but nothing listens — that is `hang`, not this row. |
+| `path-not-found` | Run a path-taking script from a different cwd. Expect `ENOENT` naming a path that is *almost* right — the near-miss is the tell that the path is relative, not missing. |
+| `hang` | `await` a promise nothing resolves. Expect no output and no exit, distinguishable from `race` by being 100% reproducible. |
+| `out-of-memory` | Accumulate rows in an array inside a loop over a large fixture. Expect the heap message and exit 137 — and note that the reported line is where allocation failed, not where the growth is. |
+| `permission-denied` | `chmod 000` a fixture and read it. Expect `EACCES`, not `ENOENT` — confusing the two sends you looking for a missing file that is right there. |
+| `order-dependent-test` | Add a module-level mutable to two tests in one file. Expect green alone, red in suite. Reversing the file order should move the failure — if it does not, the cause is shared *external* state, not order. |
+| `local-ci-drift` | Rename a fixture's casing (`Foo.ts` → `foo.ts`) and import the old name. Expect green on macOS, red on Linux CI. The generalisation: anything the local filesystem is lenient about. |
+| `race` | Replace a condition-based wait with a fixed `sleep` shorter than the operation. Expect intermittent failure whose rate moves with machine load — load-sensitivity is what separates this from `order-dependent-test`. |
+| `stale-capability-claim` | Assert a capability without asking for it, then compare against the live verb. `agent-config routing:doctor` prints provenance per field; a field whose provenance is `default` was never established by anything — which is exactly the state a confident self-claim is indistinguishable from. |
+
+## How to use
+
+1. Match the symptom to a signature above.
+2. Run the **first check** — it is the highest-probability isolation step, not a fix.
+3. If it confirms the cause → fix + add a regression test. If not → fall back to
+   the full `systematic-debugging` loop from Phase 1.
+
+No signature matches → this table earned nothing; debug from first principles.