@friedbotstudio/create-baseline 0.6.0 → 0.8.0

package/obj/template/docs/init/seed.md

@@ -247,7 +247,7 @@ Each vendored shared global ships with its own `LICENSE` + `NOTICE` alongside th
 
 - `chore` — for tasks with no failing-test-driven code change (documentation, governance counts, vendored-skill content updates, configuration, formatting, typo fixes, dependency bumps, skill consolidations). Skips `/scenario` and `/implement` — there is nothing to drive with a failing test. Runs the edits directly, then conditionally invokes `simplify` / `integrate` / `document` based on what the diff touches (each has explicit triggers in the chore skill body). `verify`, `archive`, and `/grant-commit` + `/commit` always run. Chore is a stripped-down pipeline, **not** a bypass — silent skips of triggered conditional phases are forbidden; the end-of-chore summary documents every skip rationale. Tasks that need a real failing test route to `/tdd` or higher instead.
 
-### §4.4 Commands (4) — structurally user-only
+### §4.4 Commands (6) — structurally user-only
 
 Files at `.claude/commands/<name>.md`. Commands differ from skills in exactly one way: **Claude cannot invoke them via the Skill tool.** A command is a button only a human can press.
 
@@ -258,8 +258,9 @@ Files at `.claude/commands/<name>.md`. Commands differ from skills in exactly on
 | `grant-commit` | Opens a 5-minute consent window for `git commit` on a protected branch. Writes `.claude/state/commit_consent`. Enforced by `git_commit_guard`. |
 | `grant-push` | Opens a 5-minute consent window for `git push` on a protected branch. Writes `.claude/state/push_consent`. Enforced by `git_commit_guard`. Not a workflow-phase gate — a runtime consent for the branch-aware policy (§11). |
 | `init-project` | One-time bootstrap. Detects stack, proposes `.claude/project.json` (test cmd, lint cmd, TDD globs, destructive patterns, artifact required sections, swarm config). Flips `configured: true`. |
+| `init-project-doctor` | Detects baseline drift — missing/invalid `.claude/workflows.jsonl`, schema/invariant violations, four-way Article IV / §18 mirror drift, and (advisory) shipped-tooling files placed outside `.claude/`. Interactive: presents each violation via `AskUserQuestion` and applies the named fix on confirmation. |
 
-**Adding a sixth command requires answering yes to both:** "does a human need to press this?" and "is 'user-only via frontmatter flag' too weak a guarantee?" Otherwise make it a skill.
+**Adding a seventh command requires answering yes to both:** "does a human need to press this?" and "is 'user-only via frontmatter flag' too weak a guarantee?" Otherwise make it a skill.
 
 ### §4.5 MCP servers (3)
 
@@ -338,7 +339,7 @@ Phases are fixed ordering; `/triage` picks the entry and may mark phases as exce
 
 ## §6 — Consent model
 
-**Four consent gates + one bootstrap gate.** All are slash commands, not skills. Commands live in `.claude/commands/`; Claude cannot invoke them via the Skill tool. The guarantee is structural (file location), not flag-based. Three of the four gates are workflow-phase gates (A: `/approve-spec`, B: `/approve-swarm`, C: `/grant-commit`); the fourth (`/grant-push`) is a Bash-time consent for the branch-aware push policy in §11.
+**Four consent gates + one bootstrap + one doctor.** All are slash commands, not skills. Commands live in `.claude/commands/`; Claude cannot invoke them via the Skill tool. The guarantee is structural (file location), not flag-based. Three of the four gates are workflow-phase gates (A: `/approve-spec`, B: `/approve-swarm`, C: `/grant-commit`); the fourth (`/grant-push`) is a Bash-time consent for the branch-aware push policy in §11. The bootstrap is `/init-project`; the doctor is `/init-project doctor` (drift detector + repairer for `.claude/workflows.jsonl` + the §18 / Article IV four-way mirror; see §18.7).
 
 | Gate | When it fires | Unlocks |
 |---|---|---|
