@pareto4/pp-core 1.10.0 → 1.11.0

package/pp-core/bin/lib/init-contract.cjs

@@ -0,0 +1,989 @@
+"use strict";
+/**
+ * src/init-contract.cts — the `/pp-init` question set and end-state
+ * invariant check, as code (milestone v1.11.0, Phase 34-07, gap closure).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/init-contract.cjs`; do NOT
+ * hand-edit the compiled output. Behaviour is locked by
+ * `tests/init-contract.test.cjs`.
+ *
+ * Born from a documented failure, not a speculative hardening. Two human
+ * UAT walks of `/pp-init` (`34-VALIDATION.md` § Manual-Only Verifications,
+ * `34-05-SUMMARY.md`) found that prose-driven load-bearing behaviour — a
+ * question set that must not shrink, a step that must not be skippable, a
+ * config key that must be set — is not reliably enforced by an executing
+ * agent re-interpreting Markdown, even after two escalating rounds of
+ * explicit in-file hardening. `buildInitQuestions` moves the canonical
+ * question set (and the provider option list, derived from `PROVIDERS`
+ * rather than retyped) out of prose into tested data; `verifyInitInvariants`
+ * inspects the RESULTING project state after init runs, rather than
+ * trusting that any one step announced itself — enforcement placed inside
+ * the step it protects does not constrain an agent that skips the step
+ * entirely (see `34-VALIDATION.md`'s diagnosis).
+ *
+ * Both functions are read-only and never throw. `verifyInitInvariants`
+ * calls `composeBindings` in offline mode to answer "was a composable
+ * binding ever produced" — this module therefore sits ABOVE
+ * `src/compose-bindings.cts` in the CommonJS graph. Nothing in
+ * `compose-bindings.cts`, `git-provider.cts` or `org-profile.cts` imports
+ * this module, at load time or lazily, so this introduces no require cycle.
+ *
+ * This module's own prose deliberately never names a concrete org profile
+ * package or client, matching the convention `src/org-profile.cts` and
+ * `src/compose-bindings.cts` both state in their own headers.
+ *
+ * Residual risk, stated plainly (see the plan's threat register): nothing
+ * here prevents an agent from declining to call this arm at all.
+ * `buildInitQuestions` makes the rendered content correct when called;
+ * `verifyInitInvariants` makes the omission provable afterwards, by
+ * inspecting state `init.md` cannot avoid leaving behind. It does not make
+ * step-skipping impossible.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INIT_SESSION_WRITE_FAILED = exports.INIT_SESSION_MALFORMED = exports.INIT_CONTRACT_FLAGS = exports.INIT_COMPOSE_DECLINED_KEY = void 0;
+exports.buildInitQuestions = buildInitQuestions;
+exports.verifyInitInvariants = verifyInitInvariants;
+exports.initSessionNext = initSessionNext;
+exports.initSessionAnswer = initSessionAnswer;
+exports.initSessionReset = initSessionReset;
+exports.cmdInitContract = cmdInitContract;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output } = io;
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const org_profile_cjs_1 = require("./org-profile.cjs");
+const compose_bindings_cjs_1 = require("./compose-bindings.cjs");
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// ─── Constants ───────────────────────────────────────────────────────────────
+/**
+ * The dotted `.planning/config.json` key `/pp-init` Step 2.5 sets when the
+ * operator explicitly declines the compose-and-write confirmation. This is
+ * the ONLY signal that distinguishes "the operator was asked and said no"
+ * from "the step never ran at all" — both leave `.platform-bindings.json`
+ * absent, and `verifyInitInvariants` cannot tell them apart any other way
+ * (see `INVARIANT_CODE.COMPOSITION_NOT_RUN` below). Registered as a
+ * `vault` capability config key (`capabilities/vault/capability.json`) so
+ * `pp-tools config-set` accepts it without the "unknown config key" error
+ * a bare unregistered top-level namespace would trip.
+ */
+exports.INIT_COMPOSE_DECLINED_KEY = 'init.compose_declined';
+/** The identity-only choices appended after the provider seam's own
+ * `PROVIDERS` list — never retyped ahead of `PROVIDERS` itself (T-34-50). */
+const IDENTITY_ONLY_PROVIDER_OPTIONS = Object.freeze(['github', 'other', 'none']);
+/** Bounds the `node_modules` scan `verifyInitInvariants` runs to answer
+ * "could an org profile package have been pointed to" — a DoS guard, the
+ * same convention `src/org-profile.cts`'s `PROFILE_FLATTEN_LEAF_CAP` and
+ * `PROFILE_FLATTEN_DEPTH_CAP` use for the analogous profile-document walk. */
+const NODE_MODULES_SCAN_CAP = 2000;
+const INVARIANT_CODE = Object.freeze({
+    ORG_PROFILE_UNASKED: 'INIT_QUESTIONS_ORG_PROFILE_UNASKED',
+    COMPOSITION_NOT_RUN: 'INIT_COMPOSITION_NOT_RUN',
+    VAULT_PROVIDER_UNSET: 'INIT_VAULT_PROVIDER_UNSET',
+    IDENTITY_MISSING: 'INIT_IDENTITY_MISSING',
+});
+/** The recognized flag set for the `init-contract` CLI arm (the
+ * `pp-tools.cjs` fail-fast unrecognized-flag guard reads this, mirroring
+ * `COMPOSE_BINDINGS_FLAGS`). Extended by Task 2 (34-08 gap closure) with the
+ * session relay flags — `--session-answer` additionally consumes the next
+ * argv token as its `<stepId>=<value>` payload (parsed in `pp-tools.cjs`,
+ * mirroring the `--cwd`/`--pick` convention), and `--offline` forwards to
+ * every `composeBindings` call the session makes so a CLI-driven loop can
+ * run with no network access — parity with `compose-bindings --offline`. */
+exports.INIT_CONTRACT_FLAGS = Object.freeze([
+    '--questions',
+    '--verify',
+    '--session-next',
+    '--session-answer',
+    '--session-reset',
+    '--offline',
+]);
+/** `.planning/.init-session.json` — the CLI-owned session state file
+ * (Artifacts table, 34-08). Never hand-edited; malformed content is
+ * refused, not silently repaired (T-34-63). */
+const INIT_SESSION_FILE_NAME = '.init-session.json';
+/** The `error` code `initSessionNext`/`initSessionAnswer` report when the
+ * session file exists but does not parse as valid session state — the ONLY
+ * recovery is `--session-reset` (T-34-63); this module never resumes a
+ * malformed file into a guessed-at state. */
+exports.INIT_SESSION_MALFORMED = 'INIT_SESSION_MALFORMED';
+/** CR-01: the `error`/`reason` code `initSessionNext`/`initSessionAnswer`
+ * report when a filesystem write this module performs (`persistSession`,
+ * `writeConfigMerge`, the write-mode `composeBindings` call) fails — e.g. an
+ * unwritable `.planning` directory (permissions, a read-only mount, a full
+ * disk). Every sibling module in this seam (`composeBindings`,
+ * `resolveOrgProfileDocument`, `resolveOrgProfile`, `verifyInitInvariants`)
+ * never throws and degrades to a bounded data verdict instead (D-09); this
+ * module previously did not follow that convention on its write paths and
+ * let the exception escape uncaught. Recovery is to fix the underlying
+ * filesystem issue and retry the same step — nothing is left half-recorded,
+ * since the throw is caught before `session` is persisted. */
+exports.INIT_SESSION_WRITE_FAILED = 'INIT_SESSION_WRITE_FAILED';
+/** compose_confirm's answer vocabulary — deliberately permissive so a human
+ * relaying through `AskUserQuestion`/TEXT_MODE can answer naturally; every
+ * other string is rejected (never silently treated as a decline). */
+const YES_VALUES = Object.freeze(['yes', 'y', 'approve', 'approved', 'true']);
+const NO_VALUES = Object.freeze(['no', 'n', 'decline', 'declined', 'false']);
+/** Maps each of the 7 identity/provider/visibility question ids (every
+ * question but `org_profile`, which is written immediately on answer — see
+ * `initSessionAnswer` — so the very next question, `provider`, can
+ * re-resolve its `preselected` against it) to the short key it is written
+ * under inside `.planning/config.json`'s `project` block. */
+const PROJECT_BLOCK_QUESTION_MAP = Object.freeze({
+    project_name: 'name',
+    project_slug: 'slug',
+    client_name: 'client_name',
+    client_slug: 'client_slug',
+    description: 'description',
+    provider: 'provider',
+    visibility: 'visibility',
+});
+// ─── Small local helpers (deliberate per-module duplication — this repo's
+// established convention for small, cycle-risk-free helpers; see
+// `src/git-provider.cts`'s `cfgGet` for the canonical example) ────────────────
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isUsableString(v) {
+    return typeof v === 'string' && v.trim() !== '';
+}
+function getDotted(obj, dottedPath) {
+    return dottedPath.split('.').reduce((cur, key) => (isObject(cur) ? cur[key] : undefined), obj);
+}
+// ─── buildInitQuestions ────────────────────────────────────────────────────
+/**
+ * The canonical `/pp-init` question set, as data. `init.md` renders exactly
+ * what this returns, in the order returned, none merged, reordered or
+ * dropped — see the module header for why this moved out of prose.
+ *
+ * Question 6 (`org_profile`) is the org profile pointer, marked
+ * `optionalAnswer: true` — that flag describes the ANSWER (pressing Enter
+ * is a complete, valid response), never whether the question is asked.
+ *
+ * Question 7 (`provider`) carries the fixed, complete option list: every
+ * value in `PROVIDERS` (imported, never retyped — this is what keeps
+ * `azure` from being silently dropped again, T-34-50) plus the three
+ * identity-only choices. `preselected` is resolved via `resolveProvider`,
+ * the same authority the `compose-bindings --offline --pick provider`
+ * probe reads (pure config + org-profile consultation, no network) — so
+ * calling it directly here is equivalent, not a second implementation.
+ */
+function buildInitQuestions(cwd) {
+    let preselected = git_provider_cjs_1.DEFAULT_PROVIDER;
+    try {
+        preselected = (0, git_provider_cjs_1.resolveProvider)(cwd).provider;
+    }
+    catch {
+        preselected = git_provider_cjs_1.DEFAULT_PROVIDER;
+    }
+    const providerOptions = Object.freeze([...git_provider_cjs_1.PROVIDERS, ...IDENTITY_ONLY_PROVIDER_OPTIONS]);
+    return [
+        { id: 'project_name', prompt: 'Project name (human-readable, e.g. "Acme Dashboard")', optionalAnswer: false },
+        { id: 'project_slug', prompt: 'Project slug (kebab-case, e.g. "acme-dashboard")', optionalAnswer: false },
+        {
+            id: 'client_name',
+            prompt: 'Client name (company / team, e.g. "Acme Corp") — type "internal" if none',
+            optionalAnswer: false,
+        },
+        {
+            id: 'client_slug',
+            prompt: 'Client slug (kebab-case, e.g. "acme") — type "internal" if none',
+            optionalAnswer: false,
+        },
+        { id: 'description', prompt: 'One-line description (what this project does)', optionalAnswer: false },
+        {
+            id: 'org_profile',
+            // The example is written as an angle-bracket TEMPLATE, not a literal package
+            // name. `tests/org-profile.test.cjs`'s client-confidentiality guard scans this
+            // file for any concrete scope-slash-org-prefix package identifier, so even a
+            // generic literal placeholder trips it. The template keeps the naming
+            // convention visible while staying clean, and the guard stays maximally
+            // strict — no allowlist entry was added for it.
+            prompt: 'Org profile package (optional — press Enter to skip, e.g. "@<your-scope>/org-<name>")',
+            optionalAnswer: true,
+        },
+        {
+            id: 'provider',
+            prompt: 'Provider (gitlab / azure / github / other / none)',
+            optionalAnswer: false,
+            options: providerOptions,
+            preselected,
+            preselectedLabel: `${preselected} (resolved default)`,
+        },
+        { id: 'visibility', prompt: 'Visibility (private / public / internal)', optionalAnswer: false },
+    ];
+}
+// ─── verifyInitInvariants ───────────────────────────────────────────────────
+/**
+ * Byte-for-byte the same heuristic `src/org-profile.cts`'s own (private,
+ * unexported) `resolveGlobalPackageRoot` uses. Duplicated here because it
+ * is not part of that module's public surface — the same per-module
+ * duplication convention every sibling seam module in this repo follows
+ * for helpers it cannot import without either widening an unrelated
+ * module's exports or risking a require cycle.
+ */
+function resolveGlobalNodeModulesRoot() {
+    try {
+        const prefixEnv = process.env.NPM_CONFIG_PREFIX ?? process.env.npm_config_prefix;
+        let candidate;
+        if (typeof prefixEnv === 'string' && prefixEnv.trim() !== '') {
+            const prefix = prefixEnv.trim();
+            candidate =
+                process.platform === 'win32' ? node_path_1.default.join(prefix, 'node_modules') : node_path_1.default.join(prefix, 'lib', 'node_modules');
+        }
+        else {
+            const execDir = node_path_1.default.dirname(process.execPath);
+            candidate =
+                process.platform === 'win32'
+                    ? node_path_1.default.join(execDir, 'node_modules')
+                    : node_path_1.default.resolve(execDir, '..', 'lib', 'node_modules');
+        }
+        return node_fs_1.default.existsSync(candidate) ? candidate : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `nodeModulesDir` contains at least one package directory (one
+ * level, or one level inside an `@scope/` directory) carrying a file named
+ * `ORG_PROFILE_DATA_FILE` at its root — the same fixed filename
+ * `resolveOrgProfileDocument` reads, imported rather than retyped. Bounded
+ * at `NODE_MODULES_SCAN_CAP` total directory entries visited (T-34-54: this
+ * check must never hang on a pathological `node_modules` tree).
+ *
+ * This is a heuristic, not a resolution: it answers "a package shaped like
+ * an org profile is installed here", not "this exact profile would
+ * resolve" — `verifyInitInvariants` never claims more than that.
+ */
+function containsOrgProfileShapedPackage(nodeModulesDir) {
+    let visited = 0;
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(nodeModulesDir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (visited >= NODE_MODULES_SCAN_CAP)
+            return false;
+        visited += 1;
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name.startsWith('@')) {
+            const scopeDir = node_path_1.default.join(nodeModulesDir, entry.name);
+            let scoped;
+            try {
+                scoped = node_fs_1.default.readdirSync(scopeDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const scopedEntry of scoped) {
+                if (visited >= NODE_MODULES_SCAN_CAP)
+                    return false;
+                visited += 1;
+                if (!scopedEntry.isDirectory())
+                    continue;
+                try {
+                    if (node_fs_1.default.existsSync(node_path_1.default.join(scopeDir, scopedEntry.name, org_profile_cjs_1.ORG_PROFILE_DATA_FILE)))
+                        return true;
+                }
+                catch {
+                    continue;
+                }
+            }
+        }
+        else {
+            try {
+                if (node_fs_1.default.existsSync(node_path_1.default.join(nodeModulesDir, entry.name, org_profile_cjs_1.ORG_PROFILE_DATA_FILE)))
+                    return true;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return false;
+}
+function orgProfilePackageResolvable(cwd, opts) {
+    try {
+        const projectNodeModules = node_path_1.default.join(cwd, 'node_modules');
+        if (node_fs_1.default.existsSync(projectNodeModules) && containsOrgProfileShapedPackage(projectNodeModules)) {
+            return true;
+        }
+        const globalRoot = opts._globalRoot !== undefined ? opts._globalRoot : resolveGlobalNodeModulesRoot();
+        if (globalRoot && containsOrgProfileShapedPackage(globalRoot)) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Read `.planning/config.json` at `cwd`, distinguishing "file absent" from
+ * "file present but empty/malformed" — `INIT_IDENTITY_MISSING` only fires
+ * on the latter (see `verifyInitInvariants`'s own doc comment for why an
+ * absent file must never trip it). Never throws. */
+function readConfigFile(cwd) {
+    const configPath = node_path_1.default.join(cwd, '.planning', 'config.json');
+    let exists = false;
+    try {
+        exists = node_fs_1.default.existsSync(configPath);
+        if (!exists) {
+            return { exists: false, parsed: {} };
+        }
+        const raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
+        const parsedUnknown = JSON.parse(raw);
+        return { exists: true, parsed: isObject(parsedUnknown) ? parsedUnknown : {} };
+    }
+    catch {
+        // A present-but-unreadable/malformed file still counts as "a config
+        // file exists" for INIT_IDENTITY_MISSING's purposes.
+        return { exists, parsed: {} };
+    }
+}
+/**
+ * Inspect the project's RESULTING state at `cwd` after an `/pp-init` run
+ * and report every named invariant it violates. Read-only: no filesystem
+ * write anywhere in this function or in the `composeBindings` call it
+ * makes (always `offline: true`, `write` omitted so it defaults to
+ * `false`). Never throws — each check below is independently guarded so
+ * one failing check cannot suppress the others; there is no outer
+ * catch-all because none is needed (see the design note below).
+ *
+ * An empty directory — nothing in `.planning/`, no `.platform-bindings.json`
+ * — returns `{ ok: true, violations: [] }`. Every check requires some
+ * positive signal that a partial init was attempted (a config file present
+ * for `INIT_IDENTITY_MISSING`; a "gitlab"/"azure" `project.provider` for
+ * `INIT_VAULT_PROVIDER_UNSET`; an installed org-profile-shaped package for
+ * `INIT_QUESTIONS_ORG_PROFILE_UNASKED`; a `composable: true` dry run for
+ * `INIT_COMPOSITION_NOT_RUN`) — an empty directory carries none of them, so
+ * nothing is reported as skipped. This is deliberate (see the module
+ * header): nothing was attempted, so nothing can be reported as attempted-
+ * and-abandoned.
+ */
+function verifyInitInvariants(cwd, opts = {}) {
+    const violations = [];
+    const { exists: configExists, parsed } = readConfigFile(cwd);
+    // INIT_IDENTITY_MISSING — only meaningful once a config file exists at
+    // all; an absent file is "nothing was attempted", not a violation.
+    try {
+        if (configExists) {
+            const projectBlock = getDotted(parsed, 'project');
+            const hasProjectBlock = isObject(projectBlock) && Object.keys(projectBlock).length > 0;
+            if (!hasProjectBlock) {
+                violations.push({
+                    code: INVARIANT_CODE.IDENTITY_MISSING,
+                    message: 'No "project" block found in .planning/config.json — Step 2 identity capture did not complete.',
+                });
+            }
+        }
+    }
+    catch {
+        // fail open — one check's fault must not suppress the others
+    }
+    // INIT_VAULT_PROVIDER_UNSET — project.provider names a provisioning
+    // provider (an identity record, D-13) but vault.provider —
+    // resolveProvider's ONLY gating key — was never set, so the D-13
+    // provisioning gate this phase built never fires.
+    try {
+        const projectProvider = getDotted(parsed, 'project.provider');
+        const vaultProvider = getDotted(parsed, 'vault.provider');
+        if ((projectProvider === 'gitlab' || projectProvider === 'azure') && !isUsableString(vaultProvider)) {
+            violations.push({
+                code: INVARIANT_CODE.VAULT_PROVIDER_UNSET,
+                message: `project.provider is "${String(projectProvider)}" but vault.provider is unset — the D-13 provisioning gate is disabled.`,
+            });
+        }
+    }
+    catch {
+        // fail open
+    }
+    // INIT_QUESTIONS_ORG_PROFILE_UNASKED — an org-profile-shaped package is
+    // installed (project node_modules or the machine's global root) but
+    // org.profile was never set, i.e. Question 6 appears to have been
+    // skipped rather than answered blank.
+    try {
+        const orgProfilePointer = getDotted(parsed, org_profile_cjs_1.ORG_PROFILE_CONFIG_KEY);
+        if (!isUsableString(orgProfilePointer) && orgProfilePackageResolvable(cwd, opts)) {
+            violations.push({
+                code: INVARIANT_CODE.ORG_PROFILE_UNASKED,
+                message: 'An org-profile-shaped package is installed but org.profile is unset — the pointer question (Question 6) appears to have been skipped rather than answered.',
+            });
+        }
+    }
+    catch {
+        // fail open
+    }
+    // INIT_COMPOSITION_NOT_RUN — a binding was composable from the org
+    // profile and project answers, but .platform-bindings.json was never
+    // written and no explicit decline was recorded — Step 2.5 appears to
+    // have been skipped rather than run-and-declined.
+    try {
+        const bindingsPath = node_path_1.default.join(cwd, '.platform-bindings.json');
+        const bindingsExist = node_fs_1.default.existsSync(bindingsPath);
+        const declined = getDotted(parsed, exports.INIT_COMPOSE_DECLINED_KEY) === true;
+        if (!bindingsExist && !declined) {
+            const dryRun = (0, compose_bindings_cjs_1.composeBindings)(cwd, { offline: true, _globalRoot: opts._globalRoot });
+            if (dryRun.composable === true) {
+                violations.push({
+                    code: INVARIANT_CODE.COMPOSITION_NOT_RUN,
+                    message: 'A binding is composable from the org profile and project answers, but .platform-bindings.json was never written and no decline was recorded — Step 2.5 appears to have been skipped.',
+                });
+            }
+        }
+    }
+    catch {
+        // fail open
+    }
+    return { ok: violations.length === 0, violations };
+}
+// ─── Session state machine (34-08 gap closure) ─────────────────────────────
+//
+// Why this exists at all: `buildInitQuestions`/`verifyInitInvariants` make
+// the CONTENT correct when called and the OMISSION provable afterwards —
+// they do not make skipping impossible, because prose can still hand an
+// agent the full 8-question list and the agent can still compress it (this
+// module's own header; `34-VERIFICATION.md`'s third walk). This session
+// machine removes the list itself: `initSessionNext` returns exactly ONE
+// step, `initSessionAnswer` records exactly ONE answer and rejects
+// anything out of order, and the CLI performs every side effect (identity
+// write, `vault.provider`, composition) at the state that needs it — never
+// leaving it to a workflow's own prose to remember. Neither
+// `buildInitQuestions` nor `verifyInitInvariants` nor `composeBindings` is
+// reimplemented here: this machine only sequences calls into them.
+function sessionFilePath(cwd) {
+    return node_path_1.default.join(cwd, '.planning', INIT_SESSION_FILE_NAME);
+}
+function newSession() {
+    return { version: 1, answers: {}, identityWritten: false, composeDecision: null, doneAt: null };
+}
+/** Validate the ENTIRE persisted shape before trusting it — a session file
+ * that merely parses as JSON but carries the wrong shape (hand-edited,
+ * truncated mid-write, a leftover from an incompatible future version) must
+ * fail closed exactly like a parse error (T-34-63). */
+function isValidSessionShape(v) {
+    if (!isObject(v))
+        return false;
+    const version = v.version;
+    const answers = v.answers;
+    const identityWritten = v.identityWritten;
+    const composeDecision = v.composeDecision;
+    const doneAt = v.doneAt;
+    if (version !== 1)
+        return false;
+    if (!isObject(answers))
+        return false;
+    for (const val of Object.values(answers)) {
+        if (typeof val !== 'string')
+            return false;
+    }
+    if (typeof identityWritten !== 'boolean')
+        return false;
+    if (composeDecision !== null &&
+        composeDecision !== 'approved' &&
+        composeDecision !== 'declined' &&
+        composeDecision !== 'skipped' &&
+        composeDecision !== 'unchanged') {
+        return false;
+    }
+    if (doneAt !== null && typeof doneAt !== 'string')
+        return false;
+    return true;
+}
+/** Absent file → a brand-new session (the normal first call). Present and
+ * valid → that session. Present but invalid in ANY way → `{ malformed:
+ * true }`, and every caller below refuses to proceed rather than silently
+ * re-initializing (T-34-63) — `initSessionReset` is the only documented
+ * recovery. Never throws. */
+function loadSession(cwd) {
+    const p = sessionFilePath(cwd);
+    try {
+        if (!node_fs_1.default.existsSync(p)) {
+            return { malformed: false, session: newSession() };
+        }
+        const raw = node_fs_1.default.readFileSync(p, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!isValidSessionShape(parsed)) {
+            return { malformed: true };
+        }
+        return { malformed: false, session: parsed };
+    }
+    catch {
+        return { malformed: true };
+    }
+}
+/** CR-01: format an unexpected write failure (e.g. EACCES) as a bounded,
+ * human-readable message — never a raw stack trace reaching the operator. */
+function writeFailedMessage(err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return (`A filesystem write inside the init session failed (${detail}). ` +
+        'This project\'s .planning directory (or .platform-bindings.json) may not be writable ' +
+        '(permissions, a read-only mount, a full disk). Nothing further was recorded for this step — ' +
+        'fix the underlying filesystem issue and try the same step again.');
+}
+function persistSession(cwd, session) {
+    const dir = node_path_1.default.join(cwd, '.planning');
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(dir);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(sessionFilePath(cwd), JSON.stringify(session, null, 2) + '\n');
+}
+/** Read `.planning/config.json` for a MERGE write — distinct from
+ * `readConfigFile` above (which reports `exists`/malformed for
+ * `verifyInitInvariants`'s read-only purposes): this helper only ever
+ * needs "the object to merge into", degrading to `{}` on any absence or
+ * fault so a merge write never crashes on a pre-existing malformed file —
+ * it simply starts the merge from empty and the write below then produces
+ * a well-formed file going forward. */
+function readConfigForMerge(cwd) {
+    try {
+        const raw = node_fs_1.default.readFileSync(node_path_1.default.join(cwd, '.planning', 'config.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Shallow-recursive merge: object values merge key-by-key; any other
+ * value (string, number, boolean, array) replaces the target outright.
+ * Bounded by the patches this module ever constructs itself (`project.*`,
+ * `vault.provider`, `org.profile`, `init.compose_declined` — never a
+ * caller-supplied arbitrary depth), so no depth cap is needed here the way
+ * `walkLeaves` in `compose-bindings.cts` needs one for untrusted file
+ * content. */
+function deepMergeConfigPatch(target, patch) {
+    for (const k of Object.keys(patch)) {
+        const pv = patch[k];
+        const existing = target[k];
+        if (isObject(pv) && isObject(existing)) {
+            target[k] = deepMergeConfigPatch({ ...existing }, pv);
+        }
+        else {
+            target[k] = pv;
+        }
+    }
+    return target;
+}
+/** The ONLY place this module writes `.planning/config.json` — every side
+ * effect the session performs (identity write, `vault.provider`,
+ * `org.profile`, `init.compose_declined`) routes through here, merged
+ * against whatever is already on disk so a session step never clobbers an
+ * unrelated key a human or another tool wrote. Direct `fs`/`JSON` I/O,
+ * bypassing `config-schema.cts`'s registered-key validation — the same
+ * convention `compose-bindings.cts`'s `cfgGet` and this module's own
+ * `readConfigFile` already use for `project.*`/`org.profile` reads; see
+ * `.planning/todos/pending/project-config-key-unknown.md` for why `project`
+ * is not (yet) a registered top-level key, out of scope for this plan. */
+function writeConfigMerge(cwd, patch) {
+    const dir = node_path_1.default.join(cwd, '.planning');
+    (0, shell_command_projection_cjs_1.platformEnsureDir)(dir);
+    const merged = deepMergeConfigPatch(readConfigForMerge(cwd), patch);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(node_path_1.default.join(dir, 'config.json'), JSON.stringify(merged, null, 2) + '\n');
+}
+/** The batch write Task 1 §2 describes: once all 8 answers are recorded,
+ * write the `project` identity block and — only when the `provider` answer
+ * is exactly `gitlab` or `azure` — `vault.provider`. `org_profile` is
+ * excluded from this map: it is written immediately when THAT answer is
+ * recorded (see `initSessionAnswer`), not deferred here, precisely so the
+ * `provider` question re-resolves its `preselected` against it. */
+function writeIdentityAndProvider(cwd, answers) {
+    const projectPatch = {};
+    for (const [questionId, configKey] of Object.entries(PROJECT_BLOCK_QUESTION_MAP)) {
+        const raw = answers[questionId];
+        if (isUsableString(raw)) {
+            projectPatch[configKey] = raw.trim();
+        }
+    }
+    const patch = { project: projectPatch };
+    const providerAnswer = answers.provider;
+    if (providerAnswer === 'gitlab' || providerAnswer === 'azure') {
+        patch.vault = { provider: providerAnswer };
+    }
+    writeConfigMerge(cwd, patch);
+}
+/** Case/whitespace-tolerant yes/no parse for the `compose_confirm` answer.
+ * `null` for anything else — never defaulted to a decline, so a typo'd
+ * answer is rejected rather than silently treated as "no". */
+function normalizeYesNo(value) {
+    if (typeof value !== 'string')
+        return null;
+    const v = value.trim().toLowerCase();
+    if (YES_VALUES.includes(v))
+        return true;
+    if (NO_VALUES.includes(v))
+        return false;
+    return null;
+}
+/**
+ * The single decision function every public session entry point drives.
+ * Recomputes `buildInitQuestions(cwd)` FRESH on every call — never cached
+ * across calls — which is what makes the `provider` question's
+ * `preselected` reflect an `org_profile` answer given moments earlier in
+ * the SAME session (the walk-3 regression this plan's design hazards
+ * name): by the time this function is asked for the `provider` question,
+ * `org.profile` has already been written to disk by `initSessionAnswer`,
+ * so `buildInitQuestions`'s own `resolveProvider` call sees it.
+ *
+ * Performs three idempotent side effects, each guarded by its own session
+ * flag so re-calling this (as every public entry point does, to validate
+ * the current step) never repeats a write: the identity+provider batch
+ * write once all 8 questions are answered; marking `composeDecision:
+ * 'skipped'` when nothing is composable at all (the real inert path,
+ * INIT-02) or `composeDecision: 'unchanged'` when a binding IS composable
+ * but the existing file already matches it (a healthy, up-to-date state —
+ * NOT the inert path, and reported with its own distinct message; no
+ * `compose_confirm` prompt either way, nothing written); and recording
+ * `doneAt` once `verifyInitInvariants` first reports `ok: true`.
+ */
+function computeCurrentStep(cwd, session, opts) {
+    // CR-01: every sibling module in this seam (composeBindings,
+    // resolveOrgProfileDocument, resolveOrgProfile, verifyInitInvariants)
+    // wraps its entire body in a top-level try/catch so a filesystem fault
+    // degrades to a bounded result rather than crashing (D-09). This
+    // function's writes (writeIdentityAndProvider/persistSession, below) did
+    // not — an unwritable .planning directory threw an uncaught EACCES
+    // straight out of initSessionNext/initSessionAnswer. Fixed by matching
+    // the convention: any failure anywhere in this body degrades to a
+    // `write_failed` verdict instead of propagating.
+    try {
+        const questions = buildInitQuestions(cwd);
+        for (const q of questions) {
+            if (!Object.prototype.hasOwnProperty.call(session.answers, q.id)) {
+                return { kind: 'question', question: q };
+            }
+        }
+        if (!session.identityWritten) {
+            writeIdentityAndProvider(cwd, session.answers);
+            session.identityWritten = true;
+            persistSession(cwd, session);
+        }
+        if (session.composeDecision === null) {
+            const dryRun = (0, compose_bindings_cjs_1.composeBindings)(cwd, { offline: opts.offline === true, _globalRoot: opts._globalRoot });
+            // WR-01: only offer compose_confirm when approving it would actually
+            // change something. `action: 'unchanged'` means the existing file
+            // already carries every key the composer would produce (D-08's
+            // absent-only merge) — asking the operator to approve a write that
+            // writes nothing is exactly the shape of prompt that produced the
+            // false-success report this finding names. Fall through to the
+            // messaging below instead of asking — but see the coordinator
+            // follow-up: 'unchanged' and 'not composable at all' are DIFFERENT
+            // end states and must record (and later report) distinct decisions,
+            // never sharing the inert-path (INIT-02) message below.
+            if (dryRun.composable === true && dryRun.action !== 'unchanged') {
+                return {
+                    kind: 'compose_confirm',
+                    info: {
+                        provenance: dryRun.provenance,
+                        drift: dryRun.drift,
+                        action: dryRun.action,
+                        composed: dryRun.composed,
+                        warnings: dryRun.warnings,
+                    },
+                };
+            }
+            session.composeDecision = dryRun.composable === true && dryRun.action === 'unchanged' ? 'unchanged' : 'skipped';
+            persistSession(cwd, session);
+        }
+        // Three genuinely different end states can reach `done`/`verify` with
+        // nothing written, and each needs its own message — conflating them
+        // (as an earlier pass of this fix did) tells an operator with a
+        // healthy, up-to-date binding that their org profile produced nothing
+        // composable, which is exactly the "tool reports a state that isn't
+        // the real one" failure shape this phase exists to eliminate.
+        const skippedComposeInfo = session.composeDecision === 'skipped'
+            ? 'Nothing was composable from the org profile and project answers — no compose_confirm step was shown and nothing was written (the inert path, INIT-02).'
+            : session.composeDecision === 'unchanged'
+                ? 'The existing .platform-bindings.json is already up to date with what the org profile and project answers would produce — no compose_confirm step was needed and nothing was written.'
+                : undefined;
+        const verifyResult = verifyInitInvariants(cwd, { _globalRoot: opts._globalRoot });
+        if (verifyResult.ok) {
+            if (!session.doneAt) {
+                session.doneAt = new Date().toISOString();
+                persistSession(cwd, session);
+            }
+            return { kind: 'done', skippedComposeInfo };
+        }
+        return { kind: 'verify', violations: verifyResult.violations, skippedComposeInfo };
+    }
+    catch (err) {
+        return { kind: 'write_failed', message: writeFailedMessage(err) };
+    }
+}
+function currentStepToState(step) {
+    switch (step.kind) {
+        case 'question': {
+            const q = step.question;
+            const state = { done: false, step: q.id, prompt: q.prompt, optionalAnswer: q.optionalAnswer };
+            if (q.options !== undefined)
+                state.options = q.options;
+            if (q.preselected !== undefined)
+                state.preselected = q.preselected;
+            if (q.preselectedLabel !== undefined)
+                state.preselectedLabel = q.preselectedLabel;
+            return state;
+        }
+        case 'compose_confirm':
+            return {
+                done: false,
+                step: 'compose_confirm',
+                prompt: 'A binding can be composed from the org profile and project answers. Compose and write .platform-bindings.json now? (yes/no)',
+                optionalAnswer: false,
+                info: step.info,
+            };
+        case 'verify':
+            return {
+                done: false,
+                step: 'verify',
+                prompt: null,
+                violations: step.violations,
+                ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo } : {}),
+            };
+        case 'done':
+            return {
+                done: true,
+                step: 'done',
+                prompt: null,
+                ...(step.skippedComposeInfo !== undefined ? { info: step.skippedComposeInfo } : {}),
+            };
+        case 'write_failed':
+            return {
+                done: false,
+                step: null,
+                prompt: null,
+                error: exports.INIT_SESSION_WRITE_FAILED,
+                message: step.message,
+            };
+    }
+}
+/**
+ * Return the ONE next step of the `/pp-init` session at `cwd` — a question,
+ * `compose_confirm`, `verify`, or `done`. Never a list. Fails closed (T-34-
+ * 63) with `error: INIT_SESSION_MALFORMED` when the session file exists but
+ * does not parse as valid session state; `--session-reset` is the
+ * documented recovery, never a silent re-initialize.
+ */
+function initSessionNext(cwd, opts = {}) {
+    const loaded = loadSession(cwd);
+    if (loaded.malformed) {
+        return {
+            done: false,
+            step: null,
+            prompt: null,
+            error: exports.INIT_SESSION_MALFORMED,
+            message: 'The init session file at .planning/.init-session.json exists but is malformed or unreadable. ' +
+                'Run "pp_run query init-contract --session-reset" to start over — it is never resumed silently into an unknown state.',
+        };
+    }
+    return currentStepToState(computeCurrentStep(cwd, loaded.session, opts));
+}
+/**
+ * Record ONE answer for the CURRENT step only. Rejects — with `ok: false`
+ * and a named `reason`, never a throw — an answer for any step other than
+ * the one `initSessionNext` would currently serve (T-34-60: an agent trying
+ * to batch or skip ahead fails loudly), a blank answer to a
+ * non-`optionalAnswer` question, an unparseable `compose_confirm` value, or
+ * any answer once the session is already `done`.
+ *
+ * The `org_profile` answer is written to `.planning/config.json` (`org.profile`)
+ * IMMEDIATELY when non-blank — the one exception to the "batch write after
+ * the last answer" rule in `computeCurrentStep`'s own doc comment — because
+ * the very next question (`provider`) must see it to re-resolve its
+ * `preselected` (the walk-3 regression Task 1's acceptance names).
+ */
+function initSessionAnswer(cwd, stepId, value, opts = {}) {
+    const loaded = loadSession(cwd);
+    if (loaded.malformed) {
+        return {
+            ok: false,
+            reason: 'session_malformed',
+            message: 'The init session file at .planning/.init-session.json exists but is malformed or unreadable. ' +
+                'Run "pp_run query init-contract --session-reset" to start over.',
+        };
+    }
+    const session = loaded.session;
+    // CR-01: wrap the entire remaining body — every write this function
+    // performs directly (the `org_profile` immediate write, the batch
+    // `persistSession` calls, the `compose_confirm` decline/approve writes)
+    // — in a top-level try/catch, matching the D-09 convention every sibling
+    // module in this seam already follows. `computeCurrentStep` degrades to
+    // a `write_failed` step on its own internal failures (handled explicitly
+    // below); this catch additionally covers the write sites that live in
+    // THIS function, after `computeCurrentStep` returns.
+    try {
+        const step = computeCurrentStep(cwd, session, opts);
+        if (step.kind === 'write_failed') {
+            return { ok: false, reason: 'write_failed', message: step.message };
+        }
+        if (step.kind === 'done') {
+            return {
+                ok: false,
+                reason: 'session_already_done',
+                message: 'The init session is already complete; there is nothing left to answer. Run --session-reset to start over.',
+            };
+        }
+        if (step.kind === 'question') {
+            if (step.question.id !== stepId) {
+                return {
+                    ok: false,
+                    reason: 'step_mismatch',
+                    message: `Expected an answer for step "${step.question.id}" but received one for "${stepId}". Answers must be submitted in the order the session serves them — call --session-next to see the actual current step.`,
+                };
+            }
+            if (!step.question.optionalAnswer && (typeof value !== 'string' || value.trim() === '')) {
+                return { ok: false, reason: 'answer_required', message: `Question "${stepId}" requires a non-blank answer.` };
+            }
+            session.answers[stepId] = typeof value === 'string' ? value : '';
+            if (stepId === 'org_profile') {
+                const trimmed = session.answers[stepId].trim();
+                if (trimmed !== '') {
+                    writeConfigMerge(cwd, { org: { profile: trimmed } });
+                }
+            }
+            persistSession(cwd, session);
+            return { ok: true };
+        }
+        if (step.kind === 'compose_confirm') {
+            if (stepId !== 'compose_confirm') {
+                return {
+                    ok: false,
+                    reason: 'step_mismatch',
+                    message: `Expected an answer for step "compose_confirm" but received one for "${stepId}". Call --session-next to see the actual current step.`,
+                };
+            }
+            const normalized = normalizeYesNo(value);
+            if (normalized === null) {
+                return {
+                    ok: false,
+                    reason: 'invalid_answer',
+                    message: 'compose_confirm requires "yes" or "no" (also accepts approve/decline, y/n, true/false).',
+                };
+            }
+            if (normalized === true) {
+                // WR-02: inspect the write-mode result before recording the
+                // decision. The dry run inside computeCurrentStep already reported
+                // composable:true/action!=='unchanged' moments earlier, but the
+                // world can change between that dry run and this write (the file
+                // became malformed on disk in between, a transient fault now caught
+                // internally by composeBindings's own outer catch, etc.) — in that
+                // case `wrote` comes back false even though the operator approved.
+                // Recording 'approved' unconditionally here would make the session
+                // proceed toward done/verify as though the write had succeeded,
+                // and the eventual INIT_COMPOSITION_NOT_RUN violation would then
+                // misdescribe what happened ("Step 2.5 appears to have been
+                // skipped") when in fact the user approved and the write failed.
+                const writeResult = (0, compose_bindings_cjs_1.composeBindings)(cwd, { write: true, offline: opts.offline === true, _globalRoot: opts._globalRoot });
+                if (writeResult.composable !== true || writeResult.wrote !== true) {
+                    // Do NOT record composeDecision here — leave it null so the next
+                    // --session-next call re-evaluates from a fresh dry run (and, if
+                    // still composable, re-offers compose_confirm) rather than
+                    // silently treating this as skipped or declined.
+                    return {
+                        ok: false,
+                        reason: 'compose_write_failed',
+                        message: 'compose_confirm was approved, but the write to .platform-bindings.json did not succeed — ' +
+                            'this was NOT recorded as skipped or declined.' +
+                            (writeResult.warnings.length > 0 ? ` Warnings: ${writeResult.warnings.join('; ')}.` : '') +
+                            ' Call --session-next to see the current state and try again.',
+                    };
+                }
+                session.composeDecision = 'approved';
+            }
+            else {
+                writeConfigMerge(cwd, { init: { compose_declined: true } });
+                session.composeDecision = 'declined';
+            }
+            persistSession(cwd, session);
+            return { ok: true };
+        }
+        // step.kind === 'verify': a system-computed check, never answerable.
+        return {
+            ok: false,
+            reason: 'step_not_answerable',
+            message: 'Step "verify" does not accept an answer — it is a system-computed check. Call --session-next to see its result.',
+        };
+    }
+    catch (err) {
+        return { ok: false, reason: 'write_failed', message: writeFailedMessage(err) };
+    }
+}
+/** Delete the session file, the documented recovery from a malformed
+ * session (T-34-63). Never throws; a missing file is not an error. */
+function initSessionReset(cwd) {
+    try {
+        const p = sessionFilePath(cwd);
+        if (node_fs_1.default.existsSync(p))
+            node_fs_1.default.unlinkSync(p);
+    }
+    catch {
+        // best-effort — nothing further this function can do
+    }
+    return { ok: true };
+}
+// ─── cmdInitContract ────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools query init-contract`.
+ *
+ * `--verify` runs `verifyInitInvariants` and always prints the full result
+ * as data (so `init.md` can read and show every violation verbatim), then
+ * sets `process.exitCode = 1` when the result is not `ok` — a data
+ * verdict, never an `error()` usage failure. This is the load-bearing
+ * property Task 2's acceptance requires: a caller cannot mistake a failed
+ * check for a pass, but the JSON body still reaches stdout either way.
+ *
+ * `--questions` (also the no-flag default, matching this seam's
+ * safe-default convention — mirrors `compose-bindings`'s dry-run default)
+ * is read-only and always exits 0.
+ *
+ * `--session-reset` / `--session-answer` / `--session-next` (34-08 gap
+ * closure) drive the session state machine above. Precedence — reset,
+ * then answer, then next, then verify, then the questions default — mirrors
+ * the order a relay loop actually calls them in (an agent never sends more
+ * than one of these per invocation; the order only matters for a caller
+ * that somehow set two, which should never happen from `pp-tools.cjs`'s own
+ * parsing). `--session-answer` and `--session-next` both set
+ * `process.exitCode = 1` on a data verdict that means "not ready to
+ * proceed" (`ok: false` / `error` present) — same never-a-usage-failure
+ * convention as `--verify`.
+ */
+function cmdInitContract(cwd, options, raw) {
+    if (options.sessionReset === true) {
+        const result = initSessionReset(cwd);
+        output(result, raw);
+        return;
+    }
+    if (options.sessionAnswer !== undefined) {
+        const result = initSessionAnswer(cwd, options.sessionAnswer.stepId, options.sessionAnswer.value, {
+            offline: options.offline === true,
+        });
+        output(result, raw);
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (options.sessionNext === true) {
+        const state = initSessionNext(cwd, { offline: options.offline === true });
+        output(state, raw);
+        if (state.error !== undefined) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (options.verify === true) {
+        const result = verifyInitInvariants(cwd);
+        output(result, raw);
+        if (!result.ok) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    output({ questions: buildInitQuestions(cwd) }, raw);
+}