@event4u/agent-config 14.16.0 → 14.18.0

package/dist/agent-src/skills/conventional-commits-writing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 model_tier: medium
 name: conventional-commits-writing
-description: "When writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits."
+description: "When writing a commit message, branch name or squash title — measure the repo's own convention first, Conventional Commits as fallback — even on a bare 'commit this'."
 domain: process
 scope:
   write: []
@@ -22,6 +22,8 @@ packs:
 
 Use this skill when:
 
+- Committing in a repository whose conventions you have not established this
+  session — run `## Procedure: Establish the house convention` first
 - Generating a commit message from staged changes
 - Generating a squash merge title from a PR
 - Deciding the correct Conventional Commit type for a change
@@ -34,6 +36,217 @@ Do NOT use when:
 - The message is already correct and does not need review
 - Following the Git workflow (use `git-workflow` skill)
 
+## Procedure: Establish the house convention (run FIRST, before any message)
+
+Conventional Commits is this suite's **fallback**, not a universal truth. A
+repository that has demonstrably converged on another grammar gets that grammar;
+imposing the shipped default there produces commits that read as foreign in
+`git log` and in review. The precedence, highest first:
+
+| Tier | Source | Binding? |
+|---|---|---|
+| **1 — configured** | `commitlint.config.*` · `.gitmessage` · a `commit-msg` hook (husky / lefthook / `.git/hooks`) · `CONTRIBUTING.md` § Commits · a CI job that validates subjects · release automation that PARSES subjects (semantic-release, changesets, git-cliff, conventional-changelog) | yes — Class A, no approval needed |
+| **2 — measured + approved** | the consensus pass below, after the user says yes | yes, for this repository |
+| **3 — measured, unapproved** | the same pass before the user answers | **no — advisory**; report the mismatch, write Conventional |
+| **4 — default** | Conventional Commits | yes |
+
+Release automation is the trap that makes tier 1 outrank tier 2 even when the
+history disagrees: a repo whose `git log` is 85 % `[JIRA-123] Fix thing` but
+whose manifest (`package.json`, `composer.json`, `pyproject.toml`, `Cargo.toml`)
+runs `semantic-release` or its ecosystem equivalent is a repo **migrating toward**
+Conventional Commits, and the measurement is reading its past, not its intent.
+Check for the parser before you trust the prevalence.
+
+### 1. Look for tier 1 before measuring anything
+
+```bash
+ls commitlint.config.* .commitlintrc* .gitmessage .czrc 2>/dev/null
+git config --get commit.template
+ls .husky/commit-msg .git/hooks/commit-msg 2>/dev/null
+grep -rniE 'semantic-release|git-cliff|conventional-changelog|release-please|commitlint' \
+  package.json composer.json pyproject.toml Cargo.toml .github/workflows/ .gitlab-ci.yml \
+  2>/dev/null | head
+```
+
+**Every one of these produces candidates, not verdicts — open the file before
+you act on the hit.** A `commit.template` proves a template exists, not that it
+constrains the subject: a `.gitmessage` carrying only a body checklist ends
+nothing. `CONTRIBUTING.md` is prose and cannot be grepped for a convention —
+`grep -i commit` matches "please commit early and often" — so read its commits
+section if it has one and take the grammar from the sentences, not from the
+match. Only a **confirmed** source ends the procedure, and when it does, say
+which file answered.
+
+`changesets` is deliberately not in the parser list: it reads `.changeset/*.md`
+files and never parses a commit subject, so its presence says nothing about the
+convention. The four that do parse subjects — semantic-release, git-cliff,
+conventional-changelog, release-please — count only when the hit is a real
+dependency or a wired job, not a mention in a comment.
+
+The tier table above calls a confirmed hit Class A. That is exact for a machine
+-readable config and loose for `CONTRIBUTING.md`, which carries no digest and is
+read by a human judgement — treat a prose source as tier 1 in **precedence** and
+as a quoted sentence in the report, so the next reader can check it.
+
+### 2. Sample the history — native source per dimension
+
+Only **commit subjects** are reliably measurable from a clone. Branch names,
+PR titles and commit granularity have different native sources, and `unknown`
+is a valid, honest result for each:
+
+| Dimension | Native source | Measurable from a clone? |
+|---|---|---|
+| Subject grammar | `git log` | yes |
+| Branch naming | forge refs / `git branch -r` | partially — merged branches are often deleted |
+| PR title shape | forge API (`gh pr list`) | only with forge access |
+| Granularity (atomic vs batched) | per-commit diff stat | **no** where the repo squash-merges — the evidence was destroyed at merge |
+
+Resolve the trunk explicitly. `origin/HEAD` is set by `git clone` and is absent
+in a `git init` + `git remote add` checkout, in many CI checkouts and in
+worktrees, where the sample command would die rather than return nothing:
+
+```bash
+TRUNK=$(git symbolic-ref -q --short refs/remotes/origin/HEAD)
+[ -n "$TRUNK" ] || TRUNK=$(git rev-parse -q --verify origin/main >/dev/null && echo origin/main)
+[ -n "$TRUNK" ] || TRUNK=$(git rev-parse -q --verify origin/master >/dev/null && echo origin/master)
+[ -n "$TRUNK" ] || TRUNK=HEAD          # no remote at all: this checkout is the trunk
+git log "$TRUNK" --no-merges -n 200 --since='24 months ago' \
+  --pretty=format:'%H%x09%aN%x09%aE%x09%s'
+```
+
+**`--first-parent` is deliberately absent.** On a merge-commit workflow the
+trunk's first-parent chain is merge commits, which `--no-merges` then drops —
+the two together leave only what was committed straight to the trunk, which on
+a PR-based repo is nearly nothing. The convention lives in the feature commits,
+so walk the whole reachable history and exclude merges alone.
+
+The terminal `HEAD` matters as much as the first line: a chain that ends with an
+unset `TRUNK` hands `git log` an empty argument, which walks `HEAD` anyway —
+silently doing the right thing on a local repo while hiding that the resolution
+failed on one where it should not have.
+
+`%H` leads the format because two of the exclusions below need the commit, not
+just its subject. Drop, from the sample:
+
+- **bot authors** — `[bot]`, `dependabot`, `renovate`, `github-actions`,
+  `semantic-release`, `release-please`;
+- **automation subjects** — `^Revert `, `^Merge `, `chore(release)`,
+  `^Bump `, a bare `v?\d+\.\d+\.\d+`;
+- **bulk imports** — resolve with the hash the format carries:
+  `git show --stat --oneline <sha> | tail -1` and drop anything over 500 files.
+  Check this only for the handful of subjects that read like an import; running
+  it per commit costs 200 subprocesses to remove two rows.
+
+### 3. Classify each surviving subject
+
+Match in order, first hit wins. These are POSIX extended regular expressions,
+given outside a table because a markdown cell would need the alternation pipes
+escaped and `\|` in ERE is a literal pipe, not an alternation:
+
+```
+conventional      ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?!?: 
+ticket-prefix     ^\[[A-Z][A-Z0-9]+-[0-9]+\][: ]|^[A-Z][A-Z0-9]+-[0-9]+[: ]
+gitmoji           ^:[a-z0-9_+-]+:[[:space:]]|^[^[:ascii:][:space:]]
+imperative-plain  ^[A-Z][a-z]+[[:space:]].*[^.]$
+other             everything else
+```
+
+`imperative-plain` is deliberately mechanical — capitalised first word, no
+trailing period — and does **not** test for the imperative mood. Mood needs a
+verb lexicon this procedure does not ship, and `Update` versus `Updated` is
+exactly the pair a lexicon-free test cannot separate. That is a stated limit of
+the classifier, not a gap to fill by guessing: a repo whose only distinction
+from Conventional is mood will read as `imperative-plain` either way, and the
+mood question belongs in the ask at step 6.
+
+`classifier_version` in step 7 names the revision of THIS section — the five
+patterns above plus the exclusions in step 2. It is a provenance stamp so a
+later measurement can be compared against a like one; it does not claim an
+executable classifier ships anywhere in the tree.
+
+Record the runner-up family too — a near-tie is itself the finding.
+
+### 4. Aggregate, capped per author, per half
+
+Raw commit counts let one prolific author or an unfiltered bot define the house
+style; one-vote-per-author lets a drive-by contributor with two commits veto it.
+Cap instead: split the sample into a newer and an older half by position first,
+then let **each author contribute at most 20 commits to each half**. Capping the
+sample as a whole would let one author's newest 20 fill their entire quota and
+empty the older half, which is precisely where step 5's coherence check has to
+look.
+
+Compute the dominant family's share over the **capped** total, and report that
+total — a percentage quoted against the raw eligible count describes a statistic
+nobody computed.
+
+With fewer than three authors the cap is **off**: there is no dominance to guard
+against, and a cap of 20 would put the single-maintainer bar's own `n ≥ 30`
+out of reach of its denominator.
+
+### 5. The evidence bar
+
+A measured convention is eligible to be proposed only when **all** hold:
+
+- **n ≥ 30** eligible commits after exclusions;
+- **≥ 80 %** capped-weighted share for the dominant family, over **≥ 3 human
+  authors** — or, with **one or two** authors, an uncapped **≥ 90 %** share over
+  n ≥ 30. Two authors take the stricter branch rather than falling between the
+  two: a two-person repo is a small-team repo, and leaving it unreachable by
+  both branches would make the measurement permanently advisory there;
+- **temporal coherence** — the same family is dominant in the newer half of
+  the sample *and* in the older half. If the halves disagree materially the
+  repository is **migrating**: abstain, name the change point, and use the
+  newer half's family only if it independently clears the bar.
+
+> The 80 % figure is the stricter of two council positions (2026-09-04,
+> anthropic + openai, 2/2 quorum: 70 % vs 80 % + a two-thirds-of-authors
+> clause). The per-author cap is why the separate author-share clause was not
+> also adopted — it already answers the dominance concern the clause existed
+> for. These are policy heuristics, not statistically derived thresholds.
+> **Revisit-if:** a labelled corpus of repositories shows a false-positive or
+> false-negative rate that a different bar would fix.
+
+### 6. Ask — never adopt silently
+
+Below the bar, or on a migrating repo: use Conventional Commits and say so
+**once**, in one line, when a commit is actually requested. Do not ask.
+
+At or above the bar, ask once, as numbered options (per `user-interaction`):
+name the family, the share **and the capped total it was computed over**, the
+author count, and — if a tier-1 parser exists — the tooling that would stop
+parsing.
+
+### 7. Persist the answer where the next session finds it
+
+Write the measurement as a Class-B convention card under
+`agents/memory/curated/conventions/quarantine/commit-subject.md`; the user's
+approval is what moves it to `approved/`. Carry `observed_n`,
+`dominant_share`, `author_count`, `sample_window`, `classifier_version`, and
+`confirm_against` — aggregates only, never per-author identities. Re-measure
+and re-review when the share falls below **70 %**, when a tier-1 source
+appears, or when the newer half's family changes.
+
+## What a measurement may never lower
+
+Prevalence answers *what happened*, never *what the agent is permitted to do* —
+so a house convention can change how a commit reads, and can never change what
+the agent is allowed to commit. Three override policies:
+
+| Policy | Applies to | Examples |
+|---|---|---|
+| `never` | authorization · security · integrity · destructive history · agent provenance | [`commit-policy`](../../rules/commit-policy.md) · [`secret-vcs-guard`](../../rules/secret-vcs-guard.md) · [`git-history-discipline`](../../rules/git-history-discipline.md) · [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) · [`no-attribution-footers`](../../rules/no-attribution-footers.md) |
+| `explicit-only` | governance preferences a maintainer may lift deliberately, that history may not | [`no-decorative-emojis-in-git-surfaces`](../../rules/no-decorative-emojis-in-git-surfaces.md) |
+| `approved-observation` | representation — subject grammar, ticket prefixes, type vocabulary, capitalisation, mood, subject length, body wrapping | this procedure |
+
+So a repository whose history is 70 % emoji subjects does **not** license emoji
+subjects: that rule is `explicit-only`, and the lift is the maintainer's word,
+not the log's. A repository whose history is 60 % attribution trailers licenses
+nothing at all. The council split here (one member argued subject-line emoji is
+a defect and absolute, the other that it is governance taste) resolves to
+`explicit-only` because both positions agree on the operative half — **history
+may not lift it**.
+
 ## Procedure: Generate commit message
 
 ### 1. Identify the actual intent
