@event4u/agent-config 14.23.0 → 16.0.0

package/dist/agent-src/guidelines/agent-infra/domain-adoption-gates.md

@@ -0,0 +1,112 @@
+# Domain Adoption — Gates
+
+> The three-gate evidence contract, sunset policy, and failure-mode catalog for the `domain-adoption-policy` rule
+
+_Origin: migrated from `src/rules/domain-adoption-policy.md` per the P4 pattern of `road-to-kernel-and-router.md`. The Iron Law and the three gate names stay in the rule; this file carries the per-gate evidence bars and procedures._
+
+## Gate 1 — Demand signal
+
+At least one of the following must be **true and citeable** in the roadmap:
+
+- **≥ 2 consumer projects** in the domain. Cite repository names or
+  `agents/settings/contexts/` notes — not "I think there might be".
+- **Named user direction with target.** A specific user ask plus a target
+  project / use case — e.g. "harvest the mobile skills for project X, due
+  next quarter". Vague *"this might be useful"* does not count.
+- **Public-incident pull.** A reproducible incident on a consumer project
+  the domain would have prevented, captured in `agents/settings/contexts/` with
+  the missing surface area named.
+
+If none of the three is citeable, **defer**. Open a watch-only context note
+under `agents/settings/contexts/domain-watch/<domain>.md` listing the missing signal
+so the next harvest can re-evaluate without re-relitigating the case.
+
+## Gate 2 — Named maintenance owner
+
+Domain plates rot. Pick the owner before the import, not after.
+
+- The roadmap names a **single maintainer** (not "the team", not "TBD")
+  responsible for the domain quarterly review.
+- The owner commits to the **refresh cadence** — quarterly review at
+  minimum, faster if the domain is volatile (mobile RN/Expo SDK,
+  ML model APIs).
+- Each adopted artefact carries an **inline upstream-source line** with
+  SHA + last-checked timestamp so refresh is mechanical, not archaeological.
+
+If no owner is named or no cadence is set, **defer**. An unowned domain
+plate becomes broken authoritative-links and stale skills inside two cycles.
+
+## Gate 3 — CI-tooling decision
+
+Either the domain's verification tooling is validated in CI, or the suite
+explicitly accepts platform-bound reference-only status.
+
+- **Validated.** The CI pipeline runs the relevant linters/tests/integration
+  checks for the domain (e.g. `mobile-e2e` runners, ML model validation,
+  contract conformance) on every PR. Cost noted in the roadmap risk
+  register.
+- **Out-of-scope (reference-only).** The domain is a platform fact the
+  suite cannot validate (iOS Simulator on non-macOS runners, GPU-bound
+  ML, hardware-bound IoT). The roadmap states this explicitly; affected
+  artefacts carry a "reference-only on \<unsupported platforms\>" header
+  so consumers do not file false-positive bugs.
+
+If neither line is drawn, **defer**. Half-validated CI silently rots the
+domain — green builds while the underlying tooling drifts.
+
+## Sunset Policy stacks on top
+
+Every domain track inherits the authoritative-link Sunset path documented
+in any plate that imports volatile upstream content:
+
+- Volatile content (SDK-pinned, API-pinned, tool-version-pinned) lives as
+  guideline body + SHA-pinned upstream link, not as forked scripts.
+- Refresh trigger: quarterly cadence or earlier if a SHA-pinned link
+  404s in CI.
+- The `check-refs` and `check-portability` linters apply unchanged.
+
+Adopting a domain does not exempt it from any other suite-wide rule —
+`augment-edit-discipline`, `skill-quality`, `size-enforcement`,
+`rule-type-governance`. Every domain artefact passes the same gates as a
+core artefact.
+
+## Failure modes
+
+- *"It's just one skill, not a domain."* — Audit the skill's prerequisites.
+  If it pulls in a new toolchain, simulator, language runtime, or
+  platform-specific build system, it **is** a domain entry. Run the gates.
+- *"The upstream is well-maintained, we can just track it."* — Tracking
+  upstream means owning the diff, the breaking changes, and the migrations.
+  Tracking is maintenance work; budget for it under Gate 2 or skip the
+  adoption.
+- *"We'll add CI later."* — Later does not arrive. Either CI is wired in
+  the same plate, or the artefacts ship with explicit reference-only
+  headers so users do not assume validated coverage.
+- *"Council convergence is enough."* — Council informs the gates; it does
+  not replace them. A council session may surface that all three gates
+  pass; the roadmap still cites the evidence.
+- *"Demand-signal is the user asking once."* — Single-shot interest is a
+  watch trigger, not an open trigger. Either name the target use case
+  with project + timeline, or open a watch note and wait.
+
+## What to do when the gates fail
+
+1. Mark the domain plate `[-] gated — <gate name> not met` in the relevant
+   roadmap. Do **not** silently shrink scope to dodge the gate.
+2. Open a watch-only context note under `agents/settings/contexts/domain-watch/`
+   capturing what's missing — citations, owner candidates, CI feasibility.
+3. Re-evaluate at the next harvest cycle. The note is the evidence trail
+   so the same questions are not relitigated.
+
+## Allowed without gates
+
+- Adding **a single skill** to an **already-opened** domain follows the
+  regular harvest plate; the gates do not re-fire per skill.
+- Authoring a **guideline** that documents a domain the suite already
+  ships in — the domain is open, the guideline is a within-domain artefact.
+- A **rule** that constrains an already-opened domain — within-domain.
+
+## See also
+
+- `domain-adoption-policy` (rule) — the Iron Law + gate names.
+- `size-enforcement` · `rule-type-governance` · `skill-quality` — the suite-wide floors every domain artefact still passes.

