From 78011c72a00348c5e7d3904ca2167f55dfcd1a35 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Fri, 5 Jun 2026 09:34:41 -0500 Subject: [PATCH 1/4] feat(0.24.0): scaffold Development Philosophy into AGENTS.md/CLAUDE.md on install (BRO-1406) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every newly-bootstrapped workspace now inherits an explicit Development Philosophy — four guiding principles, each bound to the primitive that enforces it — so downstream development follows the philosophy by default, cohesively with the user's own project. Previously the scaffold deployed the mechanism (P1–P20) without the intent. The four principles (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution) are sharpened by Karpathy's LLM-coding- pitfall observations; bstack's edge is the Ritual-vs-Substance rule — each principle is bound to its enforcing primitive (Think→P14+P15, Simplicity→P20, Surgical→P10, Goal-Driven→P11+P19). - AGENTS.md.template: new ## Development Philosophy section (4-principle → enforcing-primitive table + Ritual-vs-Substance rule + extend-it invite), placed before the primitives table so the why frames the how. - CLAUDE.md.template: short philosophy anchor → AGENTS.md#development-philosophy. - references/new-workspace-flow.md: deployed-files note updated. - No bootstrap.sh change (Phase 2 copies templates verbatim). Primitive count unchanged (20); governance-substrate content, not a P-row. Verified: fresh scaffold into a temp repo produces the section in both files with WORKSPACE_NAME substituted. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 22 ++++++++++++++++++++++ VERSION | 2 +- assets/templates/AGENTS.md.template | 19 +++++++++++++++++++ assets/templates/CLAUDE.md.template | 4 ++++ references/new-workspace-flow.md | 2 +- 5 files changed, 47 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 156f64f..8bbd03c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # Changelog +## 0.24.0 — 2026-06-05 + +### feat: scaffold a Development Philosophy section into AGENTS.md/CLAUDE.md on install (BRO-1406) + +Every newly-bootstrapped workspace now inherits an explicit **Development Philosophy** — four guiding principles, each bound to the primitive that enforces it — so downstream development follows the philosophy by default, cohesively with the user's own project. Previously the scaffold deployed the *mechanism* (the P1–P20 contract) without the *intent*; new repos got the "how" with no "why". + +The four principles (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution) are the disciplines every good engineer recognizes, articulated sharply in Andrej Karpathy's observations on LLM-coding pitfalls (the most-starred public CLAUDE.md, `multica-ai/andrej-karpathy-skills`, ~168k★, proves the demand). bstack's contribution is the **Ritual-vs-Substance** rule: a principle that lives only as prose decays into ritual, so each is bound to its enforcing primitive — Think→Dep-Chain (P14)+Snapshot (P15); Simplicity→Cross-Review (P20); Surgical→Hygiene (P10); Goal-Driven→Empirical (P11)+Orchestrate (P19). + +### 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 → enforcing-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) diff --git a/VERSION b/VERSION index fda96dc..2094a10 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.23.2 +0.24.0 diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index 7c7465e..741b306 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -6,6 +6,25 @@ 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 the disciplines every good engineer already recognizes, 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 that enforces it. + +| Principle | What it means | Failure it prevents | Enforced 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 (+ `/simplify`) | +| **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. | **Hygiene (P10)** clean-tree discipline | +| **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)** + **Orchestrate (P19)** `/goal` | + +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. diff --git a/assets/templates/CLAUDE.md.template b/assets/templates/CLAUDE.md.template index 1baad54..72126e2 100644 --- a/assets/templates/CLAUDE.md.template +++ b/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 universal good-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 bound to the primitive that enforces it — see [AGENTS.md § Development Philosophy](AGENTS.md#development-philosophy) for the full mapping. 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`. diff --git a/references/new-workspace-flow.md b/references/new-workspace-flow.md index fc477eb..37afc7e 100644 --- a/references/new-workspace-flow.md +++ b/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 binds each to its enforcing primitive, 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 | From 898764a9f9a7e9e5fb66df198a9b015c0c4891cd Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Fri, 5 Jun 2026 10:07:31 -0500 Subject: [PATCH 2/4] fix(P20 round 1): accurate primitive backing + honest enforcement gradient + de-hype changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-review (Codex, Strata A) blocked 4/10. Fixes: - drop undefined /simplify ref (not a primitive) - Surgical→Hygiene(P10)+Cross-Review(P20), not P10 alone (P10 is clean-tree, not no-tangential-refactor) - Goal-driven→Empirical(P11)+Orchestrate(P19), drop bare /goal pin (one cube cell, not the enforcer) - column 'Enforced by'→'Backed by' + explicit enforcement-strength-varies note (hard predicate vs judgment gate) - de-hyped CHANGELOG + template intro (drop 'every good engineer'/'proves the demand') Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 4 ++-- assets/templates/AGENTS.md.template | 12 +++++++----- assets/templates/CLAUDE.md.template | 2 +- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bbd03c..8156434 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,9 @@ ### feat: scaffold a Development Philosophy section into AGENTS.md/CLAUDE.md on install (BRO-1406) -Every newly-bootstrapped workspace now inherits an explicit **Development Philosophy** — four guiding principles, each bound to the primitive that enforces it — so downstream development follows the philosophy by default, cohesively with the user's own project. Previously the scaffold deployed the *mechanism* (the P1–P20 contract) without the *intent*; new repos got the "how" with no "why". +Every newly-bootstrapped workspace now inherits an explicit **Development Philosophy** — four guiding principles, each backed by the primitive(s) that hold it — so downstream development follows the philosophy by default, alongside the user's own project conventions. Previously the scaffold deployed the primitive contract (the *mechanism*) without its stated *intent*. -The four principles (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution) are the disciplines every good engineer recognizes, articulated sharply in Andrej Karpathy's observations on LLM-coding pitfalls (the most-starred public CLAUDE.md, `multica-ai/andrej-karpathy-skills`, ~168k★, proves the demand). bstack's contribution is the **Ritual-vs-Substance** rule: a principle that lives only as prose decays into ritual, so each is bound to its enforcing primitive — Think→Dep-Chain (P14)+Snapshot (P15); Simplicity→Cross-Review (P20); Surgical→Hygiene (P10); Goal-Driven→Empirical (P11)+Orchestrate (P19). +The four principles (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution) are widely-recognized engineering disciplines, articulated sharply in Andrej Karpathy's observations on LLM-coding pitfalls; the most-starred public CLAUDE.md, `multica-ai/andrej-karpathy-skills` (~168k★), applies the same four. bstack's contribution is the **Ritual-vs-Substance** rule: a principle that lives only as prose decays into ritual, so each is backed by a primitive — Think→Dep-Chain (P14)+Snapshot (P15); Simplicity→Cross-Review (P20); Surgical→Hygiene (P10)+Cross-Review (P20); Goal-Driven→Empirical (P11)+Orchestrate (P19). Enforcement strength varies (P14/P15 are hard predicates; P20 is an independent-judgment gate) — both beat prose because the agent never grades itself. ### Changed diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index 741b306..db31725 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -8,14 +8,16 @@ This file IS the control harness for agents operating in this workspace. Reading ## Development Philosophy -Before the twenty primitives below — which are the *mechanism* — these four principles are the *intent*. They are the disciplines every good engineer already recognizes, 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 that enforces it. +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 | Enforced by | +| 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 (+ `/simplify`) | -| **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. | **Hygiene (P10)** clean-tree discipline | -| **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)** + **Orchestrate (P19)** `/goal` | +| **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. | **Hygiene (P10)** (keeps the diff an isolated, reviewable unit) + **Cross-Review (P20)** (flags 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: diff --git a/assets/templates/CLAUDE.md.template b/assets/templates/CLAUDE.md.template index 72126e2..c07a6b0 100644 --- a/assets/templates/CLAUDE.md.template +++ b/assets/templates/CLAUDE.md.template @@ -6,7 +6,7 @@ This workspace is governed by **bstack** — twenty irreducible primitives (P1 ## Development Philosophy -Four principles govern every change in this workspace — *think before coding · simplicity first · surgical changes · goal-driven execution*. They are universal good-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 bound to the primitive that enforces it — see [AGENTS.md § Development Philosophy](AGENTS.md#development-philosophy) for the full mapping. Extend it with project-specific principles; the primitives stay the enforcement layer. +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 From bb1d13135d29cb8d1bbc883b0df852c13f2eedc2 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Fri, 5 Jun 2026 10:10:36 -0500 Subject: [PATCH 3/4] =?UTF-8?q?fix(P20=20round=202):=20Surgical=E2=86=92P1?= =?UTF-8?q?4+P20=20(drop=20P10=20overclaim)=20+=20terse=20changelog?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-review round 2 (Codex) 6/10 BLOCK on two residuals: - (b) Surgical→Hygiene(P10) still overclaimed (P10 = tree cleanliness, not diff scope) → remap to Dep-Chain(P14) bounds-the-surface + Cross-Review(P20) flags- tangential-edits; drop P10 from the row. - (d) CHANGELOG still advocacy copy → tightened to terse release-note prose (dropped 'widely-recognized', star count; rationale reduced to one cf. line). + aligned residual 'enforcing'→'backing' wording (changelog bullet, flow doc). Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 6 +++--- assets/templates/AGENTS.md.template | 2 +- references/new-workspace-flow.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8156434..30aa72b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,13 +4,13 @@ ### feat: scaffold a Development Philosophy section into AGENTS.md/CLAUDE.md on install (BRO-1406) -Every newly-bootstrapped workspace now inherits an explicit **Development Philosophy** — four guiding principles, each backed by the primitive(s) that hold it — so downstream development follows the philosophy by default, alongside the user's own project conventions. Previously the scaffold deployed the primitive contract (the *mechanism*) without its stated *intent*. +`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. A note records that enforcement strength varies (P14/P15 are hard predicates; P20 is a judgment gate) — both beat prose because the agent never grades itself. -The four principles (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution) are widely-recognized engineering disciplines, articulated sharply in Andrej Karpathy's observations on LLM-coding pitfalls; the most-starred public CLAUDE.md, `multica-ai/andrej-karpathy-skills` (~168k★), applies the same four. bstack's contribution is the **Ritual-vs-Substance** rule: a principle that lives only as prose decays into ritual, so each is backed by a primitive — Think→Dep-Chain (P14)+Snapshot (P15); Simplicity→Cross-Review (P20); Surgical→Hygiene (P10)+Cross-Review (P20); Goal-Driven→Empirical (P11)+Orchestrate (P19). Enforcement strength varies (P14/P15 are hard predicates; P20 is an independent-judgment gate) — both beat prose because the agent never grades itself. +Rationale: the scaffold previously deployed the primitive contract without its stated intent. The four principles follow Andrej Karpathy's observations on LLM-coding pitfalls (cf. `multica-ai/andrej-karpathy-skills`). ### 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 → enforcing-primitive table, the binding Ritual-vs-Substance rule, and an explicit invitation to extend it with project-specific principles. +- **`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. diff --git a/assets/templates/AGENTS.md.template b/assets/templates/AGENTS.md.template index db31725..22af6dc 100644 --- a/assets/templates/AGENTS.md.template +++ b/assets/templates/AGENTS.md.template @@ -14,7 +14,7 @@ Before the twenty primitives below — which are the *mechanism* — these four |---|---|---|---| | **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. | **Hygiene (P10)** (keeps the diff an isolated, reviewable unit) + **Cross-Review (P20)** (flags scope creep) | +| **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. diff --git a/references/new-workspace-flow.md b/references/new-workspace-flow.md index 37afc7e..923c18c 100644 --- a/references/new-workspace-flow.md +++ b/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 (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 binds each to its enforcing primitive, so downstream development inherits the *intent* behind the primitives — and the user can extend it with project-specific principles. | +| `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 | From f90a803fcac0626f53e10f3aa296df34e7f02c86 Mon Sep 17 00:00:00 2001 From: "Carlos D. Escobar-Valbuena" Date: Fri, 5 Jun 2026 10:12:39 -0500 Subject: [PATCH 4/4] fix(P20 round 3): strip changelog intro to neutral fact (provenance stays in Notes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codex round-3 residual (d): changelog still read as advocacy. Final tightening — intro now states only what shipped + the mapping + what changed; Karpathy provenance preserved factually in the Notes companion-artifact line. Co-Authored-By: Claude Opus 4.8 (1M context) --- CHANGELOG.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 30aa72b..25bf215 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,9 +4,7 @@ ### 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. A note records that enforcement strength varies (P14/P15 are hard predicates; P20 is a judgment gate) — both beat prose because the agent never grades itself. - -Rationale: the scaffold previously deployed the primitive contract without its stated intent. The four principles follow Andrej Karpathy's observations on LLM-coding pitfalls (cf. `multica-ai/andrej-karpathy-skills`). +`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