docs(0.23.1): P6 reflex — a reflex, not a request, and never a question (BRO-1288)

[broomva]

Problem

Agents repeatedly ask "do you want me to create an entry / file this into the knowledge graph?" instead of capturing proactively. bstack should define autonomous documentation by default in every workspace it installs into.

Diagnosis

P6 already said "Bookkeeping is a reflex, not a request" — but every statement framed it as run the bookkeeping run pipeline unprompted (the pipeline invocation), never the capture act. So an agent could honor "not a request" while still gating creation of the artifact behind a user yes/no. The fix adds the third clause: "a reflex, not a request — and never a question."

Classification — statement-tightening, not a new primitive

Same failure-mode class P6 owns; states it sharply enough to catch the interrogative form. Respects the L3 stability budget (λ₃≈0.006); mirrors the 2026-05-29 PR-comment decision. Primitive count stays 20 (no Self-Documenting-Standards drift).

Changes (canonical installable surfaces)

File	Change
references/primitives.md	P6 Reflexive Trigger Rule — trigger #4 (file discrete graph-worthy items proactively) + "Never a question" paragraph naming the permission-to-document anti-pattern
assets/templates/AGENTS.md.template	same P6 reflex tightening — propagates into every workspace bstack bootstraps
assets/templates/CLAUDE.md.template	P6 invariant cell states the proactive-capture rule
VERSION	0.23.0 → 0.23.1
CHANGELOG.md	0.23.1 entry

Capture stays bounded by the Nous gate (proactive ≠ indiscriminate) — low-confidence inferences still go to a synthesis note, not a committed entity.

Scope notes

• Only tracked canonical surfaces edited. The repo's root AGENTS.md/CLAUDE.md are untracked self-dogfood artifacts (bootstrapped from the templates) — intentionally left alone.
• No CLI/behavior change; documentation/governance only.
• Workspace-side surfaces ship in the paired workspace-repo PR (broomva/workspace#111).

Validation

• No primitive-count drift (stays 20)
• Templates unchanged in structure (prose-only additions)
• P20 cross-model adversarial review pending before merge

Closes part of BRO-1288.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated knowledge capture governance rules to clarify that knowledge capture is a reflexive action—never phrased as a question—with explicit guidance on trigger conditions and reporting procedures.

• Chores

  • Version bump to 0.23.1.

[linear]

BRO-1288

[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 51 minutes and 14 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ 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.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b72af710-7e6f-4095-a783-dc5ed06a077a

📥 Commits

Reviewing files that changed from the base of the PR and between ed42351 and dbb54fc.

📒 Files selected for processing (1)

• references/primitives.md

📝 Walkthrough

Walkthrough

Version 0.23.1 tightens the P6 "Reflexive Trigger Rule" across documentation and workspace templates by adding explicit "never a question" constraints and expanded proactive capture guidance. The version and changelog are updated, and the core rule is propagated through reference and template files with consistent messaging about knowledge-graph capture as a reflex rather than an interrogative choice.

Changes

P6 Reflex Rule Tightening Release

Layer / File(s)	Summary
Release version and changelog VERSION, CHANGELOG.md	Version bumped to 0.23.1 documenting the P6 reflex tightening as governance-only with no CLI/behavior impact, including the affected files and change rationale.
P6 Reflex Rule tightening across references and templates references/primitives.md, assets/templates/AGENTS.md.template, assets/templates/CLAUDE.md.template	Core P6 Reflexive Trigger Rule in primitives.md is expanded to forbid "never a question" phrasing and enumerate proactive capture triggers; the tightened rule is propagated through AGENTS and CLAUDE templates with consistent constraints about knowledge filing and reporting without seeking permission.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• bstack P6 tightening: documentation is a reflex, not a request — and never a question life#1497: Directly related; both tighten the P6 "reflex" wording by adding "never a question" and update the same documentation artifacts (CHANGELOG, VERSION, references/primitives.md, assets/templates/AGENTS.md.template, assets/templates/CLAUDE.md.template).

Poem

🐰 A reflex, not a question posed—
Knowledge captured, truth enclosed,
Primitives refined with care,
P6's path made crystal clear.
From templates wide to rules refined,
A tighter grip on thought designed. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: documenting the tightened P6 reflex rule with the added constraint 'never a question,' and includes the version bump context and ticket reference.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/bro-1288-p6-doc-reflex

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@CHANGELOG.md`:
- Line 3: The release header "## 0.23.1 — 2026-06-01" must match the exact
validator format; change that heading to "## 0.23.1" and move the date
"2026-06-01" onto the next line (e.g., as plain text or a separate subheading),
ensuring the header exactly equals "## 0.23.1" so the release validator can
locate the section.

In `@VERSION`:
- Line 1: The VERSION file contains hidden/byte-order-mark characters causing
semver validation to fail; open the VERSION file and rewrite it as a single
plain ASCII token "0.23.1" with no BOM or hidden bytes and a trailing newline
(e.g., re-save with a plain-text editor or run a text-level rewrite such as
printf '0.23.1\n' > VERSION) so the file contains only the ASCII token 0.23.1
and nothing else.

🪄 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: a253a4dd-10bb-495d-ba51-2d9e9895ea9b

📥 Commits

Reviewing files that changed from the base of the PR and between ec27482 and ed42351.

📒 Files selected for processing (5)

• CHANGELOG.md
• VERSION
• assets/templates/AGENTS.md.template
• assets/templates/CLAUDE.md.template
• references/primitives.md

[broomva]

Re: CodeRabbit threads on CHANGELOG.md and VERSION — rejected with reason (false positives).

Both flag a speculative format mismatch with the release validator. Verified against ground truth — both are incorrect:

1. CHANGELOG.md heading — ## 0.23.1 — 2026-06-01 matches the exact established convention; every prior release uses ## X.Y.Z — DATE (## 0.23.0 — 2026-05-29, ## 0.22.0 — 2026-05-28, ## 0.21.10 — 2026-05-27, …). CodeRabbit's proposed ## 0.23.1 + separate date line would break convention, not satisfy it.
2. VERSION — bytes are 30 2e 32 33 2e 31 0a = 0.23.1\n (standard single trailing newline), identical in shape to the prior 0.23.0.

The authoritative check is CI, not a guessed format: VERSION ↔ CHANGELOG match = pass and bstack doctor = pass on HEAD. CodeRabbit pattern-matched the validator without running it. Resolving both threads as no-change.