@sienklogic/plan-build-run 2.38.1 → 2.40.0

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

@@ -413,6 +413,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 ${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 ${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}"
@@ -424,6 +446,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/cursor-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)*

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.38.1",
+  "version": "2.40.0",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/pbr/agents/executor.md

@@ -120,6 +120,19 @@ One task = one commit. Exception: TDD tasks get 3 commits (RED, GREEN, REFACTOR)
 
 Stage only files listed in the task's `<files>`. If git commit fails with lock error, retry up to 3 times with 2s delay.
 
+### Issue Auto-Close
+
+When the plan frontmatter contains a non-empty `closes_issues` array, append issue-closing syntax to the **final** commit body for the plan:
+
+```
+git commit -m "feat(01-02): implement user auth
+
+Closes #42
+Closes #57"
+```
+
+Only append to the LAST commit of the plan — intermediate commits (RED/GREEN in TDD, partial progress) should NOT include closing syntax.
+
 ---
 
 ## Deviation Rules

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

@@ -155,11 +155,23 @@ Controls git integration and branching strategy.
 | `phase_branch_template` | string | `plan-build-run/phase-{phase}-{slug}` | Phase branch name pattern |
 | `milestone_branch_template` | string | `plan-build-run/{milestone}-{slug}` | Milestone branch name pattern |
 | `mode` | string | `enabled` | Git mode: `enabled` or `disabled` |
+| `auto_pr` | boolean | `false` | Create a GitHub PR after successful phase verification when branching is enabled |
 
 When `git.mode` is `disabled`, no git commands run at all -- no commits, branching, or hook validation. Useful for prototyping or non-git projects. See `references/git-integration.md` for full branching strategy details.
 
 ---
 
+## ci
+
+Controls CI integration for build gates.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ci.gate_enabled` | boolean | `false` | Block wave advancement until CI passes |
+| `ci.wait_timeout_seconds` | number | `120` | Max seconds to wait for CI completion |
+
+---
+
 ## gates
 
 Confirmation gates that pause execution to ask the user before proceeding. Setting a gate to `false` makes that step automatic.
@@ -219,6 +231,16 @@ This value is overridden by the active depth profile if a `depth_profiles` entry
 
 ---
 
+## deployment
+
+Controls post-milestone deployment verification.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `deployment.smoke_test_command` | string | `""` | Bash command to run after milestone completion (e.g., `"curl -sf https://myapp.com/health"`) |
+
+---
+
 ## depth_profiles
 
 Override the built-in depth profile defaults. Each key (`quick`, `standard`, `comprehensive`) maps to an object of settings that take effect when that depth is active.

package/plugins/pbr/references/git-integration.md

@@ -174,6 +174,36 @@ Branch name templates are configured in `config.json`:
 - `git.phase_branch_template`: Default `plan-build-run/phase-{phase}-{slug}`
 - `git.milestone_branch_template`: Default `plan-build-run/{milestone}-{slug}`
 
+### PR Creation
+
+When `git.auto_pr: true` and `git.branching` is `phase` or `milestone`, the build skill creates a GitHub PR after verification passes:
+
+1. Push the phase branch to the remote
+2. Create a PR via `gh pr create` with structured title and body
+3. PR title follows the commit convention: `feat(phase-{N}): {phase slug}`
+4. PR body includes phase goal, key files changed, and must-have verification results
+
+When `git.auto_pr: false` (default), the build skill offers the user a choice after verification:
+- Create PR now
+- Skip PR creation
+- Push branch only (create PR later)
+
+PR creation requires `gh` CLI authenticated with repo write access.
+
+### CI Integration
+
+When `ci.gate_enabled: true`, the build skill checks GitHub Actions status after each wave completes:
+
+1. Run: `gh run list --branch $(git branch --show-current) --limit 1 --json status,conclusion,url`
+2. If `status == completed` and `conclusion == success`: proceed to next wave
+3. If `status == in_progress`: wait up to `ci.wait_timeout_seconds`, re-check
+4. If `conclusion != success` or timeout: surface warning with run URL and offer:
+   - **Wait**: continue polling
+   - **Continue anyway**: proceed despite CI failure (logged as deviation)
+   - **Abort**: stop the build
+
+CI gate requires `gh` CLI and GitHub Actions configured on the repository. The gate only activates when there are commits pushed to a remote branch (branching must be enabled).
+
 ### Git Mode
 
 The `git.mode` field controls whether git integration is active:

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

@@ -46,6 +46,9 @@ consumes:
 requirement_ids:
   - "P02-G1"
   - "P02-G2"
+closes_issues:
+  - 42
+  - 57
 ---
 ```
 
