craftar 0.21.1 → 0.22.1

package/README.md

@@ -71,8 +71,11 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar init [--forge <dir\|url>] [--profile <name>] [--ref <ref>] [--targets <a,b>] [--add-recipe <name>]... [--remove-recipe <name>]... [--replace] [--no-sync] [--offline] [--workspace .]` | Starts a workspace: writes a `craftar.yaml` holding `forge` (a directory as the path from the workspace, POSIX; a URL as given), `ref` (a remote Forge only), `profile`, `recipes` (only the lists the recipe flags leave non-empty) and `targets` (only with `--targets`; otherwise the workspace follows the profile's), then runs the first `sync` — which also registers the workspace. **In a terminal** (stdin and stdout both a TTY), `--forge` and `--profile` are optional: what is missing is asked for — the Forge (offering the one last synced on this machine, from the registry), a remote Forge's ref, the profile (from the Forge's list), then the recipes and the targets the profile gives, to keep or adjust; a flag given is never asked for. One confirmation before anything is written, showing what the first sync would do. Ctrl-C, the end of input, or `no` at the confirmation: nothing written, exit 1 (`init cancelled — nothing written`). The run ends with an `again craftar init …` line: the same run as flags, for CI. Off a terminal (a pipe, CI), a missing flag is refused, exit 1, naming the flag; where the terminal does not report a TTY, the flags are required. With both flags given nothing is asked, in a terminal or not. The file is written only once the configuration loads (a remote Forge is fetched as `sync` fetches it; `--offline` reads the cache), resolves and plans, and the sync applies that same plan. `--remove-recipe` and `--add-recipe` go through `remove recipe` / `add recipe`'s core (removes first, then adds; `--replace` swaps a slot holder); a call whose every name changes nothing prints its reasons as a `note`. `--workspace` is created when missing. Files already on disk and not in a lock are adopted when equal to the plan and skipped as a `collision` otherwise, never overwritten, with one warning pointing at `craftar import`. `--no-sync` writes `craftar.yaml` only and prints what the first `sync` would do. When a declared parameter a file cites has no value (see `sync`), `craftar.yaml` is still written — the workspace's `overrides.params` is a place for the value — but the first `sync` is not run: the refusal is printed (`error: N declared parameter(s) have no value — craftar.yaml written, sync not run`, with `then run craftar sync` in its fix line), exit 1; in a terminal the confirmation says `first sync: refused — …` and asks only `Write craftar.yaml`; `--no-sync` prints `next sync: refused — …` and exits 0. Refused, with nothing written and no directory created: an existing `craftar.yaml`; a `--workspace` that is a file, or under one; credentials in `--forge` (the value is never printed); `--ref` with a directory Forge; an unknown target; a recipe both added and removed, or any refusal of `add recipe` / `remove recipe`; a `craftar.local.yaml` that sets `forge` or `profile`, or a key a given flag would write (`ref`, `recipes`, `targets`) — its value would replace the flag's; a Forge, profile or plan that does not load. |
 | `craftar import --from claude-code --forge <dir> --profile <name> [--workspace .] [--write-config] [--report <file.md>]` | Reads `.claude/{rules,agents,commands,skills,scripts,hooks}`, `.mcp.json` and, when present, `.kiro/steering` (for inclusion modes and hand-written steering). Creates ingredients, recipes (`base`, one `stack-*` per scoped rule, `<profile>-steering`) and a profile, or updates them. An ingredient already in the Forge is reused when the base, **rendered** for this profile (its declared defaults, the profile's `params`, the workspace's `overrides.params`), equals the workspace file; failing that, when a unique, proved assignment of the base's declared `{{keys}}` reproduces it, the values are **inferred** into the profile's `params` (one value per key per run; never a change another ingredient would feel). A base with section markers is rendered with the profile's `sections` and the workspace's `overrides.sections` first; when the workspace file differs from it only inside sections, the unique content that reproduces the file byte for byte is **inferred** into the profile's `sections` (tried after params, never combined with them; the report counts lines and never prints the content). An import that writes a section value, or compares a workspace file against a base holding markers, sets `schema: 2` in `craftar.forge.yaml`. A reused base takes the place its `<name>--<profile>` variant held: the profile moves to the shared recipe when that orders the base there, and an owned recipe gets the base in the variant's slot, so the rule order (and `AGENTS.md`) stays as it was. Anything else becomes a `<name>--<profile>` variant that emits under the original name, with the reason, so the workspace still round-trips while you decide what to unify. A shared recipe is never widened for one client: a profile whose ingredients differ from `base` or a `stack-*` gets its own `<recipe>--<profile>`. An existing profile is merged in place (`params`, `sections`, the recipes import owns, missing `targets`; every other field and comment kept, and an empty `{}` / `[]` it does not change stays on its line), as is a recipe the profile owns; `--write-config` merges an existing `craftar.yaml` (`forge`, `profile`, `targets`). The report adds `rendered` (with `sections <names>` when a section value filled the render), `inferred`, `sectioned`, `param <key>: <old> → <new>`, `section <key> <name>: <old> → <new>`, `forge craftar.forge.yaml edited (schema: 2)` and `profile … created\|edited\|unchanged` lines. It refuses, with the Forge untouched, a Forge that does not load, a profile or recipe or `craftar.yaml` that does not round-trip through the YAML writer, a misplaced profile, a recipe import writes whose file and `name` disagree, a workspace override that does not parse, a literal `{{key}}` the profile would render, changing a recipe or variant another profile uses, a workspace file holding a section marker at column 0 (sync would not reproduce it: indent it), a Forge base with malformed section markers, and a `craftar.forge.yaml` it needs to bump to `schema: 2` that does not round-trip (set it by hand). Ingredients holding a secret-like value (tokens, private keys, high-entropy MCP `env`/`args` values) are rejected and listed by location — the value is never printed. `authEnv` is never inferred; a variant import rewrites keeps the one it declares, a new variant takes its base's, and a declaration a profile loses is reported. A UTF-16 file with a byte-order mark is decoded for the scan; UTF-16 without one is not detected. An ingredient that would not load back into the Forge (a name that is not slug-like, a non-string MCP `env` value) refuses the import, naming its source; so does an ingredient already in the Forge whose `ingredient.yaml` has an unknown key or a YAML syntax error, naming that file. Every read and check runs before the first write, so an import that fails leaves the Forge untouched and says so. `--report <file.md>` also writes a Markdown report, after the Forge is written: what was created, reused, made a variant or rejected, the import's warnings, and the Kiro side — *Kiro collisions*, every `.kiro/` file that differs from what `sync` would generate for the imported profile (`status`' `collision` state against no lock, so a difference of line endings, BOM or JSON formatting is not one), each with its ingredient and the line counts of the two sides, a rule's steering mirror that outgrew its rule marked `steering bigger than the rule`; and *Unsourced Kiro files*, the files under `.kiro/steering/`, `.kiro/agents/`, `.kiro/skills/` and `.kiro/settings/mcp.json` that the plan for the imported profile does not write — listed, never imported. The report holds **paths and line counts, never content** (a `.kiro/` mirror is not scanned for secrets), and names an inferred parameter's key, not its value; a warning, a rejection reason or the `not computed` line is written with every parameter and section value this run accepted, replaced or inferred as `"…"`, and a variant is named against its base, without its reason — the summary on the terminal keeps them. It describes the profile as imported: of the workspace's own `craftar.yaml` and `craftar.local.yaml` only `overrides.params` and `overrides.sections` are read (as import reads them to decide a reuse) — not its `forge`, `profile`, `targets` or recipes — and `craftar.lock` is not read. The path may be inside the workspace; it is refused, before anything is imported, when it resolves inside the Forge (through symlinks and `..`), when a file already exists there, or when a component of it cannot be resolved. If the Kiro side cannot be computed — the plan fails, or `sync` would refuse it for a declared parameter with no value — its sections read `not computed: …`, the same is an import warning, and the import still exits 0. The report is written after the summary, which then ends with `report <file.md>`; if that write fails the import has still succeeded and the Forge is written, and the command says so and exits 1. Without `--report` none of this is computed. |
 | `craftar status` | With a remote Forge, the header's second line names it — `forge <url> @ <ref \| <branch> (default branch)> <commit>`, plus `· lock <commit>` when the Forge moved since the last sync — and `--json` carries `forge: {kind, source, ref, defaultBranch, commit, lockCommit, fetched}` for every Forge. Classifies every file the Forge would produce: `new`, `update`, `unchanged`, `adopt`, `drift`, `collision`, `orphan`, `orphan-drift`. A `.json` file not yet in `craftar.lock` that parses to the planned value with its keys in the same order (it differs only in whitespace, escapes, number spelling or duplicate keys) is `adopt`, and the first `sync` rewrites it with the planned bytes — by design. For `claude-code`'s `.mcp.json` that is two-space JSON keeping the file's BOM and line endings; Kiro's JSON files become CRLF without a BOM, like every Kiro text file. A different key order is a `collision` — except for integer-like keys, which `JSON.parse` reorders. A locked JSON file reformatted by hand is `drift`, not `adopt`. `--json` for tooling: `{forge, statuses, warnings, unsetParams}`. Exits 0 whenever it prints its listing, with one exception: when a declared parameter a file cites has no value (see `sync`) it prints the listing, then the refusal on stderr, and exits 1 — `--json` still prints the whole object, with `unsetParams: [{key, declaredBy, citedBy}]` (`[]` when there is none). Exits 1 on malformed section markers and on a section marker in an ingredient the workspace resolves while `craftar.forge.yaml` declares `schema: 1` (or none), naming the Forge file and line, and when a rendered file would still hold a marker line, naming the ingredient, file and rendered line — as do `sync`, `diff`, `explain` and `ls`. Warns about a section value that names no ingredient, or no marker of an ingredient the workspace resolves, and about marker lines in an emitted file not every target renders as text (copied as they are). |
-| `craftar sync` | Renders sections (no rendered body holds a marker; an emitted file not every target renders as text keeps its markers, with a warning), then writes the plan and `craftar.lock` (schema 2: the Forge's source, requested `ref` and commit, the resolved recipes and targets — rewritten only when that content changes). With a remote Forge it fetches first and exits 1 when the fetch fails, `--dry-run` and `--check` included. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default). A writing `sync` (not `--dry-run`, not `--check`) also records the workspace in `$CRAFTAR_HOME/registry.json` (see *Workspace registry*); a registry it cannot write is a warning, never a failed `sync`. **Refuses when a declared parameter has no value**: a key an ingredient declares under `params` with no `default`, that a file the plan writes cites as `{{key}}`, and that no layer sets (recipe default, profile `params`, `overrides.params` in `craftar.yaml` or `craftar.local.yaml`). The plan's warnings print, then one block on stderr — `error: N declared parameter(s) have no value — nothing written`, one line per key with the ingredients that declare it and the ones that cite it, and the fix — and `sync` exits 1 with nothing written: no file, no lock, no registry entry; `--dry-run` exits 1 the same way, and `--check` prints its listing, then the block, and exits 1 even when every file is `unchanged`. A `{{key}}` no ingredient declares (an Angular `{{ 'X' \| localize }}`, a stray placeholder) is still left verbatim with a warning, and an empty string is a value. |
+| `craftar sync` | Renders sections (no rendered body holds a marker; an emitted file not every target renders as text keeps its markers, with a warning), then writes the plan and `craftar.lock` (schema 2: the Forge's source, requested `ref` and commit, the resolved recipes and targets — rewritten only when that content changes). With a remote Forge it fetches first and exits 1 when the fetch fails, `--dry-run` and `--check` included. `--dry-run` shows without writing. `--check` exits 1 when anything is out of sync (CI). `--overwrite-drift` regenerates hand-edited files (explicit, never default); `craftar drift` lists them, discards one, or promotes one to the Forge. A writing `sync` (not `--dry-run`, not `--check`) also records the workspace in `$CRAFTAR_HOME/registry.json` (see *Workspace registry*); a registry it cannot write is a warning, never a failed `sync`. **Refuses when a declared parameter has no value**: a key an ingredient declares under `params` with no `default`, that a file the plan writes cites as `{{key}}`, and that no layer sets (recipe default, profile `params`, `overrides.params` in `craftar.yaml` or `craftar.local.yaml`). The plan's warnings print, then one block on stderr — `error: N declared parameter(s) have no value — nothing written`, one line per key with the ingredients that declare it and the ones that cite it, and the fix — and `sync` exits 1 with nothing written: no file, no lock, no registry entry; `--dry-run` exits 1 the same way, and `--check` prints its listing, then the block, and exits 1 even when every file is `unchanged`. A `{{key}}` no ingredient declares (an Angular `{{ 'X' \| localize }}`, a stray placeholder) is still left verbatim with a warning, and an empty string is a value. |
 | `craftar diff [path] [--exit-code]` | Line diff between disk and what the Forge would generate, for every file `sync --check` refuses: `update`, `drift`, `collision`, `new`, an `orphan` (shown as the removal of the whole file — the next `sync` deletes it) and an `orphan-drift` (a header and one line: `sync` keeps it). For `.claude/settings.craftar.example.json`, when it has drifted or collides, `diff` prints the headers and `content not shown: an example file may hold a value typed by hand`. `[path]` limits it to the one file whose workspace-relative path, as `status` prints it, equals it. Exits 0 by default, differences or not. `--exit-code` exits 1 when there are differences — exactly when `sync --check` would — and makes a `[path]` that names no file craftar manages an error (exit 1, nothing on stdout); without the flag such a path prints `no differences`. With a remote Forge, `--exit-code` also exits 1 when the fetch fails, as `sync --check` does; plain `diff` reads the cached copy with a warning. When a declared parameter a file cites has no value (see `sync`), the refusal is printed on stderr after the diff: plain `diff` still exits 0, `--exit-code` with no `[path]` exits 1 even with `no differences` — as `sync --check` does — and with a `[path]` its exit code answers for that file only. |
+| `craftar drift [show] [path] [--workspace <dir>] [--offline] [--json]` | The hand-edited files (`drift`, `orphan-drift`), whether the Forge also changed each, whether it can be promoted; with a path, its diff. Read-only. `--json` is a contract: `{workspace, profile, files: [{path, state, target, ingredient, forge, promotable, reason}], warnings, unsetParams}`. Exits 0 whenever it prints its listing, with one exception: when a declared parameter a file cites has no value (see `sync`) it prints the listing, then the refusal on stderr, and exits 1 — `--json` still prints the whole object, with `unsetParams: [{key, declaredBy, citedBy}]` (`[]` when there is none). |
+| `craftar drift discard <path...> [--workspace <dir>] [--dry-run] [--offline]` | A `sync` that regenerates only the named hand-edited files and removes a named hand-edited orphan; everything else `sync` would do happens too. A path that is not `drift` or `orphan-drift` refuses the whole run before any write. `--dry-run`. |
+| `craftar drift promote <path> [--forge <dir>] [--workspace <dir>] [--dry-run] [--json]` | Carries one hand edit of a `.claude/` file into the Forge's working tree: a value in the profile's `params` / `sections` when the edit is only that, otherwise a variant for the workspace's profile. Gated on git, proved before the first write, never syncs, never commits. With a remote Forge, `--forge <dir>` names the clone to write. `--dry-run`, `--json`. `--json` is a contract: `{workspace, forge, profile, dryRun, path, ingredient, outcome, promoted, written: [{path, action}], params, sections, flattened, dependents, nextSync, impact, warnings}`. |
 | `craftar explain <path>` | Which ingredient, recipe chain, target and origin produced a file and, for an ingredient with sections, which layer filled each one: `sections    flavors (profile globex), extra (default)` (`default`, `profile <p>` or `workspace`). For an ingredient whose files cite parameters, each cited key with the layer that filled it for this ingredient: `params      org (profile globex), port (default), root (unset)` — `default` (the ingredient's own), `recipe <name>`, `profile <p>`, `workspace` (either workspace file) or `unset`. `AGENTS.md` gets neither line: it is not one ingredient. |
 | `craftar ls` | Recipes and ingredients resolved for this workspace. |
 | `craftar workspaces [--fetch] [--json]` | Every workspace a writing `sync` registered on this machine, sorted by path: name, path, profile, stack (`slot=recipe`), targets, the Forge, the last sync, and a status computed now — `up to date`, `outdated` (`new`, `update` or `orphan` pending), `drift` (a `drift`, `orphan-drift` or `collision`), `no lock`, `missing` (directory or `craftar.yaml` gone) or `error` (it no longer loads, plans or reads its lock, or its `sync` would refuse for a declared parameter with no value — the reason is one of the row's warnings: `sync refused: declared parameter(s) with no value: <keys>`), plus `forge moved` when the Forge's commit differs from the lock's. Read without the network: a remote Forge comes from the cache; `--fetch` fetches first. Each row's warnings print after the table, prefixed with its path. Times are UTC. Writes nothing. Exits 0 whenever the table prints. Takes no `--workspace`. `--json` is a contract: `{registry, fetch, workspaces, warnings}`. |
@@ -310,6 +313,18 @@ Later: `service` ingredients with compose fragments (`craftar services up`); `do
 
 ## Upgrading
 
