@sienklogic/plan-build-run 2.19.0 → 2.19.1

package/plugins/pbr/skills/session-report/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: session-report
+description: "Generate post-session summary with work performed, outcomes, and resource usage."
+allowed-tools: Read, Bash, Glob, Grep, AskUserQuestion
+argument-hint: "[--since <time>] [--save]"
+---
+
+**STOP -- DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing Step 1 immediately.**
+
+# /pbr:session-report -- Post-Session Summary
+
+**References:** `@references/ui-brand.md`
+
+You are the orchestrator for `/pbr:session-report`. This read-only skill generates a summary of work performed during the current session. By default it displays the report without writing files.
+
+## Step 0 -- Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
++--------------------------------------------------------------+
+|  PLAN-BUILD-RUN > SESSION REPORT                             |
++--------------------------------------------------------------+
+```
+
+Then proceed to Step 1.
+
+## Step 1: Parse Arguments
+
+1. Parse `$ARGUMENTS` for optional flags:
+   - `--since <time>` -- git log time filter (default: "8 hours ago")
+   - `--save` -- write report to `.planning/reports/session-{date}.md`
+2. Compute the time window for analysis
+
+## Step 2: Gather Session Data
+
+1. Read `.planning/STATE.md` for current position (phase, plan, status)
+2. Count commits in time window:
+   ```bash
+   git log --oneline --since="{since}" --format="%H %s"
+   ```
+3. Get file change stats:
+   ```bash
+   git diff --stat HEAD~{commit_count}..HEAD 2>/dev/null || git diff --stat --since="{since}"
+   ```
+4. Read SUMMARY-*.md files modified during this session:
+   ```bash
+   git log --since="{since}" --diff-filter=AM --name-only --format="" -- ".planning/phases/*/SUMMARY-*.md"
+   ```
+   Extract status and key outcomes from each.
+5. Check for VERIFICATION.md updates:
+   ```bash
+   git log --since="{since}" --diff-filter=AM --name-only --format="" -- ".planning/phases/*/VERIFICATION.md"
+   ```
+6. Check test results if a test command was run recently:
+   ```bash
+   git log --since="{since}" --oneline --grep="test"
+   ```
+
+## Step 3: Compute Metrics
+
+1. **Commit breakdown**: count commits by type (feat, fix, refactor, test, docs, chore)
+2. **File breakdown**: count files by directory/category
+3. **Phase progress**: compare STATE.md current plan vs total plans
+4. **Velocity**: commits per hour estimate
+
+## Step 4: Generate Report
+
+Display the report:
+
+```
+SESSION REPORT
+==============
+
+Session Window:  {since} to now ({duration} estimate)
+Current Phase:   {phase_number} - {phase_name}
+Current Status:  {status}
+
+WORK PERFORMED
+--------------
+Commits:         {total_count}
+  feat:          {feat_count}
+  fix:           {fix_count}
+  refactor:      {refactor_count}
+  test:          {test_count}
+  other:         {other_count}
+
+Files Changed:   {file_count}
+  Insertions:    +{insertions}
+  Deletions:     -{deletions}
+
+PLAN PROGRESS
+-------------
+{For each SUMMARY written during session:}
+  Plan {NN}: {status} - {one-liner}
+
+VERIFICATION
+------------
+{If VERIFICATION.md was updated:}
+  Score:         {score}
+  Status:        {status}
+{Else:}
+  No verification updates this session.
+
+NEXT STEPS
+----------
+{Based on STATE.md status, suggest the logical next command:}
+  - If status is "planned": /pbr:build {N}
+  - If status is "executing": /pbr:build {N} (continue)
+  - If status is "verifying": /pbr:review {N}
+  - If status is "complete": /pbr:milestone or /pbr:plan {N+1}
+```
+
+## Step 5: Optional Save
+
+If `--save` flag was provided:
+**CRITICAL: Create the reports directory and write the report file NOW.**
+
+1. Create directory: `.planning/reports/` (if not exists)
+2. Write report to `.planning/reports/session-{YYYY-MM-DD-HHmm}.md`
+3. Display: "Report saved to {path}"
+
+If `--save` was NOT provided:
+- Display only. Do not write any files.
+
+## Error Handling
+
+- No commits in time window: "No commits found since {since}. Try --since '24 hours ago'."
+- No STATE.md: "No .planning directory found. Run /pbr:new-project first."
+- Git not available: stop with error

package/plugins/pbr/skills/setup/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
 allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 ---
 
-**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes tokens. Begin executing Step 1 immediately.**
 
 ## Step 0 — Immediate Output
 
@@ -12,190 +12,56 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SETUP                                      ║
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
 ╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:setup — Plan-Build-Run Setup Wizard
+# /pbr:setup — Plan-Build-Run Reconfigure
 
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
 
 ---
 
-## Step 1: Detect Project State — Idempotency Guard
+## Step 1: Detect Project State
 
-Check if `.planning/` directory exists in the current working directory.
-
-**If `.planning/` exists**:
-- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
-- If ANY of these exist, present a checkpoint:
-
-  Use AskUserQuestion:
-    question: "Existing project detected with {list of found files}. How should we proceed?"
-    header: "Setup"
-    options:
-      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
-      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
-      - label: "Abort"        description: "Cancel setup — keep everything as-is"
-
-  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
-  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
-  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
-
-- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
-  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
-  - Continue to fresh setup below
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
+Check if `.planning/config.json` exists.
 
+**If `.planning/config.json` does NOT exist:**
+Display:
 ```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
