From 61df42090eb85181e20cc81520e1033fe0e6edfa Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 17:25:55 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=96=20docs:=20calibrate=20workflow?= =?UTF-8?q?=20gates=20to=20capable-model=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 8 +++- book/README.md | 17 +++++++-- ...9-14-capable-model-workflow-calibration.md | 13 +++++++ .../ADR-003-intent-gates-vs-distrust-gates.md | 33 ++++++++++++++++ book/guidelines/README.md | 18 ++++++++- book/guidelines/workflow.md | 11 ++++-- .../2026-09/gpt6-astra-scaffold-audit.md | 38 +++++++++++++++++++ book/plans/README.md | 7 +++- 8 files changed, 132 insertions(+), 13 deletions(-) create mode 100644 book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md create mode 100644 book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md create mode 100644 book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md diff --git a/AGENTS.md b/AGENTS.md index d296655..d4456da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,7 +47,7 @@ Git commits and branching strictly follow `book/guidelines/git-workflow.md`: eve ## code ↔ book interaction rules -1. **Before coding**: read `book/guidelines/` for the baseline; search `book/notes/learn/YYYY-MM/` for related experience. +1. **Before coding**: search `book/notes/learn/YYYY-MM/` for related experience, and consult only the guideline the task actually touches — the input pointers in `book/guidelines/README.md` route you. No blanket pre-reading. 2. **While coding**: new experience or pitfalls go straight into the current month's `book/notes/learn/YYYY-MM/`. 3. **After coding**: check the book — is the plan's status updated, is a summary needed, do new issues exist? 4. **Plans drive code**: `book/plans/` documents are the input to implementation. Read the plan, build in `code/`, write back to `book/`. @@ -55,11 +55,15 @@ Git commits and branching strictly follow `book/guidelines/git-workflow.md`: eve `changelogs/` and `notes/{summary,learn,issue}/` archive under `YYYY-MM/`; the month is a physical grouping, retrieval happens through `book/README.md`, frontmatter, and links. `book/` opens directly as an Obsidian vault. +## Safe by default + +Local commands are disposable and have no production access — npm scripts, tests, builds, `git status/diff/log`, `npm run book:index`, `node scripts/check-commit-message.mjs`. Run them, fix failures, and rerun without asking. A human still owns anything touching production data or credentials, destructive operations, and every push to `main` (which never happens directly anyway). + ## Hard constraints - Step 0 (the structured requirements brief) is required before any code - No skipping between phases -- Phase 2 designs proceed only after user approval +- Phase 2 stops for the user only on real gaps — scope conflict, undetermined data shape, unclear external dependency — never just for confirmation - Problems found in Phase 5 / Phase 6 are **recorded, never fixed** - Feature work touches no code outside its scope: no opportunistic refactors, no new abstractions diff --git a/book/README.md b/book/README.md index 9958955..daa635c 100644 --- a/book/README.md +++ b/book/README.md @@ -20,12 +20,14 @@ description: Master index of the book — the map of every document. Regenerate | Directory | Purpose | |------|------| | `changelogs/` | Change log: what landed and when | +| `changelogs/2026-09/` | Archived under changelogs/, grouped by month | | `docs/` | Technical docs: architecture, API, decisions | | `docs/api/` | API design and interface docs | | `docs/architecture/` | Architecture snapshots: modules, data flow | | `docs/decisions/` | Architecture decision records (ADR) | | `guidelines/` | Development rules every contributor (including AI) must follow | | `notes/` | Running records: learn / summary / task / issue | +| `notes/learn/2026-09/` | Archived under notes/learn/, grouped by month | | `plans/` | Implementation plans: the construction blueprint agents build from | ## All files @@ -34,6 +36,10 @@ description: Master index of the book — the map of every document. Regenerate - [README.md](changelogs/README.md) — Changelogs directory usage — dated change records archived by month, found via the index +### changelogs/2026-09/ + +- [2026-09-14-capable-model-workflow-calibration.md](changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md) — Workflow calibrated to capable-model guidance — safe-by-default permissions, input pointers, gap-based Phase 2, gate-not-recipe Phase 4, plan done-criteria, and a model-change re-audit rule + ### docs/ - [README.md](docs/README.md) — Map of docs/ — architecture snapshots, API design, and architecture decision records @@ -50,24 +56,29 @@ description: Master index of the book — the map of every document. Regenerate - [ADR-001-adopt-bocode.md](docs/decisions/ADR-001-adopt-bocode.md) — We run this repository on the BoCode workflow — book drives code, code writes back, six phases gate every feature - [ADR-002-adopt-bowrite.md](docs/decisions/ADR-002-adopt-bowrite.md) — We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well +- [ADR-003-intent-gates-vs-distrust-gates.md](docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md) — We classify workflow gates by justification — intent gates stay hard, distrust gates soften as models improve; Phase 2 approval becomes gap-based stopping - [README.md](docs/decisions/README.md) — How to write an ADR here — sections, naming, numbering, and when a decision needs a record ### guidelines/ -- [README.md](guidelines/README.md) — Index of the five guidelines — workflow, writing style, git, review checklist, plus the architecture and coding templates +- [README.md](guidelines/README.md) — Index of the five guidelines and the input pointer table — which guideline to read for which kind of task, with no blanket pre-reading - [architecture.md](guidelines/architecture.md) — Template for your project's long-term architecture rules — boundary invariants, module map, tech baseline, with a worked example of boundary-style rules - [coding-style.md](guidelines/coding-style.md) — Template for your project's coding baseline — the language-specific rules any contributor or agent must follow - [git-workflow.md](guidelines/git-workflow.md) — Clean Commit message format and Clean Flow branch, PR, and merge rules for solo and team development - [review-checklist.md](guidelines/review-checklist.md) — The eight code-review checks every change must pass — findings are recorded, never fixed in passing -- [workflow.md](guidelines/workflow.md) — Six-phase gate workflow with the seven code↔book interaction rules and the document routing table +- [workflow.md](guidelines/workflow.md) — Six-phase gate workflow with the eight code↔book interaction rules and the document routing table - [writing-style.md](guidelines/writing-style.md) — Plain-language writing standard for every book document — fidelity contract first, then minimal style rules, intensity levels, and a read-back check ### notes/ - [README.md](notes/README.md) — The four note types (learn, summary, task, issue), when each is written, the retrieval order, and the template for each +### notes/learn/2026-09/ + +- [gpt6-astra-scaffold-audit.md](notes/learn/2026-09/gpt6-astra-scaffold-audit.md) — BoCode audited against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" — index-first routing and intent gates hold, five gaps worth closing + ### plans/ - [README.md](plans/README.md) — Plans directory usage — implementation plans land here after Phase 2 approval, with naming and the plan template - + diff --git a/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md b/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md new file mode 100644 index 0000000..e75356e --- /dev/null +++ b/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md @@ -0,0 +1,13 @@ +--- +description: Workflow calibrated to capable-model guidance — safe-by-default permissions, input pointers, gap-based Phase 2, gate-not-recipe Phase 4, plan done-criteria, and a model-change re-audit rule +--- + +# 2026-09-14 — capable-model workflow calibration + +Applied the audit against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" (`notes/learn/2026-09/gpt6-astra-scaffold-audit.md`); decisions recorded in ADR-003: + +- AGENTS.md — new "Safe by default" section (local commands pre-approved); the before-coding rule routes by pointer instead of blanket-reading; the Phase 2 hard constraint becomes gap-based stopping +- `guidelines/workflow.md` — Phase 2 stops only on real gaps; Phase 4 states the gate as mandatory and red-green-refactor as the default loop; new interaction rule 8 re-audits scaffolding when the agent's model generation changes +- `guidelines/README.md` — input pointer table: which guideline to read for which kind of task +- `plans/README.md` — plan template gains a done-criteria slot (the explicit finish line) +- The structured-feature-implementation skill's Phase 4 was split the same way; its Phase 2 had already moved to gap-based stopping diff --git a/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md b/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md new file mode 100644 index 0000000..9695e5a --- /dev/null +++ b/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md @@ -0,0 +1,33 @@ +--- +description: We classify workflow gates by justification — intent gates stay hard, distrust gates soften as models improve; Phase 2 approval becomes gap-based stopping +--- + +# ADR-003: Separate intent gates from distrust gates + +## Status + +Accepted — applied 2026-09-14 in the capable-model workflow calibration. Amends the Phase 2 gate from ADR-001; the six-phase structure itself stands. + +## Context + +The workflow's gates were written when agent models needed firm rails: blanket pre-reading, prescribed step sequences, stops for confirmation. Capable models invert the economics — OpenAI's "Rethinking skills and prompts for GPT-6 Astra" (audit: `notes/learn/2026-09/gpt6-astra-scaffold-audit.md`) documents the shift: scaffolding that helped weaker models now causes wrong routing, consumed context, premature stops, and halts on approvals the environment already allows. + +The gates had mixed justifications. Some exist because a human owns the decision (review integrity, scope discipline, production safety). Others exist only because weaker models couldn't be trusted to act (blanket design approval, prescribed coding loops, ask-before-running defaults). Only the second kind ages with model capability. + +## Decision + +Gates are classified by justification, and each class gets different maintenance: + +- **Intent gates — stay hard, model-independent**: Phase 5/6 record-never-fix (review must review what was built); Phase 3 scope discipline; production and credential safety; `main` merge-only. +- **Distrust-shaped rules — become defaults**: Phase 4's red-green-refactor loop is the default path; the mandatory part is the gate (all green, no weakened assertions, coverage matrix). Guideline reading is pointer-based (the input table in `guidelines/README.md`), never blanket. +- **Approval gates — become gap-based stops**: Phase 2 produces the full design and proceeds to Phase 3; it stops for the user only on real gaps — scope conflict, undetermined data shape, unclear external dependency — never just for confirmation. +- **Permissions flip to grant**: local commands are pre-approved (the safe-by-default block in AGENTS.md); agents run, fix, and rerun without asking. +- **Plans carry explicit done criteria** — the finish line that prevents premature stops. +- **Standing re-audit**: when the agent's model generation changes, re-audit AGENTS.md, `guidelines/`, and skills against this taxonomy. + +## Consequences + +- Capable agents move without halting on pre-approved actions or confirmations; tentative ones get an explicit finish line from the plan +- The human review point moves from "before any code exists" to "the delivered design plus the recorded review" — cheaper per feature, but a wrong design direction surfaces after implementation; Step 0 and the requirements brief carry more of the intent weight +- Weaker models lose some rails — projects pinned to a weak model may prefer stricter phrasing and should record that in their own ADR +- The re-audit rule is a recurring maintenance task; skipping it lets distrust gates quietly grow back diff --git a/book/guidelines/README.md b/book/guidelines/README.md index e1dfb0e..671f00f 100644 --- a/book/guidelines/README.md +++ b/book/guidelines/README.md @@ -1,5 +1,5 @@ --- -description: Index of the five guidelines — workflow, writing style, git, review checklist, plus the architecture and coding templates +description: Index of the five guidelines and the input pointer table — which guideline to read for which kind of task, with no blanket pre-reading --- # Guidelines @@ -15,4 +15,18 @@ The project's development rules. Every contributor — including AI agents — f | `architecture.md` | Long-term architecture rules (template — replace per project) | | `coding-style.md` | Language-specific coding baseline (template — replace per project) | -Start with `workflow.md`; the others answer questions it raises. +## Input pointers — consult on demand, never blanket-read + +| When the task touches… | Read first | +|--------|-----------| +| Phases, gates, book sync | `workflow.md` | +| Module boundaries, data ownership, tech swaps | `architecture.md` | +| The current shape of modules and data flow | `../docs/architecture/` snapshots | +| Interface contracts | `../docs/api/` | +| Writing any book document | `writing-style.md` | +| Commits, branches, PRs, releases | `git-workflow.md` | +| Language-level code rules | `coding-style.md` | +| Reviewing a diff | `review-checklist.md` | +| Prior experience with this symptom or tech | search `../notes/learn/` by tag | + +First contact with the repo: read `workflow.md` once. After that, jump straight to the guideline the task touches — the table above routes you. diff --git a/book/guidelines/workflow.md b/book/guidelines/workflow.md index 6f13cda..e093b9e 100644 --- a/book/guidelines/workflow.md +++ b/book/guidelines/workflow.md @@ -1,5 +1,5 @@ --- -description: Six-phase gate workflow with the seven code↔book interaction rules and the document routing table +description: Six-phase gate workflow with the eight code↔book interaction rules and the document routing table --- # Workflow @@ -12,7 +12,7 @@ Every feature moves through these phases in order. **No skipping.** |------|------|--------|------| | Step 0 | Structured requirements brief | Requirements brief | Every slot filled | | Phase 1 | Analysis | Impact map + risk list | No code changed | -| Phase 2 | Design | Data flow, file list, interfaces | **User approval required before Phase 3** | +| Phase 2 | Design | Data flow, file list, interfaces | Design complete; stop only on real gaps — scope conflict, undetermined data shape, unclear external dependency | | Phase 3 | Implementation | Code | Strictly per design; nothing outside scope | | Phase 4 | Testing | Test cases | All green; no weakened assertions | | Phase 5 | Code review | Review findings | Record only — no fixes | @@ -20,7 +20,9 @@ Every feature moves through these phases in order. **No skipping.** Step 0 comes before any code. Fill the brief: background, scope (what it affects, what it explicitly does **not** affect, and the boundaries), and the requirement itself. An empty "does not affect" list is the number-one cause of out-of-scope changes in Phase 3 — the exclusions slot is required. -Phase 4 runs test-first: write a failing test, write the minimum implementation that passes it, refactor with the test staying green. Coverage must include the normal path, boundary inputs (ranges, empty, extremes), error paths, and a regression check that existing behavior didn't break. +Phase 2 produces the full design — data flow, file list, interfaces — and proceeds; it stops for the user only when a real gap appears (scope conflict, undetermined data shape, unclear external dependency), never just for confirmation. + +Phase 4's hard part is the gate, not the sequence: all relevant tests green, no assertion weakened to get there, coverage of the normal path, boundary inputs (ranges, empty, extremes), error paths, and a regression check that existing behavior didn't break. Test-first (write a failing test → minimum implementation → refactor staying green) is the default loop — sequence the work however keeps the gate honest. Phases 5 and 6 share one discipline: **record, never fix.** A problem found during review or wrap-up goes into `notes/issue/` — fixing it is a separate, later task. Fixing in passing feels efficient and destroys the gate: the review no longer reviews what was built. @@ -51,13 +53,14 @@ Phases 5 and 6 share one discipline: **record, never fix.** A problem found duri ## Interaction rules -1. **Before coding** — read `guidelines/` for the baseline; search `notes/learn/` for related experience. +1. **Before coding** — search `notes/learn/` for related experience and consult only the guideline the task touches (the input pointers in `guidelines/README.md` route you); no blanket pre-reading. 2. **While coding** — something new learned or tripped over? Write it to `notes/learn/` immediately; future sessions (human or agent) benefit. 3. **After coding** — sync the book: plan status, summary, new issues, changelog, index. 4. **Plans drive code** — `book/plans/` is the input to implementation. The agent reads the plan, builds in `code/`, writes back to `book/`. 5. **Issues feed code** — `notes/issue/` records problems that become the direction of later iterations. 6. **The book compounds** — every feature should leave the book more complete than it found it. The book is both the agent's context and the human's reference manual. 7. **Refresh the index** — after any book change, run `cd code && npm run book:index` before wrapping up. New files must carry a frontmatter `description`, and internal links must resolve — either failing fails the build. +8. **Re-audit when the model changes** — scaffolding ages with model capability. When the agent's model generation changes, re-audit AGENTS.md, `guidelines/`, and skills against ADR-003's gate taxonomy: keep intent gates (record-never-fix, scope discipline), drop or soften gates that only exist from distrust of weaker models. ## Document routing diff --git a/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md b/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md new file mode 100644 index 0000000..3c3e146 --- /dev/null +++ b/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md @@ -0,0 +1,38 @@ +--- +description: BoCode audited against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" — index-first routing and intent gates hold, five gaps worth closing +tags: [agent-workflow, prompts, skills, agents-md, model-capability, audit] +--- +# Capable-model guidance mostly vindicates BoCode's routing; the gaps are permission grants, input pointers, done-criteria in plans, gate-vs-recipe separation, and a standing re-audit + +- **Scenario**: applies when AGENTS.md, guidelines, or skills are revised, and whenever the agent's model generation changes. +- **Why**: scaffolding written for weaker models — blanket pre-reading, distrust-driven ask-first gates, prescribed coding itineraries — taxes capable models with wrong routing, consumed context, premature stops, and redundant work. +- **How to apply**: the alignment table below says what to keep; the five deltas are candidates that change guidelines and need an explicit decision. + +Source: OpenAI developers blog, "Rethinking skills and prompts for GPT-6 Astra" (https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra), read 2026-09-14. Four sections: better skills, up-to-date AGENTS.md, decision boundaries, persistence. + +## Where BoCode already aligns + +| Article principle | BoCode practice | +|------|------| +| Skills/docs as minimal routers, not manuals | `book/README.md` is a generated master index of one-line descriptions; agents read it first and follow links only where needed | +| Keep descriptions short and specific | Frontmatter `description` must state content, not genre (`Module overview: responsibilities and boundaries of web, api, and worker`) | +| Reading costs context and can trigger compaction | Month folders are physical grouping only; retrieval goes through the index, frontmatter, and `tags` — never "read everything" | +| Don't let review mutate what was reviewed | Phase 5/6 record-never-fix is review integrity, not model distrust — keep regardless of model capability | +| Define completion upfront to avoid premature stops | The six phases already encode done: Phase 4 all green → Phase 6 book synced and index rebuilt | +| Rules must be checkable | architecture.md: "if a rule can't be checked against a diff, it's a wish" | + +The structured-feature-implementation skill also follows the article's skill hygiene: its description scopes both when to trigger and when not to (one-line fixes, typos, pure questions, already-scoped requests). + +## Five gaps worth closing (each needs a decision — they change guidelines) + +> 2026-09-14: all five applied, plus one step further — Phase 2 approval became gap-based stopping, matching the skill's own edit. Decisions recorded in ADR-003; see `changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md`. + +1. **No safe-permissions grant in AGENTS.md.** The article's most practical tip: state what is safe so the model doesn't halt on approvals the environment already allows. Add a block like "local runs and tests are disposable and have no production access — run, fix, and rerun without asking." +2. **Input routing is implied, not tabulated.** Rule 1 says "read `guidelines/` for the baseline" — close to the blanket pre-reading the article warns against. Replace with a contextual pointer table mirroring the output routing table: service boundaries → `guidelines/architecture.md`; prose → `guidelines/writing-style.md`; commits → `guidelines/git-workflow.md`; related experience → search `notes/learn/`. +3. **Phase 4 prescribes the TDD itinerary** (red → green → refactor). The durable part is the gate: all green, no weakened assertions, the coverage matrix (normal / boundary / error / regression). As models improve, the loop should read as a default, not a mandate. +4. **Plans should restate done-criteria explicitly.** Phase 2 approval is an intent gate — keep it. But tentative models stop early mid-phase; a plan-level "done" line (tests green + review recorded + book synced + index rebuilt) is the article's persistence fix at feature granularity. +5. **No standing re-audit rule.** Scaffolding ages with model capability. Adopt the article's closing move as a periodic task: whenever the agent's model generation changes, have the current model audit AGENTS.md, guidelines, and skills against these principles. + +## Calibration note + +The article's claim is not "remove gates" but "remove gates justified by distrust of the model; keep gates justified by human intent". Record-never-fix (review integrity) and scope discipline are pure intent gates — they survive capable models. Phase 2 approval sat on the fence: design direction is a human concern, but a blanket pre-implementation stop also punishes capable models with premature halts; the 2026-09-14 decision (ADR-003) keeps the full design output and stops only on real gaps. diff --git a/book/plans/README.md b/book/plans/README.md index 00ecffe..2122092 100644 --- a/book/plans/README.md +++ b/book/plans/README.md @@ -4,7 +4,7 @@ description: Plans directory usage — implementation plans land here after Phas # Plans -Implementation plans live here. Each feature's detailed plan lands in this folder once its Phase 2 design is approved — the plan is the construction blueprint the agent builds from. +Implementation plans live here. Each feature's detailed plan lands in this folder once its Phase 2 design is settled — the plan is the construction blueprint the agent builds from. ## Naming @@ -35,6 +35,9 @@ status: draft | approved | in_progress | completed ## Test plan + +## Done criteria + ``` -A plan is executable as written: each step small enough to verify on its own. When the build finishes, flip `status` to `completed` — the plan then doubles as the record of what was intended, next to the summary of what happened. +A plan is executable as written: each step small enough to verify on its own. The done-criteria slot is the finish line — agents stop where the text stops, so an explicit finish line prevents premature stops. When it reads true, flip `status` to `completed`; the plan then doubles as the record of what was intended, next to the summary of what happened. From 705343de2c6f49d04348e4ceb496306516e7026a Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 17:40:58 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=97=91=EF=B8=8F=20remove=20(book):=20?= =?UTF-8?q?drop=20instance=20working=20records=20from=20the=20template?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book/README.md | 13 +------ ...9-14-capable-model-workflow-calibration.md | 13 ------- .../ADR-003-intent-gates-vs-distrust-gates.md | 2 +- .../2026-09/gpt6-astra-scaffold-audit.md | 38 ------------------- 4 files changed, 3 insertions(+), 63 deletions(-) delete mode 100644 book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md delete mode 100644 book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md diff --git a/book/README.md b/book/README.md index daa635c..34ba103 100644 --- a/book/README.md +++ b/book/README.md @@ -20,14 +20,12 @@ description: Master index of the book — the map of every document. Regenerate | Directory | Purpose | |------|------| | `changelogs/` | Change log: what landed and when | -| `changelogs/2026-09/` | Archived under changelogs/, grouped by month | | `docs/` | Technical docs: architecture, API, decisions | | `docs/api/` | API design and interface docs | | `docs/architecture/` | Architecture snapshots: modules, data flow | | `docs/decisions/` | Architecture decision records (ADR) | | `guidelines/` | Development rules every contributor (including AI) must follow | | `notes/` | Running records: learn / summary / task / issue | -| `notes/learn/2026-09/` | Archived under notes/learn/, grouped by month | | `plans/` | Implementation plans: the construction blueprint agents build from | ## All files @@ -36,10 +34,6 @@ description: Master index of the book — the map of every document. Regenerate - [README.md](changelogs/README.md) — Changelogs directory usage — dated change records archived by month, found via the index -### changelogs/2026-09/ - -- [2026-09-14-capable-model-workflow-calibration.md](changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md) — Workflow calibrated to capable-model guidance — safe-by-default permissions, input pointers, gap-based Phase 2, gate-not-recipe Phase 4, plan done-criteria, and a model-change re-audit rule - ### docs/ - [README.md](docs/README.md) — Map of docs/ — architecture snapshots, API design, and architecture decision records @@ -57,6 +51,7 @@ description: Master index of the book — the map of every document. Regenerate - [ADR-001-adopt-bocode.md](docs/decisions/ADR-001-adopt-bocode.md) — We run this repository on the BoCode workflow — book drives code, code writes back, six phases gate every feature - [ADR-002-adopt-bowrite.md](docs/decisions/ADR-002-adopt-bowrite.md) — We distill shuorenhua plus our own review patterns into bowrite (薄写), an in-repo writing skill — write thin, write well - [ADR-003-intent-gates-vs-distrust-gates.md](docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md) — We classify workflow gates by justification — intent gates stay hard, distrust gates soften as models improve; Phase 2 approval becomes gap-based stopping +- [ADR-004-template-free-of-instance-records.md](docs/decisions/ADR-004-template-free-of-instance-records.md) — This repository ships template content only — instance working records (notes entries, plans, changelog months) never enter it; a release check enforces the boundary - [README.md](docs/decisions/README.md) — How to write an ADR here — sections, naming, numbering, and when a decision needs a record ### guidelines/ @@ -73,12 +68,8 @@ description: Master index of the book — the map of every document. Regenerate - [README.md](notes/README.md) — The four note types (learn, summary, task, issue), when each is written, the retrieval order, and the template for each -### notes/learn/2026-09/ - -- [gpt6-astra-scaffold-audit.md](notes/learn/2026-09/gpt6-astra-scaffold-audit.md) — BoCode audited against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" — index-first routing and intent gates hold, five gaps worth closing - ### plans/ - [README.md](plans/README.md) — Plans directory usage — implementation plans land here after Phase 2 approval, with naming and the plan template - + diff --git a/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md b/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md deleted file mode 100644 index e75356e..0000000 --- a/book/changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: Workflow calibrated to capable-model guidance — safe-by-default permissions, input pointers, gap-based Phase 2, gate-not-recipe Phase 4, plan done-criteria, and a model-change re-audit rule ---- - -# 2026-09-14 — capable-model workflow calibration - -Applied the audit against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" (`notes/learn/2026-09/gpt6-astra-scaffold-audit.md`); decisions recorded in ADR-003: - -- AGENTS.md — new "Safe by default" section (local commands pre-approved); the before-coding rule routes by pointer instead of blanket-reading; the Phase 2 hard constraint becomes gap-based stopping -- `guidelines/workflow.md` — Phase 2 stops only on real gaps; Phase 4 states the gate as mandatory and red-green-refactor as the default loop; new interaction rule 8 re-audits scaffolding when the agent's model generation changes -- `guidelines/README.md` — input pointer table: which guideline to read for which kind of task -- `plans/README.md` — plan template gains a done-criteria slot (the explicit finish line) -- The structured-feature-implementation skill's Phase 4 was split the same way; its Phase 2 had already moved to gap-based stopping diff --git a/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md b/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md index 9695e5a..6c17d0a 100644 --- a/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md +++ b/book/docs/decisions/ADR-003-intent-gates-vs-distrust-gates.md @@ -10,7 +10,7 @@ Accepted — applied 2026-09-14 in the capable-model workflow calibration. Amend ## Context -The workflow's gates were written when agent models needed firm rails: blanket pre-reading, prescribed step sequences, stops for confirmation. Capable models invert the economics — OpenAI's "Rethinking skills and prompts for GPT-6 Astra" (audit: `notes/learn/2026-09/gpt6-astra-scaffold-audit.md`) documents the shift: scaffolding that helped weaker models now causes wrong routing, consumed context, premature stops, and halts on approvals the environment already allows. +The workflow's gates were written when agent models needed firm rails: blanket pre-reading, prescribed step sequences, stops for confirmation. Capable models invert the economics — OpenAI's [Rethinking skills and prompts for GPT-6 Astra](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra) documents the shift: scaffolding that helped weaker models now causes wrong routing, consumed context, premature stops, and halts on approvals the environment already allows. The gates had mixed justifications. Some exist because a human owns the decision (review integrity, scope discipline, production safety). Others exist only because weaker models couldn't be trusted to act (blanket design approval, prescribed coding loops, ask-before-running defaults). Only the second kind ages with model capability. diff --git a/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md b/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md deleted file mode 100644 index 3c3e146..0000000 --- a/book/notes/learn/2026-09/gpt6-astra-scaffold-audit.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: BoCode audited against OpenAI's "Rethinking skills and prompts for GPT-6 Astra" — index-first routing and intent gates hold, five gaps worth closing -tags: [agent-workflow, prompts, skills, agents-md, model-capability, audit] ---- -# Capable-model guidance mostly vindicates BoCode's routing; the gaps are permission grants, input pointers, done-criteria in plans, gate-vs-recipe separation, and a standing re-audit - -- **Scenario**: applies when AGENTS.md, guidelines, or skills are revised, and whenever the agent's model generation changes. -- **Why**: scaffolding written for weaker models — blanket pre-reading, distrust-driven ask-first gates, prescribed coding itineraries — taxes capable models with wrong routing, consumed context, premature stops, and redundant work. -- **How to apply**: the alignment table below says what to keep; the five deltas are candidates that change guidelines and need an explicit decision. - -Source: OpenAI developers blog, "Rethinking skills and prompts for GPT-6 Astra" (https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra), read 2026-09-14. Four sections: better skills, up-to-date AGENTS.md, decision boundaries, persistence. - -## Where BoCode already aligns - -| Article principle | BoCode practice | -|------|------| -| Skills/docs as minimal routers, not manuals | `book/README.md` is a generated master index of one-line descriptions; agents read it first and follow links only where needed | -| Keep descriptions short and specific | Frontmatter `description` must state content, not genre (`Module overview: responsibilities and boundaries of web, api, and worker`) | -| Reading costs context and can trigger compaction | Month folders are physical grouping only; retrieval goes through the index, frontmatter, and `tags` — never "read everything" | -| Don't let review mutate what was reviewed | Phase 5/6 record-never-fix is review integrity, not model distrust — keep regardless of model capability | -| Define completion upfront to avoid premature stops | The six phases already encode done: Phase 4 all green → Phase 6 book synced and index rebuilt | -| Rules must be checkable | architecture.md: "if a rule can't be checked against a diff, it's a wish" | - -The structured-feature-implementation skill also follows the article's skill hygiene: its description scopes both when to trigger and when not to (one-line fixes, typos, pure questions, already-scoped requests). - -## Five gaps worth closing (each needs a decision — they change guidelines) - -> 2026-09-14: all five applied, plus one step further — Phase 2 approval became gap-based stopping, matching the skill's own edit. Decisions recorded in ADR-003; see `changelogs/2026-09/2026-09-14-capable-model-workflow-calibration.md`. - -1. **No safe-permissions grant in AGENTS.md.** The article's most practical tip: state what is safe so the model doesn't halt on approvals the environment already allows. Add a block like "local runs and tests are disposable and have no production access — run, fix, and rerun without asking." -2. **Input routing is implied, not tabulated.** Rule 1 says "read `guidelines/` for the baseline" — close to the blanket pre-reading the article warns against. Replace with a contextual pointer table mirroring the output routing table: service boundaries → `guidelines/architecture.md`; prose → `guidelines/writing-style.md`; commits → `guidelines/git-workflow.md`; related experience → search `notes/learn/`. -3. **Phase 4 prescribes the TDD itinerary** (red → green → refactor). The durable part is the gate: all green, no weakened assertions, the coverage matrix (normal / boundary / error / regression). As models improve, the loop should read as a default, not a mandate. -4. **Plans should restate done-criteria explicitly.** Phase 2 approval is an intent gate — keep it. But tentative models stop early mid-phase; a plan-level "done" line (tests green + review recorded + book synced + index rebuilt) is the article's persistence fix at feature granularity. -5. **No standing re-audit rule.** Scaffolding ages with model capability. Adopt the article's closing move as a periodic task: whenever the agent's model generation changes, have the current model audit AGENTS.md, guidelines, and skills against these principles. - -## Calibration note - -The article's claim is not "remove gates" but "remove gates justified by distrust of the model; keep gates justified by human intent". Record-never-fix (review integrity) and scope discipline are pure intent gates — they survive capable models. Phase 2 approval sat on the fence: design direction is a human concern, but a blanket pre-implementation stop also punishes capable models with premature halts; the 2026-09-14 decision (ADR-003) keeps the full design output and stops only on real gaps. From 9da7844a6ce7dfa713f3716755715017104ae158 Mon Sep 17 00:00:00 2001 From: Focus Date: Mon, 14 Sep 2026 17:41:07 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E2=9A=99=EF=B8=8F=20setup=20(tools):=20add?= =?UTF-8?q?=20template-clean=20check=20to=20the=20release=20flow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/git-policy.yml | 4 ++ ADOPT.md | 2 +- AGENTS.md | 3 + ...R-004-template-free-of-instance-records.md | 30 +++++++++ book/guidelines/git-workflow.md | 3 +- code/package.json | 3 +- code/tools/check-template-clean.mjs | 65 +++++++++++++++++++ 7 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 book/docs/decisions/ADR-004-template-free-of-instance-records.md create mode 100644 code/tools/check-template-clean.mjs diff --git a/.github/workflows/git-policy.yml b/.github/workflows/git-policy.yml index 39b627f..fd49a1e 100644 --- a/.github/workflows/git-policy.yml +++ b/.github/workflows/git-policy.yml @@ -56,6 +56,8 @@ jobs: else node scripts/check-commit-message.mjs "$PR_TITLE" fi + - name: Check template cleanliness + run: cd code && npm run book:release-check validate-protected-push: if: github.event_name == 'push' @@ -79,3 +81,5 @@ jobs: else echo "No non-merge commits in range; nothing to validate." fi + - name: Check template cleanliness + run: cd code && npm run book:release-check diff --git a/ADOPT.md b/ADOPT.md index d250f7f..4ed0827 100644 --- a/ADOPT.md +++ b/ADOPT.md @@ -48,7 +48,7 @@ Every migrated file gets a frontmatter `description` — one plain-language line 1. Copy `code/tools/gen-book-index.mjs` and wire the script (see the `scripts` block in BoCode's `code/package.json`). If the project has no JavaScript tooling at all, a shell wrapper calling `node` is fine — the script is zero-dependency. 2. Optional, recommended: copy `scripts/check-commit-message.mjs` and `.githooks/`, then run `git config core.hooksPath .githooks`. -3. Optional: copy `.github/workflows/git-policy.yml`. **Check the branch names** — if the project's integration branch isn't `dev`, either ask the user to adopt the branch model or adapt the workflow's branch filters. Don't silently rewrite their branch model. +3. Optional: copy `.github/workflows/git-policy.yml`. **Check the branch names** — if the project's integration branch isn't `dev`, either ask the user to adopt the branch model or adapt the workflow's branch filters. Don't silently rewrite their branch model. Also **delete the "Check template cleanliness" step** — it enforces the BoCode template repository's own cleanliness rule (its ADR-004) and would fail on a real project's notes and changelogs. 4. Run the index generator: every book file must carry a `description` and every internal link must resolve; zero warnings is the only passing state. ## Step 5 — Install the skills diff --git a/AGENTS.md b/AGENTS.md index d4456da..5ab1002 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,6 +55,8 @@ Git commits and branching strictly follow `book/guidelines/git-workflow.md`: eve `changelogs/` and `notes/{summary,learn,issue}/` archive under `YYYY-MM/`; the month is a physical grouping, retrieval happens through `book/README.md`, frontmatter, and links. `book/` opens directly as an Obsidian vault. +This repository is the template itself, not an adopting project: knowledge work here lands in `book/docs/decisions/` ADRs — never in `notes/{learn,summary,issue,task}/`, `plans/`, or `changelogs/` entries. `cd code && npm run book:release-check` enforces the boundary (ADR-004). + ## Safe by default Local commands are disposable and have no production access — npm scripts, tests, builds, `git status/diff/log`, `npm run book:index`, `node scripts/check-commit-message.mjs`. Run them, fix failures, and rerun without asking. A human still owns anything touching production data or credentials, destructive operations, and every push to `main` (which never happens directly anyway). @@ -70,4 +72,5 @@ Local commands are disposable and have no production access — npm scripts, tes ## Tooling - `cd code && npm run book:index` — regenerate `book/README.md` after any book change (do not edit by hand; missing frontmatter `description` warns and exits 1) +- `cd code && npm run book:release-check` — verify the tree holds no instance working records; must be green before the `dev → main` release PR - `node scripts/check-commit-message.mjs ""` — validate a commit subject against Clean Commit diff --git a/book/docs/decisions/ADR-004-template-free-of-instance-records.md b/book/docs/decisions/ADR-004-template-free-of-instance-records.md new file mode 100644 index 0000000..1f60445 --- /dev/null +++ b/book/docs/decisions/ADR-004-template-free-of-instance-records.md @@ -0,0 +1,30 @@ +--- +description: This repository ships template content only — instance working records (notes entries, plans, changelog months) never enter it; a release check enforces the boundary +--- + +# ADR-004: Keep the template free of instance working records + +## Status + +Accepted — 2026-09-14. Enforced by `code/tools/check-template-clean.mjs` (`npm run book:release-check`), wired into `.github/workflows/git-policy.yml`. + +## Context + +BoCode is a template repository: adopters copy its skeleton into their projects and fill the book with their own records. The workflow this repo teaches treats `notes/{learn,summary,issue,task}/`, `plans/`, and `changelogs/YYYY-MM/` as the adopting project's knowledge base. This repository is not an adopting project — its product is the workflow itself. + +The first instance records appeared on 2026-09-14 (a learn entry and a changelog month from the capable-model calibration). Carried by the next `dev → main` merge — which by ADR-001 and the git rules only ever merges — they would ship to every adopter as leftovers. + +Alternative rejected: keep records on `dev`, strip them at merge time. Git merges carry the whole tree; main would receive them inside the merge commit and need a cleanup commit every release, and its history would still contain them. + +## Decision + +- This repository tracks **template content only**: guidelines, READMEs, `AGENTS.md`, ADRs, tooling, the generated index. ADRs double as this repo's own decision records and ship as worked examples. +- Instance working records — anything under `book/notes/{learn,summary,issue,task}/`, `book/plans/`, or `book/changelogs/` beyond the READMEs — are never committed here. This repo's experience distills into ADRs; raw process notes stay out of the tree (git history keeps anything already committed). +- `cd code && npm run book:release-check` fails when a guarded directory holds anything but its README; it runs in CI on every PR and push to `dev`/`main`, and manually before a release. +- Adopters are unaffected: `ADOPT.md` tells them not to copy the check — in a real project it would fail on the project's own notes. + +## Consequences + +- The released template stays clean; adopters see the conventions as instructions (READMEs), never as leftovers to delete +- This repository does not dogfood its own learn/plan/changelog conventions — accepted: its features are workflow changes, recorded as ADRs plus merge history +- The boundary needs naming when it stings: content that feels like both (a changelog of template changes, say) gets decided case by case and recorded here diff --git a/book/guidelines/git-workflow.md b/book/guidelines/git-workflow.md index 2115250..714f9ad 100644 --- a/book/guidelines/git-workflow.md +++ b/book/guidelines/git-workflow.md @@ -114,7 +114,7 @@ git push origin dev When several people build the same feature, open the PR from `feature/user-profile` into `dev` and **Squash and merge** after checks; the squash subject uses Clean Commit too. Delete the work branch after merging. -When `dev` is stable, open the `dev → main` PR and choose **Create a merge commit** to preserve the integration boundary. The merge-commit subject is Clean Commit as well, e.g.: +When `dev` is stable, run `cd code && npm run book:release-check` first — the release ships template content only, and instance working records (note entries, plans, changelog months) fail the check (ADR-004). Then open the `dev → main` PR and choose **Create a merge commit** to preserve the integration boundary. The merge-commit subject is Clean Commit as well, e.g.: ```text 🚀 release: promote dev to main @@ -123,6 +123,7 @@ When `dev` is stable, open the `dev → main` PR and choose **Create a merge com ## Automation and platform settings - PRs into `dev`/`main` and pushes to them are checked by `.github/workflows/git-policy.yml` for branch direction and commit subjects; direct pushes to `dev` still pass Clean Commit validation. +- The same workflow runs `book:release-check` on every PR and push to `dev`/`main`; it fails the moment an instance working record enters the tree (ADR-004). - Run `git config core.hooksPath .githooks` once per clone to get the same `commit-msg` check locally. - Protect `main` on GitHub: require a PR from `dev`, status checks, and merge commits. Keep direct pushes to `dev` allowed for solo speed; team PRs still use squash merges. diff --git a/code/package.json b/code/package.json index 5f8c191..922f68d 100644 --- a/code/package.json +++ b/code/package.json @@ -5,6 +5,7 @@ "type": "module", "description": "Project source tree. The only script here is the book index generator — this file has zero dependencies by design.", "scripts": { - "book:index": "node tools/gen-book-index.mjs" + "book:index": "node tools/gen-book-index.mjs", + "book:release-check": "node tools/check-template-clean.mjs" } } diff --git a/code/tools/check-template-clean.mjs b/code/tools/check-template-clean.mjs new file mode 100644 index 0000000..2157753 --- /dev/null +++ b/code/tools/check-template-clean.mjs @@ -0,0 +1,65 @@ +#!/usr/bin/env node +/** + * Guards the template boundary (ADR-004): this repository ships the BoCode + * template, not an adopting project's working records. The book's + * running-record directories must hold nothing but their READMEs. + * + * Usage: cd code && node tools/check-template-clean.mjs + * (or: npm run book:release-check) + * + * Guarded: book/changelogs, book/notes/{learn,summary,issue,task}, book/plans. + * This repo's own knowledge work lands in book/docs/decisions/ ADRs instead. + * Adopters do not copy this script — see ADOPT.md step 4. + * Zero dependencies; runs on plain Node (and bun). + */ +import { readdirSync } from "node:fs"; +import { join, dirname, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +const TOOLS_DIR = dirname(fileURLToPath(import.meta.url)); +const BOOK_ROOT = join(TOOLS_DIR, "..", "..", "book"); + +const GUARDED_DIRS = [ + "changelogs", + "notes/learn", + "notes/summary", + "notes/issue", + "notes/task", + "plans", +]; + +function walk(dir) { + const out = []; + for (const entry of readdirSync(dir, { withFileTypes: true })) { + if (entry.name.startsWith(".")) continue; + const full = join(dir, entry.name); + if (entry.isDirectory()) out.push(...walk(full)); + else out.push(full); + } + return out; +} + +const violations = []; + +for (const rel of GUARDED_DIRS) { + const base = join(BOOK_ROOT, rel); + let files; + try { + files = walk(base); + } catch { + continue; // directory absent — nothing to guard + } + for (const file of files) { + if (relative(base, file) === "README.md") continue; + violations.push(`book/${relative(BOOK_ROOT, file)}`); + } +} + +if (violations.length > 0) { + console.error(`Instance working records in the template tree (${violations.length}) — ADR-004 keeps this repository to template content:`); + for (const v of violations) console.error(` - ${v}`); + console.error("Distill the entry into an ADR (book/docs/decisions/) or move it out of the repository, then rerun. The dev→main release stays blocked until this check is green."); + process.exit(1); +} + +console.log("Template tree clean — guarded directories hold READMEs only (ADR-004).");