@@ -110,9 +323,12 @@ Or add `BREAKING CHANGE:` in the commit body/footer.
 
 ## Output format
 
-1. Recommended commit message(s)
-2. Brief rationale for type choice
-3. Split suggestion if the change should be multiple commits
+1. The convention in force and the tier that established it — `configured
+   (commitlint.config.js)`, `approved (ticket-prefix, 84% of 137)`, or
+   `default (Conventional Commits)`
+2. Recommended commit message(s)
+3. Brief rationale for type choice
+4. Split suggestion if the change should be multiple commits
 
 ## Gotcha
 
@@ -120,6 +336,10 @@ Or add `BREAKING CHANGE:` in the commit body/footer.
 - File type alone does not determine commit type (e.g. a `.md` change can be `feat` if it's a new feature doc)
 - Squash merge titles should describe the net effect, not every internal detail
 - `refactor` means NO behavior change — if behavior changes, use `feat` or `fix`
+- A high dominant share over a long window can hide a format change six months
+  ago — the temporal-coherence check, not the share, is what catches it
+- Squash-merging destroys commit-granularity evidence; report granularity as
+  `unknown` there rather than inferring it from the trunk
 
 ## Frugality Standards
 
@@ -146,6 +366,11 @@ to every commit message you author.
 
 ## Do NOT
 
+- Do NOT impose Conventional Commits on a repository that has a configured or
+  approved convention of its own
+- Do NOT adopt a measured convention without asking — below tier 2 it is
+  advisory, and silence is not approval
+- Do NOT let prevalence lift a `never` or `explicit-only` floor
 - Do NOT use vague messages: `update stuff`, `fix bug`, `changes`
 - Do NOT use `refactor` for bug fixes
 - Do NOT use `chore` for meaningful behavior changes
@@ -157,3 +382,8 @@ to every commit message you author.
 - Rule: `commit-conventions` — base format, types, scope, examples
 - Guideline: `docs/guidelines/php/git.md` — type selection rules, anti-patterns, decision checklist
 - Command: `/commit` — uses this skill for message generation
+- Command: `/fix commit-messages` — retro-fits past subjects to the convention
+  this procedure establishes
+- Context: `contexts/execution/project-intelligence.md` — the Class-B
+  consensus-pass, quarantine→approved gate and deviation-staleness mechanism
+  this procedure instantiates for commit subjects

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/terraform/SKILL.md

@@ -96,6 +96,35 @@ Check existing modules in the project for which registry modules are used.
 - Security groups follow least-privilege: only allow traffic between known services.
 - IAM policies use specific resource ARNs, not wildcards (except where unavoidable).
 
+### Permissive defaults and missing security blocks
+
+The failure that reaches production is almost never a pinned-version mistake;
+it is a resource that works either way and was left on its permissive default.
+Four constructs carry it. Each backstop grep is over the `.tf` tree you are
+changing, not over this repository.
+
+| Backstop grep | What a hit means | Override condition |
+|---|---|---|
+| `grep -rn '0\.0\.0\.0/0' --include='*.tf' .` | An ingress or egress rule whose CIDR is 0.0.0.0/0, i.e. open to the whole internet. On a management or database port stop and treat it as CRITICAL - the corpus row enumerates which ports those are. | A deliberately public listener - an ALB or CloudFront origin on 80/443. Nothing else. Record the reason next to the rule. |
+| `grep -rn 'publicly_accessible\|block_public_acls\|ignore_public_acls' --include='*.tf' .` | Either `publicly_accessible = true` on a database, or a bucket with no public-access block present at all. Absence is the more common hit and the grep returning nothing is the failing case. | A bucket that genuinely serves public web assets, with the policy written explicitly rather than inherited from a default. |
+| `grep -rnE '"(Action\|Resource)" *: *"\*"\|= *\["\*"\]' --include='*.tf' .` | A wildcard IAM action or resource. One compromised workload credential then reaches everything in the account. | A named, reviewed exception - `iam:PassRole` scoped by condition, or a bootstrap role. Never the default. |
+| `grep -rL 'encrypt' --include='*.tf' .` (lists files with NO encryption mention; `-L` prints names only, so no `-n`) | A storage, volume, snapshot, or database resource with no encryption block. | None for data at rest. A resource holding no data at all. |
+
+Read the surface class before the fix, not after: the mitigation text, the
+abuse case, and the negative test live in the `infrastructure` rows of
+[`threat-modeling`](../threat-modeling/SKILL.md)'s corpus, which is the single
+authority for them. Ask that skill's grounded-corpus step for the
+`infrastructure` surface class - it carries the invocation - and describe the
+change you are making, e.g. *terraform security group ingress open to
+0.0.0.0/0*. Do not copy the command here: one skill owns that interface, for
+the same reason one file owns the control text.
+
+Those rows also carry a `Decided by:` clause stating which check actually
+decides each one. For all four constructs above that clause reads NO CHECK IN
+THIS REPOSITORY - no HCL or IAM-policy parser ships here, so these greps and
+your own IaC policy scanner are the whole enforcement story. Do not write or
+imply otherwise.
+
 ## Common patterns
 
 ### ECS service with CodeDeploy (Blue/Green)