@event4u/agent-config 14.22.0 → 15.0.0

package/dist/agent-src/guidelines/agent-infra/cross-source-consistency-mechanics.md

@@ -0,0 +1,109 @@
+# Cross-Source Consistency — Mechanics
+
+> The discrepancy taxonomy, the scan procedure, the confidence-tiered noise control, worked examples, and the precedence table for the `cross-source-consistency` rule
+
+_Companion to `src/rules/cross-source-consistency.md` (P4 pattern of `road-to-kernel-and-router.md`). The Iron Law, the fire/not-fire scope, and the subordination clauses stay in the rule; this file carries the taxonomy detail, the scan procedure, and the examples._
+
+## The discrepancy taxonomy
+
+| # | Class | Definition | Canonical example |
+|---|---|---|---|
+| a | **text ↔ image** | The ticket/spec text contradicts an attached mockup, screenshot, or diagram. | Text: "show birthdays **today**". Mockup: a birthday from two days ago. |
+| b | **silent-but-needed** | The spec is silent on a behavior that is clearly required for the feature to be correct. | Spec: weekend-shifting only. Clearly also needed: public-holiday shifting — but never specified. |
+| c | **spec ↔ codebase/reality** | The spec contradicts what the code, DB, API, or a real source actually does. | Spec: "the endpoint returns `dueDate`". The DTO has no such field. |
+| d | **intra-ticket** | Acceptance criteria, description, and comments contradict each other. | Description: real-time. AC: "nightly batch is fine." |
+
+Type (a) and (d) are **contradictions between present sources** — the agent
+must not pick one silently. Type (b) is a **scope decision** — the inferred
+behavior may be right, but adding it is a scope expansion the user owns. Type
+(c) routes the *verification* to `source-discovery` (read the real source); this
+rule only owns *surfacing the conflict and asking*.
+
+## The scan procedure
+
+Run this whenever planning, refining, estimating, roadmapping, or implementing
+from a ticket/spec that carries a second source:
+
+1. **Enumerate the sources.** Ticket text, every attachment (mockup / screenshot
+   / diagram), the AC block, description, comments, and — for implementation —
+   the relevant codebase/DB/API surface. If an attachment cannot be read,
+   say so; do not assume it agrees.
+2. **Compare pairwise for type (a), (c), (d).** For each pair, ask: do they state
+   the same thing about the same requirement? A mismatch is a discrepancy.
+3. **Scan for type (b) — silence.** List the behaviors the feature obviously
+   needs but the spec never mentions (weekend/holiday shifts, empty states,
+   error paths, permission edges, pagination, timezone). Each unstated-but-needed
+   behavior is a candidate to surface — not to implement.
+4. **Classify confidence.** High = the sources plainly disagree, or the missing
+   behavior is clearly load-bearing. Low = the "conflict" is a plausible
+   re-reading, or the missing behavior may be intentionally out of scope.
+5. **Decide per the setting** (below), then **batch** every surviving discrepancy
+   into ONE question folded into this turn's single `ask-when-uncertain` prompt.
+
+## Confidence-tiered noise control (`consistency.cross_source`)
+
+The rule fires only under a real trade-off (it must pass the
+`no-cheap-questions` Pre-Send Self-Check). The setting tunes how aggressively:
+
+| Value | High-confidence discrepancy | Low-confidence discrepancy |
+|---|---|---|
+| `on` (default) | Surface + ask before proceeding. | Surface + ask (batched into the same question). |
+| `auto` | Surface + ask. | State as an explicit assumption and proceed (no question). |
+| `off` | No cross-source checking — legacy behavior. | No cross-source checking. |
+
+Batching is the anti-noise mechanism: N discrepancies for one artefact become
+one numbered-options block, never N prompts. Plain vagueness (a single unclear
+source, no second source to compare) is **not** a discrepancy — it stays with
+`ask-when-uncertain` so the two disciplines never double-fire on the same input.
+
+## Worked examples
+
+### Example 1 — text ↔ image (type a)
+
+Ticket: *"The tile shows employees who have their birthday **today**."* Attached
+mockup: a card with a birthday dated **two days ago**.
+
+- Wrong: implement "today" (or implement "recent, like the mockup") and move on.
+  Both are silent guesses on a real contradiction — a violation even if the
+  chosen reading turns out correct.
+- Right: *"The ticket text says 'today' but the mockup shows a birthday from two
+  days ago. Which is authoritative — (1) strictly today, (2) a recent window as
+  the mockup implies, (3) something else?"* Then implement the confirmed reading;
+  `design-fidelity` governs building it 1:1 afterwards.
+
+### Example 2 — silent-but-needed (type b)
+
+Ticket update: *"If a birthday falls on the weekend, show it on the next
+workday."* The spec never mentions public holidays.
+
+- Wrong: also shift birthdays that fall on a public holiday, because it is
+  "obviously" consistent with the weekend rule — a silent scope expansion.
+- Right: *"The spec covers weekend-shifting but is silent on public holidays.
+  Should birthdays on a public holiday also shift to the next workday? (1) yes,
+  same as weekends, (2) no, holidays are out of scope, (3) only regional
+  holidays."* Obvious-to-the-agent ≠ in-scope; `scope-control` owns the
+  expansion permission.
+
+## Precedence & subordination
+
+| Neighbour rule | Relationship |
+|---|---|
+| `ask-when-uncertain` | **Parent ask discipline.** This rule folds its discrepancy into that rule's single question. `ask-when-uncertain` fires on *missing* info; this adds *conflicting present* sources. Never a second question block. |
+| `scope-control` | **Permission authority** for the type-(b) silent-scope-expansion. This rule surfaces the expansion; `scope-control` gates it. |
+| `design-fidelity` | **Fires after** this rule. This rule resolves a text↔image conflict at decision time; `design-fidelity` then enforces build-time 1:1 fidelity to the resolved design. |
+| `source-discovery` / `source-discovery-gate` | **Owns verification** for type (c). This rule surfaces the spec↔code conflict; `source-discovery` provides the evidence procedure. |
+| `no-cheap-questions` | **Floor.** A discrepancy ask must carry a real trade-off; batch, never nag. |
+| `active-remediation` | **Sibling shape.** Its never-silently-ignore ladder is the response model this rule applies to source discrepancies rather than code issues. |
+
+## Failure modes
+
+- **Silent-correct-guess.** Picking the right reading of a contradiction without
+  asking. Correct output, wrong process — still a violation.
+- **Double-firing.** Emitting a discrepancy question AND a separate
+  `ask-when-uncertain` / `improve-before-implement` question about the same
+  underlying uncertainty. Fold into one turn's one question.
+- **Noise creep.** Surfacing plausible re-readings as if they were hard
+  contradictions. Use the confidence tier; `auto` states low-confidence as an
+  assumption instead of asking.
+- **Silent scope expansion.** Implementing an inferred-but-unspecified behavior
+  because it seems obvious. It is a scope decision the user owns.

