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