refactor: default /ba:plan to decisions, gate code behind a shape label

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-workflow",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Research, brainstorm, plan, slice, execute, review, compound, and propose commands with triage, convention compliance, and knowledge compounding",
   "author": {
     "name": "Bruno Azevedo"

CLAUDE.md

@@ -79,5 +79,6 @@ Claude Code plugin providing brainstorm and plan commands with triage, conventio
 - Agents may declare `tools` in frontmatter to restrict available tools (e.g., locator agents use Grep, Glob, LS only — no Read)
 - `/ba:review` selection is a stateless per-diff judgment — every reviewer (built-in and discovered external) appears in the **selection ledger** each run, selected or set aside with a one-line reason, and is reachable via **Adjust**. Reviewers are never silently dropped; no selection state is persisted. (This never-hide convention is mirrored in `README.md` and `commands/ba/review.md` Step 2 — keep them in sync.)
 - `/ba:review` dispatches reviewer subagents with a protected-artifacts guard naming `docs/brainstorms/`, `docs/plans/`, `docs/solutions/`, `docs/research/`, and `docs/reviews/` — reviewers must not suggest deleting, relocating, or otherwise removing files under these roots (content review is unaffected)
+- Plan documents default to **decisions** (approach, exact file paths, patterns, pseudo-code for shape, test scenarios); a literal code block is permitted only under a `**Code-shape decision:** <why>` label. The label wording is mirrored across `commands/ba/plan.md` ("Key rules for all templates" trigger block **and** the three template placeholders), `commands/ba/execute.md` (Step 2b + Step 1.5b LoC projection), `commands/ba/slice.md` (LoC Counting Rules), and `README.md` (`/ba:plan` description) — keep them in sync. (This convention covers the *label* only; the `## Locked Design` anchor it references is owned by `commands/ba/brainstorm.md`.)
 - Update README.md whenever commands, agents, or artifact paths are added or changed
 - Git workflow commands (`ba:propose`) commit, push, and open PR/MR — they never modify source files outside the staged diff

README.md

@@ -98,7 +98,7 @@ Brainstorm docs are saved to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
 
 ### `/ba:plan [feature]`
 
-Transforms feature descriptions into implementation plans with exact file paths and code.
+Transforms feature descriptions into implementation plans with exact file paths and decisions (literal code only under a `**Code-shape decision:**` label, where the code's shape is the design decision).
 
 - **Auto-detects brainstorms** — searches `docs/brainstorms/` for recent (14-day) topic-matched docs and carries forward all decisions
 - **Parallel research** — dispatches agents to analyze codebase patterns and search prior learnings

commands/ba/execute.md

@@ -134,11 +134,17 @@ Do **not** include files you "might also touch" — only files the slice's tasks
 
 ### 1.5b. Project LoC per file
 
+Classify each fenced block as **literal** or **pseudo-code** before counting (three cases):
+
+- **Fence under a `**Code-shape decision:**` label** → literal.
+- **Unlabeled fence, in a plan that has at least one `**Code-shape decision:**` label** → pseudo-code.
+- **Any fence, in a plan with no `**Code-shape decision:**` labels anywhere** (a pre-change plan) → literal.
+
 For each file in the list:
 
-- **Plan provides code in this slice's tasks**: count the lines of the provided code block.
-- **No code in plan, file exists**: estimate the diff size from the task description; reference similar implementations in the codebase if needed.
-- **New file, no code in plan**: estimate from the closest analogue (similar new files in this codebase).
+- **Plan provides a literal code block for this file** (fence under a `**Code-shape decision:**` label, or any fence in a pre-change plan with no labels at all): count the lines of that block.
+- **Decisions/pseudo-code only, file exists**: estimate the diff size from the task description; reference similar implementations in the codebase if needed.
+- **New file, decisions only**: estimate from the closest analogue (similar new files in this codebase).
 
 Sum the per-file estimates. Call this the **projection** (M).
 
@@ -206,9 +212,7 @@ For COMPREHENSIVE plans, also announce phase transitions: "**--- Phase [N]: [Pha
 
 ### 2b. Implement
 
-Read the plan's code for this task and implement it. Follow the plan exactly — it has already been reviewed and approved.
-
-If the plan provides actual code, use it. If the plan describes the change without full code, implement it following existing codebase patterns.
+Implement the plan's decisions for this task. Where the plan provides a literal code block — classified per Step 1.5b (a fence under a `**Code-shape decision:**` label, or any fence in a pre-change plan with no labels anywhere) — implement that code as specified; it captures a committed decision and is binding verbatim. Where the plan gives decisions, pseudo-code, or unlabeled fences (pseudo-code), implement to them following existing codebase patterns. Where a literal code block and prose both address the same file or function, the code block governs the structure; the prose is context.
 
 When rewriting an existing file, read the original first and carry over any WHY comments (non-obvious rationale, workarounds, invariant explanations) that are not reproduced in the plan's code block but are not explicitly removed by the plan. Plan code samples are structural references, not complete comment inventories.
 
@@ -440,7 +444,7 @@ Use **AskUserQuestion**:
 
 ## Important Guidelines
 
-- **The plan is the authority.** Follow it. Don't add features, refactor surrounding code, or "improve" things beyond what the plan specifies.
+- **The plan's decisions are the authority.** Literal code blocks are authoritative verbatim; implement everything else to the plan's decisions. Don't add features, refactor surrounding code, or invent build choices the plan deliberately left as decisions.
 - **Track progress in the plan file.** Every completed task gets `[x]`. This is how resume works.
 - **Test after every task — targeted, not full suite.** Run tests related to changed files. Defer full suite + lint to completion or CI.
 - **Report deviations immediately.** Don't silently work around plan/reality mismatches.

commands/ba/plan.md

@@ -44,6 +44,7 @@ ls -la docs/brainstorms/*.md 2>/dev/null | head -10
    - Open questions (flag for resolution during planning)
    - Acceptance criteria
    - Convention compliance findings
+   - `## Locked Design` (if the brainstorm has one): reference it explicitly in any `**Code-shape decision:**` block — its interface/signatures/invariants/error modes are the anchor for code-bearing blocks. Do not paraphrase its signatures. This is *additive* — a code-shape block is still permitted with no brainstorm (it anchors to the plan's own Proposed Solution / research).
 4. **Skip the idea refinement below** — the brainstorm already answered WHAT to build
 5. **The brainstorm is the origin document.** Reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` throughout the plan. Do not paraphrase decisions in a way that loses their original context.
 6. Do not omit brainstorm content — if the brainstorm discussed it, the plan must address it.
@@ -146,7 +147,7 @@ Select based on complexity. Simpler is mostly better.
 
 **Best for:** Simple bugs, small improvements, clear features with ≤3 files.
 
-Sections: Problem/feature description, acceptance criteria, context, MVP code.
+Sections: Problem/feature description, acceptance criteria, context, MVP (decisions + pseudo-code by default; literal code only under a `**Code-shape decision:**` label).
 
 #### STANDARD (Most Features)
 
@@ -227,7 +228,8 @@ A Kent C. Dodds-style checklist of user-observable behaviors this plan must sati
 ### [filename.ext]
 
 ```language
-[Actual code — not descriptions of code]
+[Decisions: approach, exact paths, patterns to follow, pseudo-code for shape, test scenarios.
+Add a literal code block only under a **Code-shape decision:** <why the shape is non-obvious> label — see "Key rules".]
 ```
 
 ## Sources
@@ -283,7 +285,8 @@ A Kent C. Dodds-style checklist of user-observable behaviors this plan must sati
 
 **File**: `exact/path/to/file.ext`
 ```language
-[Actual code — not descriptions]
+[Decisions: approach, exact paths, patterns to follow, pseudo-code for shape, test scenarios.
+Add a literal code block only under a **Code-shape decision:** <why the shape is non-obvious> label — see "Key rules".]
 ```
 
 ### Success Criteria
@@ -351,7 +354,8 @@ A Kent C. Dodds-style checklist of user-observable behaviors this plan must sati
 #### Changes Required
 **File**: `exact/path/to/file.ext`
 ```language
-[Actual code]
+[Decisions: approach, exact paths, patterns to follow, pseudo-code for shape, test scenarios.
+Add a literal code block only under a **Code-shape decision:** <why the shape is non-obvious> label — see "Key rules".]
 ```
 
 #### Success Criteria
@@ -419,11 +423,17 @@ A Kent C. Dodds-style checklist of user-observable behaviors this plan must sati
 
 **Key rules for all templates:**
 - Include **exact file paths** — never placeholders
-- Include **actual code** — not descriptions of code
+- **Default to decisions, not code** — approach, exact file paths, patterns to follow, pseudo-code for shape, and test scenarios. Include a literal code block ONLY under a `**Code-shape decision:** <why the shape is non-obvious>` label.
 - Separate success criteria into **Automated** and **Manual**
 - Phase gates in COMPREHENSIVE: automated passes first, then pause for manual verification
 - Always include "What We're NOT Doing"
 
+**Code-shape decision rule:** Add a literal code block + label only when re-deriving the shape from a prose decision would plausibly produce a *different, wrong* structure (a specific reducer state machine, a concurrency-sensitive ordering, a tricky query window).
+- ✅ Positive: a state-machine reducer whose exact case/transition set is the decision → include it, labeled.
+- ❌ Negative: a standard CRUD handler or an obvious mapping → describe it; do not include literal code.
+- When unsure, include the code + label: a false-positive label costs a little review attention; a false-negative loses the design.
+- **Anchor:** when a brainstorm origin exists, a code-shape block anchors to the brainstorm's `## Locked Design` (interface, signatures, invariants, error modes). With no brainstorm, it anchors to the plan's own Proposed Solution / research findings.
+
 ---
 
 ## Step 5: Convention-Compliance Check
@@ -532,7 +542,7 @@ Convention compliance: [N aligned, N overrides, N debt items]
 ## Important Guidelines
 
 - **Research before writing** — understand the codebase before proposing changes
-- **Exact file paths and code** — never use placeholders
+- **Exact file paths and decisions** — never use placeholders; literal code only under a `**Code-shape decision:**` label (when unsure, include the label)
 - **Separate automated and manual verification** — different audiences, different timing
 - **"What We're NOT Doing" at every level** — prevents scope creep
 - **Convention compliance is mandatory** — not optional, not skippable

commands/ba/slice.md

@@ -63,15 +63,15 @@ Read the `detail_level` field from YAML frontmatter. If missing, infer:
 
 Based on detail level, extract the task list and estimate LoC for each:
 
-- **MINIMAL**: Each acceptance criterion checkbox is a task. Estimate LoC from the "MVP" code section -- count lines in code fences, distribute across criteria proportionally.
-- **STANDARD**: Each `**File**:` block under "Changes Required" is a task. Count lines in each file block's code fence.
-- **COMPREHENSIVE**: Each `**File**:` block within a phase is a task. Count code fence lines per block. Respect phase boundaries -- never merge tasks across phases.
+- **MINIMAL**: Each acceptance criterion checkbox is a task. Estimate LoC from the "MVP" section by applying the LoC Counting Rules below to each fence, distributing across criteria proportionally.
+- **STANDARD**: Each `**File**:` block under "Changes Required" is a task. Apply the LoC Counting Rules below to each file block's fence.
+- **COMPREHENSIVE**: Each `**File**:` block within a phase is a task. Apply the LoC Counting Rules below to each block's fence. Respect phase boundaries -- never merge tasks across phases.
 
 ### LoC Counting Rules
 
-- Count only lines inside code fences (triple-backtick blocks)
+- Count only lines inside **literal** code fences. A fence counts as literal only when it is immediately preceded by a `**Code-shape decision:**` label; any unlabeled fence is pseudo-code — do not line-count it, fall through to the estimate rule below. **Backward-compat:** if the plan has no `**Code-shape decision:**` labels anywhere (a pre-change plan), treat every fenced block as literal and count it — otherwise old plans route all code to the estimate fallback and slice under-sizes MRs. <!-- Maintainer note: keep this routing identical to execute.md Step 1.5b; both are mirrors per the CLAUDE.md Code-shape decision sync convention. -->
 - Exclude test file changes (files matching: `*.test.*`, `*.spec.*`, `*_test.*`, `test_*.*`, files under `tests/`, `__tests__/`, `test/`)
-- If a task has no code fence, estimate conservatively (~30-50 LoC per described file change) and mark as "est. approximate"
+- If a task has no literal code fence (pseudo-code/decisions only), estimate conservatively (~30-50 LoC per described file change) and mark as "est. approximate"
 - Track total estimated LoC across all tasks
 
 ### Single-Slice Check