From ed42351b8624c09f6d229fef401f67966fd46c4f Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Mon, 1 Jun 2026 11:53:18 -0500 Subject: [PATCH 1/2] =?UTF-8?q?docs(0.23.1):=20P6=20reflex=20=E2=80=94=20a?= =?UTF-8?q?=20reflex,=20not=20a=20request,=20and=20never=20a=20question=20?= =?UTF-8?q?(BRO-1288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes the permission-to-document anti-pattern: agents asking "do you want me to file this into the knowledge graph?" instead of capturing autonomously. P6 already said "a reflex, not a request" but framed it as run-the-pipeline- unprompted — never forbade the interrogative form. Adds the third clause "and never a question" (file first, report after; user vetoes after via git revert, never gates before). Statement-tightening of P6, NOT a new primitive (same failure-mode class; respects L3 budget lambda3~=0.006; mirrors the 2026-05-29 PR-comment decision). Primitive count stays 20. Changed (canonical installable surfaces — propagate to every bstack install): - references/primitives.md: P6 reflex (trigger #4 + "Never a question") - assets/templates/AGENTS.md.template: same reflex tightening - assets/templates/CLAUDE.md.template: P6 invariant cell - VERSION 0.23.0 -> 0.23.1 + CHANGELOG Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 22 ++++++++++++++++++++++ VERSION | 2 +- assets/templates/AGENTS.md.template | 5 ++++- assets/templates/CLAUDE.md.template | 2 +- references/primitives.md | 7 +++++-- 5 files changed, 33 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 694200d..729ecc7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## 0.23.1 — 2026-06-01 + +### docs: P6 reflex tightening — "a reflex, not a request, **and never a question**" (BRO-1288) + +Closes the **permission-to-document anti-pattern**: agents asking *"do you want me to create an entry / file this into the knowledge graph?"* instead of capturing autonomously. + +The P6 reflex already said *"a reflex, not a request"* but every statement framed it as *run the `bookkeeping run` pipeline unprompted* — about the pipeline **invocation**, never the **capture act**. So an agent could honor "not a request" (didn't wait to be told to run the pipeline) while still gating *creation of the artifact* behind a user yes/no. Adds the third clause — **"and never a question"** — closing the interrogative leak. + +Statement-tightening of P6, **not** a new primitive (same failure-mode class; respects the L3 stability budget λ₃≈0.006; mirrors the 2026-05-29 PR-comment-resolution decision). **Primitive count stays 20.** + +### Changed + +- **`references/primitives.md`** — P6 Reflexive Trigger Rule: opening tightened to *"a reflex, not a request, and never a question"*; new trigger #4 (file discrete graph-worthy items proactively); a **"Never a question"** paragraph naming the permission-to-document anti-pattern. Capture stays bounded by the Nous gate (proactive ≠ indiscriminate). +- **`assets/templates/AGENTS.md.template`** — same P6 reflex tightening, so the rule propagates into every workspace `bstack` bootstraps. +- **`assets/templates/CLAUDE.md.template`** — P6 primitive-table invariant cell now states the proactive-capture rule. + +### Notes + +- No CLI/behavior change; documentation/governance only. Canary unaffected. +- `VERSION` 0.23.0 → 0.23.1. +- Workspace-side surfaces (`CLAUDE.md` §Ritual-vs-Substance, `AGENTS.md`, entity `pattern/proactive-documentation.md`, bstack-engine ledger) ship in the workspace repo PR for BRO-1288. + ## 0.23.0 — 2026-05-29 ### fix+feat: gitignore-aware, public-repo-aware, non-destructive bootstrap (issue #67) diff --git a/VERSION b/VERSION index ca222b7..610e287 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.23.0 +0.23.1 diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index dd21eb2..7c7465e 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -62,11 +62,14 @@ Each primitive carries a **short name** for agent prose. When referencing a prim **Invariant**: `research/entities/` never contains unscored items. All entity pages must pass lint. -**Reflexive Trigger Rule**: Bookkeeping is a reflex. Agents must invoke `bookkeeping.py run` without being prompted in any of these situations: +**Reflexive Trigger Rule**: Bookkeeping — and knowledge capture generally — is a reflex, not a request, **and never a question**. Agents must invoke `bookkeeping.py run` and file graph-worthy material without being prompted in any of these situations: 1. Before committing a feature/page that reads from the graph. 2. Before committing a synced snapshot to a public surface. 3. At the close of any substantial work session that produced graph-relevant material. +4. The moment a session surfaces a discrete graph-worthy item (a decision, name, discovered tool/person/paper, recurring pattern, or inferred typed relation) — file it proactively (entity page, `related:` edge, or synthesis note) and report what you filed in one line. + +**Never a question.** The interrogative form — *"do you want me to create an entry / file this into the knowledge graph?"* — is forbidden. Capture is the default action, not an opt-in the user approves; the agent files first and reports after (user vetoes after via `git revert`, never gates before). Deferring capture to a user yes/no is the **permission-to-document anti-pattern** — knowledge that waits for permission is knowledge lost. Capture stays bounded by the Nous gate (proactive ≠ indiscriminate). ### P7 — Freshness: Skill Freshness Check (Stale-Install Detector) diff --git a/assets/templates/CLAUDE.md.template b/assets/templates/CLAUDE.md.template index b6583c2..1baad54 100644 --- a/assets/templates/CLAUDE.md.template +++ b/assets/templates/CLAUDE.md.template @@ -19,7 +19,7 @@ Each primitive carries a **short name** for agent prose. When referencing a prim | P3 | **Tickets** — Linear Tickets | Every work unit tracked Backlog → Done | No significant work without a ticket | | P4 | **Pipeline** — PR Pipeline | Branch → PR → CI → merge → deploy | Never merge with failing checks | | P5 | **Fanout** — Parallel Agents | Concurrent isolated agents via worktrees | No shared mutable file writes | -| P6 | **Bookkeeping** — Knowledge Bookkeeping | `bookkeeping run` → score → promote → entity pages → synthesize | `research/entities/` never contains unscored items | +| P6 | **Bookkeeping** — Knowledge Bookkeeping | `bookkeeping run` → score → promote → entity pages → synthesize | `research/entities/` never contains unscored items; knowledge capture is a reflex, not a request, and **never a question** (file proactively, report after — never ask permission to document) | | P7 | **Freshness** — Skill Freshness Check | SessionStart hook → reports stale-skill nudge if last update check ≥ 7d ago | Never blocks; closes silent-rot bug for `npx skills add` snapshots | | P8 | **Janitor** — Branch + Worktree Janitor | `make janitor` → detects squash-merged branches + dead worktrees, removes safely | Default `--dry-run`; never touches protected branches | | P9 | **Wait** — Productive Wait (`broomva/p9` skill) | wait-queue drains while a blocking operation runs (PR CI is the reference impl: `gh pr checks --watch` via `run_in_background` → classifier + evaluator self-heal). For non-PR waits (push-triggered deploys, builds), do a single direct check after kicking off next-priority work. | Never `sleep` on a blocking wait; merge defers to control metalayer | diff --git a/references/primitives.md b/references/primitives.md index c09139b..f877e65 100644 --- a/references/primitives.md +++ b/references/primitives.md @@ -112,13 +112,16 @@ Each primitive carries a **short name** for use in agent prose. When referencing ### P6 Reflexive Trigger Rule (binding on every agent) -Bookkeeping is a reflex, not a request. Agents must invoke `bookkeeping.py run` without being prompted in any of these situations: +Bookkeeping — and knowledge capture generally — is a reflex, not a request, **and never a question**. Agents must invoke `bookkeeping.py run` and file graph-worthy material without being prompted in any of these situations: 1. Before committing a feature or page that *reads from* the graph (anything consuming `~/.config/bookkeeping/status.json`, `research/entities/`, or a `public/data/bookkeeping.json` snapshot — the data must be fresh at commit time). 2. Before committing a synced snapshot to a public surface (e.g., `apps/*/public/data/bookkeeping.json`). 3. At the close of any substantial work session that produced graph-relevant material (new names, decisions, concepts, partnerships, threads, design debates). +4. The moment a session surfaces a discrete graph-worthy item (a decision, a name, a discovered tool/person/paper, a recurring pattern, a typed relation inferred between entities) — file it proactively (entity page, `related:` edge, or synthesis note) **as part of the work** and report what you filed in one line. Do **not** ask the user whether to record it. -Mental checklist before declaring graph-dependent work done: *Did this session produce material that belongs in the graph? Does my feature read graph state? Am I about to commit a snapshot?* — yes to any → run bookkeeping. +**Never a question.** The interrogative form — *"do you want me to create an entry / file this into the knowledge graph?"* — is forbidden. Capture is the default action, not an opt-in the user approves; the agent files first and reports after, so the user vetoes *after* (cheap: `git revert` / delete the entity), never gates *before*. Surfacing graph-worthy material and then deferring its capture to a user yes/no is the **permission-to-document anti-pattern**: knowledge that waits for permission is knowledge lost. (Capture stays bounded by the Nous gate — proactive ≠ indiscriminate; low-confidence inferences go to a synthesis note, not a committed entity.) + +Mental checklist before declaring graph-dependent work done: *Did this session produce material that belongs in the graph? Does my feature read graph state? Am I about to commit a snapshot?* — yes to any → file it / run bookkeeping, without asking. --- From dbb54fccc84a0da3410bfba5fb9f1e6ac96441a6 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Mon, 1 Jun 2026 12:02:40 -0500 Subject: [PATCH 2/2] =?UTF-8?q?docs(0.23.1):=20P20=20review=20follow-up=20?= =?UTF-8?q?=E2=80=94=20add=20sensitive-material=20carve-out=20to=20P6=20re?= =?UTF-8?q?flex=20(BRO-1288)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit P20 cross-review flagged the rule "reads as unconditional". Adds the two bounds to references/primitives.md "Never a question": (a) Nous-gate (low-confidence → synthesis note), (b) explicit do-not-record / sensitive-material override — the only withholding cases; agent withholds silently, never asks permission. Co-Authored-By: Claude Opus 4.8 (1M context) --- references/primitives.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/references/primitives.md b/references/primitives.md index f877e65..f3145ff 100644 --- a/references/primitives.md +++ b/references/primitives.md @@ -119,7 +119,7 @@ Bookkeeping — and knowledge capture generally — is a reflex, not a request, 3. At the close of any substantial work session that produced graph-relevant material (new names, decisions, concepts, partnerships, threads, design debates). 4. The moment a session surfaces a discrete graph-worthy item (a decision, a name, a discovered tool/person/paper, a recurring pattern, a typed relation inferred between entities) — file it proactively (entity page, `related:` edge, or synthesis note) **as part of the work** and report what you filed in one line. Do **not** ask the user whether to record it. -**Never a question.** The interrogative form — *"do you want me to create an entry / file this into the knowledge graph?"* — is forbidden. Capture is the default action, not an opt-in the user approves; the agent files first and reports after, so the user vetoes *after* (cheap: `git revert` / delete the entity), never gates *before*. Surfacing graph-worthy material and then deferring its capture to a user yes/no is the **permission-to-document anti-pattern**: knowledge that waits for permission is knowledge lost. (Capture stays bounded by the Nous gate — proactive ≠ indiscriminate; low-confidence inferences go to a synthesis note, not a committed entity.) +**Never a question.** The interrogative form — *"do you want me to create an entry / file this into the knowledge graph?"* — is forbidden. Capture is the default action, not an opt-in the user approves; the agent files first and reports after, so the user vetoes *after* (cheap: `git revert` / delete the entity), never gates *before*. Surfacing graph-worthy material and then deferring its capture to a user yes/no is the **permission-to-document anti-pattern**: knowledge that waits for permission is knowledge lost. Two bounds keep this safe rather than spammy: (a) capture is gated by the Nous score (proactive ≠ indiscriminate — low-confidence inferences go to a synthesis note, not a committed entity); (b) an explicit standing instruction not to record, or material the agent treats as sensitive/private, overrides the default — the *only* withholding cases, and the agent withholds *silently* (never by asking permission to document). Mental checklist before declaring graph-dependent work done: *Did this session produce material that belongs in the graph? Does my feature read graph state? Am I about to commit a snapshot?* — yes to any → file it / run bookkeeping, without asking.