@friedbotstudio/create-baseline 0.6.0 → 0.8.0

package/src/cli/tui/upgrade.js

@@ -2,7 +2,9 @@
 // Plan/apply split:
 //   1. detect pending semantic-merge stage (idempotency short-circuit, AC-007)
 //   2. dry-run threeWayMerge → enumerate SKIP_CUSTOMIZED conflicts (tier-1 only)
-//   3. prompt the user once per tier-1 conflict (with Show-diff loop, cap-at-2)
+//   3. prompt the user once per tier-1 conflict: Keep your version / Use new
+//      baseline / Merge / Abort. The Merge pick stages incoming bytes for
+//      /upgrade-project to reconcile (tier1-merge-option spec).
 //   4. on cancel/abort: bail before any write
 //   5. on resolve: real threeWayMerge with onSkipCustomized backed by the Map.
 // Tier-2 MECHANICAL and tier-3 SEMANTIC files are NOT prompted — they're
@@ -12,11 +14,10 @@ import * as clackModule from '@clack/prompts';
 import { existsSync } from 'node:fs';
 import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { threeWayMerge, ACTION_KINDS } from '../merge.js';
+import { threeWayMerge, ACTION_KINDS, ACTION_LABELS, ACTION_LABEL_WIDTH } from '../merge.js';
 import { loadManifest, buildManifestFromDir } from '../manifest.js';
 import { COPY_EXCLUDE } from '../install.js';
-import { findPendingStage } from '../upgrade-tiers.js';
-import { renderUnifiedDiff } from '../diff-render.js';
+import { findPendingStage, formatStageTimestamp } from '../upgrade-tiers.js';
 import { renderBrandStrip } from './splash.js';
 
 const SUCCESS = 0;
@@ -29,12 +30,10 @@ const ERR_SEMANTIC_STAGED = 5;
 const CHOICE_OPTIONS = [
   { value: 'keep-mine', label: 'Keep your version', hint: 'preserve target file as-is' },
   { value: 'take-theirs', label: 'Use new baseline', hint: 'overwrite with new template' },
-  { value: 'show-diff', label: 'Show diff', hint: 'render local vs incoming and re-prompt' },
+  { value: 'merge', label: 'Merge', hint: 'stage incoming bytes for /upgrade-project to reconcile' },
   { value: 'abort', label: 'Abort', hint: 'exit without changes' },
 ];
 
