feat(0.24.0): scaffold Development Philosophy into AGENTS.md/CLAUDE.md on install (BRO-1406)

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.24.0 — 2026-06-05
+
+### feat: scaffold a Development Philosophy section into AGENTS.md/CLAUDE.md on install (BRO-1406)
+
+`bstack bootstrap` now scaffolds a **Development Philosophy** section into a new workspace's `AGENTS.md` (full section) and `CLAUDE.md` (anchor). It states four guiding principles — Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution — and backs each with the primitive(s) that hold it: Think→P14+P15, Simplicity→P20, Surgical→P14+P20, Goal-Driven→P11+P19, with a note that enforcement strength varies (P14/P15 are hard predicates; P20 is a judgment gate). Previously the scaffold deployed the primitive contract without this stated intent.
+
+### Changed
+
+- **`assets/templates/AGENTS.md.template`** — new `## Development Philosophy` section between Self-Meta Definition and the primitives table (so the *why* frames the *how*): 4-principle → backing-primitive table, the binding Ritual-vs-Substance rule, and an explicit invitation to extend it with project-specific principles.
+- **`assets/templates/CLAUDE.md.template`** — short philosophy anchor after Identity, linking to `AGENTS.md#development-philosophy`.
+- **`references/new-workspace-flow.md`** — deployed-files table note updated to describe the philosophy section.
+
+### Notes
+
+- **No code change** in `scripts/bootstrap.sh` — Phase 2 (`scaffold_governance_file`) copies whatever the templates hold. Idempotent-never-overwrite: **new** installs get the section automatically; existing workspaces are unaffected (backfill is the deferred `bstack doctor`/`repair` next step).
+- **Not a new primitive.** Primitive count stays **20**. This is governance-substrate content, not a P-row — respects the L3 stability budget (λ₃≈0.006).
+- Companion KG artifact (workspace repo, not this repo): `research/entities/tool/karpathy-claude-md-guidelines.md` documents the lineage + the principle→primitive mapping.
+- `VERSION` 0.23.2 → 0.24.0.
+- **Deferred:** (1) a `bstack doctor` check that lints for the section (makes it contract-enforced + lets `repair` backfill existing workspaces); (2) dogfood into bstack's own root governance + `~/broomva`.
+
 ## 0.23.2 — 2026-06-04
 
 ### docs: README sync to current contract + bench surfaced + P11 cross-reference (BRO-1376)

VERSION

@@ -1 +1 @@
-0.23.2
+0.24.0

assets/templates/AGENTS.md.template

@@ -6,6 +6,27 @@ This file IS the control harness for agents operating in this workspace. Reading
 
 **If you are an agent reading this**: you are part of a self-improving system. Your session will be captured, indexed, and used to improve future agents. The bstack consciousness substrate is always active.
 
