craftar 0.15.0 → 0.16.0

package/README.md

@@ -2,7 +2,7 @@
 
 Craft, sync and convert AI-coding workspace harnesses — rules, agents, commands, skills, MCP servers — across every client workspace you maintain and every AI coder each team uses.
 
-> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). `craftar doctor` reports, one line per finding, what is off on this machine and in this workspace. Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
+> Status: **phase 0 prototype**. `import`, `sync`, `status`, `diff`, `explain`, `ls` work end-to-end for the `claude-code` and `kiro` targets and are validated byte-for-byte against a real workspace (see *Oracle*). The Forge commands `forge variants`, `forge diff` (with a suggested class per hunk) and `forge unify` (`--take base|variant`, `take: param` to turn a value into a `{{key}}` parameter, and `take: section` to turn a client block into a section) also work, covered by the unit and golden suites rather than the oracle, and `import` is render-aware: importing into an existing Forge reuses a base whose render equals the workspace file, and edits an existing profile and the recipes it owns in place. Ingredient bodies can hold client-specific **sections** (`<!-- craftar:section <name> -->` … `<!-- /craftar:section -->`), overridden by a profile's `sections` and a workspace's `overrides.sections`; import infers each client's content and `forge unify` can extract a section from a variant, and a Forge that uses them declares `schema: 2` (see *Forge layout*). The read-only catalogue — `recipes`, `ingredients` and `targets` with the capability matrix — works too, and a workspace can name its Forge by git URL with an optional `ref`, read from a per-machine cache, with a lock that records the ref, commit, recipes and targets it was generated from (see *Remote Forge*). `add recipe` / `remove recipe` change a workspace's recipe choice in `craftar.yaml`, refusing an edit that would not resolve. A writing `sync` records each workspace in a per-machine registry, and `craftar workspaces` lists them all with their status (see *Workspace registry*). `craftar forge impact` lists the workspaces registered on this machine that read a Forge (by path, by a git remote of the clone, or through another clone of the same remote) with what their next sync would do against it, and `forge unify` plans them before and after its writes, names the ones its warnings concern, and with `--prune-recipes` deletes a recipe left identical to its sibling once every one of them plans the same. `craftar doctor` reports, one line per finding, what is off on this machine and in this workspace. Everything else in the spec (profiles with IDP/PM-tool integrations, local services, `dotnet new` project templates, `craftar ui`, `craftar mcp`) is not built yet.
 
 ## The idea in one paragraph
 
@@ -79,8 +79,9 @@ From then on, change a rule in `forge/ingredients/rules/<name>/rule.md`, run `cr
 | `craftar add recipe <name...> [--replace] [--workspace <dir>] [--offline]` | Adds recipes to the workspace's choice: deletes each from `craftar.yaml`'s `recipes.remove` when it is there, and appends it to `recipes.add` when the workspace does not resolve it yet. A recipe that would share a `slot` with another resolved one is refused, naming the holder; `--replace` removes every other holder in the same edit, as `remove recipe` would. Names apply in order, all or nothing, and the edit is written only once the workspace resolves and plans with it. Writes `craftar.yaml` only — in place, keeping its comments and style (a document the YAML writer does not reproduce byte for byte, such as `{ add: [] }` with inner spaces or a column-aligned comment, is refused: reformat it by hand) — and never syncs: it prints the net edit, the new recipe order and what the next `sync` would do (`next sync: 1 new, 1 orphan — run \`craftar sync\``), or `nothing to change`. Refused when `craftar.local.yaml` sets `recipes` (its lists would replace the edited ones). |
 | `craftar remove recipe <name...> [--workspace <dir>] [--offline]` | Removes recipes from the workspace's choice: deletes each from `recipes.add`, and appends a profile recipe to `recipes.remove`. A recipe another one still brings in through `extends` is refused, naming the top-level recipe to remove instead. A name the Forge does not hold is accepted only to clean it out of `recipes.add` or `recipes.remove`. Same output, refusals and all-or-nothing rule as `add recipe`. |
 | `craftar forge variants [--forge <dir> \| --workspace <dir>] [--json]` | Lists ingredients that have variants, nearest first, with the profile each came from, its distance to the base and its hunks counted by suggested class (`[1 evolution · 2 block]`), then any variant whose base is missing from the Forge. Read-only; exits 0 either way. `--json` prints `{groups, orphans}`; each variant carries `classes: {evolution, value, block}`, which add up to `distance.hunks`. |
+| `craftar forge impact [--forge <dir> \| --workspace <dir>] [--json]` | Lists every workspace registered on this machine that reads this Forge — by its path, by a git remote of this clone, or through another clone of the same remote — with what its next `sync` would do against the Forge as it is now: a header, then one line per workspace sorted by path (`unchanged`, the next-sync counts, `missing` or `error: <message>`; ` · after push (<remote>)` for a remote match, ` · after push and pull (<dir>)` for a clone match; `, pins <ref>` when the workspace pins a `ref`). When no registered workspace reads this Forge, the short header (`craftar forge impact — <forge>`) then one line: `no registered workspace reads this Forge on this machine`; when the registry is off, the short header then one line: `the registry is off (CRAFTAR_NO_REGISTRY)`; when the registry cannot be read, exits 1. A workspace whose Forge is remote is refused with the same message as `forge unify`. A remote URL holding credentials is not matched — one warning per remote, `remote <name> of <dir> holds credentials in its URL — not matched` (the URL is never printed). Read-only; no fetch. `--json` is a contract: `{forge, registry, workspaces: [{path, profile, match, via, ref, state, counts, error}]}` (every key always present). |
 | `craftar forge diff <type/name> [--against <profile>] [--forge <dir> \| --workspace <dir>] [--json]` | Shows the differences between a base ingredient and each of its variants: a header carrying the same distance `forge variants` reports, then hunk by hunk, each with a suggested class and reason — `evolution` (one side is newer text), `value` (an identifier-like token swapped in shared prose, with a suggested `param.<slug>`) or `block` (lines only one side has) — then the files that exist on only one side. A suggestion never decides anything. It compares the raw Forge text, section marker lines included, so a base with markers shows them as hunks against a variant that has none. Read-only. `--json` prints an array of `{ref, profile, distance, diff}`; each hunk carries `suggestion: {class, reason, tokens?}` next to its `kind`. |
