buildanything 1.7.1 → 2.0.0

package/src/lrr/aggregator.ts

@@ -0,0 +1,80 @@
+export type Verdict = 'PASS' | 'CONCERNS' | 'BLOCK';
+export interface ChapterResult {
+  chapter: string;
+  verdict: Verdict;
+  override_blocks_launch: boolean;
+  findings: Array<{ severity: string; description: string; related_decision_id?: string }>;
+  follow_up_spawned?: boolean;
+  follow_up_confirmed?: boolean;
+}
+
+export interface AggregateResult {
+  combined_verdict: 'PRODUCTION READY' | 'NEEDS WORK' | 'BLOCKED';
+  triggered_rule: number;
+  chapters: ChapterResult[];
+  star_rule_triggered?: boolean;
+  star_rule_decision_ids?: string[];
+}
+
+export function aggregate(chapters: ChapterResult[]): AggregateResult {
+  // Rule 1: ANY override_blocks_launch → BLOCKED
+  if (chapters.some(c => c.override_blocks_launch))
+    return { combined_verdict: 'BLOCKED', triggered_rule: 1, chapters };
+
+  // Rule 6: contradictions between chapters on typed fields → BLOCKED
+  // Two chapters contradict if they reference the same finding description
+  // but assign conflicting verdicts (one PASS, one BLOCK on the same topic).
+  const findingsByDesc = new Map<string, Set<Verdict>>();
+  for (const ch of chapters) {
+    for (const f of ch.findings) {
+      const key = f.description.toLowerCase().trim();
+      if (!findingsByDesc.has(key)) findingsByDesc.set(key, new Set());
+      findingsByDesc.get(key)!.add(ch.verdict);
+    }
+  }
+  for (const [desc, verdicts] of findingsByDesc) {
+    if (verdicts.has('PASS') && verdicts.has('BLOCK')) {
+      return {
+        combined_verdict: 'BLOCKED', triggered_rule: 6, chapters,
+        cross_chapter_contradiction: desc,
+      } as AggregateResult;
+    }
+  }
+
+  // Rule 5: follow_up spawned AND confirmed → treat as BLOCK
+  const effectiveChapters = chapters.map(c => ({
+    ...c,
+    verdict: (c.follow_up_spawned && c.follow_up_confirmed ? 'BLOCK' : c.verdict) as Verdict,
+  }));
+
+  // Rule 2: ALL PASS and 0 follow-ups → PRODUCTION READY
+  if (effectiveChapters.every(c => c.verdict === 'PASS') && !chapters.some(c => c.follow_up_spawned))
+    return { combined_verdict: 'PRODUCTION READY', triggered_rule: 2, chapters };
+
+  // Rule 3: ANY BLOCK → NEEDS WORK
+  if (effectiveChapters.some(c => c.verdict === 'BLOCK'))
+    return { combined_verdict: 'NEEDS WORK', triggered_rule: 3, chapters };
+
+  // Rule 4: ANY CONCERNS → NEEDS WORK
+  if (effectiveChapters.some(c => c.verdict === 'CONCERNS'))
+    return { combined_verdict: 'NEEDS WORK', triggered_rule: 4, chapters };
+
+  return { combined_verdict: 'PRODUCTION READY', triggered_rule: 2, chapters };
+}
+
+/** ⭐⭐ Star rule: on BLOCK, find related_decision_id and route back to authoring phase */
+export function applyStarRule(result: AggregateResult): AggregateResult {
+  if (result.combined_verdict === 'NEEDS WORK' || result.combined_verdict === 'BLOCKED') {
+    const blockFindings = result.chapters
+      .filter(c => c.verdict === 'BLOCK')
+      .flatMap(c => c.findings.filter(f => f.related_decision_id));
+    if (blockFindings.length > 0) {
+      return {
+        ...result,
+        star_rule_triggered: true,
+        star_rule_decision_ids: blockFindings.map(f => f.related_decision_id!),
+      };
+    }
+  }
+  return { ...result, star_rule_triggered: false };
+}

