@friedbotstudio/create-baseline 0.5.0 → 0.7.0

package/README.md

@@ -41,7 +41,7 @@ A discipline layer for Claude Code. Hooks at every tool boundary, a workflow tha
 
 ## What this is
 
-The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **37 skills** organised into nine categories, **1 subagent** for parallel work in isolated worktrees, an **11-phase workflow** from intake to commit, and **3 user-typed consent gates** that Claude cannot forge.
+The Claude Code Baseline is a repository overlay shipped via `npx @friedbotstudio/create-baseline ./target`. It installs **22 hooks** at Claude's tool boundaries, **38 skills** organised into ten categories, **1 subagent** for parallel work in isolated worktrees, **4 canonical workflow tracks** declared in `.claude/workflows.jsonl` (where `intake-full` runs 11 nodes from intake to commit), and **3 user-typed consent gates** that Claude cannot forge.
 
 Every soft engineering rule a team usually repeats every session — *don't push, don't `--amend`, don't self-approve specs, don't skip phases, don't mock internal modules* — becomes a structural guarantee because the hooks run **outside Claude's tool boundary**. Claude cannot disable a hook with a flag, cannot write a consent marker, cannot reorder the phases without an explicit exception that triage records on disk.
 
@@ -62,9 +62,9 @@ A team that installs the baseline stops typing *"don't push, don't `--amend`, do
 | What | Count | Where it lives |
 |---|---:|---|
 | **Hooks** at PreToolUse / PostToolUse / SessionStart / Stop / PreCompact / UserPromptSubmit | 22 | `.claude/hooks/` |
-| **Skills** across artifact drafting, workflow phases, phase workers, spec helpers, orchestration, memory, audit, alternate tracks, and shared globals | 36 | `.claude/skills/` |
+| **Skills** across artifact drafting, workflow phases, phase workers, spec helpers, orchestration, memory, audit, alternate tracks, shared globals, and maintenance | 38 | `.claude/skills/` |
 | **Subagent** — `swarm-worker`, executes pre-decided recipes inside isolated git worktrees | 1 | `.claude/agents/` |
-| **Workflow phases** — intake → scout → research → spec → tdd → simplify → security → integrate → document → archive → memory-flush → commit | 11 | enforced by `track_guard` |
+| **Workflow tracks** declared in `.claude/workflows.jsonl`. Canonical set: `intake-full` (11 nodes), `spec-entry`, `tdd-quickfix`, `chore`. Two sub-tracks (`swarm-implementation`, `tdd-worker-chain`) are referenced by selector nodes inside the canonical set. | 4 selectable + 2 sub | `.claude/workflows.jsonl`, enforced by `track_guard` |
 | **Consent gates** — `/approve-spec`, `/approve-swarm`, `/grant-commit`. User-typed; structurally un-invokable by Claude | 3 | `consent_gate_grant` UserPromptSubmit hook |
 | **MCP servers** declared in `.mcp.json` — `context7` (third-party API docs), `plantuml` (diagram render), `playwright` (cross-engine smoke) | 3 | `.mcp.json` |
 
@@ -92,15 +92,19 @@ npx @friedbotstudio/create-baseline ./your-project
 npx @friedbotstudio/create-baseline ./your-project
 
 # Force-overwrite an existing install (interactive — type 'overwrite')
-npx @friedbotstudio/create-baseline ./your-project --overwrite
+npx @friedbotstudio/create-baseline ./your-project --force
 
 # Upgrade an existing install against a newer baseline version.
-# In a TTY, each customised file becomes a keep-mine / take-theirs / abort
-# prompt. In CI / piped stdout, reproduces the prior --merge behaviour:
+# In a TTY, each tier-1 customised file becomes a keep-mine / take-theirs / abort
+# prompt; tier-2 files auto-merge via `git merge-file --diff3`; tier-3 files
+# stage for the /upgrade-project Claude Code skill to reconcile. In CI / piped
+# stdout, every per-file action is reported with a user-facing label:
 #   - adds new baseline files
 #   - refreshes baseline files the user has not touched
-#   - preserves user-customised files (exit 3 if any)
-#   - removes baseline files the upstream removed (only if untouched locally)
+#   - keeps customised files (exit 3 if any preserved)
+#   - removes baseline files removed upstream that the user had not touched
+#   - exit 4 if a mechanical merge produced conflict markers
+#   - exit 5 if any tier-3 file was staged for /upgrade-project
 npx @friedbotstudio/create-baseline upgrade ./your-project
 
 # Preview without writing anything