-| `craftar forge unify <type/name> --profile <p> (--take base\|variant \| --plan <file> \| --save-plan <file>) [--forge <dir> \| --workspace <dir>] [--json]` | Resolves one variant back into its base, hunk by hunk. `--save-plan` writes a reviewable plan with every decision set to `keep`, each hunk annotated with its suggested class (which `--plan` ignores) and, for a `value` hunk, a pre-filled `params` list (`token` → suggested `key`); on a `block` hunk, a pre-filled `section: { name }` from the Markdown heading above (or `section-<n>`); and on a hunk touching a section the base already has, that section's name. It refuses a path that resolves inside the Forge (after `..` segments and symlinks) and a path that already exists, so it never overwrites a Forge file or a plan you already edited; it writes nothing else. A hunk set to `take: param` turns each listed token into `{{key}}` in the base, declares the base's text as the key's default in the base's `ingredient.yaml` and writes the variant's text into the variant profile's `profile.yaml` `params` — only after proving that both the base's and the variant's text render back exactly, and only when the same plan resolves the variant; it refuses (with the Forge untouched) a key another layer, profile or ingredient already uses, a variant another profile also uses, a whitespace-only difference, and a YAML file that would not round-trip unchanged. A hunk set to `take: section` (with `section: { name, lines? }`) wraps the base's lines in section markers as the default and writes the variant's lines into the variant profile's `sections` — consecutive hunks with one name form one section, `lines: "<from>-<to>"` widens it over equal base lines, and hunks inside a section the base already has only write the profile value; it is proved (both sides render back exactly) and needs the same plan to resolve the variant; `take: param` and `take: section` may share a plan, never a hunk. It refuses (Forge untouched) a `take: param` or `take: section` on a file no target emits, a variant that holds markers, a profile that already sets that section (another profile for a new section, or the variant's profile with other content), a span that cuts a hunk or crosses another section, a span that covers a hunk outside the run (including `take: base` on a hunk inside a section the plan fills), a hunk mixing lines inside and outside an existing section, and a span reaching a missing final newline; when it adds a section to a Forge still at `schema: 1` it sets `schema: 2` in `craftar.forge.yaml` in place (refused if the file does not round-trip). `--plan` applies an edited plan, refusing when it is not for this exact ingredient/profile or either side's fingerprint moved since it was saved. `--take base\|variant` resolves every decision to that side. Writes the merged base and, once every difference is resolved, removes the variant and rewrites every recipe reference to it (`ingredients`) to name the base. It never deletes a recipe and never edits an `extends`; it edits a profile only to write the values of a `take: param` or `take: section` extraction into the variant's own profile, and otherwise never: a `<recipe>--<profile>` left identical to `<recipe>` is reported as a warning, to be removed by hand after repointing the lists that name it — unify does not, because a workspace or an `extends` chain may also name `<recipe>` and the recipe order or param precedence would change. Unify cannot reach workspaces, so a removed variant is reported as a warning for any `craftar.yaml` that disables it in `overrides.ingredients.disable`. Every recipe rewrite is checked before the first write, so one that cannot land (a reference behind a YAML alias) is refused with the Forge untouched; a failure after writing began (an I/O error, a locked file) names the paths already touched and the `git checkout` / `git clean` commands that undo them. A merge never adds, removes or changes a section marker other than the sections the plan declares; a plan or `--take variant` that would is refused before the first write — take `base` for the marker lines, or `take: section` to fill the section; the citation checks of `take: param` also read the profiles' section values, which can cite `{{key}}`. `ingredient.yaml` is never merged: when the two sides' metadata differs (beyond `name`, `as` and `origin`), the variant stays unresolved and the differing fields are named — edit it by hand, or `--take base` to discard the variant, metadata included. Requires a clean git checkout in the Forge with at least one commit (`--save-plan` excepted) — the Forge has no lock, so git is the undo. It also refuses when any path it would overwrite or delete (the base, the variant, the recipe files it rewrites, the profile a parameter or section extraction edits, `craftar.forge.yaml` when it is bumped) is ignored, untracked, modified, or flagged skip-worktree or assume-unchanged in the index, since git could not restore it. `--json` prints `{base, profile, resolved, written, removed, unresolved, variantRemoved, recipes: {rewritten, identicalToSibling}, metaDiffers, params, profileEdited, sections, manifestEdited, warnings}` for `--take`/`--plan` (every key always present, `[]` when empty), or `{base, profile, plan, unresolved}` for `--save-plan`. |
+| `craftar forge unify <type/name> --profile <p> (--take base\|variant \| --plan <file> \| --save-plan <file>) [--no-impact] [--prune-recipes] [--forge <dir> \| --workspace <dir>] [--json]` | Resolves one variant back into its base, hunk by hunk. `--save-plan` writes a reviewable plan with every decision set to `keep`, each hunk annotated with its suggested class (which `--plan` ignores) and, for a `value` hunk, a pre-filled `params` list (`token` → suggested `key`); on a `block` hunk, a pre-filled `section: { name }` from the Markdown heading above (or `section-<n>`); and on a hunk touching a section the base already has, that section's name. It refuses a path that resolves inside the Forge (after `..` segments and symlinks) and a path that already exists, so it never overwrites a Forge file or a plan you already edited; it writes nothing else. A hunk set to `take: param` turns each listed token into `{{key}}` in the base, declares the base's text as the key's default in the base's `ingredient.yaml` and writes the variant's text into the variant profile's `profile.yaml` `params` — only after proving that both the base's and the variant's text render back exactly, and only when the same plan resolves the variant; it refuses (with the Forge untouched) a key another layer, profile or ingredient already uses, a variant another profile also uses, a whitespace-only difference, and a YAML file that would not round-trip unchanged. A hunk set to `take: section` (with `section: { name, lines? }`) wraps the base's lines in section markers as the default and writes the variant's lines into the variant profile's `sections` — consecutive hunks with one name form one section, `lines: "<from>-<to>"` widens it over equal base lines, and hunks inside a section the base already has only write the profile value; it is proved (both sides render back exactly) and needs the same plan to resolve the variant; `take: param` and `take: section` may share a plan, never a hunk. It refuses (Forge untouched) a `take: param` or `take: section` on a file no target emits, a variant that holds markers, a profile that already sets that section (another profile for a new section, or the variant's profile with other content), a span that cuts a hunk or crosses another section, a span that covers a hunk outside the run (including `take: base` on a hunk inside a section the plan fills), a hunk mixing lines inside and outside an existing section, and a span reaching a missing final newline; when it adds a section to a Forge still at `schema: 1` it sets `schema: 2` in `craftar.forge.yaml` in place (refused if the file does not round-trip). `--plan` applies an edited plan, refusing when it is not for this exact ingredient/profile or either side's fingerprint moved since it was saved. `--take base\|variant` resolves every decision to that side. Writes the merged base and, once every difference is resolved, removes the variant and rewrites every recipe reference to it (`ingredients`) to name the base. It never edits an `extends`, and deletes a recipe or repoints a profile's recipe list only under `--prune-recipes`; otherwise it edits a profile only to write the values of a `take: param` or `take: section` extraction into the variant's own profile. A `<recipe>--<profile>` left identical to `<recipe>` is reported as a warning unless pruned; `--prune-recipes` deletes such a recipe and repoints every profile that names it — the candidates are found in a dry pass, their profile files join the git check, and pruning is refused when another recipe's `extends` names the candidate, when the registry is off or unreadable, when the registry did not check every workspace (no registered workspace, a missing entry, one whose configuration did not load), when a registered workspace's plan throws, or when a workspace's `recipes.add` or `recipes.remove` names the suffixed recipe, or when a profile's recipe list cannot be edited in place (a YAML document that does not round-trip); each remaining candidate is deleted and its profiles repointed only when every registered workspace plans the same files (the same paths and the same bytes) with and without it — any difference refuses that one candidate, and the Forge stays as `unify` left it. `--prune-recipes` with `--no-impact` is refused before anything is read. `unify` plans every registered workspace of the Forge before its writes and again after them, and reports one `impact:` line per workspace — `no effect`, `1 file changes — <path>` / `<n> files change — <paths>`, `missing` or `error: <message>` (each line carries the same ` · after push (<remote>)` / ` · after push and pull (<dir>)` / `, pins <ref>` suffix as `forge impact`) — replacing the `next: run craftar status …` hint when at least one workspace was checked; an unreadable registry is one warning. The three warnings — a removed variant a workspace may name in `overrides.ingredients.disable`, a new parameter a workspace's `overrides.params` now overrides, a new section a workspace's `overrides.sections` now fills — now name the concerned workspaces with the file that holds the entry, vanish when the registry proves none is concerned, or keep their previous text with a reason in parentheses (the registry could not check N workspaces, no workspace registered, registry off, registry unreadable). `--no-impact` skips both impact passes and restores the previous warning text (the identical-to-sibling warning keeps its new ending). Every recipe rewrite is checked before the first write, so one that cannot land (a reference behind a YAML alias) is refused with the Forge untouched; a failure after writing began (an I/O error, a locked file) names the paths already touched and the `git checkout` / `git clean` commands that undo them. A merge never adds, removes or changes a section marker other than the sections the plan declares; a plan or `--take variant` that would is refused before the first write — take `base` for the marker lines, or `take: section` to fill the section; the citation checks of `take: param` also read the profiles' section values, which can cite `{{key}}`. `ingredient.yaml` is never merged: when the two sides' metadata differs (beyond `name`, `as` and `origin`), the variant stays unresolved and the differing fields are named — edit it by hand, or `--take base` to discard the variant, metadata included. Requires a clean git checkout in the Forge with at least one commit (`--save-plan` excepted) — the Forge has no lock, so git is the undo. It also refuses when any path it would overwrite or delete (the base, the variant, the recipe files it rewrites, the profile a parameter or section extraction edits, the profiles `--prune-recipes` repoints, `craftar.forge.yaml` when it is bumped) is ignored, untracked, modified, or flagged skip-worktree or assume-unchanged in the index, since git could not restore it. `--json` prints `{base, profile, resolved, written, removed, unresolved, variantRemoved, recipes: {rewritten, identicalToSibling, pruned, kept}, metaDiffers, params, profileEdited, sections, manifestEdited, impact, warnings}` for `--take`/`--plan` (every key always present, `[]` when empty), or `{base, profile, plan, unresolved}` for `--save-plan`. |
 
 All commands but `workspaces` take `--workspace <dir>` (default: current directory); the `forge` commands, `recipes` and `ingredients` also take `--forge <dir>` as an alternative to it — a directory: a URL there is refused — and `targets` needs no Forge. With a remote Forge (see *Remote Forge*), `status`, `sync`, `diff`, `explain`, `ls`, `recipes`, `ingredients`, `add recipe`, `remove recipe`, `forge variants` and `forge diff` fetch first and take `--offline` to use the cached copy; `targets` never fetches; `forge unify` refuses a workspace whose Forge is remote — clone it and pass `--forge <dir>`; `import --write-config` keeps a remote `forge:` and sets only `profile` and `targets`.
 