package/src/orchestrator/hooks/context-header.ts

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, existsSync } from 'node:fs';
+
+export interface ContextHeaderInput {
+  projectType: 'web' | 'ios';
+  phase: number;
+  iosFeatures?: Record<string, boolean>;
+  visualDnaPath?: string;  // path to visual-dna.md
+}
+
+export interface RenderedHeader {
+  content: string;
+  hash: string;
+}
+
+/** Cache: rendered header keyed by phase + input hash for automatic invalidation */
+let cachedHeader: RenderedHeader | null = null;
+let cachedPhase: number | null = null;
+let cachedInputHash: string | null = null;
+
+/**
+ * Compute a hash of the variable inputs that affect the rendered header.
+ * Used to detect mid-phase mutations (e.g., ios_features changing within a phase).
+ */
+function inputHash(input: ContextHeaderInput): string {
+  const key = JSON.stringify({
+    projectType: input.projectType,
+    phase: input.phase,
+    iosFeatures: input.iosFeatures ?? null,
+    visualDnaPath: input.visualDnaPath ?? null,
+  });
+  return createHash('sha256').update(key).digest('hex').slice(0, 16);
+}
+
+/**
+ * Render the CONTEXT header for a phase.
+ * Called once at phase boundary; result reused for all dispatches in that phase.
+ * Automatically invalidates if inputs change within the same phase
+ * (e.g., ios_features mutating mid-build per spec pass criteria).
+ */
+export function renderContextHeader(input: ContextHeaderInput): RenderedHeader {
+  const currentInputHash = inputHash(input);
+  // Return cached if same phase AND same inputs
+  if (cachedPhase === input.phase && cachedInputHash === currentInputHash && cachedHeader) return cachedHeader;
+
+  const lines: string[] = ['CONTEXT:'];
+  lines.push(`  project_type: ${input.projectType}`);
+  lines.push(`  phase: ${input.phase}`);
+
+  // DNA: only for web, phase >= 4
+  if (input.projectType === 'web' && input.phase >= 4 && input.visualDnaPath) {
+    if (existsSync(input.visualDnaPath)) {
+      const dna = readFileSync(input.visualDnaPath, 'utf-8');
+      const summary = dna.split('\n').slice(0, 5).join('\n').trim();
+      lines.push(`  dna: ${summary}`);
+    }
+  }
+
+  // iOS features: only for ios
+  if (input.projectType === 'ios' && input.iosFeatures) {
+    const enabled = Object.entries(input.iosFeatures)
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    if (enabled.length > 0) {
+      lines.push(`  ios_features: [${enabled.join(', ')}]`);
+    }
+  }
+
+  lines.push('');
+  lines.push('TASK:');
+
+  const content = lines.join('\n');
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+
+  cachedHeader = { content, hash };
+  cachedPhase = input.phase;
+  cachedInputHash = currentInputHash;
+  return cachedHeader;
+}
+
+/**
+ * Invalidate the cache (call on phase boundary or state mutation).
+ */
+export function invalidateCache(): void {
+  cachedHeader = null;
+  cachedPhase = null;
+  cachedInputHash = null;
+}
+
+/**
+ * Check if the cache is valid for a given phase.
+ */
+export function isCacheValid(phase: number): boolean {
+  return cachedPhase === phase && cachedHeader !== null;
+}

package/src/orchestrator/hooks/token-accounting-emitter.ts

@@ -0,0 +1,77 @@
+/**
+ * Phase-boundary + Task-completion token accounting emitter (task 3.4.2).
+ *
+ * Subscribes to SDK assistant+result message `usage` fields.
+ * At every phase boundary and Task tool call completion, calls
+ * recordUsage() to append a cost line to docs/plans/build-log.md.
+ *
+ * Spec: MIGRATION-PLAN-FINAL.md §4 Stage 3 G3
+ * Depends on: src/orchestrator/hooks/token-accounting.ts (task 3.4.1)
+ */
+
+import { recordUsage, type TokenUsage, type AccountingEntry } from './token-accounting';
+
+const DEFAULT_BUILD_LOG = 'docs/plans/build-log.md';
+
+export interface SdkUsageMessage {
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+}
+
+export interface PhaseContext {
+  phase: number;
+  step: string;
+  buildLogPath?: string;
+}
+
+export interface TaskContext extends PhaseContext {
+  task: string;
+  subagent_type: string;
+}
+
+/**
+ * Extract TokenUsage from an SDK usage message.
+ * SDK field names differ slightly from our internal format.
+ */
+export function extractUsage(msg: SdkUsageMessage): TokenUsage {
+  return {
+    input_tokens: msg.input_tokens ?? 0,
+    output_tokens: msg.output_tokens ?? 0,
+    cache_read: msg.cache_read_input_tokens ?? 0,
+    cache_create: msg.cache_creation_input_tokens ?? 0,
+  };
+}
+
+/**
+ * Emit a cost line at a phase boundary.
+ * Called by the orchestrator after each phase completes.
+ */
+export function emitPhaseBoundary(
+  ctx: PhaseContext,
+  usage: SdkUsageMessage,
+): AccountingEntry {
+  return recordUsage(ctx.buildLogPath ?? DEFAULT_BUILD_LOG, {
+    phase: ctx.phase,
+    step: ctx.step,
+    usage: extractUsage(usage),
+  });
+}
+
+/**
+ * Emit a cost line at task completion.
+ * Called after each Task tool call returns from a subagent dispatch.
+ */
+export function emitTaskCompletion(
+  ctx: TaskContext,
+  usage: SdkUsageMessage,
+): AccountingEntry {
+  return recordUsage(ctx.buildLogPath ?? DEFAULT_BUILD_LOG, {
+    phase: ctx.phase,
+    step: ctx.step,
+    task: ctx.task,
+    subagent_type: ctx.subagent_type,
+    usage: extractUsage(usage),
+  });
+}

