pi-daddy 0.27.4 → 0.32.0

package/src/governance/grant-store.ts

@@ -0,0 +1,235 @@
+/**
+ * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
+ * consent.
+ *
+ * `PI_DADDY_GRANT` and `PI_DADDY_LEDGER` remain the propagation channel to children — a parent writes them
+ * and every child inherits them. The store is a root-session source only, so an operator does not have to
+ * `source` a file and restart pi after making the project choice.
+ *
+ * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
+ * can rewrite is not a ceiling. `<cwd>/.pi/pi-daddy/settings.json` is writable by any child holding `tool:write`, so
+ * storing the live grant there would let a child widen the *next* session's ceiling — ADR-0014's
+ * self-defeating case verbatim, which is why persisted approvals were moved out of the workspace in the
+ * first place. This reuses that pattern exactly: `$PI_CODING_AGENT_DIR/pi-daddy/grants/<slug>-<hash>.json`, keyed by
+ * the directory, unwritable by a narrowed child because a narrowed child holds no write access to `$HOME`.
+ *
+ * **It does not defend against a child holding `bash`** (ADR-0012). Nothing here does.
+ *
+ * `.pi/pi-daddy/settings.json` is written by `init` and is worth committing — it is the *reviewable record*
+ * of the decision, diffable in a PR. It is not the thing the enforcer reads.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, resolve } from "node:path";
+import { withFileLock, LockTimeoutError } from "./file-lock.ts";
+import type { Capability } from "../kernel/resolve.ts";
+import {
+  grantStorePath as userGrantStorePath,
+  projectLedgerPath as projectLedgerFile,
+  agentDir as resolveAgentDir,
+} from "../kernel/project-paths.ts";
+
+interface GrantFileV1 {
+  version: 1;
+  /** The directory this grant is for. Checked on read — an entry copied elsewhere is refused (R-27). */
+  cwd: string;
+  grant: Capability[];
+  /** When `/grants init` wrote it. Informational; nothing expires. */
+  writtenAt: string;
+}
+
+interface GrantFileV2 {
+  version: 2;
+  cwd: string;
+  grant: Capability[];
+  /** Explicit consent from ADR-0037's `/grants init`; never inferred from a legacy file merely existing. */
+  projectLedger: true;
+  writtenAt: string;
+}
+
+export interface StoredGrant {
+  grant: Capability[];
+  /** Whether a root session defaults to `<cwd>/.pi/pi-daddy/grants.jsonl`. False for every legacy v1 store. */
+  projectLedger: boolean;
+}
+
+export type GrantStoreRefusalReason = "malformed" | "unsupported-version" | "unreadable" | "wrong-cwd";
+export type StoredGrantState =
+  { state: "absent" } | { state: "valid"; stored: StoredGrant } | { state: "refuse"; reason: GrantStoreRefusalReason };
+
+export interface SaveGrantOptions {
+  projectLedger?: boolean;
+}
+
+/** `$PI_CODING_AGENT_DIR`, or pi's default. Same resolution as the approval store. */
+function agentDir(): string {
+  return resolveAgentDir();
+}
+
+/**
+ * Where this directory's grant lives.
+ *
+ * Slug plus a 64-bit hash, exactly as `approvalsPath` does it and for the same two reasons: the basename
+ * keeps the directory legible to a human reading it, and the hash is what makes it unambiguous, since two
+ * checkouts can share a basename.
+ */
+export function grantStorePath(cwd: string): string {
+  return userGrantStorePath(cwd); // `<agent dir>/pi-daddy/grants/<slug>-<16 hex>.json` since ADR-0076 PR 3c
+}
+
+/**
+ * Parse a store file's text into its versioned project choice, or null.
+ *
+ * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
+ * must agree, and two parsers is how they come to disagree.
+ *
+ * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
+ * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
+ * check is R-27's: a copied file describes a directory nobody authorised it for.
+ */
+export function parseStoredGrantState(text: string, cwd: string): StoredGrantState {
+  let parsed: { version?: unknown; cwd?: unknown; grant?: unknown; projectLedger?: unknown };
+  try {
+    parsed = JSON.parse(text) as typeof parsed;
+  } catch {
+    return { state: "refuse", reason: "malformed" };
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { state: "refuse", reason: "malformed" };
+  }
+  if (parsed.version !== 1 && parsed.version !== 2) {
+    return { state: "refuse", reason: "unsupported-version" };
+  }
+  if (parsed.cwd !== cwd) return { state: "refuse", reason: "wrong-cwd" };
+  if (!Array.isArray(parsed.grant)) return { state: "refuse", reason: "malformed" };
+  if (!parsed.grant.every((c) => typeof c === "string" && c.length > 0)) {
+    return { state: "refuse", reason: "malformed" };
+  }
+  if (parsed.version === 2 && parsed.projectLedger !== true) {
+    return { state: "refuse", reason: "malformed" };
+  }
+  return {
+    state: "valid",
+    stored: { grant: parsed.grant as Capability[], projectLedger: parsed.version === 2 },
+  };
+}
+
+export function parseStoredGrant(text: string, cwd: string): StoredGrant | null {
+  const result = parseStoredGrantState(text, cwd);
+  return result.state === "valid" ? result.stored : null;
+}
+
+/** Compatibility view for callers that need only the capability ceiling. */
+export function parseGrantFile(text: string, cwd: string): Capability[] | null {
+  return parseStoredGrant(text, cwd)?.grant ?? null;
+}
+
+/**
+ * Read this directory's stored grant, synchronously.
+ *
+ * **Sync on purpose, and this is the constraint that shapes the feature.** Whether `delegate` is registered
+ * at all is decided when the extension factory runs (S-5: a session without `tool:delegate` must not be
+ * offered the tool), and that is before any `await` is possible. An async read would resolve after the
+ * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
+ * defect R-38 and R-39 were.
+ */
+export function loadStoredGrantStateSync(cwd: string): StoredGrantState {
+  try {
+    return parseStoredGrantState(readFileSync(grantStorePath(cwd), "utf8"), cwd);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { state: "absent" }
+      : { state: "refuse", reason: "unreadable" };
+  }
+}
+
+export function loadStoredGrantSync(cwd: string): StoredGrant | null {
+  const result = loadStoredGrantStateSync(cwd);
+  return result.state === "valid" ? result.stored : null;
+}
+
+export function loadGrantSync(cwd: string): Capability[] | null {
+  return loadStoredGrantSync(cwd)?.grant ?? null;
+}
+
+/** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
+export async function loadStoredGrantState(cwd: string): Promise<StoredGrantState> {
+  try {
+    return parseStoredGrantState(await readFile(grantStorePath(cwd), "utf8"), cwd);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT"
+      ? { state: "absent" }
+      : { state: "refuse", reason: "unreadable" };
+  }
+}
+
+export async function loadStoredGrant(cwd: string): Promise<StoredGrant | null> {
+  const result = await loadStoredGrantState(cwd);
+  return result.state === "valid" ? result.stored : null;
+}
+
+export async function loadGrant(cwd: string): Promise<Capability[] | null> {
+  return (await loadStoredGrant(cwd))?.grant ?? null;
+}
+
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export function projectLedgerPath(cwd: string): string {
+  return projectLedgerFile(cwd);
+}
+
+export type SaveOutcome = "saved" | "failed" | "busy";
+
+/**
+ * Write this directory's grant and optional project-ledger consent as one atomic choice.
+ *
+ * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
+ * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
+ * and changes nothing — the caller reports it and the operator retries, which is the honest outcome for a
+ * write that never looked at the file (R-68).
+ *
+ * `wx` on the temp file refuses to follow a pre-existing symlink, and `rename` is atomic within a
+ * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
+ * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
+ */
+export async function saveGrant(
+  cwd: string,
+  grant: Capability[],
+  options: SaveGrantOptions = {},
+): Promise<SaveOutcome> {
+  const path = grantStorePath(cwd);
+  const common = { cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+  const file: GrantFileV1 | GrantFileV2 = options.projectLedger
+    ? { version: 2, ...common, projectLedger: true }
+    : { version: 1, ...common };
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    return await withFileLock(path, "grant store", async () => {
+      const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temp, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        await rename(temp, path);
+        return "saved" as const;
+      } catch {
+        await unlink(temp).catch(() => undefined);
+        return "failed" as const;
+      }
+    });
+  } catch (error) {
+    return error instanceof LockTimeoutError ? "busy" : "failed";
+  }
+}
+
+/** Remove this directory's stored grant. True when a file was there to remove. */
+export async function clearGrant(cwd: string): Promise<boolean> {
+  const path = grantStorePath(cwd);
+  try {
+    await readFile(path, "utf8");
+  } catch {
+    return false;
+  }
+  await rm(path, { force: true }).catch(() => undefined);
+  return true;
+}