+### to 0.22.1
+
+- **A file the schema refuses is reported on one line, and never with a value it holds.** `invalid <file>: <key>: <what was expected>; <key>: …` replaces zod's JSON list of issues, which quoted the refused value — so a credential written where one of a fixed set of words is expected reached the terminal. A key is still named, as a path (`overrides.sections.<key>`) or as an unrecognized key, and so is the *type* received (`Expected string, received number`) — never the value. It holds for a Forge file, `craftar.yaml` (merged with `craftar.local.yaml`), the registry (`invalid <file>: …`), a `forge unify --plan` file (`<file>: <key>: …`, with no `invalid`), and the refusals of `import` and `drift promote` (`does not fit the ingredient schema: …`, `does not load (…)`), `forge unify` (`the edit no longer loads: …`), and `add recipe`, `remove recipe` and `import --write-config` (`it no longer loads: …`).
+- **A `craftar.lock` or a registry that does not read is named, and nothing of it is quoted.** `craftar.lock is not valid JSON` and `craftar.lock is not a valid lock: <key>: …` replace the raw parser and zod messages; a registry that is not valid JSON reads `cannot read <file>: not valid JSON`. `declares schema <n>, which this craftar does not read` prints the schema only when it is a whole number, and `(not a whole number)` otherwise.
+- **`craftar doctor`**: the `config`, `lock` and `registry` messages carry the same text — `<what> (<key>: <what was expected>, and N more)` keeps its shape, without `received '<value>'`; `craftar.lock is not valid JSON` no longer ends with the parser's message in parentheses.
+- **No exit code and no `--json` key changes**; the text of an error string inside `--json` follows the new wording — among them `doctor --json` `checks[].message`; the `warnings` of `workspaces --json`, `targets --json`, `forge unify --json` and `drift promote --json`; `forge impact --json` `error`; `impact[].error` of `forge unify --json` and `impact.workspaces[].error` of `drift promote --json`; and `forge unify --json` `recipes.kept[].reason`.
+- **No byte change**: no emitter and no lock changed. No workspace sees `update`.
+
+### to 0.22.0
+
+- **New commands `craftar drift show`, `craftar drift discard` and `craftar drift promote`**: list hand-edited files, discard their edits, or carry one into the Forge. `drift show --json` and `drift promote --json` are new tooling contracts. The `sync` skip lines for `drift` and `orphan-drift` were reworded (prose, not a contract).
+
 ### to 0.21.1
 
 - **A YAML syntax error no longer prints the offending lines.** In a Forge file — a manifest, a recipe, a profile, an `ingredient.yaml` — the message is now `invalid <file>: <code> at line N, column M`, or `invalid <file>: YAML syntax error` when the parser gives no code (it was the yaml parser's message, source lines included, so a credential on a broken line reached the terminal). yaml warnings — an unresolved tag, a collection used as a key — are no longer printed either, frontmatter included. `forge unify --plan` reports a plan that is not valid YAML the same way; a plan that cannot be read or does not match its schema still reads `<file>: <error>`. No exit code and no `--json` shape changes; no generated byte changes.

package/dist/cli.js

@@ -4,9 +4,10 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
+import { planPromote, applyPromote, UnheldError } from "./importers/drift-promote.js";
 import { classifyForge } from "./core/remote.js";
 import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.js";
-import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState, countStates, NEXT_SYNC_STATES } from "./core/impact.js";
+import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState, countStates, countStatesObject, NEXT_SYNC_STATES } from "./core/impact.js";
 import { runDoctor } from "./core/doctor.js";
 import { pruneCache } from "./core/cache.js";
 import { resolveHome } from "./core/home-lock.js";
