@sienklogic/plan-build-run 2.22.2 → 2.24.0

package/dashboard/src/views/partials/analytics-content.ejs

@@ -88,3 +88,64 @@
 <% } else { %>
 <p>No phase data available.</p>
 <% } %>
+
+<% if (typeof llmMetrics !== 'undefined' && llmMetrics) { %>
+<article>
+  <header>Local LLM Offload</header>
+  <div class="grid">
+    <article>
+      <header>Total Calls</header>
+      <strong class="stat-value"><%= llmMetrics.summary.total_calls %></strong>
+      <span class="stat-unit">calls</span>
+    </article>
+    <article>
+      <header>Tokens Saved</header>
+      <strong class="stat-value"><%= llmMetrics.summary.tokens_saved.toLocaleString() %></strong>
+      <span class="stat-unit">frontier tokens</span>
+    </article>
+    <article>
+      <header>Est. Cost Saved</header>
+      <strong class="stat-value">$<%= llmMetrics.summary.cost_saved_usd.toFixed(4) %></strong>
+      <span class="stat-unit">at $3/M tokens</span>
+    </article>
+    <article>
+      <header>Fallback Rate</header>
+      <strong class="stat-value"><%= llmMetrics.summary.fallback_rate_pct %>%</strong>
+      <span class="stat-unit"><%= llmMetrics.summary.fallback_count %> fallbacks</span>
+    </article>
+    <article>
+      <header>Avg Latency</header>
+      <strong class="stat-value"><%= llmMetrics.summary.avg_latency_ms %></strong>
+      <span class="stat-unit">ms/call</span>
+    </article>
+  </div>
+  <% if (llmMetrics.byOperation && llmMetrics.byOperation.length > 0) { %>
+  <div class="overflow-auto" style="margin-top: var(--space-md);">
+    <table>
+      <thead>
+        <tr>
+          <th>Operation</th>
+          <th>Calls</th>
+          <th>Fallbacks</th>
+          <th>Tokens Saved</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% llmMetrics.byOperation.forEach(op => { %>
+        <tr>
+          <td><%= op.operation %></td>
+          <td><%= op.calls %></td>
+          <td><%= op.fallbacks %></td>
+          <td><%= op.tokens_saved.toLocaleString() %></td>
+        </tr>
+        <% }) %>
+      </tbody>
+    </table>
+  </div>
+  <% } %>
+  <footer style="color: var(--pico-muted-color); font-size: 0.85em;">
+    Baseline estimate: each local call replaced ~<%= llmMetrics.baseline.estimated_frontier_tokens_without_local.toLocaleString() %> frontier tokens total.
+    Advisory only — no data collected when local LLM is disabled.
+  </footer>
+</article>
+<% } %>

package/dashboard/src/views/partials/audit-detail-content.ejs

@@ -0,0 +1,12 @@
+<%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
+<h1><%= title %></h1>
+
+<p><a href="/audits">&larr; Back to Audit Reports</a></p>
+
+<% if (typeof date !== 'undefined' && date) { %>
+<p><small>Date: <%= date %></small></p>
+<% } %>
+
+<article class="markdown-body">
+  <%- html %>
+</article>

package/dashboard/src/views/partials/audits-content.ejs

