@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/skills/shared/context-budget.md

@@ -12,10 +12,48 @@ Every skill that spawns agents or reads significant content must follow these ru
 
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
 4. **Delegate** heavy work to subagents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+**Applies to:** build, plan, review skills — any skill that reads back subagent artifacts.
+
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## State Consolidation Impact
+
+State consolidation (Phase 5) reduces core planning files from 5 to 3:
+- CONTEXT.md is now merged into PROJECT.md ## Context section
+- HISTORY.md is now merged into STATE.md ## History section
+- This reduces per-phase context loading overhead — fewer files to read, same information
+
+**File size estimates (post-consolidation):**
+- PROJECT.md: ~2-4 KB (includes Context section)
+- STATE.md: ~3-6 KB (includes History section)
+- ROADMAP.md: ~3-8 KB (depending on phase count)
+- config.json: ~1-2 KB
+
+**Note:** PROJECT.md is larger now with the merged Context section. Factor this into context budget when loading project state.
+
 ## Customization
 
 Skills should add skill-specific rules below the reference line. Common skill-specific additions:
@@ -38,3 +76,30 @@ Additionally for this skill:
 - {Skill-specific rule 1}
 - {Skill-specific rule 2}
 ```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.

package/plugins/pbr/skills/shared/context-loader-task.md

@@ -28,22 +28,28 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
     - .planning/research/SUMMARY.md (if exists)
     - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (scan for decisions relevant to current work only, do NOT summarize all history)
 
   Return ONLY the briefing text. No preamble, no suggestions."
 })
 ```
 
+### CLI Alternative
+
+Alternatively, the skill can call `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load` for structured JSON state instead of spawning a briefing Task. Use the CLI approach when only state data is needed; use the Task approach when project context (decisions, notes, history) is also needed.
+
 ### Key Rules
 
 1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
 2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
 3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
 4. **Read-only.** The briefing task must not write any files.
+5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
 
 ### Using the Briefing
 
@@ -64,9 +70,10 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (scan for decisions relevant to '{topic}' only, do NOT summarize all history)
 
   Focus on: decisions, requirements, and phase goals related to '{topic}'.
   Return ONLY the briefing text. No preamble, no suggestions."
