@thebackstoryis/engineering-with-ai 0.2.9

package/src/execution-state.mjs

@@ -0,0 +1,243 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { validatePhaseArtefacts } from './delivery-artifacts.mjs';
+import { deliveryPaths, isWithin, sha256 } from './delivery-documents.mjs';
+import { assertCompletedEvidenceFresh, validatePhaseGateAtPaths } from './delivery-gates.mjs';
+import { dependencyRequirementBlockers, validateIntentDependencyGraph } from './intent-dependencies.mjs';
+import { validateIntentStateCopies } from './intents.mjs';
+import { validateTaskGraph } from './task-graph.mjs';
+
+const terminalPhaseStatuses = new Set(['completed', 'approved', 'skipped', 'not-supported', 'waived']);
+const acceptedIntentStatuses = new Set(['ready', 'approved']);
+
+function blocker(code, message, evidence = '') {
+  return { code, message, evidence };
+}
+
+function action(permitted, blockers = [], extra = {}) {
+  return { permitted: Boolean(permitted && blockers.length === 0), blockers, ...extra };
+}
+
+function phaseSequence(state) {
+  const result = [];
+  for (const phase of state.phases ?? []) {
+    result.push(phase);
+    if (phase.id === 'reconcile') result.push((state.adjuncts ?? []).find((item) => item.id === 'ui-design'));
+    if (phase.id === 'build') result.splice(result.length - 1, 0, (state.adjuncts ?? []).find((item) => item.id === 'fit-check'));
+    if (phase.id === 'retro') result.splice(result.length - 1, 0, (state.humanGates ?? []).find((item) => item.id === 'manual-qa'));
+  }
+  return result.filter(Boolean);
+}
+
+function nextRequiredPhase(state) {
+  const running = phaseSequence(state).find((phase) => phase.status === 'running');
+  if (running) return running.id;
+  return phaseSequence(state).find((phase) => !terminalPhaseStatuses.has(phase.status))?.id ?? 'complete';
+}
+
+function progress(state) {
+  const applicable = (state.phases ?? []).filter((phase) => !['skipped', 'not-supported'].includes(phase.status));
+  if (!applicable.length) return 0;
+  return Math.round((applicable.filter((phase) => phase.status === 'completed').length / applicable.length) * 100);
+}
+
+function projection(intent, state, valid) {
+  if (!valid) return { lane: 'blocked', state: 'invalid-evidence', intentState: intent.status, progress: 0, phase: state?.currentPhase ?? intent.currentPhase ?? 'backlog' };
+  if (!state) {
+    const ready = acceptedIntentStatuses.has(String(intent.status).toLowerCase());
+    return { lane: ready ? 'ready' : 'backlog', state: 'not-started', intentState: intent.status, progress: 0, phase: 'backlog' };
+  }
+  if (state.status === 'completed') return { lane: 'done', state: state.status, intentState: state.intent.status, progress: 100, phase: state.currentPhase };
+  if (state.status === 'paused-awaiting-manual-qa') return { lane: 'qa', state: state.status, intentState: state.intent.status, progress: progress(state), phase: state.currentPhase };
+  if (['shelf-ready', 'validated-not-for-build'].includes(state.status)) {
+    return { lane: 'ready', state: state.status, intentState: state.intent.status, progress: progress(state), phase: state.currentPhase };
+  }
+  return { lane: 'active', state: state.status, intentState: state.intent.status, progress: progress(state), phase: state.currentPhase };
+}
+
+function gateBlockers(paths, state, phase) {
+  const blockers = [];
+  try {
+    validatePhaseArtefacts(
+      paths.deliveryRoot,
+      phase.id,
+      phase.validation?.providers ?? state.providers ?? [],
+      phase.validation?.cycles ?? [],
+    );
+  } catch (error) {
+    blockers.push(blocker('phase-artefacts-incomplete', error.message, relative(paths.projectRoot, paths.deliveryRoot)));
+  }
+  if (phase.validation) {
+    for (const provider of phase.validation.providers ?? []) {
+      const cycles = (phase.validation.cycles ?? []).filter((cycle) => cycle.provider === provider);
+      if (!cycles.length || cycles.at(-1).outcome !== 'pass') {
+        blockers.push(blocker('external-validation-incomplete', `${provider} has not recorded a passing final validation cycle.`, phase.id));
+      }
+    }
+  }
+
+  const gatePath = resolve(paths.gatesRoot, phase.id, 'gate-ledger.json');
+  if (!existsSync(gatePath)) {
+    blockers.push(blocker('phase-gate-missing', `Phase ${phase.id} has no gate ledger.`, relative(paths.projectRoot, gatePath)));
+    return blockers;
+  }
+  try {
+    const gate = JSON.parse(readFileSync(gatePath, 'utf8'));
+    if (gate.schema_version !== 1 || gate.phase !== phase.id || gate.status !== 'pass') {
+      blockers.push(blocker('phase-gate-not-passing', `Phase ${phase.id} gate ledger is not passing.`, relative(paths.projectRoot, gatePath)));
+    }
+    const honesty = gate.honesty_check ?? {};
+    for (const key of ['source_sections_edited', 'stale_text_removed', 'no_append_only_corrections', 'all_code_claims_cited']) {
+      if (honesty[key] !== true) blockers.push(blocker('phase-gate-honesty-incomplete', `Phase ${phase.id} gate is missing honesty confirmation: ${key}.`, relative(paths.projectRoot, gatePath)));
+    }
+    for (const item of gate.required_gates ?? []) {
+      if (item.status === 'not_applicable') continue;
+      if (item.status !== 'pass') {
+        blockers.push(blocker('required-gate-not-passing', `Required gate ${item.id} is ${item.status ?? 'unrecorded'}.`, item.id));
+        continue;
+      }
+      const evidencePath = resolve(paths.deliveryRoot, item.output_path ?? '');
+      if (!item.output_path || !isWithin(paths.deliveryRoot, evidencePath) || !existsSync(evidencePath) || !statSync(evidencePath).isFile()) {
+        blockers.push(blocker('gate-evidence-missing', `Required gate ${item.id} has no valid evidence file.`, item.output_path ?? item.id));
+      } else if (!item.evidence_hash || sha256(readFileSync(evidencePath)) !== item.evidence_hash) {
+        blockers.push(blocker('gate-evidence-stale', `Required gate ${item.id} evidence has changed.`, item.output_path));
+      }
+    }
+    validatePhaseGateAtPaths(paths, phase.id, gate, {
+      providers: phase.validation?.providers ?? state.providers ?? [],
+    });
+  } catch (error) {
+    blockers.push(blocker('phase-gate-invalid', `Phase ${phase.id} gate ledger is invalid: ${error.message}`, relative(paths.projectRoot, gatePath)));
+  }
+  return blockers;
+}
+
+function deriveTasks(paths, leases) {
+  const graphPath = resolve(paths.deliveryRoot, 'task-graph.json');
+  if (!existsSync(graphPath)) {
+    return { status: 'not-planned', validation: null, tasks: [], available: [], maxParallelTasks: 1 };
+  }
+  let graph = null;
+  try {
+    graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+  } catch {
+    // The deterministic validator reports the parse failure.
+  }
+  const validation = validateTaskGraph(paths.deliveryRoot, {
+    slug: paths.deliveryRoot.split('/').at(-1),
+  });
+  const activeByTask = new Map(
+    leases.filter((lease) => lease.status === 'active').map((lease) => [lease.taskId, lease]),
+  );
+  const tasks = validation.tasks.map((task) => {
+    const lease = activeByTask.get(task.id) ?? null;
+    return { ...task, status: lease ? 'leased' : task.status, lease };
+  });
+  return {
+    status: validation.status === 'pass' ? 'planned' : 'invalid',
+    validation,
+    tasks,
+    available: tasks.filter((task) => task.status === 'ready').map((task) => task.id),
+    maxParallelTasks: Number(graph?.parallelism?.max_parallel_tasks ?? 1),
+  };
+}
+
+export function deriveExecutionState(projectRoot, intent, options = {}) {
+  if (!intent) throw new Error('Execution state requires an intent.');
+  const paths = deliveryPaths(projectRoot, intent.slug);
+  const blockers = [];
+  let state = null;
+
+  if (existsSync(paths.statePath)) {
+    try {
+      state = JSON.parse(readFileSync(paths.statePath, 'utf8'));
+      if (state.schema !== 'ewai.delivery-state/v1' || state.slug !== intent.slug) {
+        blockers.push(blocker('delivery-state-invalid', 'Durable delivery state has the wrong schema or slug.', relative(paths.projectRoot, paths.statePath)));
+      } else {
+        try {
+          validateIntentStateCopies(paths.projectRoot, intent.path, {
+            status: state.intent.status,
+            deliveryStatus: state.status,
+            currentPhase: state.currentPhase,
+            deliveryStatePath: relative(paths.projectRoot, paths.statePath).replaceAll('\\', '/'),
+          });
+        } catch (error) {
+          blockers.push(blocker('intent-state-drift', error.message, relative(paths.projectRoot, intent.path)));
+        }
+        try {
+          assertCompletedEvidenceFresh(paths, state);
+        } catch (error) {
+          blockers.push(blocker('completed-evidence-stale', error.message, relative(paths.projectRoot, paths.deliveryRoot)));
+        }
+      }
+    } catch (error) {
+      blockers.push(blocker('delivery-state-invalid', `Durable delivery state cannot be read: ${error.message}`, relative(paths.projectRoot, paths.statePath)));
+    }
+  }
+
+  const catalog = options.intentCatalog instanceof Map ? options.intentCatalog : new Map();
+  if (!catalog.has(intent.id)) catalog.set(intent.id, intent);
+  const dependencyAudit = validateIntentDependencyGraph([...catalog.values()]);
+  for (const error of dependencyAudit.errors) {
+    if (error.source === intent.id || error.target === intent.id || error.cycle?.includes(intent.id)) {
+      blockers.push(blocker(error.code, error.message, error.target ?? intent.id));
+    }
+  }
+  const valid = blockers.length === 0;
+  const taskState = state ? deriveTasks(paths, options.leases ?? []) : { status: 'not-planned', validation: null, tasks: [], available: [], maxParallelTasks: 1 };
+  const runningPhase = state ? phaseSequence(state).find((phase) => phase.status === 'running') : null;
+  const completeBlockers = [...blockers];
+  if (runningPhase?.id === 'intent' && !acceptedIntentStatuses.has(String(intent.status).toLowerCase())) {
+    completeBlockers.push(blocker('intent-not-ready', 'Intent must be ready or approved before the Intent phase can complete.', intent.id));
+  }
+  if (runningPhase?.id === 'delivery') completeBlockers.push(...dependencyRequirementBlockers(projectRoot, intent, catalog, 'delivery'));
+  if (runningPhase && valid) completeBlockers.push(...gateBlockers(paths, state, runningPhase));
+
+  const nextPhase = state ? nextRequiredPhase(state) : null;
+  const buildApprovalPath = resolve(paths.gatesRoot, 'build/build-approval.json');
+  const buildApproved = Boolean(state?.approvals?.build && existsSync(buildApprovalPath));
+  const buildDependencyBlockers = dependencyRequirementBlockers(projectRoot, intent, catalog, 'build');
+  const buildReadinessBlockers = [
+    ...blockers,
+    ...buildDependencyBlockers,
+    ...(nextPhase === 'build' ? [] : [blocker('build-not-next', `Build is not next; current required phase is ${nextPhase ?? 'none'}.`, nextPhase ?? '')]),
+  ];
+  const taskBlockers = [...blockers];
+  if (taskState.status === 'not-planned') taskBlockers.push(blocker('task-graph-not-planned', 'No task graph exists yet.', relative(paths.projectRoot, resolve(paths.deliveryRoot, 'task-graph.json'))));
+  if (taskState.status === 'invalid') taskBlockers.push(blocker('task-graph-invalid', 'Task graph failed deterministic validation.', taskState.validation?.graphPath ?? 'task-graph.json'));
+  if (!taskState.available.length) taskBlockers.push(blocker('no-afk-task-ready', 'No unleased AFK task currently has satisfied dependencies.', 'task-graph.json'));
+  const buildRunning = state?.currentPhase === 'build'
+    && state.phases?.find((phase) => phase.id === 'build')?.status === 'running';
+  if (!buildRunning) taskBlockers.push(blocker('build-not-running', 'Tasks can be leased only after the guarded harness has entered Build.', state?.currentPhase ?? 'not-started'));
+
+  const actions = {
+    beginHarness: action(!state && valid, state ? [blocker('delivery-already-started', 'The delivery harness has already started.', relative(paths.projectRoot, paths.statePath))] : blockers),
+    continueHarness: action(Boolean(state) && valid && !['completed', 'validated-not-for-build'].includes(state?.status), blockers, { nextPhase }),
+    completeCurrentPhase: action(Boolean(runningPhase) && valid, completeBlockers, { phase: runningPhase?.id ?? null }),
+    approveBuild: action(nextPhase === 'build' && !buildApproved && valid, [
+      ...buildReadinessBlockers,
+      ...(buildApproved ? [blocker('build-already-approved', 'Build has already been approved.', relative(paths.projectRoot, buildApprovalPath))] : []),
+    ]),
+    enterBuild: action(nextPhase === 'build' && buildApproved && valid, [
+      ...buildReadinessBlockers,
+      ...(buildApproved ? [] : [blocker('build-approval-missing', 'Build requires explicit recorded approval.', relative(paths.projectRoot, buildApprovalPath))]),
+    ]),
+    acquireTask: action(valid && buildRunning && taskState.status === 'planned' && taskState.available.length > 0, taskBlockers, { candidates: taskState.available }),
+  };
+
+  return {
+    schema: 'ewai.execution-state/v1',
+    valid,
+    intent: { id: intent.id, slug: intent.slug, status: intent.status },
+    lifecycle: {
+      status: state?.status ?? 'not-started',
+      currentPhase: state?.currentPhase ?? 'backlog',
+      nextPhase,
+      deliveryStatePath: state ? relative(paths.projectRoot, paths.statePath).replaceAll('\\', '/') : null,
+    },
+    blockers,
+    actions,
+    tasks: taskState,
+    projection: projection(intent, state, valid),
+  };
+}

