@event4u/agent-config 14.17.0 → 14.18.0

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: inherit
 name: code-intelligence
-description: "Route codebase-structure questions (who calls X, where used, what imports, change-impact) to a code-graph first, grep fallback. Triggers 'who calls', 'where is this used', 'call graph'."
+description: "Route codebase-structure questions (who calls X, where is this used, what imports, change-impact) to an existing code-graph first: cheaper, never more precise; grep stays routine. Also 'call graph'."
 domain: engineering
 workspaces:
   - engineering
@@ -14,11 +14,14 @@ requires_skills:
 # code-intelligence
 
 > For a **structure** question — *who calls X*, *where is Y used*, *what
-> imports Z*, *what breaks if I change this symbol* — a code-graph answers far
-> more precisely than a blind `grep`, at a fraction of the tokens. This skill
-> routes such questions to the native code-graph engine (ADR-124, Class A) or a
-> consumer-shipped index first, and falls back to grep **with a stated reason**
-> when the graph cannot answer. It is the executable side of
+> imports Z*, *what breaks if I change this symbol* — ask an index that already
+> exists before rebuilding the relationship by hand: it is already built, its
+> answer is structured, and it costs a fraction of the tokens. It is **not** more
+> precise than a blind `grep` — measured on this repository's own source, zero
+> classes met the win bar (§ Measured twice) — so grep is the arm you fall back
+> to routinely and **with a stated reason**, not grudgingly. This skill routes
+> such questions to the native code-graph engine (ADR-124, Class A) or a
+> consumer-shipped index first. It is the executable side of
 > [`external-code-graph-interop`](../../rules/external-code-graph-interop.md):
 > *orchestrator first, owner where it wins*.
 
@@ -50,9 +53,15 @@ code-graph and no appetite to build one — plain `grep`/read is right there.
    - `agent-config code-graph path <a> <b>` — how two symbols connect.
    - `agent-config code-graph explain <symbol>` — 2-hop neighbourhood.
    Pass `--budget <tokens>` to cap output.
-4. **Read the confidence.** `EXTRACTED` = syntactic fact; `INFERRED` =
-   hierarchy-resolved; `AMBIGUOUS` = dynamic dispatch / facade, carries
+4. **Read the confidence.** `EXTRACTED` = syntactic fact — a symbol declared in
+   the file, or a name bound to the module specifier the file names; `INFERRED`
+   = resolved by hierarchy, or by a repo-wide same-name lookup with no binding
+   in the file to justify it; `AMBIGUOUS` = dynamic dispatch / facade, carries
    candidates — treat its target as *one of* the candidates, never as certain.
+   Two target shapes are **not nodes** and resolve to nothing you can read:
+   `symbol:<name>` (a name this repository does not declare) and
+   `external:<module>` / `external:<module>#<name>` (a name imported from
+   outside the indexed root — `external:node:path`).
 5. **Fall back honestly.** If the graph has no entry for the symbol, grep — and
    say so: *"the graph has no entry for X, so I grepped."* If this command is
    not available, grep and say so.
@@ -72,10 +81,22 @@ Every answer built with this skill MUST:
 - **A stale graph lies confidently.** If `detect` reports the index is N commits
   behind, rebuild (`agent-config code-graph build --update`) before trusting
   relationship answers, or say the answer is from a stale index.