@@ -598,3 +599,147 @@ The audit at `.claude/skills/audit-baseline/audit.sh` consumes `manifest.owners.
 The audit also verifies constitutional citation: CLAUDE.md SHALL contain the literal string "Article XI" and a reference to the manifest, and `docs/init/seed.md` SHALL contain "§17" and a manifest reference. Missing citations trigger FAIL with `CLAUDE.md missing Article XI citation` or `seed.md missing §17 citation`.
 
 This provenance system is intentionally minimal: the manifest tracks shipped-file hashes; the frontmatter declares per-skill ownership; the audit reconciles the two against on-disk reality. Cryptographic supply-chain attestation, signed lock files, and per-skill aggregate merkle hashes are non-goals; the per-file `manifest.files` map already covers every file in every skill directory. A future `npx @friedbotstudio/create-baseline upgrade` subcommand will consume `manifest.owners.skills` + `manifest.files` to safely re-overlay baseline-owned files while leaving user-added skills and locally-customized baseline skills untouched — that subcommand is out of scope here.
+
+---
+
+## §18 — Workflow definitions and Article IV invariants
+
+### 18.1 Source of truth
+
+`.claude/workflows.jsonl` is the canonical source for every workflow this baseline can execute. The file holds one Track record per line (JSONL). It is project-owned and `NEVER_TOUCH` (declared in `src/cli/install.js:NEVER_TOUCH` and `scripts/build-manifest.mjs:NEVER_TOUCH_PATHS`); baseline upgrades preserve user customizations verbatim via `NEVER_TOUCH_PRESERVE`. The shipped baseline overlays the pristine 6-track set from `src/.claude/workflows.template.jsonl` onto fresh installs via `scripts/build-template.sh` Stage 2; existing installs are not touched. The JSON Schema document at `.claude/schemas/workflow-track.v1.json` is referenced by `Track.$schema` and is itself `NEVER_TOUCH`.
+
+`workflows.jsonl` supersedes the hardcoded triage templates (intake-full / spec-entry / tdd-quickfix / chore). Triage reads `workflows.jsonl` at seed time, validates each Track, classifies the user's request, and materializes the chosen Track's DAG into the TaskList. The canonical four tracks shipped in the pristine template are byte-equivalent to the pre-§18 hardcoded templates per spec AC-016 (`tests/byte-equivalent-migration.test.mjs`).
+
+### 18.2 Track schema
+
+A **Track** record has this shape (full definition in `.claude/schemas/workflow-track.v1.json`):
+
+```jsonc
+{
+  "$schema": "./schemas/workflow-track.v1.json",
+  "track_id": "<unique-across-file>",
+  "name": "<short label>",
+  "description": "<paragraph; read by the LLM classifier>",
+  "selectable": true,            // false = sub-track only (referenced via sub_track)
+  "selector_hints": ["<descriptive phrase>", ...],
+  "preconditions": [{"name": "<predicate>", "argument": "<opt>"}, ...],
+  "invariants": ["commits", "requires_spec", ...],
+  "nodes": [Node, ...]
+}
+```
+
+A **Node** is either a `task` (skill invocation or sub-track expansion) or a `selector` (picks one of multiple alternates at runtime):
+
+```jsonc
+{
+  "id": "<unique-within-track>",
+  "type": "task" | "selector",
+  // type=task → exactly one of:
+  "skill": "<skill-or-command-name>",
+  "sub_track": "<another-track_id>",
+  // type=selector → required:
+  "alternates": [Alternate, ...],
+  // shared:
+  "input": "<opt; passed to the skill at invocation>",
+  "invocation_prompt": "<opt; declared-now/used-later — v2 Handlebars+LLM>",
+  "output": "<opt; informational artifact path>",
+  "output_formatter_prompt": "<opt; declared-now/used-later>",
+  "depends_on": ["<predecessor node id>", ...],
+  "blocks": ["<successor node id>", ...],
+  "can_parallel": false,         // true: peers at same dep level dispatch concurrently
+  "needs_user": false,           // true: consent gate; harness yields
+  "activeForm": "<TaskList spinner text>",
+  "metadata": {"phase": "<...>"}
+}
+```
+
+An **Alternate** (inside a selector node):
+
+```jsonc
+{
+  "skill": "<skill-name>",       // XOR with sub_track
+  "sub_track": "<track_id>",     // XOR with skill
+  "preconditions": [Predicate, ...],
+  "description": "<rationale>"
+}
+```
+
+A **Predicate** (track-level and alternate-level):
+
+```jsonc
+{
+  "name": "<v1-vocabulary>",
+  "argument": "<opt; e.g., '3' for min_components>"
+}
+```
+
+### 18.3 Article IV invariants (I1..I11)
+
+Every Track in `workflows.jsonl` SHALL satisfy these invariants. Validation runs at three points: install/upgrade time (audit-baseline), triage time (LLM-driven selector), and harness time (per-node before dispatch).
+
+- **I1.** Unique `track_id` across the file.
+- **I2.** Unique `node.id` within a track.
+- **I3.** `type=task` nodes carry exactly one of `{skill, sub_track}`. `type=selector` nodes carry non-empty `alternates[]`.
+- **I4.** Every `depends_on` and `blocks` reference resolves to a `node.id` in the same track.
+- **I5.** The dependency DAG is acyclic.
+- **I6.** Tracks declaring the `commits` invariant SHALL include a `needs_user: true` `grant-commit` node ordered before the node with `skill: "commit"`.
+- **I7.** Every `sub_track` reference resolves to a Track with `selectable: false`.
+- **I8.** Every `skill:` reference resolves to a known invokable — skill in `EXPECTED_SKILLS ∪ project.json additions.skills`, OR consent-gate command in `.claude/commands/` (e.g., `approve-spec`, `grant-commit`, `approve-swarm`).
+- **I9.** `needs_user: true` nodes appear in dependency order before any node that depends on their consent.
+- **I10.** A selector node's alternates SHALL share the same shape (all skill, or all sub_track) — they're interchangeable in the DAG.
+- **I11.** Every `Predicate.name` resolves to a known v1 predicate (see §18.4).
+
+### 18.4 Predicate vocabulary (v1)
+
+The closed set of declarative predicates that may appear in Track or Alternate `preconditions[]`:
+
+| Predicate | Argument | Evaluates true when |
+|---|---|---|
+| `requires_git` | — | `git rev-parse --is-inside-work-tree` exits 0 at the project root. |
+| `requires_user_override` | `<value>` | The user explicitly named this alternate in conversation (e.g., "use solo"). |
+| `requires_min_components` | `<int>` | The approved spec has at least N C4 Components. |
+| `requires_phase_completed` | `<phase>` | The named phase appears in `workflow.json → completed`. |
+| `requires_skill_present` | `<skill_id>` | The named skill exists in `EXPECTED_SKILLS ∪ additions.skills`. |
+
+Adding a new predicate is a constitutional change: update this section, update `src/cli/workflows-validator-predicates.js`, and update the corresponding seed.template.md mirror.
+
+### 18.5 `invocation_prompt` / `output_formatter_prompt` — declared, deferred
+
+Both fields are part of the v1 Node schema and validated at parse time. They are **not actuated in v1** — the harness ignores them. They are declared now to lock the schema shape so future Track records can carry them without a schema bump. The v2 actuation plan: Handlebars-style templates with LLM interpolation, allowing per-track UX customization of the invocation phrasing and the post-skill output formatting. Until v2 ships, populating these fields is allowed but inert.
+
+### 18.6 Migration from pre-§18 workflow.json
+
+An in-flight `.claude/state/workflow.json` written by a pre-§18 baseline (carries `entry_phase` field, no `track_id`) is one-shot-migrated by the harness preflight before the workflow loads. The canonical map:
+
+| `entry_phase` (pre-§18) | `track_id` (post-§18) |
+|---|---|
+| `intake` | `intake-full` |
+| `spec` | `spec-entry` |
+| `tdd` | `tdd-quickfix` |
+| `chore` | `chore` |
+
+`completed[]` is remapped from phase names to node ids; the canonical tracks are designed so most phase names equal the corresponding node id (identity remap), with the exception of selector wrappers (e.g., `implementation` in intake-full wraps the swarm-vs-tdd selection). The migrator initializes `skipped_alternates: []` and refreshes `updated_at`. Idempotent: re-running on an already-migrated workflow.json is a no-op. Unmapped `entry_phase` halts with a named error; the user restarts via `/triage`.
+
+Migrator implementation: `src/cli/workflow-migrator.js` exports `migrateWorkflowJsonInPlace(filePath)`.
+
+### 18.7 Lifecycle: install, upgrade, doctor
+
+- **Fresh install.** `scripts/build-template.sh` overlays `src/.claude/workflows.template.jsonl` → `obj/template/.claude/workflows.jsonl` at Stage 2, and the pristine schemas/ directory bulk-rsyncs at Stage 1. The CLI install copies both into the consumer target. Result: every fresh install has `<target>/.claude/workflows.jsonl` with the canonical 4 selectable + 2 sub-track set.
+
+- **Upgrade.** Both `.claude/workflows.jsonl` and `.claude/schemas/workflow-track.v1.json` are `NEVER_TOUCH`. The merge flow returns `NEVER_TOUCH_PRESERVE` for them on every upgrade; user customizations (added tracks, modified nodes, per-project additions like `cli-copy-review`) survive verbatim.
+
+- **Doctor.** `/init-project doctor` (new sub-command) detects drift: missing `workflows.jsonl`, schema/invariant violations, four-way mirror drift between seed.md §18 / src/seed.template.md §18 / CLAUDE.md Article IV / src/CLAUDE.template.md Article IV, and (advisory) shipped-tooling files placed outside `.claude/` per the convention codified at §3.
+
+### 18.8 Cross-references
+
+- `CLAUDE.md Article IV` — phase-ordering rules; binding on every commit-producing track.
+- `CLAUDE.md Article VII` — git rules; relevant to the `requires_git` precondition.
+- `seed.md §3` — directory structure convention (tooling lives under `.claude/`).
+- `seed.md §17` — skill provenance (separate concern; workflows.jsonl is project-owned, not baseline-owned).
+- `.claude/workflows.jsonl` — this project's live tracks.
+- `.claude/schemas/workflow-track.v1.json` — JSON Schema referenced by `Track.$schema`.
+- `src/cli/workflows-validator.js` — validator orchestration.
+- `src/cli/workflows-validator-invariants.js` — invariant checks I1–I11.
+- `src/cli/workflows-validator-predicates.js` — predicate vocabulary.
+- `src/cli/workflow-migrator.js` — pre-§18 → post-§18 migrator.
+- `src/cli/track-tasklist-materializer.js` — Track → TaskList shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@friedbotstudio/create-baseline",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Node CLI scaffolder that materializes the Claude Code baseline (hooks, skills, commands, MCP servers, governance docs) into a target project, with branded interactive install / upgrade / doctor flows. Run via `npx @friedbotstudio/create-baseline <target>`.",
   "type": "module",
   "bin": {

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

@@ -1,10 +1,10 @@
-import { cp, mkdir, unlink } from 'node:fs/promises';
+import { cp, mkdir, readFile, unlink } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 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, writeStageBaseless } 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,29 +163,46 @@ 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 {
       return await dispatchByTier(rel, tier, tierCtx);
     } catch (err) {
       if (err instanceof NoBaseError) {
-        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err });
+        return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx, err });
       }
       throw err;
     }
   }
-  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath });
+  return fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx });
 }
 
-async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, err = null }) {
+async function fallbackToBinaryPrompt({ rel, onSkipCustomized, dryRun, tplPath, tgtPath, tierCtx, err = null }) {
   const choice = onSkipCustomized ? await onSkipCustomized(rel) : 'keep-mine';
   if (choice === 'take-theirs') {
     if (!dryRun) await copyFile(tplPath, tgtPath);
     return { kind: ACTION_KINDS.OVERWRITE, path: rel, reason: err ? `BASE recovery failed (${err.kind}); user chose take-theirs` : 'customized file; user chose take-theirs' };
   }
+  if (choice === 'merge') {
+    if (!dryRun) await stageBaselessMerge({ rel, tplPath, tgtPath, tierCtx });
+    return { kind: ACTION_KINDS.SEMANTIC_MERGE_STAGED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); staged for two-way merge` : 'tier-1 customized; staged for two-way merge' };
+  }
   return { kind: ACTION_KINDS.SKIP_CUSTOMIZED, path: rel, reason: err ? `BASE recovery failed (${err.kind}); preserved` : 'target customized since last install' };
 }
 
+async function stageBaselessMerge({ rel, tplPath, tgtPath, tierCtx }) {
+  const incomingBuf = await readFile(tplPath);
+  const localBuf = await readFile(tgtPath);
+  await writeStageBaseless(tierCtx, rel, incomingBuf, localBuf);
+}
+
 function computeExitCode(actions) {
   let code = 0;
   for (const a of actions) {

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