@@ -17,6 +18,7 @@ import { listTargets } from "./core/capabilities.js";
 import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { renderImportReport } from "./core/import-report.js";
+import { driftList, unmanaged } from "./core/drift.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { hashNormalized, toLf, stripBom } from "./core/text.js";
 import { exists, gitDirty, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
@@ -31,6 +33,7 @@ import { localKeys, readLocalFile } from "./core/workspace-yaml.js";
 import { HUNK_CLASSES, INGREDIENT_TYPES, UnifyPlanSchema } from "./schema/index.js";
 import { EXAMPLE_SETTINGS } from "./emitters/shared.js";
 import { YamlSyntaxError, parseYamlText } from "./core/yaml-read.js";
+import { errorText } from "./core/schema-fault.js";
 process.stdout.on("error", (e) => { if (e.code === "EPIPE")
     process.exit(0); });
 /**
@@ -40,7 +43,7 @@ process.stdout.on("error", (e) => { if (e.code === "EPIPE")
  */
 const DIFF_EXIT_CODE_FETCH_MODE = "sync";
 const program = new Command();
-program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.21.1");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.22.1");
 const SAVE_PLAN_GATE = { what: "plan", who: "unify", outside: "save plans outside the Forge", never: "unify never overwrites" };
 const REPORT_GATE = { what: "report", who: "import", outside: "write the report outside the Forge", never: "import never overwrites" };
 program