@@ -77,10 +84,10 @@ Task({
 
 ## Variation: Scan Reconnaissance
 
-For `/pbr:scan`, the pattern adapts to codebase analysis rather than project state:
+For `/pbr:map-codebase`, the pattern adapts to codebase analysis rather than project state:
 
-1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
-2. Writes the results to `.planning/codebase/RECON.md`
-3. Passes RECON.md content to the spawned analysis agents as baseline context
+1. The orchestrator runs `init map-codebase` to get config, model, and existing map metadata
+2. Spawns 4 parallel codebase-mapper agents — each explores the codebase independently
+3. Agents write documents directly to `.planning/codebase/` (no context transfer back)
 
-This is the same principle (build context before main work) but the source is the codebase rather than planning files.
+This is the same principle (delegate heavy work to agents) but the agents self-discover rather than receiving pre-built context.

package/plugins/pbr/skills/shared/digest-select.md

@@ -64,11 +64,11 @@ These fields give downstream skills enough context to build on prior work withou
 
 ## Skill-Specific Notes
 
-### /pbr:plan
+### /pbr:plan-phase
 - Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
 - Used in Step 2: Load Context
 
-### /pbr:build
+### /pbr:execute-phase
 - Direct dependencies (completed earlier waves): frontmatter only for prior work table
 - Used in Step 6a: Spawn Executors (prior_work section of executor prompt)
 

package/plugins/pbr/skills/shared/domain-probes.md

@@ -1,6 +1,6 @@
 # Domain-Aware Probing Patterns
 
-Shared reference for `/pbr:explore`, `/pbr:begin`, and `/pbr:discuss`.
+Shared reference for `/pbr:explore`, `/pbr:new-project`, and `/pbr:discuss-phase`.
 
 When the user mentions a technology area, use these probes to ask insightful follow-up questions. Don't run through them as a checklist — pick the 2-3 most relevant based on context. The goal is to surface hidden assumptions and trade-offs the user may not have considered yet.
 

package/plugins/pbr/skills/shared/error-reporting.md

@@ -1,81 +1,59 @@
-# Error Reporting Fragment
+# Error Reporting — Standard Format
 
-Standard error display formats for all skills. Reference `references/ui-formatting.md` for the full brand guide.
+Use the branded error box for all blocking errors. Present the box, explain what happened, and give a specific fix action.
 
-## Recoverable Error
+## Error Box Format
 
-For errors that don't halt the workflow — skill can suggest a fix or retry:
-
-```
-⚠ Warning: {short description}
-
-{1-2 line explanation of what went wrong}
-
-To fix: {actionable instruction}
-```
-
-Example:
 ```
-⚠ Warning: STATE.md is 180 lines (limit: 150)
-
-The state file has grown beyond the recommended size, which increases context usage on load.
-
-To fix: Run /pbr:health to compact the Accumulated Context section.
-```
-
-## Fatal Error
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
 
-For errors that stop execution — skill cannot continue:
+{one-line description of what went wrong}
 
+**To fix:** {specific action the user should take}
 ```
-✗ Error: {short description}
 
-{1-2 line explanation}
+## Warning Format (non-blocking)
 
-What to try:
-  1. {first suggestion}
-  2. {second suggestion}
-  3. {fallback — often /pbr:health or manual fix}
 ```
-
-Example:
+⚠ {one-line warning}
+  {optional detail or suggestion}
 ```
-✗ Error: PLAN.md not found for phase 03
-
-No plan files exist in .planning/phases/03-auth/. The executor cannot run without a plan.
-
-What to try:
-  1. Run /pbr:plan 3 to create a plan first
-  2. Check if the phase directory exists: ls .planning/phases/03-*
-  3. Run /pbr:health to check planning directory integrity
-```
-
-## Validation Error
+Continue execution after showing a warning.
 
-For format or schema validation failures (config, plan format, commit message):
+## Common Error Patterns
 
-```
-✗ Validation failed: {what was validated}
+### Phase not found
+Message: "Phase {N} not found in ROADMAP.md."
+Fix: "Run `/pbr:status` to see available phases."
 
-Issues:
-  - {specific issue 1}
-  - {specific issue 2}
+### Missing prerequisites (no REQUIREMENTS.md or ROADMAP.md)
+Message: "Project not initialized. Missing REQUIREMENTS.md or ROADMAP.md."
+Fix: "Run `/pbr:new-project` first."
 
-Expected format: {brief format description or example}
-```
+### No plans found for phase
+Message: "Phase {N} has no plans."
+Fix: "Run `/pbr:plan-phase {N}` first."
 
-## Hook Block Message
+### Dependency phase not complete
+Message: "Phase {N} depends on Phase {M}, which is not complete."
+Fix: "Build Phase {M} first with `/pbr:execute-phase {M}`."
 
-For PreToolUse hooks that reject a tool call:
+### Planner agent failure
+Message: "Planner agent failed for Phase {N}."
+Fix: "Try again with `/pbr:plan-phase {N} --skip-research`. Check `.planning/PROJECT.md` for conflicting constraints."
 
-```
-Blocked: {short reason}
+### Checker loops (3+ iterations without pass)
+Message: "Plan checker failed to pass after 3 revision iterations for Phase {N}."
+Fix: "Review the remaining issues below and decide whether to proceed or revise manually. Run `/pbr:plan-phase {N}` to restart planning from scratch."
+After displaying: present remaining issues and ask user to decide (proceed or intervene).
 
-{explanation}
-
-{how to fix or alternative approach}
-```
+### Research agent failure
+Display as WARNING (non-blocking): "Research agent failed. Planning without phase-specific research. This may result in less accurate plans."
+Continue to the planning step.
 
-This format is used by validate-commit.js and check-dangerous-commands.js. The `decision: "block"` and `reason` fields in the JSON output follow this pattern.
+## Usage
 
-Block reasons should always include a "To fix:" line with actionable guidance so the user or agent knows how to resolve the block.
+In skill files, replace repeated error box content with:
+"Display a branded error box — use the format from `skills/shared/error-reporting.md`, pattern: {pattern name}."

package/plugins/pbr/skills/shared/gate-prompts.md

@@ -5,6 +5,8 @@
 
 These patterns provide consistent, structured prompts for user decision points. Skills reference these patterns by name to ensure all gate checks use the same format.
 
+**For checkpoint box format details, see `@references/ui-brand.md`** — checkpoint boxes use double-line border drawing with 62-character inner width. All gate types (approval, decision, information) should use the standardized checkpoint box format from ui-brand.md when presenting user-facing decision points.
+
 ## Rules
 
 - `header` must be max 12 characters
@@ -107,7 +109,7 @@ Use AskUserQuestion:
   header: "Escalate"
   options:
     - label: "Accept gaps"  description: "Mark as complete-with-gaps and move on"
-    - label: "Re-plan"      description: "Go back to /pbr:plan with gap context"
+    - label: "Re-plan"      description: "Go back to /pbr:plan-phase with gap context"
     - label: "Debug"        description: "Spawn /pbr:debug to investigate root causes"
     - label: "Retry"        description: "Try one more verification cycle"
   multiSelect: false
@@ -257,7 +259,7 @@ Use AskUserQuestion:
   header: "Scope"
   options:
     - label: "Quick task"  description: "Execute as lightweight task"
-    - label: "Full plan"   description: "Switch to /pbr:plan for proper planning"
+    - label: "Full plan"   description: "Switch to /pbr:plan-phase for proper planning"
     - label: "Revise"      description: "Let me rewrite the task description"
   multiSelect: false
 ```

package/plugins/pbr/skills/shared/memory-capture.md

@@ -0,0 +1,48 @@
+## Memory Capture (Post-Agent)
+
+After any agent that supports memory suggestions completes, check the agent's Task() output for `<memory_suggestion>` blocks.
+
+**Supported agents:** executor, planner, researcher, debugger.
+
+### Parsing Protocol
+
+1. Scan the agent's returned output text for `<memory_suggestion type="...">` blocks
+2. For each block found, extract:
+   - `type` attribute: one of `user`, `feedback`, `project`, `reference`
+   - `description:` line (first line of content) -- a one-line summary
+   - Remaining content after the description line -- the memory body
+3. If **0 suggestions** found: skip silently, proceed with normal flow
+4. If **1-2 suggestions** found: save each immediately (see Saving below)
+5. If **3+ suggestions** found: display them to the user and ask via AskUserQuestion which to save (the agent may be over-suggesting)
+
+### Saving
+
+For each suggestion to save:
+
+1. Generate a slug from the description (first 4 words, lowercase, hyphenated)
+2. Determine the target directory:
+   - `project` or `reference` type -> `.planning/memory/{slug}.md` (project-scoped, survives with .planning/)
+   - `user` or `feedback` type -> use the Write tool to save to the auto-memory directory
+3. Write the file with standard frontmatter:
+
+       ---
+       name: {slug}
+       description: "{description from the suggestion}"
+       type: {type from the suggestion}
+       ---
+
+       {memory content body}
+
+4. Update MEMORY.md index if saving to auto-memory directory
+
+### When to Skip
+
+- If the agent failed (PLAN FAILED, DEBUG FAILED, etc.) -- do not process suggestions from failed runs
+- If the suggestion content is clearly ephemeral (mentions "this task", "current file", etc.) -- skip it
+- If a memory with very similar content already exists -- skip to avoid duplicates
+
+### Anti-Patterns
+
+- DO NOT save every suggestion blindly -- quality over quantity
+- DO NOT save task-specific details as memory -- only reusable knowledge
+- DO NOT block the workflow waiting for memory saves -- this is a post-completion step

package/plugins/pbr/skills/shared/phase-argument-parsing.md

@@ -24,9 +24,9 @@ Input       → Normalized  → Directory Name
 1. Phase number must be numeric (integer or decimal with one decimal place)
 2. Phase must exist in ROADMAP.md (or be a valid target for insert/add)
 3. Phase must be in the expected state for the operation:
-   - `/pbr:plan N` — phase must not already have plans (unless re-planning)
-   - `/pbr:build N` — phase must have plans
-   - `/pbr:review N` — phase must have been built (SUMMARY.md files exist)
+   - `/pbr:plan-phase N` — phase must not already have plans (unless re-planning)
+   - `/pbr:execute-phase N` — phase must have plans
+   - `/pbr:verify-work N` — phase must have been built (SUMMARY.md files exist)
 
 ## Finding Phase Directory
 
@@ -42,4 +42,4 @@ Given phase number N:
 
 - No argument and no current phase: "Which phase? Specify a number or run /pbr:status to see where you are."
 - Phase not found: "Phase {N} not found in .planning/phases/. Run /pbr:status to see available phases."
-- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan {N} first."
+- Wrong state: "Phase {N} hasn't been planned yet. Run /pbr:plan-phase {N} first."

package/plugins/pbr/skills/shared/revision-loop.md

@@ -16,6 +16,7 @@ This pattern applies whenever:
 ### Flow
 
 ```
+prev_issue_count = Infinity
 iteration = 0
 
 LOOP:
@@ -27,18 +28,33 @@ LOOP:
      a. iteration += 1
      b. If iteration > 3:
         → Escalate to user (see "After 3 Iterations" below)
-     c. Re-spawn the producing agent with checker feedback appended
-     d. After revision completes, go to LOOP
+     c. Parse issue count from checker output
+     d. If issue_count >= prev_issue_count:
+        → Escalate to user: "Revision loop stalled (issue count not decreasing)"
+     e. prev_issue_count = issue_count
+     f. Re-spawn the producing agent with checker feedback appended
+     g. After revision completes, go to LOOP
 ```
 
+### Issue Count Tracking
+
+Track the number of BLOCKER + WARNING issues returned by the checker on each iteration. If the count does not decrease between consecutive iterations, the producing agent is stuck and further iterations will not help. Break early and escalate to the user.
+
+Display iteration progress before each revision spawn:
+`◆ Revision iteration {N}/3 — {blocker_count} blockers, {warning_count} warnings`
+
 ### Re-spawn Prompt Structure
 
-When re-spawning the producing agent for revision, append the checker feedback:
+When re-spawning the producing agent for revision, pass the checker's YAML-formatted issues. The checker's output contains a `## Issues` heading followed by a YAML block. Parse this block and pass it verbatim to the revision agent.
 
 ```
-<checker_feedback>
-{Inline the checker's issue report}
-</checker_feedback>
+<checker_issues>
+The issues below are in YAML format. Each has: dimension, severity, finding,
+affected_field, suggested_fix. Address ALL BLOCKER issues. Address WARNING
+issues where feasible.
+
+{YAML issues block from checker output — passed verbatim}
+</checker_issues>
 
 <revision_instructions>
 Address ALL BLOCKER and WARNING issues identified above.
@@ -46,6 +62,8 @@ Address ALL BLOCKER and WARNING issues identified above.
 - For each WARNING: address or explain why it's acceptable
 - Do NOT introduce new issues while fixing existing ones
 - Preserve all content not flagged by the checker
+This is revision iteration {N} of max 3. Previous iteration had {prev_count}
+issues. You must reduce the count or the loop will terminate.
 </revision_instructions>
 ```
 

package/plugins/pbr/skills/shared/state-update.md

@@ -1,19 +1,38 @@
 # STATE.md Update Pattern
 
-Standard pattern for updating `.planning/STATE.md`. Include this fragment in skills that modify project state.
+Standard pattern for updating `.planning/STATE.md`. CLI commands handle both YAML frontmatter and markdown body atomically. Skills and agents call `pbr-tools.js` commands instead of writing STATE.md directly.
+
+> Referenced by: build, plan, review, milestone, pause, resume, continue, begin, import, quick skills
+
+---
+
+## CLI Command Reference
+
+All commands use: `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command>`
+
+| Action | CLI Command | What It Updates |
+|--------|------------|-----------------|
+| Update single field | `state update <field> <value>` | Frontmatter field + body line |
+| Update multiple fields | `state patch '{"field":"value",...}'` | Multiple frontmatter fields + body lines atomically |
+| Advance plan counter | `state advance-plan` | `plans_complete` + `progress_percent` in frontmatter and body |
+| Recalculate progress | `state update-progress` | `progress_percent` from disk (counts plans vs summaries) |
+| Complete a phase | `phase complete <N>` | STATE.md (advance phase, reset plans) + ROADMAP.md (checkbox, table) |
+| Record activity | `state record-activity "<desc>"` | `last_activity` with today's date + description |
+| Load full state | `state load` | Returns JSON -- does not write |
 
 ---
 
-## When to Update STATE.md
+## When to Use Each Command
 
-| Event | What to Update |
-|-------|---------------|
-| Phase status changes (planned, building, verified) | Current Position section |
-| Plan completes or fails | Plan counter, status, last activity |
-| New decision made | Accumulated Context > Decisions |
-| Blocker discovered or resolved | Accumulated Context > Blockers/Concerns |
-| Session starts or ends | Session Continuity section |
-| Milestone boundary | Milestone section |
+| Event | CLI Command |
+|-------|------------|
+| Plan completes | `state advance-plan` then `state update-progress` |
+| Phase status changes | `state update status <value>` |
+| Phase fully built and verified | `phase complete <N>` |
+| After any state mutation | `state record-activity "<what happened>"` |
+| Session starts (read only) | `state load` |
+| New decision made | Edit STATE.md "Accumulated Context > Decisions" section directly (CLI does not manage this section) |
+| Blocker discovered | Edit STATE.md "Accumulated Context > Blockers" section directly |
 
 ---
 
@@ -45,7 +64,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```
@@ -88,74 +107,48 @@ Resume file: {path or "None"}
    Phase 1: verified 2026-02-08
    Phase 2: verified 2026-02-09
    ```
-2. **Remove decisions already captured in CONTEXT.md** — avoid duplication between STATE.md and phase CONTEXT.md files
-3. **Remove old session entries** — keep only the current session's continuity data
+2. **Remove decisions already captured in phase CONTEXT.md files** -- avoid duplication between STATE.md and phase-level CONTEXT.md
+3. **Remove old session entries** -- keep only the current session's continuity data
 4. **Keep these always:** current phase detail, active blockers, core value statement, milestone info
 
 If still over 150 lines after compaction, the Accumulated Context section has grown too large. Move non-critical decisions to the phase's CONTEXT.md file.
 
 ---
 
-## HISTORY.md Archival
+## History Archival
 
-When a milestone completes or a phase is verified, archive historical context to `.planning/HISTORY.md` to keep STATE.md lean:
+When a milestone completes or a phase is verified, archive historical context to the STATE.md ## History section to keep the Accumulated Context section lean:
 
 ### What to Archive
 
-| Trigger | What moves to HISTORY.md |
-|---------|-------------------------|
+| Trigger | What moves to STATE.md ## History |
+|---------|----------------------------------|
 | Phase verified | One-liner summary: "Phase {N} ({name}): verified {date}" |
 | Milestone complete | Full milestone record: name, phases covered, key decisions |
-| Accumulated Context > 20 lines | Decisions from completed phases (keep only current-phase decisions in STATE.md) |
+| Accumulated Context > 20 lines | Decisions from completed phases (keep only current-phase decisions in Accumulated Context) |
 
 ### How to Archive
 
-Use `pbr-tools.js history append`:
+Use `pbr-tools.js` to append to STATE.md ## History:
+
 ```
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "Phase 3 (Auth)" "Verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 User Auth" "Phases 1-4. All verified. Core auth flow complete."
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-activity "Phase 3 (Auth): verified 2026-02-10. Key decisions: JWT + httpOnly cookies, Discord OAuth."
 ```
 
 ### After Archiving
 
-Remove the archived content from STATE.md. The Accumulated Context section should contain ONLY:
+Remove the archived content from the Accumulated Context section. It should contain ONLY:
+
 - Decisions relevant to the **current** phase
 - Active (unresolved) blockers
 - Pending todos for the current milestone
 
-Historical decisions live in HISTORY.md and per-phase SUMMARY.md files.
+Historical decisions live in STATE.md ## History and per-phase SUMMARY.md files.
 
 ---
 
-## Common Update Scenarios
-
-### After build completes
-```
-Plan: {N} of {total} in current phase
-Status: Building → Reviewing (if all plans done) or Building (if more plans remain)
-Last activity: {date} -- Built plan {plan_id}
-```
+## Anti-Pattern
 
-### After review/verification passes
-```
-Status: Verified
-Last activity: {date} -- Phase {N} verified
-Progress: [{updated bar}] {new percent}%
-```
-Also update **Current focus** to point to the next phase.
-
-### After pause
-```
-## Session Continuity
-Last session: {timestamp}
-Stopped at: {what was in progress}
-Resume file: .planning/.pause-state.json
-```
-
-### After milestone completion
-```
-## Milestone
-Current: {project_name} {next_version}
-Phases: {new_start}-{new_end}
-Status: In progress
-```
+> **DO NOT** use Write or Edit to modify STATE.md frontmatter or the Current Position body section.
+> Always use CLI commands. They ensure frontmatter and body stay in sync.
+> **Exception:** Accumulated Context sections (Decisions, Blockers, Todos) are edited directly since they are freeform text.