@monte3l/groundwork 1.0.0-rc.4 → 1.0.0-rc.5

package/dist/customize-paths.d.ts

@@ -1,7 +1,8 @@
 /**
- * The skill's entry file: the one payload file that lives under the plugin
- * source's `skills/customize/` (every other one lives under its `src/`), and
- * the one whose presence makes Claude Code load the skill -- which is why
+ * The skill's entry file: it lives under the plugin source's
+ * `skills/customize/` beside {@link CUSTOMIZE_SKILL_STEP_FILE_NAMES} (the
+ * backing-data files live under its `src/`), and it is the one payload file
+ * whose presence makes Claude Code load the skill -- which is why
  * {@link CUSTOMIZE_SKILL_WRITE_ORDER} writes it last.
  *
  * @example
@@ -12,6 +13,24 @@
  * ```
  */
 export declare const CUSTOMIZE_SKILL_ENTRY_FILE = "SKILL.md";
+/**
+ * The step files `SKILL.md` delegates to (Step 0's adopt-mode reconcile and
+ * Step 3's Round 1), sourced from the plugin's `skills/customize/` beside
+ * {@link CUSTOMIZE_SKILL_ENTRY_FILE}. Like the backing-data files, they are
+ * written before `SKILL.md`, so a loadable `SKILL.md` never sits beside a
+ * missing step file.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_STEP_FILE_NAMES } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_STEP_FILE_NAMES[0]; // "step-0-reconcile.md"
+ * ```
+ */
+export declare const CUSTOMIZE_SKILL_STEP_FILE_NAMES: readonly [
+    "step-0-reconcile.md",
+    "step-3-round-1.md"
+];
 /**
  * Every payload file's name inside an installed copy of the skill.
  *
@@ -22,19 +41,28 @@ export declare const CUSTOMIZE_SKILL_ENTRY_FILE = "SKILL.md";
  * CUSTOMIZE_SKILL_FILE_NAMES.includes("SKILL.md"); // true
  * ```
  */
-export declare const CUSTOMIZE_SKILL_FILE_NAMES: readonly ["SKILL.md", "kind-facet-map.ts", "domain-map.ts", "pack-map.ts", "plugin-map.ts"];
+export declare const CUSTOMIZE_SKILL_FILE_NAMES: readonly [
+    "SKILL.md",
+    "kind-facet-map.ts",
+    "domain-map.ts",
+    "pack-map.ts",
+    "plugin-map.ts",
+    "step-0-reconcile.md",
+    "step-3-round-1.md"
+];
 /**
- * The order an install writes the payload in: every backing-data file
- * first, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails part-way
- * (and whose rollback cannot remove everything) therefore never leaves a
- * loadable `SKILL.md` beside missing or stale data files -- given the
- * precondition that no `SKILL.md` already sits at the destination. Wherever
- * an install replaces existing entries -- fresh mode's
+ * The order an install writes the payload in: every backing-data file, then
+ * every step file, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails
+ * part-way (and whose rollback cannot remove everything) therefore never
+ * leaves a loadable `SKILL.md` beside missing or stale data or step files --
+ * given the precondition that no `SKILL.md` already sits at the destination.
+ * Wherever an install replaces existing entries -- fresh mode's
  * `.claude/skills/customize/` (a `--force` re-run over an earlier install)
  * and the CLI-owned `.groundwork/customize/` -- `plugin.ts` establishes that
  * precondition by removing any existing `SKILL.md` entry before the first
- * data file is rewritten. Adopt mode's additive `.claude/skills/customize/`
- * install only ever writes there when no `SKILL.md` entry exists.
+ * data or step file is rewritten. Adopt mode's additive
+ * `.claude/skills/customize/` install only ever writes there when no
+ * `SKILL.md` entry exists.
  *
  * @example
  * ```ts
@@ -43,7 +71,15 @@ export declare const CUSTOMIZE_SKILL_FILE_NAMES: readonly ["SKILL.md", "kind-fac
  * CUSTOMIZE_SKILL_WRITE_ORDER.at(-1); // "SKILL.md"
  * ```
  */
