buildanything 1.8.0 → 2.1.1

package/src/orchestrator/mcp/scribe.ts

@@ -0,0 +1,294 @@
+/**
+ * scribe_decision MCP handler.
+ *
+ * The ONLY writer to docs/plans/decisions.jsonl.
+ * Subagents return deviation_row objects → orchestrator routes them here.
+ * Append-only — NEVER rewrites or truncates the file.
+ *
+ * Spec: protocols/decision-log.md
+ * Schema: docs/migration/decisions.schema.json
+ * Migration ref: MIGRATION-PLAN-FINAL.md §4 Stage 1 (tasks 1.2.1–1.2.3)
+ */
+
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RejectedAlternative {
+  approach: string;
+  reason: string;
+  revisit_criterion: string;
+}
+
+export interface DecisionRow {
+  decision_id: string;
+  phase: string;
+  timestamp: string;
+  decision: string;
+  chosen_approach: string;
+  rejected_alternatives: RejectedAlternative[];
+  decided_by: string;
+  ref: string;
+  status: 'open' | 'triggered' | 'resolved';
+}
+
+export interface ScribeInput {
+  phase: string;
+  summary: string;
+  decided_by: string;
+  impact_level: 'low' | 'medium' | 'high' | 'critical';
+  chosen_approach: string;
+  rejected_alternatives?: RejectedAlternative[];
+  ref: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants — sourced from protocols/decision-log.md §Hard Field Constraints
+// ---------------------------------------------------------------------------
+
+const VALID_IMPACTS = ['low', 'medium', 'high', 'critical'] as const;
+const VALID_STATUSES = ['open', 'triggered', 'resolved'] as const;
+const MAX_ALTERNATIVES = 3;
+const MAX_ROWS_PER_PHASE = 5;
+const MAX_DECISION_LEN = 240;
+const MAX_CHOSEN_APPROACH_LEN = 480;
+const MAX_APPROACH_LEN = 240;
+const MAX_REASON_LEN = 400;
+const MAX_REVISIT_LEN = 240;
+
+/** Ref field pattern from decisions.schema.json */
+const REF_PATTERN = /^[a-zA-Z0-9_\-./]+\.(md|json|jsonl|yaml|yml)(#[a-zA-Z0-9_\-/.]+)?$/;
+
+/** Phase string pattern from decisions.schema.json. Leading minus allowed for Phase -1 (iOS bootstrap). */
+const PHASE_PATTERN = /^-?[0-9]+(\.[0-9]+)?$/;
+
+/** Encode a phase token for embedding in a decision_id. Negative phases get an "N" prefix
+ * instead of "-" to avoid colliding with the "-" delimiter in the ID format. So phase "-1"
+ * becomes "N1" in the ID slot, yielding "D-N1-01". Round-trippable via decodePhaseFromId. */
+function encodePhaseForId(phase: string): string {
+  return phase.startsWith('-') ? `N${phase.slice(1)}` : phase;
+}
+
+// ---------------------------------------------------------------------------
+// Per-phase sequence counters (task 1.2.3 — ID allocation)
+// ---------------------------------------------------------------------------
+
+const counters: Record<string, number> = {};
+
+/**
+ * Load existing counters from a decisions.jsonl file.
+ * Scans all rows to find the max seq per phase so new IDs don't collide.
+ */
+export function loadCounters(filePath: string): void {
+  if (!existsSync(filePath)) return;
+  const content = readFileSync(filePath, 'utf-8').trim();
+  if (!content) return;
+  const lines = content.split('\n').filter(Boolean);
+  for (const line of lines) {
+    try {
+      const row = JSON.parse(line) as DecisionRow;
+      const match = row.decision_id.match(/^D-(.+)-(\d{2,})$/);
+      if (match) {
+        const phase = match[1];
+        const seq = parseInt(match[2], 10);
+        counters[phase] = Math.max(counters[phase] ?? 0, seq);
+      }
+    } catch {
+      /* skip malformed lines */
+    }
+  }
+}
+
+/** Allocate the next decision ID for a phase. Format: D-{encodedPhase}-{seq} */
+function allocateId(phase: string): string {
+  const encoded = encodePhaseForId(phase);
+  counters[encoded] = (counters[encoded] ?? 0) + 1;
+  return `D-${encoded}-${String(counters[encoded]).padStart(2, '0')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Exclusive-write lock (task 1.2.3)
+// ---------------------------------------------------------------------------
+
+let writeLocked = false;
+
+// ---------------------------------------------------------------------------
+// Schema validation (task 1.2.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Count rows for a given phase in the target file.
+ * Used to enforce the max-5-rows-per-phase constraint.
+ */
+function countPhaseRows(filePath: string, phase: string): number {
+  if (!existsSync(filePath)) return 0;
+  const content = readFileSync(filePath, 'utf-8').trim();
+  if (!content) return 0;
+  let count = 0;
+  for (const line of content.split('\n')) {
+    try {
+      const row = JSON.parse(line) as DecisionRow;
+      if (row.phase === phase) count++;
+    } catch {
+      /* skip */
+    }
+  }
+  return count;
+}
+
+/**
+ * Validate a single rejected alternative against schema constraints.
+ */
+function validateAlternative(alt: RejectedAlternative, index: number): void {
+  if (!alt.approach || alt.approach.length === 0) {
+    throw new Error(`rejected_alternatives[${index}].approach is required`);
+  }
+  if (alt.approach.length > MAX_APPROACH_LEN) {
+    throw new Error(`rejected_alternatives[${index}].approach exceeds ${MAX_APPROACH_LEN} chars`);
+  }
+  if (!alt.reason || alt.reason.length === 0) {
+    throw new Error(`rejected_alternatives[${index}].reason is required`);
+  }
+  if (alt.reason.length > MAX_REASON_LEN) {
+    throw new Error(`rejected_alternatives[${index}].reason exceeds ${MAX_REASON_LEN} chars (max 2 sentences)`);
+  }
+  if (!alt.revisit_criterion || alt.revisit_criterion.length === 0) {
+    throw new Error(`rejected_alternatives[${index}].revisit_criterion is required`);
+  }
+  if (alt.revisit_criterion.length > MAX_REVISIT_LEN) {
+    throw new Error(`rejected_alternatives[${index}].revisit_criterion exceeds ${MAX_REVISIT_LEN} chars (max 1 sentence)`);
+  }
+}
+
+/**
+ * Validate scribe input against the decision log schema.
+ * Throws on any validation failure.
+ */
+export function validate(input: ScribeInput): void {
+  if (!input.phase || !PHASE_PATTERN.test(input.phase)) {
+    throw new Error(`Invalid phase: "${input.phase ?? ''}". Must match pattern ${PHASE_PATTERN.source}`);
+  }
+  if (!input.summary || input.summary.length === 0) {
+    throw new Error('summary is required');
+  }
+  if (input.summary.length > MAX_DECISION_LEN) {
+    throw new Error(`summary exceeds ${MAX_DECISION_LEN} chars`);
+  }
+  if (!input.chosen_approach || input.chosen_approach.length === 0) {
+    throw new Error('chosen_approach is required');
+  }
+  if (input.chosen_approach.length > MAX_CHOSEN_APPROACH_LEN) {
+    throw new Error(`chosen_approach exceeds ${MAX_CHOSEN_APPROACH_LEN} chars`);
+  }
+  if (!input.decided_by || input.decided_by.length === 0) {
+    throw new Error('decided_by is required');
+  }
+  if (!VALID_IMPACTS.includes(input.impact_level as typeof VALID_IMPACTS[number])) {
+    throw new Error(`Invalid impact_level: ${input.impact_level}. Must be one of: ${VALID_IMPACTS.join(', ')}`);
+  }
+  if (!input.ref || input.ref.length === 0 || !REF_PATTERN.test(input.ref)) {
+    throw new Error(`Invalid ref: "${input.ref ?? ''}". Must match pattern ${REF_PATTERN.source}`);
+  }
+
+  const alts = input.rejected_alternatives ?? [];
+  if (alts.length > MAX_ALTERNATIVES) {
+    throw new Error(`Max ${MAX_ALTERNATIVES} rejected alternatives per decision row`);
+  }
+  for (let i = 0; i < alts.length; i++) {
+    validateAlternative(alts[i], i);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP handler (task 1.2.1)
+// ---------------------------------------------------------------------------
+
+/**
+ * scribe_decision — in-process MCP tool handler.
+ *
+ * Validates input, allocates a sequential ID, acquires the exclusive-write
+ * lock, and appends a single JSON line to the decisions file.
+ * Returns the written DecisionRow.
+ *
+ * @param input  - ScribeInput from the calling subagent
+ * @param filePath - Absolute path to decisions.jsonl (default: docs/plans/decisions.jsonl)
+ */
+export function scribeDecision(input: ScribeInput, filePath: string): DecisionRow {
+  if (writeLocked) {
+    throw new Error('Exclusive write lock held — concurrent scribe call rejected');
+  }
+
+  writeLocked = true;
+  try {
+    validate(input);
+
+    // Auto-rehydrate counters from disk (idempotent — takes max per phase)
+    loadCounters(filePath);
+
+    // Enforce max 5 rows per phase
+    const existing = countPhaseRows(filePath, input.phase);
+    if (existing >= MAX_ROWS_PER_PHASE) {
+      throw new Error(
+        `Phase "${input.phase}" already has ${existing} decision rows (max ${MAX_ROWS_PER_PHASE}). ` +
+        'Split into sub-phases or consolidate before adding more.',
+      );
+    }
+
+    const row: DecisionRow = {
+      decision_id: allocateId(input.phase),
+      phase: input.phase,
+      timestamp: new Date().toISOString(),
+      decision: input.summary,
+      chosen_approach: input.chosen_approach,
+      rejected_alternatives: input.rejected_alternatives ?? [],
+      decided_by: input.decided_by,
+      ref: input.ref,
+      status: 'open',
+    };
+
+    // Ensure parent directory exists
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // ATOMIC: read existing + append new row + write-to-tmp + rename
+    const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const newContent = existingContent + JSON.stringify(row) + '\n';
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, newContent, 'utf-8');
+    renameSync(tmp, filePath); // atomic on POSIX same-filesystem
+
+    return row;
+  } finally {
+    writeLocked = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset internal state (counters + lock). For testing only.
+ */
+export function reset(): void {
+  for (const key of Object.keys(counters)) delete counters[key];
+  writeLocked = false;
+}
+
+/** Expose constants for test assertions */
+export const LIMITS = {
+  MAX_ALTERNATIVES,
+  MAX_ROWS_PER_PHASE,
+  MAX_DECISION_LEN,
+  MAX_CHOSEN_APPROACH_LEN,
+  MAX_APPROACH_LEN,
+  MAX_REASON_LEN,
+  MAX_REVISIT_LEN,
+  VALID_IMPACTS,
+  VALID_STATUSES,
+} as const;

package/src/orchestrator/mcp/state-save.ts

@@ -0,0 +1,149 @@
+/**
+ * state_save MCP handler.
+ *
+ * Atomic state persistence for .build-state.json (and any state file).
+ * All mutations to .build-state.json MUST route through this MCP —
+ * raw Write|Edit is denied by the writer-owner hook (Stage 3.3.1).
+ *
+ * Protocol: write-to-.tmp + fsync + rename (POSIX atomic on same filesystem).
+ * Every write produces a SHA-256 integrity checksum for verification.
+ *
+ * Spec: MIGRATION-PLAN-FINAL.md §4 Stage 3 (tasks 3.2.1–3.2.3)
+ */
+
+import {
+  writeFileSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  fsyncSync,
+  closeSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface StateSaveResult {
+  success: boolean;
+  path: string;
+  sha256: string;
+  bytesWritten: number;
+}
+
+export interface StateReadResult {
+  state: Record<string, unknown>;
+  sha256: string;
+}
+
+// ---------------------------------------------------------------------------
+// Exclusive-write lock — prevents concurrent state_save calls
+// ---------------------------------------------------------------------------
+
+let writeLocked = false;
+
+// ---------------------------------------------------------------------------
+// Core: atomic state save (tasks 3.2.1 + 3.2.2 + 3.2.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Atomically save state to a JSON file.
+ *
+ * Protocol (write-to-.tmp + fsync + os.replace):
+ *   1. Serialize state to deterministic JSON
+ *   2. Compute SHA-256 checksum over serialized content
+ *   3. Write to {path}.tmp
+ *   4. fsync the .tmp fd (flush to disk — survives power loss)
+ *   5. rename .tmp → target (POSIX atomic on same filesystem)
+ *   6. On failure: delete .tmp, release lock, re-throw
+ *
+ * Callers: orchestrator phase transitions, cycle_counter_check MCP,
+ * SubagentStart hook, write-lease persistence, token accounting.
+ */
+export function stateSave(path: string, state: Record<string, unknown>): StateSaveResult {
+  if (writeLocked) {
+    throw new Error('Exclusive write lock held — concurrent state_save call rejected');
+  }
+
+  writeLocked = true;
+  const tmp = `${path}.tmp`;
+
+  try {
+    // Ensure parent directory exists
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    // 1. Serialize — deterministic pretty-print + trailing newline
+    const content = JSON.stringify(state, null, 2) + '\n';
+
+    // 2. SHA-256 integrity checksum (task 3.2.3)
+    const sha256 = createHash('sha256').update(content).digest('hex');
+
+    // 3. Write to .tmp
+    writeFileSync(tmp, content, 'utf-8');
+
+    // 4. fsync — flush kernel buffers to disk (task 3.2.2)
+    // Open with 'r+' (read-write) to guarantee data buffer flush on all platforms.
+    // Opening with 'r' (read-only) may only flush metadata on some systems.
+    const fd = openSync(tmp, 'r+');
+    try {
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+
+    // 5. Atomic rename — os.replace() equivalent (task 3.2.2)
+    renameSync(tmp, path);
+
+    return { success: true, path, sha256, bytesWritten: Buffer.byteLength(content) };
+  } catch (err) {
+    // 6. Clean up .tmp on failure — never leave partial state
+    try { if (existsSync(tmp)) unlinkSync(tmp); } catch { /* best effort */ }
+    throw err;
+  } finally {
+    writeLocked = false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State read + integrity verification
+// ---------------------------------------------------------------------------
+
+/**
+ * Read state from a JSON file and compute its SHA-256 checksum.
+ * Used by SubagentStart hook, cycle_counter_check, write-lease init.
+ */
+export function stateRead(path: string): StateReadResult {
+  const content = readFileSync(path, 'utf-8');
+  const sha256 = createHash('sha256').update(content).digest('hex');
+  return { state: JSON.parse(content) as Record<string, unknown>, sha256 };
+}
+
+/**
+ * Verify integrity of a state file against an expected SHA-256 checksum.
+ * Returns true if the file content matches the expected hash.
+ *
+ * Use case: crash recovery — confirm .build-state.json wasn't corrupted
+ * by a partial write (the atomic protocol prevents this, but defense-in-depth).
+ */
+export function verifyIntegrity(path: string, expectedSha256: string): boolean {
+  const content = readFileSync(path, 'utf-8');
+  const actual = createHash('sha256').update(content).digest('hex');
+  return actual === expectedSha256;
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Reset internal state (write lock). For testing only.
+ */
+export function reset(): void {
+  writeLocked = false;
+}

package/src/orchestrator/mcp/write-lease.ts

@@ -0,0 +1,184 @@
+/**
+ * Write-lease MCP handler (A5).
+ * Prevents intra-phase file collisions by requiring implementer dispatches
+ * to acquire exclusive leases on file paths before Write|Edit operations.
+ *
+ * Leases are persisted atomically to .build-state.json.active_write_leases[]
+ * so the PreToolUse hook (which re-reads from disk) sees them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+
+export interface Lease {
+  holder: string;       // task_id of the lease holder
+  paths: string[];      // file paths under lease
+  acquired_at: string;  // ISO timestamp
+}
+
+export interface LeaseConflict {
+  holder: string;       // task_id of the existing lease holder
+  paths: string[];      // overlapping file paths
+}
+
+export interface AcquireResult {
+  granted: boolean;
+  lease?: Lease;
+  conflict?: LeaseConflict;
+}
+
+/** In-memory lease store — kept in sync with disk via persistLeases(). */
+const leases: Lease[] = [];
+
+/** Path to .build-state.json — set via init() or defaults to docs/plans/.build-state.json */
+let statePath = 'docs/plans/.build-state.json';
+
+/**
+ * Initialize the lease manager with the state file path.
+ * Loads existing leases from disk into memory.
+ */
+export function init(buildStatePath: string): void {
+  statePath = buildStatePath;
+  leases.length = 0;
+  if (!existsSync(statePath)) return;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf-8'));
+    const diskLeases = state?.active_write_leases;
+    if (Array.isArray(diskLeases)) {
+      for (const l of diskLeases) {
+        if (l?.holder && Array.isArray(l?.paths)) {
+          leases.push({ holder: l.holder, paths: l.paths, acquired_at: l.acquired_at ?? '' });
+        }
+      }
+    }
+  } catch { /* fresh state or parse error — start with empty leases */ }
+}
+
+/**
+ * Persist current leases to .build-state.json atomically.
+ * Uses write-to-.tmp + rename (same protocol as state_save MCP).
+ *
+ * CRITICAL: If persist fails, the in-memory lease exists but the PreToolUse
+ * hook (a separate process) reads from disk and won't see it — creating a
+ * silent fail-closed where legitimate writes are denied. On persist failure,
+ * we roll back the in-memory state to match disk and re-throw so the caller
+ * knows the acquire didn't stick.
+ */
+function persistLeases(): void {
+  if (!existsSync(statePath)) return;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf-8'));
+    state.active_write_leases = leases.map(l => ({ ...l }));
+    const tmp = `${statePath}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    renameSync(tmp, statePath);
+  } catch (err) {
+    // Persist failed — roll back in-memory state to match what's on disk,
+    // then re-throw. This prevents the MCP thinking a lease exists while
+    // the hook (reading disk) sees nothing and denies writes.
+    try {
+      const diskState = JSON.parse(readFileSync(statePath, 'utf-8'));
+      const diskLeases = diskState?.active_write_leases;
+      leases.length = 0;
+      if (Array.isArray(diskLeases)) {
+        for (const l of diskLeases) {
+          if (l?.holder && Array.isArray(l?.paths)) {
+            leases.push({ holder: l.holder, paths: l.paths, acquired_at: l.acquired_at ?? '' });
+          }
+        }
+      }
+    } catch { /* disk unreadable — empty leases is the safest state */ leases.length = 0; }
+    throw new Error(`write-lease: persist failed, in-memory rolled back: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+/**
+ * Process-level async mutex for acquireWriteLease.
+ *
+ * Serializes all callers through a promise chain so that even if two async
+ * dispatch paths call acquireWriteLease concurrently, the overlap check and
+ * push are never interleaved. This prevents a TOCTOU race where both callers
+ * read the leases array before either persists, granting conflicting leases.
+ */
+let acquireLock: Promise<void> = Promise.resolve();
+
+/**
+ * Acquire a write lease for the given file paths.
+ * Persists to disk atomically so the PreToolUse hook sees the lease.
+ *
+ * Serialized via an async mutex (promise chain) to prevent TOCTOU races
+ * when called from concurrent async dispatch paths.
+ */
+export async function acquireWriteLease(taskId: string, filePaths: string[]): Promise<AcquireResult> {
+  const result = acquireLock.then(() => {
+    if (!taskId) throw new Error('task_id is required');
+    if (!filePaths.length) throw new Error('file_paths must be non-empty');
+
+    for (const existing of leases) {
+      const overlap = filePaths.filter(p => existing.paths.includes(p));
+      if (overlap.length > 0) {
+        return { granted: false, conflict: { holder: existing.holder, paths: overlap } };
+      }
+    }
+
+    const lease: Lease = { holder: taskId, paths: [...filePaths], acquired_at: new Date().toISOString() };
+    leases.push(lease);
+    persistLeases();
+    return { granted: true, lease };
+  });
+  acquireLock = result.then(() => {}, () => {}); // advance chain regardless of success/failure
+  return result;
+}
+
+/**
+ * Release ALL leases held by a task (handles multiple leases per task).
+ * Persists to disk. Called by SubagentStop hook on dispatch return.
+ */
+export function releaseLease(taskId: string): boolean {
+  let released = false;
+  for (let i = leases.length - 1; i >= 0; i--) {
+    if (leases[i].holder === taskId) {
+      leases.splice(i, 1);
+      released = true;
+    }
+  }
+  if (released) persistLeases();
+  return released;
+}
+
+/**
+ * Release specific paths for a task. Persists to disk.
+ */
+export function releasePathsForTask(taskId: string, paths: string[]): void {
+  const lease = leases.find(l => l.holder === taskId);
+  if (!lease) return;
+  lease.paths = lease.paths.filter(p => !paths.includes(p));
+  if (lease.paths.length === 0) {
+    releaseLease(taskId);
+  } else {
+    persistLeases();
+  }
+}
+
+/** Get all active leases. */
+export function getActiveLeases(): readonly Lease[] {
+  return leases;
+}
+
+/**
+ * Check if a specific file path is leased and by whom.
+ * Used by the writer-owner PreToolUse hook extension.
+ */
+export function checkPathLease(filePath: string, callerTaskId: string): { allowed: boolean; conflict?: LeaseConflict } {
+  for (const lease of leases) {
+    if (lease.paths.includes(filePath)) {
+      if (lease.holder === callerTaskId) return { allowed: true };
+      return { allowed: false, conflict: { holder: lease.holder, paths: [filePath] } };
+    }
+  }
+  return { allowed: false, conflict: undefined };
+}
+
+/** Reset all leases (for testing). */
+export function reset(): void {
+  leases.length = 0;
+}

package/src/orchestrator/phase4-shared-context.ts

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+
+export interface SprintContextInput {
+  buildState: Record<string, unknown>;
+  refs: Record<string, unknown>;
+  architecture: string;
+  qualityTargets: Record<string, unknown>;
+  iosFeatures?: string[];
+}
+
+export interface SprintContextBlock {
+  content: string;
+  hash: string;
+}
+
+/**
+ * Render the sprint-scoped shared-context block for Phase 4 dispatches.
+ * Injected once per sprint via SubagentStart hook; hash-cached for reuse.
+ */
+export function renderSprintContext(input: SprintContextInput): SprintContextBlock {
+  const sections = [
+    `## Architecture Snapshot\n${input.architecture}`,
+    `## Quality Targets\n${JSON.stringify(input.qualityTargets, null, 2)}`,
+    `## Refs Index\n${JSON.stringify(input.refs, null, 2)}`,
+  ];
+  if (input.iosFeatures?.length) {
+    sections.push(`## iOS Features\n${input.iosFeatures.join(', ')}`);
+  }
+  const content = sections.join('\n\n');
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+  return { content, hash };
+}
+
+/**
+ * Hash only the inputs that affect rendered output (excludes buildState).
+ * Cheaper than a full renderSprintContext — no section joins or content hashing.
+ * Callers should store this hash and pass it to shouldInvalidate.
+ */
+export function inputHash(input: SprintContextInput): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      architecture: input.architecture,
+      qualityTargets: input.qualityTargets,
+      refs: input.refs,
+      iosFeatures: input.iosFeatures ?? null,
+    }))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Check if the sprint context needs re-rendering (hash invalidation).
+ * Compares input hashes directly — avoids a full render just to get a hash.
+ */
+export function shouldInvalidate(currentInputHash: string, newInput: SprintContextInput): boolean {
+  return inputHash(newInput) !== currentInputHash;
+}