@monte3l/groundwork 0.1.0-next.1 → 1.0.0-rc.3

package/dist/pack-stage.js

@@ -0,0 +1,287 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Adopt mode's staging of every pack under `templates/packs/`: each pack's
+ * manifest and `files/` tree are copied into `.groundwork/packs/<name>/`,
+ * every file under an inert `<path>.staged` name, so `/customize`'s Step 0
+ * can install a pack from a self-contained copy -- after confirmation --
+ * without any toolchain globbing the project ever picking a staged file up.
+ * All packs are written together to a temporary sibling directory and
+ * swapped in by rename, so `packs/` is never half-written -- the same
+ * lifecycle `baseline-stage.ts` uses (both build on `staging.ts`).
+ */
+import { readFileSync, statSync } 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";
+/** The staging directory's name under `.groundwork/`. */
+const PACKS_DIR_NAME = "packs";
+/** Each staged pack's subdirectory holding its `files/` tree. */
+const PACK_FILES_DIR = "files";
+/**
+ * The project-relative directory every pack is staged under; a pack's own
+ * staging directory is `${STAGED_PACKS_DIR}/<name>`.
+ *
+ * @example
+ * ```ts
+ * const dir = `${STAGED_PACKS_DIR}/quality`; // ".groundwork/packs/quality"
+ * ```
+ */
+export const STAGED_PACKS_DIR = `.groundwork/${PACKS_DIR_NAME}`;
+/**
+ * The install name of a pack's manifest; it is staged as
+ * `pack.json` + `.staged` beside the pack's `files/` directory.
+ *
+ * @example
+ * ```ts
+ * const staged = `${STAGED_PACK_MANIFEST}.staged`; // "pack.json.staged"
+ * ```
+ */
+export const STAGED_PACK_MANIFEST = "pack.json";
+function assertSingleSegmentName(name) {
+    if (name === "" || name === "." || name === ".." || /[\\/]/.test(name)) {
+        throw new Error(`stagePacks: pack name ${JSON.stringify(name)} is not a single directory name`);
+    }
+    if (name.includes(":")) {
+        throw new Error(`stagePacks: pack name ${JSON.stringify(name)} contains ":", which Windows reads as a drive letter or an alternate data stream`);
+    }
+}
+/**
+ * Whether `filesDir` is a directory. A missing path answers `false`; any
+ * other `statSync` failure (a permission error, say) becomes a plan-time
+ * `Error` naming the pack and the path, with the failure as `cause` -- seen
+ * before anything is written, it is a template defect or a permission
+ * problem to fix, not an "incomplete, re-run" staging failure.
+ */
+function isFilesDir(name, filesDir) {
+    try {
+        return (statSync(filesDir, { throwIfNoEntry: false })?.isDirectory() === true);
+    }
+    catch (cause) {
+        throw new Error(`stagePacks: could not inspect pack "${name}"'s files directory ${filesDir}`, { cause });
+    }
+}
+function serializeManifest(name, manifest) {
+    // JSON.stringify is typed string but yields undefined for some inputs
+    // (a toJSON returning undefined); never write or hash that as text.
+    const text = JSON.stringify(manifest, null, 2);
+    if (typeof text !== "string") {
+        throw new Error(`stagePacks: pack "${name}"'s manifest is not JSON`);
+    }
+    return Buffer.from(`${text}\n`);
+}
+/**
+ * Validates and projects every pack before anything is touched. These
+ * defects are refused, each with its own `Error` (no `cause`): a pack name
+ * that is not a single directory name, contains `:`, or is shared by two
+ * packs (also when the two differ only by letter case or Unicode
+ * normalization); a missing
+ * `filesDir`; two files in one pack installing to the same path; an install
+ * path containing `:` (a drive letter or alternate data stream on Windows);
+ * a tokenized install path whose staged name would land outside the pack's
+ * `files/` staging directory (CWE-22, docs/assurance-case.md); and two
+ * staged names in one pack that would land on the same file
+ * ({@link findStagedPathCollision}). A `filesDir` that cannot be inspected
+ * at all is refused with its failure as `cause` (see `isFilesDir`).
+ */
+function planPacks(packs, packsDir, tokens) {
+    const seen = new Set();
+    const plan = packs.map(({ manifest, filesDir }) => {
+        const name = manifest.name;
+        assertSingleSegmentName(name);
+        if (seen.has(name)) {
+            throw new Error(`stagePacks: two packs are named "${name}"; pack names must be unique`);
+        }
+        seen.add(name);
+        if (!isFilesDir(name, filesDir)) {
+            throw new Error(`stagePacks: pack "${name}"'s files directory ${filesDir} does not exist`);
+        }
+        const stagedFilesDir = join(packsDir, name, PACK_FILES_DIR);
+        const files = [...collectTemplateFiles(filesDir, tokens)]
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([path, sourcePath]) => {
+            if (path.includes(":")) {
+                throw new Error(`stagePacks: pack "${name}"'s file ${toPosixPath(path)} contains ":", which Windows reads as a drive letter or an alternate data stream`);
+            }
+            const destPath = join(stagedFilesDir, stagedNameFor(path));
+            if (!isPathContained(destPath, stagedFilesDir)) {
+                throw new Error(`stagePacks: staged path ${resolve(destPath)} for pack "${name}"'s ${path} escapes ${resolve(stagedFilesDir)}`);
+            }
+            return { path, sourcePath };
+        });
+        const collision = findStagedPathCollision(files.map(({ path }) => toPosixPath(stagedNameFor(path))));
+        if (collision !== undefined) {
+            throw new Error(`stagePacks: two of pack "${name}"'s staged files collide: ${collision}; rename one of them under ${filesDir}`);
+        }
+        return { name, manifestBytes: serializeManifest(name, manifest), files };
+    });
+    const nameCollision = findStagedPathCollision(plan.map(({ name }) => name));
+    if (nameCollision !== undefined) {
+        throw new Error(`stagePacks: two packs' staging directories collide: ${nameCollision}; pack names must be unique ignoring case and Unicode normalization`);
+    }
+    return plan;
+}
+/**
+ * Validates `packs` and computes the plan {@link stagePacks} writes from:
+ * every path under `<groundworkDir>/packs/` -- each pack's
+ * `pack.json.staged` and every `files/<path>.staged` -- and each file's
+ * source, so adopt mode can scope-check `paths` before any pack is written
+ * and then hand the same plan to {@link stagePacks}. Reads the packs'
+ * source trees; writes nothing.
+ *
+ * @throws The same plan `Error`s as {@link stagePacks}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * const plan = planPackStaging(packs, groundworkDir, tokens);
+ * assertAdoptWriteScope(targetDir, plan.paths);
+ * stagePacks(packs, groundworkDir, tokens, plan);
+ * ```
+ */
+export function planPackStaging(packs, groundworkDir, tokens) {
+    const packsDir = join(groundworkDir, PACKS_DIR_NAME);
+    const planned = planPacks(packs, packsDir, tokens);
+    const paths = planned.flatMap(({ name, files }) => [
+        join(packsDir, name, stagedNameFor(STAGED_PACK_MANIFEST)),
+        ...files.map(({ path }) => join(packsDir, name, PACK_FILES_DIR, stagedNameFor(path))),
+    ]);
+    return { groundworkDir, paths, packs: planned };
+}
+/**
+ * Every path {@link stagePacks} would write for `packs` -- a thin wrapper
+ * returning {@link planPackStaging}'s `paths`. Reads the packs' source
+ * trees; writes nothing.
+ *
+ * @throws The same plan `Error`s as {@link stagePacks}.
+ *
+ * @example
+ * ```ts
+ * import { assertAdoptWriteScope } from "./main.js";
+ * assertAdoptWriteScope(targetDir, plannedPackStagingPaths(packs, groundworkDir, tokens));
+ * ```
+ */
+export function plannedPackStagingPaths(packs, groundworkDir, tokens) {
+    return [...planPackStaging(packs, groundworkDir, tokens).paths];
+}
+function writePack(plan, newDir) {
+    const manifestStaged = stagedNameFor(STAGED_PACK_MANIFEST);
+    // Relative to newDir, so the containment assertion also covers the name.
+    const manifestSha256 = writeStagedBytes("stagePacks", plan.manifestBytes, newDir, join(plan.name, manifestStaged));
+    const filesDir = join(newDir, plan.name, PACK_FILES_DIR);
+    const files = plan.files.map(({ path, sourcePath }) => {
+        const stagedName = stagedNameFor(path);
+        const sha256 = writeStagedBytes("stagePacks", readFileSync(sourcePath), filesDir, stagedName);
+        return {
+            path: toPosixPath(path),
+            staged: toPosixPath(stagedName),
+            sha256,
+        };
+    });
+    return {
+        name: plan.name,
+        dir: `${STAGED_PACKS_DIR}/${plan.name}`,
+        suffix: STAGED_SUFFIX,
+        manifest: {
+            path: STAGED_PACK_MANIFEST,
+            staged: manifestStaged,
+            sha256: manifestSha256,
+        },
+        files,
+    };
+}
+/**
+ * Stages every pack in `packs` into `<groundworkDir>/packs/`: for each, its
+ * manifest as `<name>/pack.json.staged` (`JSON.stringify(manifest, null, 2)`
+ * plus a newline) and every file of its `filesDir` tree as
+ * `<name>/files/<path>.staged`, copied byte-for-byte -- no token
+ * substitution into content, which is `/customize`'s job at install time.
+ * `tokens` only substitutes into install paths (and dotfile names are
+ * restored), the same derivation `planConflicts` uses. Recorded `path`/
+ * `staged` values use forward slashes; `dir` is the literal
+ * `.groundwork/packs/<name>`, whatever `groundworkDir` was passed.
+ *
+ * What is guaranteed:
+ * - The plan is validated first, before anything is deleted or written (or,
+ *   when `plan` is passed, was already validated by {@link planPackStaging}
+ *   and the packs' trees are not walked again): a pack name that is not a
+ *   single directory name, contains `:`, or is used by two packs (ignoring
+ *   case and Unicode normalization), a missing `filesDir`, two files in one
+ *   pack installing to the same path, an install path containing `:`, a
+ *   staged name that would escape its pack's staging directory, or two
+ *   staged names in one pack landing 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. A `filesDir` that
+ *   cannot be inspected (a permission error) throws a plan `Error` naming
+ *   the pack and path, with the failure as `cause`.
+ * - Then, still before anything is deleted or written, `groundworkDir` and
+ *   `<groundworkDir>/packs` are checked not to be symlinks, and every
+ *   `.packs-*` 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). `.baseline-*`
+ *   entries are left alone.
+ * - When `packs` is empty, any previous `packs/` is removed and nothing is
+ *   created.
+ * - Otherwise every pack is written into one temporary `.packs-*` sibling
+ *   directory (each file created exclusively, `wx`) and swapped in by rename
+ *   only after every copy succeeded, so `packs/` is never half-written and a
+ *   failure leaves any previous `packs/` intact; a previous `packs/` is
+ *   replaced wholesale (a pack no longer passed, or a file a pack dropped,
+ *   does not linger).
+ * - With a previous `packs/`, 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 `packs/` absent and the
+ *   previous copy at `.packs-XXXXXX/previous`; the next run's sweep removes
+ *   it and regenerates the staging.
+ * - If the final swap rename fails, the previous `packs/` is renamed back.
+ *   Only if that restore also fails is `packs/` 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).
+ * - The temporary directory is otherwise always removed; a failure to remove
+ *   it only warns, naming its path.
+ *
+ * @throws `Error` (no re-run advice; no `cause` except for an uninspectable
+ * `filesDir`) for an invalid plan, as above; `Error` before any delete or
+ * write when `groundworkDir` or
+ * `<groundworkDir>/packs` is a symlink; `AggregateError` of the swap and
+ * restore failures, naming where the previous `packs/` 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 planPackStaging} computed for these same
+ * `packs`, `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
+ * import { listPackNames, loadPack } from "./packs.js";
+ * const packs = listPackNames().map((name) => loadPack(name));
+ * const staged = stagePacks(packs, "/work/app/.groundwork", { PROJECT_NAME: "app" });
+ * // staged[0]: { name: "github", dir: ".groundwork/packs/github", suffix: ".staged", … }
+ * ```
+ */
+export function stagePacks(packs, groundworkDir, tokens, plan = planPackStaging(packs, groundworkDir, tokens)) {
+    assertPlanBuiltFor("stagePacks", plan.groundworkDir, groundworkDir);
+    const target = {
+        groundworkDir,
+        dirName: PACKS_DIR_NAME,
+        noun: "packs",
+        plural: true,
+    };
+    prepareStaging(target);
+    if (plan.packs.length === 0) {
+        clearStaging(target);
+        return [];
+    }
+    return stageAtomically(target, (newDir) => plan.packs.map((planned) => writePack(planned, newDir)));
+}
+//# sourceMappingURL=pack-stage.js.map