+## Development Philosophy
+
+Before the twenty primitives below — which are the *mechanism* — these four principles are the *intent*. They are widely-recognized engineering disciplines, articulated sharply in Andrej Karpathy's observations on where LLM-assisted coding goes wrong. bstack's contribution is to make each one **machine-checkable** instead of a hopeful instruction: a principle that lives only as prose decays into ritual — acknowledged in passing, then ignored. Each principle below therefore names the primitive(s) that back it.
+
+| Principle | What it means | Failure it prevents | Backed by |
+|---|---|---|---|
+| **1. Think before coding** | Surface assumptions and trade-offs *before* writing. Trace what the change depends on and what depends on it. Ask only for what you genuinely cannot derive from the repo. | Hidden assumptions — confidently building the wrong thing. | **Dep-Chain (P14)** + **Snapshot (P15)** |
+| **2. Simplicity first** | Deliver the minimal change that solves the actual problem. No speculative features, no premature abstraction, no scope creep. | Overcomplication — code nobody asked for, harder to maintain than the problem warranted. | **Cross-Review (P20)** anti-slop gate |
+| **3. Surgical changes** | Change only what the task requires. Match the surrounding style. Don't refactor tangentially or reformat untouched lines. | Unintended edits — diffs that touch more than they should, hiding the real change and breaking unrelated things. | **Dep-Chain (P14)** (enumerating what's touched bounds the change surface) + **Cross-Review (P20)** (flags tangential edits / scope creep) |
+| **4. Goal-driven execution** | Define measurable success criteria up front, then loop — building and *verifying by interaction* — until they are met. | No verifiable "done" — work that *looks* complete without evidence it works. | **Empirical (P11)** (interaction evidence for "done") + **Orchestrate (P19)** (the verify-until-met loop) |
+
+**Enforcement strength varies by principle, and that is the point.** P14/P15 are *hard predicates* — a checker reads the response for a dependency enumeration / state snapshot. P20 is an *independent-judgment* gate that blocks a merge below threshold. Both beat prose, because in neither case is the agent the one grading itself — but only the first kind is a literal yes/no predicate. The goal is to push each principle as far down the gradient toward a hard predicate as it will go.
+
+The binding rule across all four:
+
+> **A discipline that recurs as a phrase must map to a concrete, machine-checkable behavior — or it does not count as discipline.**
+
+"Think deeply", "follow best practices", "keep it simple", "make sure it works" are *rituals* until they produce a concrete artifact: a dependency enumeration, a state snapshot, a minimal diff, an interaction receipt. The primitives below are how this workspace converts each principle from intention into enforced behavior.
+
+**This philosophy is yours to extend.** Add project-specific principles to this section so every agent and contributor inherits them by default; the primitives stay the enforcement layer beneath whatever principles you declare here.
+
 ## Bstack Core Automation Primitives
 
 This workspace is governed by the **bstack** primitive contract — twenty irreducible building blocks. All are always active. Run `bstack doctor` to verify compliance.

assets/templates/CLAUDE.md.template

@@ -4,6 +4,10 @@
 
 This workspace is governed by **bstack** — twenty irreducible primitives (P1–P20) that turn an agent-driven workspace into a self-operating system. The full primitive contract lives in [AGENTS.md](AGENTS.md). Run `bstack doctor` to verify compliance.
 
+## Development Philosophy
+
+Four principles govern every change in this workspace — *think before coding · simplicity first · surgical changes · goal-driven execution*. They are widely-recognized engineering disciplines (sharpened by Andrej Karpathy's observations on LLM coding pitfalls); bstack's job is to make each one **machine-checkable** rather than a hopeful instruction, because a discipline that lives only as prose decays into ritual. Each principle is backed by the primitive(s) that hold it — see [AGENTS.md § Development Philosophy](AGENTS.md#development-philosophy) for the full mapping (and a note on why enforcement strength varies). Extend it with project-specific principles; the primitives stay the enforcement layer.
+
 ## Bstack Core Automation Primitives
 
 Twenty irreducible building blocks that make this workspace self-operating. All are always active. Full specification in `AGENTS.md`.

references/new-workspace-flow.md

@@ -17,7 +17,7 @@ Both paths wire the RCS control loop. `bootstrap.sh` scaffolds governance files
 
 | Path | Source | Purpose |
 |---|---|---|
-| `CLAUDE.md`, `AGENTS.md`, `.control/policy.yaml`, `METALAYER.md` | `assets/templates/*.template` | Governance substrate (P-row primitives table, reflexive trigger rules, gate config) |
+| `CLAUDE.md`, `AGENTS.md`, `.control/policy.yaml`, `METALAYER.md` | `assets/templates/*.template` | Governance substrate (Development Philosophy section, P-row primitives table, reflexive trigger rules, gate config). The philosophy section states the four guiding principles (think-before-coding · simplicity-first · surgical-changes · goal-driven) and backs each with the primitive(s) that hold it, so downstream development inherits the *intent* behind the primitives — and the user can extend it with project-specific principles. |
 | `.control/arcs.yaml` | `arcs.yaml.template` | Closure-contract arcs — the workspace's own editable loop definitions (5-tuple). Scaffolded by `bootstrap.sh` Phase 2 |
 | `.githooks/pre-commit` | `githook-pre-commit-l3-rate.sh.template` | G1 — blocks `git commit` over τ_a₃ L3 commit rate (bypassable with `--no-verify`) |
 | `.github/workflows/l3-stability.yml` | `gh-workflow-l3-stability.yml.template` | G2 — runs `compute-lambda` + `l3-rate-gate` on every PR touching L3 paths; comments verdict |