-- **Dynamic dispatch is honestly ambiguous.** On a Laravel/JS codebase most
-  method-call edges are `AMBIGUOUS` (facades, injected services, `$obj->m()`).
-  That is the engine being honest, not broken — do not "resolve" them yourself
-  by guessing.
+- **Dynamic dispatch is honestly ambiguous — where there is anything to be
+  ambiguous ABOUT.** A `$obj->m()` whose name matches a method declared
+  somewhere in the repo is `AMBIGUOUS` and carries those candidates: the engine
+  being honest, not broken — do not "resolve" them yourself by guessing. A
+  dynamic call whose name matches **no** in-repo method (`xs.push()`,
+  `map.get()`) is not emitted at all, and the count is published as
+  `suppressed_edge_counts.dynamic_no_candidate`. It used to be 39 % of this
+  engine's own graph, pointing at `symbol:push`, which is not a node and which
+  no query verb could reach.
+- **The AMBIGUOUS share is a property of the code, not a constant.** Measured
+  2026-09-04 over the three roots the v2 benchmark uses: `AMBIGUOUS` is 0 of 495
+  edges under the package's own graph-engine root, 0 of 181 under `src/shared`, and 121 of
+  4,002 (3.0 %) under its council root — class-free TypeScript has
+  almost no in-repo method to be ambiguous between. A Laravel codebase, where
+  facades and injected services dispatch onto real in-repo methods, is the
+  opposite case. Read the counts in the graph rather than a remembered ratio.
 
 ## Measured twice, and it has not won (v2, 2026-08-29)
 
@@ -113,6 +134,33 @@ engine on this repository's own code. The rule now gives the reasons that surviv
 measurement — an index that exists is already built and structured, so it is the
 cheap first question — and drops the precision claim its own benchmark refuted.
 
+## Re-run after the extractor repair (2026-09-04) — still no class won
+
+`internal/bench/reports/code-graph-vs-grep-inrepo-v2-rerun-2026-09-04.md`. The
+SAME registration, the same corpus SHA, the same per-class bars and the same
+arm-B verbs, re-run after the import-binding repair. The 2026-08-29 report is
+untouched; this is a second report beside it, which is how v1 was handled too.
+
+| Class | graph R then | graph R now | graph P then | graph P now | verdict then → now |
+|---|---|---|---|---|---|
+| `callers` | 1.000 | 1.000 | 0.667 | 0.667 | TIE → TIE |
+| `transitive-impact` | 0.500 | **0.611** | 0.667 | **1.000** | **NULL → TIE** |
+| `path-between` | 1.000 | 1.000 | 1.000 | 1.000 | TIE → TIE |
+| `references` | 0.333 | **1.000** | 0.333 | **1.000** | **NULL → TIE** |
+
+**Zero classes met the win bar, again.** Two NULLs became TIEs and nothing
+regressed, so the routing verdict below is unchanged — a TIE is not a win, and
+no bar was renegotiated after the repair.
+
+Read with two caveats the report states in full. A measured root is live source:
+`src/shared` is byte-identical between the runs, the council root moved
+by 27 files on `main` in between, and the graph-engine root IS the engine, so
+its content necessarily moves whenever the engine does — which is also why the
+GREP arm's macro precision moved (0.806 → 0.764) in a run that changed nothing
+about grep. Both classes that changed verdict did so on rows whose root did not
+drift: `references` moved on the graph-engine and shared roots, `transitive-impact` on
+`shared` alone.
+
 **No class is graph-first.** Query the index first because an index that already
 exists is cheap to ask and its answer is structured — not because it answers
 better. When it returns nothing, that is the common case, and grep remains the

package/dist/agent-src/skills/complexity-first-planning/SKILL.md

@@ -62,6 +62,33 @@ unknown to resolve), or when the user has already fixed the sequence.
 A short ordered plan that leads with the load-bearing unknown + how it will be
 proven, then the dependent steps. One recommendation, not a survey.
 
