Propagate + audit the P6 /kg-discovery reflex into existing workspaces (BRO-1555)

[broomva]

Why

Auditing "does installing bstack update agent rules to use /kg" surfaced two propagation gaps. BRO-1426 added the §P6 "/kg for discovery, never substrate grep" retrieval reflex to the AGENTS.md template — but:

1. repair never backfilled it. scaffold_governance_file is idempotent-never-overwrite (existing AGENTS.md preserved), and repair.sh only backfilled the Development Philosophy section. A workspace bootstrapped before BRO-1426 never got the reflex.
2. doctor never audited it. §6 checked catalog freshness + that /kg is installed, but never that AGENTS.md contains the reflex.

Change

• repair.sh backfill_retrieval_discipline() — backfills the §P6 paragraph into an existing AGENTS.md. Idempotent (skip if present), anchored (§P6 → next heading; warn+skip if absent), file-only awk extraction (content never shell-interpolated, backticks/pipes survive). Mirrors backfill_philosophy_section; registered beside it. (Uses flag-clear, not awk exit, on the boundary — avoids the tr|awk SIGPIPE-under-pipefail trap the philosophy code documents.)
• doctor.sh §4c — advisory: [ok] when present, [info] + backfill hint when absent. Never a GAP, never fails --strict (mirrors §4b). Proven gap-neutral + strict-neutral by test.

Robust marker

Detection uses the coined phrase substrate grep (not the full "never substrate grep"), so a workspace carrying the reflex under different wording — e.g. this workspace's hand-authored "not a substrate grep" variant — is detected as present and not duplicated. Verified on the real workspace: doctor → [ok], repair dry-run → no backfill (no dup). substrate grep appears only in the reflex (1× in template).

Tests

tests/retrieval-discipline-backfill.test.sh — 16 assertions: backfill + idempotency + position-inside-§P6 + verbatim content + --dry-run writes-nothing + missing-anchor skip + §4c advisory both directions + GAP/--strict neutrality + CRLF tolerance. Sibling philosophy-backfill (17) + all 5 canary suites green. shellcheck -S error clean.

Scope

broomva/bstack only. No primitive-count / doctor-integer-section change (sub-rule + advisory subsection). The workspace's own AGENTS.md already carries the reflex (BRO-1426 lockstep) — this is purely propagation-to-other/existing-workspaces + audit.

Closes BRO-1555

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a new automated check that notices when the AGENTS guidance is missing a retrieval-discipline note and suggests a fix.
  • Expanded the repair flow to automatically backfill that guidance into the relevant section when needed.

• Bug Fixes

  • Improved handling for repeated runs, dry runs, and formatting differences so the update is applied cleanly and only once.
  • Added validation for missing section anchors to avoid unintended file changes.

[coderabbitai]

Warning

Review limit reached

@broomva, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 47 minutes and 44 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 335652da-941f-417e-8a2a-5bcb09adb713

📥 Commits

Reviewing files that changed from the base of the PR and between f9052f5 and 8d3ccec.

📒 Files selected for processing (1)

• tests/retrieval-discipline-backfill.test.sh

📝 Walkthrough

Walkthrough

Adds a new AGENTS.md retrieval-discipline backfill in scripts/repair.sh, an informational advisory check in scripts/doctor.sh, and a new Bash test script covering insertion, idempotency, advisory output, and line-ending handling.

Changes

AGENTS.md retrieval-discipline reflex

Layer / File(s)	Summary
Repair backfill helper and wiring scripts/repair.sh	Adds backfill_retrieval_discipline, which detects an existing marker or **Retrieval discipline heading, validates the template and ### P6/later heading anchors, extracts the paragraph, inserts it before the next section, verifies the staged marker, and calls the helper from the repair flow.
Doctor advisory check scripts/doctor.sh	Adds the AGENTS.md 4c advisory that reports the retrieval-discipline marker or heading and prints an informational missing message instead of a GAP.
Backfill scenarios tests/retrieval-discipline-backfill.test.sh	Sets up the pre-1426 workspace fixture and covers template preconditions, apply-all insertion, exact-once/idempotency checks, dry-run output, and the missing ### P6 anchor skip path.
Advisory and edge cases tests/retrieval-discipline-backfill.test.sh	Covers the reworded reflex variant, doctor.sh output and strict-mode behavior with and without the paragraph, CRLF/trailing-space heading matching, and the test summary output.

Sequence Diagram(s)

sequenceDiagram
  participant Repair as "scripts/repair.sh"
  participant Template as "AGENTS.md.template"
  participant Target as "AGENTS.md"
  Repair->>Template: extract Retrieval discipline paragraph
  Repair->>Target: verify P6/P7 anchors and existing marker
  Repair->>Target: insert paragraph into P6 and replace file

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• broomva/bstack#2: Adds the earlier P6 reflex checks in scripts/doctor.sh that this PR extends with a retrieval-discipline advisory.

Poem

I nibbled the P6 carrot with care 🐇
Found a retrieval trail shimmering there
repair.sh hopped in, neat and true
doctor.sh winked, “the reflex is through”
And AGENTS.md rustled, tidy and new

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: backfilling and auditing the P6 retrieval reflex in existing workspaces.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/bro-kg-reflex-propagation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[broomva]

Review fixes pushed (f9052f5):

[MAJOR] reworded-reflex duplication — resolved. Added a structural guard: repair now also treats ^**Retrieval discipline (the reflex's bold-lead signature) as present, so a reflex reworded to drop the substrate grep phrase isn't duplicated. doctor §4c matches the same two signals (phrase OR lead) so the two agree on "present". New Test 4b proves a reworded reflex survives --apply-all without duplication (lead count stays 1). Comment scoped to the true guarantee.

[MINOR] decoy/nested ### P6, last-section extraction — acknowledged as degenerate-input only (real template has one ### P6, no nested headings, ### P7 always follows); marker still lands so detection/idempotency hold. Left as documented limitations rather than hardening against malformed templates.

[NIT] interactive path — confirm() is shared verbatim with the philosophy backfill (covered); the new fn's ordering (dry-run → confirm → work) mirrors it. SHIP stands; 17/17 + sibling 17 + 5 canary green.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/retrieval-discipline-backfill.test.sh`:
- Around line 186-189: The reworded-doctor verification in
retrieval-discipline-backfill.test.sh is currently a no-op because it only
enters a placeholder branch when grep matches, so failures in doctor.sh
recognition are never asserted. Update the check around the doctor invocation to
use a real assertion tied to the existing doctor.sh and grep -q "has P6
retrieval-discipline reflex" logic, so the test fails when the reworded
**Retrieval discipline variant is not recognized and only passes when the
expected output is present.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ddd2094c-7ca8-4881-804b-44089519658a

📥 Commits

Reviewing files that changed from the base of the PR and between 903eb5e and f9052f5.

📒 Files selected for processing (3)

• scripts/doctor.sh
• scripts/repair.sh
• tests/retrieval-discipline-backfill.test.sh

[broomva]

Fixed in 8d3ccec — turned the no-op into a real assertion (doctor §4c recognizes the reworded reflex). Doing so surfaced a test-harness bug: doctor | grep -q under set -o pipefail returns doctor's non-zero exit (gappy fixture), not grep's — switched to capture-then-grep (the Test 5 pattern). Verified non-vacuous by mutation (break doctor's structural OR-clause → Test 4b fails; restore → passes). 18/18 green.