@@ -169,7 +172,7 @@ async function applyAndReport(ws, p, st, lock, opts = {}) {
     for (const f of r.written)
         console.log(`  ${pc.green("+")} ${f}`);
     for (const f of r.removed)
-        console.log(`  ${pc.magenta("-")} ${f}  (orphan: no longer produced by the Forge)`);
+        console.log(`  ${pc.magenta("-")} ${f}  (${opts.overwritePaths?.has(f) ? "hand-edited orphan: discarded" : "orphan: no longer produced by the Forge"})`);
     for (const s of r.skipped)
         console.log(`  ${pc.yellow("!")} ${s.path}  ${explainSkip(s)}`);
     for (const w of p.warnings)
@@ -375,9 +378,8 @@ program
     const st = await status(ws, p, await readLock(ws.root));
     // Spec 19 §3.3: under --exit-code a path nothing matches must not read as "clean" to a script
     if (o.exitCode && only && !st.some((s) => s.path === only))
-        fail(`${only} is not a file craftar manages in this workspace — pass the workspace-relative path as \`craftar status\` prints it (forward slashes)`);
+        fail(unmanaged(only));
     let shown = 0;
-    const render = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
     for (const s of st) {
         if (only && s.path !== only)
             continue;
@@ -385,31 +387,7 @@ program
         if (["unchanged", "adopt"].includes(s.state))
             continue;
         shown++;
-        if (s.state === "orphan-drift") {
-            // Header and one line, no body: sync keeps this file
-            console.log(pc.bold(`--- ${s.path} (disk, orphan-drift)`));
-            console.log(`  ${explainSkip(s)}`);
-            continue;
-        }
-        const disk = await readText(path.join(ws.root, s.path));
-        if (s.state === "orphan") {
-            // A removal: the file exists on disk but the Forge no longer produces it
-            console.log(pc.bold(`--- ${s.path} (disk, orphan)`));
-            console.log(pc.bold(`+++ ${s.path} (forge: no longer produced — sync removes it)`));
-            console.log(renderDiff(disk ?? "", "", render));
-        }
-        else {
-            const next = s.planned ? toLf(stripBom(s.planned.content.toString("utf8"))) : "";
-            console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
-            console.log(pc.bold(`+++ ${s.path} (forge)`));
-            // Spec 27 §4.2, Ruling 4: do not print on-disk content of the example file for drift/collision
-            if (s.path === EXAMPLE_SETTINGS && (s.state === "drift" || s.state === "collision")) {
-                console.log("  content not shown: an example file may hold a value typed by hand");
-            }
-            else {
-                console.log(renderDiff(disk ?? "", next, render));
-            }
-        }
+        await printFileDiff(ws.root, s);
     }
     if (!shown)
         console.log(pc.green("no differences"));
@@ -420,6 +398,322 @@ program
     if (refusalBlock(unsetDeclared(p)) && o.exitCode && !only)
         process.exitCode = 1;
 });