+## The four plan criteria — what a reviewer fails the ordered plan on
+
+Risk-first ordering is one of four things a plan is judged on. All four are
+stated so a reviewer can **fail** a plan on them — each names what failing looks
+like. This skill owns the third; the other three are stated here because a plan
+reviewed on ordering alone passes while being unnecessary, insufficient, or
+built on verbs that do not exist. The same four are carried in
+`feature-planning` (pack `product-basic`), which is pruned under `projection.mode: scoped` and so is named rather than linked.
+
+1. **Necessity** — every step traces to a stated problem or acceptance criterion.
+   **Fails when** the plan carries work nothing asked for — a spike for an
+   unknown that is not load-bearing is the version of this failure this skill
+   causes.
+2. **Sufficiency** — every requirement is discharged by at least one step.
+   **Fails when** a requirement owns no step, or its only step has no verifiable
+   outcome. Walk the requirements, not the steps.
+3. **Ordering** — the load-bearing unknown is resolved before anything that
+   assumes it, and no step consumes what a later step creates. **Fails when** the
+   plan front-loads the easy parts, or ranks by effort instead of dependency
+   blast radius (see Gotchas). This is the criterion this skill exists for.
+4. **Groundedness** — every command, skill and tool the plan tells someone to run
+   exists. **Fails when** the plan names a verb that is not in the index. Check
+   it against [`CAPABILITIES.yaml`](../../../CAPABILITIES.yaml) at the repository
+   root — the generated capability index of every shipped skill and command —
+   plus the project's own script/task entry points. It is the only one of the
+   four decidable without judgement, so it is never waved through.
+
 ## Do NOT
 
 - Build the easy parts first to show progress, then discover the hard part breaks them.

package/dist/agent-src/skills/design-review/SKILL.md

@@ -3,6 +3,8 @@ model_tier: high
 name: design-review
 description: "When the user says \"review the design\", \"check the UI\", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility and more."
 domain: quality
+enforced_by:
+  - "instruction-only: the Phase 4 sweep claims WCAG 2.1 AA and its criteria table is a deliberate SUBSET — depth is delegated to accessibility-auditor, which claims 2.2 AA and carries the resolver. No resolver checks this table against 2.1, so the claim is model-carried and the gap is recorded rather than implied."
 workspaces:
   - engineering
 packs:

package/dist/agent-src/skills/feature-planning/SKILL.md

@@ -176,6 +176,40 @@ complexity: lightweight  # default — skips bite-sized granularity
 
 Source: adapted from an external reference; complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
 
+## The four plan criteria — what a reviewer fails a plan on
+
+The 3-scan self-review below catches mechanical gaps. These four catch the plan
+itself. Each is written so a reviewer can **fail** on it: the criterion states
+what failing looks like, not what passing feels like. A plan that cannot be
+failed on any of the four has not been reviewed, it has been read.
+
+1. **Necessity** — every phase, step and artifact in the plan is traceable to a
+   stated problem or acceptance criterion. **Fails when** the plan contains work
+   no requirement asked for: a new abstraction with one caller, a migration for a
+   field nothing reads, a "while we're in there" refactor, a config surface
+   nobody requested. Name the orphan step and the requirement it does not map to.
+2. **Sufficiency** — every stated requirement and acceptance criterion is
+   discharged by at least one step. **Fails when** a requirement has no owning
+   step, or when the only step that claims it is a heading with no verifiable
+   outcome under it. This is the mirror of Necessity and is checked in the
+   opposite direction: walk the requirements, not the steps.
+3. **Ordering** — no step depends on the outcome of a step that comes after it,
+   and the load-bearing unknown is resolved before the work that assumes it (see
+   [`complexity-first-planning`](../complexity-first-planning/SKILL.md)).
+   **Fails when** step N consumes something step N+2 creates, or when the plan
+   builds three cheap phases on an integration nobody has proven yet.
+4. **Groundedness** — every command, skill, command-verb and tool the plan tells
+   someone to run **exists**. **Fails when** the plan names a verb, skill or
+   command that is not in the index. Check it against
+   [`CAPABILITIES.yaml`](../../../CAPABILITIES.yaml) at the repository root — the
+   generated capability index listing every shipped skill and command per
+   capability area — plus the project's own script/task entry points for anything
+   the index does not cover. This is the one of the four that is decidable
+   without judgement, so it is the one that should never be waved through.
+
+A failure on any of the four is a blocker, not a note: fix the plan and re-run
+the criterion, or move the item to *Open questions* with the reason.
+
 ## Self-review (3-scan checklist)
 
 Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.

package/dist/agent-src/skills/git-workflow/SKILL.md

@@ -100,21 +100,46 @@ Work complete. What would you like to do?
 ### Option 1: Push and create PR
 
 1. Run quality pipeline + tests (only when `quality.local_auto_run: true`; default `false` → skip, remote CI is the gate).
