@sienklogic/plan-build-run 2.1.0 → 2.1.1

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

@@ -0,0 +1,934 @@
+/**
+ * lib/core.js — Foundation utilities for Plan-Build-Run tools.
+ *
+ * Pure utility functions with no dependencies on other lib modules.
+ * Provides: output/error formatting, YAML frontmatter parsing, status transitions,
+ * file operations (atomicWrite, lockedFileUpdate, findFiles, tailLines),
+ * and shared constants (KNOWN_AGENTS, VALID_STATUS_TRANSITIONS).
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+/**
+ * Canonical list of known PBR agent types.
+ * Imported by validate-task.js and check-subagent-output.js to avoid drift.
+ */
+const KNOWN_AGENTS = [
+  'researcher',
+  'planner',
+  'plan-checker',
+  'executor',
+  'verifier',
+  'integration-checker',
+  'debugger',
+  'codebase-mapper',
+  'synthesizer',
+  'general',
+  'audit',
+  'dev-sync'
+];
+
+// --- Phase status transition state machine ---
+
+/**
+ * Valid phase status transitions. Each key is a current status, and its value
+ * is an array of statuses that are legal to transition to. This is advisory —
+ * invalid transitions produce a stderr warning but are not blocked, to avoid
+ * breaking existing workflows.
+ *
+ * State machine:
+ *   pending -> planned, skipped
+ *   planned -> building
+ *   building -> built, partial, needs_fixes
+ *   built -> verified, needs_fixes
+ *   partial -> building, needs_fixes
+ *   verified -> building (re-execution)
+ *   needs_fixes -> planned, building
+ *   skipped -> pending (unskip)
+ */
+const VALID_STATUS_TRANSITIONS = {
+  pending:     ['planned', 'skipped'],
+  planned:     ['building'],
+  building:    ['built', 'partial', 'needs_fixes'],
+  built:       ['verified', 'needs_fixes'],
+  partial:     ['building', 'needs_fixes'],
+  verified:    ['building'],
+  needs_fixes: ['planned', 'building'],
+  skipped:     ['pending']
+};
+
+/**
+ * Check whether a phase status transition is valid according to the state machine.
+ * Returns { valid, warning? } — never blocks, only advises.
+ *
+ * @param {string} oldStatus - Current phase status
+ * @param {string} newStatus - Desired phase status
+ * @returns {{ valid: boolean, warning?: string }}
+ */
+function validateStatusTransition(oldStatus, newStatus) {
+  const from = (oldStatus || '').trim().toLowerCase();
+  const to = (newStatus || '').trim().toLowerCase();
+
+  // If the status isn't changing, that's always fine
+  if (from === to) {
+    return { valid: true };
+  }
+
+  // If the old status is unknown to our map, we can't validate — allow it
+  if (!VALID_STATUS_TRANSITIONS[from]) {
+    return { valid: true };
+  }
+
+  const allowed = VALID_STATUS_TRANSITIONS[from];
+  if (allowed.includes(to)) {
+    return { valid: true };
+  }
+
+  return {
+    valid: false,
+    warning: `Suspicious status transition: "${from}" -> "${to}". Expected one of: [${allowed.join(', ')}]. Proceeding anyway (advisory).`
+  };
+}
+
+// --- Output helpers ---
+
+function output(data) {
+  const json = JSON.stringify(data, null, 2);
+  if (json.length > 50000) {
+    const tmpPath = path.join(os.tmpdir(), `pbr-${Date.now()}.json`);
+    fs.writeFileSync(tmpPath, json, 'utf8');
+    process.stdout.write('@file:' + tmpPath + '\n');
+  } else {
+    process.stdout.write(json + '\n');
+  }
+  process.exit(0);
+}
+
+function error(msg) {
+  process.stdout.write(JSON.stringify({ error: msg }));
+  process.exit(1);
+}
+
+// --- YAML frontmatter parsing ---
+
+function parseYamlFrontmatter(content) {
+  // Normalize CRLF to LF at parse boundary for cross-platform support
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return {};
+
+  const yaml = match[1];
+  const result = {};
+
+  // Simple YAML parser for flat and basic nested values
+  const lines = yaml.split('\n');
+  let currentKey = null;
+
+  for (const line of lines) {
+    // Array item
+    if (/^\s+-\s+/.test(line) && currentKey) {
+      const val = line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, '');
+      if (!result[currentKey]) result[currentKey] = [];
+      if (Array.isArray(result[currentKey])) {
+        result[currentKey].push(val);
+      }
+      continue;
+    }
+
+    // Key-value pair
+    const kvMatch = line.match(/^(\w[\w_]*)\s*:\s*(.*)/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      let val = kvMatch[2].trim();
+
+      if (val === '' || val === '|') {
+        // Possible array or block follows
+        continue;
+      }
+
+      // Handle arrays on same line: [a, b, c]
+      if (val.startsWith('[') && val.endsWith(']')) {
+        result[currentKey] = val.slice(1, -1).split(',')
+          .map(v => v.trim().replace(/^["']|["']$/g, ''))
+          .filter(Boolean);
+        continue;
+      }
+
+      // Clean quotes
+      val = val.replace(/^["']|["']$/g, '');
+
+      // Type coercion
+      if (val === 'true') val = true;
+      else if (val === 'false') val = false;
+      else if (/^\d+$/.test(val)) val = parseInt(val, 10);
+
+      result[currentKey] = val;
+    }
+  }
+
+  // Handle must_haves as a nested object
+  if (yaml.includes('must_haves:')) {
+    result.must_haves = parseMustHaves(yaml);
+  }
+
+  return result;
+}
+
+function parseMustHaves(yaml) {
+  const result = { truths: [], artifacts: [], key_links: [] };
+  let section = null;
+
+  const inMustHaves = yaml.replace(/\r\n/g, '\n').split('\n');
+  let collecting = false;
+
+  for (const line of inMustHaves) {
+    if (/^\s*must_haves:/.test(line)) {
+      collecting = true;
+      continue;
+    }
+    if (collecting) {
+      if (/^\s{2}truths:/.test(line)) { section = 'truths'; continue; }
+      if (/^\s{2}artifacts:/.test(line)) { section = 'artifacts'; continue; }
+      if (/^\s{2}key_links:/.test(line)) { section = 'key_links'; continue; }
+      if (/^\w/.test(line)) break; // New top-level key, stop
+
+      if (section && /^\s+-\s+/.test(line)) {
+        result[section].push(line.replace(/^\s+-\s+/, '').trim().replace(/^["']|["']$/g, ''));
+      }
+    }
+  }
+
+  return result;
+}
+
+// --- File helpers ---
+
+function findFiles(dir, pattern) {
+  try {
+    return fs.readdirSync(dir).filter(f => pattern.test(f)).sort();
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Read the last N lines from a file efficiently.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @param {number} n - Number of trailing lines to return
+ * @returns {string[]} Array of raw line strings (last n lines)
+ */
+function tailLines(filePath, n) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    const content = fs.readFileSync(filePath, 'utf8').trim();
+    if (!content) return [];
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    if (lines.length <= n) return lines;
+    return lines.slice(lines.length - n);
+  } catch (_e) {
+    return [];
+  }
+}
+
+function countMustHaves(mustHaves) {
+  if (!mustHaves) return 0;
+  return (mustHaves.truths || []).length +
+    (mustHaves.artifacts || []).length +
+    (mustHaves.key_links || []).length;
+}
+
+function determinePhaseStatus(planCount, completedCount, summaryCount, hasVerification, phaseDir) {
+  if (planCount === 0) {
+    // Check for CONTEXT.md (discussed only)
+    if (fs.existsSync(path.join(phaseDir, 'CONTEXT.md'))) return 'discussed';
+    return 'not_started';
+  }
+  if (completedCount === 0 && summaryCount === 0) return 'planned';
+  if (completedCount < planCount) return 'building';
+  if (!hasVerification) return 'built';
+  // Check verification status
+  try {
+    const vContent = fs.readFileSync(path.join(phaseDir, 'VERIFICATION.md'), 'utf8');
+    if (/status:\s*["']?passed/i.test(vContent)) return 'verified';
+    if (/status:\s*["']?gaps_found/i.test(vContent)) return 'needs_fixes';
+    return 'reviewed';
+  } catch (_) {
+    return 'built';
+  }
+}
+
+function calculateProgress(planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { total: 0, completed: 0, percentage: 0 };
+  }
+
+  let total = 0;
+  let completed = 0;
+
+  const entries = fs.readdirSync(phasesDir, { withFileTypes: true })
+    .filter(e => e.isDirectory());
+
+  for (const entry of entries) {
+    const dir = path.join(phasesDir, entry.name);
+    const plans = findFiles(dir, /PLAN.*\.md$/i);
+    total += plans.length;
+
+    const summaries = findFiles(dir, /^SUMMARY-.*\.md$/);
+    for (const s of summaries) {
+      const content = fs.readFileSync(path.join(dir, s), 'utf8');
+      if (/status:\s*["']?complete/i.test(content)) completed++;
+    }
+  }
+
+  return {
+    total,
+    completed,
+    percentage: total > 0 ? Math.round((completed / total) * 100) : 0
+  };
+}
+
+// --- Atomic file operations ---
+
+/**
+ * Write content to a file atomically: write to .tmp, backup original to .bak,
+ * rename .tmp over original. On failure, restore from .bak if available.
+ *
+ * @param {string} filePath - Target file path
+ * @param {string} content - Content to write
+ * @returns {{success: boolean, error?: string}} Result
+ */
+function atomicWrite(filePath, content) {
+  const tmpPath = filePath + '.tmp';
+  const bakPath = filePath + '.bak';
+
+  try {
+    // 1. Write to temp file
+    fs.writeFileSync(tmpPath, content, 'utf8');
+
+    // 2. Backup original if it exists
+    if (fs.existsSync(filePath)) {
+      try {
+        fs.copyFileSync(filePath, bakPath);
+      } catch (_e) {
+        // Backup failure is non-fatal — proceed with rename
+      }
+    }
+
+    // 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
+    try {
+      if (fs.existsSync(bakPath)) {
+        fs.copyFileSync(bakPath, filePath);
+      }
+    } catch (_restoreErr) {
+      // Restore also failed — nothing more we can do
+    }
+
+    // Clean up temp file if it still exists
+    try {
+      if (fs.existsSync(tmpPath)) {
+        fs.unlinkSync(tmpPath);
+      }
+    } catch (_cleanupErr) {
+      // Best-effort cleanup
+    }
+
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Locked file update: read-modify-write with exclusive lockfile.
+ * Prevents concurrent writes to STATE.md and ROADMAP.md.
+ *
+ * @param {string} filePath - Absolute path to the file to update
+ * @param {function} updateFn - Receives current content, returns new content
+ * @param {object} opts - Options: { retries: 3, retryDelayMs: 100, timeoutMs: 5000 }
+ * @returns {object} { success, content?, error? }
+ */
+function lockedFileUpdate(filePath, updateFn, opts = {}) {
+  const retries = opts.retries || 3;
+  const retryDelayMs = opts.retryDelayMs || 100;
+  const timeoutMs = opts.timeoutMs || 5000;
+  const lockPath = filePath + '.lock';
+
+  let lockFd = null;
+  let lockAcquired = false;
+
+  try {
+    // Acquire lock with retries
+    for (let attempt = 0; attempt < retries; attempt++) {
+      try {
+        lockFd = fs.openSync(lockPath, 'wx');
+        lockAcquired = true;
+        break;
+      } catch (e) {
+        if (e.code === 'EEXIST') {
+          // Lock exists — check if stale (older than timeoutMs)
+          try {
+            const stats = fs.statSync(lockPath);
+            if (Date.now() - stats.mtimeMs > timeoutMs) {
+              // Stale lock — remove and retry
+              fs.unlinkSync(lockPath);
+              continue;
+            }
+          } catch (_statErr) {
+            // Lock disappeared between check — retry
+            continue;
+          }
+
+          if (attempt < retries - 1) {
+            // Wait and retry
+            const waitMs = retryDelayMs * (attempt + 1);
+            try {
+              Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
+            } catch (_atomicsErr) {
+              const end = Date.now() + waitMs;
+              while (Date.now() < end) { /* last-resort fallback */ }
+            }
+            continue;
+          }
+          return { success: false, error: `Could not acquire lock for ${path.basename(filePath)} after ${retries} attempts` };
+        }
+        throw e;
+      }
+    }
+
+    if (!lockAcquired) {
+      return { success: false, error: `Could not acquire lock for ${path.basename(filePath)}` };
+    }
+
+    // Write PID to lock file for debugging
+    fs.writeSync(lockFd, `${process.pid}`);
+    fs.closeSync(lockFd);
+    lockFd = null;
+
+    // Read current content
+    let content = '';
+    if (fs.existsSync(filePath)) {
+      content = fs.readFileSync(filePath, 'utf8');
+    }
+
+    // Apply update
+    const newContent = updateFn(content);
+
+    // Write back atomically
+    const writeResult = atomicWrite(filePath, newContent);
+    if (!writeResult.success) {
+      return { success: false, error: writeResult.error };
+    }
+
+    return { success: true, content: newContent };
+  } catch (e) {
+    return { success: false, error: e.message };
+  } finally {
+    // Close fd if still open
+    try {
+      if (lockFd !== null) fs.closeSync(lockFd);
+    } catch (_e) { /* ignore */ }
+    // Only release lock if we acquired it
+    if (lockAcquired) {
+      try {
+        fs.unlinkSync(lockPath);
+      } catch (_e) { /* ignore — may already be cleaned up */ }
+    }
+  }
+}
+
+// --- Session-scoped path resolution ---
+
+const STALE_SESSION_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+/**
+ * Resolve a session-scoped file path.
+ * Always returns a path under .sessions/{sessionId}/.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} filename - Filename to resolve (e.g. '.session.json', '.active-skill')
+ * @param {string} sessionId - Session identifier (required)
+ * @returns {string} Resolved path
+ */
+function resolveSessionPath(planningDir, filename, sessionId) {
+  return path.join(planningDir, '.sessions', sessionId, filename);
+}
+
+/**
+ * Ensure session directory exists and write meta.json.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} sessionId - Session identifier (required)
+ */
+function ensureSessionDir(planningDir, sessionId) {
+  const dirPath = path.join(planningDir, '.sessions', sessionId);
+  fs.mkdirSync(dirPath, { recursive: true });
+  const metaPath = path.join(dirPath, 'meta.json');
+  if (!fs.existsSync(metaPath)) {
+    fs.writeFileSync(metaPath, JSON.stringify({
+      session_id: sessionId,
+      created: new Date().toISOString(),
+      pid: process.pid
+    }, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Remove a session directory and all its contents.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} sessionId - Session identifier (required)
+ */
+function removeSessionDir(planningDir, sessionId) {
+  const dirPath = path.join(planningDir, '.sessions', sessionId);
+  if (fs.existsSync(dirPath)) {
+    fs.rmSync(dirPath, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Remove stale session directories older than STALE_SESSION_MS.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {Array<{sessionId: string, age: number}>} Removed sessions
+ */
+function cleanStaleSessions(planningDir) {
+  const sessionsDir = path.join(planningDir, '.sessions');
+  if (!fs.existsSync(sessionsDir)) return [];
+
+  const removed = [];
+  try {
+    const entries = fs.readdirSync(sessionsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dirPath = path.join(sessionsDir, entry.name);
+      let ageMs = 0;
+
+      // Try reading meta.json for creation time
+      const metaPath = path.join(dirPath, 'meta.json');
+      try {
+        const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+        ageMs = Date.now() - new Date(meta.created).getTime();
+      } catch (_e) {
+        // Fall back to directory mtime
+        try {
+          const stats = fs.statSync(dirPath);
+          ageMs = Date.now() - stats.mtimeMs;
+        } catch (_statErr) {
+          continue;
+        }
+      }
+
+      if (ageMs > STALE_SESSION_MS) {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+        removed.push({ sessionId: entry.name, age: ageMs });
+      }
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+
+  return removed;
+}
+
+// --- Session state management (.planning/.session.json) ---
+
+const SESSION_ALLOWED_KEYS = ['activeSkill', 'compactCounter', 'sessionStart', 'activeOperation', 'activePlan'];
+
+/**
+ * Load .session.json from .planning/ directory.
+ * Returns parsed object or {} if file is missing or unreadable.
+ *
+ * @param {string} dir - Path to .planning/ directory
+ * @param {string} [sessionId] - Session identifier for session-scoped path
+ * @returns {object}
+ */
+function sessionLoad(dir, sessionId) {
+  const sessionPath = sessionId
+    ? resolveSessionPath(dir, '.session.json', sessionId)
+    : path.join(dir, '.session.json');
+  try {
+    if (!fs.existsSync(sessionPath)) return {};
+    const content = fs.readFileSync(sessionPath, 'utf8');
+    return JSON.parse(content);
+  } catch (_e) {
+    return {};
+  }
+}
+
+/**
+ * Save data to .session.json using atomic write (write .tmp, then rename).
+ * Merges provided data with existing session data.
+ *
+ * @param {string} dir - Path to .planning/ directory
+ * @param {object} data - Key-value pairs to merge into session
+ * @param {string} [sessionId] - Session identifier for session-scoped path
+ * @returns {{ success: boolean, error?: string }}
+ */
+function sessionSave(dir, data, sessionId) {
+  const sessionPath = sessionId
+    ? resolveSessionPath(dir, '.session.json', sessionId)
+    : path.join(dir, '.session.json');
+  const tmpPath = sessionPath + '.tmp';
+  try {
+    if (sessionId) {
+      ensureSessionDir(dir, sessionId);
+    }
+    const existing = sessionLoad(dir, sessionId);
+    const merged = Object.assign(existing, data);
+    fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2), 'utf8');
+    fs.renameSync(tmpPath, sessionPath);
+    return { success: true };
+  } catch (e) {
+    try { if (fs.existsSync(tmpPath)) fs.unlinkSync(tmpPath); } catch (_) { /* cleanup */ }
+    return { success: false, error: e.message };
+  }
+}
+
+/**
+ * Write .active-skill with OS-level mutual exclusion.
+ * Also writes activeSkill to .session.json for consolidated session tracking.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} skillName - Skill name to write
+ * @param {string} [sessionId] - Session identifier for session-scoped path
+ * @returns {{success: boolean, warning?: string}} Result
+ */
+function writeActiveSkill(planningDir, skillName, sessionId) {
+  const skillFile = sessionId
+    ? resolveSessionPath(planningDir, '.active-skill', sessionId)
+    : path.join(planningDir, '.active-skill');
+  const lockFile = skillFile + '.lock';
+  const staleThresholdMs = 60 * 60 * 1000; // 60 minutes
+
+  if (sessionId) {
+    ensureSessionDir(planningDir, sessionId);
+  }
+
+  let lockFd = null;
+  try {
+    // Try exclusive create of lock file
+    lockFd = fs.openSync(lockFile, 'wx');
+    fs.writeSync(lockFd, `${process.pid}`);
+    fs.closeSync(lockFd);
+    lockFd = null;
+
+    // Check for existing .active-skill from another session
+    let warning = null;
+    if (fs.existsSync(skillFile)) {
+      try {
+        const stats = fs.statSync(skillFile);
+        const ageMs = Date.now() - stats.mtimeMs;
+        if (ageMs < staleThresholdMs) {
+          const existing = fs.readFileSync(skillFile, 'utf8').trim();
+          warning = `.active-skill already set to "${existing}" (${Math.round(ageMs / 60000)}min ago). Overwriting — possible concurrent session.`;
+        }
+      } catch (_e) {
+        // File disappeared between exists and stat — fine
+      }
+    }
+
+    // Write the skill name (legacy file — kept for backward compat with reader scripts)
+    fs.writeFileSync(skillFile, skillName, 'utf8');
+
+    // Also write to .session.json for consolidated session tracking
+    try { sessionSave(planningDir, { activeSkill: skillName }, sessionId); } catch (_e) { /* non-fatal */ }
+
+    // Release lock
+    try { fs.unlinkSync(lockFile); } catch (_e) { /* best effort */ }
+
+    return { success: true, warning };
+  } catch (e) {
+    // Close fd if still open
+    try { if (lockFd !== null) fs.closeSync(lockFd); } catch (_e) { /* ignore */ }
+
+    if (e.code === 'EEXIST') {
+      // Lock held by another process — check staleness
+      try {
+        const lockStats = fs.statSync(lockFile);
+        const lockAgeMs = Date.now() - lockStats.mtimeMs;
+        if (lockAgeMs > staleThresholdMs) {
+          // Stale lock — force remove and retry once
+          fs.unlinkSync(lockFile);
+          return writeActiveSkill(planningDir, skillName, sessionId);
+        }
+      } catch (_statErr) {
+        // Lock disappeared — retry once
+        return writeActiveSkill(planningDir, skillName, sessionId);
+      }
+      return { success: false, warning: `.active-skill.lock held by another process. Another PBR session may be active.` };
+    }
+
+    // Other error — write without lock as fallback
+    try {
+      fs.writeFileSync(skillFile, skillName, 'utf8');
+      return { success: true, warning: `Lock failed (${e.code}), wrote without lock` };
+    } catch (writeErr) {
+      return { success: false, warning: `Failed to write .active-skill: ${writeErr.message}` };
+    }
+  }
+}
+
+/**
+ * Lightweight JSON Schema validator — supports type, enum, properties,
+ * additionalProperties, minimum, maximum for the config schema.
+ */
+function validateObject(value, schema, prefix, errors, warnings) {
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const actualType = typeof value;
+    const typeMatch = types.some(t => {
+      if (t === 'integer') return actualType === 'number' && Number.isInteger(value);
+      return actualType === t;
+    });
+    if (!typeMatch) {
+      errors.push(`${prefix || 'root'}: expected ${types.join('|')}, got ${actualType}`);
+      return;
+    }
+  }
+
+  if (schema.enum && !schema.enum.includes(value)) {
+    errors.push(`${prefix || 'root'}: value "${value}" not in allowed values [${schema.enum.join(', ')}]`);
+    return;
+  }
+
+  if (schema.minimum !== undefined && value < schema.minimum) {
+    errors.push(`${prefix || 'root'}: value ${value} is below minimum ${schema.minimum}`);
+  }
+  if (schema.maximum !== undefined && value > schema.maximum) {
+    errors.push(`${prefix || 'root'}: value ${value} is above maximum ${schema.maximum}`);
+  }
+
+  if (schema.type === 'object' && schema.properties) {
+    const knownKeys = new Set(Object.keys(schema.properties));
+
+    for (const key of Object.keys(value)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (!knownKeys.has(key)) {
+        if (schema.additionalProperties === false) {
+          warnings.push(`${fullKey}: unrecognized key (possible typo?)`);
+        }
+        continue;
+      }
+      validateObject(value[key], schema.properties[key], fullKey, errors, warnings);
+    }
+  }
+}
+
+// --- Phase claiming ---
+
+/**
+ * Check whether a claim is stale (its session directory no longer exists).
+ *
+ * @param {object} claimData - Parsed .claim JSON (must have session_id)
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ stale: boolean, reason?: string }}
+ */
+function isClaimStale(claimData, planningDir) {
+  const sessionDir = path.join(planningDir, '.sessions', claimData.session_id);
+  if (!fs.existsSync(sessionDir)) {
+    return { stale: true, reason: 'session_dir_missing' };
+  }
+  return { stale: false };
+}
+
+/**
+ * Acquire a phase claim for a session. Auto-releases stale claims.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} phaseDir - Absolute path to the phase directory
+ * @param {string} sessionId - Session identifier
+ * @param {string} skill - Skill name acquiring the claim
+ * @returns {{ acquired: boolean, conflict?: object, auto_released?: object }}
+ */
+function acquireClaim(planningDir, phaseDir, sessionId, skill) {
+  const claimPath = path.join(phaseDir, '.claim');
+  let autoReleased = null;
+
+  if (fs.existsSync(claimPath)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(claimPath, 'utf8'));
+      if (existing.session_id !== sessionId) {
+        const staleCheck = isClaimStale(existing, planningDir);
+        if (staleCheck.stale) {
+          fs.unlinkSync(claimPath);
+          autoReleased = existing;
+        } else {
+          return {
+            acquired: false,
+            conflict: {
+              session_id: existing.session_id,
+              skill: existing.skill,
+              started: existing.started,
+              pid: existing.pid
+            },
+            auto_released: null
+          };
+        }
+      }
+    } catch (_e) {
+      // Malformed claim file — remove and proceed
+      try { fs.unlinkSync(claimPath); } catch (_unlinkErr) { /* best effort */ }
+    }
+  }
+
+  const claimData = {
+    session_id: sessionId,
+    skill: skill,
+    started: new Date().toISOString(),
+    pid: process.pid
+  };
+  fs.writeFileSync(claimPath, JSON.stringify(claimData, null, 2), 'utf8');
+
+  return { acquired: true, conflict: null, auto_released: autoReleased };
+}
+
+/**
+ * Release a phase claim owned by a specific session.
+ *
+ * @param {string} _planningDir - Path to .planning/ directory (unused, for API consistency)
+ * @param {string} phaseDir - Absolute path to the phase directory
+ * @param {string} sessionId - Session identifier
+ * @returns {{ released: boolean, reason?: string, owner?: string }}
+ */
+function releaseClaim(_planningDir, phaseDir, sessionId) {
+  const claimPath = path.join(phaseDir, '.claim');
+
+  if (!fs.existsSync(claimPath)) {
+    return { released: false, reason: 'no_claim' };
+  }
+
+  try {
+    const claim = JSON.parse(fs.readFileSync(claimPath, 'utf8'));
+    if (claim.session_id !== sessionId) {
+      return { released: false, reason: 'not_owner', owner: claim.session_id };
+    }
+    fs.unlinkSync(claimPath);
+    return { released: true };
+  } catch (_e) {
+    // Malformed — remove it
+    try { fs.unlinkSync(claimPath); } catch (_unlinkErr) { /* best effort */ }
+    return { released: true };
+  }
+}
+
+/**
+ * List all active phase claims.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @returns {{ claims: Array<object> }}
+ */
+function listClaims(planningDir) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { claims: [] };
+  }
+
+  const results = [];
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const claimPath = path.join(phasesDir, entry.name, '.claim');
+      if (!fs.existsSync(claimPath)) continue;
+      try {
+        const claimData = JSON.parse(fs.readFileSync(claimPath, 'utf8'));
+        results.push({
+          phase: entry.name,
+          ...claimData,
+          stale: isClaimStale(claimData, planningDir).stale
+        });
+      } catch (_e) {
+        // Skip malformed claim files
+      }
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+
+  return { claims: results };
+}
+
+/**
+ * Release all claims held by a specific session across all phase directories.
+ *
+ * @param {string} planningDir - Path to .planning/ directory
+ * @param {string} sessionId - Session identifier
+ * @returns {{ released: string[] }}
+ */
+function releaseSessionClaims(planningDir, sessionId) {
+  const phasesDir = path.join(planningDir, 'phases');
+  if (!fs.existsSync(phasesDir)) {
+    return { released: [] };
+  }
+
+  const released = [];
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const claimPath = path.join(phasesDir, entry.name, '.claim');
+      if (!fs.existsSync(claimPath)) continue;
+      try {
+        const claimData = JSON.parse(fs.readFileSync(claimPath, 'utf8'));
+        if (claimData.session_id === sessionId) {
+          fs.unlinkSync(claimPath);
+          released.push(entry.name);
+        }
+      } catch (_e) {
+        // Skip malformed claim files
+      }
+    }
+  } catch (_e) {
+    // Best-effort
+  }
+
+  return { released };
+}
+
+module.exports = {
+  KNOWN_AGENTS,
+  VALID_STATUS_TRANSITIONS,
+  validateStatusTransition,
+  output,
+  error,
+  parseYamlFrontmatter,
+  parseMustHaves,
+  findFiles,
+  tailLines,
+  countMustHaves,
+  determinePhaseStatus,
+  calculateProgress,
+  atomicWrite,
+  lockedFileUpdate,
+  writeActiveSkill,
+  sessionLoad,
+  sessionSave,
+  SESSION_ALLOWED_KEYS,
+  validateObject,
+  STALE_SESSION_MS,
+  resolveSessionPath,
+  ensureSessionDir,
+  removeSessionDir,
+  cleanStaleSessions,
+  isClaimStale,
+  acquireClaim,
+  releaseClaim,
+  listClaims,
+  releaseSessionClaims
+};