package/src/install.mjs

@@ -0,0 +1,166 @@
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  symlinkSync
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const installRoot = resolve(moduleDir, '..');
+const skillSourceRoot = resolve(installRoot, 'skills-src');
+const claudeAgentSourceRoot = resolve(installRoot, 'agents-src/claude');
+
+function availableSkills() {
+  return readdirSync(skillSourceRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(resolve(skillSourceRoot, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function availableClaudeAgents() {
+  if (!existsSync(claudeAgentSourceRoot)) return [];
+  return readdirSync(claudeAgentSourceRoot, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function selectedHosts(host, home) {
+  if (host !== 'auto') return [host];
+  const hosts = [];
+  if (existsSync(resolve(home, '.codex'))) hosts.push('codex');
+  if (existsSync(resolve(home, '.claude'))) hosts.push('claude');
+  if (
+    existsSync(resolve(home, '.gemini/antigravity-cli'))
+    || existsSync(resolve(home, '.gemini/config'))
+  ) hosts.push('antigravity');
+  return hosts.length ? hosts : ['codex'];
+}
+
+function skillDestinationRoot({ scope, host, home, projectRoot }) {
+  if (scope === 'project') {
+    if (!projectRoot) throw new Error('Project installation requires projectRoot');
+    return host === 'claude'
+      ? resolve(projectRoot, '.claude/skills')
+      : resolve(projectRoot, '.agents/skills');
+  }
+  return host === 'claude'
+    ? resolve(home, '.claude/skills')
+    : host === 'antigravity'
+      ? resolve(home, '.gemini/config/skills')
+      : resolve(home, '.codex/skills');
+}
+
+function installSkill(source, destination, mode, force) {
+  if (existsSync(destination) || lstatExists(destination)) {
+    if (!force) return { status: 'skipped', destination };
+    rmSync(destination, { recursive: true, force: true });
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  if (mode === 'link') {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source)) {
+      symlinkSync(resolve(source, entry), resolve(destination, entry));
+    }
+  } else {
+    cpSync(source, destination, { recursive: true, force: false, errorOnExist: true });
+  }
+  return { status: 'installed', destination };
+}
+
+function installFile(source, destination, mode, force) {
+  if (lstatExists(destination)) {
+    if (!force) return { status: 'skipped', destination };
+    rmSync(destination, { recursive: true, force: true });
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  if (mode === 'link') symlinkSync(source, destination);
+  else cpSync(source, destination, { force: false, errorOnExist: true });
+  return { status: 'installed', destination };
+}
+
+function lstatExists(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function install(options = {}) {
+  const scope = options.scope ?? 'global';
+  const home = resolve(options.home ?? homedir());
+  const mode = options.mode ?? 'copy';
+  if (!['global', 'project'].includes(scope)) throw new Error(`Unsupported install scope: ${scope}`);
+  if (!['copy', 'link'].includes(mode)) throw new Error(`Unsupported install mode: ${mode}`);
+
+  const hosts = selectedHosts(options.host ?? 'auto', home);
+  for (const host of hosts) {
+    if (!['codex', 'claude', 'antigravity'].includes(host)) throw new Error(`Unsupported agent host: ${host}`);
+  }
+
+  const results = [];
+  const agentResults = [];
+  for (const host of hosts) {
+    const destinationRoot = skillDestinationRoot({
+      scope,
+      host,
+      home,
+      projectRoot: options.projectRoot ? resolve(options.projectRoot) : ''
+    });
+    mkdirSync(destinationRoot, { recursive: true });
+    for (const skill of availableSkills()) {
+      const destination = resolve(destinationRoot, skill);
+      results.push({
+        host,
+        skill,
+        ...installSkill(
+          resolve(skillSourceRoot, skill),
+          destination,
+          mode,
+          Boolean(options.force)
+        )
+      });
+    }
+    if (host === 'claude') {
+      const agentRoot = scope === 'project'
+        ? resolve(options.projectRoot, '.claude/agents')
+        : resolve(home, '.claude/agents');
+      for (const agent of availableClaudeAgents()) {
+        agentResults.push({
+          host,
+          agent: agent.slice(0, -3),
+          ...installFile(
+            resolve(claudeAgentSourceRoot, agent),
+            resolve(agentRoot, agent),
+            mode,
+            Boolean(options.force)
+          )
+        });
+      }
+    }
+  }
+
+  if (scope === 'global' && options.installBin !== false) {
+    const binDir = resolve(options.binDir ?? resolve(home, '.local/bin'));
+    const destination = resolve(binDir, basename('ewai'));
+    mkdirSync(binDir, { recursive: true });
+    if (lstatExists(destination)) {
+      if (options.force) rmSync(destination, { force: true });
+      else return { scope, mode, hosts, skills: results, agents: agentResults, bin: { status: 'skipped', destination } };
+    }
+    symlinkSync(resolve(installRoot, 'bin/ewai'), destination);
+    return { scope, mode, hosts, skills: results, agents: agentResults, bin: { status: 'installed', destination } };
+  }
+
+  return { scope, mode, hosts, skills: results, agents: agentResults };
+}

package/src/intent-dependencies.mjs

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { projectPaths } from './paths.mjs';
+
+const enforcementPoints = new Set(['build', 'delivery']);
+const requiredStates = new Set(['plan-complete', 'delivered']);
+
+function dependencyRelationships(intent) {
+  return (intent.relationships ?? []).filter((relationship) => relationship.type === 'depends-on');
+}
+
+function requirement(relationship) {
+  return {
+    requiredBefore: relationship.required_before ?? 'delivery',
+    requiredState: relationship.required_state ?? 'delivered',
+  };
+}
+
+function targetSatisfies(projectRoot, target, requiredState) {
+  if (requiredState === 'delivered') {
+    return ['completed', 'delivered'].includes(String(target.deliveryStatus ?? target.status).toLowerCase());
+  }
+  const path = resolve(projectPaths(projectRoot).buildRoot, target.slug, 'delivery-state.json');
+  if (!existsSync(path)) return false;
+  try {
+    const state = JSON.parse(readFileSync(path, 'utf8'));
+    return state.schema === 'ewai.delivery-state/v1'
+      && state.slug === target.slug
+      && state.phases?.find((phase) => phase.id === 'plan')?.status === 'completed';
+  } catch {
+    return false;
+  }
+}
+
+export function validateIntentDependencyGraph(intents) {
+  const catalog = new Map(intents.map((intent) => [intent.id, intent]));
+  const errors = [];
+  const edges = new Map(intents.map((intent) => [intent.id, []]));
+  const slugOwners = new Map();
+  for (const intent of intents) {
+    const owners = slugOwners.get(intent.slug) ?? [];
+    owners.push(intent.id);
+    slugOwners.set(intent.slug, owners);
+  }
+  for (const [slug, owners] of slugOwners) {
+    if (owners.length < 2) continue;
+    for (const owner of owners) {
+      errors.push({
+        code: 'intent-slug-collision',
+        source: owner,
+        target: owners.find((candidate) => candidate !== owner),
+        message: `Intent slug ${slug} is shared by ${owners.join(', ')} but delivery folders are slug-keyed.`,
+      });
+    }
+  }
+  for (const intent of intents) {
+    for (const relationship of dependencyRelationships(intent)) {
+      const { requiredBefore, requiredState } = requirement(relationship);
+      if (!catalog.has(relationship.target)) {
+        errors.push({ code: 'intent-dependency-missing', source: intent.id, target: relationship.target, message: `${intent.id} depends on missing intent ${relationship.target}.` });
+      } else {
+        edges.get(intent.id).push(relationship.target);
+        const target = catalog.get(relationship.target);
+        if ((slugOwners.get(target.slug) ?? []).length > 1) {
+          errors.push({
+            code: 'intent-dependency-target-collision',
+            source: intent.id,
+            target: relationship.target,
+            message: `${intent.id} depends on ${relationship.target}, whose slug-keyed delivery namespace collides.`,
+          });
+        }
+      }
+      if (!enforcementPoints.has(requiredBefore)) {
+        errors.push({ code: 'intent-dependency-enforcement', source: intent.id, target: relationship.target, message: `${intent.id} has unsupported required_before ${requiredBefore}.` });
+      }
+      if (!requiredStates.has(requiredState)) {
+        errors.push({ code: 'intent-dependency-state', source: intent.id, target: relationship.target, message: `${intent.id} has unsupported required_state ${requiredState}.` });
+      }
+    }
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (id, trail = []) => {
+    if (visiting.has(id)) {
+      const cycle = [...trail, id];
+      errors.push({ code: 'intent-dependency-cycle', source: id, target: id, cycle, message: `Intent dependency cycle detected: ${cycle.join(' -> ')}.` });
+      return;
+    }
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const target of edges.get(id) ?? []) visit(target, [...trail, id]);
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of edges.keys()) visit(id);
+  return { schema: 'ewai.intent-dependency-audit/v1', status: errors.length ? 'fail' : 'pass', checked: intents.length, errors };
+}
+
+export function dependencyRequirementBlockers(projectRoot, intent, catalog, enforcementPoint) {
+  const blockers = [];
+  for (const relationship of dependencyRelationships(intent)) {
+    const target = catalog.get(relationship.target);
+    const { requiredBefore, requiredState } = requirement(relationship);
+    if (requiredBefore !== enforcementPoint) continue;
+    if (!target) {
+      blockers.push({ code: 'intent-dependency-missing', message: `Dependency ${relationship.target} does not exist.`, evidence: relationship.target });
+    } else if (!targetSatisfies(projectRoot, target, requiredState)) {
+      blockers.push({
+        code: 'intent-dependency-incomplete',
+        message: `Dependency ${relationship.target} must reach ${requiredState} before ${enforcementPoint}.`,
+        evidence: relationship.target,
+      });
+    }
+  }
+  return blockers;
+}