@event4u/agent-config 1.14.0 → 1.16.0

package/docs/contracts/linear-ai-rules-inclusion.md

@@ -0,0 +1,143 @@
+---
+stability: beta
+---
+
+# Linear AI — rules inclusion list
+
+> Phase 3 Step 1 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
+> Per-rule decision for the Linear AI rules digest. The digest is a
+> Markdown blob the user pastes into Linear's `Settings → Agents →
+> Additional guidance` (workspace / team / personal). The third-party
+> agent (Codegen, Charlie, Cursor's Linear app, …) reads it verbatim —
+> no skill triggering, no script execution, no `.augment/` access.
+>
+> Source of tier data: `python3 scripts/audit_cloud_compatibility.py
+> --details` (47 rules: T1=20, T2=19, T3-S=8).
+>
+> Last refreshed: 2026-04-29.
+
+## Inclusion criteria
+
+- **Workspace** — universal coding posture and interaction discipline.
+  Survives without filesystem, scripts, or this package's tooling.
+- **Team** — framework-specific (Laravel, PHP, E2E with Playwright).
+  Only applied where the team uses that stack.
+- **Personal** — empty by default; reserved for individual preferences
+  the user may add manually.
+- **Excluded** — meta-rules about authoring this package, Augment Code
+  specifics, or rules already declared `cloud_safe: noop`.
+
+Two transformations the digest builder (Phase 3 Step 2) must apply
+to *included-degraded* rules:
+
+1. Strip references to scripts, `.agent-settings.yml`, `.agent-src/`,
+   `.augment/`, `agents/`, and `task <foo>` invocations.
+2. Replace `[link](path)` to other rules/skills/files with a footnote
+   or inline summary, since the path won't resolve outside this repo.
+
+## Workspace digest (18 rules)
+
+Universal coding posture — applies to every team regardless of stack.
+
+| Rule | Tier | Mode | Notes |
+|---|---|---|---|
+| `ask-when-uncertain` | T1 | as-is | One-question-per-turn iron law; strip cross-refs to `user-interaction` / `artifact-drafting-protocol` |
+| `commit-conventions` | T1 | as-is | Generic Conventional Commits |
+| `context-hygiene` | T1 | as-is | Conversation freshness, 3-Failure Rule, tool-loop detection; strip Augment-specific `.augmentignore` section |
+| `direct-answers` | T1 | as-is | Iron Laws (no flattery, no invented facts, brevity); strip emoji whitelist refs to other rules |
+| `markdown-safe-codeblocks` | T1 | as-is | Generic markdown safety |
+| `minimal-safe-diff` | T1 | as-is | Universal coding discipline |
+| `reviewer-awareness` | T1 | as-is | Anchor reviewer choice in paths and risk |
+| `scope-control` | T1 | as-is | Universal scope discipline + git-ops permission gating |
+| `security-sensitive-stop` | T1 | as-is | Stop-and-threat-model on security-sensitive paths |
+| `think-before-action` | T1 | degraded | Strip `memory-access` guideline ref (no shared memory on Linear) |
+| `verify-before-complete` | T1 | as-is | Evidence gate; the tool list (PHPStan etc.) is illustrative, harmless |
+| `cli-output-handling` | T2 | degraded | Keep "use targeted output, not full dumps"; strip `rtk` Iron Law (rtk is a local tool) |
+| `downstream-changes` | T2 | as-is | Universal post-edit propagation |
+| `improve-before-implement` | T2 | as-is | Challenge weak requirements before implementing |
+| `language-and-tone` | T2 | degraded | Keep mirroring + tone; strip "all `.md` docs must be English" clause (no `.md` files on Linear) |
+| `missing-tool-handling` | T2 | as-is | Don't install silently |
+| `token-efficiency` | T2 | degraded | Strip `.agent-settings.yml` references (`personal.minimal_output`, `personal.play_by_play`) |
+| `user-interaction` | T3-S | degraded | Numbered-options Iron Law, single-source recommendation; strip `scripts/check_reply_consistency.py` reference |
+
+## Team digest (4 rules)
+
+Framework-specific. Only paste into the Team layer of teams that use
+the stack. Each rule already names the stack in its own trigger line,
+so nothing to strip.
+
+| Rule | Tier | Stack | Notes |
+|---|---|---|---|
+| `docker-commands` | T1 | Docker / Laravel | Container-prefixed CLI for artisan/composer/phpunit |
+| `laravel-translations` | T1 | Laravel | `__()` helper, `lang/de`, `lang/en` |
+| `e2e-testing` | T2 | Playwright | Locators, Page Objects, fixtures, flake prevention |
+| `php-coding` | T2 | PHP | Strict types, naming, comparisons, Eloquent conventions |
+
+## Personal digest (0 rules)
+
+Empty by default. The user may paste individual preferences (preferred
+naming, IDE-specific shortcuts, response language overrides) into this
+layer manually. The digest builder emits an empty stub with a comment.
+
+## Excluded (25 rules) — categorised
+
+### Meta — about authoring this package (20)
+
+These rules govern how skills/rules/commands are created, kept in sync,
+and shipped from this repository. They have no meaning for a third-party
+agent that does not maintain `event4u/agent-config`.
+
+`agent-docs`, `architecture`, `artifact-drafting-protocol`,
+`augment-portability`, `augment-source-of-truth`, `capture-learnings`,
+`docs-sync`, `guidelines`, `package-ci-checks`, `preservation-guard`,
+`review-routing-awareness`, `roadmap-progress-sync`,
+`role-mode-adherence`, `rule-type-governance`, `runtime-safety`,
+`size-enforcement`, `skill-improvement-trigger`, `skill-quality`,
+`tool-safety`, `upstream-proposal`.
+
+### Augment Code specifics (3)
+
+These reference Augment-only mechanics — model identity in Augment's
+system prompt, Augment's `/slash` command surface, and the Augment
+onboarding flow gated by `.agent-settings.yml`.
+
+`model-recommendation`, `onboarding-gate`, `slash-command-routing-policy`.
+
+### Skill-routing only (1)
+
+`analysis-skill-routing` — routes to one of our `analysis-*` skills.
+Skills do not exist on Linear AI; the third-party agent has its own
+capability surface.
+
+### Already declared inert on cloud (1)
+
+`chat-history` — carries `<!-- cloud_safe: noop -->` by design. No
+persistence on cloud platforms; the rule is a no-op.
+
+## Open follow-ups
+
+- **Phase 3 Step 2** (`scripts/build_linear_digest.py`) implements the
+  two transformations above (strip script/path/setting refs, replace
+  cross-refs with inline summaries or footnotes). Pin the *degraded*
+  set in the script's source so a human can audit which rules ship
+  modified vs. as-is.
+- **Phase 3 Step 4 char-budget test** — Linear's per-field char limit
+  is still unresearched (Open Question #1 in the roadmap). Before the
+  test is wired, run a quick recon and capture the value. The
+  conservative fallback (~30 KB) probably fits this 18-rule workspace
+  digest without contention; team layer is far smaller.
+- **Phase 3 Step 3 three-layer split** — this document already
+  partitions workspace / team / personal. Step 3 only needs to
+  document the three-layer rationale for the README.
+- Re-classify on every audit run; if a rule is added to
+  `.agent-src.uncompressed/rules/`, this document MUST gain a row.
+
+## Source of tier data
+
+```
+python3 scripts/audit_cloud_compatibility.py --details --format json
+```
+
+47 rules: T1=20, T2=19, T3-S=8. Counts in this document derive from the
+above; if they drift, this document is stale and the digest builder
+must refuse to emit until reconciled.

package/docs/contracts/linear-ai-three-layers.md

@@ -0,0 +1,131 @@
+---
+stability: beta
+---
+
+# Linear AI — three-layer split rationale
+
+> Phase 3 Step 3 deliverable for [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md).
+> Per-rule routing is in [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md);
+> this file documents *why* the split is workspace / team / personal and
+> what belongs in each.
+
+## The three slots Linear gives us
+
+`Settings → Agents → Additional guidance` exposes three text fields:
+
+| Field | Scope | Inheritance | Editable by |
+|---|---|---|---|
+| **Workspace** | Whole organisation | Inherited by every team and every member | Workspace admins |
+| **Team** | One Linear team | Overrides workspace for that team's issues | Team admins |
+| **Personal** | One member, on their own assigned issues | Layered on top of workspace + team | The member |
+
+Linear's docs frame this as **most-specific-wins**: when an agent is
+linked to a Linear issue, it reads workspace + team + personal
+concatenated, with later layers overriding earlier ones. The third-party
+agent (Codegen, Charlie, Cursor's Linear app, …) receives the bytes
+verbatim — no filesystem, no skill triggering, no `.augment/` access.
+
+## Our mapping — workspace / team / personal
+
+The inclusion list partitions our 47 rules into three mutually exclusive
+buckets. Counts and per-rule decisions live in
+[`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md); this
+section explains the *principle* behind each bucket.
+
+### Workspace — universal coding posture (18 rules)
+
+Goes into the **Workspace** field. Rules that:
+
+- Apply regardless of stack (PHP, Node, Python, Go, …)
+- Govern *interaction discipline* — when to ask, how to commit, how to
+  surface options, how to push back on weak reviews
+- Survive without filesystem, scripts, or this package's tooling
+- Carry no Augment-specific or repo-authoring scaffolding
+
+Examples: `ask-when-uncertain`, `commit-conventions`, `direct-answers`,
+`minimal-safe-diff`, `scope-control`, `verify-before-complete`,
+`user-interaction`. Anything that helps a generic third-party agent
+behave like a competent engineer on *any* codebase.
+
+A few rules in this bucket are **degraded** — the digest builder strips
+the local-only sections (rtk, `.agent-settings.yml`, `.augment/` paths,
+`.md`-files-must-be-English clause). The substance survives; the tooling
+references don't.
+
+### Team — framework-specific (4 rules)
+
+Goes into the **Team** field of teams that match the stack. Rules that:
+
+- Name a specific framework, language, or tool in their trigger line
+- Carry conventions that only fire when that stack is touched
+- Don't apply to teams using a different stack (a frontend-only team
+  doesn't need the PHP rules)
+
+Currently four rules: `docker-commands`, `laravel-translations`,
+`e2e-testing` (Playwright), `php-coding`. Each rule already names its
+stack, so the digest builder ships them as-is — no per-rule stripping.
+
+If the org has a Node-only team, paste only `e2e-testing`. If a
+Laravel-Docker team, paste all four. The Team layer is per-team, not
+universal.
+
+### Personal — empty by default (0 rules)
+
+Goes into the **Personal** field of individual members. Empty stub by
+default. Each developer pastes their own preferences into this layer
+manually. Examples a member might add:
+
+- Response language overrides ("respond in German on my issues")
+- Personal naming conventions ("I prefer `result_` prefixes for outputs")
+- Individual IDE shortcuts they want surfaced in PR descriptions
+- Scoped opt-outs from a workspace rule, with a one-sentence reason
+
+The digest builder emits an empty stub with a comment line so members
+have a starting point, but the file is intentionally minimal — the
+package does not own personal preferences.
+
+## Why this split, not a flat blob
+
+Three reasons we don't merge everything into one workspace digest:
+
+1. **Stack-specific noise.** A frontend-only team doesn't need 4 KB of
+   Laravel + PHP + Docker conventions cluttering their guidance field.
+   Pushing those into Team layers keeps the workspace lean and
+   universal.
+2. **Per-team override surface.** When a team needs to override a
+   workspace rule (e.g. their own commit-message convention), Linear's
+   layering already gives them the surface. We don't need to fork the
+   workspace digest per team.
+3. **Personal autonomy.** Members own the Personal layer. The package
+   never writes there; it's the user's escape hatch for individual
+   preferences without lobbying for a workspace-wide rule change.
+
+## Excluded from all three layers (25 rules)
+
+[`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md) §
+"Excluded" covers the four categories: meta-rules about authoring this
+package (20), Augment Code specifics (3), skill-routing only (1),
+already-cloud-inert (1). None of these benefit a third-party agent that
+does not maintain `event4u/agent-config`.
+
+## Future evolution
+
+- **More stacks → more team rules.** When the package gains a Node,
+  Python, or Go equivalent of `php-coding`, the Team digest grows. The
+  decision criterion stays: stack-named in the trigger line → Team;
+  stack-agnostic → Workspace.
+- **Workspace stays bounded.** Adding new universal rules is fine, but
+  the workspace digest should not grow to swamp Linear's per-field cap.
+  Current digest is well under the 100 KB safety budget; if growth
+  approaches the cap, split workspace by *concern* (interaction vs.
+  code-shape vs. delivery) rather than relaxing the cap.
+- **Personal layer stays empty in this package.** Even if patterns
+  emerge, they belong in workspace (if universal) or team (if
+  stack-bound), not in a curated personal blob the package owns.
+
+## Source of truth
+
+- Per-rule decision: [`linear-ai-rules-inclusion.md`](linear-ai-rules-inclusion.md)
+- Builder script: [`scripts/build_linear_digest.py`](../../scripts/build_linear_digest.py)
+- Generated digests: `dist/linear/{workspace,team,personal}.md` (gitignored)
+- Roadmap: [`road-to-universal-distribution.md`](../../agents/roadmaps/road-to-universal-distribution.md) Phase 3

package/docs/contracts/load-context-schema.md

@@ -0,0 +1,186 @@
+---
+stability: beta
+---
+
+# `load_context:` Frontmatter Schema
+
+> **Audience:** rule authors and reviewers who want to keep an Always-rule
+> small while making deeper reasoning available on demand.
+> **Linter:** `scripts/lint_load_context.py` (run via `task lint-load-context`).
+> **Companion:** [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) —
+> hierarchy that decides *which* rule wins when several fire on the same turn.
+
+This contract defines the frontmatter convention by which a rule (or
+another context) declares the deeper reading material it relies on.
+The convention is **lazy by default**: declared entries are *available
+to load* when the situation demands them, never auto-loaded into every
+turn.
+
+## Schema
+
+Two keys, both optional, both top-level frontmatter:
+
+```yaml
+---
+type: "always"
+description: "..."
+load_context:                # lazy — on-demand reference list
+  - .agent-src.uncompressed/contexts/<file>.md
+  - agents/contexts/<file>.md
+load_context_eager:          # opt-in eager — auto-loaded on rule fire
+  - .agent-src.uncompressed/contexts/<file>.md
+---
+```
+
+| Key | Loading | When to use |
+|---|---|---|
+| `load_context:` | **Lazy.** The agent reads the entry only when the rule's reasoning needs it. | Default. Use for everything that is "available knowledge" rather than "on every turn". |
+| `load_context_eager:` | **Eager.** The entry is concatenated into the active context whenever the rule fires. | Only when the deeper material is needed *every single time* the rule fires. Counts against the combined char budget. |
+
+**No default eager-load.** A rule with `load_context:` only does **not**
+auto-load anything; the agent decides per turn. Eager loading is
+opt-in and budget-gated.
+
+## Path rules
+
+- Paths are repo-root relative.
+- Paths MUST end in `.md`.
+- Allowed roots: `.agent-src.uncompressed/contexts/`, `agents/contexts/`,
+  `.agent-src/contexts/` (compressed mirror). Any other root → linter
+  error.
+- A rule MAY reference contexts under either tree, but a
+  `.agent-src.uncompressed/` rule SHOULD NOT eager-load an
+  `agents/contexts/` file (project-local leak into shared package).
+  Linter warns on this combination.
+- A context file may itself declare `load_context:` (chain reasoning).
+  The linter rejects cycles.
+
+## Subdirectory conventions
+
+Subdirectories under `contexts/` are **conventional, not enforced**.
+The linter only validates the root prefix; subdirectory layout is a
+documentation contract for human reviewers.
+
+Two canonical subdirectories are in production:
+
+| Subdir | Holds | First consumer |
+|---|---|---|
+| `contexts/execution/` | runtime decision logic, mechanics, and examples for execution-time rules (autonomy detection, verification mechanics, etc.) | `autonomous-execution` (Phase 2 of `road-to-pr-34-followups`) |
+| `contexts/authority/` | mechanics behind authority gates — what makes commits, scope changes, and git ops legal vs. illegal | `commit-policy` and `scope-control` (Phase 6 of `road-to-pr-34-followups`) |
+
+A third subdirectory, `contexts/communication/`, was proposed by the
+PR #34 round-6 review for user-interaction and language-and-tone
+mechanics. It is **not yet created** — the anti-speculation guard in
+Phase 6 forbids creating a context root before its triggering rule
+exists. Add it the same turn as the first migrating rule, not before.
+
+A new subdirectory is justified when:
+
+- A second rule needs to share contexts with the first one, AND
+- The contexts have a coherent topic (execution, authority, communication, …), AND
+- The triggering rule and its content move at the same time
+  (no empty subdir reservations).
+
+Single-rule contexts that don't fit one of the canonical topics live
+directly under `contexts/` (see `contexts/model-recommendations.md`,
+`contexts/skills-and-commands.md`).
+
+## Combined char-budget guard
+
+`load_context_eager:` triggers a budget check:
+
+```
+chars(rule.md) + sum(chars(eager_target.md) for each entry) ≤ rule_cap
+```
+
+`rule_cap` is the per-rule budget from
+[`road-to-rebalancing.md`](../../agents/roadmaps/road-to-rebalancing.md)
+§ Target architecture:
+
+- Always rule: 2,500
+- Auto rule: 4,000
+- Safety rule (`type: "always"` AND covers Hard-Floor topics): 5,000
+
+Linter computes the rule's class from frontmatter `type:` and the
+hard-floor allowlist (`non-destructive-by-default`,
+`security-sensitive-stop`). Exceeding the cap → linter error.
+
+Lazy `load_context:` does **not** count against the budget — by
+definition it is not loaded into every turn.
+
+## Public-vs-internal leak
+
+A rule shipped to consumers (`.agent-src.uncompressed/rules/`) may
+declare `load_context:` entries pointing at:
+
+- `.agent-src.uncompressed/contexts/` — public, OK.
+- `agents/contexts/` — package-internal, **lint warning** (the entry
+  will not exist in consumer projects).
+
+Project-local rules may reference either. The linter classifies by
+the rule's tree, not by the target's tree.
+
+## No circular references
+
+A `load_context:` graph that cycles fails the linter. Cycles are
+defined across both `load_context:` and `load_context_eager:` edges.
+
+## Examples
+
+### Real consumer — `autonomous-execution`
+
+`.agent-src.uncompressed/rules/autonomous-execution.md` is the first
+production rule to declare `load_context:`. Its frontmatter:
+
+```yaml
+---
+type: "auto"
+description: "Deciding whether to ask the user or just act on a workflow step — trivial-vs-blocking classification, autonomy opt-in detection, commit default; defers to non-destructive-by-default for the Hard Floor"
+alwaysApply: false
+source: package
+load_context:
+  - .agent-src.uncompressed/contexts/execution/autonomy-detection.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-mechanics.md
+  - .agent-src.uncompressed/contexts/execution/autonomy-examples.md
+---
+```
+
+Three lazy-loaded contexts, no `load_context_eager:`. The agent reads
+each context only when the corresponding section of the slim rule
+points at it (the rule body cites the same paths in prose so the
+load is intent-driven, not blanket).
+
+Pattern proven by this consumer:
+
+- **Slim the rule to obligations only** — the 192-line pre-split
+  source dropped to 119 lines (≤ 120 target met) by extracting LOGIC
+  (detection algorithm), MECHANICS (setting table, cloud behavior),
+  and EXAMPLES (anchor phrases, worked cases, failure modes) into
+  three separate context files.
+- **Cite, don't duplicate** — the slim rule contains zero
+  algorithm/mechanics/example prose; everything moved was physically
+  removed (verified by Phase 2.5 obligation diff:
+  [`agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md`](../../agents/reports/pr-34-phase-2-5-autonomous-execution-obligation-check.md)).
+- **Lazy by default** — no eager-load is declared; the budget guard
+  is therefore a no-op for this rule.
+
+`task lint-load-context` reports **1 declarer**, all paths resolve,
+no cycles.
+
+## Stability
+
+`beta` — schema is settled and serves one production rule
+(`autonomous-execution`). A breaking schema change is a SemVer-minor
+pre-1.0 bump. Adding a new optional key is non-breaking. The first
+consumer surfaced no schema gaps; the next migration batch (roadmap
+`road-to-pr-34-followups` Phase 6 — `commit-policy`, `scope-control`,
+`verify-before-complete`) is the next stress test.
+
+## Cross-references
+
+- [`rule-priority-hierarchy.md`](rule-priority-hierarchy.md) — which
+  rule wins on conflict; this schema is orthogonal (depth, not
+  priority).
+- [`rule-interactions.yml`](rule-interactions.yml) — pairwise rule
+  interaction matrix.
+- [`STABILITY.md`](STABILITY.md) — beta-tag implications.

package/docs/contracts/rule-interactions.md

@@ -0,0 +1,107 @@
+---
+stability: beta
+---
+
+# Rule-Interaction Matrix
+
+> **Audience:** rule authors and reviewers — anyone editing
+> `.agent-src.uncompressed/rules/*.md` or proposing a new always-rule.
+> **Authoritative source:** [`rule-interactions.yml`](rule-interactions.yml).
+> **Linter:** `scripts/lint_rule_interactions.py` (run via `task lint-rule-interactions`).
+
+The matrix captures how the package's `always` rules relate when more
+than one fires on the same turn. It exists because rules at this size
+(55 rules, ~49k tokens budget) develop emergent precedence relationships
+that no single rule file can document on its own.
+
+The anchor pair is `non-destructive-by-default` — the universal safety
+floor — paired with the five rules most likely to be invoked in the
+same turn:
+
+- `autonomous-execution` — autonomy never lifts the floor.
+- `scope-control` — git-ops permission gate; floor is the never-overridable subset.
+- `commit-policy` — four exception paths to commit; floor still gates the diff content.
+- `ask-when-uncertain` — both rules push toward the same response on a destructive ambiguous request.
+- `verify-before-complete` — independent gates; both must be satisfied.
+
+## Diagram
+
+```mermaid
+graph LR
+  NDD["non-destructive-by-default<br/>(Hard Floor)"]
+  AE["autonomous-execution"]
+  SC["scope-control"]
+  CP["commit-policy"]
+  AWU["ask-when-uncertain"]
+  VBC["verify-before-complete"]
+
+  NDD -- "overrides" --> AE
+  NDD -- "restates" --> SC
+  NDD -- "gates diff" --> CP
+  NDD -- "complements" --> AWU
+  NDD -- "complements" --> VBC
+
+  SC -- "gates git ops" --> AE
+  CP -- "overrides<br/>commit Q" --> AE
+
+  classDef floor fill:#7a1f1f,stroke:#fff,color:#fff,font-weight:bold
+  classDef gate fill:#1f4f7a,stroke:#fff,color:#fff
+  class NDD floor
+  class SC,CP gate
+```
+
+## Relations
+
+The YAML uses six relation kinds. Definitions:
+
+| Relation | Meaning |
+|---|---|
+| `overrides` | Senior rule's outcome wins when both fire — junior's permission cannot proceed past senior's stop. |
+| `narrows` | Senior shrinks the surface area on which junior applies, but does not stop it. |
+| `defers_to` | Junior explicitly hands over to senior on the overlapping surface. |
+| `restates` | The two rules cover overlapping ground intentionally — the restatement prevents future weakening of one side. |
+| `gates` | Senior fires *in addition to* junior on a specific subset, not instead of. |
+| `complements` | Both rules independently apply; outcomes are additive and harmonious. |
+
+## Reading a pair entry
+
+```yaml
+- id: ndd-x-autonomous-execution
+  rules: [non-destructive-by-default, autonomous-execution]   # senior, junior
+  relation: overrides
+  conflict: …                                                  # what triggers both
+  resolution: …                                                # what the agent does
+  evidence:
+    - .agent-src.uncompressed/rules/non-destructive-by-default.md#the-iron-law
+    - .agent-src.uncompressed/rules/autonomous-execution.md#hard-floor--see-non-destructive-by-default
+```
+
+`rules: [a, b]` is ordered: `a` is senior (wins on conflict), `b` is
+junior (yields). For `complements`, ordering is documentary only.
+
+## Adding a new pair
+
+1. Edit `rule-interactions.yml`, append a pair under `pairs:` with all
+   six required fields.
+2. Add both rule slugs to the top-level `rules:` block if not already
+   listed.
+3. Run `task lint-rule-interactions` — must exit 0.
+4. Update the Mermaid diagram above if the pair is anchor-relevant
+   (involves `non-destructive-by-default` or one of its five partners).
+5. Reference the matrix from the rule files that are involved (one
+   line each — the matrix is the source, not the rules).
+
+## When **not** to add a pair
+
+- Two rules that never fire on the same turn — no interaction means
+  no entry; the matrix is for *active* relationships.
+- Documentation-only cross-references (e.g. "see also") — those stay
+  in the rule files.
+- Skill ↔ rule interactions — the matrix is rule-only. Skills are
+  invoked, not always-active.
+
+## See also
+
+- [`docs/contracts/STABILITY.md`](STABILITY.md) — public-surface stability tiers.
+- [`docs/contracts/adr-chat-history-split.md`](adr-chat-history-split.md) — ADR pattern for major rule structural changes.
+- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) § P2.2 — anchor for this matrix.