@@ -0,0 +1,34 @@
+<%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
+<h1>Audit Reports</h1>
+
+<% if (typeof reports !== 'undefined' && reports.length > 0) { %>
+<article>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">Date</th>
+        <th scope="col">Report</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% reports.forEach(function(report) { %>
+      <tr>
+        <td><%= report.date || '—' %></td>
+        <td>
+          <a href="/audits/<%= report.filename %>"
+             hx-get="/audits/<%= report.filename %>"
+             hx-target="#main-content"
+             hx-push-url="true">
+            <%= report.title %>
+          </a>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% } else { %>
+<%- include('empty-state', { icon: '🔍', title: 'No audit reports found', action: 'Run /pbr:audit to generate a session audit report.' }) %>
+<% } %>

package/dashboard/src/views/partials/quick-content.ejs

@@ -0,0 +1,40 @@
+<%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
+<h1>Quick Tasks</h1>
+
+<% if (typeof tasks !== 'undefined' && tasks.length > 0) { %>
+<article>
+  <div class="table-wrap">
+  <table>
+    <thead>
+      <tr>
+        <th scope="col">ID</th>
+        <th scope="col">Title</th>
+        <th scope="col">Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% tasks.forEach(function(task) { %>
+      <tr>
+        <td><%= task.id %></td>
+        <td>
+          <a href="/quick/<%= task.id %>"
+             hx-get="/quick/<%= task.id %>"
+             hx-target="#main-content"
+             hx-push-url="true">
+            <%= task.title %>
+          </a>
+        </td>
+        <td>
+          <span class="status-badge" data-status="<%= task.status %>">
+            <%= task.status %>
+          </span>
+        </td>
+      </tr>
+      <% }); %>
+    </tbody>
+  </table>
+  </div>
+</article>
+<% } else { %>
+<%- include('empty-state', { icon: '⚡', title: 'No quick tasks found', action: '' }) %>
+<% } %>

package/dashboard/src/views/partials/quick-detail-content.ejs

@@ -0,0 +1,29 @@
+<%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
+<h1><%= title %></h1>
+
+<p><a href="/quick">&larr; Back to Quick Tasks</a></p>
+
+<article>
+  <header>
+    <strong>Quick Task <%= id %></strong>
+    &nbsp;
+    <span class="status-badge" data-status="<%= status %>">
+      <%= status %>
+    </span>
+  </header>
+
+  <% if (planHtml) { %>
+  <section>
+    <h2>Plan</h2>
+    <%- planHtml %>
+  </section>
+  <% } %>
+
+  <% if (summaryHtml) { %>
+  <hr>
+  <section>
+    <h2>Summary</h2>
+    <%- summaryHtml %>
+  </section>
+  <% } %>
+</article>

package/dashboard/src/views/partials/sidebar.ejs

@@ -79,6 +79,22 @@
             Notes
           </a>
         </li>
+        <li>
+          <a href="/quick"
+             hx-get="/quick"
+             hx-target="#main-content"
+             hx-push-url="true"<%= typeof activePage !== 'undefined' && activePage === 'quick' ? ' aria-current="page"' : '' %>>
+            Quick Tasks
+          </a>
+        </li>
+        <li>
+          <a href="/audits"
+             hx-get="/audits"
+             hx-target="#main-content"
+             hx-push-url="true"<%= typeof activePage !== 'undefined' && activePage === 'audits' ? ' aria-current="page"' : '' %>>
+            Audit Reports
+          </a>
+        </li>
       </ul>
     </details>
 

package/dashboard/src/views/partials/todos-content.ejs

@@ -1,10 +1,17 @@
 <%- include('breadcrumbs', { breadcrumbs: typeof breadcrumbs !== 'undefined' ? breadcrumbs : [] }) %>
 <h1>Todos</h1>
 
-<p><a href="/todos/new" role="button"
+<p>
+  <a href="/todos/new" role="button"
       hx-get="/todos/new"
       hx-target="#main-content"
-      hx-push-url="true">Create Todo</a></p>
+      hx-push-url="true">Create Todo</a>
+  &nbsp;
+  <a href="/todos/done"
+      hx-get="/todos/done"
+      hx-target="#main-content"
+      hx-push-url="true">View Completed Todos</a>
+</p>
 
 <% const f = typeof filters !== 'undefined' ? filters : { priority: '', status: '', q: '' }; %>
 <article>
@@ -70,7 +77,10 @@
       <tr>
         <td><%= todo.id %></td>
         <td>
-          <a href="/todos/<%= todo.id %>">
+          <a href="/todos/<%= todo.id %>"
+             hx-get="/todos/<%= todo.id %>"
+             hx-target="#main-content"
+             hx-push-url="true">
             <%= todo.title %>
           </a>
         </td>

package/dashboard/src/views/quick-detail.ejs

@@ -0,0 +1,5 @@
+<%- include('partials/layout-top', { title: title, activePage: 'quick' }) %>
+
+<%- include('partials/quick-detail-content') %>
+
+<%- include('partials/layout-bottom') %>

package/dashboard/src/views/quick.ejs

@@ -0,0 +1,5 @@
+<%- include('partials/layout-top', { title: 'Quick Tasks', activePage: 'quick' }) %>
+
+<%- include('partials/quick-content') %>
+
+<%- include('partials/layout-bottom') %>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.22.2",
+  "version": "2.24.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

package/plugins/copilot-pbr/agents/debugger.agent.md

@@ -138,6 +138,21 @@ Then emit a `DECISION` checkpoint asking the user to approve, modify, or reject
 
 **Commit format**: `fix({scope}): {description}` with body: `Root cause: ...` and `Debug session: .planning/debug/{slug}.md`
 
+## Local LLM Error Classification (Optional)
+
+When you receive an error message or stack trace, you MAY use the local LLM to classify it before starting hypothesis generation. This is advisory — skip it if unavailable.
+
+```bash
+# Write the error to a temp file, then classify:
+echo "Error text here" > /tmp/debug-error.txt
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" llm classify-error /tmp/debug-error.txt debugger 2>/dev/null
+# Returns: {"category":"missing_output","confidence":0.91,"latency_ms":1840,"fallback_used":false}
+```
+
+Categories: `connection_refused`, `timeout`, `missing_output`, `wrong_output_format`, `permission_error`, `unknown`.
+
+If classification succeeds, use the returned category to bias your initial hypothesis ranking. If it returns null or fails, proceed with manual hypothesis generation as normal.
+
 ## Common Bug Patterns
 
 Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undefined, async/timing, state management, import/module, environment, and data shape patterns.

package/plugins/copilot-pbr/agents/integration-checker.agent.md

@@ -35,6 +35,7 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 3. **Auth Protection** — Every non-public route must have auth middleware. Frontend route guards must match backend protection.
 4. **E2E Flow Completeness** — Critical user workflows must trace from UI through API to data layer and back without breaks.
 5. **Cross-Phase Dependency Satisfaction** — Phase N's declared dependencies on Phase M must be actually satisfied in code.
+6. **Data-Flow Propagation** — Values originating at one boundary (hook stdin fields, API request params, env vars) must propagate correctly through the call chain to their destination (log entries, database records, API responses). A connected pipeline with missing data is a broken integration.
 
 > **First-phase edge case**: If no completed phases exist yet, focus on verifying the current phase's internal consistency — exports match imports within the phase, API contracts are self-consistent. Cross-phase checks are not applicable and should be skipped.
 
@@ -47,14 +48,19 @@ Read `references/agent-contracts.md` to validate agent-to-agent handoffs. Verify
 - **Write access for output artifact only** — you have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues.
 - **Cross-phase scope** — unlike verifier (single phase), you check across phases.
 
-## 6-Step Verification Process
+## 7-Step Verification Process
 
 1. **Build Export/Import Map**: Read each completed phase's SUMMARY.md frontmatter (`requires`, `provides`, `affects`). Grep actual exports/imports in source. Cross-reference declared vs actual — flag mismatches.
 2. **Verify Export Usage**: For each `provides` item: locate actual export (missing = `MISSING_EXPORT` ERROR), find consumers (none = `ORPHANED` WARNING), verify usage not just import (`IMPORTED_UNUSED` WARNING), check signature compatibility (`MISMATCHED` ERROR). Status `CONSUMED` = OK.
 3. **Verify API Coverage**: Discover routes, find frontend callers, match by method+path+body/params. Produce coverage table. See `references/integration-patterns.md` for framework-specific patterns.
 4. **Verify Auth Protection**: Identify auth mechanism, list all routes, classify (public vs protected), check frontend guards. Flag UNPROTECTED routes.
 5. **Verify E2E Flows**: Trace critical workflows step-by-step — verify each step exists and connects to the next (import/call/redirect). Record evidence (file:line). Flow status: COMPLETE | BROKEN | PARTIAL | UNTRACEABLE. See `references/integration-patterns.md` for flow templates.
-6. **Compile Integration Report**: Produce final report with all findings by category.
+6. **Verify Data-Flow Propagation**: For each cross-boundary data field identified in plans or SUMMARY.md, trace the value from source through intermediate functions to destination. Verify the value is actually passed (not `undefined`/`null`/hardcoded) at each step.
+   - **Source examples**: hook stdin (`data.session_id`), API request params, environment variables, config fields
+   - **Destination examples**: log entries, database records, API responses, metric files
+   - **Method**: Grep each intermediate call site and inspect arguments. Flag `DATA_DROPPED` when a value available in scope is replaced by `undefined` or a placeholder.
+   - **Status**: `PROPAGATED` (value flows correctly) | `DATA_DROPPED` (value lost at some step) | `UNTRACEABLE` (cannot determine flow)
+7. **Compile Integration Report**: Produce final report with all findings by category.
 
 ## Output Format
 
@@ -119,3 +125,4 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 - "File exists" is not "component is integrated"
 - Auth middleware existing somewhere does not mean routes are protected
 - Always check error handling paths, not just happy paths
+- Structural connectivity is not data-flow correctness — a connected pipeline can still drop data at any step

package/plugins/copilot-pbr/agents/planner.agent.md

@@ -66,6 +66,23 @@ Each must-have maps to one or more tasks. Every task exists to make a must-have
 
 ---
 
+## Data Contracts for Cross-Boundary Parameters
+
+When a function signature includes parameters that flow across module boundaries — session IDs from hook stdin, config objects from disk, auth tokens from environment — the plan **MUST** specify the **source** for each argument, not just the type.
+
+For every cross-boundary call in a task's `<action>`, document:
+
+| Parameter | Source | Context | Fallback |
+|-----------|--------|---------|----------|
+| `sessionId` | `data.session_id` (hook stdin) | Hook scripts only | `undefined` (CLI context) |
+| `config` | `configLoad(planningDir)` | All callers | `resolveConfig(undefined)` |
+
+**When to apply:** Any function call where the caller and callee live in different modules AND at least one argument originates from an external boundary (stdin, env, disk, network). Internal helper calls within the same module do not need contracts.
+
+**Why this matters:** Without explicit source mapping, executors will use the type-correct but value-wrong default (e.g., `undefined` instead of `data.session_id`). The plan is the single source of truth for how data flows — if the plan says `undefined`, the executor will faithfully implement `undefined`.
+
+---
+
 ## Plan Structure
 
 Read `references/plan-format.md` for the complete plan file specification including:
@@ -165,6 +182,7 @@ When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from th
    - [ ] Dependencies are acyclic, no file conflicts within same wave
    - [ ] Locked decisions honored, no deferred ideas included
    - [ ] Verify commands are actually executable
+   - [ ] Cross-boundary parameters have documented sources (data contracts)
 
 ---
 
@@ -238,3 +256,4 @@ One-line task descriptions in `<name>`. File paths in `<files>`, not explanation
 9. DO NOT plan for features outside the current phase goal
 10. DO NOT assume research is done — check discovery level
 11. DO NOT leave done conditions vague — they must be observable
+12. DO NOT specify literal `undefined` for parameters that have a known source in the calling context — use data contracts to map sources

package/plugins/copilot-pbr/agents/researcher.agent.md

@@ -54,6 +54,26 @@ All claims must be attributed to a source level. Higher levels override lower le
 
 **Offline Fallback**: If web tools are unavailable (air-gapped environment, MCP not configured), rely on local sources: codebase analysis via Glob/Grep, existing documentation, and README files. Assign these S3-S4 confidence levels. Do not attempt WebFetch or WebSearch — note in the output header that external sources were unavailable.
 
+## Local LLM Source Scoring (Optional)
+
+If local LLM offload is configured, you MAY use it to score source credibility instead of manually assigning S-levels. This is advisory — never wait on it or fail if it returns null.
+
+Check availability first:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" llm status 2>/dev/null
+```
+
+If `enabled: true`, score a source excerpt:
+
+```bash
+echo "Source URL and content excerpt" > /tmp/source-excerpt.txt
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" llm score-source "https://example.com/docs" /tmp/source-excerpt.txt 2>/dev/null
+# Returns: {"level":"S2","confidence":0.87,"reason":"Official library documentation page"}
+```
+
+Use the returned `level` to set your source tag. If the call fails or returns `null`, assign the level manually per the hierarchy table above.
+
 ---
 
 ## Confidence Levels

package/plugins/copilot-pbr/agents/synthesizer.agent.md

@@ -98,6 +98,18 @@ conflicts: N
 - **Research gaps**: Add `[RESEARCH GAP]` flag, add to Open Questions with high impact, never fabricate
 - **Duplicates**: Consolidate into one entry, note multi-source agreement, reference all documents
 
+## Local LLM Context Summarization (Optional)
+
+When input research documents are large (>2000 words combined), you MAY use the local LLM to pre-summarize each document before synthesis. This reduces your own context consumption. Advisory only — if unavailable, read documents normally.
+
+```bash
+# Pre-summarize a large research document to ~150 words:
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" llm summarize /path/to/RESEARCH.md 150 2>/dev/null
+# Returns: {"summary":"...plain text summary under 150 words...","latency_ms":2100,"fallback_used":false}
+```
+
+Use the returned `summary` string as your working copy of that document's findings. Still read the original for any specific version numbers, code examples, or direct quotes needed in the output.
+
 ## Anti-Patterns
 
 ### Universal Anti-Patterns

package/plugins/copilot-pbr/agents/verifier.agent.md

@@ -95,10 +95,29 @@ Verify the artifact is imported AND used by other parts of the system (functions
 | Yes | Yes | No | UNWIRED |
 | Yes | Yes | Yes | PASSED |
 
+> **Note:** WIRED status (Level 3) requires correct arguments, not just correct function names. A call that passes `undefined` for a parameter available in scope is `ARGS_WRONG`, not `WIRED`.
+
 ### Step 6: Verify Key Links (Always)
 
 For each key_link: identify source and target components, verify the import path resolves, verify the imported symbol is actually called/used, and verify call signatures match. Watch for: wrong import paths, imported-but-never-called symbols, defined-but-never-applied middleware, registered-but-never-triggered event handlers.
 
+### Step 6b: Argument-Level Spot Checks (Always)
+
+Beyond verifying that calls exist, spot-check that **arguments passed to cross-boundary calls carry the correct values**. A call with the right function but wrong arguments is effectively UNWIRED.
+
+**Focus on:** IDs (session, user, request), config objects, auth tokens, and context data that originate from external boundaries (stdin, env, disk).
+
+**Method:**
+1. For each key_link verified in Step 6, grep the call site and inspect the arguments
+2. Compare each argument against the data source available in the calling scope
+3. Flag any argument that passes `undefined`, `null`, or a hardcoded placeholder when the calling scope has the real value available (e.g., `data.session_id` is in scope but `undefined` is passed)
+
+**Classification:**
+- `WIRED` requires both correct function AND correct arguments
+- `ARGS_WRONG` = correct function called but one or more arguments are incorrect/missing — this is a key link gap
+
+**Example:** A hook script receives `data` from stdin containing `session_id`. If it calls `logMetric(planningDir, { session_id: undefined })` instead of `logMetric(planningDir, { session_id: data.session_id })`, that is an `ARGS_WRONG` gap even though the call itself exists.
+
 ### Step 7: Check Requirements Coverage (Always)
 
 Cross-reference all must-haves against verification results in a table:
@@ -107,8 +126,8 @@ Cross-reference all must-haves against verification results in a table:
 | # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | Status |
 |---|----------|------|-------------|-------------------|------------|--------|
 | 1 | {description} | truth | - | - | - | VERIFIED/FAILED |
-| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED | PASS/FAIL |
-| 3 | {description} | key_link | - | - | YES/NO | PASS/FAIL |
+| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED/ARGS_WRONG | PASS/FAIL |
+| 3 | {description} | key_link | - | - | YES/NO/ARGS_WRONG | PASS/FAIL |
 ```
 
 ### Step 8: Scan for Anti-Patterns (Full Verification Only)
@@ -226,3 +245,4 @@ Read `references/stub-patterns.md` for stub detection patterns by technology. Re
 9. DO NOT give PASSED status if ANY must-have fails at ANY level
 10. DO NOT count deferred items as gaps — they are intentionally not implemented
 11. DO NOT be lenient — your job is to find problems, not to be encouraging
+12. DO NOT mark a call as WIRED if it passes hardcoded `undefined`/`null` for parameters that have a known source in scope — check arguments, not just function names

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.22.2",
+  "version": "2.24.0",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/copilot-pbr/references/config-reference.md

@@ -440,3 +440,92 @@ Run validation with: `node plugins/pbr/scripts/pbr-tools.js config validate`
 | `tdd_mode: true` + `depth: quick` | quick depth skips verification, which conflicts with TDD's verify-first approach |
 | `git.mode: disabled` + `atomic_commits: true` | atomic_commits has no effect when git is disabled |
 | `git.branching: phase` + `git.mode: disabled` | Branching settings are ignored when git is disabled |
+
+---
+
+## local_llm
+
+Offloads selected PBR inference tasks to a locally running Ollama instance, reducing frontier model usage and latency for fast classification calls. The key `enabled` defaults to `false`, so users without Ollama see no change — all LLM calls continue routing to Claude as normal. When enabled, PBR uses a `local_first` routing strategy: fast tasks (artifact classification, task validation) go to the local model; complex tasks (planning, execution) stay on the frontier model.
+
+### Quick setup
+
+1. Install Ollama:
+   - **Linux/macOS**: `curl -fsSL https://ollama.com/install.sh | sh`
+   - **Windows**: Download from [ollama.com/download](https://ollama.com/download) and run the installer
+2. Pull the recommended model: `ollama pull qwen2.5-coder:7b`
+3. Add to `.planning/config.json`:
+
+   ```json
+   "local_llm": {
+     "enabled": true,
+     "model": "qwen2.5-coder:7b"
+   }
+   ```
+
+4. Verify connectivity: `node /path/to/plugins/pbr/scripts/pbr-tools.js llm health`
+
+### Field reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `local_llm.enabled` | boolean | `false` | Enable local LLM offloading; `false` = all calls use frontier |
+| `local_llm.provider` | string | `"ollama"` | Backend provider; only `"ollama"` is supported |
+| `local_llm.endpoint` | string | `"http://localhost:11434"` | Ollama API base URL |
+| `local_llm.model` | string | `"qwen2.5-coder:7b"` | Model tag to use for local inference |
+| `local_llm.timeout_ms` | integer | `3000` | Per-request timeout in milliseconds; >= 500 |
+| `local_llm.max_retries` | integer | `1` | Number of retry attempts on failure before falling back |
+| `local_llm.fallback` | string | `"frontier"` | What to use when local LLM fails: `"frontier"` or `"skip"` |
+| `local_llm.routing_strategy` | string | `"local_first"` | `"local_first"` sends fast tasks local; `"always_local"` routes everything |
+
+### features sub-table
+
+Controls which PBR tasks are eligible for local LLM offloading.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `artifact_classification` | `true` | Classify artifact types (PLAN, SUMMARY, VERIFICATION) locally |
+| `task_validation` | `true` | Validate task scope and completeness locally |
+| `context_summarization` | `false` | Summarize context windows locally (higher token demand) |
+| `source_scoring` | `false` | Score source files by relevance locally |
+
+### advanced sub-table
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `confidence_threshold` | `0.9` | Minimum confidence (0–1) for local output to be accepted; below this, falls back to frontier |
+| `shadow_mode` | `false` | Run local LLM in parallel with frontier but discard local results — useful for tuning confidence thresholds without affecting output |
+| `max_input_tokens` | `2000` | Truncate inputs longer than this before sending to local model |
+| `keep_alive` | `"30m"` | How long Ollama keeps the model loaded between requests (Ollama format: `"5m"`, `"1h"`) |
+| `num_ctx` | `4096` | Context window size passed to Ollama; **must be 4096 on Windows** (see Windows gotchas) |
+| `disable_after_failures` | `3` | Automatically disable local LLM for the session after this many consecutive failures |
+
+### Hardware requirements
+
+| Tier | Hardware | Notes |
+|------|----------|-------|
+| Recommended | RTX 3060+ with 8 GB VRAM | Full GPU acceleration; qwen2.5-coder:7b loads entirely in VRAM |
+| Functional | GTX 1660+ with 6 GB VRAM | GPU acceleration with slight layer offload to RAM |
+| Marginal | CPU only, 32 GB RAM | Works but adds 5-20s latency per call; disable context-heavy features |
+
+For GPU acceleration, ensure NVIDIA drivers are 520+ and CUDA 11.8+ is installed. AMD GPU support is available via ROCm on Linux only.
+
+### Windows gotchas
+
+- **Smart App Control**: May block `ollama_llama_server.exe` on first run. Allow it via Security settings or disable Smart App Control.
+- **Windows Defender**: Add an exclusion for `%LOCALAPPDATA%\Programs\Ollama\ollama_llama_server.exe` to prevent Defender from scanning inference calls in real time.
+- **`num_ctx` must be 4096**: Higher values cause GPU memory fragmentation on Windows and result in OOM errors mid-session. Always set `advanced.num_ctx: 4096` in your config.
+- **Firewall**: Ollama listens on `localhost:11434` by default. If you see connection refused errors, check that Windows Firewall is not blocking loopback connections.
+
+### Viewing metrics
+
+After enabling local LLM, PBR logs per-call metrics to `.planning/logs/local-llm-metrics.jsonl`. Use the built-in subcommands to inspect them:
+
+```bash
+# Show session summary (calls routed, latency, token savings)
+node plugins/pbr/scripts/pbr-tools.js llm metrics
+
+# Suggest routing threshold adjustments based on recent accuracy
+node plugins/pbr/scripts/pbr-tools.js llm adjust-thresholds
+```
+
+Metrics include: routing decision, model used, latency ms, confidence score, whether the frontier fallback was triggered, and estimated tokens saved.

package/plugins/copilot-pbr/references/plan-format.md

@@ -71,6 +71,28 @@ requirement_ids:
 | `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
 | `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
 | `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
+| `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
+
+### Data Contracts
+
+When a task's `<action>` includes calls across module boundaries where arguments come from external sources (hook stdin, env vars, API params, config files), document the parameter-to-source mapping in `data_contracts` frontmatter and in the `<action>` step itself.
+
+Example frontmatter:
+
+```yaml
+data_contracts:
+  - "sessionId: data.session_id (hook stdin) [undefined in CLI context]"
+  - "config: configLoad(planningDir) (disk) [resolveConfig(undefined)]"
+```
+
+Example in `<action>`:
+
+```
+3. Call classifyArtifact(llmConfig, planningDir, content, fileType, data.session_id)
+   Data contract: sessionId ← data.session_id from hook stdin (undefined in CLI context)
+```
+
+**When to apply:** Any call where caller and callee are in different modules AND at least one argument originates from an external boundary. Internal helper calls within the same module do not need contracts.
 
 ---
 

package/plugins/copilot-pbr/skills/health/SKILL.md

@@ -127,7 +127,7 @@ Read `.planning/config.json` and check for fields referenced by skills:
 - PASS: All expected fields present with correct types
 - WARN (missing fields): Report each missing field and which skill uses it — "Run `/pbr:config` to set all options."
 
-### Check 10: Orphaned Crash Recovery Files
+### Check 10: Orphaned Crash Recovery & Lock Files
 
 The executor creates `.PROGRESS-{plan_id}` files as crash recovery breadcrumbs during builds and deletes them after `SUMMARY.md` is written. Similarly, `.checkpoint-manifest.json` files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
 
@@ -147,6 +147,13 @@ Glob for `.planning/phases/**/.PROGRESS-*` and `.planning/phases/**/.checkpoint-
   ```
   Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no `/pbr:build` is currently running. Remove with `rm <path>`."
 
+Also check for `.planning/.active-skill`:
+
+- If the file does not exist: no action needed (PASS for this sub-check)
+- If the file exists, check its age by comparing the file modification time to the current time:
+  - If older than 1 hour: WARN with fix suggestion: "Stale .active-skill lock file detected (set {age} ago). No PBR skill appears to be running. Safe to delete with `rm .planning/.active-skill`."
+  - If younger than 1 hour: INFO: "Active skill lock exists ({content}). A PBR skill may be running."
+
 ---
 
 ## Auto-Fix for Common Corruption Patterns

package/plugins/copilot-pbr/skills/help/SKILL.md

@@ -210,10 +210,10 @@ The `features.team_discussions` config flag (and `/pbr:build --team`) enables **
 ║  ▶ NEXT UP                                                   ║
 ╚══════════════════════════════════════════════════════════════╝
 
-→ `/pbr:begin` — start a new project
-→ `/pbr:status` — check current project status
-→ `/pbr:config` — configure workflow settings
-→ `/pbr:help <command>` — detailed help for a specific command
+- `/pbr:begin` — start a new project
+- `/pbr:status` — check current project status
+- `/pbr:config` — configure workflow settings
+- `/pbr:help <command>` — detailed help for a specific command
 
 ```