pi-daddy 0.28.0 → 0.32.0

package/dist/governance/grant-store.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 type { Capability } from "../kernel/resolve.ts";
+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;
+}
+/**
+ * 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 declare function grantStorePath(cwd: string): string;
+/**
+ * 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 declare function parseStoredGrantState(text: string, cwd: string): StoredGrantState;
+export declare function parseStoredGrant(text: string, cwd: string): StoredGrant | null;
+/** Compatibility view for callers that need only the capability ceiling. */
+export declare function parseGrantFile(text: string, cwd: string): Capability[] | 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 declare function loadStoredGrantStateSync(cwd: string): StoredGrantState;
+export declare function loadStoredGrantSync(cwd: string): StoredGrant | null;
+export declare function loadGrantSync(cwd: string): Capability[] | null;
+/** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
+export declare function loadStoredGrantState(cwd: string): Promise<StoredGrantState>;
+export declare function loadStoredGrant(cwd: string): Promise<StoredGrant | null>;
+export declare function loadGrant(cwd: string): Promise<Capability[] | null>;
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export declare function projectLedgerPath(cwd: string): string;
+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 declare function saveGrant(cwd: string, grant: Capability[], options?: SaveGrantOptions): Promise<SaveOutcome>;
+/** Remove this directory's stored grant. True when a file was there to remove. */
+export declare function clearGrant(cwd: string): Promise<boolean>;
+//# sourceMappingURL=grant-store.d.ts.map

package/dist/governance/grant-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-store.d.ts","sourceRoot":"","sources":["../../src/governance/grant-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAyBvD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,6GAA6G;IAC7G,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,uBAAuB,GAAG,WAAW,GAAG,qBAAqB,GAAG,YAAY,GAAG,WAAW,CAAC;AACvG,MAAM,MAAM,gBAAgB,GAC1B;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAEvH,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAyBjF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAG9E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAQtE;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAGnE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAE9D;AAED,2FAA2F;AAC3F,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQjF;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAG9E;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAEzE;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAED,kFAAkF;AAClF,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS9D"}

package/dist/governance/grant-store.js

@@ -0,0 +1,186 @@
+/**
+ * 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.js";
+import { grantStorePath as userGrantStorePath, projectLedgerPath as projectLedgerFile, agentDir as resolveAgentDir, } from "../kernel/project-paths.js";
+/** `$PI_CODING_AGENT_DIR`, or pi's default. Same resolution as the approval store. */
+function agentDir() {
+    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) {
+    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, cwd) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    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, projectLedger: parsed.version === 2 },
+    };
+}
+export function parseStoredGrant(text, cwd) {
+    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, cwd) {
+    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) {
+    try {
+        return parseStoredGrantState(readFileSync(grantStorePath(cwd), "utf8"), cwd);
+    }
+    catch (error) {
+        return error.code === "ENOENT"
+            ? { state: "absent" }
+            : { state: "refuse", reason: "unreadable" };
+    }
+}
+export function loadStoredGrantSync(cwd) {
+    const result = loadStoredGrantStateSync(cwd);
+    return result.state === "valid" ? result.stored : null;
+}
+export function loadGrantSync(cwd) {
+    return loadStoredGrantSync(cwd)?.grant ?? null;
+}
+/** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
+export async function loadStoredGrantState(cwd) {
+    try {
+        return parseStoredGrantState(await readFile(grantStorePath(cwd), "utf8"), cwd);
+    }
+    catch (error) {
+        return error.code === "ENOENT"
+            ? { state: "absent" }
+            : { state: "refuse", reason: "unreadable" };
+    }
+}
+export async function loadStoredGrant(cwd) {
+    const result = await loadStoredGrantState(cwd);
+    return result.state === "valid" ? result.stored : null;
+}
+export async function loadGrant(cwd) {
+    return (await loadStoredGrant(cwd))?.grant ?? null;
+}
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export function projectLedgerPath(cwd) {
+    return projectLedgerFile(cwd);
+}
+/**
+ * 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, grant, options = {}) {
+    const path = grantStorePath(cwd);
+    const common = { cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+    const file = 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";
+            }
+            catch {
+                await unlink(temp).catch(() => undefined);
+                return "failed";
+            }
+        });
+    }
+    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) {
+    const path = grantStorePath(cwd);
+    try {
+        await readFile(path, "utf8");
+    }
+    catch {
+        return false;
+    }
+    await rm(path, { force: true }).catch(() => undefined);
+    return true;
+}
+//# sourceMappingURL=grant-store.js.map

package/dist/governance/grant-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-store.js","sourceRoot":"","sources":["../../src/governance/grant-store.ts"],"names":[],"mappings":"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"}

package/dist/governance/init.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `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 type { Capability } from "../kernel/resolve.ts";
+import type { SkillPackage } from "../kernel/skill-packages.ts";
+/**
+ * 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 declare function countDeclaring(skills: PlannedSkill[], from: string): number;
+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[];
+}
+/**
+ * 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 declare function withPlaceholder(text: string, declared: boolean, note?: string[]): string;
+/**
+ * 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 declare 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;
+export interface InitOutcome {
+    written: string[];
+    /** Present already, so left alone. `init` never silently overwrites an edited ceiling. */
+    kept: string[];
+    failed: {
+        path: string;
+        error: string;
+    }[];
+}
+/**
+ * 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 declare function settingsIgnoredByGit(settingsPath: string): Promise<boolean | null>;
+/** The two lines an operator adds to the root `.gitignore` so the reviewable record is committable. */
+export declare const GITIGNORE_REINCLUDE_LINES: string[];
+export declare function applyInit(plan: InitPlan, options?: {
+    force?: boolean;
+}): Promise<InitOutcome>;
+//# sourceMappingURL=init.d.ts.map

package/dist/governance/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/governance/init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAeH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAahE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAEzE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,8FAA8F;IAC9F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,4FAA4F;IAC5F,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,0GAA0G;IAC1G,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iFAAiF;IACjF,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,4FAA4F;IAC5F,oBAAoB,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAChD,0GAA0G;IAC1G,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,uGAAuG;IACvG,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,GAAE,MAAM,EAAgB,GAAG,MAAM,CASrG;AAUD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,YAAY,EAAE,EACxB,GAAG,EAAE,MAAM;AACX;;;;;;;;GAQG;AACH,sBAAsB,GAAE,SAAS,MAAM,EAAO,GAC7C,QAAQ,CAiJV;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0FAA0F;IAC1F,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAiDD;;;;;;;;;;;;GAYG;AACH;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAgBxF;AAED,uGAAuG;AACvG,eAAO,MAAM,yBAAyB,UAGrC,CAAC;AAEF,wBAAsB,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAiCvG"}