package/dist/agent-src/guidelines/agent-infra/domain-eval-anti-pattern.md

@@ -0,0 +1,53 @@
+# Domain-eval anti-pattern — manufactured false objectivity at N=1
+
+> A retrospective from the legal pack (council round 3). It exists so the next
+> domain does not repeat the mistake. The short version: **do not call a
+> self-labeled regression harness an "objective" correctness gate.**
+
+## The anti-pattern
+
+Gating skill ship on *"≥X% match to expert ground-truth"* and calling it "the
+objective replacement for reviewer sign-off" — when:
+
+1. **The ground-truth is unsourced or self-generated.** If the maintainer guesses
+   what an expert would flag, the eval measures "does the skill match the
+   maintainer's guess," i.e. reviewer subjectivity wearing a quantitative costume.
+2. **Expert agreement is not truth.** Even an attorney-validated gold set at
+   inter-annotator agreement ≥0.7 is *inter-subjective expert consensus*, not
+   ground truth — `0.7 ≠ 1.0` admits the domain is contested ~30% of the time.
+   The honest goal is **measurement objectivity** (reliably detect change), not
+   **ground-truth objectivity** (the labels are correct).
+3. **Model capability caps below the threshold.** Clause-extraction caps at
+   ~F1 0.62; any passable threshold therefore measures "not worse than a mediocre
+   baseline," i.e. regression detection — never correctness.
+4. **The statistical language is borrowed from infra that does not exist.**
+   Calibrating a threshold "from cross-model distributions" requires a built
+   cross-model-parity layer. Borrowing the vocabulary before the layer exists is
+   false precision.
+
+## The honest alternative
+
+- **Ship a regression / consistency harness.** Self-labeled fixtures, explicitly
+  marked "regression-only, not correctness, not objective." It catches "did a
+  change make a skill worse than its own baseline."
+- **Keep correctness with the human.** Licensed-expert review on material use,
+  baked into the skill's output, not a footnote.
+- **Make the objective eval a separate, gated track.** Attorney/expert-validated
+  gold set + inter-annotator ≥0.7 is real but expensive; gate it on **validated
+  demand + funding**, not on a phase timeline — and note it is classification, so
+  it does **not** depend on a cross-model-parity keystone.
+
+## The false-blocker corollary
+
+When you scope an eval, check what it *actually* depends on. The legal eval was
+briefly gated on the cross-model-parity keystone; the full critique round showed
+that was wrong — legal fixture matching is **classification** (clause
+present/absent/ambiguous), not the finding-count distributions that keystone
+calibrates. The real dependency was labeled-gold-set tooling, buildable in-pack.
+A false structural blocker is as much an error as false objectivity.
+
+## See also
+
+- [ADR-107 — Legal domain-pack adoption](../../decisions/ADR-107-legal-domain-pack-adoption.md)
+- `domain-pack-architecture.md` — the retrospective sequence this is part of.
+- `src/domains/legal-review-prep/evals/README.md` — the regression harness in practice.