@@ -285,14 +286,23 @@ A writing `sync` records the workspace in `$CRAFTAR_HOME/registry.json` (`~/.cra
 - **`CRAFTAR_NO_REGISTRY`** — read the name as "no registry", the way `NO_COLOR` means "no colour". Set to any non-empty value, it turns the registry off: `sync` neither reads nor writes it, and `craftar workspaces` exits 1. An empty value counts as unset. Set it on CI runners and throwaway checkouts, whose directories would only pile up as `missing`.
 - **A registry that cannot be written** (an unwritable `$CRAFTAR_HOME`, a busy lock after 60 s, a file this craftar cannot read) leaves `sync`'s files, lock and exit code as they would be, and adds one warning. Craftar never overwrites a registry it cannot read: repair or remove it yourself.
 - The registry is per machine: paths are native and absolute, and SSH and HTTPS spellings of one remote are two Forges in it, as they are two cache entries.
+- **The registry also tells a Forge its workspaces**: `forge impact` and `forge unify` read it (never write it); a workspace synced on CI, another machine or under `CRAFTAR_NO_REGISTRY` is not known to them, which is why `--prune-recipes` says so.
 
 ## Roadmap (from the functional spec)
 
-Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock); the workspace registry and `craftar workspaces`; `craftar add recipe` / `remove recipe`; `craftar init` with flags; `craftar doctor`.
+Phase 0 (this): schema, import, sync/status/diff/explain, claude-code + kiro + agents-md targets, lock, drift, orphans; the read-only catalogue (`recipes`, `ingredients`, `targets` with the capability matrix); remote Forge (git URL + `ref`, a per-machine cache, the schema 2 lock); the workspace registry and `craftar workspaces`; `craftar add recipe` / `remove recipe`; `craftar init` with flags; `craftar doctor`; `craftar forge impact` and `forge unify --prune-recipes`.
 Next: an interactive `craftar init` (choose the Forge and the profile); cloning a profile's repositories at init; profile-driven integrations (PM tool → MCP, IDP → MCP); `service` ingredients with compose fragments (`craftar services up`); `dotnet new` template registration; rulesync bridge for Codex/Kimi/Cursor specifics; `craftar docs validate`; GitHub Action and Azure Pipelines task around `sync --check`; `craftar ui`; `craftar mcp` + Claude Code / Agent Plugin packaging.
 
 ## Upgrading
 
+### to 0.16.0
+
+- **New command `craftar forge impact`**: lists every workspace registered on this machine that reads a Forge with what its next sync would do against it. Its `--json` output is a tooling contract.
+- **`forge unify` plans the registered workspaces of the Forge before and after writing**: `impact:` lines replace the `next:` hint when at least one workspace was checked; `--no-impact` restores the previous output except the identical-to-sibling warning's new ending; the three "unify cannot reach workspaces" warnings name the concerned workspaces, vanish when none is concerned and every workspace was checked, or gain the reason in parentheses.
+- **`forge unify --json` gains `impact` and `recipes.pruned` / `recipes.kept`** (additive; always present).
+- **New flag `--prune-recipes`**: deletes a recipe left identical to its sibling and repoints the profiles that name it, only when every registered workspace plans the same files.
+- **No byte change**: no emitter, `plan`, `status`, `sync` or lock changed. No workspace sees `update`. A prune changes `craftar.lock`'s `recipes` at the next `sync` of a workspace on that profile, and that workspace's registry entry (`recipes`, `stack`) with it.
+
 ### to 0.15.0
 
 - **New command `craftar doctor`**: reports, one line per finding, what is off on this machine and in this workspace. Its `--json` output is a tooling contract, like `status --json`.

package/dist/cli.js

@@ -6,6 +6,7 @@ import YAML from "yaml";
 import { importClaudeCode } from "./importers/claude-code.js";
 import { classifyForge } from "./core/remote.js";
 import { forget, listWorkspaces, prune, register, registryFile } from "./core/registry.js";
+import { forgeWorkspaces, planAll, nextSync, impactOf, concerned, refineRegistryState } from "./core/impact.js";
 import { runDoctor } from "./core/doctor.js";
 import { resolveHome } from "./core/home-lock.js";
 import { loadWorkspace, plan, readLock, status, apply, resolveForge, resolveForgeSource, WORKSPACE_FILE, LOCAL_FILE } from "./core/sync.js";
@@ -16,9 +17,9 @@ import { canonicalValue } from "./core/sections.js";
 import { renderDiff, NO_EOF_NEWLINE_MARKER } from "./core/diff.js";
 import { diffIngredients, listVariants, profileOf } from "./core/variants.js";
 import { hashNormalized, toLf, stripBom } from "./core/text.js";
-import { exists, gitDirty, gitIsRepo, gitUnheld } from "./core/forge.js";
+import { exists, gitDirty, gitIsRepo, gitUnheld, loadForge } from "./core/forge.js";
 import { fingerprintDir } from "./core/fingerprint.js";
-import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, } from "./core/unify.js";
+import { hunkAt, planFrom, applyPlan, writeUnified, checkRecipeCascade, rewriteRecipes, pruneCandidates, pruneRecipes, note, } from "./core/unify.js";
 import { checkParamWrites, writeParamFile } from "./core/param-writes.js";
 import { planInit } from "./core/init.js";
 import { editRecipesText, planRecipeEdit, recipeDiffLine } from "./core/recipe-edit.js";
@@ -33,7 +34,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.15.0");
+program.name("craftar").description("Craft, sync and convert AI-coding workspace harnesses.").version("0.16.0");
 /* ---------------------------------------------------------------- import */
 program
     .command("import")
@@ -869,6 +870,94 @@ forge
     const orphanNote = orphans.length ? `, ${orphans.length} orphan${orphans.length === 1 ? "" : "s"}` : "";
     console.log(`\n  ${groups.length} base${groups.length === 1 ? "" : "s"} with variants, ${total} variant${total === 1 ? "" : "s"} total${orphanNote}`);
 });
+forge
+    .command("impact")
+    .description("List every workspace registered on this machine that reads this Forge — by its path, by a git remote of this clone, or through another clone of the same remote — with what its next sync would do against the Forge as it is now. Read-only; no fetch")
+    .option("--forge <dir>", "Forge directory (instead of --workspace)")
+    .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
+    .option("--json", "machine-readable output", false)
+    .action(async (o) => {
+    const f = await resolveForge({
+        forge: o.forge,
+        workspace: o.workspace,
+        refuseRemote: (url) => `the Forge of this workspace is remote (${url}) — clone it and pass --forge <dir>`,
+    });
+    let fw;
+    try {
+        fw = await forgeWorkspaces(craftarHome(), f.root);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e));
+    }
+    warnStderr(fw.warnings);
+    const planned = await planAll(fw.workspaces, f);
+    const results = await Promise.all(planned.map((p) => nextSync(p)));
+    // Refine the registry state: "partial" when any entry is missing or stage-config error (spec 25 §3)
+    const registryState = refineRegistryState(fw.state, planned);
+    if (o.json) {
+        const workspaces = fw.workspaces.map((ws, i) => {
+            const r = results[i];
+            return {
+                path: ws.entry.path,
+                profile: ws.entry.profile,
+                match: ws.match,
+                via: ws.via,
+                ref: ws.ref,
+                state: r.state,
+                counts: r.counts,
+                error: r.error,
+            };
+        });
+        console.log(JSON.stringify({ forge: fw.realForge, registry: registryState, workspaces }, null, 2));
+        return;
+    }
+    // Text output
+    const parts = [];
+    const byMatch = {};
+    for (const ws of fw.workspaces)
+        byMatch[ws.match] = (byMatch[ws.match] ?? 0) + 1;
+    if (byMatch.path)
+        parts.push(`${byMatch.path} by path`);
+    if (byMatch.remote)
+        parts.push(`${byMatch.remote} by remote`);
+    if (byMatch.clone)
+        parts.push(`${byMatch.clone} by clone`);
+    if (fw.state === "none") {
+        console.log(`craftar forge impact — ${fw.realForge}`);
+        console.log(`  no registered workspace reads this Forge on this machine`);
+        return;
+    }
+    if (fw.state === "off") {
+        console.log(`craftar forge impact — ${fw.realForge}`);
+        console.log(`  the registry is off (CRAFTAR_NO_REGISTRY)`);
+        return;
+    }
+    const n = fw.workspaces.length;
+    console.log(`craftar forge impact — ${fw.realForge} · ${n} registered workspace${n === 1 ? "" : "s"} (${parts.join(", ")})`);
+    const maxPath = Math.max(...fw.workspaces.map((ws) => ws.entry.path.length));
+    const maxProfile = Math.max(...fw.workspaces.map((ws) => ws.entry.profile.length));
+    for (let i = 0; i < fw.workspaces.length; i++) {
+        const ws = fw.workspaces[i];
+        const r = results[i];
+        let stateStr;
+        if (r.state === "unchanged") {
+            stateStr = "unchanged";
+        }
+        else if (r.state === "changed") {
+            // Counts in NEXT_SYNC order
+            const countParts = NEXT_SYNC_STATES.map((k) => (r.counts[k] ? `${r.counts[k]} ${k}` : "")).filter(Boolean);
+            stateStr = countParts.join(", ");
+        }
+        else if (r.state === "missing") {
+            stateStr = "missing";
+        }
+        else {
+            stateStr = `error: ${r.error}`;
+        }
+        const suffix = matchSuffix(ws);
+        console.log(`  ${ws.entry.path.padEnd(maxPath)}  ${ws.entry.profile.padEnd(maxProfile)}  ${stateStr}${suffix}`);
+    }
+});
 forge
     .command("diff")
     .description("Show the distance and the differences between a base ingredient and each of its variants, each hunk with a suggested class (evolution, value, block) that never decides anything. Read-only")
@@ -930,10 +1019,16 @@ forge
     .option("--take <side>", "resolve every decision to base or variant")
     .option("--plan <file>", "apply the decisions in this plan file (a hunk may be take: param with its params list, or take: section with its section name)")
     .option("--save-plan <file>", "write a plan with every decision deferred, each hunk annotated with its suggested class (which --plan ignores), value hunks pre-filled with params, block hunks pre-filled with a section name, and hunks touching an existing section with its name, to a new file outside the Forge, and stop")
+    .option("--no-impact", "skip planning the registered workspaces of this Forge before and after the writes (the warnings then keep their previous text)")
+    .option("--prune-recipes", "delete each suffixed recipe the cascade leaves identical to its sibling and repoint the profiles that name it — only when every workspace registered on this machine plans byte for byte the same; needs the impact passes")
     .option("--forge <dir>", "Forge directory (instead of --workspace)")
     .option("--workspace <dir>", "workspace whose craftar.yaml names the Forge (default: .)")
     .option("--json", "machine-readable output", false)
     .action(async (ref, o) => {
+    // Spec 25 §4.4: --prune-recipes with --no-impact is refused before anything is read
+    if (o.pruneRecipes && !o.impact) {
+        fail("--prune-recipes needs the impact passes — drop --no-impact");
+    }
     const frontEnds = [o.take, o.plan, o.savePlan].filter((v) => v !== undefined);
     if (frontEnds.length !== 1)
         fail("pass exactly one of --take, --plan or --save-plan");
@@ -1048,6 +1143,10 @@ forge
     // Ruling 33, dry pass: every recipe `ingredients` rewrite the cascade will make is checked before
     // the first byte is written, so a refusal (an aliased reference) leaves the Forge untouched.
     const cascadeFiles = result.resolved ? await checkRecipeCascade(f, base.ref, variant.ref) : [];
+    // Spec 25 §4.4: prune candidates, computed in the dry pass
+    const candidates = o.pruneRecipes && result.resolved
+        ? await pruneCandidates(f, base.ref, variant.ref, o.profile)
+        : [];
     // Spec 09 & 12: the Forge-level rows and YAML edits for parameter and section extractions, rendered before any write.
     const paramWrites = result.params.length || result.sections.length
         ? await checkParamWrites(f, base, variant, o.profile, result.params, result.sections)
@@ -1056,7 +1155,9 @@ forge
     // check above cannot see ignored files (a Forge its enclosing repo ignores, an ignored file in
     // a variant) nor untracked ones under `status.showUntrackedFiles=no` — so every path this run
     // will overwrite or delete is checked on its own, before the first write.
-    const mustHold = [base.dir, ...(result.resolved ? [variant.dir, ...cascadeFiles] : []), ...(paramWrites?.mustHold ?? [])];
+    // Spec 25 §4.4: prune candidates' profile files join mustHold
+    const candidateProfiles = candidates.flatMap((c) => c.profiles.map((p) => p.abs));
+    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.
@@ -1066,6 +1167,25 @@ forge
             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")}`);
     }