@@ -158,7 +162,7 @@ The three workflow-phase consent gates pause the workflow until you type the cor
 
 - **`/approve-spec <slug>`** — after the spec phase, before any code is written
 - **`/approve-swarm <slug>`** — after `/swarm-plan`, before parallel dispatch
-- **`/grant-commit`** — after `/archive`, before the commit lands
+- **`/grant-commit`** — after `/archive` and `/memory-flush`, before the commit lands
 
 A fourth consent gate sits outside the phase pipeline:
 
@@ -172,7 +176,7 @@ The 22 hooks declared in `.claude/settings.json` fire at every Claude tool bound
 
 The architectural rule is simple: **decisions live in main context; subagents only execute pre-decided recipes**. The baseline ships exactly one subagent — `swarm-worker` — and its only sanctioned use is parallel dispatch of fully-specified recipes inside isolated git worktrees during `/swarm-dispatch`. Every other capability that might have been a subagent (code authoring, scenario design, scouting, security review, prose writing, UI design) lives instead as a **skill** that runs in main context with full conversation visibility.
 
-The 11-phase workflow is enforced at the write boundary by `track_guard`. Phase ordering is binding; the only mechanism to bypass a phase is the `exceptions` array in `.claude/state/workflow.json`, written by `/triage` at workflow creation time. The chore track is a stripped-down ordering of the same gates, with the test-first phases removed because there is nothing to test-first.
+Tracks declared in `.claude/workflows.jsonl` are enforced at the write boundary by `track_guard`. Node ordering inside each track is binding; the only mechanism to bypass a node is the `exceptions` array in `.claude/state/workflow.json`, written by `/triage` at workflow creation time. The `chore` track is a stripped-down ordering of the same gates, with the test-first nodes removed because nothing needs testing first. Projects declare their own tracks (or add nodes to the canonical ones) by editing their `.claude/workflows.jsonl`. Article IV's invariants (I1..I11) bind every track regardless of who wrote it; a track that omits `/grant-commit` before a `commit` node, or whose dependency graph contains a cycle, is rejected at triage time with a named error.
 
 The constitution at `CLAUDE.md` is the source of truth for in-session behaviour; `docs/init/seed.md` is the source of truth for the baseline's shape. When the constitution and the implementation conflict, the constitution governs and the implementation gets corrected. When `seed.md` and the constitution conflict, `seed.md` governs and you stop and surface the drift before acting.
 

package/bin/cli.js

@@ -8,8 +8,8 @@ import { existsSync } from 'node:fs';
 import * as io from '../src/cli/io.js';
 import { scanSentinels } from '../src/cli/conflict.js';
 import { freshInstall, forceInstall, COPY_EXCLUDE } from '../src/cli/install.js';
-import { threeWayMerge } from '../src/cli/merge.js';
-import { loadManifest, buildManifestFromDir } from '../src/cli/manifest.js';
+import { threeWayMerge, ACTION_LABELS, ACTION_LABEL_WIDTH } from '../src/cli/merge.js';
+import { loadManifest, buildManifestFromDir, MANIFEST_VERSION } from '../src/cli/manifest.js';
 import { fetchPlantumlIfMissing, FETCH_OUTCOMES } from '../src/cli/plantuml.js';
 import { runDoctor, formatReport } from '../src/cli/doctor.js';
 
