@sienklogic/plan-build-run 2.37.0 → 2.38.1

package/plugins/pbr/references/verification-patterns.md

@@ -4,9 +4,9 @@ Reference patterns for deriving verification criteria from goals. Used by the pl
 
 ---
 
-## The Three-Layer Check
+## The Four-Layer Check
 
-Every must-have is verified through three layers, checked in order:
+Every must-have is verified through up to four layers, checked in order:
 
 ### Layer 1: Existence
 
@@ -62,6 +62,28 @@ grep -q "prisma" src/app.ts
 grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
 ```
 
+### Layer 4: Functional
+
+Does the artifact actually work when executed?
+
+```bash
+# Tests pass
+npm test -- --testPathPattern auth
+pytest tests/test_auth.py -v
+
+# Build succeeds
+npm run build
+npx tsc --noEmit
+
+# API returns correct data
+curl -s http://localhost:3000/api/auth/login -X POST -d '{"code":"test"}' | jq '.token'
+
+# CLI produces expected output
+node src/cli.js --help | grep -q "Usage:"
+```
+
+**When to apply L4:** Only when automated verification commands exist (test suites, build scripts, API endpoints with test data). Skip for items requiring manual/visual testing. L4 is optional — artifacts passing L1-L3 without available automated tests are reported as `PASSED (L3 only)`.
+
 ---
 
 ## Verification by Feature Type
@@ -69,41 +91,46 @@ grep -q "DISCORD_CLIENT_ID" src/auth/discord.ts
 ### API Endpoint
 
 ```
-Existence:  curl returns non-404 status
-Substance:  curl returns expected response shape (correct fields)
-Wiring:     endpoint calls the right service, middleware is applied
+Existence:   curl returns non-404 status
+Substance:   curl returns expected response shape (correct fields)
+Wiring:      endpoint calls the right service, middleware is applied
+Functional:  POST/GET with test data returns correct response, error cases handled
 ```
 
 ### Database Schema
 
 ```
-Existence:  table/collection exists, can query without error
-Substance:  columns/fields match specification, constraints are applied
-Wiring:     application code references the schema, migrations run cleanly
+Existence:   table/collection exists, can query without error
+Substance:   columns/fields match specification, constraints are applied
+Wiring:      application code references the schema, migrations run cleanly
+Functional:  CRUD operations work end-to-end, constraints reject invalid data
 ```
 
 ### Authentication
 
 ```
-Existence:  auth routes exist, auth module exports functions
-Substance:  login flow returns token, invalid creds return error
-Wiring:     protected routes use auth middleware, tokens are validated
+Existence:   auth routes exist, auth module exports functions
+Substance:   login flow returns token, invalid creds return error
+Wiring:      protected routes use auth middleware, tokens are validated
+Functional:  auth tests pass (valid token, expired token, missing token, malformed token)
 ```
 
 ### UI Component
 
 ```
-Existence:  component file exists, exports default component
-Substance:  component renders expected elements (test or visual check)
-Wiring:     component is imported in parent, receives correct props, routes to it
+Existence:   component file exists, exports default component
+Substance:   component renders expected elements (test or visual check)
+Wiring:      component is imported in parent, receives correct props, routes to it
+Functional:  component tests pass, build succeeds with component included
 ```
 
 ### Configuration
 
 ```