+No Plan-Build-Run project found in this directory.
 
-**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
+/pbr:setup is for reconfiguring existing projects.
+To start a new project, run: /pbr:new-project
 
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+/pbr:new-project includes everything /pbr:setup used to do, plus deep requirements gathering and roadmap creation.
 ```
+Stop. Do not proceed further.
 
-**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
-
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "sonnet"
-  },
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2,
-    "use_teams": false
-  },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
-  },
-  "git": {
-    "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
-  },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
-  }
-}
-```
-
-**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
-
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
-```
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
 
 ---
 
-## Step 2: Project Type (new projects only)
+## Step 2: Model Selection
 
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
-
-Update config.json with any changes.
-
----
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
 
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
   header: "Models"
   options:
     - label: "Balanced (Recommended)"
@@ -204,19 +70,20 @@ AskUserQuestion:
       description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
     - label: "Budget"
       description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
 
-Apply the selected profile to `config.json`:
-- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
-- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
-- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet, context_window_tokens=1000000, agent_checkpoint_pct=65, extended_context=true
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Keep current**: no change to models block, no change to context_window_tokens
 
 ---
 
-## Step 4: Workflow Preferences
+## Step 3: Workflow Features
 
-```
-AskUserQuestion:
+Use AskUserQuestion:
   question: "Which workflow features do you want enabled?"
   header: "Features"
   multiSelect: true
@@ -229,9 +96,8 @@ AskUserQuestion:
       description: "Require verification AND review to pass before advancing phases"
     - label: "Git branching"
       description: "Create a branch per phase for cleaner PR history"
-```
 
-Apply selections:
+Apply selections (others unchanged):
 - **Auto-continue**: Set `features.auto_continue: true`
 - **TDD mode**: Set `features.tdd_mode: true`
 - **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
@@ -239,15 +105,23 @@ Apply selections:
 
 ---
 
-## Step 4b: CLAUDE.md Integration
+## Step 4: CLAUDE.md Integration
 
 Check if a `CLAUDE.md` file exists in the project root.
 
-**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
-**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
 
-Append/create this content:
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
 
+If "Yes", append/create:
 ```markdown
 ## Plan-Build-Run
 
@@ -255,45 +129,118 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 - Project state: `.planning/STATE.md` (source of truth for current phase and progress)
 - Configuration: `.planning/config.json`
-- Run `/pbr:status` to see current project state and suggested next action.
+- Run `/pbr:progress` to see current project state and suggested next action.
 
 **After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 ```
 
 ---
 
-## Step 5: Verification
+## Step 5: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
+
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
+
+Display the report:
+
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
+
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
+```
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent /pbr:setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: Write Updated Config
 
-**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
 
-Run a quick health check:
+Write the updated config.json to disk with all applied changes.
 
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
+### Commit Changes
 
-Display results:
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
 
+If `planning.commit_docs` is true in config.json, commit modified files:
+
+```text
+docs(setup): reconfigure project — {changed_settings}
 ```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