package/dist/packs.d.ts

@@ -28,7 +28,7 @@ export interface Pack {
 export declare function packsRootDir(): string;
 /** Names of every pack directory that has a `pack.json` under `root`, sorted for deterministic install order. `root` defaults to `templates/packs`, overridable for tests. */
 export declare function listPackNames(root?: string): string[];
-/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown or malformed. */
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}). */
 export declare function loadPack(name: string, root?: string): Pack;
 export interface PackInstallResult {
     filesWritten: string[];
@@ -41,21 +41,27 @@ export interface PackInstallResult {
  * applies the pack's three JSON wiring merges.
  */
 export declare function installPack(pack: Pack, targetDir: string, tokens: TokenTable): PackInstallResult;
-/**
- * Copies a pack's `pack.json` + `files/` tree, unmodified, into
- * `<groundworkDir>/packs/<name>/` -- adopt mode's staging area. `/customize`
- * installs from this self-contained copy rather than from `templateRoot`
- * (an absolute path that may not exist by the time it runs). Token
- * substitution is a no-op here (`{}`): staging a project's real name into
- * pack content is `/customize`'s job, not this offline copy's.
- */
-export declare function stagePackFiles(pack: Pack, groundworkDir: string): string[];
 /**
  * Index-level, adopt-mode-only facts about how a pack's wiring would land
  * against a real project's current `.claude/settings.json` and
  * `bin/lib/verify-steps.packs.json` -- never a verdict on whether it will
- * work, which is `/customize`'s Step 0 judgment call to make after reading
- * the project's real gate runner and hook config.
+ * work. That verdict is a judgment call for `/customize`'s Step 0 (the
+ * adopt-mode reconcile step in `/customize`) to make after reading the
+ * project's real gate runner and hook config. A path this process cannot
+ * reach (`EACCES`/`EPERM`/`ELOOP`) is observed with its errno, never as
+ * "not found"; nor is a dangling symlink or a file blocking an ancestor
+ * directory, which is also recorded once in `undetermined`. A
+ * `.claude/settings.json` that exists but cannot be read for a reason that
+ * is a property of the project's tree (`EACCES`/`EPERM`, `EISDIR`, `ENOENT`,
+ * `ELOOP`) is observed with its errno and also recorded once in
+ * `undetermined` -- adopt mode passes the survey's own list, so the report
+ * shows it; any other errno throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const observations = observeWiring(targetDir, pack.manifest, undetermined);
+ * ```
  */
-export declare function observeWiring(targetDir: string, manifest: PackManifest): string[];
+export declare function observeWiring(targetDir: string, manifest: PackManifest, undetermined?: string[]): string[];
 //# sourceMappingURL=packs.d.ts.map

package/dist/packs.js

@@ -1,17 +1,25 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
 /**
  * Loads pack manifests from `templates/packs/<name>/pack.json` and installs
  * a pack's files + JSON wiring into a freshly-bootstrapped project. Adopt
  * mode never calls `installPack` -- it surveys packs into the report
- * (`observeWiring`, `stagePackFiles`) and defers installation to
- * `/customize`, which reads a project's real gate runner before translating
- * a pack's wiring (see inventory.ts).
+ * (`observeWiring`; `pack-stage.ts`'s `stagePacks` stages them, inert) and
+ * defers installation to `/customize`, which reads a project's real gate
+ * runner before translating a pack's wiring (see inventory.ts). Both modes call `loadPack` for every
+ * pack they handle (fresh mode: each `--pack`; adopt mode: every pack)
+ * before writing anything, and `loadPack` refuses a prototype-sensitive
+ * key in `wiring.settings`, `wiring.settingsTopLevel` or
+ * `wiring.packageScripts`, so such a pack is neither installed nor staged.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { resolveAsset } from "./assets.js";
 import { emitTemplate } from "./emit.js";
 import { parseJsonc } from "./jsonc.js";
-import { isRecord, mergePackageScripts, mergeSettingsHooks, mergeSettingsTopLevel, mergeVerifySteps, } from "./merge-json.js";
+import { blockedAbsentNote } from "./survey/internal/blocked-path.js";
+import { probePath, readFailure, recordedReadCode, unreadableNote, } from "./survey/internal/read-guard.js";
+import { isPrototypeSensitiveKey, isRecord, mergePackageScripts, mergeSettingsHooks, mergeSettingsTopLevel, mergeVerifySteps, } from "./merge-json.js";
 /** `templates/packs`, resolved the same way `templatesCoreDir()` resolves `templates/core`. */
 export function packsRootDir() {
     return resolveAsset({ repo: "templates/packs", local: "templates/packs" });
@@ -26,7 +34,105 @@ export function listPackNames(root = packsRootDir()) {
         .map((entry) => entry.name)
         .sort();
 }
-/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown or malformed. */
+/** A pack's own `name` becomes a path segment under `.groundwork/packs/`, so it must be a bare lowercase identifier: no separators, no `..`. */
+const PACK_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+const CAP_KEYS = [
+    "agents",
+    "skills",
+    "hooks",
+    "workflows",
+    "scripts",
+];
+/** True when `budget` has an own non-negative integer for every {@link CapCounts} key (one read per key). */
+function isValidBudget(budget) {
+    if (!isRecord(budget))
+        return false;
+    return CAP_KEYS.every((key) => {
+        if (!Object.hasOwn(budget, key))
+            return false;
+        const value = budget[key];
+        return Number.isInteger(value) && value >= 0;
+    });
+}
+/** The two CLI modes a pack's `modes` may name (see mode.ts). */
+const PACK_MODES = ["fresh", "adopt"];
+/** The `bin/lib/verify-steps.mjs` groups a pack's verify step may join. */
+const VERIFY_GROUPS = [
+    "format",
+    "lint",
+    "typecheck",
+    "build",
+    "test",
+];
+/** Throws, naming the entry's 0-based `index` and the offending field, when one `wiring.verifySteps[]` entry isn't an object, lacks a string `id`/`name`, lacks a non-empty string-array `cmd`, or names an unknown `group`. Each field is read once into a local before it is checked. */
+function assertValidVerifyStep(name, step, index) {
+    const where = `pack "${name}": pack.json's wiring.verifySteps[${String(index)}]`;
+    if (!isRecord(step)) {
+        throw new Error(`${where} must be an object, got ${String(JSON.stringify(step))}`);
+    }
+    for (const key of ["id", "name"]) {
+        const value = Object.hasOwn(step, key) ? step[key] : undefined;
+        if (typeof value !== "string") {
+            throw new Error(`${where}.${key} must be a string, got ${String(JSON.stringify(value))}`);
+        }
+    }
+    const cmd = Object.hasOwn(step, "cmd") ? step["cmd"] : undefined;
+    if (!Array.isArray(cmd) ||
+        cmd.length === 0 ||
+        !cmd.every((part) => typeof part === "string")) {
+        throw new Error(`${where}.cmd must be a non-empty array of strings, got ${String(JSON.stringify(cmd))}`);
+    }
+    const group = Object.hasOwn(step, "group")
+        ? step["group"]
+        : undefined;
+    if (typeof group !== "string" || !VERIFY_GROUPS.includes(group)) {
+        throw new Error(`${where} group ${String(JSON.stringify(group))} must be one of ${VERIFY_GROUPS.join(", ")}`);
+    }
+}
+/**
+ * Throws, naming the pack, the field and the key, when one of `fragment`'s own
+ * enumerable keys is prototype-sensitive ({@link isPrototypeSensitiveKey}).
+ * `Object.keys` sees a `__proto__` key here because `parseJsonc`, like
+ * `JSON.parse`, creates it as an ordinary own data property. Only the
+ * fragment's own top-level keys are checked: they are the names a merge
+ * writes, while everything nested below them is an opaque value.
+ */
+function assertNoPrototypeSensitiveKeys(name, field, fragment) {
+    for (const key of Object.keys(fragment)) {
+        if (isPrototypeSensitiveKey(key)) {
+            throw new Error(`pack "${name}": pack.json's wiring.${field} must not use the prototype-sensitive key ${JSON.stringify(key)}`);
+        }
+    }
+}
+/**
+ * Throws, naming the offending key or value, when `wiring.settings`/`packageScripts` is missing or isn't an object, `verifySteps` is missing or isn't an array, any `verifySteps[]` entry is malformed (see {@link assertValidVerifyStep}), or `settings`, `packageScripts` or (when it is an object) `settingsTopLevel` has a prototype-sensitive own key (see {@link assertNoPrototypeSensitiveKeys}).
+ * Those three are the only wiring fields whose keys a merge writes; `verifySteps` ids are values. An absent or non-object `settingsTopLevel` is not rejected here.
+ */
+function assertValidWiringShape(name, wiring) {
+    for (const key of ["settings", "packageScripts"]) {
+        const value = Object.hasOwn(wiring, key) ? wiring[key] : undefined;
+        if (!isRecord(value)) {
+            throw new Error(`pack "${name}": pack.json's wiring.${key} must be an object`);
+        }
+        assertNoPrototypeSensitiveKeys(name, key, value);
+    }
+    const topLevel = Object.hasOwn(wiring, "settingsTopLevel")
+        ? wiring["settingsTopLevel"]
+        : undefined;
+    if (isRecord(topLevel)) {
+        assertNoPrototypeSensitiveKeys(name, "settingsTopLevel", topLevel);
+    }
+    const steps = Object.hasOwn(wiring, "verifySteps")
+        ? wiring["verifySteps"]
+        : undefined;
+    if (!Array.isArray(steps)) {
+        throw new Error(`pack "${name}": pack.json's wiring.verifySteps must be an array`);
+    }
+    steps.forEach((step, index) => {
+        assertValidVerifyStep(name, step, index);
+    });
+}
+/** Loads and validates one pack's manifest from under `root` (default `templates/packs`, overridable for tests). Throws, naming the available packs, if unknown; throws naming the pack and the problem if malformed, including a prototype-sensitive key in its wiring (see {@link assertValidWiringShape}). */
 export function loadPack(name, root = packsRootDir()) {
     const packDir = join(root, name);
     const manifestPath = join(packDir, "pack.json");
@@ -38,10 +144,43 @@ export function loadPack(name, root = packsRootDir()) {
     if (!parsed.ok) {
         throw new Error(`pack "${name}": pack.json failed to parse -- ${parsed.error}`);
     }
-    const manifest = parsed.value;
+    const raw = parsed.value;
+    if (!isRecord(raw)) {
+        throw new Error(`pack "${name}": pack.json must be an object, got ${String(JSON.stringify(raw))}`);
+    }
+    const manifest = raw;
     if (manifest.schemaVersion !== 1) {
         throw new Error(`pack "${name}": unsupported pack.json schemaVersion ${JSON.stringify(manifest.schemaVersion)}`);
     }
+    const manifestName = manifest.name;
+    if (typeof manifestName !== "string" ||
+        !PACK_NAME_PATTERN.test(manifestName)) {
+        throw new Error(`pack "${name}": pack.json's pack name ${JSON.stringify(manifestName)} must match ${String(PACK_NAME_PATTERN)} (a bare lowercase identifier, no path separators)`);
+    }
+    const modes = manifest.modes;
+    if (!Array.isArray(modes) ||
+        modes.length === 0 ||
+        !modes.every((mode) => typeof mode === "string")) {
+        throw new Error(`pack "${name}": pack.json's modes must be a non-empty array of strings`);
+    }
+    const badMode = modes.find((mode) => !PACK_MODES.includes(mode));
+    if (badMode !== undefined) {
+        throw new Error(`pack "${name}": pack.json's mode ${JSON.stringify(badMode)} must be one of ${PACK_MODES.join(", ")}`);
+    }
+    const wiring = manifest.wiring;
+    if (!isRecord(wiring)) {
+        throw new Error(`pack "${name}": pack.json's wiring must be an object`);
+    }
+    assertValidWiringShape(name, wiring);
+    const budget = manifest.budget;
+    if (!isValidBudget(budget)) {
+        throw new Error(`pack "${name}": pack.json's budget must set ${CAP_KEYS.join(", ")} to non-negative integers`);
+    }
+    // pack-stage.ts's stagePacks keys each pack's staging directory on
+    // manifest.name, so a mismatch would let two pack directories collide.
+    if (manifestName !== name) {
+        throw new Error(`pack "${name}": pack.json's name "${manifestName}" does not match its directory name "${name}"`);
+    }
     return { manifest, filesDir: join(packDir, "files") };
 }
 function readJsonOrThrow(path) {
@@ -126,35 +265,96 @@ export function installPack(pack, targetDir, tokens) {
     return { filesWritten, budget: manifest.budget };
 }
 /**
- * Copies a pack's `pack.json` + `files/` tree, unmodified, into
- * `<groundworkDir>/packs/<name>/` -- adopt mode's staging area. `/customize`
- * installs from this self-contained copy rather than from `templateRoot`
- * (an absolute path that may not exist by the time it runs). Token
- * substitution is a no-op here (`{}`): staging a project's real name into
- * pack content is `/customize`'s job, not this offline copy's.
+ * Reads `.claude/settings.json` for {@link observeWiring}. A failure that is
+ * a fact about the project's own tree -- a permission failure
+ * (`EACCES`/`EPERM`), a directory at the path (`EISDIR`), the file vanishing
+ * after the exists probe or a dangling symlink (`ENOENT`), a symlink loop
+ * (`ELOOP`) -- is recorded as an observation naming the path and errno, and
+ * once in `undetermined` (so the adoption report shows it), and `undefined`
+ * is returned; any other errno is about the machine and throws, naming the
+ * path with the original failure as `cause`.
  */
-export function stagePackFiles(pack, groundworkDir) {
-    const destDir = join(groundworkDir, "packs", pack.manifest.name);
-    const { filesWritten } = emitTemplate(pack.filesDir, join(destDir, "files"), {});
-    writeJson(join(destDir, "pack.json"), pack.manifest);
-    return [...filesWritten.map((f) => join("files", f)), "pack.json"];
+function readSettingsOrObserve(settingsPath, observations, undetermined) {
+    try {
+        return readFileSync(settingsPath, "utf8");
+    }
+    catch (error) {
+        const code = recordedReadCode(error);
+        if (code === undefined)
+            throw readFailure(settingsPath, error);
+        observations.push(`.claude/settings.json (${settingsPath}) exists but could not be read (${code})`);
+        // Called once per pack against the same file: record the note once.
+        const note = unreadableNote(settingsPath, code);
+        if (!undetermined.includes(note))
+            undetermined.push(note);
+        return undefined;
+    }
+}
+/**
+ * Whether `path` exists, for {@link observeWiring}. A real `stat`, never
+ * `existsSync`, so a file under a directory this process cannot search is
+ * not observed as missing: an `EACCES`/`EPERM`/`ELOOP` is recorded as an
+ * observation naming the path and errno, and `undefined` is returned so the
+ * caller states neither "found" nor "not found". `ENOENT`/`ENOTDIR` answers
+ * `false` only when nothing is really there: a dangling symlink at the path
+ * or an ancestor, or a regular file blocking an ancestor, is observed and
+ * recorded once in `undetermined` (the same note `conflicts.ts` records via
+ * `blockedAbsentNote`) and answers `undefined`. Any other errno throws (see
+ * `probePath`).
+ */
+function existsOrObserve(path, targetDir, observations, undetermined) {
+    const probe = probePath(path);
+    if (probe.kind === "unresolvable") {
+        observations.push(`could not check whether ${path} exists (${probe.code}) -- left undetermined, not reported missing`);
+        return undefined;
+    }
+    if (probe.kind === "present")
+        return true;
+    const note = blockedAbsentNote(path, targetDir);
+    if (note === undefined)
+        return false;
+    observations.push(`${note} -- left undetermined, not reported missing`);
+    // Called once per pack against the same path: record the note once.
+    if (!undetermined.includes(note))
+        undetermined.push(note);
+    return undefined;
 }
 /**
  * Index-level, adopt-mode-only facts about how a pack's wiring would land
  * against a real project's current `.claude/settings.json` and
  * `bin/lib/verify-steps.packs.json` -- never a verdict on whether it will
- * work, which is `/customize`'s Step 0 judgment call to make after reading
- * the project's real gate runner and hook config.
+ * work. That verdict is a judgment call for `/customize`'s Step 0 (the
+ * adopt-mode reconcile step in `/customize`) to make after reading the
+ * project's real gate runner and hook config. A path this process cannot
+ * reach (`EACCES`/`EPERM`/`ELOOP`) is observed with its errno, never as
+ * "not found"; nor is a dangling symlink or a file blocking an ancestor
+ * directory, which is also recorded once in `undetermined`. A
+ * `.claude/settings.json` that exists but cannot be read for a reason that
+ * is a property of the project's tree (`EACCES`/`EPERM`, `EISDIR`, `ENOENT`,
+ * `ELOOP`) is observed with its errno and also recorded once in
+ * `undetermined` -- adopt mode passes the survey's own list, so the report
+ * shows it; any other errno throws.
+ *
+ * @example
+ * ```ts
+ * const undetermined: string[] = [];
+ * const observations = observeWiring(targetDir, pack.manifest, undetermined);
+ * ```
  */
-export function observeWiring(targetDir, manifest) {
+export function observeWiring(targetDir, manifest, undetermined = []) {
     const observations = [];
     const settingsPath = join(targetDir, ".claude", "settings.json");
-    if (!existsSync(settingsPath)) {
+    const settingsExists = existsOrObserve(settingsPath, targetDir, observations, undetermined);
+    if (settingsExists === false) {
         observations.push("no .claude/settings.json found");
     }
-    else {
-        const parsed = parseJsonc(readFileSync(settingsPath, "utf8"));
-        if (!parsed.ok || !isRecord(parsed.value)) {
+    else if (settingsExists) {
+        const content = readSettingsOrObserve(settingsPath, observations, undetermined);
+        const parsed = content === undefined ? undefined : parseJsonc(content);
+        if (parsed === undefined) {
+            // Unreadable -- already recorded as an observation.
+        }
+        else if (!parsed.ok || !isRecord(parsed.value)) {
             observations.push(".claude/settings.json exists but could not be parsed");
         }
         else {
@@ -172,14 +372,17 @@ export function observeWiring(targetDir, manifest) {
             }
         }
     }
-    if (existsSync(join(targetDir, ".claude", "settings.local.json"))) {
+    if (existsOrObserve(join(targetDir, ".claude", "settings.local.json"), targetDir, observations, undetermined) === true) {
         observations.push(".claude/settings.local.json is present and may shadow a merged hook entry");
     }
     if (manifest.wiring.verifySteps.length > 0) {
         const stepsPath = join(targetDir, "bin", "lib", "verify-steps.packs.json");
-        observations.push(existsSync(stepsPath)
-            ? "bin/lib/verify-steps.packs.json exists"
-            : "no bin/lib/verify-steps.packs.json found -- no bin/verify.mjs-shaped gate runner detected");
+        const stepsExist = existsOrObserve(stepsPath, targetDir, observations, undetermined);
+        if (stepsExist !== undefined) {
+            observations.push(stepsExist
+                ? "bin/lib/verify-steps.packs.json exists"
+                : "no bin/lib/verify-steps.packs.json found -- no bin/verify.mjs-shaped gate runner detected");
+        }
     }
     return observations;
 }