-Existence:  config file exists, environment variables documented
-Substance:  config values are used (not dead code), defaults are sensible
-Wiring:     application reads config at startup, config changes take effect
+Existence:   config file exists, environment variables documented
+Substance:   config values are used (not dead code), defaults are sensible
+Wiring:      application reads config at startup, config changes take effect
+Functional:  app starts with config, missing config produces clear error message
 ```
 
 ---

package/plugins/pbr/scripts/context-bridge.js

@@ -11,9 +11,10 @@
  *   PEAK      (0-30%)  — no warnings
  *   GOOD      (30-50%) — no warnings
  *   DEGRADING (50-70%) — suggest subagent delegation
- *   POOR      (70%+)   — recommend /pbr:pause
+ *   POOR      (70-85%) — recommend /pbr:pause
+ *   CRITICAL  (85%+)   — urgent stop, context rot imminent
  *
- * Debounce: same-tier warnings suppressed for 5 tool calls.
+ * Debounce: same-tier warnings suppressed for 5 tool calls (2 for CRITICAL).
  * Tier escalation always warns immediately.
  *
  * Exit codes:
@@ -28,15 +29,18 @@ const TIERS = [
   { name: 'PEAK', min: 0, max: 30 },
   { name: 'GOOD', min: 30, max: 50 },
   { name: 'DEGRADING', min: 50, max: 70 },
-  { name: 'POOR', min: 70, max: 100 }
+  { name: 'POOR', min: 70, max: 85 },
+  { name: 'CRITICAL', min: 85, max: 100 }
 ];
 
 const TIER_MESSAGES = {
-  DEGRADING: 'Context is filling. Consider delegating heavy work to subagents.',
-  POOR: 'Context critically low. Recommend /pbr:pause to save state.'
+  DEGRADING: 'Context at ~50-70%. Delegate heavy reads and analysis to Task() subagents to preserve orchestrator quality.',
+  POOR: 'Context at ~70-85%. Run /pbr:pause soon to save state before quality degrades.',
+  CRITICAL: 'STOP — Context at 85%+. Run /pbr:pause NOW. Context rot is imminent — further work risks hallucinations and skipped steps.'
 };
 
 const DEBOUNCE_INTERVAL = 5; // tool calls between same-tier warnings
+const CRITICAL_DEBOUNCE_INTERVAL = 2; // shorter debounce for CRITICAL tier
 
 /**
  * Determine the context tier for a given percentage.
@@ -117,13 +121,14 @@ function shouldWarn(bridge, tierName) {
   const callsSinceWarn = bridge.calls_since_warn || 0;
 
   // Tier escalation — always warn
-  const tierOrder = { PEAK: 0, GOOD: 1, DEGRADING: 2, POOR: 3 };
+  const tierOrder = { PEAK: 0, GOOD: 1, DEGRADING: 2, POOR: 3, CRITICAL: 4 };
   if ((tierOrder[tierName] || 0) > (tierOrder[prevTier] || 0)) {
     return true;
   }
 
-  // Same tier — debounce
-  if (callsSinceWarn >= DEBOUNCE_INTERVAL) {
+  // Same tier — debounce (CRITICAL uses shorter interval)
+  const interval = tierName === 'CRITICAL' ? CRITICAL_DEBOUNCE_INTERVAL : DEBOUNCE_INTERVAL;
+  if (callsSinceWarn >= interval) {
     return true;
   }
 
@@ -253,7 +258,8 @@ module.exports = {
   updateBridge,
   TIERS,
   TIER_MESSAGES,
-  DEBOUNCE_INTERVAL
+  DEBOUNCE_INTERVAL,
+  CRITICAL_DEBOUNCE_INTERVAL
 };
 
 if (require.main === module || process.argv[1] === __filename) { main(); }

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

@@ -8,6 +8,7 @@
 const fs = require('fs');
 const path = require('path');
 const { validateObject } = require('./core');
+const { CURRENT_SCHEMA_VERSION } = require('./migrate');
 
 // --- Cached config loader ---
 
@@ -84,10 +85,11 @@ function configValidate(preloadedConfig, planningDir) {
 
   validateObject(config, schema, '', errors, warnings);
 
-  // Schema version check — detect outdated config format
-  const CURRENT_SCHEMA_VERSION = 1;
+  // Schema version check — detect outdated or future config format
   if (config.schema_version && config.schema_version > CURRENT_SCHEMA_VERSION) {
     warnings.push(`config.json schema_version (${config.schema_version}) is newer than this PBR version supports (${CURRENT_SCHEMA_VERSION}). Some fields may be ignored. Consider updating PBR.`);
+  } else if (!config.schema_version || config.schema_version < CURRENT_SCHEMA_VERSION) {
+    warnings.push(`config.json schema is outdated. Run: node pbr-tools.js migrate`);
   }
 
   // Semantic conflict detection — logical contradictions that pass schema validation
@@ -169,10 +171,101 @@ function resolveDepthProfile(config) {
   return { depth, profile };
 }
 
+// --- User-level defaults ---
+
+const USER_DEFAULTS_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE || '',
+  '.claude',
+  'pbr-defaults.json'
+);
+
+/**
+ * Load user-level defaults from ~/.claude/pbr-defaults.json.
+ * Returns null if file doesn't exist or is invalid.
+ *
+ * @returns {object|null} User defaults or null
+ */
+function loadUserDefaults() {
+  try {
+    if (!fs.existsSync(USER_DEFAULTS_PATH)) return null;
+    return JSON.parse(fs.readFileSync(USER_DEFAULTS_PATH, 'utf8'));
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Save current project config as user-level defaults.
+ * Only saves portable keys (excludes project-specific state).
+ *
+ * @param {object} config - Current project config.json contents
+ * @returns {{ saved: boolean, path: string, keys: string[] }}
+ */
+function saveUserDefaults(config) {
+  const portableKeys = [
+    'mode', 'depth', 'context_strategy',
+    'features', 'models', 'parallelization',
+    'planning', 'git', 'gates', 'safety',
+    'hooks', 'dashboard', 'status_line'
+  ];
+
+  const defaults = {};
+  for (const key of portableKeys) {
+    if (config[key] !== undefined) {
+      defaults[key] = config[key];
+    }
+  }
+
+  const dir = path.dirname(USER_DEFAULTS_PATH);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(USER_DEFAULTS_PATH, JSON.stringify(defaults, null, 2), 'utf8');
+
+  return {
+    saved: true,
+    path: USER_DEFAULTS_PATH,
+    keys: Object.keys(defaults)
+  };
+}
+
+/**
+ * Deep-merge user defaults into a base config.
+ * User defaults provide values only where the base config doesn't already set them.
+ * For nested objects, merges recursively. Scalars from base take precedence.
+ *
+ * @param {object} base - The base config (project defaults from setup)
+ * @param {object} userDefaults - User-level defaults from ~/.claude/pbr-defaults.json
+ * @returns {object} Merged config
+ */
+function mergeUserDefaults(base, userDefaults) {
+  if (!userDefaults) return base;
+
+  const result = { ...base };
+  for (const [key, value] of Object.entries(userDefaults)) {
+    if (result[key] === undefined) {
+      // Key not in base — use user default
+      result[key] = value;
+    } else if (
+      typeof value === 'object' && value !== null && !Array.isArray(value) &&
+      typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key])
+    ) {
+      // Both are objects — merge recursively (base values take precedence)
+      result[key] = mergeUserDefaults(result[key], value);
+    }
+    // Scalar in base already set — base wins
+  }
+  return result;
+}
+
 module.exports = {
   configLoad,
   configClearCache,
   configValidate,
   resolveDepthProfile,
-  DEPTH_PROFILE_DEFAULTS
+  DEPTH_PROFILE_DEFAULTS,
+  loadUserDefaults,
+  saveUserDefaults,
+  mergeUserDefaults,
+  USER_DEFAULTS_PATH
 };

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

@@ -319,6 +319,15 @@ function atomicWrite(filePath, content) {
     // 3. Rename temp over original (atomic on most filesystems)
     fs.renameSync(tmpPath, filePath);
 
+    // 4. Clean up backup file on success
+    try {
+      if (fs.existsSync(bakPath)) {
+        fs.unlinkSync(bakPath);
+      }
+    } catch (_e) {
+      // Cleanup failure is non-fatal
+    }
+
     return { success: true };
   } catch (e) {
     // Rename failed — try to restore from backup

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

@@ -0,0 +1,169 @@
+/**
+ * lib/migrate.js — Schema migration for Plan-Build-Run config.json.
+ *
+ * Tracks config.json schema version and applies sequential migrations
+ * to bring outdated configs up to the current version.
+ *
+ * Usage:
+ *   const { applyMigrations, CURRENT_SCHEMA_VERSION } = require('./migrate');
+ *   const result = await applyMigrations(planningDir, { dryRun: false });
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { atomicWrite } = require('./core');
+
+/** The current schema version supported by this version of PBR. */
+const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Migration registry. Each entry describes one schema version step.
+ * Migrations MUST be listed in ascending `from` order.
+ *
+ * @type {Array<{ from: number, to: number, description: string, migrate: function }>}
+ */
+const MIGRATIONS = [
+  {
+    from: 0,
+    to: 1,
+    description: 'Add schema_version field',
+    migrate(config) {
+      config.schema_version = 1;
+    }
+  }
+];
+
+/**
+ * Detect the current schema version from a config object.
+ * Returns 0 if schema_version is absent or non-numeric.
+ *
+ * @param {object} config - Parsed config.json object
+ * @returns {number} Detected schema version
+ */
+function detectSchemaVersion(config) {
+  const v = config && config.schema_version;
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  return 0;
+}
+
+/**
+ * Return the ordered list of migrations needed to go from `fromVersion` to `toVersion`.
+ * Returns an empty array if versions are equal.
+ * Throws if fromVersion > toVersion (downgrade not supported).
+ *
+ * @param {number} fromVersion - Current schema version
+ * @param {number} toVersion - Target schema version
+ * @returns {Array} Ordered migrations to apply
+ */
+function getMigrationPath(fromVersion, toVersion) {
+  if (fromVersion > toVersion) {
+    throw new Error(`Cannot downgrade schema from version ${fromVersion} to ${toVersion}`);
+  }
+  if (fromVersion === toVersion) return [];
+  return MIGRATIONS.filter(m => m.from >= fromVersion && m.to <= toVersion);
+}
+
+/**
+ * Apply pending migrations to config.json in planningDir.
+ *
+ * Options:
+ *   dryRun {boolean} — If true, simulate migration without writing files (default: false)
+ *   force  {boolean} — Reserved for future use (default: false)
+ *
+ * Returns:
+ *   { migrated: false, version: N }                          — already current
+ *   { migrated: false, message: string }                     — future version, no-op
+ *   { migrated: true, fromVersion, toVersion, applied, backupPath } — success
+ *   { error: string }                                        — failure
+ *
+ * @param {string} planningDir - Path to .planning directory
+ * @param {object} [options] - Options { dryRun, force }
+ * @returns {Promise<object>} Result object
+ */
+async function applyMigrations(planningDir, options) {
+  const opts = options || {};
+  const dryRun = opts.dryRun === true;
+
+  const configPath = path.join(planningDir, 'config.json');
+
+  // Load config.json
+  if (!fs.existsSync(configPath)) {
+    return { error: 'config.json not found in ' + planningDir };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (e) {
+    return { error: 'config.json is not valid JSON: ' + e.message };
+  }
+
+  const currentVersion = detectSchemaVersion(config);
+
+  // Future version — don't touch it
+  if (currentVersion > CURRENT_SCHEMA_VERSION) {
+    return {
+      migrated: false,
+      version: currentVersion,
+      message: `config.json schema_version (${currentVersion}) is newer than this PBR version supports (${CURRENT_SCHEMA_VERSION}). No migration applied.`
+    };
+  }
+
+  // Already current
+  if (currentVersion === CURRENT_SCHEMA_VERSION) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Determine migrations to apply
+  const migrations = getMigrationPath(currentVersion, CURRENT_SCHEMA_VERSION);
+  if (migrations.length === 0) {
+    return { migrated: false, version: currentVersion };
+  }
+
+  // Clone config for mutation
+  const updatedConfig = JSON.parse(JSON.stringify(config));
+
+  // Apply each migration in sequence
+  const applied = [];
+  for (const m of migrations) {
+    m.migrate(updatedConfig);
+    applied.push(m.description);
+  }
+
+  if (dryRun) {
+    return {
+      migrated: true,
+      fromVersion: currentVersion,
+      toVersion: CURRENT_SCHEMA_VERSION,
+      applied,
+      dryRun: true
+    };
+  }
+
+  // Create backup
+  const backupDir = path.join(planningDir, '.migration-backup');
+  const backupPath = path.join(backupDir, 'config.json.bak');
+  if (!fs.existsSync(backupDir)) {
+    fs.mkdirSync(backupDir, { recursive: true });
+  }
+  fs.copyFileSync(configPath, backupPath);
+
+  // Write updated config atomically
+  atomicWrite(configPath, JSON.stringify(updatedConfig, null, 2));
+
+  return {
+    migrated: true,
+    fromVersion: currentVersion,
+    toVersion: CURRENT_SCHEMA_VERSION,
+    applied,
+    backupPath
+  };
+}
+
+module.exports = {
+  CURRENT_SCHEMA_VERSION,
+  MIGRATIONS,
+  detectSchemaVersion,
+  getMigrationPath,
+  applyMigrations
+};