-2. `git push -u origin <branch>`.
-3. `gh pr create` using PR template.
+2. **The push-ready sequence** — fetch → integrate the base SET → regenerate →
+   verify → re-check freshness (this repo wires it as a `push-ready` task target;
+   a consumer wires its own). Not optional housekeeping: see § A push closes its
+   own loop. A stale push is refused, so skipping this buys the refusal.
+3. `git push -u origin <branch>`.
+4. `gh pr create` using PR template.
+5. **Settle it** — the turn is not over at step 4:
+   `npx tsx node_modules/@event4u/agent-config/src/scripts/ci_settle.ts <pr>`
 
-### Option 2: Keep as-is
+## A push closes its own loop
 
-Report: "Branch `<name>` preserved locally." — do nothing.
-
-### Option 3: Discard
-
-**Confirm first** — list branch name and commit count.
-Wait for explicit confirmation. Then:
-```bash
-git checkout main
-git branch -D <feature-branch>
 ```
+A PUSH IS NOT A DELIVERY. THE EVIDENCE FOR A PUSH IS THE CI VERDICT,
+NEVER THE PUSH'S OWN EXIT CODE.
+BEHIND THE BASE → INTEGRATE BEFORE PUSHING, NEVER AFTER THE PR IS RED.
+RED AFTER PUSHING → FIX IT IN THE SAME TURN, OR SAY PLAINLY THAT YOU DID NOT.
+NEVER HAND THE USER A RED PR WITH ITS CAUSE NAMED AND UNFIXED.
+```
+
+Two halves, failing differently, over the 30 sessions and 50 PRs before
+2026-09-04. **Stale base**: 25 of 50 PRs carried a `Merge branch 'main' into …`
+commit (52 in total), and the three most-failing workflows are the base-relative
+ones — a branch pushed behind its base was verified against a base it no longer
+merges into. **Unsettled push**: 22 of 30 sessions ran `gh run view
+--log-failed`, and 20 of 50 PRs carried a follow-up `fix(ci|gates|budget)`
+commit. Only 19 of 50 landed with neither. Each half now has a deterministic
+carrier — the pre-push hook refuses a verified-behind branch and points at the
+push-ready sequence; the `push-settle` PostToolUse concern fires the moment git
+reports a ref advanced. Neither replaces the discipline: the hook is skippable
+with `AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1` for a genuine WIP push, and the
+settle reminder is advisory, because leaving a push deliberately unsettled is
+legitimate — **ending the turn silently on one is not**.
+
+`ci_settle` non-zero → read only the failing part
+(`gh run view --job <id> --log-failed | grep -E '×|FAIL|Error'`), fix, push
+again; the author of the red is irrelevant (`fix-what-you-see`). Three failed
+attempts on one target → stop and surface them (`autonomous-execution` N=3).
+Exit `2` is **not** a verdict — the wait timed out or the API could not be read.
+Counts, carrier limits and the honest cost:
+[`references/push-closes-its-loop.md`](references/push-closes-its-loop.md).
 
 ## PR template
 

package/dist/agent-src/skills/git-workflow/references/push-closes-its-loop.md

@@ -0,0 +1,176 @@
+# A push closes its own loop — the measurement
+
+Reference for [`git-workflow`](../SKILL.md) § A push closes its own loop. The
+obligation lives in the skill; this file carries the evidence behind it and the
+two deterministic carriers that now exist, so neither has to be re-derived and
+neither inflates the skill body.
+
+## What was measured
+
+Corpus: the 30 most recent local session transcripts and the 50 most recent
+pull requests on this repository, read on 2026-09-04. Session events are counted
+from git's and `gh`'s own literal output in the transcripts, never from prose
+about them; PR workflow runs come from `actions/runs?event=pull_request`, which
+paginates out at 1,000 runs and therefore covers **36** of the 50 PRs — the
+older 14 are unmeasured, not clean, and are excluded from that row rather than
+counted as green.
+
+### Half one — the stale base
+
+| Signal | Count |
+|---|---|
+| PRs carrying ≥ 1 `Merge branch 'main' into <branch>` commit | **25 / 50** |
+| Such merge commits in total | **52** |
+| Sessions hitting a literal `CONFLICT (content)` / `Automatic merge failed` | **10 / 30** |
+| Sessions hitting a rejected push (`Updates were rejected` / non-fast-forward) | **20 / 30** |
+
+The worst single PRs needed four and five separate base merges. What that
+buys is not only conflict work: the three workflows that failed most —
+**Tests (18), Consistency (16), Rule Backstops (13)** — are the base-relative
+ones. Ratchets, budgets and generated counts are green against the base a branch
+forked from and red against the base it merges into, so a branch pushed behind
+its base was verified against a question nobody asked.
+
+### Half two — the unsettled push
+
+| Signal | Count |
+|---|---|
+| Sessions running `gh run view --log-failed` (a red job was investigated) | **22 / 30** |
+| PRs with ≥ 1 FAILED workflow run (of the 36 readable) | **17** |
+| Failed runs in total | **56** |
+| PRs carrying a follow-up `fix(ci\|gates\|budget\|deps\|tests)` commit | **20 / 50** |
+| Such repair commits in total | **41** |
+
+Every one of those pushes SUCCEEDED. What failed was the ending: the push
+returned 0, the turn closed, and the red arrived where the user found it.
+
+**Only 19 of 50 PRs landed with neither half.**
+
+## The two carriers
+
+| Half | Carrier | Behavior |
+|---|---|---|
+| Stale base | `check_branch_freshness` in the pre-push hook (`src/scripts/install-hooks.sh`) | Asks the REMOTE, one `ls-remote`, ~4.5 s. Refuses only on a VERIFIED behind state and names the push-ready sequence. Never merges. |
+| Unsettled push | the `push-settle` PostToolUse concern (`src/scripts/hooks/push_settle_hook.ts`) | Fires on git's own ref-advance report, resolves the PR number, and names the literal `ci_settle` command. Warn only. |
+
+### What each one does NOT do
+
+- **The hook never merges.** Resolution belongs to a step run with the result in
+  front of you; a hook that rewrites the tree at the moment the contributor
+  believes their work is finished turns one refused push into an unreviewed
+  commit. It refuses and names the push-ready sequence instead.
+- **The hook cannot see an unverifiable base.** Offline, in CI, on a detached
+  HEAD, or standing on the base itself, `check_branch_freshness` exits 0 and
+  says which — so an unreachable network never blocks a push, and a green there
+  means "did not refuse", not "current".
+- **The concern cannot block.** It is `severity: advisory`,
+  `fail_closed: false`. Leaving a push deliberately unsettled is legitimate;
+  ending the turn silently on one is what the reminder exists to stop. Whether
+  the reminder changes behavior is unmeasured — it ships as a carrier, not as a
+  claim.
+- **Neither reaches a host without the slot.** `agent-config hooks:status`
+  answers which slots are bound where you actually are; `post_tool_use` is
+  unbound on windsurf and copilot, and there the settle obligation is
+  model-carried by the skill alone.
+
+## Cost, stated rather than implied
+
+The pre-push gate set was already measured at 36.05 s against the 25 s
+`pre_push_budget_seconds` ceiling in `src/config/ci-local-parity.yml`, and the
+freshness gate adds ~4.5 s on the green path. That is a real cost on an already
+over-budget hook, and it is recorded here rather than hidden: the trade is 4.5 s
+per push against 52 base merges and 56 failed runs across 50 PRs. On the RED
+path the hook gets *cheaper*, not dearer — the refusal exits before the ~10 s
+regeneration and the preflight set, because everything after it would be
+answered against a base that is about to move.
+
+## The gap this change does NOT close
+
+**The pre-push hook is INSTALLED, not read from source.** `install-hooks.sh`
+writes `.git/hooks/pre-push`, and afterwards it is rewritten only by the
+package manager's post-install lifecycle step or by running the installer
+again. Measured in this repository on 2026-09-04, before this change: the
+installed hook was
+**113 lines** against a source body of ~146 — it was missing header revisions
+merged on 2026-08-30, so it had been stale for days with no signal anywhere.
+
+The freshness gate therefore does nothing on a checkout whose hook predates it,
+and the contributor is not told. That is a real hole in a change whose whole
+subject is "the agent should not leave work for the user to discover", and it is
+recorded rather than papered over:
+
+    task install-hooks     # rewrites .git/hooks/* from source
+
+### Closed 2026-09-05 — the contributor is now told
+
+`check_installed_hooks_fresh` renders what `install-hooks.sh` would write into a
+scratch directory and compares content AND the executable bit against
+`.git/hooks`. It runs in the pre-push body — advisory, and after the
+base-freshness gate — and again from the `post-merge` / `post-checkout`
+auto-sync block, at the moment a pull causes the drift.
+
+**It reports and never refuses, and the ordering is part of the answer.** The
+predicate is "installed == what THIS checkout renders", and `.git/hooks` is
+shared by every linked worktree, so with two worktrees whose installer bodies
+differ at most one satisfies it at a time — a refusal would fire on ordinary
+parallel work and the skip variable would become routine, which retires the
+check rather than enforcing it. And being behind a base that moved the installer
+is the commonest cause of a mismatch, whose repair is to MERGE: re-installing
+from a behind-base checkout writes the older hook set over the shared directory.
+Base freshness therefore answers first, and the notice never prescribes a
+re-install as universally correct. On the checkout that closed the gap it found `pre-push`, `post-merge` and
+`post-checkout` all stale — the same drift, five days on and one hook wider.
+
+It compares rendered output rather than slicing these heredocs, because
+`post-merge` and `post-checkout` are a heredoc PLUS an appended block: no slice
+of the installer equals what it installs, so a slice-based comparison would have
+been wrong for two of six hooks.
+
+**What was deliberately NOT built: the repair.** The roadmap asked for
+`post-merge` to re-run the installer so the hooks fixed themselves with no
+command. Two findings stopped it, and both are worth keeping.
+
+1. **Measured 2026-09-05:** a bash script that `cat >`-overwrites its own path
+   mid-run stops executing at that point and **exits 0**. Every statement after
+   it is skipped, silently. A repair placed in `post-merge` would truncate
+   `post-merge`'s own remaining body — the projection sync and the CLI rebuild —
+   and report success. Any future attempt needs the installer to stage and
+   `mv` into place first.
+2. **Linked worktrees share one `.git/hooks`** through the common dir. "The
+   installed hooks match the checked-out tree" has no unique referent when eight
+   worktrees hold eight versions of the installer: a repair would let whichever
+   worktree checked out last redefine the gates all the others run, and a
+   checkout of an older branch would reinstall older hooks over newer ones.
+
+An AI council (`claude-sonnet-4-5` + `codex-default`, 2026-09-05, two rounds,
+2 of 2 seats present in both) reached the same verdict independently in both
+seats: report, do not repair. *Reopen* on either per-worktree hook isolation
+(`core.hooksPath`) or a branch-independent dispatcher installed once in the
+common dir — both make "which version is authoritative" answerable, which is the
+question the repair cannot currently answer.
+
+### Answered 2026-09-05 — consumers get no git hooks, by decision
+
+A consumer install writes **no git hooks at all** (`src/install/` references
+`.git/hooks` nowhere, and the package manager's post-install lifecycle step does
+not run for a registry dependency), so the pre-push gate is a maintainer-only
+mechanism. The same council, unanimously, made that the decision rather than the
+status quo: the pre-push chain runs this repository's own consistency and
+preflight gate chains, which depend on its Taskfile, its `./scripts-run` shim
+and its generated trees — none of which exist in a consumer project — and a
+dependency install should not establish persistent repository execution. *Revisit-if* a
+consumer-native gate set is designed with its own opt-in command and consent
+step; that is a product feature, not an extension of this installer. Stated for
+consumers in `docs/development.md` § "Git hooks are maintainer-only". Named
+rather than linked: this file is projected byte-identically into
+`dist/agent-src/`, which sits one level deeper, so a repo-root-relative link
+resolves in one copy and not in the other.
+
+## Revisit-if
+
+- A later corpus shows base merges and post-push repair commits at a rate the
+  carriers cannot explain — then the carriers are firing and not landing, and
+  the next lever is delivery, not another reminder.
+- `pre_push_budget_seconds` is enforced by something. Today nothing measures the
+  hook, which is how the set grew past its own ceiling with no signal; once it
+  is measured, this gate is one of the entries that has to justify its slice.

package/dist/agent-src/skills/laravel-mail/SKILL.md

@@ -167,6 +167,50 @@ Route::get('/mail-preview', function () {
 });
 ```
 