@@ -71,6 +74,7 @@ requirement_ids:
 | `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]"` |
+| `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
 
 ### Data Contracts
 

package/plugins/pbr/scripts/lib/learnings.js

@@ -0,0 +1,312 @@
+'use strict';
+
+/**
+ * learnings.js — Global cross-project learnings store for Plan-Build-Run.
+ *
+ * Storage: JSONL at ~/.claude/learnings.jsonl
+ * Schema v1: id, source_project, type, tags, confidence, occurrences, summary, detail, custom_tags
+ *
+ * Usage (library):
+ *   const { learningsIngest, learningsQuery } = require('./lib/learnings');
+ *
+ * Usage (CLI via pbr-tools.js):
+ *   node pbr-tools.js learnings ingest <json-file>
+ *   node pbr-tools.js learnings query [--tags X] [--min-confidence Y] [--stack S] [--type T]
+ *   node pbr-tools.js learnings check-thresholds
+ */
+
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// --- Constants ---
+
+const GLOBAL_LEARNINGS_PATH = path.join(os.homedir(), '.claude', 'learnings.jsonl');
+
+// Schema v1 type taxonomy
+const LEARNING_TYPES = [
+  'tech-pattern',        // positive: "this tech/pattern worked well"
+  'anti-pattern',        // negative: "avoid this approach"
+  'estimation-metric',   // timing/sizing data (e.g., "OAuth takes ~3 phases")
+  'planning-failure',    // what went wrong in planning
+  'deferred-item',       // common deferrals with trigger conditions
+  'stack-insight',       // tech stack compatibility facts
+  'process-win',         // positive process patterns
+  'process-failure'      // negative process patterns
+];
+
+// Confidence tiers based on occurrence count
+const CONFIDENCE_TIERS = { low: 1, medium: 2, high: 3 };
+
+// Deferral thresholds for the 4 deferred items from phase 45
+const DEFERRAL_THRESHOLDS = [
+  { key: 'organic-taxonomy',       trigger: 'count > 50',   check: (count) => count > 50 },
+  { key: 'statistical-confidence', trigger: 'any_tag >= 20', check: (_c, tagMax) => tagMax >= 20 },
+  { key: 'audit-integration',      trigger: 'audits > 10',  check: (_c, _t, audits) => audits > 10 },
+  { key: 'executor-injection',     trigger: 'queries > 30', check: (_c, _t, _a, queries) => queries > 30 }
+];
+
+// --- Core functions ---
+
+/**
+ * Compute confidence tier from occurrence count.
+ * @param {number} occurrences
+ * @returns {'low'|'medium'|'high'}
+ */
+function computeConfidence(occurrences) {
+  if (occurrences >= 3) return 'high';
+  if (occurrences === 2) return 'medium';
+  return 'low';
+}
+
+/**
+ * Validate a learning entry against schema v1.
+ * @param {object} entry
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+function validateEntry(entry) {
+  const errors = [];
+
+  if (!entry) {
+    return { valid: false, errors: ['entry is null or undefined'] };
+  }
+
+  // Required fields
+  const required = ['id', 'source_project', 'type', 'tags', 'confidence', 'occurrences', 'summary'];
+  for (const field of required) {
+    if (entry[field] === undefined || entry[field] === null) {
+      errors.push(`missing required field: ${field}`);
+    }
+  }
+
+  // Type must be in taxonomy
+  if (entry.type !== undefined && !LEARNING_TYPES.includes(entry.type)) {
+    errors.push(`invalid type: "${entry.type}". Must be one of: ${LEARNING_TYPES.join(', ')}`);
+  }
+
+  // Confidence must be valid tier
+  if (entry.confidence !== undefined && !['low', 'medium', 'high'].includes(entry.confidence)) {
+    errors.push(`invalid confidence: "${entry.confidence}". Must be one of: low, medium, high`);
+  }
+
+  // Occurrences must be positive integer
+  if (entry.occurrences !== undefined) {
+    if (!Number.isInteger(entry.occurrences) || entry.occurrences < 1) {
+      errors.push(`occurrences must be a positive integer, got: ${entry.occurrences}`);
+    }
+  }
+
+  // Tags must be a non-empty array of strings
+  if (entry.tags !== undefined) {
+    if (!Array.isArray(entry.tags)) {
+      errors.push('tags must be an array');
+    } else if (entry.tags.length === 0) {
+      errors.push('tags must be a non-empty array');
+    } else {
+      const nonStrings = entry.tags.filter(t => typeof t !== 'string');
+      if (nonStrings.length > 0) {
+        errors.push(`all tags must be strings; got ${nonStrings.length} non-string value(s)`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Load all entries from the learnings JSONL file.
+ * @param {string} [filePath] — defaults to GLOBAL_LEARNINGS_PATH
+ * @returns {object[]}
+ */
+function loadAll(filePath) {
+  const target = filePath || GLOBAL_LEARNINGS_PATH;
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const content = fs.readFileSync(target, 'utf8');
+  return content
+    .split('\n')
+    .filter(line => line.trim().length > 0)
+    .reduce((acc, line) => {
+      try {
+        acc.push(JSON.parse(line));
+      } catch (_e) {
+        console.error(`[learnings] Skipping malformed line: ${line.slice(0, 80)}`);
+      }
+      return acc;
+    }, []);
+}
+
+/**
+ * Save all entries to the learnings JSONL file.
+ * @param {object[]} entries
+ * @param {string} [filePath] — defaults to GLOBAL_LEARNINGS_PATH
+ */
+function saveAll(entries, filePath) {
+  const target = filePath || GLOBAL_LEARNINGS_PATH;
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+  const content = entries.map(e => JSON.stringify(e)).join('\n') + (entries.length > 0 ? '\n' : '');
+  fs.writeFileSync(target, content, 'utf8');
+}
+
+/**
+ * Ingest a learning entry into the global store.
+ * Deduplicates by source_project + type + summary.
+ * If a duplicate is found, increments occurrences and updates confidence.
+ * @param {object} rawEntry
+ * @param {{ filePath?: string }} [options]
+ * @returns {{ action: 'created'|'updated', entry: object }}
+ */
+function learningsIngest(rawEntry, options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+
+  // Fill in generated fields if missing
+  const entry = Object.assign({}, rawEntry);
+  if (!entry.id) {
+    try {
+      entry.id = crypto.randomUUID();
+    } catch (_e) {
+      entry.id = Date.now().toString(36) + Math.random().toString(36).slice(2);
+    }
+  }
+  if (!entry.created_at) {
+    entry.created_at = new Date().toISOString();
+  }
+
+  const existing = loadAll(filePath);
+
+  // Dedup check: same source_project + type + summary
+  const dupIndex = existing.findIndex(
+    e => e.source_project === entry.source_project &&
+         e.type === entry.type &&
+         e.summary === entry.summary
+  );
+
+  if (dupIndex !== -1) {
+    // Update existing entry
+    const dup = existing[dupIndex];
+    dup.occurrences = (dup.occurrences || 1) + 1;
+    dup.confidence = computeConfidence(dup.occurrences);
+    dup.updated_at = new Date().toISOString();
+    saveAll(existing, filePath);
+    return { action: 'updated', entry: dup };
+  }
+
+  // New entry — validate before saving
+  const validation = validateEntry(entry);
+  if (!validation.valid) {
+    throw new Error(`Invalid learning entry: ${validation.errors.join('; ')}`);
+  }
+
+  existing.push(entry);
+  saveAll(existing, filePath);
+  return { action: 'created', entry };
+}
+
+/**
+ * Query learnings with optional filters.
+ * @param {{ tags?: string[], minConfidence?: string, stack?: string, type?: string }} [filters]
+ * @param {{ filePath?: string }} [options]
+ * @returns {object[]} Matching entries sorted by occurrences descending
+ */
+function learningsQuery(filters = {}, options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+  let entries = loadAll(filePath);
+
+  // Filter by tags (ALL listed tags must be present)
+  if (filters.tags && filters.tags.length > 0) {
+    entries = entries.filter(e => {
+      const entryTags = e.tags || [];
+      return filters.tags.every(t => entryTags.includes(t));
+    });
+  }
+
+  // Filter by minConfidence (entry confidence must be >= threshold)
+  if (filters.minConfidence && filters.minConfidence !== 'low') {
+    const minLevel = CONFIDENCE_TIERS[filters.minConfidence];
+    if (minLevel !== undefined) {
+      entries = entries.filter(e => {
+        const entryLevel = CONFIDENCE_TIERS[e.confidence] || 0;
+        return entryLevel >= minLevel;
+      });
+    }
+  }
+
+  // Filter by stack: matches if tags include "stack:<value>" OR stack_tags includes value
+  if (filters.stack) {
+    const stackTag = `stack:${filters.stack}`;
+    entries = entries.filter(e => {
+      const entryTags = e.tags || [];
+      const stackTags = e.stack_tags || [];
+      return entryTags.includes(stackTag) || stackTags.includes(filters.stack);
+    });
+  }
+
+  // Filter by type (exact match)
+  if (filters.type) {
+    entries = entries.filter(e => e.type === filters.type);
+  }
+
+  // Sort by occurrences descending
+  entries.sort((a, b) => (b.occurrences || 1) - (a.occurrences || 1));
+
+  return entries;
+}
+
+/**
+ * Check deferral thresholds against current learnings data.
+ * @param {{ filePath?: string }} [options]
+ * @returns {Array<{ key: string, trigger: string, message: string }>} Triggered thresholds
+ */
+function checkDeferralThresholds(options = {}) {
+  const filePath = options.filePath || GLOBAL_LEARNINGS_PATH;
+  const entries = loadAll(filePath);
+
+  const totalCount = entries.length;
+
+  // Compute max occurrences for any single tag
+  const tagCounts = {};
+  for (const entry of entries) {
+    for (const tag of (entry.tags || [])) {
+      tagCounts[tag] = (tagCounts[tag] || 0) + (entry.occurrences || 1);
+    }
+  }
+  const tagMax = Object.values(tagCounts).reduce((max, v) => Math.max(max, v), 0);
+
+  // Count audit-type entries
+  const auditCount = entries.filter(e => e.type === 'planning-failure' || e.type === 'process-failure').length;
+
+  // Query count: default 0 (separate counter not implemented in v1 — threshold tracked externally)
+  const queryCount = 0;
+
+  const triggered = [];
+  for (const threshold of DEFERRAL_THRESHOLDS) {
+    if (threshold.check(totalCount, tagMax, auditCount, queryCount)) {
+      triggered.push({
+        key: threshold.key,
+        trigger: threshold.trigger,
+        message: `Deferral threshold met: ${threshold.key} (${threshold.trigger})`
+      });
+    }
+  }
+
+  return triggered;
+}
+
+// --- Exports ---
+
+module.exports = {
+  GLOBAL_LEARNINGS_PATH,
+  LEARNING_TYPES,
+  CONFIDENCE_TIERS,
+  DEFERRAL_THRESHOLDS,
+  computeConfidence,
+  validateEntry,
+  loadAll,
+  saveAll,
+  learningsIngest,
+  learningsQuery,
+  checkDeferralThresholds
+};