+    let impactState = "skipped";
+    let impactEntries = [];
+    let impactBefore = [];
+    let impactWarnings = [];
+    let impactUnreadableReason = null;
+    if (o.impact) {
+        try {
+            const fw = await forgeWorkspaces(craftarHome(), f.root);
+            impactEntries = fw.workspaces;
+            impactWarnings = fw.warnings;
+            impactBefore = await planAll(fw.workspaces, f);
+            // Refine the state: "partial" when any before entry is missing or stage-config error
+            impactState = refineRegistryState(fw.state, impactBefore);
+        }
+        catch (e) {
+            impactState = "unreadable";
+            impactUnreadableReason = e instanceof Error ? e.message : String(e);
+        }
+    }
     // Order: merged files, then the recipe cascade, then removal of the variant directory
     // (Ruling 21) — a late failure leaves the variant in place, never a recipe naming a removed ingredient.
     // Spec 12 §6.7: the manifest is first when it moves to schema: 2; each prefix is emission-neutral.
@@ -1097,8 +1217,72 @@ forge
         // writing began: name what was touched and how git undoes it, and still exit 1.
         throw new Error(lateFailure(e, f.root, journal), { cause: e });
     }
+    // Spec 25 §4.2: after pass — planAll against the Forge as unify left it, then impactOf per entry
+    let impactAfter = [];
+    let impactResults = [];
+    if (o.impact && impactState !== "skipped" && impactState !== "unreadable" && impactEntries.length > 0) {
+        let afterForge = f;
+        try {
+            afterForge = await loadForge(f.root);
+        }
+        catch (e) {
+            // If loadForge fails, treat every entry as error with the actual message
+            const msg = e instanceof Error ? e.message : String(e);
+            for (let i = 0; i < impactEntries.length; i++) {
+                impactAfter.push({ kind: "error", stage: "plan", message: msg });
+            }
+        }
+        if (impactAfter.length === 0) {
+            impactAfter = await planAll(impactEntries, afterForge);
+        }
+        for (let i = 0; i < impactEntries.length; i++) {
+            impactResults.push(impactOf(impactBefore[i], impactAfter[i]));
+        }
+    }
+    // Spec 25 §4.4: prune step — after unify's writes and the after pass, prove and apply prunes
+    let pruneResult = { pruned: [], kept: [] };
+    if (o.pruneRecipes && candidates.length > 0) {
+        // Map the state: "skipped" cannot happen here (--prune-recipes requires --impact)
+        const pruneState = impactState === "unreadable" ? "unreadable" : impactState;
+        try {
+            pruneResult = await pruneRecipes(f.root, candidates, {
+                state: pruneState,
+                entries: impactEntries,
+                after: impactAfter,
+            });
+        }
+        catch (e) {
+            // A throw in pruneRecipes (e.g. loadForge fails) after unify's writes: name what was touched.
+            throw new Error(lateFailure(e, f.root, journal), { cause: e });
+        }
+        // Apply the prune writes
+        for (const p of pruneResult.pruned) {
+            try {
+                // Write profile files first, then delete the recipe file
+                for (const w of p.writes) {
+                    if (w.content !== null) {
+                        await note(journal, w.abs);
+                        await fs.writeFile(w.abs, w.content);
+                    }
+                    else {
+                        journal.push({ abs: w.abs, created: false });
+                        await fs.rm(w.abs, { force: true });
+                    }
+                }
+            }
+            catch (e) {
+                throw new Error(lateFailure(e, f.root, journal), { cause: e });
+            }
+        }
+    }
     // Ruling 28: a metadata difference leaves the variant in place; say which fields and why.
     const warnings = [];