@@ -18,7 +18,7 @@ const PKG_ROOT = resolve(__dirname, '..');
 
 const HELP_TEXT = `Usage:
   create-baseline <target> [options]      install the baseline
-  create-baseline upgrade [target]        three-way merge against an installed baseline
+  create-baseline upgrade [target]        three-tier merge (mechanical / semantic / binary-prompt)
   create-baseline doctor [target]         report drift in an installed target
 
 Materializes the Claude Code baseline (.claude/, CLAUDE.md, .mcp.json,
@@ -31,10 +31,15 @@ Install modes:
 
 Upgrade:
   Replaces the prior --merge flag. Reads <target>/.claude/.baseline-manifest.json
-  and runs a three-way merge against the shipped template. Prunes baseline files
-  removed upstream that the user hadn't touched; customized-stale files are
-  preserved (exit 3) — or interactively resolved when stdout is a TTY (keep
-  mine / take theirs / abort).
+  and runs a three-tier merge against the shipped template:
+    - tier 1 (binary prompt): customized files prompt "Keep your version / Use
+      new baseline / Show diff" in TTY mode (exit 3 on any skipped).
+    - tier 2 (mechanical): files routed through git merge-file --diff3 with
+      BASE recovered from .claude/.baseline-prior/ cache or npm fallback;
+      clean merges land silently, conflicts surface with markers (exit 4).
+    - tier 3 (semantic): staged at .claude/state/upgrade/<ts>/ for the
+      /upgrade-project Claude Code skill to reconcile (exit 5).
+  Prunes baseline files removed upstream that the user hadn't touched.
   --dry-run        Print intended actions without writing.
 
 Doctor:
@@ -61,11 +66,13 @@ Misc:
   --version        Print version.
 
 Exit codes:
-  0  success / clean doctor
+  0  success (or clean doctor)
   1  user abort, conflict-without-force, doctor reports missing files, or upgrade aborted
-  2  argv error, non-TTY where TTY required, doctor finds no manifest, or --merge passed
-  3  upgrade had skipped customizations (or stale-customized prunes)
-  4  --require-plantuml fetch failure
+  2  bad command line, prompted input needed but no terminal, doctor finds no manifest,
+     or deprecated --merge passed
+  3  upgrade kept your customized files (or preserved files removed upstream)
+  4  --require-plantuml jar fetch failed, OR mechanical merge produced conflicts to resolve
+  5  semantic merge staged for /upgrade-project to reconcile in Claude Code
 `;
 
 const OPTIONS = {
@@ -198,8 +205,9 @@ async function runPlainInstall(target, values, templateDir) {
   if (!dryRun) {
     const plantumlExit = await fetchPlantumlPlain(target, values);
     if (plantumlExit !== 0) return plantumlExit;
-    io.log(`Installed manifest version 1 to ${target}.`);
-    io.log(`Pin via "@friedbotstudio/create-baseline@<exact-version>" in your bootstrap docs.`);
+    const version = await readPackageVersion();
+    io.log(`Baseline installed at ${target} (manifest v${MANIFEST_VERSION}).`);
+    io.log(`For reproducible installs, pin the exact version: @friedbotstudio/create-baseline@${version}`);
   }
   return 0;
 }
@@ -227,6 +235,13 @@ async function dispatchUpgrade(target, values, templateDir) {
     await usageError(`No baseline manifest at ${manifestPath}. Run a fresh install first.`);
     return 2;
   }
+  const { findPendingStage, formatStageTimestamp } = await import('../src/cli/upgrade-tiers.js');
+  const pending = await findPendingStage(target);
+  if (pending) {
+    const fileLines = pending.files.map((f) => `  - ${f}`).join('\n');
+    io.log(`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.`);
+    return 5;
+  }
   if (process.stdout.isTTY) {
     const tui = await import('../src/cli/tui/upgrade.js');
     return tui.run({
@@ -241,17 +256,33 @@ async function runPlainUpgrade(target, values, templateDir, manifestPath) {
   const oldManifest = await loadManifest(manifestPath);
   const tplFiles = await listShippedFiles(templateDir);
   const newManifest = await buildManifestFromDir(templateDir, tplFiles);
+  await overlayShippedTiers(templateDir, newManifest);
   if (values['dry-run']) {
     io.log(`Would upgrade ${tplFiles.length} files into ${target}`);
     return 0;
   }
   const report = await threeWayMerge(templateDir, target, oldManifest, newManifest);
   for (const action of report.actions) {
-    io.log(`${action.kind.padEnd(24)} ${action.path}`);
+    const label = ACTION_LABELS[action.kind] ?? action.kind;
+    io.log(`${label.padEnd(ACTION_LABEL_WIDTH)}  ${action.path}`);
   }
   return report.exitCode;
 }
 
+async function overlayShippedTiers(templateDir, newManifest) {
+  const shippedPath = join(templateDir, '.claude/manifest.json');
+  if (!existsSync(shippedPath)) return;
+  const { readFile: rf } = await import('node:fs/promises');
+  const shipped = JSON.parse(await rf(shippedPath, 'utf8'));
+  if (!shipped?.files) return;
+  for (const rel of Object.keys(newManifest.files)) {
+    const shippedEntry = shipped.files[rel];
+    if (shippedEntry && typeof shippedEntry === 'object' && typeof shippedEntry.tier === 'string') {
+      newManifest.files[rel] = { sha256: newManifest.files[rel], tier: shippedEntry.tier };
+    }
+  }
+}
+
 async function dispatchDoctor(positionals, values) {
   const target = resolve(positionals[1] ?? '.');
   const report = await runDoctor(target, { strict: !!values.strict });
@@ -326,7 +357,7 @@ async function main(argv) {
   }
 
   if (values['no-plantuml'] && values['require-plantuml']) {
-    await usageError('--no-plantuml and --require-plantuml are mutually exclusive');
+    await usageError('--no-plantuml and --require-plantuml conflict; pick one or omit both.');
     return 2;
   }
   if (positionals.length === 0) {

package/obj/template/.claude/commands/init-project-doctor.md

@@ -0,0 +1,74 @@
+---
+description: Detect and repair baseline drift — missing or invalid `.claude/workflows.jsonl`, schema violations, four-way Article IV / §18 mirror drift, and (advisory) shipped-tooling files placed outside `.claude/` against the convention codified at seed.md §3. Interactive: presents each detected violation via AskUserQuestion and applies the named fix on confirmation.
+argument-hint: ""
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion, Glob, Grep
+disable-model-invocation: true
+---
+
+# `/init-project doctor` — baseline drift detector + repairer
+
+User-only command. Run after a `create-baseline upgrade` cycle, after manually editing `workflows.jsonl`, or any time the baseline feels out of sync. Different from `create-baseline doctor` (the npm CLI manifest-drift checker) — this is a project-internal interactive repair tool.
+
+## Step 1 — Pre-flight
+
+- Print: "`/init-project doctor` — checking baseline integrity. Each detected violation is presented separately; you confirm each fix via AskUserQuestion."
+- Verify the project is configured: `.claude/project.json → configured == true`. If false, halt with: "Run `/init-project` first; the project is in agnostic mode."
+- Verify `python3` and `node` available; halt with one-line missing-dep message if not.
+
+## Step 2 — Check `.claude/workflows.jsonl` presence
+
+- If `.claude/workflows.jsonl` is missing on disk:
+  - AskUserQuestion: "`.claude/workflows.jsonl` missing. Restore from pristine template (`src/.claude/workflows.template.jsonl`)?"
+  - Options: `Restore` | `Skip` | `Show diff`
+  - On `Restore`: `cp src/.claude/workflows.template.jsonl .claude/workflows.jsonl`. Log to `.claude/state/init/doctor-<timestamp>.log`.
+  - On `Skip`: note in report; proceed.
+
+## Step 3 — Check `.claude/schemas/` presence
+
+- If `.claude/schemas/workflow-track.v1.json` is missing:
+  - AskUserQuestion: "`.claude/schemas/workflow-track.v1.json` missing. Restore from `src/.claude/schemas/`?"
+  - Apply on `Restore` (recursive cp).
+
+## Step 4 — Validate workflows.jsonl against §18 schema + invariants
+
+- Run `node .claude/skills/triage/seed-tasklist.mjs --validate-only`. The helper exits 0 on success or non-zero with a named-error report on failure.
+- On validation failure, parse the helper's stderr for each error. For each:
+  - AskUserQuestion: "Violation: `<kind>` in track `<id>`: `<message>`. Options: `Show context`, `Skip` (mark as known), `Edit manually` (open file at line)."
+  - The doctor does NOT auto-fix schema/invariant violations — manual user judgment is required. Surface the violation context (track + node ids) and pause.
+
+## Step 5 — Four-way mirror check (Article IV / §18)
+
+Extract the §18 sections from `docs/init/seed.md` and `src/seed.template.md`. Extract Article IV sections from `CLAUDE.md` and `src/CLAUDE.template.md`. Byte-compare each pair.
+
+- On §18 mirror drift:
+  - AskUserQuestion: "`docs/init/seed.md §18` differs from `src/seed.template.md §18`. Options: `Re-mirror docs→src`, `Re-mirror src→docs`, `Show diff`, `Skip`."
+  - Apply the chosen overwrite.
+
+- Same pattern for Article IV mirror.
+
+## Step 6 — `.claude/` tooling convention check (advisory)
+
+Per seed.md §3 + `conventions.md → user-shipped-tooling-lives-in-claude-directory`, user-shipped baseline tooling lives under `.claude/`. The only project-root exceptions are `CLAUDE.md` and `.mcp.json`.
+
+- Scan for shipped tooling at the project root that should live under `.claude/`. Heuristic: files matching `*.skill.md`, `*.workflow.json`, `*.hook.sh`, `*.command.md` at the project root.
+- For each match:
+  - AskUserQuestion: "Convention violation: `<path>` at project root. Suggested target: `.claude/<subdir>/<filename>`. Move?"
+  - The doctor offers the move; the user confirms.
+
+## Step 7 — Report + log
+
+- Print a summary table:
+  - Checks run: N
+  - Fixes applied: M
+  - Skipped (user declined or manual fix required): K
+  - Remaining manual: L
+- Write the full session record to `.claude/state/init/doctor-<UTC-timestamp>.log` (one line per check + action).
+- If any check returned a manual-fix path (e.g., schema violation in workflows.jsonl), exit with code 1 so caller workflows treat the result as "drift remains". Otherwise exit 0.
+
+## Constraints
+
+- **Read-only by default; writes only on user confirmation.** Every Edit/Write happens after an AskUserQuestion `Apply` response. No silent fixes.
+- **No commits.** The doctor's fixes land on the working tree. The user commits via the normal `/grant-commit` + `/commit` flow.
+- **No new dependencies.** Validation reuses `src/cli/workflows-validator.js` via the triage helper.
+- **Schema/invariant violations require manual fixes.** Auto-fixing structurally violates the user's intent (the violation might be intentional during development). Doctor surfaces; user fixes.
+- **Mirror drift CAN be auto-fixed** (one-direction overwrite on confirmation). The reverse direction (which file is canonical?) is the user's call.

package/obj/template/.claude/hooks/lib/resume_writer.py

@@ -191,7 +191,20 @@ def compose_snapshot(transcript: Path, project_dir: Path, trigger: str) -> str:
     workflow = _read_workflow(project_dir)
 
     slug = workflow.get("slug") or "(none)"
-    entry_phase = workflow.get("entry_phase") or "(unknown)"
+    # Post-§18: workflow.json carries `track_id`; legacy pre-§18 files carry
+    # `entry_phase`. Accept both. Map reverses
+    # `src/cli/workflow-migrator.js → ENTRY_PHASE_TO_TRACK_ID`.
+    _TRACK_ID_TO_ENTRY_PHASE = {
+        "intake-full": "intake",
+        "spec-entry": "spec",
+        "tdd-quickfix": "tdd",
+        "chore": "chore",
+    }
+    entry_phase = (
+        workflow.get("entry_phase")
+        or _TRACK_ID_TO_ENTRY_PHASE.get(workflow.get("track_id"))
+        or "(unknown)"
+    )
     completed = workflow.get("completed") or []
     exceptions = workflow.get("exceptions") or []
     phases = workflow.get("phases") or []

package/obj/template/.claude/hooks/track_guard.sh

@@ -54,7 +54,17 @@ except Exception:
 phases = pj.get("workflow", {}).get("phases") or []
 artifacts = pj.get("workflow", {}).get("artifacts") or {}
 exceptions = set(ws.get("exceptions") or [])
-entry = ws.get("entry_phase")
+# Post-§18: workflow.json carries `track_id`; legacy pre-§18 files carry
+# `entry_phase`. Accept both. The canonical map below mirrors
+# `src/cli/workflow-migrator.js → ENTRY_PHASE_TO_TRACK_ID` in reverse so
+# track_guard's phase-ordering enforcement keeps working on both shapes.
+_TRACK_ID_TO_ENTRY_PHASE = {
+    "intake-full": "intake",
+    "spec-entry": "spec",
+    "tdd-quickfix": "tdd",
+    "chore": "chore",
+}
+entry = ws.get("entry_phase") or _TRACK_ID_TO_ENTRY_PHASE.get(ws.get("track_id"))
 
 # Find which phase this file belongs to.
 file_phase = None