+## Surviving the mail client
+
+An email is not a web page. Mail clients strip, rewrite, and ignore CSS that
+every browser honors, so a template that renders correctly in
+`/mail-preview` tells you nothing about the inbox. Markdown templates (above)
+give you a tested baseline for free — this section is what to hold to when a
+design forces you off them.
+
+**Four requirements, in order of what breaks first:**
+
+1. **Table-based layout, not flexbox or grid.** Use nested `<table>` elements
+   with `role="presentation"`, a fixed outer width of 600px, and `cellpadding`
+   / `cellspacing` / `border` set to `0`. `display: flex` and
+   `display: grid` are unsupported or partially supported in the Windows
+   Outlook family and collapse to a single stacked column.
+2. **Inline styles, not a `<style>` block.** Write `style="…"` on the element.
+   A `<head><style>` block is stripped outright by some webmail clients, and
+   class selectors then match nothing. Use a CSS inliner at build time if the
+   template is authored with classes — never ship the classes unresolved. Keep
+   a `<style>` block only for what cannot be inlined (media queries), and treat
+   everything in it as optional.
+3. **No web fonts, no background images, no external JS.** Declare a font stack
+   ending in a system fallback; a remote font silently degrades. Background
+   images require the `v:fill` VML fallback in Outlook, so put the color on
+   `bgcolor` and treat the image as decoration.
+4. **Explicit width and alt text on every image, and no image-only content.**
+   Images are blocked by default in several clients, so an email whose call to
+   action is an image is an email with no call to action.
+
+**The client list worth testing, and what breaks in each:**
+
+| Client | What breaks |
+|---|---|
+| **Outlook 2016-2019 / Windows (Word engine)** | `flex`, `grid`, `float`, `max-width`, `border-radius`, background images, `padding` on `<div>`; the strictest target — if it renders, most others do |
+| **Outlook.com / Outlook 365 web** | strips `<style>` blocks in some views; rewrites `class` attributes; ignores `margin` on several elements |
+| **Gmail web** | clips the message past ~102 KB of HTML with a "view entire message" link — anything below the clip, including the unsubscribe link, is not seen; strips `<style>` when the message is clipped |
+| **Gmail app (iOS / Android)** | no support for embedded `<style>` on non-Gmail accounts; media queries ignored there, so the mobile layout must be the fluid default |
+| **Apple Mail / iOS Mail** | the most permissive; auto-scales small text and auto-links dates and addresses unless suppressed — a false green if it is the only client you check |
+| **Dark mode (Apple Mail, Outlook, Gmail)** | colors are force-inverted; a logo on a hardcoded white background becomes a white box on dark, and `#000` text on a transparent background becomes invisible |
+
+**Verify against a real client, not a preview route.** `/mail-preview` renders in
+a browser and proves none of the above. Send to real accounts, or use a
+rendering service, before the template ships.
+
 ## Core rules
 
 - **Always queue emails** — implement `ShouldQueue` to avoid blocking requests.

