@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/plugins/pbr/scripts/sync-context-to-claude.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Syncs Locked Decisions from .planning/CONTEXT.md into project CLAUDE.md.
+ * Called by post-write-dispatch.js when .planning/CONTEXT.md is written.
+ *
+ * Algorithm:
+ *   1. Read .planning/CONTEXT.md — extract ## Locked Decisions table rows
+ *   2. Find project CLAUDE.md (cwd/CLAUDE.md)
+ *   3. Replace or append a "### Locked Decisions (PBR)" section
+ *
+ * Idempotent: re-running produces the same result.
+ * Advisory only: never throws, never blocks.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+
+const SECTION_START = '### Locked Decisions (PBR)';
+const SECTION_END_MARKER = '<!-- /pbr:locked-decisions -->';
+
+/**
+ * Extract decision rows from the ## Locked Decisions table in CONTEXT.md.
+ * Handles both \n and \r\n line endings.
+ * @param {string} contextContent - Full content of CONTEXT.md
+ * @returns {{ decision: string, rationale: string }[]}
+ */
+function extractLockedDecisions(contextContent) {
+  // Find ## Locked Decisions section (handle \r\n line endings)
+  const sectionMatch = contextContent.match(/## Locked Decisions\r?\n([\s\S]*?)(?=\r?\n## |\r?\n# |$)/);
+  if (!sectionMatch) return [];
+  const sectionText = sectionMatch[1];
+  // Extract table rows (skip header and separator lines)
+  const rows = sectionText.split(/\r?\n/).filter(l => l.startsWith('|') && !l.includes('---') && !l.includes('Decision'));
+  return rows.map(row => {
+    const cols = row.split('|').map(c => c.trim()).filter(Boolean);
+    return cols.length >= 2 ? { decision: cols[0], rationale: cols[1] } : null;
+  }).filter(Boolean);
+}
+
+/**
+ * Build the Locked Decisions CLAUDE.md section string from decisions array.
+ * Returns empty string if decisions is empty (caller should skip sync).
+ * @param {{ decision: string, rationale: string }[]} decisions
+ * @returns {string}
+ */
+function buildSection(decisions) {
+  if (decisions.length === 0) return '';
+  const rows = decisions.map(d => `| ${d.decision} | ${d.rationale} |`).join('\n');
+  return `${SECTION_START}\n\n> Auto-synced from \`.planning/CONTEXT.md\`. Edit source file, not this section.\n\n| Decision | Rationale |\n|----------|-----------|\n${rows}\n\n${SECTION_END_MARKER}`;
+}
+
+/**
+ * Main sync function. Reads CONTEXT.md from cwd/.planning/ and writes/updates
+ * the Locked Decisions section in cwd/CLAUDE.md.
+ * @param {string} cwd - Project root directory
+ */
+function syncContextToClaude(cwd) {
+  try {
+    const contextPath = path.join(cwd, '.planning', 'CONTEXT.md');
+    const claudePath = path.join(cwd, 'CLAUDE.md');
+
+    if (!fs.existsSync(contextPath)) return;
+
+    const contextContent = fs.readFileSync(contextPath, 'utf8');
+    const decisions = extractLockedDecisions(contextContent);
+
+    if (decisions.length === 0) return; // Nothing to sync
+
+    const section = buildSection(decisions);
+    let claudeContent = fs.existsSync(claudePath) ? fs.readFileSync(claudePath, 'utf8') : '';
+
+    // Replace existing section or append
+    const startIdx = claudeContent.indexOf(SECTION_START);
+    const endIdx = claudeContent.indexOf(SECTION_END_MARKER);
+
+    if (startIdx !== -1 && endIdx !== -1) {
+      // Replace existing section in-place
+      claudeContent = claudeContent.substring(0, startIdx) + section + claudeContent.substring(endIdx + SECTION_END_MARKER.length);
+    } else {
+      // Append new section
+      claudeContent = claudeContent.trimEnd() + '\n\n' + section + '\n';
+    }
+
+    fs.writeFileSync(claudePath, claudeContent, 'utf8');
+    logHook('sync-context-to-claude', 'PostToolUse', 'pass', { decisions: decisions.length });
+  } catch (_e) {
+    // Advisory only — never propagate errors
+  }
+}
+
+module.exports = { syncContextToClaude, extractLockedDecisions, buildSection };
+
+// Main entry point when run as a hook script
+if (require.main === module || process.argv[1] === __filename) {
+  syncContextToClaude(process.env.PBR_PROJECT_ROOT || process.cwd());
+  process.exit(0);
+}

package/plugins/pbr/scripts/task-completed.js

@@ -5,14 +5,33 @@
  *
  * Fires when a Task() sub-agent finishes (distinct from SubagentStop).
  * Logs the completion event and agent type for workflow tracking.
+ * Returns continue:false if a verifier finds critical gaps or an executor
+ * produces no SUMMARY.md — preventing the orchestrator from silently moving on.
  *
  * Non-blocking — exits 0 always.
  */
 
 const fs = require('fs');
+const path = require('path');
 const { logHook } = require('./hook-logger');
 const { logEvent } = require('./event-logger');
 
+/**
+ * Read current_phase from STATE.md frontmatter.
+ * Lightweight — avoids heavy stateLoad() which parses roadmap/config too.
+ */
+function readCurrentPhase(planningDir) {
+  try {
+    const statePath = path.join(planningDir, 'STATE.md');
+    if (!fs.existsSync(statePath)) return null;
+    const content = fs.readFileSync(statePath, 'utf8');
+    const match = content.match(/^current_phase:\s*(\d+)/m);
+    return match ? match[1] : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
 function readStdin() {
   try {
     const input = fs.readFileSync(0, 'utf8').trim();
@@ -23,8 +42,68 @@ function readStdin() {
   return {};
 }
 
+/**
+ * Check whether a halt signal should be emitted after a PBR agent completes.
+ * Returns null (no halt) or { continue: false, stopReason: "..." }.
+ *
+ * @param {object} data - parsed stdin JSON from the TaskCompleted event
+ * @param {string} planningDir - absolute path to the .planning directory
+ * @returns {{ continue: false, stopReason: string }|null}
+ */
+function checkHaltConditions(data, planningDir) {
+  const agentType = data.agent_type || data.subagent_type || null;
+  if (!agentType) return null;
+
+  // --- Verifier: halt if VERIFICATION.md reports gaps_found or failed ---
+  if (agentType === 'pbr:verifier') {
+    try {
+      const rawPhase = readCurrentPhase(planningDir);
+      const phaseNum = rawPhase ? String(rawPhase).padStart(2, '0') : null;
+      if (phaseNum) {
+        const phasesDir = path.join(planningDir, 'phases');
+        const candidates = fs.readdirSync(phasesDir).filter(d => d.startsWith(phaseNum + '-'));
+        const target = candidates.length > 0 ? path.join(phasesDir, candidates[0], 'VERIFICATION.md') : null;
+        if (target && fs.existsSync(target)) {
+          const content = fs.readFileSync(target, 'utf8');
+          const statusMatch = content.match(/^status:\s*(.+)$/m);
+          const status = statusMatch ? statusMatch[1].trim() : null;
+          if (status === 'gaps_found' || status === 'failed') {
+            return {
+              continue: false,
+              stopReason: `Verifier found critical gaps in Phase ${phaseNum} (status: ${status}). Run /pbr:verify-work to address gaps before continuing.`
+            };
+          }
+        }
+      }
+    } catch (_e) { /* non-fatal — fall through to normal exit */ }
+  }
+
+  // --- Executor: halt if SUMMARY.md is missing from current phase dir ---
+  if (agentType === 'pbr:executor') {
+    try {
+      const rawPhase = readCurrentPhase(planningDir);
+      const phaseNum = rawPhase ? String(rawPhase).padStart(2, '0') : null;
+      if (phaseNum) {
+        const phasesDir = path.join(planningDir, 'phases');
+        const candidates = fs.readdirSync(phasesDir).filter(d => d.startsWith(phaseNum + '-'));
+        const target = candidates.length > 0 ? path.join(phasesDir, candidates[0], 'SUMMARY.md') : null;
+        if (target && !fs.existsSync(target)) {
+          return {
+            continue: false,
+            stopReason: `Executor completed Phase ${phaseNum} but produced no SUMMARY.md. Review executor output and re-run /pbr:execute-phase.`
+          };
+        }
+      }
+    } catch (_e) { /* non-fatal */ }
+  }
+
+  return null;
+}
+
 function main() {
   const data = readStdin();
+  const cwd = process.env.PBR_PROJECT_ROOT || process.cwd();
+  const planningDir = path.join(cwd, '.planning');
 
   logHook('task-completed', 'TaskCompleted', 'completed', {
     agent_type: data.agent_type || data.subagent_type || null,
@@ -38,8 +117,51 @@ function main() {
     duration_ms: data.duration_ms || null
   });
 
+  if (fs.existsSync(planningDir)) {
+    const halt = checkHaltConditions(data, planningDir);
+    if (halt) {
+      logHook('task-completed', 'TaskCompleted', 'halting', halt);
+      process.stdout.write(JSON.stringify(halt));
+      process.exit(0);
+    }
+  }
+
   process.exit(0);
 }
 
+/**
+ * HTTP handler for hook-server.js integration.
+ * Called as handleHttp(reqBody, cache) where reqBody = { event, tool, data, planningDir, ... }.
+ * Must NOT call process.exit().
+ * @param {{ data: object, planningDir: string }} reqBody
+ * @returns {{ continue: false, stopReason: string }|null}
+ */
+function handleHttp(reqBody) {
+  const data = reqBody.data || {};
+  const planningDir = reqBody.planningDir;
+
+  logHook('task-completed', 'TaskCompleted', 'completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    duration_ms: data.duration_ms || null
+  });
+
+  logEvent('agent', 'task-completed', {
+    agent_type: data.agent_type || data.subagent_type || null,
+    agent_id: data.agent_id || null,
+    duration_ms: data.duration_ms || null
+  });
+
+  if (planningDir && fs.existsSync(planningDir)) {
+    const halt = checkHaltConditions(data, planningDir);
+    if (halt) {
+      logHook('task-completed', 'TaskCompleted', 'halting', halt);
+      return halt;
+    }
+  }
+
+  return null;
+}
+
 if (require.main === module || process.argv[1] === __filename) { main(); }
-module.exports = { main };
+module.exports = { main, checkHaltConditions, readCurrentPhase, handleHttp };

package/plugins/pbr/scripts/test/config.test.js

@@ -0,0 +1,126 @@
+/**
+ * Unit tests for lib/config.js — Config loading, validation, and depth profiles.
+ */
+
+const { describe, it, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { configLoad, configClearCache, resolveDepthProfile, mergeUserDefaults, DEPTH_PROFILE_DEFAULTS } = require('../lib/config');
+
+afterEach(() => {
+  configClearCache();
+});
+
+describe('configLoad', () => {
+  it('returns null when config.json is missing', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    const result = configLoad(tmpDir);
+    assert.strictEqual(result, null);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('returns parsed config when config.json exists', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    const config = { mode: 'autonomous', depth: 'standard' };
+    fs.writeFileSync(path.join(tmpDir, 'config.json'), JSON.stringify(config), 'utf8');
+
+    const result = configLoad(tmpDir);
+    assert.strictEqual(result.mode, 'autonomous');
+    assert.strictEqual(result.depth, 'standard');
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('returns null for invalid JSON', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    fs.writeFileSync(path.join(tmpDir, 'config.json'), '{ invalid json }', 'utf8');
+
+    const result = configLoad(tmpDir);
+    assert.strictEqual(result, null);
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it('uses mtime-based caching', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-test-'));
+    fs.writeFileSync(path.join(tmpDir, 'config.json'), '{"mode":"interactive"}', 'utf8');
+
+    const result1 = configLoad(tmpDir);
+    const result2 = configLoad(tmpDir);
+    assert.strictEqual(result1, result2); // Same object reference (cached)
+
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+});
+
+describe('resolveDepthProfile', () => {
+  it('returns standard defaults when config is null', () => {
+    const { depth, profile } = resolveDepthProfile(null);
+    assert.strictEqual(depth, 'standard');
+    assert.strictEqual(profile['features.research_phase'], true);
+  });
+
+  it('returns quick profile when depth is quick', () => {
+    const { depth, profile } = resolveDepthProfile({ depth: 'quick' });
+    assert.strictEqual(depth, 'quick');
+    assert.strictEqual(profile['features.research_phase'], false);
+    assert.strictEqual(profile['features.plan_checking'], false);
+  });
+
+  it('returns comprehensive profile when depth is comprehensive', () => {
+    const { depth, profile } = resolveDepthProfile({ depth: 'comprehensive' });
+    assert.strictEqual(depth, 'comprehensive');
+    assert.strictEqual(profile['features.inline_verify'], true);
+  });
+
+  it('merges user overrides from depth_profiles', () => {
+    const config = {
+      depth: 'standard',
+      depth_profiles: {
+        standard: { 'scan.mapper_count': 6 }
+      }
+    };
+    const { profile } = resolveDepthProfile(config);
+    assert.strictEqual(profile['scan.mapper_count'], 6);
+    // Other defaults preserved
+    assert.strictEqual(profile['features.research_phase'], true);
+  });
+});
+
+describe('mergeUserDefaults', () => {
+  it('uses user defaults when base key is missing', () => {
+    const base = { mode: 'interactive' };
+    const defaults = { mode: 'autonomous', depth: 'comprehensive' };
+    const merged = mergeUserDefaults(base, defaults);
+    assert.strictEqual(merged.mode, 'interactive'); // base wins
+    assert.strictEqual(merged.depth, 'comprehensive'); // from defaults
+  });
+
+  it('deep-merges nested objects', () => {
+    const base = { features: { research_phase: true } };
+    const defaults = { features: { plan_checking: true, research_phase: false } };
+    const merged = mergeUserDefaults(base, defaults);
+    assert.strictEqual(merged.features.research_phase, true); // base wins
+    assert.strictEqual(merged.features.plan_checking, true); // from defaults
+  });
+
+  it('returns base unchanged when defaults is null', () => {
+    const base = { mode: 'interactive' };
+    const merged = mergeUserDefaults(base, null);
+    assert.deepStrictEqual(merged, base);
+  });
+});
+
+describe('config paths use path.join', () => {
+  it('USER_DEFAULTS_PATH uses platform path separator', () => {
+    const { USER_DEFAULTS_PATH } = require('../lib/config');
+    // Should contain the platform-appropriate separator
+    assert.ok(USER_DEFAULTS_PATH.includes('pbr-defaults.json'));
+    // Should NOT contain a mix of forward and back slashes (unless on platform that uses them)
+    if (process.platform === 'win32') {
+      assert.ok(USER_DEFAULTS_PATH.includes('\\'));
+    }
+  });
+});

package/plugins/pbr/scripts/test/cross-platform.test.js

@@ -0,0 +1,131 @@
+/**
+ * Cross-platform tests — CRLF normalization, path construction, MSYS path regex.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const path = require('path');
+const { parseYamlFrontmatter } = require('../lib/core');
+const { parseStateMd } = require('../lib/state');
+const { parseRoadmapMd } = require('../lib/roadmap');
+
+// --- CRLF normalization ---
+
+describe('CRLF normalization', () => {
+  const FRONTMATTER_LF = '---\nversion: 2\ncurrent_phase: 5\nstatus: "built"\n---\n# Test';
+  const FRONTMATTER_CRLF = '---\r\nversion: 2\r\ncurrent_phase: 5\r\nstatus: "built"\r\n---\r\n# Test';
+
+  it('parseYamlFrontmatter: CRLF produces same result as LF', () => {
+    const lfResult = parseYamlFrontmatter(FRONTMATTER_LF);
+    const crlfResult = parseYamlFrontmatter(FRONTMATTER_CRLF);
+    assert.strictEqual(crlfResult.version, lfResult.version);
+    assert.strictEqual(crlfResult.current_phase, lfResult.current_phase);
+    assert.strictEqual(crlfResult.status, lfResult.status);
+  });
+
+  it('parseStateMd: CRLF produces same result as LF', () => {
+    const STATE = '---\nversion: 2\ncurrent_phase: 3\nstatus: "building"\nprogress_percent: 50\nplans_complete: 2\nplans_total: 4\n---\n# State\nPhase: 3 of 8\nStatus: Building\nPlan: 2 of 4';
+    const lfResult = parseStateMd(STATE);
+    const crlfResult = parseStateMd(STATE.replace(/\n/g, '\r\n'));
+    assert.strictEqual(crlfResult.current_phase, lfResult.current_phase);
+    assert.strictEqual(crlfResult.status, lfResult.status);
+    assert.strictEqual(crlfResult.plans_complete, lfResult.plans_complete);
+  });
+
+  it('parseRoadmapMd: CRLF produces same result as LF', () => {
+    const ROADMAP = '# Roadmap\n\n## Phase Overview\n\n| Phase | Name | Goal |\n|---|---|---|\n| 01 | Setup | Init |\n| 02 | Build | Core |\n';
+    const lfResult = parseRoadmapMd(ROADMAP);
+    const crlfResult = parseRoadmapMd(ROADMAP.replace(/\n/g, '\r\n'));
+    assert.strictEqual(crlfResult.phases.length, lfResult.phases.length);
+    assert.strictEqual(crlfResult.phases[0].number, lfResult.phases[0].number);
+    assert.strictEqual(crlfResult.phases[1].name, lfResult.phases[1].name);
+  });
+
+  it('mixed line endings (\\r\\n and \\n) still parse correctly', () => {
+    // Simulate a file with inconsistent line endings
+    const mixed = '---\r\nversion: 2\ncurrent_phase: 7\r\nstatus: "planned"\n---\n# Test';
+    const result = parseYamlFrontmatter(mixed);
+    assert.strictEqual(result.version, 2);
+    assert.strictEqual(result.current_phase, 7);
+    assert.strictEqual(result.status, 'planned');
+  });
+});
+
+// --- Path construction ---
+
+describe('path construction', () => {
+  it('path.join produces valid paths on current platform', () => {
+    const result = path.join('plugins', 'pbr', 'scripts', 'lib', 'state.js');
+    assert.ok(result.includes('state.js'));
+    // No double separators
+    assert.ok(!result.includes('//'));
+    assert.ok(!result.includes('\\\\'));
+  });
+
+  it('path.join handles mixed separators', () => {
+    const result = path.join('plugins/pbr', 'scripts\\lib', 'core.js');
+    assert.ok(result.includes('core.js'));
+    assert.ok(result.includes('plugins'));
+  });
+
+  it('path.resolve produces absolute path', () => {
+    const result = path.resolve('plugins', 'pbr', 'scripts');
+    assert.ok(path.isAbsolute(result));
+  });
+});
+
+// --- MSYS path regex ---
+
+describe('MSYS path regex', () => {
+  // This is the regex from run-hook.js bootstrap pattern
+  const MSYS_REGEX = /^\/([a-zA-Z])\/(.*)/;
+
+  function fixMsysPath(p) {
+    if (!p) return p;
+    const match = p.match(MSYS_REGEX);
+    if (match) {
+      return match[1].toUpperCase() + ':\\' + match[2].replace(/\//g, '\\');
+    }
+    return p;
+  }
+
+  it('converts /d/Repos/foo to D:\\Repos\\foo', () => {
+    const result = fixMsysPath('/d/Repos/foo');
+    assert.strictEqual(result, 'D:\\Repos\\foo');
+  });
+
+  it('converts /D/Repos/foo to D:\\Repos\\foo (case insensitive drive)', () => {
+    const result = fixMsysPath('/D/Repos/foo');
+    assert.strictEqual(result, 'D:\\Repos\\foo');
+  });
+
+  it('converts /c/Users/test/project to C:\\Users\\test\\project', () => {
+    const result = fixMsysPath('/c/Users/test/project');
+    assert.strictEqual(result, 'C:\\Users\\test\\project');
+  });
+
+  it('leaves Windows-native paths unchanged', () => {
+    const result = fixMsysPath('D:\\Repos\\foo');
+    assert.strictEqual(result, 'D:\\Repos\\foo');
+  });
+
+  it('leaves relative paths unchanged', () => {
+    const result = fixMsysPath('plugins/pbr/scripts');
+    assert.strictEqual(result, 'plugins/pbr/scripts');
+  });
+
+  it('leaves Unix absolute paths with >1 char dir unchanged', () => {
+    const result = fixMsysPath('/usr/local/bin');
+    assert.strictEqual(result, '/usr/local/bin');
+  });
+
+  it('handles null/empty input', () => {
+    assert.strictEqual(fixMsysPath(null), null);
+    assert.strictEqual(fixMsysPath(''), '');
+  });
+
+  it('handles deep nested MSYS paths', () => {
+    const result = fixMsysPath('/e/Projects/my-app/plugins/pbr/scripts/lib');
+    assert.strictEqual(result, 'E:\\Projects\\my-app\\plugins\\pbr\\scripts\\lib');
+  });
+});

package/plugins/pbr/scripts/test/fixtures/config.json

@@ -0,0 +1,20 @@
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "schema_version": 2,
+  "parallelization": {
+    "enabled": true,
+    "plan_level": false,
+    "max_concurrent_agents": 3
+  },
+  "git": {
+    "branching": "phase",
+    "auto_commit": true
+  },
+  "features": {
+    "research_phase": true,
+    "plan_checking": true,
+    "goal_verification": true,
+    "inline_verify": false
+  }
+}

package/plugins/pbr/scripts/test/fixtures/plan.md

@@ -0,0 +1,54 @@
+---
+phase: 01-foundation
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/core/setup.js
+  - src/core/config.js
+autonomous: true
+must_haves:
+  truths:
+    - "Core setup module exists and exports expected functions"
+  artifacts:
+    - path: "src/core/setup.js"
+      provides: "Project initialization logic"
+---
+
+<objective>
+Set up the core project structure with initialization and configuration modules.
+</objective>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create core setup module</name>
+  <files>src/core/setup.js</files>
+  <action>
+    Create src/core/setup.js with project initialization logic.
+  </action>
+  <verify>
+    <automated>node -e "require('./src/core/setup.js')"</automated>
+  </verify>
+  <done>
+    setup.js exists and can be required without errors.
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. `node -e "require('./src/core/setup.js')"` -- module loads
+2. `node -e "require('./src/core/config.js')"` -- config loads
+</verification>
+
+<success_criteria>
+- Core setup module exists with initialization function
+- Config module exists with load/validate functions
+</success_criteria>

package/plugins/pbr/scripts/test/fixtures/project.md

@@ -0,0 +1,30 @@
+# Project: Fixture Test Project
+
+## What This Is
+
+A minimal PROJECT.md fixture for testing the PBR file format parsers. This file follows the Phase 5 consolidated format where CONTEXT.md is merged into the Context section.
+
+## Core Value
+
+Ensure PBR planning file formats remain stable across versions by providing canonical fixture examples that automated tests validate against production parsers.
+
+## Requirements Summary
+
+| Category | Count | Key Requirements |
+|----------|-------|-----------------|
+| Setup | 2 | SETUP-01, SETUP-02 |
+| Features | 2 | FEAT-01, FEAT-02 |
+| Testing | 1 | TEST-01 |
+
+## Context
+
+**Tech stack:** Node.js, CommonJS modules, node:test runner
+**Target users:** PBR plugin developers and contributors
+**Key constraint:** Zero external dependencies for core parsing
+
+## Key Decisions
+
+| Phase | Decision | Rationale |
+|-------|----------|-----------|
+| Phase 1 | Use built-in modules only | Zero-dependency operation |
+| Phase 2 | CommonJS over ESM | Plugin ecosystem compatibility |

package/plugins/pbr/scripts/test/fixtures/roadmap.md

@@ -0,0 +1,55 @@
+# Roadmap
+
+## Overview
+
+A minimal roadmap fixture with 2 phases for testing.
+
+## Phases
+
+- [x] Phase 1: Foundation
+- [ ] Phase 2: Features
+
+## Phase Details
+
+## Milestone: v1.0
+
+### Phase 1: Foundation
+
+**Goal:** Set up project structure and core utilities
+**Depends on:** None
+**Requirements:** SETUP-01, SETUP-02
+**Success Criteria:** All core modules exist and pass validation
+
+**Plans:**
+1. 01-01: Core setup
+2. 01-02: Config system
+
+### Phase 2: Features
+
+**Goal:** Implement primary feature set
+**Depends on:** Phase 1
+**Requirements:** FEAT-01, FEAT-02
+**Success Criteria:** Feature tests pass
+
+**Plans:**
+1. 02-01: Feature A
+2. 02-02: Feature B
+
+## Standing Disciplines
+
+- Review all changes before commit
+- Maintain test coverage
+
+## Phase Overview
+
+| Phase | Name | Goal | Plans | Wave | Status |
+|-------|------|------|-------|------|--------|
+| 01 | Foundation | Core setup | 2/2 | 1 | verified |
+| 02 | Features | Feature set | 0/2 | 2 | planned |
+
+## Progress
+
+| Phase | Plans Complete | Status | Completed |
+|-------|---------------|--------|-----------|
+| 1. Foundation | 2/2 | Complete | 2026-02-28 |
+| 2. Features | 0/2 | Pending | -- |