package/src/orchestrator/hooks/token-accounting.ts

@@ -0,0 +1,101 @@
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read?: number;
+  cache_create?: number;
+}
+
+export interface AccountingEntry {
+  timestamp: string;
+  phase: number;
+  step: string;
+  task?: string;
+  subagent_type?: string;
+  usage: TokenUsage;
+  cost_usd: number;
+  cumulative_usd: number;
+}
+
+/** Running cumulative cost across the build */
+let cumulativeCost = 0;
+
+/** Pricing per million tokens (sonnet defaults) */
+const PRICING = {
+  input: 3.0,
+  output: 15.0,
+  cache_read: 0.30,
+  cache_create: 3.75,
+};
+
+/**
+ * Calculate cost from token usage.
+ */
+export function calculateCost(usage: TokenUsage): number {
+  const inputCost = (usage.input_tokens / 1_000_000) * PRICING.input;
+  const outputCost = (usage.output_tokens / 1_000_000) * PRICING.output;
+  const cacheReadCost = ((usage.cache_read ?? 0) / 1_000_000) * PRICING.cache_read;
+  const cacheCreateCost = ((usage.cache_create ?? 0) / 1_000_000) * PRICING.cache_create;
+  return Math.round((inputCost + outputCost + cacheReadCost + cacheCreateCost) * 10000) / 10000;
+}
+
+/**
+ * Record a token usage entry and append to build-log.md.
+ */
+export function recordUsage(
+  buildLogPath: string,
+  entry: Omit<AccountingEntry, 'cost_usd' | 'cumulative_usd' | 'timestamp'>,
+): AccountingEntry {
+  const cost = calculateCost(entry.usage);
+  cumulativeCost += cost;
+
+  const record: AccountingEntry = {
+    timestamp: new Date().toISOString(),
+    ...entry,
+    cost_usd: cost,
+    cumulative_usd: Math.round(cumulativeCost * 10000) / 10000,
+  };
+
+  const line = formatLogLine(record);
+  const dir = dirname(buildLogPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(buildLogPath, line + '\n', { flag: 'a' });
+
+  return record;
+}
+
+/**
+ * Format an accounting entry as a build-log line.
+ */
+export function formatLogLine(entry: AccountingEntry): string {
+  const meta = [`phase=${entry.phase}`, `step=${entry.step}`];
+  if (entry.task) meta.push(`task=${entry.task}`);
+  if (entry.subagent_type) meta.push(`subagent_type=${entry.subagent_type}`);
+
+  const tokens = [
+    `input_tokens=${entry.usage.input_tokens}`,
+    `output_tokens=${entry.usage.output_tokens}`,
+  ];
+  if (entry.usage.cache_read) tokens.push(`cache_read=${entry.usage.cache_read}`);
+  if (entry.usage.cache_create) tokens.push(`cache_create=${entry.usage.cache_create}`);
+  tokens.push(`cost_usd=${entry.cost_usd}`);
+  tokens.push(`cumulative_usd=${entry.cumulative_usd}`);
+
+  return `[${entry.timestamp}] ${meta.join(' ')}\n${tokens.join(' ')}`;
+}
+
+/**
+ * Get current cumulative cost.
+ */
+export function getCumulativeCost(): number {
+  return cumulativeCost;
+}
+
+/**
+ * Reset cumulative cost (for testing).
+ */
+export function reset(): void {
+  cumulativeCost = 0;
+}

package/src/orchestrator/mcp/cycle-counter.ts

@@ -0,0 +1,129 @@
+/**
+ * cycle_counter_check MCP handler (Stage 4, A6 semantic).
+ *
+ * Authoritative semantic: escalation fires when NEW counter value > max_cycles.
+ * max_cycles = 2 → first two attempts allow, third escalates.
+ *
+ * Dual counter: per-decision AND per-target-phase. Escalation when EITHER exceeds cap.
+ */
+
+import type { InFlightBackwardEdge, BackwardRoutingCounters } from '../schemas/backward-edge';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CycleCheckInput {
+  decision_id: string;
+  target_phase: string;
+}
+
+export interface CycleCheckResult {
+  action: 'allow' | 'escalate_to_user';
+  decision_count: number;
+  phase_count: number;
+}
+
+export interface CounterState extends BackwardRoutingCounters {}
+
+const DEFAULT_MAX_CYCLES = 2;
+
+// ---------------------------------------------------------------------------
+// Core handler (tasks 4.2.1, 4.2.2, 4.2.3)
+// ---------------------------------------------------------------------------
+
+/**
+ * Check and increment the cycle counter for a backward-routing edge.
+ * Returns allow for the first max_cycles attempts, escalate_to_user after.
+ *
+ * Mutates the state object in place — caller must persist via a single
+ * atomic state_save combining counter increment + in_flight_backward_edge
+ * write (A3 crash-seam protocol).
+ */
+export function cycleCounterCheck(
+  state: CounterState,
+  input: CycleCheckInput,
+  maxCycles: number = DEFAULT_MAX_CYCLES,
+): CycleCheckResult {
+  if (!input.decision_id) throw new Error('decision_id is required');
+  if (!input.target_phase) throw new Error('target_phase is required');
+
+  // Initialize counters if missing
+  state.backward_routing_count ??= {};
+  state.backward_routing_count_by_target_phase ??= {};
+
+  // Atomically increment both counters
+  const decisionCount = (state.backward_routing_count[input.decision_id] ?? 0) + 1;
+  const phaseCount = (state.backward_routing_count_by_target_phase[input.target_phase] ?? 0) + 1;
+
+  state.backward_routing_count[input.decision_id] = decisionCount;
+  state.backward_routing_count_by_target_phase[input.target_phase] = phaseCount;
+
+  // Write in_flight_backward_edge (A3 crash-seam) — single atomic state_save
+  state.in_flight_backward_edge = {
+    decision_id: input.decision_id,
+    target_phase: input.target_phase,
+    counter_value: decisionCount,
+    started_at: new Date().toISOString(),
+  };
+
+  // Escalation: EITHER counter exceeds cap → escalate
+  const action: CycleCheckResult['action'] =
+    (decisionCount > maxCycles || phaseCount > maxCycles)
+      ? 'escalate_to_user'
+      : 'allow';
+
+  return { action, decision_count: decisionCount, phase_count: phaseCount };
+}
+
+// ---------------------------------------------------------------------------
+// Edge lifecycle helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Clear the in-flight backward edge (called by target phase on re-entry).
+ * Caller must persist via state_save.
+ */
+export function clearInFlightEdge(state: CounterState): void {
+  delete state.in_flight_backward_edge;
+}
+
+/**
+ * Handle stale edge on --resume (A3 crash recovery).
+ * If edge is older than threshold, decrement both counters and clear the edge.
+ * Returns true if a stale edge was cleaned up.
+ */
+export function handleStaleEdge(state: CounterState, thresholdMs: number = 60_000): boolean {
+  const edge = state.in_flight_backward_edge;
+  if (!edge) return false;
+
+  const age = Date.now() - new Date(edge.started_at).getTime();
+  if (age <= thresholdMs) return false; // edge is fresh, standard resume
+
+  // Edge never completed — decrement per-decision counter
+  const decCurrent = state.backward_routing_count[edge.decision_id] ?? 0;
+  if (decCurrent > 0) {
+    state.backward_routing_count[edge.decision_id] = decCurrent - 1;
+  }
+
+  // Decrement per-target-phase counter
+  const phaseCurrent = state.backward_routing_count_by_target_phase[edge.target_phase] ?? 0;
+  if (phaseCurrent > 0) {
+    state.backward_routing_count_by_target_phase[edge.target_phase] = phaseCurrent - 1;
+  }
+
+  delete state.in_flight_backward_edge;
+  return true; // stale edge handled
+}
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+/** Create a fresh empty CounterState. For testing only. */
+export function createEmptyState(): CounterState {
+  return {
+    backward_routing_count: {},
+    backward_routing_count_by_target_phase: {},
+  };
+}