-export declare const CUSTOMIZE_SKILL_WRITE_ORDER: readonly ["kind-facet-map.ts", "domain-map.ts", "pack-map.ts", "plugin-map.ts", "SKILL.md"];
+export declare const CUSTOMIZE_SKILL_WRITE_ORDER: readonly [
+    "kind-facet-map.ts",
+    "domain-map.ts",
+    "pack-map.ts",
+    "plugin-map.ts",
+    "step-0-reconcile.md",
+    "step-3-round-1.md",
+    "SKILL.md"
+];
 /**
  * The fresh-mode destination -- and adopt mode's, when nothing is there yet
  * or an earlier install was interrupted before its `SKILL.md` -- as path
@@ -63,7 +99,7 @@ export declare const CLAUDE_DEST_SEGMENTS: readonly [".claude", "skills", "custo
  * project root. Used whenever {@link CLAUDE_DEST_SEGMENTS} cannot be written
  * additively: a project-owned entry under any of the skill's payload names
  * that is not this CLI's current copy (a differing file, a symlink, a
- * directory, a `SKILL.md` without its data), or a component of
+ * directory, a `SKILL.md` without its data or step files), or a component of
  * `.claude/skills/customize` that is a symlink or not a directory.
  *
  * @example
@@ -85,7 +121,7 @@ export declare const GROUNDWORK_DEST_SEGMENTS: readonly [".groundwork", "customi
  * import { plannedCustomizeSkillPaths } from "./customize-paths.js";
  *
  * plannedCustomizeSkillPaths();
- * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/plugin-map.ts"]
+ * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/step-3-round-1.md"]
  * ```
  */
 export declare function plannedCustomizeSkillPaths(): readonly string[];

package/dist/customize-paths.js