+
+---
+
+## Step 7: Verification
+
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
+
+Display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
+
+Run /pbr:progress to see current project state.
 ```
 
 ---
 
 ## Error Handling
 
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
 - If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/agent-context-enrichment.md

@@ -0,0 +1,21 @@
+## Agent Context Enrichment
+
+When spawning a Task() executor or other subagent, enrich the spawn prompt with project context if `features.rich_agent_prompts` is enabled in config.
+
+### How to Use
+
+Before spawning Task(), call the enrichment modules:
+
+1. **Rich context** (from `lib/gates/rich-agent-context.js`):
+   - `buildRichAgentContext(planningDir, config, 5000)` returns a markdown string with project summary, state, decisions, conventions.
+   - Append this to the Task() prompt under a `## Project Context` header.
+
+2. **Multi-phase plans** (from `lib/gates/multi-phase-loader.js`):
+   - `loadMultiPhasePlans(planningDir, currentPhase, config)` returns plans from adjacent phases.
+   - Include the current phase plans in full. Include adjacent phase plans as frontmatter summaries only (first 30 lines).
+
+### Budget Control
+
+- Rich context defaults to 5000 chars (~1250 tokens). Adjust via `budgetChars` parameter.
+- Multi-phase loading is bounded by `workflow.max_phases_in_context` (default 3).
+- If orchestrator context is above 50%, reduce budgetChars to 2500.

package/plugins/pbr/skills/shared/agent-type-resolution.md

@@ -0,0 +1,32 @@
+# Agent Type Resolution
+
+PBR agents register under two naming formats depending on how the plugin loads:
+
+- **Plugin format**: `pbr:{name}` (e.g., `pbr:executor`) — when Claude Code loads agents from the plugin's `agents/` directory
+- **Standalone format**: `pbr-{name}` (e.g., `pbr-executor`) — when agents load from a root `agents/` directory
+
+**Resolution rule**: Always use `pbr:{name}` first. If the Task() spawn fails with "Agent type not found", retry the same Task() call with `pbr-{name}`. Do not change anything else in the prompt — only the `subagent_type` value.
+
+Example:
+
+```
+# First attempt (plugin format)
+Task({ subagent_type: "pbr:executor", prompt: ... })
+
+# If "Agent type not found" error, retry with:
+Task({ subagent_type: "pbr-executor", prompt: ... })
+```
+
+This applies to ALL `pbr:*` agent spawns: executor, verifier, planner, researcher, synthesizer, debugger, codebase-mapper, plan-checker, integration-checker, intel-updater, audit, general, ui-checker, ui-researcher.
+
+---
+
+## Individual Spawn Rule
+
+When spawning multiple agents in parallel, each agent MUST be a separate Task() tool call in a single response message.
+
+**Why:** Claude Code assigns colored name badges and independent ctrl+o expansion to each individual Task() call. When multiple agents are described in prose ("launched 5 executors"), they appear as flat text without badges or expandable status.
+
+**Rule:** Make N separate Task() tool calls — do NOT describe the batch in prose. Multiple Task() calls in one message still run concurrently. No parallelism is lost.
+
+**Exception:** Bare `Task()` calls without `subagent_type` (e.g., context-loader briefings per `context-loader-task.md`) are exempt — they are lightweight read-only tasks that do not benefit from colored badges.

package/plugins/pbr/skills/shared/commit-planning-docs.md

@@ -16,6 +16,14 @@ If `planning.commit_docs: false` or config.json missing:
 - Skip the commit step
 ```
 
+**Note:** CLI state commands (`state advance-plan`, `phase complete`, `state update-progress`) automatically update STATE.md and ROADMAP.md. The commit step here covers planning artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md), not state files -- those are updated atomically by CLI commands.
+
+## Session Affinity
+
+When a session ID is available (from `.planning/.session.json`), append `[session:{short_id}]` to the commit description, where `short_id` is the first 8 characters of the session_id. This enables conflict tracing when multiple sessions modify planning docs concurrently.
+
+Example: `docs(planning): capture phase 3 discussion decisions [session:a1b2c3d4]`
+
 ## Commit Messages by Skill
 
 | Skill | Commit message format |