package/dist/agent-src/skills/testing-anti-patterns/SKILL.md

@@ -208,6 +208,46 @@ rg -n '\b(it|test|describe)\.skip\b|\.only\b|xit\(|xdescribe\(|@pytest\.mark\.(s
 
 This is the test-surface instance of the `autonomous-execution` N=3 / allowlist-growth antipattern (bulk `skip`/`xfail` to force green counts as the tool being wrong, not the content) and the `verify-before-complete` floor (green must be *earned*, not manufactured).
 
+### The named smells — canonical vocabulary, and what it does NOT cover
+
+The behaviors above are described; two of them also have field names a
+reviewer can cite, and this table is where the name meets the behavior. The
+grep column follows the shape [`ai-code-blindspots`](../ai-code-blindspots/SKILL.md)
+uses: an authoring-time backstop, zero results is the pass, a hit is a prompt
+to read that line — never an auto-fix.
+
+| Canonical name | The behavior, as already described above | Backstop grep |
+|---|---|---|
+| **Magic-number test** | Anti-Pattern 6 — "a hardcoded expected value the code will always emit". The expectation is a literal rather than something derived from the input, so the test cannot disagree with the code. | `rg -n '\b(toBe\|toEqual\|assertEquals\|assertSame)\(\s*-?[0-9]{2,}' tests/` |
+| **Assertion roulette** | The multi-case stack Anti-Pattern 6 *requires* (boundary, error, abuse in one test), written without per-assertion messages — so a failure names a line number and not a reason. The stack is right; the silence is the smell. | `rg -c '\b(expect\|assert\w*\|self\.assert\w*\|\$this->assert\w*)\(' tests/ \| awk -F: '$2 >= 8'` |
+
+Both greps are scoped to **the test file you just wrote**, not to a tree —
+`tests/` above is a placeholder for that path. Run over a whole repository
+they are useless as verdicts: measured on this repository on 2026-09-04 the
+first returns 585 lines and the second 1189 files, because an exact assertion
+against a two-digit literal and a file with eight assertions are both ordinary.
+They are authoring-time prompts to reread one file, exactly as
+`ai-code-blindspots` states, and neither is a gate.
+
+The second grep counts per **file**, not per test — no regex sees a test
+boundary.
+
+**Three further names are deliberately NOT in the table**, recorded here so a
+later round meets a record rather than a fresh argument. Measured 2026-09-04
+over both files of this skill: `roulette`, `eager`, `lazy` and `duplicate` each
+return **0** occurrences, and `hardcoded` returns **6**.
+
+- **Eager test** (one test exercising several behaviors) would carry the same
+  behavior and the same grep as assertion roulette above, and Anti-Pattern 6
+  *prescribes* the shape on purpose. A row for it would be one entry under two
+  names, which is the drift this table exists to prevent.
+- **Lazy test** (several tests over one fixture, differing only in name) is
+  described nowhere above. A row would be new guidance wearing a naming step's
+  clothes.
+- **Duplicate assert** (the same condition asserted twice in one test) is
+  likewise undescribed, and is not greppable without parsing test boundaries —
+  so it could not carry the backstop column even if it were.
+
 ## Output format
 
 1. The mocking decision recorded as a one-line comment in the test file (`// mock at <seam>: <reason>`).

package/dist/agent-src/skills/using-git-worktrees/SKILL.md

@@ -109,6 +109,18 @@ Ask format:
 
 **Recommendation: 1 — `.worktrees/`** — project-local keeps the worktree next to the repo (easy cleanup), and the leading dot keeps it out of `ls`. Caveat: pick 3 if multiple repos must share a single worktree root.
 
+> **A worktree outside the repository root costs the persistent shell cwd.**
+> It sits outside the host's working-directory boundary, so a `cd` into it does
+> not survive the call — Claude Code appends `Shell cwd was reset to <root>` and
+> the next command runs in the main checkout. Every command then repeats its own
+> `cd`, and one that forgets edits the wrong tree silently. Measured 2026-09-05
+> on this repository: 2,128 transcript records carrying that line across 20
+> sessions, alongside 1,694 whose `cd` targeted a worktree placed beside the
+> repo. Choosing option 3 — or any path outside the root — means also declaring
+> the parent directory in the host's working-directory allowlist
+> (`permissions.additionalDirectories` on Claude Code). Options 1 and 2 are
+> inside the root and need nothing.
+
 ### 3. Verify ignore-safety (project-local only)
 
 ```bash