@sienklogic/plan-build-run 2.38.1 → 2.40.0

package/plugins/pbr/scripts/milestone-learnings.js

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * milestone-learnings.js — Auto-aggregate learnings from milestone phase SUMMARY.md files.
+ * Called by the milestone complete flow after archiving phases.
+ *
+ * Usage: node milestone-learnings.js <milestone-archive-path> [--project <name>]
+ *   e.g. node milestone-learnings.js .planning/milestones/v2.0 --project my-app
+ *
+ * Env: PBR_LEARNINGS_FILE — override the learnings file path (for testing)
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { learningsIngest } = require('./lib/learnings');
+
+// --- Helpers ---
+
+/**
+ * Parse YAML frontmatter from a markdown file.
+ * Returns an object with string/array field values, or null if no frontmatter.
+ * Only handles simple YAML: scalar strings and dash-list arrays.
+ * @param {string} content
+ * @returns {object|null}
+ */
+function parseFrontmatter(content) {
+  // Normalize line endings
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+  const lines = yaml.split('\n');
+  let currentKey = null;
+
+  for (const line of lines) {
+    // List item (must check before key match so "  - item" doesn't match as key)
+    const listMatch = line.match(/^\s+-\s+"?([^"]+?)"?\s*$/);
+    if (listMatch) {
+      if (currentKey !== null) {
+        if (!Array.isArray(result[currentKey])) {
+          result[currentKey] = [];
+        }
+        result[currentKey].push(listMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Key: value pair
+    const kvMatch = line.match(/^(\w[\w_-]*):\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const rawVal = kvMatch[2].trim();
+
+      if (rawVal === '' || rawVal === '[]') {
+        // Empty scalar or empty inline array — may be followed by list items
+        result[currentKey] = [];
+      } else if (rawVal.startsWith('[')) {
+        // Inline array (basic): [a, b]
+        const inner = rawVal.slice(1, rawVal.lastIndexOf(']'));
+        result[currentKey] = inner.split(',').map(s => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+      } else {
+        result[currentKey] = rawVal.replace(/^["']|["']$/g, '');
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract learning entries from a SUMMARY.md file's frontmatter.
+ * @param {string} summaryContent — raw file content
+ * @param {string} sourceProject — project name
+ * @returns {object[]} array of raw learning entry objects
+ */
+function extractLearningsFromSummary(summaryContent, sourceProject) {
+  const fm = parseFrontmatter(summaryContent);
+  if (!fm) return [];
+
+  const entries = [];
+
+  // provides items → tech-pattern
+  const provides = Array.isArray(fm.provides) ? fm.provides : [];
+  for (const item of provides) {
+    if (!item || typeof item !== 'string') continue;
+    entries.push({
+      source_project: sourceProject,
+      type: 'tech-pattern',
+      tags: ['stack:inferred'],
+      confidence: 'low',
+      occurrences: 1,
+      summary: `Built: ${item}`,
+      detail: item
+    });
+  }
+
+  // key_decisions items → process-win
+  const decisions = Array.isArray(fm.key_decisions) ? fm.key_decisions : [];
+  for (const item of decisions) {
+    if (!item || typeof item !== 'string') continue;
+    entries.push({
+      source_project: sourceProject,
+      type: 'process-win',
+      tags: ['decision'],
+      confidence: 'low',
+      occurrences: 1,
+      summary: `Decision: ${item}`,
+      detail: item
+    });
+  }
+
+  // patterns items → tech-pattern
+  const patterns = Array.isArray(fm.patterns) ? fm.patterns : [];
+  for (const item of patterns) {
+    if (!item || typeof item !== 'string') continue;
+    entries.push({
+      source_project: sourceProject,
+      type: 'tech-pattern',
+      tags: ['pattern'],
+      confidence: 'low',
+      occurrences: 1,
+      summary: `Pattern: ${item}`,
+      detail: item
+    });
+  }
+
+  // deferred items → deferred-item
+  const deferred = Array.isArray(fm.deferred) ? fm.deferred : [];
+  for (const item of deferred) {
+    if (!item || typeof item !== 'string') continue;
+    entries.push({
+      source_project: sourceProject,
+      type: 'deferred-item',
+      tags: ['deferred'],
+      confidence: 'low',
+      occurrences: 1,
+      summary: `Deferred: ${item}`,
+      detail: item
+    });
+  }
+
+  // issues items → planning-failure or anti-pattern
+  const issues = Array.isArray(fm.issues) ? fm.issues : [];
+  for (const item of issues) {
+    if (!item || typeof item !== 'string') continue;
+    entries.push({
+      source_project: sourceProject,
+      type: 'planning-failure',
+      tags: ['issue'],
+      confidence: 'low',
+      occurrences: 1,
+      summary: `Issue: ${item}`,
+      detail: item
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Recursively find all SUMMARY*.md files under a phases directory.
+ * Matches both single-summary (SUMMARY.md) and per-plan (SUMMARY-45-01.md) patterns.
+ * @param {string} phasesDir
+ * @returns {string[]} absolute paths to SUMMARY*.md files
+ */
+function findSummaryFiles(phasesDir) {
+  const results = [];
+  if (!fs.existsSync(phasesDir)) return results;
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(phasesDir, entry.name);
+      if (entry.isDirectory()) {
+        // Find all SUMMARY*.md files in this phase directory
+        try {
+          const phaseFiles = fs.readdirSync(fullPath);
+          for (const file of phaseFiles) {
+            if (/^SUMMARY.*\.md$/i.test(file)) {
+              results.push(path.join(fullPath, file));
+            }
+          }
+        } catch (_e) {
+          // Ignore read errors for individual phase dirs
+        }
+        // Recurse in case of nested dirs
+        results.push(...findSummaryFiles(fullPath));
+      }
+    }
+  } catch (_e) {
+    // Ignore permission errors
+  }
+  return results;
+}
+
+// --- Main ---
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Parse CLI arguments
+  const archivePath = args[0];
+  if (!archivePath) {
+    process.stderr.write(
+      'Usage: node milestone-learnings.js <milestone-archive-path> [--project <name>]\n' +
+      'Error: archive path is required\n'
+    );
+    process.exit(1);
+  }
+
+  // Parse --project flag
+  let projectName = null;
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--project' && args[i + 1]) {
+      projectName = args[i + 1];
+      i++;
+    }
+  }
+
+  // Default project name to basename of cwd
+  if (!projectName) {
+    projectName = path.basename(process.cwd());
+  }
+
+  const resolvedArchivePath = path.resolve(archivePath);
+
+  // Verify archive path exists
+  if (!fs.existsSync(resolvedArchivePath)) {
+    process.stderr.write(`Error: archive path does not exist: ${resolvedArchivePath}\n`);
+    process.exit(1);
+  }
+
+  // Learnings file path (can be overridden for testing)
+  const learningsOpts = process.env.PBR_LEARNINGS_FILE
+    ? { filePath: process.env.PBR_LEARNINGS_FILE }
+    : {};
+
+  const phasesDir = path.join(resolvedArchivePath, 'phases');
+  const summaryFiles = findSummaryFiles(phasesDir);
+
+  let created = 0;
+  let updated = 0;
+  let errors = 0;
+
+  for (const summaryPath of summaryFiles) {
+    try {
+      const content = fs.readFileSync(summaryPath, 'utf8');
+      const rawEntries = extractLearningsFromSummary(content, projectName);
+
+      for (const rawEntry of rawEntries) {
+        try {
+          const result = learningsIngest(rawEntry, learningsOpts);
+          if (result.action === 'created') {
+            created++;
+          } else {
+            updated++;
+          }
+        } catch (ingestErr) {
+          errors++;
+          process.stderr.write(`[milestone-learnings] Ingest error: ${ingestErr.message}\n`);
+        }
+      }
+    } catch (readErr) {
+      errors++;
+      process.stderr.write(`[milestone-learnings] Read error for ${summaryPath}: ${readErr.message}\n`);
+    }
+  }
+
+  const summary = `Learnings aggregated: ${created} new, ${updated} updated, ${errors} errors`;
+  process.stdout.write(summary + '\n');
+
+  try {
+    logHook('milestone-learnings', 'complete', 'aggregated', { created, updated, errors });
+  } catch (_e) {
+    // Non-fatal: logging failure must not break the script
+  }
+}
+
+// Run if called directly
+if (require.main === module || process.argv[1] === __filename) {
+  main().catch(err => {
+    process.stderr.write(`[milestone-learnings] Fatal error: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { extractLearningsFromSummary, findSummaryFiles, parseFrontmatter };

package/plugins/pbr/scripts/pbr-tools.js

@@ -37,6 +37,9 @@
  *   phase add <slug> [--after N] — Add a new phase directory (with renumbering)
  *   phase remove <N>             — Remove an empty phase directory (with renumbering)
  *   phase list                   — List all phase directories with status
+ *   learnings ingest <json-file>  — Ingest a learning entry into global store
+ *   learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T] — Query learnings
+ *   learnings check-thresholds   — Check deferral trigger conditions
  *
  * Environment: PBR_PROJECT_ROOT — Override project root directory (used when hooks fire from subagent cwd)
  */
@@ -129,6 +132,12 @@ const {
   applyMigrations: _applyMigrations
 } = require('./lib/migrate');
 
+const {
+  learningsIngest: _learningsIngest,
+  learningsQuery: _learningsQuery,
+  checkDeferralThresholds: _checkDeferralThresholds
+} = require('./lib/learnings');
+
 // --- Local LLM imports (not extracted — separate module tree) ---
 const { resolveConfig, checkHealth } = require('./local-llm/health');
 const { classifyArtifact } = require('./local-llm/operations/classify-artifact');
@@ -669,10 +678,43 @@ async function main() {
       const force = args.includes('--force');
       const result = await migrate({ dryRun, force });
       output(result);
+    } else if (command === 'learnings') {
+      const subCmd = args[1];
+
+      if (subCmd === 'ingest') {
+        // learnings ingest <json-file-path>
+        const jsonFile = args[2];
+        if (!jsonFile) { error('Usage: learnings ingest <json-file>'); process.exit(1); }
+        const raw = fs.readFileSync(jsonFile, 'utf8');
+        const entry = JSON.parse(raw);
+        const result = _learningsIngest(entry);
+        output(result);
+
+      } else if (subCmd === 'query') {
+        // learnings query [--tags tag1,tag2] [--min-confidence low|medium|high] [--stack react] [--type tech-pattern]
+        const filters = {};
+        for (let i = 2; i < args.length; i++) {
+          if (args[i] === '--tags' && args[i + 1]) { filters.tags = args[++i].split(',').map(t => t.trim()); }
+          else if (args[i] === '--min-confidence' && args[i + 1]) { filters.minConfidence = args[++i]; }
+          else if (args[i] === '--stack' && args[i + 1]) { filters.stack = args[++i]; }
+          else if (args[i] === '--type' && args[i + 1]) { filters.type = args[++i]; }
+        }
+        const results = _learningsQuery(filters);
+        output(results);
+
+      } else if (subCmd === 'check-thresholds') {
+        // learnings check-thresholds — for progress-tracker to call
+        const triggered = _checkDeferralThresholds();
+        output(triggered);
+
+      } else {
+        error('Usage: learnings <ingest|query|check-thresholds>');
+        process.exit(1);
+      }
     } else if (command === 'validate-project') {
       output(validateProject());
     } else {
-      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds`);
+      error(`Unknown command: ${args.join(' ')}\nCommands: state load|check-progress|update|patch|advance-plan|record-metric, config validate|load-defaults|save-defaults|resolve-depth, validate-project, migrate [--dry-run] [--force], init execute-phase|plan-phase|quick|verify-work|resume|progress, plan-index, frontmatter, must-haves, phase-info, phase add|remove|list, roadmap update-status|update-plans, history append|load, todo list|get|add|done, event, llm health|status|classify|score-source|classify-error|summarize|metrics [--session <ISO>]|adjust-thresholds, learnings ingest|query|check-thresholds`);
     }
   } catch (e) {
     error(e.message);

package/plugins/pbr/scripts/progress-tracker.js

@@ -262,6 +262,12 @@ function buildContext(planningDir, stateFile) {
     parts.push(`\n${hookHealth}`);
   }
 
+  // Check learnings deferral thresholds
+  const learningsThresholds = checkLearningsDeferrals(planningDir);
+  if (learningsThresholds.length > 0) {
+    parts.push(`\nLearnings deferral triggers ready:\n${learningsThresholds.join('\n')}`);
+  }
+
   parts.push('\n[PBR WORKFLOW REQUIRED — Route all work through PBR commands]\n- Fix a bug or small task → /pbr:quick\n- Plan a feature → /pbr:plan N\n- Build from a plan → /pbr:build N\n- Explore or research → /pbr:explore\n- Freeform request → /pbr:do\n- Do NOT write source code or spawn generic agents without an active PBR skill.\n- Use PBR agents (pbr:researcher, pbr:executor, etc.) not Explore/general-purpose.');
 
   return parts.join('\n');
@@ -396,7 +402,24 @@ function tryLaunchDashboard(port, _planningDir, projectDir) {
   probe.unref();
 }
 
+/**
+ * Check learnings deferral thresholds and return notification strings.
+ * Wrapped in try/catch — threshold check must never break SessionStart.
+ * Equivalent to: node pbr-tools.js learnings check-thresholds
+ * @param {string} _planningDir — unused; thresholds check global learnings store
+ * @returns {string[]}
+ */
+function checkLearningsDeferrals(_planningDir) {
+  try {
+    const { checkDeferralThresholds } = require('./lib/learnings');
+    const triggered = checkDeferralThresholds();
+    return triggered.map(t => `  - ${t.key}: ${t.trigger} met — consider implementing deferred feature`);
+  } catch (_e) {
+    return [];
+  }
+}
+
 // Exported for testing
-module.exports = { getHookHealthSummary, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard };
+module.exports = { getHookHealthSummary, checkLearningsDeferrals, FAILURE_DECISIONS, HOOK_HEALTH_MAX_ENTRIES, tryLaunchDashboard };
 
 main().catch(() => {});

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

@@ -215,6 +215,25 @@ Spawn parallel Task() subagents for research. Each researcher writes to `.planni
 
 **CRITICAL: Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.**
 
+**Learnings injection (opt-in):** Before spawning researchers, check if global learnings exist:
+
+```bash
+node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" 2>/dev/null
+```
+
+If the command succeeds AND returns a non-empty JSON array:
+
+- Write the results to a temp file:
+
+  ```bash
+  node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" > /tmp/pbr-learnings-$$.md
+  ```
+
+- Note the temp file path as `{learnings_temp_path}`
+- Add this file to the researcher's `files_to_read` block (see below)
+
+If no learnings exist or the command fails: skip injection silently.
+
 **For each research topic, spawn a Task():**
 
 ```
@@ -236,13 +255,17 @@ For each researcher, construct the prompt by reading the template and filling in
 Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
 
 **Prepend this block to the researcher prompt before sending:**
+
 ```
 <files_to_read>
 CRITICAL: Read these files BEFORE any other action:
 1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
+{if learnings_temp_path exists}2. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
 </files_to_read>
 ```
 
+If `{learnings_temp_path}` was produced in the learnings injection step above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit line 2 entirely.
+
 **Placeholders to fill:**
 - `{project name from questioning}` — project name gathered in Step 2
 - `{2-3 sentence description from questioning}` — project description from Step 2

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

@@ -616,6 +616,26 @@ Resume at: Task {N+1} (or re-execute checkpoint task with user's answer)
 Continue execution from the checkpoint. Skip completed tasks. Process the checkpoint resolution, then continue with remaining tasks. Write SUMMARY.md when done.
 ```
 
+#### 6e-ii. CI Gate (after wave completion, conditional)
+
+If `config.ci.gate_enabled` is `true` AND `config.git.branching` is not `none`:
+
+1. Push current commits: `git push`
+2. Wait 5 seconds for CI to trigger
+3. Check: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
+4. If in_progress: poll every 15 seconds up to `config.ci.wait_timeout_seconds`
+5. If failed/timed out: show warning box:
+
+   ```
+   ⚠ CI Status: {conclusion}
+   Run: {url}
+   Options: [Wait] [Continue anyway] [Abort]
+   ```
+
+6. Use AskUserQuestion to present options: Wait / Continue anyway / Abort
+7. If "Continue anyway": log deviation — `DEVIATION: CI gate bypassed for wave {N}`
+8. If "Abort": stop build, update STATE.md
+
 #### 6f. Update STATE.md
 
 After each wave completes (all plans in the wave are done, skipped, or aborted):
@@ -791,6 +811,31 @@ If `git.branching` is `phase`:
 - If "Yes, merge": complete the merge and delete the phase branch
 - If "No, keep" or "Other": leave the branch as-is and inform the user
 
+**8d-ii. PR Creation (when branching enabled):**
+
+If `config.git.branching` is `phase` or `milestone` AND phase verification passed:
+
+1. Push the phase branch: `git push -u origin {branch-name}`
+2. If `config.git.auto_pr` is `true`:
+   - Run: `gh pr create --title "feat({phase-scope}): {phase-slug}" --body "$(cat <<'EOF'
+## Phase {N}: {phase name}
+
+**Goal**: {phase goal from ROADMAP.md}
+
+### Key Files
+{key_files from SUMMARY.md, bulleted}
+
+### Verification
+{pass/fail status from VERIFICATION.md}
+
+---
+Generated by Plan-Build-Run
+EOF
+)"`
+3. If `config.git.auto_pr` is `false`:
+   - Use AskUserQuestion to ask: "Phase branch pushed. Create a PR?"
+   - Options: Yes (create PR as above) / No / Later (skip)
+
 **8e. Auto-advance / auto-continue (conditional):**
 
 **If `features.auto_advance` is `true` AND `mode` is `autonomous`:**

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

@@ -119,6 +119,19 @@ When a knowledge gap emerges during the conversation — you're unsure about a l
 
 Display to the user: `◐ Spawning researcher...`
 
+**Learnings injection (opt-in):** Check for relevant tech stack learnings:
+
+```bash
+node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" 2>/dev/null
+```
+
+If non-empty JSON array returned:
+
+- Write to temp file: `node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" > /tmp/pbr-learnings-$$.md`
+- Note path as `{learnings_temp_path}`; add as item 3 in the researcher's `files_to_read` block below
+
+If no learnings or command fails: omit the extra files_to_read entry.
+
 ```
 Task({
   subagent_type: "pbr:researcher",
@@ -126,6 +139,7 @@ Task({
     CRITICAL: Read these files BEFORE any other action:
     1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
     2. .planning/STATE.md — current project state (if exists)
+    {if learnings_temp_path exists}3. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
   </files_to_read>
   <research_assignment>
     Topic: {specific research question}
@@ -139,6 +153,8 @@ Task({
 })
 ```
 
+If `{learnings_temp_path}` was produced above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit item 3 entirely.
+
 After the researcher completes, check for completion markers in the Task() output:
 
 - If `## RESEARCH COMPLETE` is present: proceed normally

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

@@ -417,6 +417,28 @@ Archive a completed milestone and prepare for the next one.
      - Key deliverables: {summary from Step 4}
      ```
 
+7d. **Aggregate learnings from milestone phases:**
+
+**CRITICAL: Run learnings aggregation NOW. Do NOT skip this step.**
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/milestone-learnings.js .planning/milestones/{version} --project {project-name-from-STATE.md}
+```
+
+- If the script outputs an error, log it but do NOT abort milestone completion — learnings aggregation is advisory.
+- Display the aggregation summary line to the user (e.g., "Learnings aggregated: 12 new, 3 updated, 0 errors").
+- After aggregation, check for triggered deferral thresholds:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js learnings check-thresholds
+```
+
+If any thresholds are triggered, display each as a notification:
+
+```
+Note: Learnings threshold met — {key}: {trigger}. Consider implementing the deferred feature.
+```
+
 8. **Git tag:**
    ```bash
    git tag -a {version} -m "Milestone: {name}"
@@ -428,6 +450,38 @@ Archive a completed milestone and prepare for the next one.
    git commit -m "docs(planning): complete milestone {version}"
    ```
 
+9b. **Push milestone to remote:**
+
+Use AskUserQuestion to ask the user how they want to publish the milestone:
+
+```
+question: "How should this milestone be published to GitHub?"
+header: "Publish"
+options:
+  - label: "Push tag + commits"    description: "Push the v{version} tag and any unpushed commits to origin"
+  - label: "Skip for now"          description: "Keep everything local — push later manually"
+```
+
+- If "Push tag + commits": run `git push origin main --follow-tags` to push both commits and the annotated tag in one command. Display success or error.
+- If "Skip for now": display reminder: "Tag v{version} is local only. Push when ready: `git push origin main --follow-tags`"
+- If "Other": follow user instructions (e.g., create a PR, push to a different branch, etc.)
+
+### Post-Completion Smoke Test
+
+If `config.deployment.smoke_test_command` is set and non-empty:
+
+1. Run the command via Bash
+2. If exit code 0: display "Smoke test passed" with command output
+3. If exit code non-zero: display advisory warning:
+
+   ```
+   ⚠ Smoke test failed (exit code {N})
+   Command: {smoke_test_command}
+   Output: {first 20 lines of output}
+   ```
+
+   This is advisory only — the milestone is already archived. Surface it as a potential issue for the user to investigate.
+
 10. **Confirm** with branded output:
     ```
     ╔══════════════════════════════════════════════════════════════╗

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

@@ -350,6 +350,24 @@ If `--teams` is NOT set and `config.parallelization.use_teams` is false or unset
 
 #### Single-Planner Flow (default)
 
+**Learnings injection (opt-in):** Check for planning and estimation learnings before spawning the planner:
+
+```bash
+node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "estimation,planning,process" 2>/dev/null
+```
+
+If non-empty JSON array returned:
+
+- Write to temp file and note as `{learnings_temp_path}`:
+
+  ```bash
+  node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "estimation,planning,process" > /tmp/pbr-learnings-$$.md
+  ```
+
+- Add as an additional `files_to_read` item in the planner prompt below
+
+If no learnings or command fails: omit.
+
 Display to the user: `◐ Spawning planner...`
 
 Spawn the planner Task() with all context inlined:
@@ -370,6 +388,7 @@ After planner completes, check for completion markers: `## PLANNING COMPLETE`, `
 #### Planning Prompt Template
 
 Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt template for spawning the planner agent. Fill in all placeholder blocks with phase-specific context:
+
 - `<phase_context>` - phase number, directory, goal, requirements, dependencies, success criteria
 - `<project_context>` - locked decisions, user constraints, deferred ideas, phase-specific decisions
 - `<prior_work>` - manifest table of preceding phase SUMMARY.md file paths with status and one-line exports (NOT full bodies)
@@ -378,15 +397,19 @@ Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt tem
 - `<planning_instructions>` - phase-specific planning rules and output path
 
 **Prepend this block to the planner prompt before sending:**
+
 ```
 <files_to_read>
 CRITICAL: Read these files BEFORE any other action:
 1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
 2. .planning/ROADMAP.md — phase goals, dependencies, and structure
 3. .planning/phases/{NN}-{slug}/RESEARCH.md — research findings (if exists)
+{if learnings_temp_path exists}4. {learnings_temp_path} — cross-project learnings (estimation and planning patterns from past PBR projects){/if}
 </files_to_read>
 ```
 
+If `{learnings_temp_path}` was produced in the learnings injection step above, replace `{if...}{/if}` with the actual line. If no learnings were found, omit item 4 entirely.
+
 Wait for the planner to complete.
 
 After the planner returns, read the plan files it created to extract counts. Display a completion summary:

package/plugins/pbr/templates/pr-body.md.tmpl

@@ -0,0 +1,22 @@
+## Phase <%= phase_number %>: <%= phase_name %>
+
+**Goal**: <%= phase_goal %>
+
+### Key Files Changed
+<% key_files.forEach(f => { %>
+- `<%= f %>`
+<% }) %>
+
+### Verification
+- Status: <%= verification_status %>
+- Must-haves: <%= must_haves_passed %>/<%= must_haves_total %> passed
+
+<% if (closes_issues && closes_issues.length > 0) { %>
+### Issues
+<% closes_issues.forEach(n => { %>
+Closes #<%= n %>
+<% }) %>
+<% } %>
+
+---
+*Generated by [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)*