@event4u/agent-config 1.15.0 → 1.17.0

package/.agent-src/rules/package-ci-checks.md

@@ -3,11 +3,16 @@ type: "auto"
 alwaysApply: false
 description: "Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/package-ci-checks-mechanics.md
 ---
 
 # Package CI Checks
 
-Before **any** push/PR in agent-config: run ALL CI checks locally.
+## When this applies
+
+Before **any** push to remote or PR creation in the **agent-config** package.
+This rule is specific to this package — it does NOT apply to consumer projects.
 
 ## The Iron Law
 
@@ -17,69 +22,24 @@ NEVER push without running ALL CI checks locally first.
 
 Every CI pipeline failure is preventable by running these checks before pushing.
 
-## Required checks
-
-### 1. Sync
-
-```bash
-bash scripts/compress.sh --check          # .agent-src/ matches .agent-src.uncompressed/
-bash scripts/compress.sh --check-hashes   # compression hashes are clean
-```
-
-### 2. Consistency
-
-```bash
-python3 scripts/check_compression.py   # compressed variants are valid
-python3 scripts/check_references.py     # no broken cross-references
-python3 scripts/check_portability.py    # no project-specific references in shared files
-```
-
-### 3. Linter (0 FAIL required)
-
-```bash
-python3 scripts/skill_linter.py --all   # 0 FAIL required
-```
-
-### 4. Tests
-
-```bash
-python3 -m pytest tests/ --tb=short     # all tests must pass
-```
-
-### 5. README
-
-```bash
-python3 scripts/readme_linter.py README.md --root .
-```
-
-## Quick one-liner
-
-```bash
-bash scripts/compress.sh --check && \
-bash scripts/compress.sh --check-hashes && \
-python3 scripts/check_compression.py && \
-python3 scripts/check_references.py && \
-python3 scripts/check_portability.py && \
-python3 scripts/skill_linter.py --all && \
-python3 -m pytest tests/ --tb=short && \
-python3 scripts/readme_linter.py README.md --root .
-```
-
-## After editing skills/rules in .agent-src.uncompressed/
-
-1. Edit uncompressed file
-2. Edit compressed file in `.agent-src/` to match
-3. `bash scripts/compress.sh --mark-done {relative-path}` — update hash
-4. `bash scripts/compress.sh --check-hashes` — verify
+## Required checks — see mechanics
 
-**Skip step 3 → CI WILL fail.**
+Five checks must pass locally before push, in this order:
 
-## After editing scripts/compress.py
+1. **Sync** — `compress.sh --check` and `--check-hashes`.
+2. **Consistency** — `check_compression.py`, `check_references.py`, `check_portability.py`.
+3. **Linter** — `skill_linter.py --all`, 0 FAIL required.
+4. **Tests** — `pytest tests/`.
+5. **README** — `readme_linter.py`.
 
