docs: resolve §2/§1/§10 backlink contradictions flagged on #685

[0xbulma]

Follow-up to #685 (merged). Foulques flagged four internal contradictions that survived the audit; this PR fixes all four. Doc-only — no code paths affected.

Summary

1. §2 backlink no longer credits silent-failure-hunter for "2 — typed errors". The persona's own body (.agents/personas/silent-failure-hunter.md:7) + .agents/personas/code-quality.md:24 explicitly defer the typed-class-existence rule to code-quality. The §2 backlink now lists the actual owners for the two orphaned rules: module-api-architecture for build(deps-dev): bump eslint-plugin-prettier from 4.2.1 to 5.1.3 #5 (deep cross-package imports — its body at module-api-architecture.md:20 enforces exactly this) and test-coverage for feat(viem): add viem support #6 (mocked viem clients on RPC paths — test-coverage.md:37). silent-failure-hunter stays in the callout but reframed as the complement to rule 2 (handling discipline once the error is thrown) — which is what the body actually says, and what keeps the documentation persona's bidirectional-consistency check (.agents/personas/documentation.md:71) from flagging a one-way pointer.

2. code-quality.md's "Code smells" section no longer claims early returns are "not codified in AGENTS.md". The rule is the last bullet of §1 "Stateless, immutable, composable" (AGENTS.md:52). Header parenthetical tightened; the bullet now cites §1 directly.

3. CI/release dedupe (the two <HAS_CI_RELEASE> and secrets: inherit drifts).

   • <HAS_CI_RELEASE> trigger path-list now lives in exactly one place (.agents/lib/pr-review-base.md:85, Step 4). The §10 inventory table cell and ci-release-security.md's Trigger section are thin pointers to it.
   • Two rules that existed only in the persona body (and so couldn't be enforced as canonical) are promoted to §10: Newly added actions from publishers the org has not used before (appended to "Action pinning") and Workspace install behavior (auto-install-peers / strict-peer-dependencies flips, medium severity).
   • secrets: inherit wording synced — both AGENTS.md:233 and ci-release-security.md:42 now read …is forbidden — list secrets explicitly.
   • ci-release-security.md gains an intro line declaring §10 as source-of-truth, mirroring the pattern code-quality.md:17 uses for §2/§3.

4. silent-failure-hunter.applies no longer cites §1 (testability). §1 "Testability" (AGENTS.md:40-45) is about DI / I/O at the boundary, which the persona doesn't enforce. The applies line is rewritten to describe what the persona actually does (the rule-2 complement). §1 backlink drops silent-failure-hunter to match.

Files changed

File	Why
AGENTS.md	§1 backlink (drop SFH); §2 backlink (drop SFH-as-enforcer, add MAA + TC + SFH-as-complement); §10 inventory rows for MAA / SFH / TC; §10 ci-release-security row collapses trigger spec to a pointer; add 2 missing rules to §10
.agents/personas/silent-failure-hunter.md	applies: reframed (drop §1, narrow §2 to rule-2 complement)
.agents/personas/ci-release-security.md	Trigger section → pointer at pr-review-base.md Step 4; intro line referencing §10; secrets: inherit wording sync
.agents/personas/code-quality.md	Code-smells header parenthetical; early-returns bullet now cites §1
.agents/personas/module-api-architecture.md	applies: adds §2 rule 5
.agents/personas/test-coverage.md	applies: adds §2 rule 6

Test plan

• Bidirectional consistency walk (every > Applied by personas: callout in AGENTS.md vs every persona's applies: frontmatter). One pre-existing asymmetry remains at §7 ↔ ci-release-security (publish-flow); out of scope for this PR.
• <HAS_CI_RELEASE> path-list grep — exactly one full definition in the repo (.agents/lib/pr-review-base.md:85), two pointers (AGENTS.md §10 table cell, ci-release-security.md Trigger section).
• secrets: inherit grep — both occurrences match verbatim.
• documentation persona's bidirectional-consistency check returns clean against this branch.

🤖 Generated with Claude Code

---

View Slack thread

[devin-ai-integration]

Devin Review found 1 potential issue.

View 4 additional findings in Devin Review.

[devin-ai-integration]

🟡 module-api-architecture body intro omits §2 after frontmatter was updated to include it

The PR updates applies: frontmatter to add §2 Forbidden patterns (rule 5 — deep cross-package imports), and AGENTS.md §2's backlink now lists module-api-architecture. However, the body intro on this same line was not updated — it still says "The authoritative rules live in §1 (Architecture), §3 (Type discipline), and §4 (Public API & packaging)" with no mention of §2. Per the documentation persona (.agents/personas/documentation.md:50), this is stale prose: a statement that no longer matches reality after the diff. An agent reading the body for context could miss that §2 rule 5 is now an authoritative anchor for this persona. The deep-import bullet at line 20 does enforce the rule, but the intro misleadingly omits §2 from the list of authoritative sources.

Prompt for agents

The applies: frontmatter on line 4 now includes §2 Forbidden patterns (rule 5), but the body intro on line 14 still says 'The authoritative rules live in AGENTS.md §1 (Architecture), §3 (Type discipline), and §4 (Public API & packaging)'. Update line 14 to also mention §2 (Forbidden patterns — rule 5), e.g.: 'The authoritative rules live in AGENTS.md §1 (Architecture), §2 (Forbidden patterns — rule 5: deep cross-package imports), §3 (Type discipline), and §4 (Public API & packaging)'. Similarly, line 18 groups the deep-import bullet under 'Per AGENTS.md §1 and §4' — consider splitting out a 'Per AGENTS.md §2 — forbidden pattern 5' sub-heading for the deep-import rule, or updating line 18 to say 'Per AGENTS.md §1, §2 (rule 5), and §4'.

---

Was this helpful? React with 👍 or 👎 to provide feedback.