@@ -7,9 +7,10 @@
  */
 import { join } from "node:path";
 /**
- * The skill's entry file: the one payload file that lives under the plugin
- * source's `skills/customize/` (every other one lives under its `src/`), and
- * the one whose presence makes Claude Code load the skill -- which is why
+ * The skill's entry file: it lives under the plugin source's
+ * `skills/customize/` beside {@link CUSTOMIZE_SKILL_STEP_FILE_NAMES} (the
+ * backing-data files live under its `src/`), and it is the one payload file
+ * whose presence makes Claude Code load the skill -- which is why
  * {@link CUSTOMIZE_SKILL_WRITE_ORDER} writes it last.
  *
  * @example
@@ -27,6 +28,21 @@ const CUSTOMIZE_SKILL_DATA_FILE_NAMES = [
     "pack-map.ts",
     "plugin-map.ts",
 ];
+/**
+ * The step files `SKILL.md` delegates to (Step 0's adopt-mode reconcile and
+ * Step 3's Round 1), sourced from the plugin's `skills/customize/` beside
+ * {@link CUSTOMIZE_SKILL_ENTRY_FILE}. Like the backing-data files, they are
+ * written before `SKILL.md`, so a loadable `SKILL.md` never sits beside a
+ * missing step file.
+ *
+ * @example
+ * ```ts
+ * import { CUSTOMIZE_SKILL_STEP_FILE_NAMES } from "./customize-paths.js";
+ *
+ * CUSTOMIZE_SKILL_STEP_FILE_NAMES[0]; // "step-0-reconcile.md"
+ * ```
+ */
+export const CUSTOMIZE_SKILL_STEP_FILE_NAMES = ["step-0-reconcile.md", "step-3-round-1.md"];
 /**
  * Every payload file's name inside an installed copy of the skill.
  *
@@ -40,19 +56,21 @@ const CUSTOMIZE_SKILL_DATA_FILE_NAMES = [
 export const CUSTOMIZE_SKILL_FILE_NAMES = [
     CUSTOMIZE_SKILL_ENTRY_FILE,
     ...CUSTOMIZE_SKILL_DATA_FILE_NAMES,
+    ...CUSTOMIZE_SKILL_STEP_FILE_NAMES,
 ];
 /**
- * The order an install writes the payload in: every backing-data file
- * first, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails part-way
- * (and whose rollback cannot remove everything) therefore never leaves a
- * loadable `SKILL.md` beside missing or stale data files -- given the
- * precondition that no `SKILL.md` already sits at the destination. Wherever
- * an install replaces existing entries -- fresh mode's
+ * The order an install writes the payload in: every backing-data file, then
+ * every step file, {@link CUSTOMIZE_SKILL_ENTRY_FILE} last. A run that fails
+ * part-way (and whose rollback cannot remove everything) therefore never
+ * leaves a loadable `SKILL.md` beside missing or stale data or step files --
+ * given the precondition that no `SKILL.md` already sits at the destination.
+ * Wherever an install replaces existing entries -- fresh mode's
  * `.claude/skills/customize/` (a `--force` re-run over an earlier install)
  * and the CLI-owned `.groundwork/customize/` -- `plugin.ts` establishes that
  * precondition by removing any existing `SKILL.md` entry before the first
- * data file is rewritten. Adopt mode's additive `.claude/skills/customize/`
- * install only ever writes there when no `SKILL.md` entry exists.
+ * data or step file is rewritten. Adopt mode's additive
+ * `.claude/skills/customize/` install only ever writes there when no
+ * `SKILL.md` entry exists.
  *
  * @example
  * ```ts
@@ -63,6 +81,7 @@ export const CUSTOMIZE_SKILL_FILE_NAMES = [
  */
 export const CUSTOMIZE_SKILL_WRITE_ORDER = [
     ...CUSTOMIZE_SKILL_DATA_FILE_NAMES,
+    ...CUSTOMIZE_SKILL_STEP_FILE_NAMES,
     CUSTOMIZE_SKILL_ENTRY_FILE,
 ];
 /**
@@ -84,7 +103,7 @@ export const CLAUDE_DEST_SEGMENTS = [".claude", "skills", "customize"];
  * project root. Used whenever {@link CLAUDE_DEST_SEGMENTS} cannot be written
  * additively: a project-owned entry under any of the skill's payload names
  * that is not this CLI's current copy (a differing file, a symlink, a
- * directory, a `SKILL.md` without its data), or a component of
+ * directory, a `SKILL.md` without its data or step files), or a component of
  * `.claude/skills/customize` that is a symlink or not a directory.
  *
  * @example
@@ -106,7 +125,7 @@ export const GROUNDWORK_DEST_SEGMENTS = [".groundwork", "customize"];
  * import { plannedCustomizeSkillPaths } from "./customize-paths.js";
  *
  * plannedCustomizeSkillPaths();
- * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/plugin-map.ts"]
+ * // [".claude/skills/customize/SKILL.md", ..., ".groundwork/customize/step-3-round-1.md"]
  * ```
  */
 export function plannedCustomizeSkillPaths() {

package/dist/fs-guard.d.ts

@@ -12,7 +12,7 @@
  * endsWithRerunAdvice(message); // true
  * ```
  */
-export declare const FIX_AND_RERUN_ADVICE = "fix the cause and re-run the CLI";
+export declare const FIX_AND_RERUN_ADVICE: string;
 /**
  * Whether `message` already ENDS with "re-run the CLI" advice, in any
  * wording that ends that way (e.g. {@link assertNotSymlink}'s "remove it and
@@ -138,5 +138,5 @@ export declare function assertNotDirectory(path: string, advice: string): void;
  * assertNotSymlink("/work/app/package.json", FRESH_SYMLINK_ADVICE);
  * ```
  */
-export declare const FRESH_SYMLINK_ADVICE = "remove it, then retry the same command with --fresh --force added";
+export declare const FRESH_SYMLINK_ADVICE: string;
 //# sourceMappingURL=fs-guard.d.ts.map

package/dist/harness/rules.d.ts

@@ -59,7 +59,8 @@ export interface HarnessRule {
  * Model ids and aliases the rubric accepts: the current ids and aliases, plus
  * ids that were once listed here, kept until Anthropic deprecates them. The
  * ids follow Anthropic's models overview and model-deprecations pages
- * (retrieved 2026-10-01). A legacy id that was never listed here is
+ * (retrieved 2026-10-08): Haiku 5.5 (released 2026-10-07) is current, and
+ * Haiku 4.5 is legacy but still active. A legacy id that was never listed here is
  * deliberately not added, so the rule keeps nudging pins toward current
  * models. Bump alongside the `harness-guidance` refresh sweep;
  * `templates/core/bin/lib/harness-rules.mjs` carries the same list and the

package/dist/harness/rules.js

@@ -20,7 +20,8 @@ import { fieldList, fieldText, parseFrontmatter } from "./frontmatter.js";
  * Model ids and aliases the rubric accepts: the current ids and aliases, plus
  * ids that were once listed here, kept until Anthropic deprecates them. The
  * ids follow Anthropic's models overview and model-deprecations pages
- * (retrieved 2026-10-01). A legacy id that was never listed here is
+ * (retrieved 2026-10-08): Haiku 5.5 (released 2026-10-07) is current, and
+ * Haiku 4.5 is legacy but still active. A legacy id that was never listed here is
  * deliberately not added, so the rule keeps nudging pins toward current
  * models. Bump alongside the `harness-guidance` refresh sweep;
  * `templates/core/bin/lib/harness-rules.mjs` carries the same list and the
@@ -37,6 +38,7 @@ export const CURRENT_MODELS = [
     "claude-sonnet-5",
     "claude-sonnet-5-5",
     "claude-fable-5-1",
+    "claude-haiku-5-5",
     "claude-haiku-4-5",
     "claude-haiku-4-5-20251001",
 ];

package/dist/plugin.d.ts

@@ -89,20 +89,20 @@ export interface GuardedInstallResult {
  *   `fallbackCause` is `"component"` -- the entry (and any link target) is
  *   left untouched.
  * - Otherwise, if every payload file already there is a regular file
- *   matching what this CLI ships byte-for-byte: with all five present the
- *   result is `"already-present"` (nothing written); with no `SKILL.md` file
- *   (none at all, or an install interrupted before writing it) the missing
- *   files are written into `.claude/skills/customize/`, `SKILL.md` last,
- *   never rewriting or removing the correct ones.
+ *   matching what this CLI ships byte-for-byte: with every payload file
+ *   present the result is `"already-present"` (nothing written); with no
+ *   `SKILL.md` file (none at all, or an install interrupted before writing
+ *   it) the missing files are written into `.claude/skills/customize/`,
+ *   `SKILL.md` last, never rewriting or removing the correct ones.
  * - Anything else under a payload name (a differing file, a regular file
  *   that cannot be read, a symlink -- dangling or not -- a directory, a
- *   `SKILL.md` without its data; detected by `lstat`) is kept as the
- *   project's own: the skill is written to `.groundwork/customize/` instead,
- *   `fallbackReason` names that entry (saying so when it could not be read)
- *   and `fallbackCause` is `"entry"`. Adopt mode never guesses at a project
- *   entry it cannot compare, and the fallback does not guess either: it
- *   leaves that entry exactly as it was. Claude Code does not load a skill
- *   from there; the caller must say so.
+ *   `SKILL.md` without its data or step files; detected by `lstat`) is kept
+ *   as the project's own: the skill is written to `.groundwork/customize/`
+ *   instead, `fallbackReason` names that entry (saying so when it could not
+ *   be read) and `fallbackCause` is `"entry"`. Adopt mode never guesses at a
+ *   project entry it cannot compare, and the fallback does not guess either:
+ *   it leaves that entry exactly as it was. Claude Code does not load a
+ *   skill from there; the caller must say so.
  *
  * Writes into `.claude/skills/customize/` use `"wx"` only, so an entry that
  * appears there mid-install fails the run (rolled back) rather than being

package/dist/plugin.js

@@ -4,14 +4,14 @@
  * Installs the `/customize` skill into a bootstrapped or adopted project.
  * Claude Code's marketplace-based plugin installation is an interactive,
  * network-involving flow this offline CLI can't drive; instead this copies
- * the skill's SKILL.md plus its deterministic backing data directly into a
- * destination directory, so `/customize` works immediately with no further
- * setup step.
+ * the skill's SKILL.md, its step files and its deterministic backing data
+ * into a destination directory, so `/customize` works immediately with no
+ * further setup step.
  */
 import { lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { resolveAsset } from "./assets.js";
-import { CLAUDE_DEST_SEGMENTS, CUSTOMIZE_SKILL_ENTRY_FILE, CUSTOMIZE_SKILL_WRITE_ORDER, GROUNDWORK_DEST_SEGMENTS, } from "./customize-paths.js";
+import { CLAUDE_DEST_SEGMENTS, CUSTOMIZE_SKILL_ENTRY_FILE, CUSTOMIZE_SKILL_STEP_FILE_NAMES, CUSTOMIZE_SKILL_WRITE_ORDER, GROUNDWORK_DEST_SEGMENTS, } from "./customize-paths.js";
 import { assertNotSymlink, endsWithRerunAdvice, FIX_AND_RERUN_ADVICE, FRESH_RETRY, FRESH_SYMLINK_ADVICE, } from "./fs-guard.js";
 /** Resolves the plugin payload for a source checkout (`packages/plugin`) or a published tarball (`plugin/`). */
 function pluginDir() {
@@ -107,6 +107,14 @@ function errnoField(error, field) {
     const value = Reflect.get(error, field);
     return typeof value === "string" ? value : undefined;
 }
+/**
+ * The payload files sourced from the plugin's `skills/customize/` (the
+ * entry file and its step files); every other one comes from its `src/`.
+ */
+const SKILL_DIR_FILE_NAMES = new Set([
+    CUSTOMIZE_SKILL_ENTRY_FILE,
+    ...CUSTOMIZE_SKILL_STEP_FILE_NAMES,
+]);
 /**
  * Reads every payload file from the plugin source, in
  * {@link CUSTOMIZE_SKILL_WRITE_ORDER} (`SKILL.md` last), before anything is
@@ -117,7 +125,7 @@ function errnoField(error, field) {
  */
 function readCustomizeSkillPayload(sourceDir) {
     return CUSTOMIZE_SKILL_WRITE_ORDER.map((name) => {
-        const from = name === CUSTOMIZE_SKILL_ENTRY_FILE
+        const from = SKILL_DIR_FILE_NAMES.has(name)
             ? join(sourceDir, "skills", "customize", name)
             : join(sourceDir, "src", name);
         try {
@@ -201,13 +209,13 @@ function assertNoDirectoryAtPayloadNames(destDir, payload, alreadyCurrent, polic
 /**
  * For every policy that replaces existing entries: removes an existing
  * `SKILL.md` entry (a file or a symlink, unlinked, never followed) BEFORE any
- * data file is rewritten, so a later failure never leaves a stale `SKILL.md`
- * loadable beside missing or half-rewritten data. Runs after
- * {@link assertNoDirectoryAtPayloadNames}, so a directory there has already
- * been refused (one raced in since makes `rmSync` throw). Returns the
- * removed path, if any; throws (wrapped) before anything is written when the
- * removal fails. `label` is how the entry is described: `"existing"` for a
- * project's own `.claude/` copy, `"stale"` for the CLI-owned staging.
+ * data or step file is rewritten, so a later failure never leaves a stale
+ * `SKILL.md` loadable beside missing or half-rewritten data or step files.
+ * Runs after {@link assertNoDirectoryAtPayloadNames}, so a directory there
+ * has already been refused (one raced in since makes `rmSync` throw). Returns
+ * the removed path, if any; throws (wrapped) before anything is written when
+ * the removal fails. `label` is how the entry is described: `"existing"` for
+ * a project's own `.claude/` copy, `"stale"` for the CLI-owned staging.
  */
 function removeStaleSkillEntry(destDir, label) {
     const staleEntry = join(destDir, CUSTOMIZE_SKILL_ENTRY_FILE);
@@ -323,8 +331,8 @@ function replacedClause(policy, skillRemoved, replaced, skillMaybeLeft) {
             if (skillRemoved === undefined && others === "") {
                 return "";
             }
-            // One sentence for SKILL.md and the data files alike: every one of
-            // them was removed and none is restored.
+            // One sentence for SKILL.md and the other payload files alike: every
+            // one of them was removed and none is restored.
             const removedPaths = [
                 ...(skillRemoved === undefined
                     ? []
@@ -668,20 +676,20 @@ function installGuarded(targetDir, sourceDir) {
  *   `fallbackCause` is `"component"` -- the entry (and any link target) is
  *   left untouched.
  * - Otherwise, if every payload file already there is a regular file
- *   matching what this CLI ships byte-for-byte: with all five present the
- *   result is `"already-present"` (nothing written); with no `SKILL.md` file
- *   (none at all, or an install interrupted before writing it) the missing
- *   files are written into `.claude/skills/customize/`, `SKILL.md` last,
- *   never rewriting or removing the correct ones.
+ *   matching what this CLI ships byte-for-byte: with every payload file
+ *   present the result is `"already-present"` (nothing written); with no
+ *   `SKILL.md` file (none at all, or an install interrupted before writing
+ *   it) the missing files are written into `.claude/skills/customize/`,
+ *   `SKILL.md` last, never rewriting or removing the correct ones.
  * - Anything else under a payload name (a differing file, a regular file
  *   that cannot be read, a symlink -- dangling or not -- a directory, a
- *   `SKILL.md` without its data; detected by `lstat`) is kept as the
- *   project's own: the skill is written to `.groundwork/customize/` instead,
- *   `fallbackReason` names that entry (saying so when it could not be read)
- *   and `fallbackCause` is `"entry"`. Adopt mode never guesses at a project
- *   entry it cannot compare, and the fallback does not guess either: it
- *   leaves that entry exactly as it was. Claude Code does not load a skill
- *   from there; the caller must say so.
+ *   `SKILL.md` without its data or step files; detected by `lstat`) is kept
+ *   as the project's own: the skill is written to `.groundwork/customize/`
+ *   instead, `fallbackReason` names that entry (saying so when it could not
+ *   be read) and `fallbackCause` is `"entry"`. Adopt mode never guesses at a
+ *   project entry it cannot compare, and the fallback does not guess either:
+ *   it leaves that entry exactly as it was. Claude Code does not load a
+ *   skill from there; the caller must say so.
  *
  * Writes into `.claude/skills/customize/` use `"wx"` only, so an entry that
  * appears there mid-install fails the run (rolled back) rather than being

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monte3l/groundwork",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.5",
   "description": "CLI that writes a TypeScript toolchain and Claude Code setup into an empty directory, or -- against an existing project -- read-only surveys it and reports the differences. No prompts, and no network access beyond the package install.",
   "keywords": [
     "typescript",