-Run `python3 -m pytest tests/test_compress.py -v` **immediately** — don't wait.
+The full command snippets, common-failure notes per step, the quick
+chained one-liner, and the post-edit workflow ("after editing
+skills/rules", "after editing `scripts/compress.py`") all live in
+[`contexts/communication/rules-auto/package-ci-checks-mechanics.md`](../contexts/communication/rules-auto/package-ci-checks-mechanics.md).
+Pull it whenever pre-push verification is needed.
 
 ## Do NOT
 
-- Push "to see if CI passes" — wastes pipeline minutes
-- Skip hash checks for "small changes"
-- Assume tests pass because linter passes
+- Do NOT push "to see if CI passes" — that wastes pipeline minutes
+- Do NOT skip hash checks because "I only changed one file"
+- Do NOT assume tests pass because linter passes — they check different things

package/.agent-src/rules/preservation-guard.md

@@ -7,43 +7,78 @@ source: package
 
 # Preservation Guard
 
-Transformations (merge, refactor, compress, split) must produce output **at least as strong** as input.
+When transforming any agent artifact (merge, refactor, compress, split, restructure),
+the result must be **at least as strong** as the original.
 
 ## Iron Laws — every passage stays, caveman is fine
 
-Sections marked **Iron Law** (heading matches `# Iron Law`, `# Iron Laws`,
-`# The Iron Law`, any level, numbered like `Iron Law 1`, `Iron Law 2`)
-are **non-negotiable**, strictest preservation:
+Sections marked **Iron Law** (any heading matching `# Iron Law`, `# Iron Laws`,
+`# The Iron Law`, at any heading level, including numbered variants like
+`Iron Law 1`, `Iron Law 2`) are **non-negotiable** and require the strictest
+preservation:
 
-- [ ] **Heading verbatim** — exact text, exact level. Drop heading → law gone, even if code block survives.
-- [ ] **Fenced code blocks byte-for-byte** — the law itself.
-- [ ] **Negation clauses kept** — `NO X`, `NEVER Y`, `NOT Z` stay. Load-bearing exception denials, not filler.
-- [ ] **Every passage stays** — every paragraph, every list item, every fenced code block from source survives in compressed output, in order. One paragraph → one paragraph; one bullet → one bullet. Dropping whole sentences, merging two paragraphs, skipping a list item is forbidden, even if surviving prose still "makes the point".
-- [ ] **No Iron Law downgrades** — `## Iron Law` MUST NOT become `### Iron Law`, `**Iron Law:**`, or inline prose. Heading level is part of prominence.
+- [ ] **Heading preserved verbatim** — exact text and exact heading level. Drop the
+  heading → the law is gone, even if the code block underneath survives.
+- [ ] **Fenced code blocks preserved byte-for-byte** — the law itself.
+- [ ] **Negation clauses preserved** — `NO X`, `NEVER Y`, `NOT Z` stay in. These
+  are the load-bearing exception denials, not filler.
+- [ ] **Every passage stays** — every paragraph, every list item, and every
+  fenced code block from the source survives in the compressed output, in
+  order. One paragraph → one paragraph; one bullet → one bullet. Dropping
+  whole sentences, merging two paragraphs into one, or skipping a list item
+  is forbidden, even if the surviving prose still "makes the point".
+- [ ] **No Iron Law downgrades** — `## Iron Law` MUST NOT become `### Iron Law`,
+  `**Iron Law:**`, or inline prose. Heading level is part of the prominence.
 
-**Caveman style encouraged for Iron Law bodies** — drop articles ("the", "a"), shorten phrasing, primitive grammar, terse cave-speak. Word count not a budget; structural unit count is. Every paragraph, bullet, code block from source present → compress as hard as you want. Forbidden is **deletion**: rationale paragraph stays, canonical-failure example stays, every "NEVER X" bullet stays.
+**Caveman style is encouraged for Iron Law bodies** — drop articles ("the",
+"a"), shorten phrasing, primitive grammar, terse cave-speak. Word count is
+not a budget; the structural unit count is. As long as every paragraph,
+bullet, and code block from the source is present, compress as hard as you
+want. What's forbidden is **deletion**: the rationale paragraph stays, the
+canonical-failure example stays, every "NEVER X" bullet stays.
 
-`scripts/check_compression.py` enforces mechanically — any violation is `error`, not warning.
+`scripts/check_compression.py` enforces these mechanically — any violation is
+an `error`, not a warning.
 
-## Checklist — verify before completing
+## Mandatory preservation checklist
 
-- [ ] **Iron Law sections** preserved per rules above — heading, body, fenced blocks, rationale
-- [ ] Strongest validation step preserved
-- [ ] Strongest example preserved
-- [ ] Strongest anti-pattern / "Do NOT" preserved
-- [ ] Essential decision hints (if/when/unless) preserved
-- [ ] Required sections preserved
-- [ ] Single clear responsibility preserved
-- [ ] Strong language ("MUST"/"NEVER") not weakened
+Before completing any transformation, verify:
 
-## Reject if
+- [ ] **Iron Law sections** preserved per the rules above — heading, body, fenced blocks, rationale
+- [ ] **Strongest validation step** preserved — concrete verify/confirm actions survive
+- [ ] **Strongest example** preserved — the most illustrative code block or scenario stays
+- [ ] **Strongest anti-pattern** preserved — the most important "Do NOT" or failure mode stays
+- [ ] **Essential decision hints** preserved — if/when/unless logic that prevents mistakes
+- [ ] **Required sections** preserved — When to use, Procedure, Output, Gotchas, Do NOT
+- [ ] **Single clear responsibility** preserved — no scope creep from merging unrelated concerns
+- [ ] **Strong language** preserved — "MUST", "NEVER", "Do NOT" not weakened to "should", "avoid"
 
-- Iron Law heading removed or downgraded
-- Paragraph, list item, or fenced code block dropped from Iron Law section
-- Negation clauses or canonical-failure prose stripped from Iron Law
-- Validation, example, or anti-pattern removed without replacement
-- Decision logic weakened
-- Scope broadened by merging unrelated concerns
-- Strong language downgraded
+## Reject criteria
 
-→ Skills: `skill-management`, `skill-reviewer` · Command: `/compress` · Linter: `check_compression_quality()`
+**REJECT** the transformation if it:
+
+- Removes or downgrades an Iron Law heading
+- Drops a paragraph, list item, or fenced code block from an Iron Law section
+- Strips negation clauses or canonical-failure prose from an Iron Law
+- Removes a concrete validation step without equivalent replacement
+- Removes the strongest example without equivalent replacement
+- Removes the strongest anti-pattern without equivalent replacement
+- Weakens routing or decision logic
+- Broadens scope by merging unrelated workflows
+- Weakens strong enforcement language
+
+## Applies to
+
+- Skill merges (combining two skills into one)
+- Skill splits (extracting part of a skill)
+- Refactoring (restructuring without behavior change)
+- Compression (`.agent-src.uncompressed/` → `.agent-src/`)
+- Rule consolidation
+- Guideline restructuring
+
+## References
+
+- Skill: `skill-management` — compression/refactoring modes
+- Skill: `skill-reviewer` — compression safety checks
+- Command: `/compress` — compression quality checklist
+- Linter: `scripts/skill_linter.py` — `check_compression_quality()`

package/.agent-src/rules/review-routing-awareness.md

@@ -2,6 +2,8 @@
 type: "auto"
 description: "When routing reviewers or flagging risk hotspots — consult ownership-map and historical-bug-patterns before suggesting reviewers or claiming a change is safe"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/review-routing-awareness-mechanics.md
 ---
 
 # Review Routing Awareness
@@ -37,24 +39,13 @@ Look, in order, for:
 - `.github/historical-bug-patterns.yml` (or
   `agents/historical-bug-patterns.yml`)
 
-If neither exists, fall back to engineering-memory via
-[`memory-access`](../guidelines/agent-infra/memory-access.md):
-
-```python
-from scripts.memory_lookup import retrieve
-extra = retrieve(
-    types=["ownership", "historical-patterns"],
-    keys=<changed file paths>,
-    limit=5,
-)
-```
-
-Curated memory (`agents/memory/ownership.yml`,
-`agents/memory/historical-patterns.yml`) shares the schema with the
-project-local YAMLs and is merged into the routing output. If both
-memory and project YAMLs are absent, skip this rule and rely on
-[`reviewer-awareness`](reviewer-awareness.md) defaults. **Do not invent
-owners or patterns** from context.
+If neither file exists, fall back to the engineering-memory layer.
+Memory-lookup snippet and merge semantics live in
+[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
+§ Memory-lookup fallback. If both memory and project YAMLs are absent,
+skip this rule and rely on
+[`reviewer-awareness`](reviewer-awareness.md) defaults. **Do not
+invent owners or patterns** from context.
 
 ### 2. Match the diff
 
@@ -66,30 +57,24 @@ For every changed file, collect:
   mode and the minimum control or test the project expects.
 
 Matching uses glob patterns (see
-[`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+[`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
 for the schema).
 
 ### 3. Surface findings
 
-When producing a review plan, include:
-
-- **Owner-mapped roles** — explicitly preferred over generic roles. If
-  the ownership map says `app/Billing/**` is owned by `finance-engineering
-  + security`, use those, not "backend + security".
-- **Historical-pattern warnings** — list every matched pattern with a
-  short label and the required control, e.g. _"Pattern: N+1 on tenant
-  listings → add an eager-load regression test"_.
-- **Confidence note** — if the ownership map is stale (last updated > 6
-  months ago per the `updated` field), say so. Ownership maps rot.
+When producing a review plan, include owner-mapped roles (preferred
+over generic), historical-pattern warnings (with required control),
+and a staleness note if the ownership map's `updated` field is older
+than 6 months. Worked examples for each in
+[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
+§ Surface findings.
 
 ### 4. Do NOT overreach
 
-- **Never rename paths** or add ownership entries as a side effect of a
-  code change. Ownership map edits are a separate, explicit task.
-- **Never mark a change safe** only because no pattern matched. Pattern
-  absence means "no known hit", not "no risk".
-- **Never copy historical-pattern names into the diff** as code comments
-  or commit messages — they are routing metadata, not commentary.
+The "do NOT overreach" guardrails (no path renames as side effects, no
+"safe because no match", no pattern names in diffs/commits) live in
+[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
+§ Do NOT overreach.
 
 ## Interaction with other rules
 
@@ -102,22 +87,18 @@ When producing a review plan, include:
   matched pattern is a reason to **add a test**, never a reason to
   expand scope into unrelated refactors.
 
-## Anti-patterns — reject them
+## Anti-patterns
 
-- Suggesting owners "because this looks like billing code" without
-  consulting the ownership map when one exists.
-- Inventing historical patterns from general knowledge — patterns must
-  come from the project's own registry.
-- Downgrading a matched high-severity pattern because "the author said
-  it's fine" — the pattern was registered because it bit before.
-- Treating an out-of-date map as absent. Flag staleness; do not silently
-  skip.
+The four anti-pattern rejections (invented owners, invented patterns,
+downgrading high-severity hits, treating stale maps as absent) live in
+[`contexts/communication/rules-auto/review-routing-awareness-mechanics.md`](../contexts/communication/rules-auto/review-routing-awareness-mechanics.md)
+§ Anti-patterns.
 
 ## See also
 
 - [`reviewer-awareness`](reviewer-awareness.md) — formatting reviewer
   suggestions.
-- [`review-routing-data-format`](../guidelines/review-routing-data-format.md)
+- [`review-routing-data-format`](../../docs/guidelines/agent-infra/review-routing-data-format.md)
   — YAML schemas for ownership-map and historical-bug-patterns.
 - [`review-routing`](../skills/review-routing/SKILL.md) — the skill
   that produces the merged routing report.

package/.agent-src/rules/roadmap-progress-sync.md

@@ -1,10 +1,15 @@
 ---
 type: "auto"
-description: "Any touch to agents/roadmaps/ — creating, renaming, deleting, or moving a roadmap file (including into archive/ or skipped/), editing checkboxes ([x], [~], [-]), or adding/renaming/removing phases — must regenerate the roadmap dashboard in the SAME response; a roadmap that hits 0 open items must also be archived in the SAME response"
+description: "Any touch to agents/roadmaps/ — create/rename/delete/move, edit checkboxes ([x]/[~]/[-]), add/rename/remove phases — must regenerate dashboard and archive if 0 open items, same response"
 alwaysApply: false
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md
 ---
 
+<!-- cloud_safe: degrade -->
+<!-- Authoring discipline applies in cloud; local script + regen are no-ops there. -->
+
 # Roadmap Progress Sync
 
 ## Iron Law — dashboard sync
@@ -30,6 +35,7 @@ without regenerating? The dashboard claims it does not exist. Marked
 EVERY ACTIVE ROADMAP MUST CONTAIN AT LEAST ONE TRACKABLE CHECKBOX
 (`- [ ]`) PER NON-INTRO PHASE. ROADMAPS WITHOUT EXECUTABLE STEPS
 EITHER GET A CHECKLIST OR THE `status: draft` FLAG.
+CI-ENFORCED: `scripts/check_roadmap_trackable.py` (CANNOT BE DEFERRED).
 ```
 
 **Active roadmap =** any file in `agents/roadmaps/` (root, not
@@ -42,9 +48,16 @@ Tables of decisions, ICE matrices, ADR captures, and "block
 sequencing" tables are valid **rationale**, but they do not satisfy
 this rule on their own — they must be paired with at least one
 `## Phase N` section whose checkboxes execute the decision.
-Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`, or
-`## Block A` do **not** count — only the canonical `Phase <id>`
-form parsed by the dashboard.
+Headings such as `## Phase steps`, `### Sequencing — Phase 1 …`,
+`### P0 #1 — …`, or `## Block A` do **not** count — only the
+canonical `Phase <id>` form parsed by the dashboard.
+
+**CI backstop.** `scripts/check_roadmap_trackable.py` (package-shipped,
+wire into the consumer's pre-commit / pre-push / Actions gate) fails
+when an active roadmap has zero canonical `Phase` headings or when
+any parsed phase has zero checkboxes. Last line of defence — real-time
+authoring still flips checkboxes and regenerates the dashboard the
+same response.
 
 ## Status — binary `ready` (default) vs `draft`
 
@@ -69,11 +82,6 @@ in the dashboard.
   executable phases. Flip to ready (or remove the field) the
   moment the roadmap is ready to track.
 
-A `## Decisions` or `## Block sequencing` table is **not** a roadmap
-on its own. Either pair it with a `## Phase N: <name>` section whose
-checkboxes execute the decision, or mark the file `status: draft`
-until the executable phases land.
-
 **Completion = archival, same response.** When the edit takes a
 roadmap to `count_open == 0` (every item is `[x]`, `[~]`, or `[-]`),
 `git mv` it into `agents/roadmaps/archive/` (or `skipped/` if no `[x]`
@@ -82,33 +90,6 @@ roadmap left under `agents/roadmaps/` is a rule violation, not an
 optional cleanup. See `roadmap-management` skill for the archive vs
 skipped decision table.
 
-## How to regenerate
-
-```bash
-./agent-config roadmap:progress
-```
-
-The `./agent-config` wrapper is written into the project root by the
-package installer and delegates to the master CLI inside
-`node_modules/@event4u/agent-config/` or `vendor/event4u/agent-config/`.
-No global tooling required.
-
-## Triggers
-
-| Edit | Must run, same response |
-|---|---|
-| **Create a new roadmap file** | regenerate dashboard |
-| **Rename or delete a roadmap file** | regenerate dashboard |
-| Mark step `[x]`, `[~]`, `[-]`, or unmark back to `[ ]` | regenerate dashboard |
-| Add, rename, or remove a phase | regenerate dashboard |
-| **Last `[ ]` flips** — roadmap reaches `count_open == 0` | `git mv` → `archive/` (or `skipped/`) **then** regenerate dashboard |
-| Move roadmap between `roadmaps/` ↔ `archive/` ↔ `skipped/` | regenerate dashboard |
-
-**Batching rule:** if you edit multiple checkboxes in one response, a
-**single** regeneration at the end of that response is enough — but
-the response must not end without it. If one of those edits closes a
-roadmap, archive it first, then run the single regen.
-
 ## Autonomous execution — checkbox cadence
 
 When executing a roadmap autonomously (multi-turn, no per-step user
@@ -130,20 +111,9 @@ Step counts as completed when:
 Then in the **same reply**: flip the checkbox, regenerate the
 dashboard, commit if commit policy allows.
 
-**Forbidden pattern** (canonical failure):
-
-> Turn 1: implement Step 1. Turn 2: implement Step 2. Turn 3:
-> implement Step 3. Turn 4: implement Step 4. Turn 5: "all done,
-> let me update the roadmap and commit." → the user spent four turns
-> without dashboard movement.
-
-**Required pattern:**
-
-> Turn 1: implement Step 1, flip `[x]`, regen, commit.
-> Turn 2: implement Step 2, flip `[x]`, regen, commit. …
-
-A reply that lands a verified step without flipping its checkbox
-is a rule violation.
+**Forbidden:** four turns of step work, dashboard flat, single regen at the end.
+**Required:** each turn — implement step, flip `[x]`, regen, commit (if policy allows).
+A reply that lands a verified step without flipping its checkbox is a rule violation.
 
 **In-progress marker:** when a step takes more than one reply,
 mark it `[~]` the moment work starts on it and regenerate. The
@@ -151,49 +121,11 @@ user sees one row move from `[ ]` to `[~]` to `[x]` instead of
 silent rows. `[~]` is treated as open for `count_open` but moves
 the phase percentage forward in the dashboard.
 
-## Pre-send self-check — MANDATORY
-
-Before sending any reply that touched `agents/roadmaps/`, run this
-silent gate:
-
-1. Did this turn create, rename, delete, or move a roadmap file? → regen MUST be in the reply.
-2. Did this turn flip any checkbox in a roadmap file? → regen MUST be in the reply.
-3. Did the regen output (`✅ Wrote agents/roadmaps-progress.md · …`) actually appear this turn? → if no, run it now before sending.
-4. **Autonomous roadmap execution gate** — did this turn complete a roadmap step (code saved + verification passed) without flipping its checkbox? → flip `[x]` (or `[~]` if multi-turn) and regen before sending.
-5. **Trackable-roadmap gate** — did this turn create or substantially edit a roadmap file? → does it now contain at least one `- [ ]` per non-intro phase, **or** carry `status: draft` in frontmatter? → if neither, add the checklist or the draft flag before sending.
-
-Any "yes" + no regen run = rule violation. Rerun before sending.
-
-## Failure modes
-
-- **Created the roadmap, marked Phase 1 done across multiple turns,
-  never regenerated** — dashboard silently lies "this roadmap does
-  not exist" to the next reader. Canonical failure of this rule;
-  the rule was hardened in response to it.
-- **Regenerated yesterday, edited today, "I'll regen at session
-  end"** — session ends from a crash, regen never lands.
-- **Closed a roadmap (last `[ ]` → `[x]`) and regenerated before
-  `git mv`** — the closed roadmap reappears in "Open roadmaps".
-- **Edited the dashboard by hand to "fix it quickly"** — next regen
-  overwrites the manual edit; no audit trail of why.
-- **Autonomous run, four steps shipped across four turns, dashboard
-  flat the whole time, single regen at the end** — user lost
-  progress visibility for the entire run. Each completed step must
-  flip its checkbox in the reply that ships it.
-- **Decision-only roadmap shipped without checkboxes** — the file
-  documents synthesized decisions, ICE matrices, or block sequencing
-  but contains zero `- [ ]` items. The dashboard regenerates with
-  `0/0 steps` for that file or omits it from the open set entirely.
-  The reader thinks no work is planned. Either pair the decisions
-  with a `## Phase N` / `## Implementation Checklist` section, or
-  mark the file `status: draft` so it is hidden until the executable
-  phases land.
-
-## Do NOT
-
-- Do NOT edit `agents/roadmaps-progress.md` by hand — always regenerate.
-- Do NOT defer the regen to "next commit" or "before push" — same response.
-- Do NOT rely on CI (`--check` mode) as the first line of defence — CI is last-line, not real-time.
-- Do NOT skip the regen because "only one checkbox changed" — the dashboard aggregates counts and phase percentages that shift on single edits.
-- Do NOT leave a 100%-complete roadmap in `agents/roadmaps/` "for review" — archive it in the same response, ask the user afterwards if needed, not before.
-- Do NOT regenerate the dashboard before the `git mv` when a roadmap closes — otherwise the completed roadmap reappears in "Open roadmaps".
+## Mechanics — triggers, regen command, self-check, failures
+
+The triggers table, the regen command (`./agent-config roadmap:progress`),
+the mandatory pre-send self-check, the failure-mode catalog, and the
+`Do NOT` list live in
+[`contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md`](../contexts/communication/rules-auto/roadmap-progress-sync-mechanics.md).
+Pull it whenever a trigger fires — the rule above is the obligation
+surface; the mechanics file is the lookup material.

package/.agent-src/rules/role-mode-adherence.md

@@ -9,7 +9,7 @@ source: package
 
 Auto-activates when `.agent-settings.yml` sets `roles.active_role` to
 one of the six modes defined in
-[`role-contracts`](../guidelines/agent-infra/role-contracts.md):
+[`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md):
 `developer`, `reviewer`, `tester`, `po`, `incident`, `planner`.
 
 Read `roles.active_role` from `.agent-settings.yml` at session start.
@@ -47,7 +47,7 @@ Infer the mode (Phase-3 router does that). Touch `.agent-settings.yml`
 
 ## See also
 
-- [`role-contracts`](../guidelines/agent-infra/role-contracts.md)
+- [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md)
 - [`/mode`](../commands/mode.md)
 - [`ask-when-uncertain`](ask-when-uncertain.md)
 - [`scope-control`](scope-control.md)