package/src/governance/init.ts

@@ -0,0 +1,447 @@
+/**
+ * `pi-daddy init` — scaffold a governed project from the skill packages already installed (B2, P3).
+ *
+ * Legacy unregistered npm packages can be scaffolded per skill: create a directory, copy the
+ * body and declaration copies plus a starting `PI_DADDY_GRANT`. Configured enabled Pi resources
+ * are referenced where installed instead (ADR-0074); no competing .pi/skills copy is created.
+ *
+ * **The line it does not cross, and the reason this module exists at all:** `init` writes files an operator
+ * then **reviews, edits and commits**. It never chooses a ceiling. A skill that declares `allowed-tools` is
+ * copied *verbatim* — the author's declaration is the ceiling, and re-deriving it here would put a second
+ * opinion between the file and the enforcer. A skill that declares none is copied with a **commented**
+ * placeholder and stays unspawnable until a human fills it in.
+ *
+ * **What it DOES choose is the starting grant, which is a stronger act** — ADR-0029, added after a reviewer
+ * pointed out that ADR-0028 drew its boundary around the wrong object. The handoff's reason a third party
+ * may safely author `allowed-tools` is that *"the operator's `PI_DADDY_GRANT` still bounds it"*; a
+ * generated union gives the bound and the bounded one author, and it is not the operator. So capabilities
+ * that can change a machine are emitted **commented** (`./grant-env.ts`).
+ *
+ * The placeholder is deliberately not a working example. Uncommenting it unedited yields capability ids
+ * like `tool:<list` which the catalog refuses as unknown — a loud failure, in the direction rule 8 asks
+ * for, rather than a grant nobody decided.
+ */
+
+import { lstat, mkdir, open, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { agentCapability, workspaceCapability } from "../kernel/capabilities.ts";
+import { ceilingForDefinition } from "../kernel/definitions.ts";
+import { runWithFinalizers } from "./finalization.ts";
+import {
+  ALWAYS_LIVE,
+  assertGrantIsWritable,
+  isLiveByDefault,
+  renderProjectSettings,
+  type GrantEnvSkill,
+} from "../kernel/grant-env.ts";
+import { PI_BUILTIN_TOOLS } from "../kernel/pi-tools.ts";
+import type { Capability } from "../kernel/resolve.ts";
+import type { SkillPackage } from "../kernel/skill-packages.ts";
+import {
+  PI_PROJECT_DIR,
+  PROJECT_FILES,
+  PROJECT_GITIGNORE_CONTENT,
+  PROJECT_STATE_DIRNAME,
+  piProjectDir,
+  projectGitignorePath,
+  projectSettingsPath,
+  projectStateDir,
+} from "../kernel/project-paths.ts";
+import { spawnSync } from "node:child_process";
+
+/**
+ * Count declarations, not authorizations (R-73). Both pattern and needs-withheld mean the skill
+ * declared a ceiling; only undeclared means it did not. The CLI must report the same distinction.
+ */
+export function countDeclaring(skills: PlannedSkill[], from: string): number {
+  return skills.filter((s) => s.from === from && s.withheld !== "undeclared").length;
+}
+
+export type WithholdReason = "undeclared" | "pattern" | "needs-withheld";
+
+export interface PlannedSkill {
+  name: string;
+  /** Which package it came from, as `name@version`. */
+  from: string;
+  sourcePath: string;
+  targetPath: string;
+  /** Configured skills stay at their installed/local source, including when --force is used. */
+  referenced?: boolean;
+  /** Exactly what would be written — the file verbatim, or the file plus a commented note. */
+  content: string;
+  /** The declared ceiling, empty when the declaration is absent or unusable. */
+  ceiling: Capability[];
+  withheld: WithholdReason | null;
+  /** e.g. a sub-tool pattern pi's `--tools` cannot express. Reported, never reinterpreted. */
+  notes: string[];
+}
+
+export interface InitPlan {
+  skills: PlannedSkill[];
+  /** Definitions two packages both declare. First wins; the loser is named rather than silently dropped. */
+  collisions: string[];
+  /** The live grant — what `settings.json` records and the grant store applies. */
+  grant: Capability[];
+  /** Withheld capability → the definitions that declared it (ADR-0029). Emitted commented. */
+  withheldCapabilities: Map<Capability, string[]>;
+  /** `workspace:<id>` this project could route to (ADR-0035). Always commented — `init` does not choose. */
+  routableWorkspaces: Capability[];
+  /** `<cwd>/.pi/pi-daddy` — created owner-only by apply. */
+  stateDir: string;
+  settingsPath: string;
+  settingsContent: string;
+  gitignorePath: string;
+  /** Capabilities a declared ceiling names that pi 0.84.1 has no tool for — a caution, not a verdict. */
+  cautions: string[];
+}
+
+const PLACEHOLDER = [
+  "# pi-daddy: this skill declares no `allowed-tools`, so it CANNOT be spawned as a governed sub-agent —",
+  "# an undeclared capability set is treated as NONE, never as everything. Decide what it needs, then",
+  "# uncomment and complete the line below. pi-daddy does not choose this for you: the capability set is",
+  "# the thing you are meant to review and commit.",
+  "# pi 0.84.1's tools: " + PI_BUILTIN_TOOLS.join(", ") + ".",
+  "# allowed-tools: <list the tools this skill needs, e.g. Read, Grep>",
+];
+
+/**
+ * A copied file that is unspawnable for a reason an operator cannot see by reading it.
+ *
+ * The undeclared case got four explanatory lines from the start; a pattern-carrying one got nothing, so
+ * opening `.pi/skills/git-ops/SKILL.md` to find out why it will not spawn showed a perfectly ordinary file.
+ * Same argument, opposite treatment — now the same treatment.
+ */
+const patternNote = (patterns: string[]) => [
+  "# pi-daddy: this skill CANNOT be spawned as a governed sub-agent. Its `allowed-tools` restricts a tool",
+  `# with a pattern (${patterns.join(", ")}), and pi's --tools matches whole tool names only — granting the`,
+  "# bare tool would widen the declaration and dropping it would silently narrow, so neither is done.",
+  "# Replace the pattern with whole tool names to make it spawnable.",
+];
+
+/**
+ * The file to write for one skill: verbatim when it declares a usable ceiling, plus a commented note when
+ * it does not.
+ *
+ * Inserted at the END of the frontmatter block, so the rest of the file — including its own key order and
+ * its body — is byte-identical to the package's. A `#` line is a YAML comment and this package's
+ * frontmatter reader skips it, so an undeclared copy is still *undeclared*: not spawnable until a human
+ * edits it, which is the whole point.
+ */
+export function withPlaceholder(text: string, declared: boolean, note: string[] = PLACEHOLDER): string {
+  if (declared) return text;
+  const match = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(text);
+  // No frontmatter at all means `parseSkillDefinition` returned null and this skill was never discovered;
+  // inventing one here would invent a file shape. Left exactly as it is.
+  if (!match) return text;
+  const [full, opening, body, close] = match;
+  const eol = close.startsWith("\r\n") ? "\r\n" : "\n";
+  return opening + body + eol + note.join(eol) + close + text.slice(full.length);
+}
+
+/** `tool:` ids pi 0.84.1 has no tool for. `delegate` is this package's own, hence the exemption. */
+function unknownToolIds(capabilities: Capability[]): Capability[] {
+  const builtins = new Set<string>(PI_BUILTIN_TOOLS);
+  return capabilities.filter(
+    (c) => c.startsWith("tool:") && c !== ALWAYS_LIVE && !builtins.has(c.slice("tool:".length)),
+  );
+}
+
+/**
+ * Decide what `init` would write. Pure: no filesystem, no npm, no decisions taken on the operator's behalf.
+ *
+ * The grant is **the read-only part** of what the copied skills declare, plus one `agent:` id per definition
+ * that can actually run within it, plus `tool:delegate` — without which the session registers no delegation
+ * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
+ * away (ADR-0029).
+ */
+export function planInit(
+  packages: SkillPackage[],
+  cwd: string,
+  /**
+   * Ids from the operator's workspace registry, when one is configured — read by the CALLER, because
+   * `planInit` is pure and stays that way.
+   *
+   * ADR-0035 made routing a capability and said `init` "scaffolds the registered ids so the common path is a
+   * one-line grant edit". It did not: `init` had never heard of the registry, so the ADR's own stated
+   * migration path for a breaking change did not exist. These are emitted **commented**, never live —
+   * offering the ids while refusing to choose among them is exactly ADR-0028's position.
+   */
+  registeredWorkspaceIds: readonly string[] = [],
+): InitPlan {
+  const skills: PlannedSkill[] = [];
+  const collisions: string[] = [];
+  const seen = new Set<string>();
+
+  for (const pkg of packages) {
+    for (const skill of pkg.skills) {
+      const name = skill.definition.name;
+      if (seen.has(name)) {
+        collisions.push(`${name} (also in ${pkg.name}@${pkg.version}, not written)`);
+        continue;
+      }
+      seen.add(name);
+
+      const ceiling = ceilingForDefinition(skill.definition);
+      const notes: string[] = [];
+      let withheld: WithholdReason | null = null;
+      let note = PLACEHOLDER;
+      if (ceiling.undeclared) withheld = "undeclared";
+      else if (ceiling.patterns.length > 0) {
+        withheld = "pattern";
+        note = patternNote(ceiling.patterns);
+        notes.push(
+          `declares ${ceiling.patterns.join(", ")} — pi's --tools matches whole tool names only, so a ` +
+            `sub-tool pattern is refused rather than reinterpreted (granting the bare tool would widen it)`,
+        );
+      }
+
+      skills.push({
+        name,
+        from: `${pkg.name}@${pkg.version}`,
+        sourcePath: skill.path,
+        targetPath: skill.referenced ? skill.path : join(piProjectDir(cwd), "skills", name, "SKILL.md"),
+        referenced: skill.referenced,
+        content: withPlaceholder(skill.text, withheld === null, note),
+        ceiling: ceiling.capabilities,
+        withheld,
+        notes,
+      });
+    }
+  }
+
+  // ADR-0029: split what the declared ceilings ask for into what `init` grants live and what it comments.
+  const declared = skills.filter((s) => s.withheld === null);
+  const withheldCapabilities = new Map<Capability, string[]>();
+  for (const skill of declared) {
+    for (const capability of skill.ceiling) {
+      if (isLiveByDefault(capability)) continue;
+      // A routing destination is withheld but does NOT belong in this map, and the difference is not
+      // cosmetic. This map drives two things: the "WITHHELD BY DEFAULT — these can change your machine"
+      // block, and `/grants init`'s dialog. Review found a `workspace:` id reaching both — described to the
+      // operator with `tool:bash`'s rationale (routing does not change your machine, and unlike `bash` it
+      // *is* gateable), and then granted **live and persisted** on one "Yes", off a third-party package's
+      // declaration. That is the rule `grant-env.ts` states — "does not become live because a package asked
+      // for it" — honoured by the rendered file and broken by the dialog beside it: two surfaces of one
+      // command disagreeing, which is R-28's shape inside the fix for R-28.
+      //
+      // Which worktree a child starts in is not derivable from a declaration (ADR-0028), so `init` lists
+      // routing and never grants it. `routableWorkspaces` below is where these go; the definition that
+      // declared one still loses its live `agent:` id via the `needs-withheld` pass, so nothing becomes
+      // spawnable behind the operator's back either.
+      if (capability.startsWith("workspace:")) continue;
+      withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
+    }
+  }
+
+  // A definition needing a withheld capability does not get a live `agent:` id either: authorising it to run
+  // and then refusing it at spawn time is a worse answer than not authorising it, and it would put an
+  // `agent:` id in the grant whose definition cannot work — the shape ADR-0028 rule 3 already refuses.
+  for (const skill of declared) {
+    if (skill.ceiling.some((c) => !isLiveByDefault(c))) skill.withheld = "needs-withheld";
+  }
+
+  const authorised = skills.filter((s) => s.withheld === null);
+  const written = new Set(authorised.map((s) => s.name));
+  // `agent:<other>` in a ceiling is legitimate — it is how a delegator learns which definitions IT may
+  // spawn — but a name `init` did not write here would authorise a file from another skill root that the
+  // operator is not reviewing, including `~/.pi/agent/skills`, which other tools install into. Reported,
+  // never granted: the same objection ADR-0028 rule 3 makes to authorising an undeclared skill.
+  const crossReferences: { from: string; capability: Capability }[] = [];
+  const live = new Set<Capability>([ALWAYS_LIVE]);
+  for (const skill of authorised) {
+    live.add(agentCapability(skill.name));
+    for (const capability of skill.ceiling) {
+      if (capability.startsWith("agent:") && !written.has(capability.slice("agent:".length))) {
+        crossReferences.push({ from: skill.name, capability });
+        continue;
+      }
+      live.add(capability);
+    }
+  }
+  const grant = [...live].sort();
+
+  const cautions = authorised.flatMap((s) =>
+    unknownToolIds(s.ceiling).map(
+      (c) =>
+        `${s.name} declares ${c}, which pi 0.84.1 has no tool for — unless an extension provides it, ` +
+        `spawning ${s.name} is refused as an unknown capability`,
+    ),
+  );
+
+  // R-78's structural backstop. Throws rather than rendering something a shell could read as more than a
+  // value, so a gap in the per-entry whitelist costs a refusal instead of an injection.
+  assertGrantIsWritable(grant);
+
+  const describe: Record<WithholdReason, (s: PlannedSkill) => string> = {
+    undeclared: (s) => "declares no `allowed-tools` — fill it in, then add `agent:" + s.name + "` below",
+    pattern: (s) => s.notes.join("; "),
+    "needs-withheld": (s) =>
+      `needs ${s.ceiling.filter((c) => !isLiveByDefault(c)).join(", ")}, withheld by default — see below`,
+  };
+
+  const grantEnvSkills: GrantEnvSkill[] = skills.map((s) => ({
+    name: s.name,
+    ceiling: s.ceiling,
+    ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
+  }));
+
+  // Registry ids the operator could route to, plus any a copied definition actually declares — a package
+  // naming `workspace:prod` is evidence that id matters here, and it must still be uncommented by hand.
+  const declaredWorkspaces = skills.flatMap((s) => s.ceiling.filter((c) => c.startsWith("workspace:")));
+  const routableWorkspaces = [
+    ...new Set([...registeredWorkspaceIds.map(workspaceCapability), ...declaredWorkspaces]),
+  ].sort();
+
+  return {
+    skills,
+    collisions,
+    grant,
+    withheldCapabilities,
+    routableWorkspaces,
+    stateDir: projectStateDir(cwd),
+    settingsPath: projectSettingsPath(cwd),
+    gitignorePath: projectGitignorePath(cwd),
+    settingsContent: renderProjectSettings({
+      skills: grantEnvSkills,
+      live: grant,
+      withheld: withheldCapabilities,
+      withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
+      crossReferences,
+      cautions,
+      routableWorkspaces,
+    }),
+    cautions,
+  };
+}
+
+export interface InitOutcome {
+  written: string[];
+  /** Present already, so left alone. `init` never silently overwrites an edited ceiling. */
+  kept: string[];
+  failed: { path: string; error: string }[];
+}
+
+/**
+ * Create a file only if nothing is there, and **never through a symlink**.
+ *
+ * Both properties come from `O_CREAT|O_EXCL` (`flag: "wx"`), and both were defects in the first version
+ * (R-79). It probed for existence with `readFile` and then called `writeFile`:
+ *
+ *  - `readFile` conflates *unreadable* with *absent*, so an operator's `SKILL.md` with restrictive
+ *    permissions was reported `wrote` and their narrowed `allowed-tools: Read` was replaced by the
+ *    package's wider one — **without `--force`**, falsifying this package's own documented "Kept" rule.
+ *    A FIFO at the target path hung the probe forever, with no timeout anywhere in the path.
+ *  - `writeFile` follows symlinks, so a dangling symlink at a target path created the file at the link's
+ *    destination, outside the project, while reporting an in-project path. That is **B-I6**, which
+ *    `approval-store.ts` already fixed for the approval store under ADR-0014 — a new writer in the same
+ *    package reintroducing a defect the package documents as closed, and whose comment says in so many
+ *    words *"never through a symlink"*.
+ *
+ * `wx` fails with `EEXIST` on anything at the path, including a dangling symlink, so there is no probe, no
+ * race between the probe and the write, and no way to write through a link.
+ */
+async function createUnlessPresent(path: string, content: string, outcome: InitOutcome): Promise<void> {
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    const handle = await open(path, "wx");
+    await runWithFinalizers(
+      () => handle.writeFile(content, "utf8"),
+      [{ label: "new-file handle cleanup failed", run: () => handle.close() }],
+    );
+    outcome.written.push(path);
+  } catch (error) {
+    if ((error as { code?: string }).code === "EEXIST") outcome.kept.push(path);
+    else outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/** Replace a file, unlinking first so a symlink is REPLACED rather than written through. */
+async function replace(path: string, content: string, outcome: InitOutcome): Promise<void> {
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    // `rm` unlinks the LINK, never its target — which is exactly the semantics `--force` should have.
+    await rm(path, { force: true });
+    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    outcome.written.push(path);
+  } catch (error) {
+    outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/**
+ * Apply a plan.
+ *
+ * **Existing files are kept, not overwritten**, and that default is load-bearing rather than polite: the
+ * edit an operator makes to one of these files IS the capability decision, and the second run of a
+ * scaffolding command is exactly when it would be destroyed.
+ *
+ * **`--force` never regenerates `settings.json`** (R-79). It rewrites the definition copies, which is the
+ * documented re-sync path for R-74 — but the grant file is the *reviewed artifact*, and an operator who had
+ * deleted `agent:build` and added a ledger path would have had both silently restored to generated defaults
+ * by a command whose usage text mentions only `allowed-tools`. Deleting the file is how to regenerate it,
+ * and that is not something anyone does by accident.
+ */
+/**
+ * Whether git would ignore `settings.json` anyway — the common case, because most projects' root `.gitignore`
+ * lists `.pi/`, and git never descends into an ignored directory, so the nested `!settings.json` cannot
+ * re-include it (ADR-0076 PR 3c review finding). `true` = ignored, `false` = tracked-or-untracked, `null` =
+ * not a git checkout or git unavailable; the caller only warns on `true`.
+ */
+export async function settingsIgnoredByGit(settingsPath: string): Promise<boolean | null> {
+  try {
+    const { status } = spawnSync(
+      "git",
+      ["-C", dirname(dirname(dirname(settingsPath))), "check-ignore", "-q", "--", settingsPath],
+      {
+        stdio: "ignore",
+        timeout: 5000,
+      },
+    );
+    if (status === 0) return true;
+    if (status === 1) return false;
+    return null; // 128: not a repository, or git refused
+  } catch {
+    return null;
+  }
+}
+
+/** The two lines an operator adds to the root `.gitignore` so the reviewable record is committable. */
+export const GITIGNORE_REINCLUDE_LINES = [
+  `!${PI_PROJECT_DIR}/`,
+  `!${PI_PROJECT_DIR}/${PROJECT_STATE_DIRNAME}/${PROJECT_FILES.settings}`,
+];
+
+export async function applyInit(plan: InitPlan, options: { force?: boolean } = {}): Promise<InitOutcome> {
+  const outcome: InitOutcome = { written: [], kept: [], failed: [] };
+  // pi's `.pi` first, then our owner-only state directory inside it. Existing operator/Pi state is never
+  // chmodded, followed through a symlink, or reused if it is not a directory.
+  for (const dir of [dirname(plan.stateDir), plan.stateDir]) {
+    try {
+      await mkdir(dir, { mode: 0o700 });
+      const created = await lstat(dir);
+      if (!created.isDirectory() || created.isSymbolicLink()) throw Error("private state directory creation failed");
+    } catch (error) {
+      if ((error as { code?: string }).code !== "EEXIST") {
+        outcome.failed.push({ path: dir, error: error instanceof Error ? error.message : String(error) });
+        return outcome;
+      }
+      const existing = await lstat(dir);
+      if (existing.isSymbolicLink() || !existing.isDirectory()) {
+        outcome.failed.push({
+          path: dir,
+          error: "existing state path is not a directory; it was not followed or changed",
+        });
+        return outcome;
+      }
+    }
+  }
+  const force = options.force === true;
+  for (const skill of plan.skills) {
+    if (skill.referenced) continue;
+    if (force) await replace(skill.targetPath, skill.content, outcome);
+    else await createUnlessPresent(skill.targetPath, skill.content, outcome);
+  }
+  await createUnlessPresent(plan.settingsPath, plan.settingsContent, outcome);
+  await createUnlessPresent(plan.gitignorePath, PROJECT_GITIGNORE_CONTENT, outcome);
+  return outcome;
+}