@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/plugins/pbr/scripts/worktree-create.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+/**
+ * WorktreeCreate hook: Initializes .planning/ directory structure in new git worktrees.
+ *
+ * Fires when a new git worktree is created. Copies the minimal .planning/ structure
+ * from the parent project so PBR skills work correctly in the new worktree context.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) { /* empty or non-JSON stdin */ }
+  return {};
+}
+
+function main() {
+  try {
+    const data = readStdin();
+
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const parentRoot = data.project_root || process.env.PBR_PROJECT_ROOT || process.cwd();
+
+    const planningDir = path.join(worktreePath, '.planning');
+    const parentPlanningDir = path.join(parentRoot, '.planning');
+
+    // Skip if parent has no .planning/ — not a PBR project
+    if (!fs.existsSync(parentPlanningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-no-parent', { worktree_path: worktreePath });
+      process.stdout.write(JSON.stringify({ additionalContext: '[Plan-Build-Run] Worktree skip — no parent .planning/ found.' }));
+      process.exit(0); return;
+    }
+
+    // Skip if worktree already has .planning/ initialized
+    if (fs.existsSync(planningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-exists', { worktree_path: worktreePath });
+      process.stdout.write(JSON.stringify({ additionalContext: '[Plan-Build-Run] Worktree .planning/ already initialized.' }));
+      process.exit(0); return;
+    }
+
+    // Create .planning/ directory
+    fs.mkdirSync(planningDir, { recursive: true });
+
+    // Create .planning/logs/ directory
+    fs.mkdirSync(path.join(planningDir, 'logs'), { recursive: true });
+
+    // Write a minimal STATE.md
+    const stateMd = `# STATE
+
+## Current Position
+phase: (none)
+status: Worktree initialized — run /pbr:resume-work or /pbr:progress for project state.
+
+## Source
+parent: ${parentRoot}
+initialized: ${new Date().toISOString()}
+`;
+    fs.writeFileSync(path.join(planningDir, 'STATE.md'), stateMd, 'utf8');
+
+    // Copy config.json from parent if it exists
+    try {
+      const srcConfig = path.join(parentPlanningDir, 'config.json');
+      const destConfig = path.join(planningDir, 'config.json');
+      if (fs.existsSync(srcConfig)) {
+        fs.copyFileSync(srcConfig, destConfig);
+      }
+    } catch (_e) { /* non-fatal — config copy is best-effort */ }
+
+    logHook('worktree-create', 'WorktreeCreate', 'initialized', {
+      worktree_path: worktreePath,
+      parent_root: parentRoot
+    });
+
+    process.stdout.write(JSON.stringify({
+      additionalContext: '[Plan-Build-Run] Worktree .planning/ initialized. Run /pbr:progress to see project state.'
+    }));
+
+    process.exit(0);
+  } catch (err) {
+    logHook('worktree-create', 'WorktreeCreate', 'error', { error: err.message });
+    process.stdout.write(JSON.stringify({ additionalContext: `[Plan-Build-Run] Worktree init error: ${err.message}` }));
+    process.exit(0);
+  }
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns { additionalContext: "..." } or null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = (reqBody && reqBody.data) || {};
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const parentRoot = data.project_root || process.env.PBR_PROJECT_ROOT || process.cwd();
+
+    const planningDir = path.join(worktreePath, '.planning');
+    const parentPlanningDir = path.join(parentRoot, '.planning');
+
+    if (!fs.existsSync(parentPlanningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-no-parent', { worktree_path: worktreePath });
+      return { additionalContext: '[Plan-Build-Run] Worktree skip — no parent .planning/ found.' };
+    }
+
+    if (fs.existsSync(planningDir)) {
+      logHook('worktree-create', 'WorktreeCreate', 'skip-exists', { worktree_path: worktreePath });
+      return { additionalContext: '[Plan-Build-Run] Worktree .planning/ already initialized.' };
+    }
+
+    fs.mkdirSync(planningDir, { recursive: true });
+    fs.mkdirSync(path.join(planningDir, 'logs'), { recursive: true });
+
+    const stateMd = `# STATE\n\n## Current Position\nphase: (none)\nstatus: Worktree initialized — run /pbr:resume-work or /pbr:progress for project state.\n\n## Source\nparent: ${parentRoot}\ninitialized: ${new Date().toISOString()}\n`;
+    fs.writeFileSync(path.join(planningDir, 'STATE.md'), stateMd, 'utf8');
+
+    try {
+      const srcConfig = path.join(parentPlanningDir, 'config.json');
+      const destConfig = path.join(planningDir, 'config.json');
+      if (fs.existsSync(srcConfig)) fs.copyFileSync(srcConfig, destConfig);
+    } catch (_e) { /* non-fatal */ }
+
+    logHook('worktree-create', 'WorktreeCreate', 'initialized', {
+      worktree_path: worktreePath,
+      parent_root: parentRoot
+    });
+
+    return { additionalContext: '[Plan-Build-Run] Worktree .planning/ initialized. Run /pbr:progress to see project state.' };
+  } catch (err) {
+    logHook('worktree-create', 'WorktreeCreate', 'error', { error: err.message });
+    return { additionalContext: `[Plan-Build-Run] Worktree init error: ${err.message}` };
+  }
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };

package/plugins/pbr/scripts/worktree-remove.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * WorktreeRemove hook: Cleans up worktree-specific .planning/ state on git worktree removal.
+ *
+ * Fires when a git worktree is removed. Performs non-destructive cleanup of
+ * session-specific files only. Guards against accidentally cleaning the parent
+ * project's .planning/ directory.
+ *
+ * Non-blocking — always exits 0.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+function readStdin() {
+  try {
+    const input = fs.readFileSync(0, 'utf8').trim();
+    if (input) return JSON.parse(input);
+  } catch (_e) { /* empty or non-JSON stdin */ }
+  return {};
+}
+
+function main() {
+  try {
+    const data = readStdin();
+
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const planningDir = path.join(worktreePath, '.planning');
+
+    // Skip if no .planning/ exists in worktree
+    if (!fs.existsSync(planningDir)) {
+      logHook('worktree-remove', 'WorktreeRemove', 'skip-no-planning', { worktree_path: worktreePath });
+      process.stdout.write('{}');
+      process.exit(0); return;
+    }
+
+    // Guard: only clean up if STATE.md has the "parent:" marker — this indicates
+    // it was initialized by worktree-create.js and is safe to clean up.
+    // If STATE.md has no "parent:" line, this might be the parent project itself.
+    const stateMdPath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(stateMdPath)) {
+      const stateContent = fs.readFileSync(stateMdPath, 'utf8');
+      if (!stateContent.includes('parent:')) {
+        logHook('worktree-remove', 'WorktreeRemove', 'skip-not-worktree', { worktree_path: worktreePath });
+        process.stdout.write('{}');
+        process.exit(0); return;
+      }
+    }
+
+    // Non-destructive cleanup: remove session-specific files only
+    const sessionFiles = [
+      '.session.json',
+      '.session-start',
+      '.active-skill',
+      '.auto-next'
+    ];
+
+    for (const filename of sessionFiles) {
+      try {
+        const filePath = path.join(planningDir, filename);
+        if (fs.existsSync(filePath)) {
+          fs.unlinkSync(filePath);
+        }
+      } catch (_e) { /* non-fatal — best-effort cleanup */ }
+    }
+
+    // Remove .sessions/ directory (session-scoped state)
+    try {
+      const sessionsDir = path.join(planningDir, '.sessions');
+      if (fs.existsSync(sessionsDir)) {
+        fs.rmSync(sessionsDir, { recursive: true, force: true });
+      }
+    } catch (_e) { /* non-fatal — best-effort cleanup */ }
+
+    logHook('worktree-remove', 'WorktreeRemove', 'cleaned', {
+      worktree_path: worktreePath,
+      files_removed: ['session files']
+    });
+
+    process.stdout.write('{}');
+    process.exit(0);
+  } catch (err) {
+    logHook('worktree-remove', 'WorktreeRemove', 'error', { error: err.message });
+    process.stdout.write(JSON.stringify({ additionalContext: '⚠ [PBR] worktree-remove failed: ' + err.message }));
+    process.exit(0);
+  }
+}
+
+/**
+ * handleHttp — hook-server.js interface.
+ * reqBody = { event, tool, data, planningDir, cache }
+ * Returns null. Never calls process.exit().
+ */
+function handleHttp(reqBody) {
+  try {
+    const data = (reqBody && reqBody.data) || {};
+    const worktreePath = data.worktree_path || process.env.PBR_PROJECT_ROOT || process.cwd();
+    const planningDir = path.join(worktreePath, '.planning');
+
+    if (!fs.existsSync(planningDir)) {
+      logHook('worktree-remove', 'WorktreeRemove', 'skip-no-planning', { worktree_path: worktreePath });
+      return {};
+    }
+
+    const stateMdPath = path.join(planningDir, 'STATE.md');
+    if (fs.existsSync(stateMdPath)) {
+      const stateContent = fs.readFileSync(stateMdPath, 'utf8');
+      if (!stateContent.includes('parent:')) {
+        logHook('worktree-remove', 'WorktreeRemove', 'skip-not-worktree', { worktree_path: worktreePath });
+        return {};
+      }
+    }
+
+    const sessionFiles = ['.session.json', '.session-start', '.active-skill', '.auto-next'];
+    for (const filename of sessionFiles) {
+      try {
+        const filePath = path.join(planningDir, filename);
+        if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+      } catch (_e) { /* non-fatal */ }
+    }
+
+    // Remove .sessions/ directory (session-scoped state)
+    try {
+      const sessionsDir = path.join(planningDir, '.sessions');
+      if (fs.existsSync(sessionsDir)) {
+        fs.rmSync(sessionsDir, { recursive: true, force: true });
+      }
+    } catch (_e) { /* non-fatal */ }
+
+    logHook('worktree-remove', 'WorktreeRemove', 'cleaned', {
+      worktree_path: worktreePath,
+      files_removed: ['session files']
+    });
+
+    return {};
+  } catch (err) {
+    logHook('worktree-remove', 'WorktreeRemove', 'error', { error: err.message });
+    return {};
+  }
+}
+
+if (require.main === module || process.argv[1] === __filename) { main(); }
+module.exports = { main, handleHttp };

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

@@ -2,7 +2,7 @@
 name: audit
 description: "Review past Claude Code sessions for PBR workflow compliance and UX quality."
 allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
-argument-hint: "[--from DATE] [--to DATE] [--today] [--mode compliance|ux|full]"
+argument-hint: "[--from DATE] [--to DATE] [--today] [--mode compliance|ux|full] [--preset minimal|standard|comprehensive] [--dimension ID...] [--skip ID...] [--only ID...]"
 ---
 
 **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 0 immediately.**
@@ -30,6 +30,7 @@ This skill uses **parallel Task() delegation** to analyze multiple sessions simu
 ## Context Budget
 
 Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
 
 Additionally for this skill:
 - **Delegate ALL session analysis** to audit subagents — do NOT read JSONL files in main context
@@ -48,6 +49,10 @@ Parse `$ARGUMENTS` for:
 | `--to DATE` | Now | End of audit window |
 | `--today` | false | Shorthand for `--from` start of today `--to` now |
 | `--mode MODE` | `full` | `compliance` = workflow only, `ux` = user experience only, `full` = both |
+| `--preset PRESET` | config.json audit.preset | Override audit preset (minimal/standard/comprehensive) |
+| `--dimension ID` | (none) | Add specific dimension(s) to the active set. Accepts code (SI-01) or slug (skill-template-refs). Repeatable. |
+| `--skip ID` | (none) | Remove specific dimension(s) from the active set. Accepts code or slug. Repeatable. |
+| `--only ID` | (none) | Run ONLY these dimensions, ignoring preset/categories. Accepts code or slug. Repeatable. |
 
 **Natural language parsing**: Accept formats like:
 - `--today` or just `today`
@@ -67,6 +72,38 @@ Mode: {mode}
 
 ---
 
+## Step 1b — Resolve Dimensions
+
+Load the project's `config.json` audit section. Build `cliFlags` from parsed arguments:
+
+```javascript
+const cliFlags = {
+  preset: parsedArgs.preset,       // string or undefined
+  dimension: parsedArgs.dimension, // array of ID/slug strings or undefined
+  skip: parsedArgs.skip,           // array of ID/slug strings or undefined
+  only: parsedArgs.only,           // array of ID/slug strings or undefined
+};
+```
+
+Call `audit-dimensions.js` `resolveDimensions(config, cliFlags)` to compute the active dimension set.
+
+Display the resolution summary:
+
+```
+Preset: {preset} ({N} base dimensions)
+Active dimensions: {N} ({breakdown by category, e.g., "SI: 15, IH: 10, EF: 7, WC: 12"})
+```
+
+If `--dimension` or `--skip` was used, also display:
+
+```
+Adjustments: +{added} -{removed}
+```
+
+Store the resolved dimension list for use in Step 4.
+
+---
+
 ## Step 2 — Discover Session Logs
 
 Session JSONL files live at:
@@ -85,6 +122,14 @@ find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 \
   -newermt "{from_datetime}" ! -newermt "{to_datetime}" | sort
 ```
 
+**CRITICAL — Exclude Current Session**: Before proceeding, determine the current session ID:
+
+1. The current session's JSONL file is the most recently modified `.jsonl` in the project directory that is actively being written to (i.e., THIS session)
+2. Identify it by checking which session file has been modified within the last 60 seconds: `find ~/.claude/projects/{encoded-path}/ -name "*.jsonl" -maxdepth 1 -mmin -1 2>/dev/null`
+3. Remove the current session from the discovered sessions list
+4. Display: `Excluding current session {id} from analysis (self-referential)`
+5. If no sessions remain after exclusion, show the "no sessions found" error
+
 For each session file found, also check for subagent logs:
 ```bash
 ls ~/.claude/projects/{encoded-path}/{session-id}/subagents/*.jsonl 2>/dev/null
@@ -132,29 +177,64 @@ This data feeds into the final report synthesis.
 
 **CRITICAL**: Spawn one `pbr:audit` agent per session, ALL in parallel. Do NOT analyze sessions sequentially.
 
+### 4a. Discover Insights Report
+
+Before spawning agents, check for a recent insights report:
+
+```bash
+ls -t ~/.claude/insights/*.html 2>/dev/null | head -1
+```
+
+If a file exists and was modified within the last 30 days, store its absolute path as `insights_report_path`. Otherwise set to `'none'`.
+
+### 4b. Compute Spawn Parameters
+
+Compute paths for the spawn prompt:
+- **Plugin root**: absolute path to `plugins/pbr` (e.g., `D:/Repos/plan-build-run/plugins/pbr`)
+- **Planning dir**: absolute path to `.planning` (e.g., `D:/Repos/plan-build-run/.planning`)
+- **Config JSON**: `JSON.stringify(config)` from the loaded config.json — escape backslashes and quotes for template embedding
+
 For each session:
 
 ```
 Task({
   subagent_type: "pbr:audit",
-  prompt: "<audit_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. {absolute_path_to_session.jsonl} — session log to analyze
+    2. {subagent log paths, if any} — subagent session logs
+  </files_to_read>
+  <audit_assignment>
     Session JSONL: {absolute_path_to_session.jsonl}
     Subagent logs: {list of subagent jsonl paths, or 'none'}
     Audit mode: {mode}
+    Active dimensions: {comma-separated list of dimension codes from Step 1b}
+    Preset: {preset}
+    Plugin root: {absolute path to plugins/pbr}
+    Planning dir: {absolute path to .planning}
+    Config JSON: {JSON.stringify(config) — escaped for template}
+
+    Run programmatic checks first via audit-checks/index.js runAllChecks(),
+    then analyze JSONL for session-dependent dimensions.
+    Return per-dimension results table.
+
+    Only check dimensions in the active set. Skip all others.
     Output path: DO NOT write to disk — return findings inline.
 
     Analyze this session for PBR workflow compliance and/or UX quality
     per your audit checklists. Return your full findings as structured
     markdown in your response.
+
+    Insights report: {insights_report_path}
   </audit_assignment>"
 })
 ```
 
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
+Also spawn a git analysis agent:
 
 ```
 Task({
-  subagent_type: "Bash",
+  subagent_type: "pbr:general",
   model: "haiku",
   prompt: "Run these git commands in {project_dir}:
     1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
@@ -173,32 +253,51 @@ Display progress:
 
 ## Step 5 — Collect and Synthesize
 
-As agents complete, collect their findings. Wait for all agents before proceeding.
+As agents complete, check each audit agent's Task() output for `## AUDIT COMPLETE`. If the marker is absent, mark that session as "analysis failed" in the synthesis and skip its findings — do not treat incomplete output as valid analysis. Log: `⚠ Session {id}: audit agent did not return completion marker — skipping.`
+
+Wait for all agents before proceeding.
+
+### 5a. Parse Per-Dimension Results
+
+From each agent's output, extract the per-dimension results tables. Each row has: Code, Dimension, Status, Evidence Summary.
+
+Merge results across sessions:
+- For **static dimensions** (SI, IH, FV): results are the same across sessions — use the single result
+- For **session-dependent dimensions** (EF, WC, BC, SQ, QM): use the **worst status** across sessions (fail > warn > pass)
+- Record which sessions contributed to each dimension's evidence
+
+### 5b. Build Category Summaries
 
-Synthesize across all sessions:
+For each of the 9 categories (AC, SI, IH, EF, WC, BC, SQ, FV, QM):
+- Count pass/warn/fail per category
+- Format: `{Category Name} ({Code}): {pass}/{total} pass, {warn} warn, {fail} fail`
 
-### 5a. Executive Summary
+Compute overall dimension score: `{pass}/{total} dimensions passed`
+
+### 5c. Executive Summary
 - Total sessions, total commits, releases
+- **Overall dimension score**: `{pass}/{total} dimensions passed`
 - Overall compliance: how many sessions passed/failed
 - Headline finding (the most important issue)
 
-### 5b. Per-Session Summary Table
-| Session | Duration | Commands | Compliance | UX Rating |
-|---------|----------|----------|------------|-----------|
+### 5d. Per-Session Summary Table
+| Session | Duration | Commands | Compliance | UX Rating | Dimensions Checked |
+|---------|----------|----------|------------|-----------|-------------------|
 
-### 5c. Cross-Session Patterns
+### 5e. Cross-Session Patterns
 - Recurring issues (e.g., STATE.md never read across multiple sessions)
 - Hook coverage gaps
 - Common flow mistakes
+- Dimensions that failed across ALL sessions (systemic issues)
 
-### 5d. Consolidated Findings
+### 5f. Consolidated Findings
 Merge and deduplicate findings across sessions. Categorize by severity:
 - **CRITICAL**: Workflow bypassed despite user requests, hooks not firing
 - **HIGH**: State files not consulted, missing artifacts
 - **MEDIUM**: Suboptimal flow choice, missing feedback
 - **LOW**: Minor ceremony issues, informational
 
-### 5e. Recommendations
+### 5g. Recommendations
 Prioritize as:
 - **Immediate**: Fix in next session
 - **Short-term**: Fix in next sprint/milestone
@@ -212,9 +311,11 @@ Prioritize as:
 
 Write to: `.planning/audits/{YYYY-MM-DD}-session-audit.md`
 
+**CRITICAL: Create the audits directory NOW. Do not skip this step.**
+
 Create `.planning/audits/` directory if it doesn't exist.
 
-The report should follow this structure:
+The report should follow this v2 structure:
 
 ```markdown
 # PBR Session Audit Report — {date range}
@@ -228,6 +329,34 @@ The report should follow this structure:
 
 ## Executive Summary
 {2-3 sentence overview}
+**Overall dimension score:** {pass}/{total} dimensions passed
+
+## Dimension Coverage
+
+**Preset:** {preset}
+**Dimensions checked:** {N}/{total enabled}
+**Overall:** {pass} pass, {warn} warn, {fail} fail
+
+## Per-Category Results
+
+### Self-Integrity (SI): {pass}/{total} pass, {warn} warn
+
+| Code | Dimension | Status | Evidence Summary |
+|------|-----------|--------|------------------|
+
+### Infrastructure Health (IH): {pass}/{total} pass, {warn} warn
+
+(repeat for each active category: AC, SI, IH, EF, WC, BC, SQ, FV, QM)
+
+## Config Cross-Reference
+
+For each dimension that references an `audit.thresholds` key, show:
+
+| Dimension | Threshold Key | Configured Value | Check Result |
+|-----------|--------------|-----------------|--------------|
+| IH-03 | hook_performance_ms | 500 | pass |
+
+(Only include dimensions with non-null thresholdKey from audit-dimensions.js)
 
 ## Session Summary
 {per-session table}
@@ -241,6 +370,15 @@ The report should follow this structure:
 ## Cross-Session Patterns
 {recurring issues}
 
+## Trend Analysis
+
+If QM-03 baseline comparison data is available:
+- Dimensions that **regressed** (were pass, now warn/fail)
+- Dimensions that **improved** (were warn/fail, now pass)
+- Overall trend direction
+
+If no prior audit data: "No prior audit data available for trend comparison."
+
 ## Consolidated Findings
 ### Critical
 ### High
@@ -258,6 +396,34 @@ The report should follow this structure:
 
 ---
 
+## Step 6b — Spot-Check Artifacts
+
+**Before displaying results, verify the report landed on disk:**
+
+1. Glob `.planning/audits/{YYYY-MM-DD}-session-audit.md` to confirm the file exists
+2. If missing: re-attempt the write (Step 6). If still missing, display an error and include findings inline instead.
+
+---
+
+## Step 6c — Verbosity Control
+
+Apply verbosity filtering to the Per-Category Results section based on the active preset:
+
+| Preset | Per-Category Results Behavior |
+|--------|-------------------------------|
+| `minimal` | Omit Per-Category Results detail entirely. Show only category-level summary lines (e.g., "SI: 14/15 pass, 1 warn"). |
+| `standard` | Per-Category Results shows only warn/fail dimensions. Passing dimensions are omitted from the detail tables. |
+| `comprehensive` | Per-Category Results shows ALL dimensions including passing ones. |
+
+**Implementation**: After building the per-category dimension tables in Step 5, filter rows before writing to the report:
+- If preset is `minimal`: skip writing dimension tables, keep only the `### {Category} ({Code}): {summary}` header lines
+- If preset is `standard`: filter each category table to only include rows where Status is `warn` or `fail`
+- If preset is `comprehensive`: include all rows
+
+The Dimension Coverage section and Executive Summary are always included regardless of verbosity.
+
+---
+
 ## Step 7 — Display Summary
 
 After writing the report, display inline (keep it concise — the full report is on disk):
@@ -286,16 +452,18 @@ Full report: .planning/audits/{filename}
 
 {Smart routing based on findings:}
 - If critical issues found: **Fix workflow** → `/pbr:quick`
-- If todos identified: **Create todos** → `/pbr:todo add "{description}"`
-- Default: **See project status** → `/pbr:status`
+- If todos identified: **Create todos** → `/pbr:add-todo "{description}"`
+- Default: **See project status** → `/pbr:progress`
 
-`/clear` first → fresh context window
+<sub>`/clear` first → fresh context window</sub>
 ```
 
 ---
 
 ## Error Handling
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ### Agent fails to analyze a session
 If an audit agent fails:
 ```
@@ -316,17 +484,20 @@ Note: Session {id} is {size}MB. Sampling key sections (first 200 lines, last 200
 
 ---
 
-## Anti-Patterns
+Reference: `skills/shared/commit-planning-docs.md` -- if `planning.commit_docs` is true, commit the audit report file.
+
+---
 
-Reference: `skills/shared/universal-anti-patterns.md` for rules that apply to ALL skills.
+## Anti-Patterns
 
 Additionally for this skill:
 
 1. **DO NOT** read JSONL files in main context — always delegate to audit agents
 2. **DO NOT** display the full report inline — write to disk, show summary
 3. **DO NOT** analyze sessions sequentially — spawn all agents in parallel
-4. **DO NOT** report findings without evidence (line numbers, timestamps, quotes)
-5. **DO NOT** judge explore sessions for missing STATE.md updates (explore is read-only)
-6. **DO NOT** flag release-please/merge commits as format violations
-7. **DO NOT** fabricate UX ratings — base them on concrete evidence (user repetitions, escalations, course-corrections)
-8. **DO NOT** exceed 5 headline findings in the inline summary — full details go in the report file
+4. **DO NOT** describe multiple agent spawns in prose (e.g., "launched 5 audit agents") — each session audit agent and the git analysis agent MUST be a separate Task() tool call in a single response message. Each separate call gets its own colored badge and independent ctrl+o expansion in the Claude Code UI. Multiple Task() calls in one message still run concurrently.
+5. **DO NOT** report findings without evidence (line numbers, timestamps, quotes)
+6. **DO NOT** judge explore sessions for missing STATE.md updates (explore is read-only)
+7. **DO NOT** flag release-please/merge commits as format violations
+8. **DO NOT** fabricate UX ratings — base them on concrete evidence (user repetitions, escalations, course-corrections)
+9. **DO NOT** exceed 5 headline findings in the inline summary — full details go in the report file