@event4u/agent-config 16.4.0 → 17.0.0

package/docs/MIGRATION.md

@@ -42,6 +42,57 @@ reason, which no arithmetic can.
 or that promises a future breaking removal, gets a row here in the same commit
 that makes the promise. A promise with no row is not tracked and will be missed.
 
+## 17.0.0 — Node 22 is the floor, and the rule-layer form is no longer a setting
+
+✋ manual on Node 20 · 🔄 automatic for the removed settings keys.
+
+### Node 22.6 or newer is required
+
+`engines.node` is `>=22.6.0` (ADR-290). Node 20 left its upstream support
+window on 2026-04-30, and this package backports nothing (`SECURITY.md`), so
+the old `>=20.11.0` floor promised support that was never given. The floor is
+22.6 rather than 22.0 because 22.6 is the first Node with
+`--experimental-strip-types`: `/pr merge`'s danger gate runs the base copy of
+its classifier under plain `node` with that flag, and on 22.0–22.5 it would
+fall back to the checkout's `tsx`, which a head that changes a dependency
+manifest can influence.
+
+- **On Node 22.6 or newer:** nothing to do.
+- **On Node 22.0–22.5:** upgrade to a current Node 22 release.
+- **On Node 20:** upgrade Node before taking 17.0.0. npm reports the
+  `engines` mismatch as a warning (a hard failure under pnpm, yarn or
+  `engine-strict`); the unattended updater refuses the release outright — it
+  compares `engines.node` against the running Node, and the release is
+  classed `action`, which it never installs on its own.
+- **Staying on Node 20:** the last compatible release is **16.5.0**. It
+  receives no security, bug or compatibility backports. Pinning it keeps the
+  install working; it does not keep it maintained.
+
+### Three settings keys are removed
+
+`lean_projection.mode`, `lean_projection.hosts` and
+`projection.rule_workspaces` are gone (ADR-293). How the rule layer is
+delivered is now computed per layer, host and machine, and the computation
+returns the full layer whenever any of its conditions is missing.
+
+- **Never set them:** nothing to do.
+- **Set one of them:** a leftover value is ignored with one line naming what
+  decides instead. For this release, an explicit `lean_projection.mode:
+  eager-all` or `legacy-all` — the values that meant *keep the full layer* — is
+  read once more and converted into the install receipt's pin. Every other
+  value is dropped. Delete the keys at your convenience.
+- **Want the full layer regardless:** run `agent-config install --full`.
+  `agent-config doctor --check layer-form` shows which form each layer is in
+  and why.
+
+### Also in 17.0.0 — changes that landed after 16.5.0
+
+The two rows of the `BREAKING_CHANGES.md` pending table ship in this release:
+three `fail_closed` hook guards now run on installs where the hook command
+used to end silently, and `uninstall --global --purge` deletes only what this
+package recorded writing rather than whole host configuration roots. The
+migration for each is in that row.
+
 ## 16.2.0 — `doctor --json` reads the forge, and `--no-forge` opts out
 
 💡 advisory · ✋ manual only if you scripted `doctor` as an offline diagnostic.
@@ -93,6 +144,41 @@ every run, including a single-check run, is the surprising default, and
   Both still work and are still the more specific instruction: they beat
   `--online` when both are given.
 