+    // Spec 25 §4.2: warning for unreadable registry
+    if (impactUnreadableReason !== null) {
+        warnings.push(`the registry could not be read (${impactUnreadableReason}) — no workspace was checked`);
+    }
+    // Spec 25 §4.2: push warnings from forgeWorkspaces (credential lines)
+    warnings.push(...impactWarnings);
     if (result.metaDiffers.length) {
         warnings.push(`ingredient.yaml differs in ${result.metaDiffers.join(", ")} — unify cannot merge ingredient.yaml, so ${variant.ref} stays; ` +
             `resolve it by hand, or use --take base to discard the variant`);
@@ -1106,30 +1290,142 @@ forge
     // Ruling 42: a suffixed recipe left identical to its sibling is reported, never deleted — a
     // workspace's recipes.add or an extends chain may name the sibling, and removing the suffixed
     // one would shift recipe order or param precedence there.
+    // Spec 25 §4.4: only printed for candidates NOT pruned; without --prune-recipes, ends with a hint
     const suffix = `--${o.profile}`;
+    const prunedRecipes = new Set(pruneResult.pruned.map((p) => p.recipe));
     for (const rn of cascade.identicalToSibling) {
+        // Skip if this was pruned
+        if (prunedRecipes.has(rn))
+            continue;
         const sibling = rn.slice(0, -suffix.length);
-        warnings.push(`recipe ${rn} is now identical to ${sibling} — it can be removed by hand after repointing the profiles, extends and ` +
+        const baseText = `recipe ${rn} is now identical to ${sibling} — it can be removed by hand after repointing the profiles, extends and ` +
             `workspace recipes lists that name it; unify does not, because a workspace or an extends chain may also name ` +
-            `${sibling} and the recipe order or param precedence would change`);
+            `${sibling} and the recipe order or param precedence would change`;
+        // Without --prune-recipes: add the hint to rerun with it
+        const warning = o.pruneRecipes
+            ? baseText
+            : `${baseText} — or restore the Forge with git and rerun this unify with --prune-recipes`;
+        warnings.push(warning);
     }
-    // Ruling 38: `resolve()` matches overrides.ingredients.disable by ref, so once the variant ref
-    // is gone a workspace that disabled it gets the base back, enabled, with no error.
-    // Spec 09 W1: what a parameter extraction cannot check from inside the Forge (W2 went with spec 10).
+    // Spec 25 §4.3: helper to build conditional warnings based on registry state and concerned workspaces
+    const unchecked = impactBefore.filter((p) => p.kind === "missing" || (p.kind === "error" && p.stage === "config")).length;
+    const reach = (text, test) => {
+        // --no-impact → today's text
+        if (!o.impact)
+            return `${text}; unify cannot reach workspaces`;
+        const c = concerned(impactBefore, impactEntries, test);
+        // concerned non-empty → name them
+        if (c.concerned.length > 0) {
+            const names = c.concerned.map((w) => `${w.path} (${w.file})`).join(", ");
+            const uncheckedNote = c.unchecked > 0 ? ` (the registry could not check ${c.unchecked} workspace${c.unchecked > 1 ? "s" : ""})` : "";
+            return `${text} — concerned: ${names}${uncheckedNote}`;
+        }
+        // none concerned and registry state read → no warning
+        if (impactState === "read")
+            return null;
+        // otherwise → today's text plus suffix by state
+        let stateSuffix;
+        switch (impactState) {
+            case "partial":
+                stateSuffix = ` (the registry could not check ${unchecked} workspace${unchecked > 1 ? "s" : ""})`;
+                break;
+            case "none":
+                stateSuffix = " (no workspace of this Forge is registered on this machine)";
+                break;
+            case "off":
+                stateSuffix = " (the registry is off)";
+                break;
+            case "unreadable":
+                stateSuffix = " (the registry could not be read)";
+                break;
+            default:
+                stateSuffix = "";
+        }
+        return `${text}; unify cannot reach workspaces${stateSuffix}`;
+    };
+    // Spec 09 W1: a new parameter may override a workspace's overrides.params
     for (const e of result.params.filter((p) => !p.reused)) {
-        warnings.push(`${e.key} is now a parameter of ${base.ref} — a workspace that sets overrides.params.${e.key} (craftar.yaml or ` +
-            `craftar.local.yaml) now overrides ${base.ref} too; unify cannot reach workspaces`);
+        const text = `${e.key} is now a parameter of ${base.ref} — a workspace that sets overrides.params.${e.key} (craftar.yaml or ` +
+            `craftar.local.yaml) now overrides ${base.ref} too`;
+        const testW1 = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.params !== "object" || ov.params === null)
+                return false;
+            return Object.hasOwn(ov.params, e.key);
+        };
+        const warn = reach(text, testW1);
+        if (warn !== null)
+            warnings.push(warn);
     }
