@friedbotstudio/create-baseline 0.6.0 → 0.7.0

package/src/.claude/workflows.template.jsonl

@@ -0,0 +1,6 @@
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"intake-full","name":"Intake-entry full pipeline","description":"Canonical 11-phase pipeline for new features that need full design upfront (intake → scout → research → spec → approval → tdd/swarm → simplify → security → integrate → document → archive → memory-flush → grant-commit → changelog → commit).","selectable":true,"selector_hints":["build a new feature with full design upfront","add new functionality requiring a written spec","constitutional change or architectural refactor"],"preconditions":[],"invariants":["commits","requires_spec"],"nodes":[{"id":"intake","type":"task","skill":"intake","depends_on":[],"blocks":["scout"],"can_parallel":false,"needs_user":false,"activeForm":"Running intake","metadata":{"phase":"intake"}},{"id":"scout","type":"task","skill":"scout","depends_on":["intake"],"blocks":["research"],"can_parallel":false,"needs_user":false,"activeForm":"Running scout","metadata":{"phase":"scout"}},{"id":"research","type":"task","skill":"research","depends_on":["scout"],"blocks":["spec"],"can_parallel":false,"needs_user":false,"activeForm":"Running research","metadata":{"phase":"research"}},{"id":"spec","type":"task","skill":"spec","depends_on":["research"],"blocks":["approve-spec"],"can_parallel":false,"needs_user":false,"activeForm":"Running spec","metadata":{"phase":"spec"}},{"id":"approve-spec","type":"task","skill":"approve-spec","depends_on":["spec"],"blocks":["implementation"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting spec approval","metadata":{"phase":"approve-spec","needs_user":true}},{"id":"implementation","type":"selector","alternates":[{"sub_track":"swarm-implementation","preconditions":[{"name":"requires_git"},{"name":"requires_min_components","argument":"3"}],"description":"Swarm path for git projects with 3+ independent components"},{"sub_track":"tdd-worker-chain","preconditions":[],"description":"Solo TDD fallback (default)"}],"depends_on":["approve-spec"],"blocks":["simplify"],"can_parallel":false,"needs_user":false},{"id":"simplify","type":"task","skill":"simplify","depends_on":["implementation"],"blocks":["security"],"can_parallel":false,"needs_user":false,"activeForm":"Running simplify","metadata":{"phase":"simplify"}},{"id":"security","type":"task","skill":"security","depends_on":["simplify"],"blocks":["integrate"],"can_parallel":false,"needs_user":false,"activeForm":"Running security","metadata":{"phase":"security"}},{"id":"integrate","type":"task","skill":"integrate","depends_on":["security"],"blocks":["document"],"can_parallel":false,"needs_user":false,"activeForm":"Running integrate","metadata":{"phase":"integrate"}},{"id":"document","type":"task","skill":"document","depends_on":["integrate"],"blocks":["archive"],"can_parallel":false,"needs_user":false,"activeForm":"Running document","metadata":{"phase":"document"}},{"id":"archive","type":"task","skill":"archive","depends_on":["document"],"blocks":["memory-flush"],"can_parallel":false,"needs_user":false,"activeForm":"Running archive","metadata":{"phase":"archive"}},{"id":"memory-flush","type":"task","skill":"memory-flush","depends_on":["archive"],"blocks":["grant-commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running memory-flush","metadata":{"phase":"memory-flush"}},{"id":"grant-commit","type":"task","skill":"grant-commit","depends_on":["memory-flush"],"blocks":["changelog"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting commit consent","metadata":{"phase":"grant-commit","needs_user":true}},{"id":"changelog","type":"task","skill":"changelog","depends_on":["grant-commit"],"blocks":["commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running changelog","metadata":{"phase":"changelog"}},{"id":"commit","type":"task","skill":"commit","depends_on":["changelog"],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running commit","metadata":{"phase":"commit"}}]}
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"spec-entry","name":"Spec-entry bugfix pipeline","description":"Bugfix workflow that starts at /spec; skips intake/scout/research. For known-behavior bugs needing a contract-level fix.","selectable":true,"selector_hints":["bug needs a spec","contract-level bugfix","behaviour change requires written design"],"preconditions":[],"invariants":["commits","requires_spec"],"nodes":[{"id":"spec","type":"task","skill":"spec","depends_on":[],"blocks":["approve-spec"],"can_parallel":false,"needs_user":false,"activeForm":"Running spec","metadata":{"phase":"spec"}},{"id":"approve-spec","type":"task","skill":"approve-spec","depends_on":["spec"],"blocks":["tdd"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting spec approval","metadata":{"phase":"approve-spec","needs_user":true}},{"id":"tdd","type":"task","skill":"tdd","depends_on":["approve-spec"],"blocks":["simplify"],"can_parallel":false,"needs_user":false,"activeForm":"Running TDD","metadata":{"phase":"tdd"}},{"id":"simplify","type":"task","skill":"simplify","depends_on":["tdd"],"blocks":["security"],"can_parallel":false,"needs_user":false,"activeForm":"Running simplify","metadata":{"phase":"simplify"}},{"id":"security","type":"task","skill":"security","depends_on":["simplify"],"blocks":["integrate"],"can_parallel":false,"needs_user":false,"activeForm":"Running security","metadata":{"phase":"security"}},{"id":"integrate","type":"task","skill":"integrate","depends_on":["security"],"blocks":["document"],"can_parallel":false,"needs_user":false,"activeForm":"Running integrate","metadata":{"phase":"integrate"}},{"id":"document","type":"task","skill":"document","depends_on":["integrate"],"blocks":["archive"],"can_parallel":false,"needs_user":false,"activeForm":"Running document","metadata":{"phase":"document"}},{"id":"archive","type":"task","skill":"archive","depends_on":["document"],"blocks":["memory-flush"],"can_parallel":false,"needs_user":false,"activeForm":"Running archive","metadata":{"phase":"archive"}},{"id":"memory-flush","type":"task","skill":"memory-flush","depends_on":["archive"],"blocks":["grant-commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running memory-flush","metadata":{"phase":"memory-flush"}},{"id":"grant-commit","type":"task","skill":"grant-commit","depends_on":["memory-flush"],"blocks":["changelog"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting commit consent","metadata":{"phase":"grant-commit","needs_user":true}},{"id":"changelog","type":"task","skill":"changelog","depends_on":["grant-commit"],"blocks":["commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running changelog","metadata":{"phase":"changelog"}},{"id":"commit","type":"task","skill":"commit","depends_on":["changelog"],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running commit","metadata":{"phase":"commit"}}]}
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"tdd-quickfix","name":"TDD-entry quickfix pipeline","description":"Quickfix workflow that starts directly at /tdd. For localized misbehaviour with a known failing case; no spec needed.","selectable":true,"selector_hints":["quickfix with known failing test","localized bug; no spec needed","small bundled patch with a clear failing case"],"preconditions":[],"invariants":["commits"],"nodes":[{"id":"tdd","type":"task","skill":"tdd","depends_on":[],"blocks":["simplify"],"can_parallel":false,"needs_user":false,"activeForm":"Running TDD","metadata":{"phase":"tdd"}},{"id":"simplify","type":"task","skill":"simplify","depends_on":["tdd"],"blocks":["security"],"can_parallel":false,"needs_user":false,"activeForm":"Running simplify","metadata":{"phase":"simplify"}},{"id":"security","type":"task","skill":"security","depends_on":["simplify"],"blocks":["integrate"],"can_parallel":false,"needs_user":false,"activeForm":"Running security","metadata":{"phase":"security"}},{"id":"integrate","type":"task","skill":"integrate","depends_on":["security"],"blocks":["document"],"can_parallel":false,"needs_user":false,"activeForm":"Running integrate","metadata":{"phase":"integrate"}},{"id":"document","type":"task","skill":"document","depends_on":["integrate"],"blocks":["archive"],"can_parallel":false,"needs_user":false,"activeForm":"Running document","metadata":{"phase":"document"}},{"id":"archive","type":"task","skill":"archive","depends_on":["document"],"blocks":["memory-flush"],"can_parallel":false,"needs_user":false,"activeForm":"Running archive","metadata":{"phase":"archive"}},{"id":"memory-flush","type":"task","skill":"memory-flush","depends_on":["archive"],"blocks":["grant-commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running memory-flush","metadata":{"phase":"memory-flush"}},{"id":"grant-commit","type":"task","skill":"grant-commit","depends_on":["memory-flush"],"blocks":["changelog"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting commit consent","metadata":{"phase":"grant-commit","needs_user":true}},{"id":"changelog","type":"task","skill":"changelog","depends_on":["grant-commit"],"blocks":["commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running changelog","metadata":{"phase":"changelog"}},{"id":"commit","type":"task","skill":"commit","depends_on":["changelog"],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running commit","metadata":{"phase":"commit"}}]}
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"chore","name":"Chore track","description":"Stripped-down pipeline for changes that need no failing-test-driven code change: documentation edits, configuration tweaks, formatting, dependency bumps with no project code change.","selectable":true,"selector_hints":["documentation edit","governance count refresh","configuration tweak","formatting or typo fix","skill consolidation move"],"preconditions":[],"invariants":["commits","chore"],"nodes":[{"id":"chore","type":"task","skill":"chore","depends_on":[],"blocks":["memory-flush"],"can_parallel":false,"needs_user":false,"activeForm":"Running chore","metadata":{"phase":"chore"}},{"id":"memory-flush","type":"task","skill":"memory-flush","depends_on":["chore"],"blocks":["grant-commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running memory-flush","metadata":{"phase":"memory-flush"}},{"id":"grant-commit","type":"task","skill":"grant-commit","depends_on":["memory-flush"],"blocks":["changelog"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting commit consent","metadata":{"phase":"grant-commit","needs_user":true}},{"id":"changelog","type":"task","skill":"changelog","depends_on":["grant-commit"],"blocks":["commit"],"can_parallel":false,"needs_user":false,"activeForm":"Running changelog","metadata":{"phase":"changelog"}},{"id":"commit","type":"task","skill":"commit","depends_on":["changelog"],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running commit","metadata":{"phase":"commit"}}]}
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"swarm-implementation","name":"Swarm implementation sub-track","description":"Parallel implementation via swarm-plan + approve-swarm + swarm-dispatch. Selected by intake-full's selector node when requires_git and requires_min_components:3 preconditions pass.","selectable":false,"selector_hints":[],"preconditions":[{"name":"requires_git"}],"invariants":["requires_swarm","git_only"],"nodes":[{"id":"swarm-plan","type":"task","skill":"swarm-plan","depends_on":[],"blocks":["approve-swarm"],"can_parallel":false,"needs_user":false,"activeForm":"Running swarm-plan","metadata":{"phase":"swarm-plan"}},{"id":"approve-swarm","type":"task","skill":"approve-swarm","depends_on":["swarm-plan"],"blocks":["swarm-dispatch"],"can_parallel":false,"needs_user":true,"activeForm":"Awaiting swarm approval","metadata":{"phase":"approve-swarm","needs_user":true}},{"id":"swarm-dispatch","type":"task","skill":"swarm-dispatch","depends_on":["approve-swarm"],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running swarm-dispatch","metadata":{"phase":"swarm-dispatch"}}]}
+{"$schema":"./schemas/workflow-track.v1.json","track_id":"tdd-worker-chain","name":"TDD worker-chain sub-track","description":"Solo TDD path. Fallback alternate for intake-full when swarm preconditions fail or the user picks solo explicitly.","selectable":false,"selector_hints":[],"preconditions":[],"invariants":[],"nodes":[{"id":"tdd","type":"task","skill":"tdd","depends_on":[],"blocks":[],"can_parallel":false,"needs_user":false,"activeForm":"Running TDD","metadata":{"phase":"tdd"}}]}

package/src/CLAUDE.template.md

@@ -91,25 +91,19 @@ The 11-phase workflow is the only sanctioned path from request to commit. Phase
 
 **Swarm vs solo at Phase 6.** When the approved spec has fewer than `project.json → swarm.min_tasks_worth_swarming` (default 3) independent components **OR** the project is not a git repository, run `/tdd` solo. Otherwise route through `/swarm-plan` → `/approve-swarm` → `/swarm-dispatch`. In non-git projects the swarm phases are excepted at triage time (see the "Phase 6c and Phase 11 are git-conditional" bullet above), so this decision always resolves to solo — the rule's first clause never fires on a non-git tree, and a user "use swarm" override SHALL be refused with the reason `swarm requires git`.
 
+**Post-§18 amendment (2026-05-21).** Workflow track definitions live in `.claude/workflows.jsonl` per `docs/init/seed.md §18`. The phase-ordering rules and entry-point classifications above remain binding; every Track declared in `workflows.jsonl` SHALL satisfy them plus the additional invariants in seed.md §18.3 (I1..I11). `/triage` reads `workflows.jsonl`, validates each Track against §18, classifies the user's request via LLM reasoning over `name + description + selector_hints`, confirms via `AskUserQuestion`, and materializes the chosen Track's DAG into the TaskList (via `src/cli/track-tasklist-materializer.js`). The 4 canonical tracks shipped in the pristine template are byte-equivalent to this Article's hardcoded templates per spec AC-016. The harness migrates pre-§18 `workflow.json` files (carrying `entry_phase` + no `track_id`) one-shot at preflight via `src/cli/workflow-migrator.js`. `/init-project doctor` (sub-command) detects schema / invariant / mirror drift and offers interactive fixes.
+
 ## Article V — Harness orchestration (MANDATORY SOP)
 
 `/harness` is invokable by both the user (via the slash command) and the model (via `Skill(harness)`). A single `Skill(harness)` invocation **loops internally through every non-gated phase boundary** until the loop hits one of four exit conditions: consent gate, phase-skill failure, integrate-failure-needs-spec-change, or workflow done. The user invokes `/harness` to start a fresh workflow or to resume after a yield. You SHALL suggest `/harness` when a concrete engineering ask crystallizes in conversation; the user decides when to invoke it.
 
-When `/harness` is invoked, you SHALL:
-
-1. **Preflight (once per invocation).** Read `.claude/state/workflow.json` and `.claude/state/harness_state` (if present); read `.claude/state/spec_approvals/`, `swarm_approvals/`, and `commit_consent` to reconcile state.
-2. **Arm the safety net.** Marker FIRST: `echo "<slug>" > .claude/state/.harness_active`. Then write `harness_state` with `{state: "continue", slug, reason: "loop armed; preflight passed"}`. This pair stays in place for the entire loop.
-3. **Enter the loop body.** Each iteration: pick the lowest-id `pending` task whose `blockedBy` list is empty. If no task remains → **EXIT LOOP with DONE**. If the task carries `metadata.needs_user: true` → **EXIT LOOP with YIELD** (surface the gate; do NOT self-approve, simulate approval, or write approval tokens directly). Otherwise invoke the matching phase skill via the Skill tool, mark `completed` on success, append to `workflow.json → completed`, refresh marker+state, and **continue to the next iteration**.
-4. **Exit the loop** on yield/failure/done. Write the matching `harness_state` (`yielded` or `done`) with marker-first ordering, then emit a single terminal message naming what just happened.
-5. **Log every transition** to `.claude/state/harness/<slug>.log`.
-
-**Internal loop atomicity.** Inside the loop, every iteration is one Skill(`<phase>`) invocation plus one marker refresh plus one `harness_state` refresh — all happening within the same `Skill(harness)` call, **without emitting an intermediate terminal message**. Intermediate terminal messages would invite the model to stop and trigger the safety net unnecessarily. The marker op is FIRST (`echo "<slug>" > .claude/state/.harness_active` on `continue`-refresh, `rm -f .claude/state/.harness_active` on exit with `yielded`/`done`), then `harness_state` is written, then (only on loop exit) the terminal message is emitted.
-
-**The safety net.** The `harness_continuation` Stop hook (Article VIII) re-fires `Skill(harness)` only when the loop exited mid-flow — i.e., on-disk state is `{state: "continue"}` with the marker present, and `stop_hook_active` is absent on the Stop payload. In normal operation (loop runs to gate/failure/done), the hook sees `state != continue` or marker absent and stays silent. The hook is a defense-in-depth signal, not the primary driver: a healthy `Skill(harness)` invocation never depends on it. The hook is also bounded to one block per turn by Claude Code's `stop_hook_active` semantics, so it cannot itself drive multi-phase chaining.
-
-**Resume after yield (auto).** After yielding at a consent gate, the harness skill writes `state: yielded` and removes `.harness_active`. The user runs the consent slash command in their next prompt; `consent_gate_grant` writes the gate marker (outside Claude's tool boundary), the command body writes the consent token, and the `harness_continuation` Stop hook detects fresh consent (rung 4: `workflow.json` present + `state=yielded` + a consent-token mtime newer than `harness_state`). The hook emits `{decision:"block"}`, and `Skill(harness)` is re-invoked in the same turn. The next invocation re-enters preflight, finds the gate token on disk, marks the gate task `completed`, and re-enters the loop. The user does not type `/harness` to resume.
+**Operational SOP lives in `.claude/skills/harness/SKILL.md`** — preflight, marker-first state writes, loop body iteration, safety-net interaction with `harness_continuation`, resume-after-yield mechanics, and task discipline. This Article declares the constitutional invariants the SOP must satisfy:
 
-**Task discipline (autonomous progression).** `/triage` seeds a `TaskCreate`-backed checklist covering every non-excepted phase plus consent-gate placeholders (the placeholders carry `metadata.needs_user: true`). Inside the loop you SHALL: (a) call `TaskList` first; if empty, re-seed from `workflow.json → completed + exceptions + entry_phase` using the canonical templates in `triage`'s SKILL.md; (b) `TaskUpdate` the next pending non-blocked task to `in_progress` before invoking its phase skill; (c) `TaskUpdate` to `completed` only after the phase skill returns success; (d) when the next pending task carries `needs_user: true`, EXIT LOOP with YIELD — never invoke a skill for that task. The TaskList is session-bound; `workflow.json → completed` is the durable truth, and re-seeding always reconciles to it.
+- The loop SHALL exit on one of four conditions: consent gate (yield), phase-skill failure (yield), integrate-failure-needs-spec-change (yield), or workflow done.
+- You SHALL NOT self-approve at any consent gate. You SHALL NOT simulate approval. You SHALL NOT write approval tokens directly.
+- Every successful phase invocation SHALL `TaskUpdate` to `completed`, append the phase name to `workflow.json → completed`, and refresh marker + `harness_state` (marker FIRST) before continuing.
+- `workflow.json → completed` is the durable truth across sessions; the TaskList is session-bound. When they disagree, trust `workflow.json` and re-seed.
+- The `harness_continuation` Stop hook is a safety net, not the primary driver. A healthy `Skill(harness)` invocation runs to a clean exit on its own; the hook re-fires only when the loop was interrupted mid-flow with `state: "continue"` + marker present.
 
 **Integrate-failure decision tree.** When `/integrate` fails inside the loop, you SHALL classify:
 

package/src/cli/install.js

@@ -10,7 +10,11 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(__dirname, '../..');
 const NPMRC_TEMPLATE_PATH = join(PACKAGE_ROOT, 'src/.npmrc.template');
 
-export const NEVER_TOUCH = Object.freeze(['.claude/project.json']);
+export const NEVER_TOUCH = Object.freeze([
+  '.claude/project.json',
+  '.claude/workflows.jsonl',
+  '.claude/schemas/workflow-track.v1.json',
+]);
 export const SPECIAL_MERGE = Object.freeze(['.mcp.json']);
 // The shipped manifest now lives at `.claude/manifest.json` (inside the
 // template's .claude/ subtree), so the recursive cp drops it at the correct

package/src/cli/merge.js

@@ -4,7 +4,7 @@ import { hashFile, saveManifest } from './manifest.js';
 import { deepMergeMcpServers } from './mcp.js';
 import { NEVER_TOUCH, SPECIAL_MERGE } from './install.js';
 import { pathExists } from './util.js';
-import { dispatchByTier, NoBaseError } from './upgrade-tiers.js';
+import { dispatchByTier, NoBaseError, canRecoverBase } from './upgrade-tiers.js';
 
 export const ACTION_KINDS = Object.freeze({
   ADD: 'ADD',
@@ -21,6 +21,26 @@ export const ACTION_KINDS = Object.freeze({
   SEMANTIC_MERGE_STAGED: 'SEMANTIC_MERGE_STAGED',
 });
 
+// User-facing labels for each ACTION_KIND. Surfaced in the per-file upgrade
+// report (TTY via `tui/upgrade.js`, non-TTY via `bin/cli.js dispatchUpgrade`).
+// Kept centralized so both paths render identically.
+export const ACTION_LABELS = Object.freeze({
+  ADD: 'add',
+  OVERWRITE: 'update',
+  NOOP: 'unchanged',
+  SKIP_CUSTOMIZED: 'kept yours',
+  PRUNE: 'removed (upstream)',
+  PRUNE_SKIPPED_CUSTOMIZED: 'kept yours (upstream removed)',
+  NEVER_TOUCH_PRESERVE: 'kept yours (never-touch)',
+  NEVER_TOUCH_ADD: 'add (never-touch)',
+  SPECIAL_MERGE: 'merged (.mcp.json deep-merge)',
+  MECHANICAL_MERGE_CLEAN: 'merged cleanly',
+  MECHANICAL_MERGE_CONFLICTED: 'merged with conflicts — resolve manually',
+  SEMANTIC_MERGE_STAGED: 'staged for /upgrade-project',
+});
+
+export const ACTION_LABEL_WIDTH = Math.max(...Object.values(ACTION_LABELS).map((s) => s.length));
+
 async function copyFile(src, dst) {
   await mkdir(dirname(dst), { recursive: true });
   await cp(src, dst, { force: true });
@@ -143,6 +163,13 @@ async function dispatchCustomized({ rel, newEntry, tierCtx, dryRun, onSkipCustom
   const tier = readTierFromEntry(newEntry);
   if (tier === 'MECHANICAL' || tier === 'SEMANTIC') {
     if (dryRun) {
+      // When BASE recovery would fail (legacy manifest with no cache hit, no
+      // npm fallback), the real run will fall through to the binary prompt.
+      // Surface this file as SKIP_CUSTOMIZED at dry-run time so the TUI
+      // collects a user choice up front instead of silently keep-mine'ing it.
+      if (!canRecoverBase(rel, tierCtx.baseline_version, tierCtx.target)) {
+        return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: 'BASE unrecoverable; will prompt user' };
+      }
       return { kind: tier === 'MECHANICAL' ? ACTION_KINDS.MECHANICAL_MERGE_CLEAN : ACTION_KINDS.SEMANTIC_MERGE_STAGED, path: rel, reason: 'dry-run: tier dispatch deferred' };
     }
     try {

package/src/cli/track-tasklist-materializer.js

@@ -0,0 +1,223 @@
+// Foundation — translate a workflows.jsonl Track record into a canonical
+// TaskList shape. Used by triage at workflow-seed time AND by the
+// byte-equivalent-migration tests (compared to golden fixtures).
+//
+// The returned shape is ordinal-positioned (1-indexed `ord`); `blockedBy`
+// references predecessor ordinals (NOT session task_ids). The runtime
+// caller (triage skill body, harness re-seed) translates ordinals to
+// TaskCreate-assigned task_ids at materialization time.
+//
+// Selector nodes resolve to their default alternate (the first alternate
+// with empty preconditions). Sub-track refs read the originating track's
+// `_allTracks` Map (attached by the validator) to find the target track.
+
+export function materializeTaskList(track, { slug, ctx } = {}) {
+  if (!slug) {
+    throw new Error('materializeTaskList requires a slug option (used for <slug> substitution in subjects/activeForms).');
+  }
+  const emitter = createEmitter(slug, track._allTracks ?? new Map(), ctx);
+  emitNodes(track.nodes, emitter);
+  return finalize(emitter);
+}
+
+function createEmitter(slug, allTracks, ctx) {
+  return {
+    slug,
+    allTracks,
+    ctx: ctx ?? null,
+    tasks: [],
+    idToOrd: new Map(),
+  };
+}
+
+function emitNodes(nodes, emitter) {
+  for (const node of nodes) {
+    emitNode(node, emitter);
+  }
+}
+
+function emitNode(node, emitter) {
+  if (node.type === 'selector') {
+    const chosen = evaluateAlternates(node, emitter.ctx);
+    if (!chosen) {
+      throw new Error(
+        `Selector node '${node.id}' has no alternate whose preconditions pass against the provided context. ` +
+        `Either provide a ctx that satisfies one alternate's preconditions, or declare an alternate with empty preconditions (unconditional default).`
+      );
+    }
+    emitAlternate(chosen, node, emitter);
+    return;
+  }
+  if (node.sub_track) {
+    expandSubTrack(node.sub_track, node, emitter);
+    return;
+  }
+  recordTask(node, emitter, []);
+}
+
+function emitAlternate(alternate, parentNode, emitter) {
+  if (alternate.sub_track) {
+    expandSubTrack(alternate.sub_track, parentNode, emitter);
+    return;
+  }
+  if (alternate.skill) {
+    const synthetic = {
+      id: parentNode.id,
+      type: 'task',
+      skill: alternate.skill,
+      depends_on: parentNode.depends_on || [],
+      blocks: parentNode.blocks || [],
+      can_parallel: false,
+      needs_user: false,
+    };
+    recordTask(synthetic, emitter, []);
+    return;
+  }
+  throw new Error(`Alternate on selector '${parentNode.id}' has neither skill nor sub_track.`);
+}
+
+function expandSubTrack(subTrackId, parentNode, emitter) {
+  const sub = emitter.allTracks.get(subTrackId);
+  if (!sub) {
+    throw new Error(`sub_track '${subTrackId}' referenced by node '${parentNode.id}' not found in _allTracks.`);
+  }
+  const parentDepends = parentNode.depends_on || [];
+  const beforeOrd = emitter.tasks.length;
+  for (const subNode of sub.nodes) {
+    const isEntry = !subNode.depends_on || subNode.depends_on.length === 0;
+    const effectiveDepends = isEntry ? parentDepends : subNode.depends_on;
+    recordTask(subNode, emitter, effectiveDepends);
+    if (emitter.tasks.length === beforeOrd + 1) {
+      emitter.idToOrd.set(parentNode.id, emitter.tasks[beforeOrd].ord);
+    }
+  }
+}
+
+function recordTask(node, emitter, effectiveDepends) {
+  const ord = emitter.tasks.length + 1;
+  emitter.idToOrd.set(node.id, ord);
+  emitter.tasks.push({
+    ord,
+    subject: deriveSubject(node, emitter.slug),
+    activeForm: deriveActiveForm(node),
+    metadata: deriveMetadata(node),
+    needs_user: !!node.needs_user,
+    can_parallel: !!node.can_parallel,
+    _dependsOnIds: effectiveDepends.length > 0 ? effectiveDepends : (node.depends_on || []),
+  });
+}
+
+function finalize(emitter) {
+  const out = [];
+  for (const task of emitter.tasks) {
+    const blockedBy = task._dependsOnIds
+      .map((id) => emitter.idToOrd.get(id))
+      .filter((ord) => typeof ord === 'number');
+    out.push({
+      ord: task.ord,
+      subject: task.subject,
+      activeForm: task.activeForm,
+      metadata: task.metadata,
+      needs_user: task.needs_user,
+      can_parallel: task.can_parallel,
+      blockedBy,
+    });
+  }
+  return out;
+}
+
+// evaluateAlternates walks the selector node's alternates in declaration order
+// and returns the first one whose preconditions all pass against ctx. When ctx
+// is null/undefined, only alternates with empty preconditions are eligible
+// (preserves the materialize-time-only default-fallback behavior used by tests
+// that don't pass a ctx — e.g., the byte-equivalent fixture comparison). When
+// ctx is provided, predicates evaluate against its fields:
+//   { isGit: bool, componentCount: int, userOverride: string|null,
+//     completed: string[], knownSkills: Set<string> }
+// Any predicate whose required field is absent in ctx evaluates false.
+function evaluateAlternates(selectorNode, ctx) {
+  const alts = selectorNode.alternates || [];
+  for (const alt of alts) {
+    const preconditions = Array.isArray(alt.preconditions) ? alt.preconditions : [];
+    if (preconditions.every((p) => evaluatePredicate(p, ctx))) {
+      return alt;
+    }
+  }
+  return null;
+}
+
+function evaluatePredicate(pred, ctx) {
+  if (!ctx) return false;
+  switch (pred.name) {
+    case 'requires_git':
+      return ctx.isGit === true;
+    case 'requires_user_override':
+      return typeof ctx.userOverride === 'string' && ctx.userOverride === pred.argument;
+    case 'requires_min_components': {
+      const n = parseInt(pred.argument, 10);
+      return Number.isFinite(n) && typeof ctx.componentCount === 'number' && ctx.componentCount >= n;
+    }
+    case 'requires_phase_completed':
+      return Array.isArray(ctx.completed) && ctx.completed.includes(pred.argument);
+    case 'requires_skill_present':
+      return ctx.knownSkills instanceof Set && ctx.knownSkills.has(pred.argument);
+    default:
+      return false;
+  }
+}
+
+const ACTIVE_FORM_OVERRIDES = Object.freeze({
+  tdd: 'Running TDD',
+  intake: 'Running intake',
+  scout: 'Running scout',
+  research: 'Running research',
+  spec: 'Running spec',
+  simplify: 'Running simplify',
+  security: 'Running security',
+  integrate: 'Running integrate',
+  document: 'Running document',
+  archive: 'Running archive',
+  'memory-flush': 'Running memory-flush',
+  changelog: 'Running changelog',
+  commit: 'Running commit',
+  chore: 'Running chore',
+  'swarm-plan': 'Running swarm-plan',
+  'swarm-dispatch': 'Running swarm-dispatch',
+});
+
+const CONSENT_GATE_SUBJECTS = Object.freeze({
+  'approve-spec': 'Wait for /approve-spec <path>',
+  'grant-commit': 'Wait for /grant-commit',
+  'approve-swarm': 'Wait for /approve-swarm <slug>',
+});
+
+const CONSENT_GATE_ACTIVE_FORMS = Object.freeze({
+  'approve-spec': 'Awaiting spec approval',
+  'grant-commit': 'Awaiting commit consent',
+  'approve-swarm': 'Awaiting swarm approval',
+});
+
+function deriveSubject(node, slug) {
+  if (node.needs_user) {
+    return CONSENT_GATE_SUBJECTS[node.id] ?? `Wait for /${node.id}`;
+  }
+  const skill = node.skill || node.id;
+  return `Run /${skill} for ${slug}`;
+}
+
+function deriveActiveForm(node) {
+  if (node.activeForm) return node.activeForm;
+  if (node.needs_user) {
+    return CONSENT_GATE_ACTIVE_FORMS[node.id] ?? `Awaiting /${node.id}`;
+  }
+  const skill = node.skill || node.id;
+  return ACTIVE_FORM_OVERRIDES[skill] ?? `Running ${skill}`;
+}
+
+function deriveMetadata(node) {
+  const phase = node.metadata?.phase ?? node.skill ?? node.id;
+  if (node.needs_user) {
+    return { phase, needs_user: true };
+  }
+  return { phase };
+}

package/src/cli/tui/upgrade.js

@@ -12,10 +12,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 { findPendingStage, formatStageTimestamp } from '../upgrade-tiers.js';
 import { renderUnifiedDiff } from '../diff-render.js';
 import { renderBrandStrip } from './splash.js';
 
@@ -58,7 +58,7 @@ 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 });
@@ -73,7 +73,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 +85,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}`);
@@ -98,14 +100,18 @@ export async function run({ target, opts = {}, prompts = clackModule } = {}) {
 
   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;
 }
 

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;

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 };
+}