+const DIFF_PAINT = { paint: { same: pc.dim, del: pc.red, add: pc.green } };
+/** What `craftar diff` prints for one file `sync --check` refuses; `drift show <path>` prints the same for a drifted one. */
+async function printFileDiff(root, s) {
+    if (s.state === "orphan-drift") {
+        // Header and one line, no body: sync keeps this file
+        console.log(pc.bold(`--- ${s.path} (disk, orphan-drift)`));
+        console.log(`  ${explainSkip(s)}`);
+        return;
+    }
+    const disk = await readText(path.join(root, s.path));
+    if (s.state === "orphan") {
+        // A removal: the file exists on disk but the Forge no longer produces it
+        console.log(pc.bold(`--- ${s.path} (disk, orphan)`));
+        console.log(pc.bold(`+++ ${s.path} (forge: no longer produced — sync removes it)`));
+        console.log(renderDiff(disk ?? "", "", DIFF_PAINT));
+    }
+    else {
+        const next = s.planned ? toLf(stripBom(s.planned.content.toString("utf8"))) : "";
+        console.log(pc.bold(`--- ${s.path} (disk, ${s.state})`));
+        console.log(pc.bold(`+++ ${s.path} (forge)`));
+        // Spec 27 §4.2, Ruling 4: do not print on-disk content of the example file for drift/collision
+        if (s.path === EXAMPLE_SETTINGS && (s.state === "drift" || s.state === "collision")) {
+            console.log(EXAMPLE_CONTENT_HIDDEN);
+        }
+        else {
+            console.log(renderDiff(disk ?? "", next, DIFF_PAINT));
+        }
+    }
+}
+/** Spec 27 Ruling 4: the on-disk content of the example file is never printed. */
+const EXAMPLE_CONTENT_HIDDEN = "  content not shown: an example file may hold a value typed by hand";
+/** A path as the user may type it, to the spelling `status` prints: forward slashes, no leading `./`. */
+const statusPath = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+/* ---------------------------------------------------------------- drift */
+const drift = program.command("drift").description("Hand-edited generated files: show them, discard the edit, or promote it to the Forge");
+drift
+    .command("show", { isDefault: true })
+    .description("List the files hand-edited since the last sync, with the Forge's side and whether the edit can be promoted; with a path, that file's row and its diff. Writes nothing")
+    .argument("[path]", "limit to one file, and show its diff")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--json", "machine-readable output", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .action(async (given, o) => {
+    const ws = await loadWorkspace(o.workspace, load(o, "read"));
+    warnStderr(ws.warnings);
+    const p = await plan(ws);
+    const st = await status(ws, p, await readLock(ws.root));
+    const only = given === undefined ? null : statusPath(given);
+    const named = only === null ? null : st.find((s) => s.path === only);
+    if (only !== null && !named)
+        fail(unmanaged(only));
+    const rows = driftList(named ? [named] : st);
+    // Spec 30r5: drift show decides a refused sync as status does — unsetParams in --json, the refusal block on stderr, exit 1.
+    const unset = unsetDeclared(p);
+    if (o.json) {
+        console.log(JSON.stringify({ workspace: await fs.realpath(ws.root), profile: ws.config.profile, files: rows, warnings: p.warnings, unsetParams: unset }, null, 2));
+        if (unset.length)
+            process.exitCode = 1;
+        return;
+    }
+    if (named && !rows.length) {
+        console.log(`${named.path} is not drifted (${named.state})`);
+        if (refusalBlock(unset))
+            process.exitCode = 1;
+        return;
+    }
+    if (!rows.length) {
+        console.log("no drift");
+        if (refusalBlock(unset))
+            process.exitCode = 1;
+        return;
+    }
+    // Columns as wide as their longest value, as the spec's example lines them up (§4.2).
+    const wide = (pick) => Math.max(...rows.map((r) => pick(r).length));
+    const [pathW, ingW, forgeW] = [wide((r) => r.path), wide((r) => r.ingredient), wide((r) => `forge: ${r.forge}`)];
+    for (const r of rows)
+        console.log(`${color(r.state)(r.state.padEnd(13))} ${r.path.padEnd(pathW)}  ${pc.dim(r.ingredient.padEnd(ingW))}  ${`forge: ${r.forge}`.padEnd(forgeW)}  promote: ${r.promotable ? "yes" : `no (${r.reason})`}`);
+    if (!named) {
+        if (refusalBlock(unset))
+            process.exitCode = 1;
+        return;
+    }
+    if (named.state === "orphan-drift") {
+        // The whole file as a removal: what `drift discard` would do to it.
+        console.log(pc.bold(`--- ${named.path} (disk, orphan-drift)`));
+        console.log(pc.bold(`+++ ${named.path} (forge: no longer produced — \`craftar drift discard\` removes it)`));
+        // Spec 27 Ruling 4: the on-disk content of the example file is never printed.
+        if (named.path === EXAMPLE_SETTINGS) {
+            console.log(EXAMPLE_CONTENT_HIDDEN);
+        }
+        else {
+            console.log(renderDiff((await readText(path.join(ws.root, named.path))) ?? "", "", DIFF_PAINT));
+        }
+    }
+    else
+        await printFileDiff(ws.root, named);
+    if (refusalBlock(unset))
+        process.exitCode = 1;
+});
+drift
+    .command("discard")
+    .description("Regenerate the named hand-edited files from the Forge (their edits are lost) and remove a named hand-edited file the Forge no longer produces; otherwise a sync like any other")
+    .argument("<path...>", "the hand-edited files, as `craftar status` prints them")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--dry-run", "show the plan, write nothing", false)
+    .option("--offline", "use the cached copy of a remote Forge, without fetching", false)
+    .action(async (given, o) => {
+    const ws = await loadWorkspace(o.workspace, load(o, "sync"));
+    const p = await plan(ws);
+    const lock = await readLock(ws.root);
+    const st = await status(ws, p, lock);
+    const paths = [...new Set(given.map(statusPath))];
+    // Every refusal comes before the first write: one path that is not a hand edit stops the whole run.
+    const stateOf = new Map(st.map((s) => [s.path, s.state]));
+    const not = paths.filter((x) => stateOf.get(x) !== "drift" && stateOf.get(x) !== "orphan-drift");
+    if (not.length)
+        fail(`not drifted: ${not.map((x) => `${x} (${stateOf.get(x) ?? "not managed"})`).join(", ")} — nothing was written`);
+    // Check for unset params BEFORE any output (spec 29 §4.1, spec 30r1 commit 3 issue 1)
+    // Print plan warnings before the refusal, as sync does (spec 30r3 commit 3 issue 6)
+    const unset = unsetDeclared(p);
+    if (unset.length) {
+        for (const w of p.warnings)
+            console.log(`  ${pc.yellow("warn")} ${w}`);
+        fail(unsetRefusal(unset));
+    }
+    const overwritePaths = new Set(paths);
+    console.log(`discarding ${paths.length} hand edit(s): ${st.filter((s) => overwritePaths.has(s.path)).map((s) => s.path).join(", ")}`);
+    await applyAndReport(ws, p, st, lock, { dryRun: o.dryRun, overwritePaths });
+});
+drift
+    .command("promote")
+    .description("Carry a hand-edited file to the Forge as a profile variant, behind git's gate, proved before any write; never writes the lock, the registry or the cache")
+    .argument("<path>", "the hand-edited file, as `craftar status` prints it")
+    .option("--workspace <dir>", "workspace root", ".")
+    .option("--forge <dir>", "the Forge directory to write (required for a URL Forge)")
+    .option("--dry-run", "prove and show the plan, write nothing", false)
+    .option("--json", "machine-readable output", false)
+    .action(async (givenPath, o) => {
+    const home = craftarHome();
+    const normalizedPath = statusPath(givenPath);
+    let promotePlan;
+    try {
+        promotePlan = await planPromote({
+            workspaceRoot: o.workspace,
+            forgeDir: o.forge ?? null,
+            path: normalizedPath,
+            home,
+            env: process.env,
+        });
+    }
+    catch (e) {
+        // Handle UnheldError
+        if (e instanceof UnheldError) {
+            fail(unheldMessage("drift promote", e.forgeRoot, e.unheld));
+        }
+        throw e;
+    }
+    // --json output
+    if (o.json) {
+        // Apply first if not dry-run (spec 30r1 §3.2: JSON follows the write)
+        if (!o.dryRun) {
+            const journal = [];
+            try {
+                await applyPromote(promotePlan, journal);
+            }
+            catch (e) {
+                // Late failure: stdout stays "", stderr is lateFailure
+                fail(lateFailure(e, promotePlan.forgeRoot, journal, "drift promote"));
+            }
+        }
+        // Build the JSON object in spec §4.7 order
+        const jsonObj = {
+            workspace: promotePlan.workspaceRealPath,
+            forge: promotePlan.forgeRoot,
+            profile: promotePlan.profile,
+            dryRun: o.dryRun,
+            path: promotePlan.inputPath,
+            ingredient: promotePlan.ingredientRef,
+            outcome: promotePlan.outcome,
+            promoted: promotePlan.promoted,
+            written: promotePlan.entries.map((e) => ({
+                path: e.rel,
+                action: e.created ? "created" : "edited",
+            })),
+            params: promotePlan.params.map((p) => ({ key: p.key, old: p.old, value: p.value })),
+            sections: promotePlan.sections.map((s) => ({ key: s.key, name: s.name })),
+            flattened: promotePlan.flattened,
+            dependents: promotePlan.dependents,
+            nextSync: { counts: countStatesObject(promotePlan.nextSync) },
+            impact: {
+                registry: promotePlan.impact.registry,
+                workspaces: promotePlan.impact.workspaces,
+            },
+            warnings: promotePlan.warnings,
+        };
+        console.log(JSON.stringify(jsonObj, null, 2));
+        return;
+    }
+    // Apply first (unless dry-run), print after — spec 30r3 §3.4: on late failure stdout is ""
+    const journal = [];
+    if (!o.dryRun) {
+        try {
+            await applyPromote(promotePlan, journal);
+        }
+        catch (e) {
+            fail(lateFailure(e, promotePlan.forgeRoot, journal, "drift promote"));
+        }
+    }
+    // Print the report
+    const writeVerb = o.dryRun ? "would write" : "wrote ";
+    const editVerb = o.dryRun ? "would edit" : "edited";
+    // First line depends on outcome
+    if (promotePlan.outcome === "params" || promotePlan.outcome === "sections") {
+        console.log(`promote ${promotePlan.inputPath} → profile ${promotePlan.profile} (${promotePlan.outcome})`);
+    }
+    else {
+        console.log(`promote ${promotePlan.inputPath} → ${promotePlan.promoted} (${promotePlan.outcome}, profile ${promotePlan.profile})`);
+    }
+    // Skip entries that are also in editedKeys (they'll be printed with keys below)
+    const editedKeyFiles = new Set(promotePlan.editedKeys.keys());
+    for (const e of promotePlan.entries) {
+        if (editedKeyFiles.has(e.rel))
+            continue;
+        if (e.created) {
+            console.log(`  ${writeVerb} ${e.rel}`);
+        }
+        else {
+            console.log(`  ${editVerb} ${e.rel}`);
+        }
+    }
+    // Print early warnings (e.g., unmanaged skill files) — pinned by test 10
+    const unusedSectionPrefix = "profile ";
+    for (const w of promotePlan.warnings) {
+        if (!w.startsWith(unusedSectionPrefix) || !w.includes(" still sets section ")) {
+            // Skip registry warnings here — they come later
+            if (!w.includes(": missing") && !w.includes(": error:")) {
+                console.log(`  ${pc.yellow("warn")} ${w}`);
+            }
+        }
+    }
+    for (const [file, keys] of promotePlan.editedKeys) {
+        console.log(`  ${editVerb} ${file} (${keys.join(", ")})`);
+    }
+    // Print param changes
+    for (const p of promotePlan.params) {
+        console.log(`  param ${p.key}: ${p.old === null ? "(unset)" : JSON.stringify(p.old)} → ${JSON.stringify(p.value)}`);
+    }
+    // Print section changes (line count, never content)
+    for (const s of promotePlan.sections) {
+        console.log(`  section ${s.key} ${s.name}: ${s.lines} line(s)`);
+    }
+    // Print flattened (only for variant outcomes)
+    const flatParts = [];
+    if (promotePlan.flattened.params.length > 0) {
+        flatParts.push(`${promotePlan.flattened.params.length} param(s) (${promotePlan.flattened.params.join(", ")})`);
+    }
+    if (promotePlan.flattened.sections.length > 0) {
+        flatParts.push(`${promotePlan.flattened.sections.length} section(s) (${promotePlan.flattened.sections.join(", ")})`);
+    }
+    if (flatParts.length > 0) {
+        console.log(`  flattened: ${flatParts.join(", ")}`);
+    }
+    // Print late warnings (unused section value) after flattened — step 30g
+    for (const w of promotePlan.warnings) {
+        if (w.startsWith(unusedSectionPrefix) && w.includes(" still sets section ")) {
+            console.log(`  ${pc.yellow("warn")} ${w}`);
+        }
+    }
+    const otherCount = promotePlan.otherFilesUnchanged;
+    console.log(`  proved: this workspace plans the file on disk; ${otherCount} other file(s) unchanged`);
+    if (promotePlan.dependents.length > 0) {
+        console.log(`  also changes ${promotePlan.dependents.join(", ")}`);
+    }
+    console.log(`  ${nextSyncLine(promotePlan.nextSync, promotePlan.nextUnset)}`);
+    // Impact: print other workspaces or registry warning
+    const impact = promotePlan.impact;
+    if (impact.registry !== "read") {
+        // none, partial, or off — spec 30 §4.6 item 6
+        console.log(`  ${pc.yellow("warn")} other workspaces could not be checked (registry: ${impact.registry})`);
+    }
+    else if (impact.workspaces.length === 0) {
+        console.log("  no other registered workspace reads this Forge");
+    }
+    else {
+        // Group by profile and print
+        const sameProfile = impact.workspaces.filter((ws) => ws.profile === promotePlan.profile && ws.state !== "missing" && ws.state !== "error");
+        if (sameProfile.length > 0) {
+            const countParts = sameProfile.map((ws) => {
+                const c = NEXT_SYNC_STATES.map((k) => (ws.counts[k] ? `${ws.counts[k]} ${k}` : "")).filter(Boolean);
+                return `${ws.path} — ${c.length ? c.join(", ") : "unchanged"}`;
+            });
+            console.log(`  ${sameProfile.length} other workspace(s) of profile ${promotePlan.profile} read this Forge: ${countParts.join("; ")}`);
+        }
+        else if (impact.workspaces.filter((ws) => ws.state !== "missing" && ws.state !== "error").length === 0) {
+            console.log("  no other registered workspace reads this Forge");
+        }
+        // Print missing/error as warnings
+        for (const ws of impact.workspaces) {
+            if (ws.state === "missing") {
+                console.log(`  ${pc.yellow("warn")} ${ws.path}: missing`);
+            }
+            else if (ws.state === "error") {
+                console.log(`  ${pc.yellow("warn")} ${ws.path}: error: ${ws.error}`);
+            }
+        }
+    }
+    if (o.dryRun) {
+        console.log("  dry run — the Forge was not written");
+    }
+    else {
+        console.log("  the Forge is not committed — review with git, then commit and push it");
+        if (promotePlan.isUrlForge) {
+            console.log("  push the Forge for sync to see this");
+        }
+    }
+});
 /* ---------------------------------------------------------------- add / remove recipe */
 /**
  * Spec 22's line: what the next sync would do (also `init --no-sync`, spec 23 §4.4).
@@ -1229,13 +1523,13 @@ forge
             parsed = parseYamlText(o.plan, await fs.readFile(o.plan, "utf8"));
         }
         catch (e) {
-            fail(e instanceof YamlSyntaxError ? e.message : `${o.plan}: ${e instanceof Error ? e.message : String(e)}`);
+            fail(e instanceof YamlSyntaxError ? e.message : `${o.plan}: ${errorText(e)}`);
         }
         try {
             loadedPlan = UnifyPlanSchema.parse(parsed);
         }
         catch (e) {
-            fail(`${o.plan}: ${e instanceof Error ? e.message : String(e)}`);
+            fail(`${o.plan}: ${errorText(e)}`);
         }
         // The plan must be for this exact invocation (Ruling 23) — checked before staleness, so a
         // right-ingredient-wrong-profile plan is named for what it is rather than misdiagnosed as
@@ -1311,12 +1605,7 @@ forge
     const mustHold = [base.dir, ...(result.resolved ? [variant.dir, ...cascadeFiles] : []), ...(paramWrites?.mustHold ?? []), ...candidateProfiles];
     const unheld = await gitUnheld(f.root, mustHold);
     if (unheld.length) {
-        // Name every such path (the first few, then a count), so one run shows the whole problem.
-        const SHOWN = 10;
-        const lines = unheld.slice(0, SHOWN).map((u) => `  ${u.path} is not held by git (${u.reason})`);
-        if (unheld.length > SHOWN)
-            lines.push(`  … and ${unheld.length - SHOWN} more`);
-        fail(`unify can only change files git can restore — ${unheld.length} path(s) under ${f.root} are not:\n${lines.join("\n")}`);
+        fail(unheldMessage("unify", f.root, unheld));
     }
     let impactState = "skipped";
     let impactEntries = [];
@@ -1706,7 +1995,7 @@ cache
     else
         printPrune(result);
 });
-program.parseAsync().catch((e) => fail(e instanceof Error ? e.message : String(e)));
+program.parseAsync().catch((e) => fail(errorText(e)));
 /* ---------------------------------------------------------------- helpers */
 /** The network rule of a command, `--offline`, and `$CRAFTAR_HOME` (spec 13 §4.1, §6.3). */
 function load(o, mode) {
@@ -1924,11 +2213,11 @@ function color(state) {
 function explainSkip(s) {
     switch (s.state) {
         case "drift":
-            return "hand-edited since last sync — run `craftar diff` and either `--overwrite-drift` or promote the change to the Forge";
+            return "hand-edited since last sync — `craftar drift show <path>`, then `craftar drift discard` or `craftar drift promote`";
         case "collision":
             return "exists but was never generated by craftar and differs from the Forge — rename it or import it";
         case "orphan-drift":
-            return "no longer produced by the Forge but hand-edited — kept; delete it yourself if unwanted";
+            return "no longer produced by the Forge but hand-edited — kept; `craftar drift discard <path>` removes it, or delete it yourself";
         default:
             return "";
     }
@@ -2026,20 +2315,28 @@ async function pathTaken(p) {
         return false;
     }
 }
+/** The refusal message for paths git cannot restore (Ruling 37): the command name and every unheld path. */
+function unheldMessage(command, root, unheld) {
+    const SHOWN = 10;
+    const lines = unheld.slice(0, SHOWN).map((u) => `  ${u.path} is not held by git (${u.reason})`);
+    if (unheld.length > SHOWN)
+        lines.push(`  … and ${unheld.length - SHOWN} more`);
+    return `${command} can only change files git can restore — ${unheld.length} path(s) under ${root} are not:\n${lines.join("\n")}`;
+}
 /**
  * The message for a `forge unify` failure after writing began (Ruling 33): the original error, the
  * Forge-relative paths already touched, and the git commands that undo them — `checkout` for what
  * git tracks, `clean` for files unify created (checkout refuses a path git does not know).
  */
-function lateFailure(e, root, journal) {
-    const msg = e instanceof Error ? e.message : String(e);
+function lateFailure(e, root, journal, command = "unify") {
+    const msg = errorText(e);
     if (journal.length === 0)
         return msg;
     const rel = (abs) => path.relative(root, abs).split(path.sep).join("/");
     const quote = (p) => (/^[\w./-]+$/.test(p) ? p : `"${p}"`);
     const restore = [...new Set(journal.filter((j) => !j.created).map((j) => rel(j.abs)))];
     const created = [...new Set(journal.filter((j) => j.created).map((j) => rel(j.abs)))];
-    const lines = [msg, `unify had already started changing the Forge (${root}) when this failed:`];
+    const lines = [msg, `${command} had already started changing the Forge (${root}) when this failed:`];
     for (const p of [...restore, ...created])
         lines.push(`  ${p}`);
     lines.push("recover with:");