package/dist/agent-src/guidelines/agent-infra/domain-pack-architecture.md

@@ -0,0 +1,56 @@
+# Domain-pack architecture — a retrospective observation (NOT a design driver)
+
+> **Status: retrospective hypothesis, N=1.** This documents the sequence the
+> **legal** pack happened to follow. It is **not** a rule and **not** a template
+> that future packs must fit. Validate it against a *second* domain before
+> promoting any of it to a rule or building scaffolding tooling — per
+> `domain-adoption-policy` and the `domain-pack-extraction-when-triggered` (N=2)
+> roadmap. Designing a new pack to fit this speculative pattern would invert the
+> lever: build the domain correctly on its own legs, then observe whether the
+> pattern recurred.
+
+## The sequence legal followed
+
+1. **Safety floor first** — a domain `*-safety-floor` rule (Iron-Law-shaped,
+   ~100 lines) before any drafting skill. A drafting skill shipped before its
+   floor is the exact liability the floor prevents.
+2. **Enforcement teeth** — the floor's machine-checkable elements become a
+   deterministic linter (`lint_legal_pack`) wired into CI. Prompt rules are not
+   governance; lint rules are. This is the differentiator vs prompt-only suites.
+3. **Eval = regression harness, not a correctness oracle** — self-labeled
+   fixtures in the maintainer's genuine-competence sub-domain; the *objective*
+   eval (attorney-validated gold set, inter-annotator ≥0.7) is a separate,
+   demand-and-funding-gated track. See `domain-eval-anti-pattern.md`.
+4. **Skills = procedure + output template only** — no default domain positions;
+   positions live in a practice profile, so one skill set behaves
+   team-specifically and the pack stays portable.
+5. **Practice profile (the keystone)** — a cold-start interview writing a
+   plain-prose profile into `.agent-settings.yml` / the setup wizard; skills read
+   it and halt on unresolved placeholders.
+6. **Deferred by default** — personas, scheduled watchers, installer hubs, and
+   broader scope are recorded as rejected/gated, not built, until evidence pulls
+   them in.
+
+## Why it is NOT yet a rule
+
+- **N=1.** Finance might need real-time-data evals; security might need red-team
+  evals; neither looks like "clause extraction + self-labeled fixtures." The
+  shape that fit legal may not fit them.
+- **Premature tooling is the maintainer's enemy.** No `domain-pack:new`
+  scaffolding ships from this observation. Extraction waits for N=2, where a
+  second domain either confirms the sequence (promote to a rule) or diverges
+  (document the delta, keep both bespoke).
+
+## What to do at N=2
+
+Build the second domain on its own merits. *Then* compare: which steps generalised,
+which broke. If the sequence held twice, promote it to a rule and consider
+scaffolding. If it diverged, this note records why a one-size pattern was wrong —
+itself a useful result.
+
+## See also
+
+- [Capability Boundary Matrix](../../contracts/capability-boundary.md) — per-pack safety posture (default-install / consent / council / disclaimer / eval / risk_class).
+- [ADR-107 — Legal domain-pack adoption](../../decisions/ADR-107-legal-domain-pack-adoption.md)
+- `domain-adoption-policy` (rule) — the three gates before opening any domain.
+- `domain-eval-anti-pattern.md` — why the legal eval is a regression harness, not an objective gate.

package/dist/agent-src/guidelines/agent-infra/downstream-changes-mechanics.md

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

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

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

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

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

package/dist/agent-src/guidelines/agent-infra/evaluator-independence-mechanics.md

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