feat(p5): add why-bypure architecture rationale#23
Open
rocklambros wants to merge 1 commit into
Open
Conversation
P5 followup. Authors docs/explanation/why-bypure.md — the short-form explanation of CSCR's B-pure architecture decision for readers who don't want to walk the full decision lineage in the design spec. Structure: - One-sentence thesis up front (no executable enforcement code ships; the reasons follow) - "The pattern that forced B-pure" — the model-controlled-bypass loop that any executable-shipping architecture recreates, with the 93% approval rate (Hughes 2026) named as the load-bearing user-side number - "What B-pure ships" — three inert components (skills, template, docs) - "What B-pure does NOT ship" — no CLIs, no installers, no state files, no upgrade mechanism, no telemetry - "The costs" — six honest tradeoffs, including the cognitive burden shifted to users and the fact that skills are advisory full stop - "What B-pure is NOT" — three things this architecture choice does not claim (hooks unsafe; only safe option; refusal to evolve) - "When to read this document" — four trigger conditions - Related reading — six cross-references to the spec and the other explanation/how-to docs The doc explicitly addresses (and rejects) the "but co-signing / sigstore / runtime attestation would make a hook-shipping architecture safe" objection by acknowledging it could but pointing out it requires distribution infrastructure CSCR doesn't have AND adds friction users wouldn't accept. Closes the explanation/ trio (this + enforcement-coverage.md). The full public-facing P5 doc set is now: settings-template.json, merge-settings-template.md, write-your-own-hook.md, verify-the-release.md, enforcement-coverage.md, why-bypure.md.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new short-form explanation document describing CSCR’s “B-pure” architecture decision (shipping no executable enforcement code) and the tradeoffs of that approach, intended as a companion to the longer design-spec lineage.
Changes:
- Adds
docs/explanation/why-bypure.mddescribing the model-controlled-bypass rationale for B-pure - Documents what B-pure ships vs. explicitly does not ship
- Enumerates tradeoffs/costs and links to related reading
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| Three things, all inert: | ||
|
|
||
| 1. **Skills catalog** — ~42 path-scoped markdown files under `skills/`. Each loads when the user's working directory matches its `paths:` glob. Each teaches the model about secure patterns in its domain. **No skill can deny a tool call.** Skills shape the model's output; they do not gate it. |
Comment on lines
+31
to
+38
| 2. **Permission-rule template** — `settings-template.json`. A static JSON file enumerating ~24 deny rules. The user runs `jq -s '.[0] * .[1]'` (or merges manually in an editor) to add the rules to their own `~/.claude/settings.json`. The platform's permission system enforces the rules. **CSCR does not run the merge.** The user owns the file at all times. | ||
|
|
||
| 3. **Hook-authoring documentation** — `docs/how-to/write-your-own-hook.md`. ~11 hook patterns in markdown fenced code blocks. Each pattern has full Python source, settings.json snippet, enumerated bypass classes, and pytest suite. The user reads, picks, copies, and tests. **CSCR ships no `.py` hook files.** | ||
|
|
||
| ## What B-pure does NOT ship | ||
|
|
||
| - No `cscr` CLI of any kind. No `cscr hooks install`. No `cscr-configure`. No `cscr-verify` (sigstore verification is done by the user calling sigstore directly per `docs/how-to/verify-the-release.md`). | ||
| - No installer for the settings template. The user runs `jq` or their editor. |
Comment on lines
+31
to
+33
| 2. **Permission-rule template** — `settings-template.json`. A static JSON file enumerating ~24 deny rules. The user runs `jq -s '.[0] * .[1]'` (or merges manually in an editor) to add the rules to their own `~/.claude/settings.json`. The platform's permission system enforces the rules. **CSCR does not run the merge.** The user owns the file at all times. | ||
|
|
||
| 3. **Hook-authoring documentation** — `docs/how-to/write-your-own-hook.md`. ~11 hook patterns in markdown fenced code blocks. Each pattern has full Python source, settings.json snippet, enumerated bypass classes, and pytest suite. The user reads, picks, copies, and tests. **CSCR ships no `.py` hook files.** |
|
|
||
| ## What B-pure does NOT ship | ||
|
|
||
| - No `cscr` CLI of any kind. No `cscr hooks install`. No `cscr-configure`. No `cscr-verify` (sigstore verification is done by the user calling sigstore directly per `docs/how-to/verify-the-release.md`). |
|
|
||
| - No `cscr` CLI of any kind. No `cscr hooks install`. No `cscr-configure`. No `cscr-verify` (sigstore verification is done by the user calling sigstore directly per `docs/how-to/verify-the-release.md`). | ||
| - No installer for the settings template. The user runs `jq` or their editor. | ||
| - No state files outside the user's own config. CSCR's surface area in the filesystem after install is exactly the skills directory and the template JSON, both of which the user can `rm` without consequence to anything CSCR controls. |
Comment on lines
+76
to
+79
| - `docs/explanation/enforcement-coverage.md` — what each Layer 1 deny rule and Layer 2 hook actually covers, with enumerated bypass classes. | ||
| - `docs/how-to/merge-settings-template.md` — the manual-merge guide for the permission template. | ||
| - `docs/how-to/write-your-own-hook.md` — the 11 hook patterns the user can copy. | ||
| - `docs/how-to/verify-the-release.md` — sigstore verification (user calls sigstore directly; no CSCR-shipped verifier). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
P5 followup deliverable. New file
docs/explanation/why-bypure.md— the short-form explanation of CSCR's B-pure architecture decision for readers who don't want to walk the full premortem lineage in the design spec.Thesis: Every architecture that ships CSCR-authored executable hooks recreates the model-controlled-bypass problem. Three rounds of premortem on three different architectures all surfaced 5+ Critical findings on the same root cause. B-pure was the first to survive cleanly.
Structure
Notable framing decisions worth flagging
sed -i-removed; B-pure just removes the high-confidence CSCR-said-so social signal from the suggestion.Test plan
Level: strictdecoration language reintroduced (per the v1 vocabulary retirement)Reviewer
@fewdisc — this is the explanation/ companion to
enforcement-coverage.md(PR #22). Together they form the rationale-and-coverage pair. Worth checking:Related
enforcement-coverage.md) — the catalog this doc explains the existence of