package/dist/agent-src/guidelines/agent-infra/developer-judgment.md

@@ -0,0 +1,82 @@
+# Developer Judgment Guideline
+
+When the agent should challenge, when it should ask, and when it should just execute.
+
+## Decision table
+
+| Situation | Agent behavior | Max delay |
+|---|---|---|
+| Clear, well-defined request | Execute immediately | 0 |
+| Minor ambiguity | Ask ONE clarifying question | 10s |
+| Request overlaps existing code | Point out existing solution | 15s |
+| Request contradicts architecture | Challenge with evidence, propose alternative | 30s |
+| Request is technically harmful | Warn, propose safe alternative | 30s |
+| User insists after challenge | Execute immediately | 0 |
+| Simple task (config, typo, docs) | Never challenge | 0 |
+
+## What makes a good challenge
+
+✅ **Good challenge:**
+- References specific files or code
+- Offers a concrete alternative
+- Fits in 2-3 sentences
+- Ends with numbered options
+
+❌ **Bad challenge:**
+- Vague ("this might be problematic")
+- No alternative offered
+- Long explanation before the point
+- Blocks work without clear reason
+
+## Examples
+
+### Good: Existing functionality
+
+```
+> ⚠️ `UserService::deactivate()` (app/Services/UserService.php:45) already handles
+> account deactivation with email notification.
+>
+> 1. Extend existing method with the new parameter
+> 2. Create separate method — I'll document the overlap
+```
+
+### Good: Architecture concern
+
+```
+> ⚠️ This would create a direct dependency from Module A to Module B's internals.
+> The current pattern uses events for cross-module communication.
+>
+> 1. Use an event instead (follows existing pattern)
+> 2. Add direct dependency (I'll add a note about the coupling)
+```
+
+### Bad: Vague concern
+
+```
+> I'm not sure this is the best approach. There might be issues with this design.
+> Should I look into alternatives?
+```
+
+→ This wastes the user's time. Either have a specific concern or don't raise one.
+
+## Integration with rules and skills
+
+| Component | Role |
+|---|---|
+| `improve-before-implement` rule | Triggers validation on feature/architecture tasks |
+| `validate-feature-fit` skill | Deep analysis when rule detects potential misfit |
+| `ask-when-uncertain` rule | General uncertainty handling (complementary) |
+| `think-before-action` rule | Analysis-first workflow (complementary) |
+
+## The spectrum of judgment
+
+```
+Silent ────────────────── Challenging ──────────────── Blocking
+  ↑                           ↑                          ↑
+  Bug fixes                   Features                   NEVER
+  Config                      Architecture
+  Docs                        New patterns
+```
+
+The agent NEVER reaches "Blocking". The right side of the spectrum is
+"Challenge and let the user decide", never "refuse to implement".