-    // Spec 12 W3: a new section's name may be cited by a workspace's overrides.sections that was inert until now.
+    // Spec 12 W3: a new section may be filled by a workspace's overrides.sections
     for (const s of result.sections.filter((sec) => !sec.existing)) {
-        warnings.push(`${s.name} is now a section of ${base.ref} — a workspace that sets overrides.sections.${s.key}.${s.name} (craftar.yaml or ` +
-            `craftar.local.yaml) now applies there; unify cannot reach workspaces`);
+        const text = `${s.name} is now a section of ${base.ref} — a workspace that sets overrides.sections.${s.key}.${s.name} (craftar.yaml or ` +
+            `craftar.local.yaml) now applies there`;
+        const testW3 = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.sections !== "object" || ov.sections === null)
+                return false;
+            const sec = ov.sections;
+            if (!Object.hasOwn(sec, s.key))
+                return false;
+            const keyObj = sec[s.key];
+            if (typeof keyObj !== "object" || keyObj === null)
+                return false;
+            return Object.hasOwn(keyObj, s.name);
+        };
+        const warn = reach(text, testW3);
+        if (warn !== null)
+            warnings.push(warn);
     }
+    // Ruling 38: a removed variant may be disabled by a workspace's overrides.ingredients.disable
     if (variantRemoved) {
-        warnings.push(`${variant.ref} was removed — a workspace that disables it in overrides.ingredients.disable (craftar.yaml or craftar.local.yaml) ` +
-            `must now name ${base.ref}, or the base comes back enabled; unify cannot reach workspaces`);
+        const text = `${variant.ref} was removed — a workspace that disables it in overrides.ingredients.disable (craftar.yaml or craftar.local.yaml) ` +
+            `must now name ${base.ref}, or the base comes back enabled`;
+        const testDisable = (doc) => {
+            if (typeof doc !== "object" || doc === null)
+                return false;
+            const d = doc;
+            if (typeof d.overrides !== "object" || d.overrides === null)
+                return false;
+            const ov = d.overrides;
+            if (typeof ov.ingredients !== "object" || ov.ingredients === null)
+                return false;
+            const ing = ov.ingredients;
+            if (!Array.isArray(ing.disable))
+                return false;
+            return ing.disable.includes(variant.ref);
+        };
+        const warn = reach(text, testDisable);
+        if (warn !== null)
+            warnings.push(warn);
+    }
+    // Spec 25 §4.4: when at least one recipe was pruned, add coverage warning
+    if (pruneResult.pruned.length > 0) {
+        const n = impactEntries.length;
+        warnings.push(`pruned against the ${n} workspace${n === 1 ? "" : "s"} registered on this machine — a workspace synced elsewhere (CI, another machine, CRAFTAR_NO_REGISTRY) is not covered`);
     }
     if (o.json) {
+        // Spec 25 §4.2: impact array in JSON output
+        const impact = impactResults.map((r, i) => ({
+            path: impactEntries[i].entry.path,
+            profile: impactEntries[i].entry.profile,
+            match: impactEntries[i].match,
+            via: impactEntries[i].via,
+            ref: impactEntries[i].ref,
+            state: r.state,
+            files: r.files,
+            error: r.error,
+        }));
         return console.log(JSON.stringify({
             base: base.ref,
             profile: o.profile,
@@ -1143,6 +1439,8 @@ forge
             recipes: {
                 rewritten: cascade.rewritten,
                 identicalToSibling: cascade.identicalToSibling,
+                pruned: pruneResult.pruned.map((p) => ({ recipe: p.recipe, sibling: p.sibling, profiles: p.profiles })),
+                kept: pruneResult.kept,
             },
             metaDiffers: result.metaDiffers,
             // Spec 09 §4.5: only what this run wrote — [] when every key was already declared and valued.
@@ -1160,6 +1458,8 @@ forge
             manifestEdited: paramWrites?.manifest !== null && paramWrites?.manifest !== undefined,
             profileEdited: paramWrites?.profile ? path.relative(f.root, paramWrites.profile.abs).split(path.sep).join("/") : null,
             warnings,
+            // Spec 25 §4.2: always present, [] when no workspace was checked
+            impact,
         }, null, 2));
     }
     console.log(pc.bold(`craftar forge unify ${ref} ↔ ${o.profile}`));