-const SHOW_DIFF_CONSECUTIVE_CAP = 2;
-
 export async function run({ target, opts = {}, prompts = clackModule } = {}) {
   if (!target || typeof target !== 'string') {
     throw new Error('tui.upgrade.run requires a non-empty string target');
@@ -58,14 +57,14 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   const { oldManifest, newManifest } = await loadManifests(opts.templateDir, manifestPath);
   if (isLegacyManifest(oldManifest)) {
-    prompts.log.warn('legacy manifest_version: 1 detected; BASE-content recovery unavailable. Tier-2 / tier-3 files will fall back to the binary prompt.');
+    prompts.log.warn("Your previous install predates version-tracked manifests, so this upgrade can't perform automatic three-way merges on customized files. You'll be prompted to keep your version or take the new baseline for each customized file. To enable three-way merges next time, re-install with the latest baseline.");
   }
 
   const dryReport = await threeWayMerge(opts.templateDir, target, oldManifest, newManifest, { dryRun: true });
   const conflicts = dryReport.actions.filter((a) => a.kind === ACTION_KINDS.SKIP_CUSTOMIZED);
 
   const choices = new Map();
-  const aborted = await collectUserChoices(prompts, conflicts, opts.templateDir, target, choices);
+  const aborted = await collectUserChoices(prompts, conflicts, choices);
   if (aborted) {
     prompts.cancel('Upgrade aborted; tree unchanged.');
     return ERR_ABORT;
@@ -73,7 +72,8 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   if (opts.dryRun) {
     for (const action of dryReport.actions) {
-      prompts.log.info(`${action.kind.padEnd(28)} ${action.path}`);
+      const label = ACTION_LABELS[action.kind] ?? action.kind;
+      prompts.log.info(`${label.padEnd(ACTION_LABEL_WIDTH)}  ${action.path}`);
     }
     prompts.outro('Dry run complete; no changes written.');
     return SUCCESS;
@@ -84,7 +84,8 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   for (const action of finalReport.actions) {
     if (isReportableAction(action.kind)) {
-      prompts.log.info(`${action.kind.padEnd(28)} ${action.path}`);
+      const label = ACTION_LABELS[action.kind] ?? action.kind;
+      prompts.log.info(`${label.padEnd(ACTION_LABEL_WIDTH)}  ${action.path}`);
     }
     if (action.kind === ACTION_KINDS.MECHANICAL_MERGE_CONFLICTED) {
       prompts.log.warn(`Merged with conflicts — resolve in ${action.path}`);
@@ -93,19 +94,23 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   const stagedCount = finalReport.actions.filter((a) => a.kind === ACTION_KINDS.SEMANTIC_MERGE_STAGED).length;
   if (stagedCount > 0) {
-    prompts.log.info(`${stagedCount} file(s) need semantic merge. Open Claude Code and run /upgrade-project to reconcile.`);
+    prompts.log.info(`${stagedCount} file(s) staged. Open Claude Code and run /upgrade-project to reconcile.`);
   }
 
   const applied = finalReport.actions.filter((a) => isApplied(a.kind)).length;
   const skipped = finalReport.actions.filter((a) => a.kind === ACTION_KINDS.SKIP_CUSTOMIZED).length;
-  prompts.outro(`Applied ${applied}; ${skipped} skipped.`);
+  prompts.outro(
+    skipped === 0
+      ? `Applied ${applied} update(s).`
+      : `Applied ${applied} update(s); kept your version on ${skipped} customized file(s). Re-run \`create-baseline upgrade\` if you want to revisit those choices.`,
+  );
   return mapExitCode(finalReport.exitCode);
 }
 
 function reportPendingStage(prompts, pending) {
   const fileLines = pending.files.map((f) => `  - ${f}`).join('\n');
-  prompts.log.warn(`Pending semantic-merge stage at ${pending.stage_ts}.\n${pending.files.length} file(s) awaiting reconciliation:\n${fileLines}\nOpen Claude Code and run /upgrade-project to reconcile.`);
-  prompts.outro('No new work; existing stage pending.');
+  prompts.log.warn(`A previous upgrade staged ${pending.files.length} file(s) for Claude Code review (staged ${formatStageTimestamp(pending.stage_ts)}):\n${fileLines}\nOpen Claude Code and run /upgrade-project to reconcile.`);
+  prompts.outro('No new work; previous staged files still need reconciliation.');
   return ERR_SEMANTIC_STAGED;
 }
 
@@ -115,38 +120,22 @@ function isLegacyManifest(m) {
   return typeof m.baseline_version !== 'string';
 }
 
-async function collectUserChoices(prompts, conflicts, templateDir, target, choices) {
+async function collectUserChoices(prompts, conflicts, choices) {
   for (const conflict of conflicts) {
-    const choice = await pickForFile(prompts, conflict.path, templateDir, target);
+    const choice = await pickForFile(prompts, conflict.path);
     if (choice === 'abort') return true;
-    if (choice !== null) choices.set(conflict.path, choice);
+    choices.set(conflict.path, choice);
   }
   return false;
 }
 
-async function pickForFile(prompts, rel, templateDir, target) {
-  let consecutiveShowDiff = 0;
-  while (true) {
-    const choice = await prompts.select({
-      message: `${rel} has been customized — choose:`,
-      options: CHOICE_OPTIONS,
-    });
-    if (prompts.isCancel(choice)) return 'abort';
-    if (choice !== 'show-diff') return choice;
-    await renderConflictDiff(prompts, rel, templateDir, target);
-    consecutiveShowDiff++;
-    if (consecutiveShowDiff >= SHOW_DIFF_CONSECUTIVE_CAP) {
-      prompts.log.info(`Show-diff picked ${SHOW_DIFF_CONSECUTIVE_CAP} times for ${rel}; falling through (keeping your version). Re-run if you want to choose differently.`);
-      return null;
-    }
-  }
-}
-
-async function renderConflictDiff(prompts, rel, templateDir, target) {
-  const localBytes = await readFile(join(target, rel), 'utf8');
-  const incomingBytes = await readFile(join(templateDir, rel), 'utf8');
-  const diff = renderUnifiedDiff(localBytes, incomingBytes, { colorize: process.stdout.isTTY === true });
-  prompts.log.info(`Diff for ${rel} (local → incoming):\n${diff}`);
+async function pickForFile(prompts, rel) {
+  const choice = await prompts.select({
+    message: `${rel} has been customized — choose:`,
+    options: CHOICE_OPTIONS,
+  });
+  if (prompts.isCancel(choice)) return 'abort';
+  return choice;
 }
 
 function isReportableAction(kind) {

package/src/cli/upgrade-tiers.js

@@ -41,6 +41,28 @@ export async function resolveBase(rel, baseline_version, target, opts = {}) {
   return fetched;
 }
 
+// Returns true when resolveBase would succeed for this file without throwing
+// NoBaseError. Used by merge.js:dispatchCustomized in dry-run mode so the TUI
+// surfaces files whose BASE is unrecoverable as conflicts (and prompts the
+// user) instead of optimistically classifying them as tier-2/3 merge candidates
+// that will silently fall back to keep-mine at real-run time.
+export function canRecoverBase(rel, baseline_version, target) {
+  const cachePath = join(target, '.claude/.baseline-prior', rel);
+  if (existsSync(cachePath)) return true;
+  return Boolean(baseline_version);
+}
+
+// Render a stage_ts (the `stageTimestamp` format: ISO 8601 with every `:` and
+// `.` replaced by `-`, e.g. "2026-05-20T14-49-00-000Z") as a human-readable
+// "YYYY-MM-DD HH:MM UTC". Returns the input unchanged when the pattern doesn't
+// match so we never silently corrupt an unexpected value.
+export function formatStageTimestamp(ts) {
+  if (typeof ts !== 'string') return String(ts);
+  const m = ts.match(/^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-\d{2}-\d{3}Z$/);
+  if (!m) return ts;
+  return `${m[1]} ${m[2]}:${m[3]} UTC`;
+}
+
 export async function findPendingStage(target) {
   const stageRoot = join(target, '.claude/state/upgrade');
   if (!existsSync(stageRoot)) return null;
@@ -64,14 +86,30 @@ export async function dispatchByTier(rel, tier, ctx) {
 }
 
 export async function writeStage(ctx, rel, baseBuf, incomingBuf, localBuf) {
-  if (!ctx.stageRunTs) ctx.stageRunTs = stageTimestamp();
-  const stageDir = join(ctx.target, '.claude/state/upgrade', ctx.stageRunTs);
-  await mkdir(stageDir, { recursive: true });
+  const stageDir = await ensureStageDir(ctx);
   await writeStageArtifact(stageDir, `${rel}.baseline-base`, baseBuf);
   await writeStageArtifact(stageDir, `${rel}.baseline-incoming`, incomingBuf);
   await appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, localBuf);
 }
 
+// BASE-less stage writer used by the tier-1 Merge pick (see
+// docs/specs/tier1-merge-option.md §Behavior #2 + design pick 1A). Unlike
+// writeStage, no BASE artifact is written and the manifest entry carries
+// base_sha256: null — the discriminator /upgrade-project reads to route to
+// two-way reconciliation.
+export async function writeStageBaseless(ctx, rel, incomingBuf, localBuf) {
+  const stageDir = await ensureStageDir(ctx);
+  await writeStageArtifact(stageDir, `${rel}.baseline-incoming`, incomingBuf);
+  await appendToStageManifest(stageDir, ctx, rel, null, incomingBuf, localBuf);
+}
+
+async function ensureStageDir(ctx) {
+  if (!ctx.stageRunTs) ctx.stageRunTs = stageTimestamp();
+  const stageDir = join(ctx.target, '.claude/state/upgrade', ctx.stageRunTs);
+  await mkdir(stageDir, { recursive: true });
+  return stageDir;
+}
+
 // --- foundation helpers ---
 
 function sha256(buf) {
@@ -210,7 +248,7 @@ async function appendToStageManifest(stageDir, ctx, rel, baseBuf, incomingBuf, l
     : newStageManifest(ctx);
   manifest.files.push({
     rel,
-    base_sha256: sha256(baseBuf),
+    base_sha256: baseBuf === null ? null : sha256(baseBuf),
     incoming_sha256: sha256(incomingBuf),
     local_sha256: sha256(localBuf),
     status: 'PENDING',

package/src/cli/workflow-migrator.js

@@ -0,0 +1,40 @@
+// Foundation — one-shot migrator that rewrites a pre-§18 `workflow.json`
+// (entry_phase set, no track_id) into the post-§18 shape (track_id, plus
+// skipped_alternates[]) in place. Idempotent on already-post-§18 input.
+// Throws a named error when entry_phase is not in the canonical map.
+
+import { readFile, writeFile } from 'node:fs/promises';
+
+export const ENTRY_PHASE_TO_TRACK_ID = Object.freeze({
+  intake: 'intake-full',
+  spec: 'spec-entry',
+  tdd: 'tdd-quickfix',
+  chore: 'chore',
+});
+
+export async function migrateWorkflowJsonInPlace(filePath) {
+  const text = await readFile(filePath, 'utf8');
+  const data = JSON.parse(text);
+  if ('track_id' in data && !('entry_phase' in data)) {
+    return { migrated: false, reason: 'already post-§18' };
+  }
+  if (!('entry_phase' in data)) {
+    return { migrated: false, reason: 'no entry_phase and no track_id; cannot determine shape' };
+  }
+  const entryPhase = data.entry_phase;
+  const trackId = ENTRY_PHASE_TO_TRACK_ID[entryPhase];
+  if (!trackId) {
+    throw new Error(
+      `Pre-§18 workflow.json has unmapped entry_phase='${entryPhase}'. ` +
+      `Canonical map covers ${Object.keys(ENTRY_PHASE_TO_TRACK_ID).join(', ')}. ` +
+      `Cannot migrate; run /triage to restart this workflow.`
+    );
+  }
+  const migrated = { ...data };
+  migrated.track_id = trackId;
+  migrated.skipped_alternates = Array.isArray(data.skipped_alternates) ? data.skipped_alternates : [];
+  migrated.updated_at = Math.floor(Date.now() / 1000);
+  delete migrated.entry_phase;
+  await writeFile(filePath, JSON.stringify(migrated, null, 2) + '\n');
+  return { migrated: true, track_id: trackId };
+}

package/src/cli/workflows-validator-invariants.js

@@ -0,0 +1,417 @@
+// Domain — Article IV invariant checks (I1..I11). Each `check*` function
+// returns an array of named-error objects; empty array means the invariant
+// holds. `checkAllInvariants` runs them in order and returns the union.
+//
+// Named-error shape:
+//   { kind: 'invariant_iN', track_id?, node_id?, message, ...details }
+
+import { isKnownPredicate } from './workflows-validator-predicates.js';
+
+// ---------- I1 ----------
+
+export function checkI1_uniqueTrackIds(tracks) {
+  const seen = new Map();
+  const errors = [];
+  for (let i = 0; i < tracks.length; i++) {
+    const t = tracks[i];
+    if (seen.has(t.track_id)) {
+      errors.push({
+        kind: 'invariant_i1',
+        track_id: t.track_id,
+        first_line: seen.get(t.track_id) + 1,
+        second_line: i + 1,
+        message: `Duplicate track_id '${t.track_id}' at index ${i + 1} (first seen at index ${seen.get(t.track_id) + 1}).`,
+      });
+    } else {
+      seen.set(t.track_id, i);
+    }
+  }
+  return errors;
+}
+
+// ---------- I2 ----------
+
+export function checkI2_uniqueNodeIdsWithinTrack(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    const seen = new Set();
+    for (const node of t.nodes) {
+      if (seen.has(node.id)) {
+        errors.push({
+          kind: 'invariant_i2',
+          track_id: t.track_id,
+          node_id: node.id,
+          message: `Track '${t.track_id}' has duplicate node id '${node.id}'.`,
+        });
+      } else {
+        seen.add(node.id);
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------- I3 ----------
+
+export function checkI3_skillOrSubTrackXor(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    for (const node of t.nodes) {
+      if (node.type === 'selector') {
+        if (!Array.isArray(node.alternates) || node.alternates.length === 0) {
+          errors.push({
+            kind: 'invariant_i3',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Selector node '${node.id}' in track '${t.track_id}' has empty alternates[]. Selector nodes require non-empty alternates.`,
+          });
+        }
+      } else {
+        const hasSkill = typeof node.skill === 'string' && node.skill.length > 0;
+        const hasSubTrack = typeof node.sub_track === 'string' && node.sub_track.length > 0;
+        if (hasSkill && hasSubTrack) {
+          errors.push({
+            kind: 'invariant_i3',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Task node '${node.id}' in track '${t.track_id}' has BOTH skill and sub_track set. Exactly one of {skill, sub_track} is required.`,
+          });
+        } else if (!hasSkill && !hasSubTrack) {
+          errors.push({
+            kind: 'invariant_i3',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Task node '${node.id}' in track '${t.track_id}' has NEITHER skill nor sub_track set. Exactly one is required.`,
+          });
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------- I4 ----------
+
+export function checkI4_edgeResolution(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    const nodeIds = new Set(t.nodes.map((n) => n.id));
+    for (const node of t.nodes) {
+      for (const dep of node.depends_on || []) {
+        if (!nodeIds.has(dep)) {
+          errors.push({
+            kind: 'invariant_i4',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Track '${t.track_id}' node '${node.id}' depends_on '${dep}' which does not exist in the track. (I4: edge resolution)`,
+          });
+        }
+      }
+      for (const blk of node.blocks || []) {
+        if (!nodeIds.has(blk)) {
+          errors.push({
+            kind: 'invariant_i4',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Track '${t.track_id}' node '${node.id}' blocks '${blk}' which does not exist in the track. (I4: edge resolution)`,
+          });
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------- I5 ----------
+
+export function checkI5_dagAcyclic(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    const cycle = detectCycle(t.nodes);
+    if (cycle) {
+      errors.push({
+        kind: 'invariant_i5',
+        track_id: t.track_id,
+        cycle,
+        message: `Track '${t.track_id}' has a cycle in its dependency DAG: ${cycle.join(' -> ')}.`,
+      });
+    }
+  }
+  return errors;
+}
+
+function detectCycle(nodes) {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map(nodes.map((n) => [n.id, WHITE]));
+  const stack = [];
+  function dfs(id) {
+    color.set(id, GRAY);
+    stack.push(id);
+    const node = byId.get(id);
+    for (const dep of node?.depends_on || []) {
+      if (!byId.has(dep)) continue;
+      const c = color.get(dep);
+      if (c === GRAY) {
+        const idx = stack.indexOf(dep);
+        return stack.slice(idx).concat(dep);
+      }
+      if (c === WHITE) {
+        const found = dfs(dep);
+        if (found) return found;
+      }
+    }
+    stack.pop();
+    color.set(id, BLACK);
+    return null;
+  }
+  for (const n of nodes) {
+    if (color.get(n.id) === WHITE) {
+      const found = dfs(n.id);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// ---------- I6 ----------
+
+export function checkI6_commitsTrackHasGrantCommit(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    if (!Array.isArray(t.invariants) || !t.invariants.includes('commits')) continue;
+    const commitNode = t.nodes.find((n) => n.skill === 'commit');
+    if (!commitNode) {
+      errors.push({
+        kind: 'invariant_i6',
+        track_id: t.track_id,
+        message: `Track '${t.track_id}' declares 'commits' invariant but contains no node with skill='commit'.`,
+      });
+      continue;
+    }
+    const grantCommitNode = t.nodes.find(
+      (n) => n.needs_user === true && (n.skill === 'grant-commit' || n.id === 'grant-commit')
+    );
+    if (!grantCommitNode) {
+      errors.push({
+        kind: 'invariant_i6',
+        track_id: t.track_id,
+        message: `Track '${t.track_id}' declares 'commits' invariant but has no needs_user 'grant-commit' node before commit.`,
+      });
+      continue;
+    }
+    if (!nodeOrderedBefore(t, grantCommitNode.id, commitNode.id)) {
+      errors.push({
+        kind: 'invariant_i6',
+        track_id: t.track_id,
+        message: `Track '${t.track_id}' grant-commit node is not ordered before commit in the dependency DAG.`,
+      });
+    }
+  }
+  return errors;
+}
+
+function nodeOrderedBefore(track, predecessorId, successorId) {
+  const byId = new Map(track.nodes.map((n) => [n.id, n]));
+  const visited = new Set();
+  function reaches(fromId) {
+    if (fromId === successorId) return true;
+    if (visited.has(fromId)) return false;
+    visited.add(fromId);
+    const node = byId.get(fromId);
+    for (const blocked of node?.blocks || []) {
+      if (reaches(blocked)) return true;
+    }
+    return false;
+  }
+  return reaches(predecessorId);
+}
+
+// ---------- I7 ----------
+
+export function checkI7_subTrackResolves(tracks) {
+  const errors = [];
+  const trackMap = new Map(tracks.map((t) => [t.track_id, t]));
+  for (const t of tracks) {
+    for (const node of t.nodes) {
+      const subTrackRefs = collectSubTrackRefs(node);
+      for (const ref of subTrackRefs) {
+        const target = trackMap.get(ref);
+        if (!target) {
+          errors.push({
+            kind: 'invariant_i7',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Track '${t.track_id}' node '${node.id}' references sub_track '${ref}' which does not exist.`,
+          });
+          continue;
+        }
+        if (target.selectable === true) {
+          errors.push({
+            kind: 'invariant_i7',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Track '${t.track_id}' node '${node.id}' references sub_track '${ref}' whose selectable=true. Sub-tracks must have selectable=false.`,
+          });
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+function collectSubTrackRefs(node) {
+  const refs = [];
+  if (node.sub_track) refs.push(node.sub_track);
+  if (Array.isArray(node.alternates)) {
+    for (const alt of node.alternates) {
+      if (alt.sub_track) refs.push(alt.sub_track);
+    }
+  }
+  return refs;
+}
+
+// ---------- I8 ----------
+
+export function checkI8_skillResolves(tracks, { knownSkills }) {
+  const errors = [];
+  for (const t of tracks) {
+    for (const node of t.nodes) {
+      const skillRefs = collectSkillRefs(node);
+      for (const skill of skillRefs) {
+        if (!knownSkills.has(skill)) {
+          errors.push({
+            kind: 'invariant_i8',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Track '${t.track_id}' node '${node.id}' references skill '${skill}' which does not exist on disk.`,
+          });
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+function collectSkillRefs(node) {
+  const refs = [];
+  if (node.skill) refs.push(node.skill);
+  if (Array.isArray(node.alternates)) {
+    for (const alt of node.alternates) {
+      if (alt.skill) refs.push(alt.skill);
+    }
+  }
+  return refs;
+}
+
+// ---------- I9 ----------
+
+export function checkI9_consentGateOrdering(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    const gates = t.nodes.filter((n) => n.needs_user === true);
+    for (const gate of gates) {
+      const hasDependents = t.nodes.some((n) =>
+        (n.depends_on || []).includes(gate.id)
+      );
+      if (!hasDependents && gate.id !== lastNodeId(t)) {
+        errors.push({
+          kind: 'invariant_i9',
+          track_id: t.track_id,
+          node_id: gate.id,
+          message: `Track '${t.track_id}' consent gate '${gate.id}' has no dependent nodes. Consent gates must be followed by at least one dependent unless they terminate the track.`,
+        });
+      }
+    }
+  }
+  return errors;
+}
+
+function lastNodeId(track) {
+  return track.nodes[track.nodes.length - 1]?.id;
+}
+
+// ---------- I10 ----------
+
+export function checkI10_alternatesCongruent(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    for (const node of t.nodes) {
+      if (node.type !== 'selector') continue;
+      const alternates = node.alternates || [];
+      if (alternates.length < 2) continue;
+      const firstShape = describeAlternate(alternates[0]);
+      for (let i = 1; i < alternates.length; i++) {
+        const otherShape = describeAlternate(alternates[i]);
+        if (otherShape !== firstShape) {
+          errors.push({
+            kind: 'invariant_i10',
+            track_id: t.track_id,
+            node_id: node.id,
+            message: `Selector node '${node.id}' in track '${t.track_id}' has alternates with divergent shapes. Alternates must be interchangeable in the DAG (same skill vs sub_track distribution).`,
+          });
+          break;
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+function describeAlternate(alt) {
+  return JSON.stringify({
+    hasSubTrack: !!alt.sub_track,
+    hasSkill: !!alt.skill,
+  });
+}
+
+// ---------- I11 ----------
+
+export function checkI11_predicateNamesResolve(tracks) {
+  const errors = [];
+  for (const t of tracks) {
+    for (const pred of t.preconditions || []) {
+      if (!isKnownPredicate(pred.name)) {
+        errors.push({
+          kind: 'invariant_i11',
+          track_id: t.track_id,
+          message: `Track '${t.track_id}' precondition uses unknown predicate '${pred.name}'. Not in v1 vocabulary.`,
+        });
+      }
+    }
+    for (const node of t.nodes) {
+      if (!Array.isArray(node.alternates)) continue;
+      for (const alt of node.alternates) {
+        for (const pred of alt.preconditions || []) {
+          if (!isKnownPredicate(pred.name)) {
+            errors.push({
+              kind: 'invariant_i11',
+              track_id: t.track_id,
+              node_id: node.id,
+              message: `Track '${t.track_id}' node '${node.id}' alternate uses unknown predicate '${pred.name}'. Not in v1 vocabulary.`,
+            });
+          }
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------- Orchestration ----------
+
+export function checkAllInvariants(tracks, ctx) {
+  return [
+    ...checkI1_uniqueTrackIds(tracks),
+    ...checkI2_uniqueNodeIdsWithinTrack(tracks),
+    ...checkI3_skillOrSubTrackXor(tracks),
+    ...checkI4_edgeResolution(tracks),
+    ...checkI5_dagAcyclic(tracks),
+    ...checkI6_commitsTrackHasGrantCommit(tracks),
+    ...checkI7_subTrackResolves(tracks),
+    ...checkI8_skillResolves(tracks, ctx),
+    ...checkI9_consentGateOrdering(tracks),
+    ...checkI10_alternatesCongruent(tracks),
+    ...checkI11_predicateNamesResolve(tracks),
+  ];
+}