+### Also in 16.4.0 — 46 settings keys are retired
+
+💡 advisory · 🔄 automatic — **no consumer action unless you set one of them.**
+
+Each retired key's shipped default became fixed behavior, and every reader of
+it — code, rule and command prose, the setup wizard — was rewritten to state
+that default in the same change
+([`b35d432b1`](https://github.com/event4u-app/agent-config/commit/b35d432b11cc3328517c7963c570bb1a06b8dda7)).
+The registry went from 15 retired keys to 61; the 46 new ones span 21 prefixes,
+the largest being `reasoning` (10), `commands` (8) and `hooks` (6).
+
+**What happens to a leftover value.** Nothing applies it. No reader consults a
+retired key, so a value still sitting in your `.agent-settings.yml` is ignored
+rather than honoured — including a value that differs from the default it
+replaced. The loader surfaces it instead, once per key per process run, on
+stderr:
+
+```
+<key> was removed (<what decides instead>); ignored.
+```
+
+The exit code never changes, so a leftover key cannot fail a run; it can only
+tell you about itself. Each line names what decides the behavior now, because
+the 46 do not share one retirement reason — some were replaced by a fixed
+default, and five were never read by any code path at all.
+
+**What to do.** Delete the keys from your `.agent-settings.yml` when the notice
+names one. If you were relying on a non-default value, the line tells you where
+that decision now lives; there is no replacement key to set.
+
+**Where the list lives.** `src/scripts/_lib/settings_removed_keys.ts` — the
+`REMOVED_KEYS` map, one row per key with its reason. It is the single source
+for both the notice and the settings linter, so the file is the answer to "was
+this key retired, and what replaced it?".
+
 ### How to tell the two apart in the output
 
 The block gained a **`not_checked`** key, present on every run, so a consumer
@@ -110,8 +196,9 @@ row states, which is the misreading this key exists to prevent.
 `read_from_forge` keeps its meaning and is unchanged.
 
 The flag is additive: a run that passes none of these reads the forge exactly
-as before. Whether offline becomes the default is an open owner decision
-(`road-to-findings-that-get-a-disposition`, blocker `doctor-network-default`).
+as before. **Offline is the default as of 16.4.0** — see the section above,
+which is where blocker `doctor-network-default` of
+`road-to-findings-that-get-a-disposition` was settled and shipped.
 
 ## 16.0.0 — the stored standing-payload ceiling is deleted
 

package/docs/THIRD-PARTY-NOTICES.md

@@ -23,3 +23,30 @@
 - **Files:** `src/scripts/cost/budget.mjs`, `src/scripts/cost/track.mjs`
 - **Transformation:** Forked from the upstream cost-tracker plugin's budget.mjs and track.mjs, then re-derived against a store this repository already had. The upstream persists through an MCP memory tool (`mcp__claude-flow__memory_store`); that dependency is removed entirely and replaced with a local append-only JSONL at agents/cost-tracking/sessions.jsonl plus a budget.json beside it, so the scripts run under bare `node` with no MCP server present — which is what lets them ship to consumers as plain .mjs (the /cost:report command doc states why tsx is not available on that path). track.mjs additionally gained dedup and a main/subagent split whose logic is MIRRORED, not imported, from src/scripts/_lib/cc_transcript.ts, and pricing constants are kept in sync with REFERENCE.md rather than carried from upstream. The borrow is recorded here rather than as an in-file source name because MIT requires the copyright and permission notice to travel with copies, not to sit inside each source file: docs/THIRD-PARTY-NOTICES.md is generated from this ledger and is shipped in package.json's files list in the same change, which is what actually discharges the obligation for a consumer who receives src/scripts/ from npm.
 - **Cleared by:** human
+
+## https://github.com/google/fonts
+
+- **License:** OFL-1.1
+- **Source SHA:** 47d54ca1ebb14fd864695f1d39dc734f39017c33
+- **Borrowed:** 2026-10-19
+- **Files:** `tests/fixtures/fonts/poppins/Poppins-Regular.ttf`, `tests/fixtures/fonts/poppins/OFL.txt`
+- **Transformation:** Not a code borrow and deliberately not transformed: the geometric sans is vendored byte-for-byte as held-out ground truth for the type-reconstruction benchmark (internal/bench/type-reconstruction-PREREG.md), its license text committed beside it. No outline, table or name changes, so the Reserved Font Name clause is not engaged. Repository-only under the 2026-10-16 council amendment: tests/ is outside package.json#files, export-ignored and docker-ignored, and tests/scripts/typeface_fixture_bound.test.ts checks the produced npm tarball, git archive and container contexts.
+- **Cleared by:** ledger
+
+## https://github.com/google/fonts
+
+- **License:** OFL-1.1
+- **Source SHA:** 47d54ca1ebb14fd864695f1d39dc734f39017c33
+- **Borrowed:** 2026-10-19
+- **Files:** `tests/fixtures/fonts/lato/Lato-Regular.ttf`, `tests/fixtures/fonts/lato/OFL.txt`
+- **Transformation:** Not a code borrow and deliberately not transformed: the humanist sans is vendored byte-for-byte as held-out ground truth for the type-reconstruction benchmark (internal/bench/type-reconstruction-PREREG.md), its license text committed beside it. No outline, table or name changes, so the Reserved Font Name clause is not engaged. Repository-only under the 2026-10-16 council amendment: tests/ is outside package.json#files, export-ignored and docker-ignored, and tests/scripts/typeface_fixture_bound.test.ts checks the produced npm tarball, git archive and container contexts.
+- **Cleared by:** ledger
+
+## https://github.com/google/fonts
+
+- **License:** OFL-1.1
+- **Source SHA:** 47d54ca1ebb14fd864695f1d39dc734f39017c33
+- **Borrowed:** 2026-10-19
+- **Files:** `tests/fixtures/fonts/pt-serif/PT_Serif-Web-Regular.ttf`, `tests/fixtures/fonts/pt-serif/OFL.txt`
+- **Transformation:** Not a code borrow and deliberately not transformed: the serif is vendored byte-for-byte as held-out ground truth for the type-reconstruction benchmark (internal/bench/type-reconstruction-PREREG.md), its license text committed beside it. No outline, table or name changes, so the Reserved Font Name clause is not engaged. Repository-only under the 2026-10-16 council amendment: tests/ is outside package.json#files, export-ignored and docker-ignored, and tests/scripts/typeface_fixture_bound.test.ts checks the produced npm tarball, git archive and container contexts.
+- **Cleared by:** ledger

package/docs/contracts/settings-classes.md

@@ -249,8 +249,22 @@ dispatch runs, not WHETHER the layer exists, so they keep their own C rows.
 |---|---|
 | A — preference | 9 |
 | B — consent | 3 |
-| C — guarded | 100 |
-| **Total** | **112** |
+| C — guarded | 104 |
+| **Total** | **116** |
+
+It rose to 116 on 2026-10-21 when the advisories council round 3 added `advisories.kev` — one C, `policy`: it decides whether a refresh reads the CISA catalog, the independent switch both seats asked for beside the egress key (evidence `advisory-kev-epss-sources-20261021`).
+
+It rose to 115 on 2026-10-21 when `road-to-advisories-heard-the-same-day` step 4.3 added `advisories.mode` and `advisories.egress` — two C. `mode` is `consent`: it adds a line to the first session start of every day, which an install that never asked must not have switched on for it by an agent. `egress` is `policy`: it decides which package names leave the machine, the privacy boundary the roadmap's D4 fixes for private names and this key extends to all of them.
+
+It rose to 113 on 2026-10-21 when `road-to-worktrees-that-leave-after-the-merge` step 4.2 added `worktrees.cleanup` — one C, `consent`: `auto` deletes worktree directories without asking, and a council round on 2026-10-21 held 2/2 that installation alone is not consent to that, so the key ships `notify` and no agent write path may reach it (ADR-295). It is a removal key; ADR-229's deletion of the creation key `worktrees.mode` is untouched.
+
+It fell to 112 on 2026-10-20 when `road-to-a-setup-that-decides-itself` removed the three projection keys the package now decides itself — `lean_projection.mode`, `lean_projection.hosts` and `projection.rule_workspaces` (two `derivable`, one `policy`, all C). Each carries a `REMOVED_KEYS` reason, so an older install that still sets one warns once and boots unchanged.
+
+It rose to 115 on 2026-10-20 when `road-to-a-retro-the-merge-runs` step 0.2 added `retro.enabled` (ADR-292) — one C, `consent`: it arms automatic producers on the merge, push and first-session paths, and it ships `true` by the owner's directive of 2026-10-12, which is the documented-decision shape `continuity.auto_record` already has. A class-B key could not carry that default; the class C fence keeps an agent from switching it either way, and `MERGEABLE_KEYS` lets a user-global `false` hold.
+
+It rose to 114 on 2026-10-20 when `road-to-an-update-that-installs-itself-only-when-it-is-safe` step 4.1 added `update.mode` — one C, `consent`: it is a standing authorisation to replace the user's global install, and `auto` is an action they cannot un-see, so no agent write path may reach it. An absent key resolves to `notify`, which installs nothing.
+
+It rose to 113 on 2026-10-15 when `road-to-placeholders-on-the-wire` step 1.4 added `egress.placeholders.mode` — one C, `policy`: it decides whether conversation content is replaced before it reaches local stores, and the default for consumers is an owner decision no agent may take by writing the key.
 
 <!-- derivable-retirement-2026-10-09 -->
 It fell to 112 on 2026-10-09 when `road-to-settings-classes-derivable-surface-stagnation` Phase 2 retired 46 `derivable` keys (17 A, 29 C) whose absence changes no effective default: every reader was removed with the key and left the old default as the only behavior, and each key carries a `REMOVED_KEYS` reason, so an older install that still sets one warns once and boots unchanged. By group: 2.1 output and tone — `telegraph.speak`, `tokens.rich_skills`, `personal.minimal_output`, `personal.play_by_play`, `personal.pr_comment_bot_icon`, `verbosity.intent_announcements`, `verbosity.preview_artifacts`, `verbosity.routine_confirmations`, `verbosity.post_action_reports`; 2.2 reasoning protocol switches — `reasoning.auto_gate`, `reasoning.components.orchestrator`, `reasoning.components.notes_first`, `reasoning.components.grounding`, `reasoning.components.intent`, `reasoning.components.complexity_first`, `reasoning.components.verifier_default`, `reasoning.components.prediction_tracking`, `reasoning.components.decision_ledger`, `reasoning.components.uncertainty_budget`; 2.3 roadmap cadence — `roadmap.skip_pre_run_gate`, `roadmap.dashboard_regen_cadence`; 2.4 command suggestion and PR creation — `commands.auto_detect`, `commands.suggestion.enabled`, `commands.suggestion.confidence_floor`, `commands.suggestion.cooldown_seconds`, `commands.suggestion.max_options`, `commands.create_pr.api_examples`, `commands.create_pr.ui_paths`, `commands.create_pr.api_paths`; 2.5 memory and knowledge sharing — `memory.cadence`, `memory.review_threshold`, `knowledge.global_sharing.redaction.enabled`, `knowledge.global_sharing.redaction.halt_on_trigger`, `knowledge.global_sharing.auto_promote_threshold`, `knowledge.global_sharing.freshness.hypothesis_after_days`, `knowledge.global_sharing.freshness.stale_after_days`; 2.6 hooks and engine — `hooks.concern_budget.max_per_event`, `hooks.concern_budget.hard_fail`, `decision_engine.surface_traces`, `decision_engine.on_block_fallback`, `explain.enable_last`; 2.7 remaining — `project.pr_template`, `pipelines.skill_improvement`, `consistency.cross_source`, `subagents.downshift`, `ai_team.suppress_setup_hint`. Selection and per-key evidence: `agents/evidence/analysis/settings-derivable-retirement-audit-2026-10-09.md`.
@@ -393,11 +407,11 @@ the template, which is the drift this contract exists to prevent.
 
 | Disposition | Keys |
 |---|---|
-| derivable | 37 |
+| derivable | 35 |
 | un-inferrable | 10 |
-| consent | 48 |
-| policy | 17 |
-| **Total** | **112** |
+| consent | 52 |
+| policy | 19 |
+| **Total** | **116** |
 
 First measured 2026-08-12 at 140 leaves (derivable 88 · consent 38 ·
 un-inferrable 9 · policy 5), from the table below rather than predicted — the
@@ -496,12 +510,9 @@ Rows follow template order, so a diff against the template reads straight down.
 | `agent_config_version` | C | `""` | installer-owned pin selecting which package code executes | derivable — the installed package's own `package.json` version; `check_template_pin_drift` already enforces pin == package.json |
 | `profile.id` | C | `developer` | master axis selecting the projected skill and command surface | un-inferrable |
 | `projection.mode` | C | `scoped` | governs which artefacts reach the host trees at all | derivable — the resolved active-profile + `runtime.active_packs` set `_resolve_scoped_projection` already computes |
-| `projection.rule_workspaces` | C | 9 workspaces | allowlist deciding which rules reach the agent | derivable — the rule's own `workspaces:` frontmatter intersected with the active profile/pack set, as `rule_scope.ts` already performs for `rule_packs: auto` |
 | `projection.rule_packs` | C | `[]` | second allowlist axis on rule projection | derivable — the `auto` derivation already implemented in `src/install/rule_scope.ts` |
 | `discipline_profile` | C | `__DISCIPLINE_PROFILE__` | master switch for the discipline rule tier | derivable — its own `auto` resolution against `src/config/host-capabilities.yml` |
 | `rule_loading_tier` | C | `__RULE_LOADING_TIER__` | legacy master switch for rule loading | derivable — `discipline_profile` supersedes it with a documented mapping (minimal→off, balanced→essential, full→full) |
-| `lean_projection.mode` | C | `delivery` | `thin` and `delivery` remove rule bodies from the agent's standing context. Two defaults, and this column carries the template one: the shipped template has said `delivery` since ADR-267, while the parser fallback for a value that resolves from no layer stays `eager-all` (ADR-267 decision 4) | derivable — `probe_host_compliance.ts` already computes the per-host thin/eager recommendation |
-| `lean_projection.hosts` | C | `[claude-code]` | decides WHICH hosts a thinning mode may thin, so an added id removes rule bodies from that host's context | policy — the value is a package-level decision the tree already holds: ADR-267 scopes the shipped `delivery` flip to `claude-code` alone. NOT `derivable`, and the distinction is the whole reason for this row: the mechanism that would compute an admissible host set, `admissibleUnderE3` in `src/scripts/_lib/injection_effect.ts`, admits **nothing** today — `src/config/host-injection-effect.json` carries 1 `observed-false` and 8 `unobserved` rows and no `observed-true` — so a derivation would yield `[]` rather than the shipped `[claude-code]`. Naming a mechanism that returns empty as the replacement would put a key in the deletion queue whose deletion would silently change the default. Move target: the ADR plus that census, once a host earns an `observed-true` row |
 | `cost.budgets.daily` | C | `0` | rolling spend ceiling | consent |
 | `cost.budgets.weekly` | C | `0` | rolling spend ceiling | consent |
 | `cost.budgets.monthly` | C | `0` | rolling spend ceiling | consent |
@@ -582,11 +593,13 @@ Rows follow template order, so a diff against the template reads straight down.
 | `commands.create_pr.screenshots` | C | `false` | puts captured screenshots into a published PR body | consent |
 | `continuity.auto_record` | C | `"on"` | arms an automatic producer on the normal session-end path | consent |
 | `continuity.run_checkpoints` | C | `"on"` | disabling it removes a recovery artifact a killed run resumes from | consent |
+| `retro.enabled` | C | `true` | arms automatic producers on the merge, push and first-session paths (ADR-292) | consent |
 | `memory.redact_patterns` | C | `[]` | deny-list of secret and PII regexes | policy |
 | `memory.session_index` | A | `"off"` | injects a compact index at session start | derivable — the row cap and index cost the mechanism already computes; the flag only holds an unproven ship-criterion open |
 | `memory.learn_on_session_end` | B | `false` | turns on automatic memory writes at session end | consent |
 | `knowledge.global_sharing.enabled` | C | `true` | kill-switch over cross-project egress | consent |
 | `knowledge.global_sharing.allowed_tiers` | C | `[public]` | allowlist for that egress | consent |
+| `egress.placeholders.mode` | C | `"off"` | C-tests 6 and 8 — it decides whether conversation content is replaced before it reaches local stores and, once the host rewrite exists, a model provider, and lowering it erases what the egress record would have shown | policy — whether a consumer's content is replaced by default is the owner decision `default-mode-for-consumers`; no tree fact computes a protection preference |
 | `hooks.concern_budget.tier1_concerns` | C | `[]` | allowlist of concerns permitted to fail closed | policy |
 | `hooks.injection_scan.enabled` | C | `false` | the prompt-injection scanner | derivable — the scanner's own signature match on the tool envelope; warn-only and silent on no hit |
 | `hooks.rtk_wrap.enabled` | C | `false` | configures code that runs on every tool call | derivable — the live PATH and identity probe the hook already runs; silent when rtk is absent |
@@ -603,6 +616,11 @@ Rows follow template order, so a diff against the template reads straight down.
 | `decision_engine.on_block` | C | `stop` | `warn` advances past a gate that fired | derivable — the non-interactive probe decides ask-versus-stop, and the fired gate's own action decides the rest |
 | `decision_engine.ask_timeout_seconds` | C | `30` | how long a fired gate waits before falling back | derivable — the same non-interactive probe: where nobody can answer there is nothing to wait for |
 | `update_check.enabled` | C | `true` | a background safety check; disabling it pins the user to known-vulnerable code | consent |
+| `advisories.mode` | C | `notify` | a notice at every first session start of a day; turning it on for an install that never asked is a flip the agent may not make | consent |
+| `advisories.egress` | C | `query` | decides which package names and versions leave the machine on a refresh | policy |
+| `advisories.kev` | C | `on` | decides whether a refresh reads the CISA known-exploited catalog that raises a tier | policy |
+| `update.mode` | C | `notify` | a standing authorisation to replace the user's global install; `auto` is something they cannot un-see happening | consent |
+| `worktrees.cleanup` | C | `notify` | a standing authorisation to delete worktree directories on the proven-merged set; `auto` removes them unasked (ADR-295) | consent |
 | `legal_review_prep.acknowledged` | C | `false` | the consent gate; the safety floor requires the wizard checkbox | consent |
 | `legal_review_prep.require_council` | C | `true` | a fail-closed defence-in-depth gate | consent |
 

package/docs/guidelines/agent-infra/api-cost-levers.md

@@ -127,9 +127,10 @@ version 2.1.220 (2026-07-30), re-check on drift:**
 - A **fork** inherits the parent's system prompt, tools, and conversation
   history exactly, so its first request **reads the parent's cache** instead
   of writing a fresh one — the only documented mechanism that shares a cache
-  across a dispatch boundary. Forking forces background mode, which changes
-  the tool set and therefore invalidates the very prefix that motivated the
-  fork; weigh that cost before reaching for it — see the fork-vs-subagent
+  across a dispatch boundary. Forking forces background mode; on a host
+  whose row says `fork_shares_cache: true` (Claude Code 2.1.302, observed) the
+  fork still reads the parent's prefix and keeps its tool pool, elsewhere that
+  is unobserved; weigh the tool-fit cost before reaching for it — see the fork-vs-subagent
   ordering rule in See also.
 - Either way, the **cold-start preamble is re-written on every spawn** — the
   always-loaded rule set, the tool definitions, and the dispatch prompt are

package/docs/guidelines/agent-infra/model-recommendation.md

@@ -12,13 +12,19 @@ double-ask, never front-load the question.
 
 ## Source of truth — the capability tier
 
-Each skill/command declares `model_tier: lite | medium | high | inherit`
-(ADR-035) — a band, not a model. `inherit` = "no opinion, keep the session
-model". The task→tier heuristics live in
+Each skill/command declares `model_tier: lite | medium | high | frontier |
+inherit` (ADR-035) — a band, not a model. `inherit` = "no opinion, keep the
+session model". The task→tier heuristics live in
 `contexts/model-recommendations.md` — cite them, don't restate. The **only**
 tier→model mapping the package maintains is the Claude generator's
-(`high→opus`, `medium→sonnet`, `lite→haiku`); every other agent resolves the
-band to its own line-up.
+(`frontier→fable`, `high→opus`, `medium→sonnet`, `lite→haiku`); every other
+agent resolves the band to its own line-up.
+
+`frontier` is named in both halves of that sentence because
+`TIER_TO_CLAUDE_MODEL` in `src/scripts/_lib/model_tier.ts` has mapped it since
+the fourth family landed. While this page listed three bands, a skill author
+reading the declarable set here could not declare a band the resolver already
+answered — the page was the narrower of the two, and it was the one being read.
 
 ## Surface-aware behaviour
 

package/docs/guidelines/agent-infra/rule-body-migration-inventory.md

@@ -57,7 +57,7 @@ always-loaded rules.
 | ask-when-uncertain.md | stay | 66 | Y | — | kernel Iron Law + ask-policy floor |
 | augment-edit-discipline.md | thin | 29 | | `guideline:augment-portability-patterns` + `skill:agent-docs-writing` (both existing) | two explicit "body migrated to" sentences |
 | autonomous-execution.md | thin | 81 | | `contexts/execution/autonomy-mechanics.md` + siblings (existing) | hybrid: several short Iron-Law-style blocks retained (Hard Floor pointer, N=3 budget headline), full mechanics already migrated |
-| brand-consistency.md | stay | 75 | | — | gate definition is the enforcement surface itself; already routes deeper mechanics to `brand-identity`/`brand-to-tokens`/`design-intelligence` |
+| brand-consistency.md | stay | 75 | | — | checklist definition is the rule itself; already routes deeper mechanics to `brand-identity`/`brand-to-tokens`/`design-intelligence` |
 | brand-source-of-truth.md | stay | 65 | | — | explicitly "light by design"; precedence order is the whole rule |
 | broken-access-control.md | thin | 68 | | `skill:authz-review` (existing) | hybrid: 2 short Iron-Law blocks (3 negative tests) retained, deep controls/matrix/backstop-grep content already migrated |
 | cli-output-handling.md | thin | 40 | | `skill:rtk-output-filtering` (existing) | pure P4 stub |

package/docs/guidelines/agent-infra/self-improvement-pipeline.md

@@ -2,10 +2,13 @@
 
 Five-stage flow that turns real project experience into reviewed
 rule / skill / command / guideline changes. Self-modification is a goal
-(ADR-281): for a proposal scoped to the package the approval is the AI
-council's ratification record, and the user is its last rung; a change a
-user asked for keeps that user's approval as now. A passing record makes a
-change ready, not landed — every upstream change still ships via a PR.
+(ADR-281, as amended 2026-10-07): for a proposal scoped to the package a
+digest-bound AI council record is **required and is a review, not the
+approval** — a council refusal fails closed, and a favourable verdict
+recommends passage and stays advisory until the owner's authenticated
+authorization is bound to the same digest. A change a user asked for keeps
+that user's approval as now. A reviewed record makes a change ready, not
+landed — every upstream change still ships via a PR.
 
 Referenced by `road-to-curated-self-improvement.md`. Consumed by the live
 artifacts — the `skill-improvement-trigger` rule and the existing skills
@@ -33,15 +36,19 @@ blocks — it does not hand a half-filled doc to the next stage.
   finding recurs, a successful pattern is worth codifying.
   The existing `skill-improvement-trigger` rule signals the event.
 - **Input:** raw observation (PR link, log line, review comment).
-- **Output:** learning note at `agents/learnings/<date>-<slug>.md`
-  with frontmatter `source`, `evidence[]` (≥1 link), `stage: captured`.
-- **Guardrails:** nothing is written into `dist/agent-src/` at this stage.
-  Learnings live in the consumer repo until promoted.
+- **Output:** a signal appended to the intake stream
+  `agents/memory/intake/signals-<YYYY-MM>.jsonl` by `memory_signal`, carrying
+  its source, its evidence reference and its polarity. `learning_sidecar`
+  verdicts that stream — decay, corroboration at two distinct origins, dead
+  ends — into a gitignored overlay.
+- **Guardrails:** nothing is written into `dist/agent-src/` at this stage, and
+  the overlay is never auto-promoted. A single session can never mint a lesson;
+  the stream lives in the consumer repo until a human curates it onward.
 
 ### Stage 2 — Classify
 
 - **Trigger:** explicit invocation or pipeline progression.
-- **Input:** learning note from Stage 1.
+- **Input:** the signal, and the sidecar's verdict over it, from Stage 1.
 - **Output:** same file, frontmatter extended with:
   - `scope: project | package`
   - `type: rule | skill | command | guideline`
@@ -66,14 +73,15 @@ blocks — it does not hand a half-filled doc to the next stage.
 ### Stage 4 — Gate
 
 - **Trigger:** proposal doc committed or staged.
-- **Executor:** `scripts/check_proposal.ts`.
+- **Executor:** `./agent-config proposal:check`.
 - **Input:** proposal doc from Stage 3.
 - **Output:** verdict recorded in the proposal doc section 9
   (`pass | request changes | block`). Frontmatter `stage: gated`
   only after a `pass`.
 - **Gate checks (all must pass):**
   1. At least **2 independent evidence** entries (distinct PRs,
-     issues, or incidents).
+     issues, or incidents) — the local row of the evidence threshold
+     in `docs/contracts/retro-v1.md` § Evidence threshold.
   2. `skill_linter` zero errors on the draft body.
   3. `check_portability` zero violations (no project identifiers
      on `package`-scoped proposals).
@@ -81,6 +89,8 @@ blocks — it does not hand a half-filled doc to the next stage.
   5. `size-enforcement` within the budget for the artefact type.
   6. `preservation-guard` justifies any replacement (section 6 of
      the proposal doc).
+  7. For `scope: package` at `stage: gated`: the review and the owner's
+     authorization are bound to the declared change (see Stage 5).
 - **Guardrails:** the gate is not a rubber stamp. A `block` verdict
   stays in the proposal as history; the pipeline restarts at
   Stage 3 if the author wants to revise.
@@ -88,19 +98,30 @@ blocks — it does not hand a half-filled doc to the next stage.
 ### Stage 5 — Upstream
 
 - **Trigger:** gate passed AND, for a proposal scoped to the package, a
-  council ratification record whose `subject` matches the proposal's change
-  passed it (ADR-281); where the council cannot conclude, the user decides by
-  the route ADR-281 § 5 names. A proposal scoped to a consumer's own project
-  needs that user's approval, as before.
-- **Executor:** `upstream-contribute` skill. Refuses invocation if
-  the proposal frontmatter is not `stage: gated`.
+  council ratification record reviewed it favourably AND the owner's
+  authorization is on record (ADR-281 as amended 2026-10-07 — the council
+  record is the review, the owner's authorization is the approval); where the
+  council cannot conclude, the user decides by the route ADR-281 § 5 names. A
+  proposal scoped to a consumer's own project needs that user's approval, as
+  before.
+  `proposal:check` performs the binding (gate check 7): a `scope: package`
+  proposal at `stage: gated` declares `changed_files:` and names a
+  `ratification_record:` that passes the reader against the committed provider
+  policy and an `owner_authorization:`, both bound to one digest over those
+  files read at one commit. It cannot prove the owner wrote the authorization;
+  it proves the review and the approval name the same content.
+- **Executor:** the `upstream-contribute` skill decides *whether*, and
+  `self-repair:release` — the one gated outward step — decides *what leaves*.
+  The skill refuses invocation if the proposal frontmatter is not
+  `stage: gated`.
 - **Input:** gated proposal doc.
-- **Output:** PR against `event4u/agent-config` carrying the
-  proposal doc as the PR body. Standard package CI runs.
+- **Output:** a pull request or an issue against `event4u-app/agent-config`
+  carrying the proposal doc as the body. Standard package CI runs.
   Frontmatter `stage: upstream` and `upstream_pr_url` set.
-- **Guardrails:** no `upstream-contribute` invocation ever edits
-  `.agent-src.uncondensed/` in the consumer repo. Writes happen
-  in the fork / PR branch of the package repo only.
+- **Guardrails:** the skill never pushes and never opens a pull request
+  itself, so there is one privacy floor and not two. No invocation edits any
+  installed tree in the consumer repo; writes happen in the package checkout's
+  branch only, and a consumer install reaches the issue step.
 
 ## Stage ownership
 
@@ -129,8 +150,10 @@ unreviewed upstream changes is not.
   need the evidence in one place.
 - **Do NOT** promote a learning with one piece of evidence. Two
   independent sources is the minimum; the gate enforces it.
-- **Do NOT** edit `.agent-src.uncondensed/` directly in a consumer
-  project "just to try it out". Drafts live in `agents/proposals/`.
+- **Do NOT** edit the installed tree directly in a consumer project
+  "just to try it out" — `.augment/` today, `.agent-src.uncondensed/`
+  in a legacy install. Both are managed; drafts live in
+  `agents/proposals/` and local changes in `agents/overrides/`.
 - **Do NOT** treat a `block` verdict as a personal rejection. The
   gate checks structural shape, not author intent.
 

package/docs/guidelines/design-antipatterns.md

@@ -114,7 +114,7 @@ Within-project invariants + repetition caps. Override = declare the value in
 | V2 | Glassmorphism as decoration (`backdrop-blur` + `bg-white/10`) with no functional depth hierarchy | Model defaults to it for "premium feel"; result looks like 2021 Material You clip-art | Element genuinely sits above a complex, blurred background layer; use sparingly and only for top-level floating surfaces | craft-presumption | delete → reduce | static |
 | V3 | Ghost card: `border: 1px solid` + box-shadow ≥ 16px spread together | The combination creates visual noise — the ghost card signals no confident decision about depth | Choose either border OR shadow to indicate depth; never both on the same surface | invariant | delete → reduce | static |
 | V4 | Over-rounded small cards or badges: `border-radius` > 16px on elements < 200px wide | Excessive rounding on small surfaces looks toy-ish; standard cap is 12–16px | Pill shape (`border-radius: 9999px`) is intentional on single-line tags/chips only | craft-presumption | retune | static |
-| V5 | Hand-drawn or illustrated SVG icons mixed with crisp icon-system icons | Visual register collision; instantly reads as "generated asset" | Intentional illustrative section (hero illustration, empty-state art); isolate from the icon system | invariant | replace | render |
+| V5 | Hand-drawn or illustrated SVG icons mixed with crisp icon-system icons | Visual register collision; instantly reads as "generated asset" | Intentional illustrative section (hero illustration, empty-state art); isolate from the icon system. A genuinely missing glyph is authored under [`svg-authoring`](../../src/skills/svg-authoring/SKILL.md) against the incumbent set's own grid | invariant | replace | render |
 | V6 | Repeating diagonal stripes as a background texture | A cliché background default; reads as generated CSS art | Brand explicitly uses pattern backgrounds (e.g., a textile brand); document the stripe definition | style-preference | delete | static |
 | V7 | Nested cards: a card inside a card inside a card | Depth hierarchy collapses; user cannot parse elevation intent | A truly three-level hierarchy (e.g., project → board → card); ensure each level has distinct visual weight | invariant | delete → reduce | render |
 | V9 | Noise or grain texture laid over a gradient as a "premium" surface default | The visual sibling of V6's diagonal stripes — a generated-CSS-art texture reached for to make a flat gradient look considered, applied because it is available rather than because the surface needed a texture | The texture is part of a documented brand surface treatment (a print-inspired or analog-photographic identity) with the grain opacity defined as a token, not chosen per surface | style-preference | delete | render |
@@ -135,6 +135,8 @@ Within-project invariants + repetition caps. Override = declare the value in
 | T8 | Single typeface for everything | Missed typographic contrast opportunity; in the **brand** register an unexamined single family reads as "I did not think about fonts" | **Register-scoped like T7.** Intentional mono-typeface aesthetic (e.g., terminal-inspired), stated in the brief — *or* the **product** register, where one reliable family is the sanctioned strategy ([`design-modes`](design-modes.md) § The two registers) and contrast is carried by weight and scale rather than by a second family. | reference-constraint | retune | judgment |
 | T9 | All-caps body paragraphs or field labels | Reduces legibility below WCAG AA for sustained reading; reads as flair over function | Short UI labels (e.g., button text in a brutalist layout); never for body paragraphs | floor | delete → retune | static |
 | T10 | Wide letter-spacing on body text (`letter-spacing` > 0.05em) | Reduces readability for sustained reading; reserved for display use | Display text (headlines, pull quotes) where intentional tracking is a brand element | craft-presumption | retune | static |
+| T11 | Faux bold or italic: a weight or style requested of a family that does not carry that face, so the renderer emboldens or slants the face it has | Synthesised strokes thicken unevenly and slant without the true italic's letterforms; reads as a missing font, not a style choice | Load the face that carries the weight or style, or set `font-synthesis: none` on purpose where the regular face is the intended look | floor | replace → retune | render |
+| T12 | Self-hosted webfont with `font-display: swap` and no metric-matched fallback `@font-face` (`size-adjust`, `ascent-override`, `descent-override`) | The fallback paints first at different metrics, so every line reflows when the webfont swaps in — measurable layout shift | `font-display: optional` or `block` on purpose, or a fallback face whose overrides are derived from the webfont's vertical metrics ([`design-asset-discipline`](design-asset-discipline.md)) | craft-presumption | retune | static |
 
 ---
 
@@ -241,6 +243,7 @@ are listed in § Quality floors.
 | `judgment-only` | needs structural or aesthetic judgment a text pass cannot make; `design-review` decides it |
 | `deferred` | pattern-detectable but a design-system opinion rather than a floor; deliberately not shipped |
 | `candidate` | a numeric threshold stated in the entry, not yet detected — a status that must resolve to `backed` or `judgment-only`, never persist |
+| `witness` | read from the rendered asset by `ui:render --profile asset`, not from text; the note names the witness rule, which must exist in the witness source |
 
 | Entry | Status | Note |
 |---|---|---|
@@ -270,6 +273,8 @@ are listed in § Quality floors.
 | T8 | deferred | typeface count is a design-system opinion, not a floor |
 | T9 | backed | |
 | T10 | backed | |
+| T11 | witness | `ui:render --profile asset` reports `geometry/font-synthesised`; fixture `missing-weight-reads-synthesised` |
+| T12 | backed | |
 | L1 | judgment-only | composite structural template |
 | L2 | judgment-only | three-identical-card grid; DOM-structure analysis |
 | L3 | deferred | spacing-multiple uniformity is a design-system opinion |

package/docs/guidelines/design-asset-discipline.md

@@ -25,6 +25,23 @@ brand evidence**. The design-surface instance of the no-invented-facts floor.
   emitters (`typography-system`, UI-apply directives, brand-asset paths) are
   consumers and point here rather than restating it. (fixture:
   `daf-webfont-delivery`.)
+- **Self-hosted font files are subset and the one above-the-fold face is
+  preloaded.** Split a self-hosted family into files by script and declare each
+  with `unicode-range` on its `@font-face`, so a page downloads only the ranges
+  its text uses. Add `<link rel="preload" as="font" type="font/woff2"
+  crossorigin>` for the single face that paints above the fold, and for no
+  other: every preload competes with the first render for bandwidth. These are
+  mechanics, not tells — nothing here is detected.
+- **A swapped face gets a metric-matched fallback, derived from the font.**
+  With `font-display: swap`, declare a second `@font-face` over a `local()`
+  system face and set its overrides from the webfont's own tables (own analysis
+  of the CSS Fonts 5 descriptors): `size-adjust` = the webfont's average advance
+  over the fallback's for the same sample text; `ascent-override` =
+  ascender ÷ (unitsPerEm × size-adjust), `descent-override` =
+  |descender| ÷ (unitsPerEm × size-adjust), `line-gap-override` = lineGap ÷
+  (unitsPerEm × size-adjust). Read the `OS/2` typo values when the font sets
+  `USE_TYPO_METRICS`, the `hhea` values otherwise. The missing fallback is
+  catalogue tell T12 in [`design-antipatterns`](design-antipatterns.md).
 - **Real imagery where inspection matters.** On visual pages/decks, use actual
   product / place / object / state imagery where the image IS the proof (a
   product screenshot, a real dashboard state). Decorative atmosphere is not proof

package/docs/guidelines/design-fidelity-routing.md

@@ -77,6 +77,7 @@ contract rather than a courtesy:
 | `phrase: claude.site/artifacts` | `near-claude-ai-chat-link` | a bare `claude.ai` chat link is a conversation reference, not a spec |
 | `path_prefix: .claude/design-system/` | `near-generic-design-system-dir` | a bare `design-system/` is a normal source folder in a large fraction of frontend repos |
 | `file_pattern: *.dc.html` | `near-plain-html-open-file`, `near-dc-in-a-filename` | an ordinary `.html` file in the tree; a filename that merely contains the letters |
+| `path_prefix: .design-sync/` | `near-plain-sync-dir` | a bare `sync/` or `design-sync/` folder is ordinary source, only the host's dot-folder is a handover |
 | the withdrawn builder URL | `near-bare-host-mention` | left behind on purpose, so the broad form stays pinned silent |
 
 ### Write the near-miss row first — and test the right direction

package/docs/guidelines/php/api-design.md

@@ -81,7 +81,16 @@ RateLimiter::for('api', function (Request $request) {
 });
 
 RateLimiter::for('auth', function (Request $request) {
-    return Limit::perMinute(5)->by($request->ip());
+    // Two limits, not one: the account and the source. An IP-only key fails
+    // in BOTH directions — one attacker rotating addresses gets five attempts
+    // per address against the same account, and one office NAT locks every
+    // colleague out after five attempts between them.
+    $account = Str::lower(trim((string) $request->input('email')));
+
+    return [
+        Limit::perMinute(5)->by('auth:acct:' . sha1($account)),
+        Limit::perMinute(5)->by('auth:ip:' . $request->ip()),
+    ];
 });
 ```