@@ -1190,9 +1490,42 @@ forge
     if (cascade.identicalToSibling.length) {
         console.log(`  recipes now identical to a sibling: ${cascade.identicalToSibling.join(", ")}`);
     }
+    // Spec 25 §4.4: pruned and kept recipes, after the identical-to-sibling line
+    for (const p of pruneResult.pruned) {
+        console.log(`  pruned recipe ${p.recipe} → ${p.sibling} (${p.profiles.join(", ")})`);
+    }
+    for (const k of pruneResult.kept) {
+        console.log(`  kept recipe ${k.recipe} — ${k.reason}`);
+    }
     for (const w of warnings)
         console.log(`  ${pc.yellow("warn")} ${w}`);
-    console.log(`  next: run \`craftar status --workspace <dir>\` in a workspace on profile ${o.profile} to see what moved`);
+    // Spec 25 §4.2: impact lines, one per workspace, with suffix format
+    for (let i = 0; i < impactResults.length; i++) {
+        const ws = impactEntries[i];
+        const r = impactResults[i];
+        let stateStr;
+        if (r.state === "no-effect") {
+            stateStr = "no effect";
+        }
+        else if (r.state === "changed") {
+            const n = r.files.length;
+            stateStr = n === 1 ? `1 file changes — ${r.files[0]}` : `${n} files change — ${r.files.join(", ")}`;
+        }
+        else if (r.state === "missing") {
+            stateStr = "missing";
+        }
+        else {
+            stateStr = `error: ${r.error}`;
+        }
+        const impactSuffix = matchSuffix(ws);
+        console.log(`  impact: ${ws.entry.path} (${ws.entry.profile}) ${stateStr}${impactSuffix}`);
+    }
+    // Spec 25 §4.2: the next: hint is printed only when no workspace was checked
+    // (every entry missing/stage-config error, or no entries, or --no-impact, or unreadable)
+    const someChecked = impactBefore.some((p) => p.kind !== "missing" && !(p.kind === "error" && p.stage === "config"));
+    if (!someChecked) {
+        console.log(`  next: run \`craftar status --workspace <dir>\` in a workspace on profile ${o.profile} to see what moved`);
+    }
 });
 program.parseAsync().catch((e) => fail(e instanceof Error ? e.message : String(e)));
 /* ---------------------------------------------------------------- helpers */
@@ -1272,6 +1605,20 @@ function warnStderr(warnings) {
     for (const w of warnings)
         console.error(`${pc.yellow("warn")} ${w}`);
 }
+/**
+ * Spec 25 §4.1–§4.2: the suffix format for a workspace that is not a path match.
+ * Used by both `forge impact` and `forge unify` so the format is shared.
+ */
+function matchSuffix(ws) {
+    let suffix = "";
+    if (ws.match === "remote")
+        suffix = ` · after push (${ws.via})`;
+    if (ws.match === "clone")
+        suffix = ` · after push and pull (${ws.via})`;
+    if (ws.ref)
+        suffix += `, pins ${ws.ref}`;
+    return suffix;
+}
 /** The header line naming a remote Forge (spec 13 §4.1); null for a path Forge, whose headers keep their shape. */
 function forgeLine(ws, lock) {
     const o = ws.origin;