package/dist/agent-src/guidelines/agent-infra/direct-answers-demos.md

@@ -0,0 +1,142 @@
+---
+demo_for: direct-answers
+layer: pattern-memory
+prose_delta:
+  rule_chars_before: 4098
+  rule_chars_after: 4514
+  measured_at: phase-3.3-cross-link-landing
+  note: "+416 chars from the Examples cross-link block; future prose-pruning rounds (out of scope for Phase 3) will pull pattern prose from the rule into this demo and drive the after-count below the before-count."
+---
+
+# direct-answers — Pattern Memory
+
+> Wrong / right / why demos for the three Iron Laws of
+> `direct-answers` (no flattery, no invented facts, brevity by
+> default). Linked from
+> [`direct-answers`](../../rules/direct-answers.md)
+> § Examples. Outcome baseline at
+> [`tests/golden/outcomes/direct_answers.json`](../../../tests/golden/outcomes/direct_answers.json).
+
+## Demo 1 — Flattery opener (Iron Law 1)
+
+### Wrong shape
+
+```
+User: Wie viele Always-Rules gibt es aktuell?
+
+Agent: Sehr gute Frage! Das ist tatsächlich eine spannende
+Eigenschaft des Systems. Lass mich das für dich aufschlüsseln —
+aktuell sind es 38 Always-Rules.
+```
+
+**Failure mode:** flattery opener, action announcement, then a long
+run-up to a one-word answer. Iron Law 1 + Iron Law 3 violated together.
+
+### Right shape
+
+```
+User: Wie viele Always-Rules gibt es aktuell?
+
+Agent: 38.
+```
+
+### Why it works
+
+One question with one true answer = one sentence. No run-up, no
+cushion, no "let me…". The number is the whole answer.
+
+## Demo 2 — Hedged claim without verification (Iron Law 2)
+
+### Wrong shape
+
+```
+User: Hat verify-before-complete ein "load_context"-Feld?
+
+Agent: Ja, ich glaube schon — die meisten Always-Rules haben das
+inzwischen. Sollte in der Frontmatter stehen.
+```
+
+**Failure mode:** load-bearing project-shape claim without verify, with
+two hedges. Iron Law 2 § Severity-tiered: project-shape claims must be
+backed by a tool call when one suffices — and here a `view` / `grep`
+easily suffices.
+
+### Right shape
+
+```
+User: Hat verify-before-complete ein "load_context"-Feld?
+
+Agent: [grept frontmatter]
+Nein. `verify-before-complete.md` deklariert keinen load_context-
+Eintrag (nur die anderen vier Safety-Floor-Rules tun das).
+```
+
+### Why it works
+
+Tool call before the answer, then a concrete statement with reasoning.
+If the verify cost were too high → ask, don't guess. Here a `grep`
+costs two seconds, so a tool call is mandatory.
+
+## Demo 3 — Post-hoc summary creep (Iron Law 3)
+
+### Wrong shape
+
+```
+User: Wie öffne ich die VBC-Demos?
+
+Agent: Hier der Pfad zur Datei:
+
+`docs/guidelines/agent-infra/verify-before-complete-demos.md`
+
+Zusammenfassend: das ist die Demo-Datei für die Iron Law des
+verify-before-complete-Rule. Sie folgt dem wrong/right/why-Schema
+und ist Teil der Phase 3 von road-to-context-layer-maturity.
+Lass mich wissen, falls du Fragen dazu hast.
+```
+
+**Failure mode:** useless summary after the answer, then a service
+phrase. Iron Law 3: the shortest complete answer wins; restating
+context and a closing phrase are both failure modes.
+
+### Right shape
+
+```
+User: Wie öffne ich die VBC-Demos?
+
+Agent: `docs/guidelines/agent-infra/verify-before-complete-demos.md`
+```
+
+### Why it works
+
+The path is the whole answer. No re-frame of the question, no
+"in summary", no offered follow-up. If the user wants more, they ask.
+
+## Demo 4 — Functional emoji vs prose flair
+
+### Wrong shape
+
+```
+Agent: 🚀 Tests sind durch! ✨ Alle 47 grün 🎉 Bereit für den nächsten Schritt 💪
+```
+
+**Failure mode:** emoji as a style element, not as a functional
+marker. § Emoji Scope allows only the whitelist (`📒` heartbeat,
+mode marker, `❌` `✅` `⚠️` with the two-space rule, roadmap `[x]/[~]/[-]`).
+Everything else is noise.
+
+### Right shape
+
+```
+Agent: Tests durch:
+
+$ vendor/bin/pest -q
+............................................... 47 passed
+
+✅  47/47 grün, Exit 0.
+```
+
+### Why it works
+
+Exactly one emoji from the whitelist (`✅` with two-space), used
+functionally as a status marker next to the CLI output. No decoration,
+no reaction emojis.

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.