@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/README.md

@@ -1,15 +1,21 @@
 # @monte3l/groundwork
 
+**What this is:** a command-line tool that sets up a TypeScript project's
+toolchain and Claude Code configuration, or reports on how an existing
+project compares to that setup.
+
 The offline bootstrapper behind [m3l-groundwork](https://github.com/monte3l/m3l-groundwork):
 one deterministic CLI that either writes a baseline TypeScript toolchain and
-Claude Code harness into an empty directory (**fresh** mode) or surveys an
-existing project and writes only a report (**adopt** mode, which never touches a
-project file).
+Claude Code **harness** (its agents, skills, hooks, and settings) into an
+empty directory (**fresh** mode) or surveys an existing project and writes
+only a report (**adopt mode**, which never touches a project file --
+it's for a project that already exists and shouldn't be rewritten
+automatically).
 
 ```bash
 # currently a 1.0.0 release candidate, shipping on the `rc` dist-tag
 npx @monte3l/groundwork@rc my-new-project
-npx @monte3l/groundwork@rc my-new-project --pack statusline
+npx @monte3l/groundwork@rc my-new-project --pack harness-extras
 npx @monte3l/groundwork@rc ../existing-project
 ```
 
@@ -18,6 +24,8 @@ fresh bootstrap ends with (`--skip-install` to skip it). Run with `--help` for
 every flag, or `--list-packs` for the optional packs.
 
 The `/customize` skill it installs, the packs, and the design are documented in
-the [repository README](https://github.com/monte3l/m3l-groundwork#readme).
+the [repository README](https://github.com/monte3l/m3l-groundwork/blob/main/README.md).
+Unfamiliar terms (harness, adopt mode, pack, and the rest) are defined in the
+[glossary](https://github.com/monte3l/m3l-groundwork/blob/main/docs/glossary.md).
 
 MIT licensed.

package/bin/m3l-groundwork.mjs

@@ -1,10 +1,44 @@
 #!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+
+/**
+ * The published CLI's entry point: `npx @monte3l/groundwork <target-dir>`
+ * resolves here. Delegates straight to the built `main()` and turns a
+ * `CliUsageError` into exit code 2 (a bad invocation), any other thrown
+ * error into exit code 1 (a runtime failure) -- see `packages/cli/src/main.ts`.
+ * The error is printed with its full `cause` chain (`formatErrorChain`), so
+ * a wrapped failure never hides the underlying reason; `handleFatal` sets the
+ * exit code before printing and never throws, even when reporting fails --
+ * if the painted print throws, it falls back to a plain, unpainted
+ * `console.error` (`printRaw`). Not `process.stderr.write`: a write to a
+ * closed pipe reports EPIPE asynchronously as an `'error'` event on
+ * `process.stderr`, which nothing here listens for, so it would crash the
+ * process as an uncaught exception and turn exit code 2 into 1 after
+ * `handleFatal` returned; `console.error` swallows stream errors itself.
+ */
 import process from "node:process";
 import { main, CliUsageError } from "../dist/main.js";
+import { handleFatal } from "../dist/fatal.js";
+import { paint } from "../dist/term.js";
 
 try {
   main(process.argv.slice(2));
 } catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exitCode = error instanceof CliUsageError ? 2 : 1;
+  handleFatal(
+    error,
+    {
+      setExitCode: (code) => {
+        process.exitCode = code;
+      },
+      print: (text) => {
+        console.error(paint(process.stderr, "danger", text));
+      },
+      printRaw: (text) => {
+        console.error(text);
+      },
+    },
+    (e) => e instanceof CliUsageError,
+    (process.env["M3L_DEBUG"] ?? "") !== "",
+  );
 }

package/dist/assets.d.ts

@@ -11,6 +11,16 @@ export declare function escapeDotfileName(name: string): string;
 export declare function restoreDotfileName(name: string): string;
 /** `restoreDotfileName` applied to the final segment of a `/`- or `\`-separated relative path. */
 export declare function restoreDotfilePath(relPath: string): string;
+/**
+ * Normalizes a native relative path to forward slashes, so a path recorded
+ * in `inventory.json` reads the same whichever OS ran the CLI.
+ *
+ * @example
+ * ```ts
+ * toPosixPath("src\\index.ts"); // "src/index.ts"
+ * ```
+ */
+export declare function toPosixPath(p: string): string;
 /**
  * Resolves an asset for whichever layout is running. `fromDir` is the
  * directory of a module at `src/` or `dist/` depth; it defaults to this

package/dist/assets.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * The one place that decides where the CLI's data trees live: `templates/`
  * (the baseline and its packs) and the `/customize` plugin payload.
@@ -43,6 +45,18 @@ export function restoreDotfilePath(relPath) {
     const cut = Math.max(relPath.lastIndexOf("/"), relPath.lastIndexOf("\\"));
     return relPath.slice(0, cut + 1) + restoreDotfileName(relPath.slice(cut + 1));
 }
+/**
+ * Normalizes a native relative path to forward slashes, so a path recorded
+ * in `inventory.json` reads the same whichever OS ran the CLI.
+ *
+ * @example
+ * ```ts
+ * toPosixPath("src\\index.ts"); // "src/index.ts"
+ * ```
+ */
+export function toPosixPath(p) {
+    return p.replaceAll("\\", "/");
+}
 /** True when `dir` is this project's own source checkout, by two independent markers. */
 function isSourceCheckout(dir) {
     if (!existsSync(join(dir, "pnpm-workspace.yaml"))) {

package/dist/baseline-stage.d.ts

@@ -0,0 +1,173 @@
+import { toPosixPath } from "./assets.js";
+import type { FileConflict } from "./conflicts.js";
+import { STAGED_SUFFIX, stagedNameFor } from "./staging.js";
+import type { TokenTable } from "./tokens.js";
+export { STAGED_SUFFIX, stagedNameFor, toPosixPath };
+/**
+ * The directory name, under `.groundwork/`, that absent baseline files are
+ * staged into.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * const stagedDir = join(".groundwork", STAGED_BASELINE_DIR); // ".groundwork/baseline"
+ * ```
+ */
+export declare const STAGED_BASELINE_DIR = "baseline";
+/**
+ * One staged baseline file: its install path, its staged name, and the
+ * sha256 of the staged bytes, so `/customize` can verify the copy it installs.
+ *
+ * @example
+ * ```ts
+ * const file: StagedBaselineFile = {
+ *   path: "eslint.config.js",
+ *   staged: "eslint.config.js.staged",
+ *   sha256: "e3b0c442...", // hex digest of the staged bytes
+ * };
+ * ```
+ */
+export interface StagedBaselineFile {
+    /** The project-relative path the file installs to. */
+    path: string;
+    /** The staged file's name, relative to the staging directory: `path` + {@link STAGED_SUFFIX}. */
+    staged: string;
+    /** Lowercase hex sha256 of the staged bytes. */
+    sha256: string;
+}
+/**
+ * The validated plan for one {@link stageBaselineAdditions} run: every path
+ * it would write, plus each file's install path and template source, so
+ * staging never re-walks the template tree. Built by
+ * {@link planBaselineStaging}.
+ *
+ * @example
+ * ```ts
+ * import { planBaselineStaging, stageBaselineAdditions } from "./baseline-stage.js";
+ * const plan = planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens);
+ * stageBaselineAdditions(templateRoot, conflicts, groundworkDir, tokens, plan);
+ * ```
+ */
+export interface BaselineStagingPlan {
+    /** The `groundworkDir` the plan was computed for; {@link stageBaselineAdditions} refuses the plan for any other. */
+    readonly groundworkDir: string;
+    /** Every path the run writes: one `<groundworkDir>/baseline/<path>.staged` per absent conflict, in `conflicts` order. */
+    readonly paths: readonly string[];
+    /** Each absent conflict's install path and template source, in the same order. */
+    readonly files: readonly {
+        readonly path: string;
+        readonly sourcePath: string;
+    }[];
+}
+/**
+ * Validates the absent conflicts in `conflicts` against `templateRoot` and
+ * computes the plan {@link stageBaselineAdditions} writes from: every path
+ * under `<groundworkDir>/baseline/` -- one `<path>.staged` per absent
+ * conflict -- and each file's template source, so adopt mode can
+ * scope-check `paths` before anything under `.groundwork/` is deleted or
+ * written and then hand the same plan to {@link stageBaselineAdditions}.
+ * Reads the template tree (not at all when nothing is absent); writes
+ * nothing. Both arrays are empty when nothing is absent.
+ *
+ * @throws The same plan `Error`s as {@link stageBaselineAdditions}: a
+ * template with two files installing to one path, an absent conflict with no
+ * template counterpart or whose staged name would escape the staging
+ * directory, or two colliding staged names.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const plan = planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, plan.paths);
+ * stageBaselineAdditions(templateRoot, conflicts, groundworkDir, tokens, plan);
+ * ```
+ */
+export declare function planBaselineStaging(templateRoot: string, conflicts: readonly FileConflict[], groundworkDir: string, tokens: TokenTable): BaselineStagingPlan;
+/**
+ * Every path {@link stageBaselineAdditions} would write for `conflicts` -- a
+ * thin wrapper returning {@link planBaselineStaging}'s `paths`. Reads the
+ * template tree; writes nothing. Returns `[]` when nothing is absent.
+ *
+ * @throws The same plan `Error`s as {@link planBaselineStaging}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const paths = plannedBaselineStagingPaths(templateRoot, conflicts, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, paths);
+ * ```
+ */
+export declare function plannedBaselineStagingPaths(templateRoot: string, conflicts: readonly FileConflict[], groundworkDir: string, tokens: TokenTable): string[];
+/**
+ * Copies every template file `conflicts` marks "absent" from `templateRoot`
+ * into `<groundworkDir>/baseline/` as `<path>.staged`, byte-for-byte -- no
+ * token substitution into content, which is `/customize`'s job at install
+ * time. `tokens` is used only to match a tokenized template path
+ * (`__PROJECT_NAME__.txt`) to the substituted `relPath` the conflict plan
+ * reports. Recorded `path`/`staged` values use forward slashes
+ * ({@link toPosixPath}).
+ *
+ * What is guaranteed:
+ * - The plan is validated first, before anything is deleted or written (or,
+ *   when `plan` is passed, was already validated by
+ *   {@link planBaselineStaging} and the template tree is not walked again): a
+ *   template with two files installing to the same path (a dotfile-escaped
+ *   name beside its literal twin), an absent conflict with no template
+ *   counterpart or whose staged name would escape the staging directory, or
+ *   two staged names that would land on the same file (equal once
+ *   NFC-normalized and case-folded, or one a directory prefix of the other)
+ *   throws its own
+ *   `Error`, leaving `.groundwork/` exactly as it was.
+ * - Then, still before anything is deleted or written, `groundworkDir` and
+ *   `<groundworkDir>/baseline` are checked not to be symlinks, and every
+ *   `.baseline-*` entry of the CLI-owned `groundworkDir` -- meant for work
+ *   directories a crashed earlier run left, but removed whatever created
+ *   it, so a concurrent run against the same directory can lose its
+ *   in-progress work directory and fail with the incomplete/re-run error
+ *   -- is removed (best effort; a failure to remove one only warns, a
+ *   failure to list `groundworkDir` throws).
+ * - When nothing is absent, any previous staging is removed and nothing is
+ *   created.
+ * - Files are then written into a temporary `.baseline-*` sibling directory
+ *   and swapped in by rename only after every copy succeeded, so
+ *   `baseline/` is never half-written and a copy failure leaves any previous
+ *   `baseline/` intact. A previous staging is replaced wholesale (no stale
+ *   file lingers).
+ * - With a previous `baseline/`, the swap is two renames: the previous one
+ *   is parked inside the temporary directory, then the new one moved into
+ *   place. A process killed between the two leaves `baseline/` absent and
+ *   the previous copy at `.baseline-XXXXXX/previous`; the next run's sweep
+ *   removes it and regenerates the staging.
+ * - If the final swap rename fails, the previous `baseline/` is renamed back
+ *   into place. Only if that restore also fails is `baseline/` left absent:
+ *   the previous staging then survives, parked inside the temporary
+ *   directory, which is deliberately not removed (a later run's stale-dir
+ *   sweep does remove it, regenerating the staging from scratch).
+ * - The temporary directory is otherwise always removed; a failure to remove
+ *   it only warns, naming its path.
+ *
+ * @throws `Error` (no `cause`, no re-run advice) for an invalid plan, as
+ * above; `Error` before any delete or write when `groundworkDir` or
+ * `<groundworkDir>/baseline` is a symlink; `AggregateError` of the swap and
+ * restore failures, naming where the previous baseline is parked, when both
+ * renames fail; the `AssertionError` itself, unwrapped, if the staged-path
+ * containment invariant ever fails while writing; otherwise an `Error` with
+ * `cause`, including the cause's message, saying `.groundwork/` is
+ * incomplete and the CLI should be re-run.
+ *
+ * @param plan - The plan {@link planBaselineStaging} computed for these same
+ * `templateRoot`, `conflicts`, `groundworkDir` and `tokens`; computed here
+ * when omitted. A plan whose `groundworkDir` resolves to a different
+ * directory throws a plain `Error` naming both ("the plan was built for …")
+ * before anything is deleted or written.
+ *
+ * @example
+ * ```ts
+ * // conflicts: the plan `planConflicts` (conflicts.ts) computed for the target
+ * const conflicts = planConflicts(templateRoot, targetDir, tokens);
+ * const staged = stageBaselineAdditions(templateRoot, conflicts, ".groundwork", tokens);
+ * // staged: [{ path: "eslint.config.js", staged: "eslint.config.js.staged", sha256: "…" }, …]
+ * ```
+ */
+export declare function stageBaselineAdditions(templateRoot: string, conflicts: readonly FileConflict[], groundworkDir: string, tokens: TokenTable, plan?: BaselineStagingPlan): StagedBaselineFile[];
+//# sourceMappingURL=baseline-stage.d.ts.map

package/dist/baseline-stage.js

@@ -0,0 +1,215 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Adopt mode's staging of the baseline files a project lacks entirely: the
+ * template files a conflict plan marked "absent" are copied verbatim into
+ * `.groundwork/baseline/`, each under an inert `<path>.staged` name, so
+ * `/customize`'s Step 0 can install them from a self-contained copy rather
+ * than from `templateRoot` -- an absolute path that may not exist by the time
+ * it runs -- and no toolchain globbing the project ever picks one up.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { toPosixPath } from "./assets.js";
+import { isPathContained } from "./emit.js";
+import { STAGED_SUFFIX, assertPlanBuiltFor, clearStaging, collectTemplateFiles, findStagedPathCollision, prepareStaging, stageAtomically, stagedNameFor, writeStagedBytes, } from "./staging.js";
+// Re-exported so existing consumers of this module keep one import site.
+export { STAGED_SUFFIX, stagedNameFor, toPosixPath };
+/**
+ * The directory name, under `.groundwork/`, that absent baseline files are
+ * staged into.
+ *
+ * @example
+ * ```ts
+ * import { join } from "node:path";
+ * const stagedDir = join(".groundwork", STAGED_BASELINE_DIR); // ".groundwork/baseline"
+ * ```
+ */
+export const STAGED_BASELINE_DIR = "baseline";
+/**
+ * Pairs every absent conflict with its template source. Four defects are
+ * refused, each with its own `Error` (no `cause`) and never skipped: a
+ * template with two files mapping to one install path, a `relPath` whose
+ * staged name would land outside `destDir` (CWE-22, docs/assurance-case.md),
+ * an absent path with no template counterpart, and two staged names that
+ * would land on the same file ({@link findStagedPathCollision}: equal once
+ * NFC-normalized and case-folded, or one a directory prefix of the other).
+ */
+function planStaging(templateRoot, absent, tokens, destDir) {
+    const templateFiles = collectTemplateFiles(templateRoot, tokens);
+    const plan = absent.map(({ relPath }) => {
+        // No ":" refusal here: that check (a Windows drive letter / ADS) is packs-only, in pack-stage.ts.
+        const destPath = join(destDir, stagedNameFor(relPath));
+        if (!isPathContained(destPath, destDir)) {
+            throw new Error(`stageBaselineAdditions: staged path ${resolve(destPath)} for ${relPath} escapes ${resolve(destDir)}`);
+        }
+        const sourcePath = templateFiles.get(relPath);
+        if (sourcePath === undefined) {
+            throw new Error(`absent baseline file ${relPath} has no counterpart under ${templateRoot}`);
+        }
+        return { path: relPath, sourcePath };
+    });
+    const collision = findStagedPathCollision(plan.map(({ path }) => toPosixPath(stagedNameFor(path))));
+    if (collision !== undefined) {
+        throw new Error(`stageBaselineAdditions: two staged baseline files under ${destDir} collide: ${collision}; rename one of the template files under ${templateRoot}`);
+    }
+    return plan;
+}
+/** The absent conflicts in `conflicts` -- the files a baseline staging copies. */
+function absentConflicts(conflicts) {
+    return conflicts.filter((c) => c.status === "absent");
+}
+/**
+ * Validates the absent conflicts in `conflicts` against `templateRoot` and
+ * computes the plan {@link stageBaselineAdditions} writes from: every path
+ * under `<groundworkDir>/baseline/` -- one `<path>.staged` per absent
+ * conflict -- and each file's template source, so adopt mode can
+ * scope-check `paths` before anything under `.groundwork/` is deleted or
+ * written and then hand the same plan to {@link stageBaselineAdditions}.
+ * Reads the template tree (not at all when nothing is absent); writes
+ * nothing. Both arrays are empty when nothing is absent.
+ *
+ * @throws The same plan `Error`s as {@link stageBaselineAdditions}: a
+ * template with two files installing to one path, an absent conflict with no
+ * template counterpart or whose staged name would escape the staging
+ * directory, or two colliding staged names.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const plan = planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, plan.paths);
+ * stageBaselineAdditions(templateRoot, conflicts, groundworkDir, tokens, plan);
+ * ```
+ */
+export function planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens) {
+    const absent = absentConflicts(conflicts);
+    if (absent.length === 0) {
+        return { groundworkDir, paths: [], files: [] };
+    }
+    const destDir = join(groundworkDir, STAGED_BASELINE_DIR);
+    const files = planStaging(templateRoot, absent, tokens, destDir);
+    const paths = files.map(({ path }) => join(destDir, stagedNameFor(path)));
+    return { groundworkDir, paths, files };
+}
+/**
+ * Every path {@link stageBaselineAdditions} would write for `conflicts` -- a
+ * thin wrapper returning {@link planBaselineStaging}'s `paths`. Reads the
+ * template tree; writes nothing. Returns `[]` when nothing is absent.
+ *
+ * @throws The same plan `Error`s as {@link planBaselineStaging}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const paths = plannedBaselineStagingPaths(templateRoot, conflicts, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, paths);
+ * ```
+ */
+export function plannedBaselineStagingPaths(templateRoot, conflicts, groundworkDir, tokens) {
+    return [
+        ...planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens)
+            .paths,
+    ];
+}
+/**
+ * Copies every template file `conflicts` marks "absent" from `templateRoot`
+ * into `<groundworkDir>/baseline/` as `<path>.staged`, byte-for-byte -- no
+ * token substitution into content, which is `/customize`'s job at install
+ * time. `tokens` is used only to match a tokenized template path
+ * (`__PROJECT_NAME__.txt`) to the substituted `relPath` the conflict plan
+ * reports. Recorded `path`/`staged` values use forward slashes
+ * ({@link toPosixPath}).
+ *
+ * What is guaranteed:
+ * - The plan is validated first, before anything is deleted or written (or,
+ *   when `plan` is passed, was already validated by
+ *   {@link planBaselineStaging} and the template tree is not walked again): a
+ *   template with two files installing to the same path (a dotfile-escaped
+ *   name beside its literal twin), an absent conflict with no template
+ *   counterpart or whose staged name would escape the staging directory, or
+ *   two staged names that would land on the same file (equal once
+ *   NFC-normalized and case-folded, or one a directory prefix of the other)
+ *   throws its own
+ *   `Error`, leaving `.groundwork/` exactly as it was.
+ * - Then, still before anything is deleted or written, `groundworkDir` and
+ *   `<groundworkDir>/baseline` are checked not to be symlinks, and every
+ *   `.baseline-*` entry of the CLI-owned `groundworkDir` -- meant for work
+ *   directories a crashed earlier run left, but removed whatever created
+ *   it, so a concurrent run against the same directory can lose its
+ *   in-progress work directory and fail with the incomplete/re-run error
+ *   -- is removed (best effort; a failure to remove one only warns, a
+ *   failure to list `groundworkDir` throws).
+ * - When nothing is absent, any previous staging is removed and nothing is
+ *   created.
+ * - Files are then written into a temporary `.baseline-*` sibling directory
+ *   and swapped in by rename only after every copy succeeded, so
+ *   `baseline/` is never half-written and a copy failure leaves any previous
+ *   `baseline/` intact. A previous staging is replaced wholesale (no stale
+ *   file lingers).
+ * - With a previous `baseline/`, the swap is two renames: the previous one
+ *   is parked inside the temporary directory, then the new one moved into
+ *   place. A process killed between the two leaves `baseline/` absent and
+ *   the previous copy at `.baseline-XXXXXX/previous`; the next run's sweep
+ *   removes it and regenerates the staging.
+ * - If the final swap rename fails, the previous `baseline/` is renamed back
+ *   into place. Only if that restore also fails is `baseline/` left absent:
+ *   the previous staging then survives, parked inside the temporary
+ *   directory, which is deliberately not removed (a later run's stale-dir
+ *   sweep does remove it, regenerating the staging from scratch).
+ * - The temporary directory is otherwise always removed; a failure to remove
+ *   it only warns, naming its path.
+ *
+ * @throws `Error` (no `cause`, no re-run advice) for an invalid plan, as
+ * above; `Error` before any delete or write when `groundworkDir` or
+ * `<groundworkDir>/baseline` is a symlink; `AggregateError` of the swap and
+ * restore failures, naming where the previous baseline is parked, when both
+ * renames fail; the `AssertionError` itself, unwrapped, if the staged-path
+ * containment invariant ever fails while writing; otherwise an `Error` with
+ * `cause`, including the cause's message, saying `.groundwork/` is
+ * incomplete and the CLI should be re-run.
+ *
+ * @param plan - The plan {@link planBaselineStaging} computed for these same
+ * `templateRoot`, `conflicts`, `groundworkDir` and `tokens`; computed here
+ * when omitted. A plan whose `groundworkDir` resolves to a different
+ * directory throws a plain `Error` naming both ("the plan was built for …")
+ * before anything is deleted or written.
+ *
+ * @example
+ * ```ts
+ * // conflicts: the plan `planConflicts` (conflicts.ts) computed for the target
+ * const conflicts = planConflicts(templateRoot, targetDir, tokens);
+ * const staged = stageBaselineAdditions(templateRoot, conflicts, ".groundwork", tokens);
+ * // staged: [{ path: "eslint.config.js", staged: "eslint.config.js.staged", sha256: "…" }, …]
+ * ```
+ */
+export function stageBaselineAdditions(templateRoot, conflicts, groundworkDir, tokens, 
+// Defaulted before the symlink check and stale-dir sweep below, so an
+// invalid plan -- a template defect, with its own message rather than the
+// "incomplete, re-run" staging failure -- deletes and writes nothing.
+plan = planBaselineStaging(templateRoot, conflicts, groundworkDir, tokens)) {
+    assertPlanBuiltFor("stageBaselineAdditions", plan.groundworkDir, groundworkDir);
+    const target = {
+        groundworkDir,
+        dirName: STAGED_BASELINE_DIR,
+        noun: "baseline",
+        plural: false,
+    };
+    prepareStaging(target);
+    if (plan.files.length === 0) {
+        clearStaging(target);
+        return [];
+    }
+    return stageAtomically(target, (newDir) => plan.files.map(({ path, sourcePath }) => {
+        const stagedName = stagedNameFor(path);
+        // writeStagedBytes re-asserts the CWE-22 containment planStaging
+        // already checked, against the directory actually written to.
+        const sha256 = writeStagedBytes("stageBaselineAdditions", readFileSync(sourcePath), newDir, stagedName);
+        return {
+            path: toPosixPath(path),
+            staged: toPosixPath(stagedName),
+            sha256,
+        };
+    }));
+}
+//# sourceMappingURL=baseline-stage.js.map

package/dist/caps.d.ts

@@ -20,6 +20,9 @@ export declare function countBaselineCaps(templateRoot: string): CapCounts;
  * the same shape as {@link countBaselineCaps} but without the `/customize`
  * adjustment, since a pack never ships that skill. Used to verify a pack's
  * declared `budget` matches what its own file tree actually contains.
+ * `packageScripts` is the pack's `wiring.packageScripts`, added to the
+ * `scripts` count -- those are merged into the target's real `package.json`
+ * at install time, never shipped as a file, so the tree walk can't see them.
  */
-export declare function countPackBudget(packFilesDir: string): CapCounts;
+export declare function countPackBudget(packFilesDir: string, packageScripts?: Record<string, string>): CapCounts;
 //# sourceMappingURL=caps.d.ts.map

package/dist/caps.js

@@ -1,8 +1,15 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Counts the baseline's own `.claude/` + workflow + script artifacts
  * against the five hard caps `templates/core`'s own `CLAUDE.md` states
  * (≤5 agents, ≤8 skills, ≤10 hooks, ≤3 CI workflows, ≤12 root scripts).
- * The counting logic and the cap numbers both live here, once, so
+ * A cap is a fixed upper bound on how many artifacts of one category
+ * (agents, skills, hooks, CI workflows, root `package.json` scripts) the
+ * emitted baseline may contain -- kept deliberately low so a bootstrapped
+ * project's Claude Code harness and toolchain stay small enough for a human
+ * to read and reason about in full, rather than growing without bound as
+ * more capability gets added. The counting logic and the cap numbers both live here, once, so
  * `report.ts` (the adoption-report table) and `main.ts` (the fresh-mode
  * post-install summary) can't state a different number for the same cap.
  */
@@ -62,8 +69,15 @@ export function countBaselineCaps(templateRoot) {
  * the same shape as {@link countBaselineCaps} but without the `/customize`
  * adjustment, since a pack never ships that skill. Used to verify a pack's
  * declared `budget` matches what its own file tree actually contains.
+ * `packageScripts` is the pack's `wiring.packageScripts`, added to the
+ * `scripts` count -- those are merged into the target's real `package.json`
+ * at install time, never shipped as a file, so the tree walk can't see them.
  */
-export function countPackBudget(packFilesDir) {
-    return countArtifacts(packFilesDir);
+export function countPackBudget(packFilesDir, packageScripts) {
+    const raw = countArtifacts(packFilesDir);
+    return {
+        ...raw,
+        scripts: raw.scripts + Object.keys(packageScripts ?? {}).length,
+    };
 }
 //# sourceMappingURL=caps.js.map

package/dist/conflicts.d.ts

@@ -6,7 +6,28 @@ export interface FileConflict {
     /** Present only for a key-level comparison (package.json / tsconfig*.json): the top-level keys that differ. */
     keyDiffs: string[] | undefined;
 }
-/** Compares every file `templates/core` would emit against what `targetDir` already has. */
-export declare function planConflicts(templateRoot: string, targetDir: string, tokens: TokenTable): FileConflict[];
+/**
+ * Compares every file `templates/core` (or a pack's `files/`) would emit
+ * against what `targetDir` already has. A target path this process cannot
+ * reach (`EACCES`/`EPERM`/`ELOOP`) is never reported `absent`: it is
+ * `divergent`, and a note naming the errno is appended to `undetermined`
+ * once (adopt mode passes the survey's own list, so the report shows it) --
+ * naming the enclosing directory for a permission failure on the `stat`, the
+ * path itself for a symlink loop, or for a permission failure or a
+ * directory-where-a-file-was-expected (`EISDIR`) on the read. A dangling
+ * symlink at the target path is `divergent` too, recorded naming the path;
+ * so is a dangling symlink at one of its ancestors below `targetDir`,
+ * recorded once naming that ancestor. A regular file where an enclosing
+ * directory should be (`ENOTDIR`) is `divergent`, recorded once naming that
+ * blocking ancestor. A genuinely missing path is `absent`; any other errno
+ * throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const conflicts = planConflicts(templateRoot, targetDir, tokens, undetermined);
+ * ```
+ */
+export declare function planConflicts(templateRoot: string, targetDir: string, tokens: TokenTable, undetermined?: string[]): FileConflict[];
 export {};
 //# sourceMappingURL=conflicts.d.ts.map