@pareto4/pp-core 1.9.0 → 1.10.0

package/pp-core/bin/lib/vault-write-back.cjs

@@ -0,0 +1,756 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * src/vault-write-back.cts — Vault write-back promote arm, deterministic
+ * guard core (milestone v1.10.0 Vault-Guided Code Generation, Phase 29-01).
+ *
+ * Responsibility (Phase 29-01 only — the guard-chain half of the arm):
+ *   A curated in-repo secret-content scanner (`SECRET_SHAPES` /
+ *   `scanForSecrets`) plus the preflight guard chain (`promotePreflight`)
+ *   that runs before any git subprocess exists in this module: the
+ *   activation gate, the Phase 24 format validator reused verbatim, the
+ *   secret scan, and the frozen `assertVaultWriteTarget` write-target
+ *   check. Every stage emits the uniform refusal contract (D-16) via the
+ *   `refusal` helper.
+ *
+ * Deliberately a NEW module (not folded into `src/vault.cts` or
+ * `src/vault-command-router.cts`) — the name is load-bearing: it forms a
+ * fresh `vault-write-back` test-file cluster for
+ * `scripts/lint-test-file-count.cjs` instead of being swept into the
+ * `vault` cluster, which is already at its allowlisted cap of five files.
+ *
+ * Responsibility (Phase 29-02 additions — the read-only half of the write
+ * path): `previewPromotion` clones the client vault into a disposable temp
+ * directory, captures the current content of the destination as a pinned
+ * baseline, stages the promoted content, and asks git itself for the diff
+ * (or the full content on a create) — so the thing an operator confirms is
+ * generated from exactly the working-tree state a later confirmed run
+ * would push. `buildExpectToken` pins both sides (local content + remote
+ * baseline) into one opaque token 29-03's concurrent-edit guard checks
+ * against. This is the ONLY function in this module that calls `execGit`,
+ * and it never creates a commit or moves a remote ref.
+ *
+ * Responsibility (Phase 29-03 additions — the write half of the write
+ * path): `confirmPromotion` re-runs the full 29-01 preflight chain, refuses
+ * before any clone when the opaque `expect` token is missing or its pinned
+ * LOCAL hash no longer matches the freshly-read file, clones fresh (never
+ * reusing the preview's clone or the read cache), fetches the resolved ref
+ * and fast-forward-only pulls to absorb any unrelated remote movement, then
+ * re-derives the remote baseline from the now-current working tree and
+ * compares it against the token's pinned REMOTE hash (file-scoped —
+ * commit/tree shas are never compared, so an unrelated promotion never
+ * blocks this one). On a match it stages exactly the destination path,
+ * commits once, and pushes once with no force flag on any code path — a
+ * genuine non-fast-forward rejection from git is the intended structural
+ * backstop and is never retried. On success it refreshes the local read
+ * cache via `./vault.cjs`'s `vaultFetch` verbatim (D-11), treating a
+ * refresh failure as non-fatal (the push already succeeded). `promotePractice`
+ * is the single entry point 29-04's router calls, dispatching to
+ * `previewPromotion` or `confirmPromotion` on the `confirmed` flag.
+ *
+ * Responsibility (Phase 29-04 addition — the human-readable report half):
+ * `renderPromoteReport` renders any verdict `promotePractice` can produce as
+ * plain English (COMM-01), selected by the CLI router when `--raw` is
+ * absent.
+ *
+ * Out of scope here (later plans): the workflow/command docs (29-05).
+ *
+ * Reuses (no new runtime dependency):
+ *   - `./vault-practices.cjs` (`parsePracticeFile`) — the ONLY format
+ *     validator in the write path (D-03). Reused verbatim, never
+ *     re-derived.
+ *   - `./vault.cjs` (`cfgGet`, `readBindings`, `assertVaultWriteTarget`) —
+ *     `assertVaultWriteTarget` is called verbatim and unmodified (D-05).
+ *   - `./io.cjs` (`ERROR_REASON`) — the typed refusal reason codes added
+ *     alongside this module.
+ *
+ * Test seams: pass `_vault` / `_practices` to inject mock modules (the
+ * repo's established `_`-prefix convention — see
+ * `src/vault-command-router.cts`). Production callers omit both; the real
+ * `./vault.cjs` / `./vault-practices.cjs` are lazy-required inside
+ * `promotePreflight` so they only load when a promotion actually runs.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the git-ignored `pp-core/bin/lib/vault-write-back.cjs`; do NOT
+ * hand-edit the compiled output.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { ERROR_REASON } = io;
+// ─── Guard identity (PROMOTE_GUARD) ─────────────────────────────────────────────
+// 29-02/29-03 reuse CONCURRENT_EDIT and TRANSPORT — declare all seven now so
+// the enum is not edited twice.
+const PROMOTE_GUARD = Object.freeze({
+    ACTIVATION: 'activation',
+    INPUT: 'input',
+    VALIDATION: 'validation',
+    SECRET_SCAN: 'secret_scan',
+    WRITE_TARGET: 'write_target',
+    CONCURRENT_EDIT: 'concurrent_edit',
+    TRANSPORT: 'transport',
+});
+// ─── Secret-content scanner (WRB-03 / D-13 / D-14) ──────────────────────────────
+//
+// Transliterated from scripts/secret-scan.sh's SECRET_PATTERNS (18 labeled
+// POSIX ERE patterns) into JavaScript RegExp, preserving every human label
+// verbatim, plus one ADDED shape the CI scanner is missing: a GitLab access
+// token keyed on the `glpat-` prefix (confirmed absent from
+// scripts/secret-scan.sh but already referenced in ad-hoc greps at
+// pp-core/workflows/docs-update.md and pp-core/workflows/map-codebase.md).
+//
+// Order is declaration order and is load-bearing: the Anthropic shape is
+// placed before the OpenAI shape so a key of the form `sk-ant-<alnum>` is
+// never reported under the OpenAI label (the OpenAI pattern's `[A-Za-z0-9]`
+// class alone would also match the alnum-only tail of an Anthropic key).
+//
+// Deliberately NOT ported: the `.secretscanignore` mechanism, an exclusion
+// parameter, a placeholder carve-out, or an entropy heuristic — D-14's
+// no-override rule is deliberate, and the generic assignment shapes' false-
+// positive exposure is an accepted residual (T-29-02b).
+const SECRET_SHAPES = Object.freeze([
+    { label: 'AWS Access Key', re: /AKIA[0-9A-Z]{16}/ },
+    { label: 'AWS Secret Key', re: /aws_secret_access_key\s*=\s*[A-Za-z0-9/+=]{40}/ },
+    { label: 'Anthropic API Key', re: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { label: 'OpenAI API Key', re: /sk-[A-Za-z0-9]{20,}/ },
+    { label: 'GitHub PAT', re: /ghp_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub OAuth', re: /gho_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub App Token', re: /ghs_[A-Za-z0-9]{36}/ },
+    { label: 'GitHub Fine-grained PAT', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { label: 'GitLab access token', re: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { label: 'Stripe Secret Key', re: /sk_live_[A-Za-z0-9]{24,}/ },
+    { label: 'Stripe Publishable Key', re: /pk_live_[A-Za-z0-9]{24,}/ },
+    { label: 'Private Key Header', re: /-----BEGIN\s+(RSA|EC|DSA|OPENSSH)?\s*PRIVATE\s+KEY-----/ },
+    { label: 'Slack Bot Token', re: /xoxb-[0-9]{10,}-[A-Za-z0-9]{20,}/ },
+    {
+        label: 'Slack Webhook',
+        re: /hooks\.slack\.com\/services\/T[A-Z0-9]{8,}\/B[A-Z0-9]{8,}\/[A-Za-z0-9]{24}/,
+    },
+    { label: 'Google API Key', re: /AIza[A-Za-z0-9_-]{35}/ },
+    { label: 'NPM Token', re: /npm_[A-Za-z0-9]{36}/ },
+    {
+        label: 'Env Variable Leak',
+        re: /(DATABASE_URL|DB_PASSWORD|REDIS_URL|MONGO_URI|JWT_SECRET|SESSION_SECRET|ENCRYPTION_KEY)\s*=\s*[^\s]{8,}/,
+    },
+    { label: 'Generic API Key Assignment', re: /api[_-]?key\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Secret Assignment', re: /secret\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Token Assignment', re: /token\s*[:=]\s*['"][A-Za-z0-9_-]{20,}['"]/i },
+    { label: 'Generic Password Assignment', re: /password\s*[:=]\s*['"][^'"]{8,}['"]/i },
+]);
+/**
+ * Scan `content` line by line, walking SECRET_SHAPES in declaration order
+ * for each line, and return the FIRST match as `{ label, line }` (1-based).
+ * Returns null on clean content. Never places the matched substring, a
+ * slice of it, or a match index into the return value — name and line only
+ * (T-29-01).
+ */
+function scanForSecrets(content) {
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const shape of SECRET_SHAPES) {
+            if (shape.re.test(line)) {
+                return { label: shape.label, line: i + 1 };
+            }
+        }
+    }
+    return null;
+}
+// ─── Refusal contract (D-16) ─────────────────────────────────────────────────────
+/**
+ * Build a uniform refusal verdict. `message` is collapsed to a single line
+ * (any CR/LF run becomes a space) so a client-authored fragment carried
+ * into `extra` or the cause clause can never inject a fake second line into
+ * operator output.
+ */
+function refusal(guard, reason, message, extra = {}) {
+    return {
+        status: 'refused',
+        guard,
+        reason,
+        message: message.replace(/[\r\n]+/g, ' '),
+        ...extra,
+    };
+}
+/** Bound an untrusted value before it is echoed into a refusal message. */
+function boundedToken(v, max = 80) {
+    let s;
+    try {
+        s = typeof v === 'string' ? v : JSON.stringify(v);
+    }
+    catch {
+        s = String(v);
+    }
+    s = s.replace(/[\r\n]+/g, ' ');
+    return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+// ─── Preflight guard chain ───────────────────────────────────────────────────────
+/**
+ * Run the promote preflight guard chain: activation, input, format
+ * validation (D-03), secret scan (D-13/D-14), target resolution, and the
+ * write-target guard (D-05) — strictly in that order, refusing at the
+ * first failing stage and never continuing past it. Makes no network
+ * access and spawns no subprocess.
+ */
+function promotePreflight({ cwd, filePath, _vault, _practices }) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = _vault ?? require('./vault.cjs');
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const practices = _practices ?? require('./vault-practices.cjs');
+    // 1. Activation — both vault.enabled and vault.practices_enabled must be
+    // strictly true. Runs before any filesystem access; rides the two
+    // existing default-false config keys (no new config key, no capability
+    // surface widening).
+    const enabled = vault.cfgGet(cwd, 'vault.enabled', false);
+    const practicesEnabled = vault.cfgGet(cwd, 'vault.practices_enabled', false);
+    if (enabled !== true || practicesEnabled !== true) {
+        return refusal(PROMOTE_GUARD.ACTIVATION, ERROR_REASON.VAULT_PROMOTE_DISABLED, 'This practice was not promoted: vault write-back is switched off for this project. ' +
+            'Set both vault.enabled and vault.practices_enabled to true in .planning/config.json and run the promotion again.');
+    }
+    // 2. Input — a path to an already-authored practice file (D-02); this
+    // module never composes, rewrites, reformats, or extracts a practice.
+    if (typeof filePath !== 'string' ||
+        filePath.length === 0 ||
+        !filePath.endsWith('.md') ||
+        !node_fs_1.default.existsSync(filePath) ||
+        !node_fs_1.default.statSync(filePath).isFile()) {
+        return refusal(PROMOTE_GUARD.INPUT, ERROR_REASON.SDK_MISSING_ARG, `This practice was not promoted: ${boundedToken(filePath)} is not an existing practice file. ` +
+            'Point at an existing .md practice file and run the promotion again.');
+    }
+    // Read the FULL file content — not the bounded prefix discovery uses —
+    // because both the validation oracle and the secret scan must see the
+    // whole file.
+    const raw = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    // 3. Validation — the Phase 24 parser is the only format validator in
+    // this write path (D-03). No second validator, no new format rule.
+    const parsed = practices.parsePracticeFile(node_path_1.default.basename(filePath), raw);
+    if (!parsed.ok) {
+        const cause = parsed.warning.replace(/^.*?\s+skipped:\s*/, '');
+        return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_PRACTICE, `This practice was not promoted: ${cause} Fix the practice file and run the promotion again.`);
+    }
+    // 4. Secret scan — a hit refuses hard, no override (D-14). The matched
+    // text is never carried, quoted, echoed, logged, or truncated into the
+    // refusal — a truncated secret is still a partial disclosure.
+    const hit = scanForSecrets(raw);
+    if (hit) {
+        return refusal(PROMOTE_GUARD.SECRET_SCAN, ERROR_REASON.VAULT_PROMOTE_SECRET_DETECTED, `This practice was not pushed: line ${hit.line} looks like ${hit.label}. Remove it and run the promotion again.`, { label: hit.label, line: hit.line });
+    }
+    // 5. Target resolution — client.vaultRepo / client.vaultRef / host.
+    // Deliberately does NOT call resolveBaseBranch (src/git-base-branch.cts)
+    // — that resolver answers a question about this project's OWN
+    // repository, a different repository from the client vault.
+    const bindings = vault.readBindings(cwd);
+    const client = bindings && typeof bindings.client === 'object' && bindings.client !== null
+        ? bindings.client
+        : null;
+    const targetRepo = client && typeof client.vaultRepo === 'string' ? client.vaultRepo : null;
+    if (!targetRepo) {
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, 'This practice was not promoted: no client vault repository is configured. ' +
+            'Check client.vaultRepo in .platform-bindings.json and run the promotion again.');
+    }
+    // T-29-26: a repo or ref that git would read as an option is refused here,
+    // before any transport exists, rather than being handed to git and surfacing
+    // as a confusing "repository does not exist". Fails closed.
+    const flagShaped = [
+        ['client.vaultRepo', targetRepo],
+        ['client.vaultRef', client && typeof client.vaultRef === 'string' ? client.vaultRef : ''],
+    ].find(([, v]) => typeof v === 'string' && v.trim().startsWith('-'));
+    if (flagShaped) {
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, `This practice was not promoted: ${flagShaped[0]} starts with "-", which git would read as an option rather than a location. ` +
+            'Fix it in .platform-bindings.json and run the promotion again.');
+    }
+    const targetRef = client && typeof client.vaultRef === 'string' && client.vaultRef.trim() ? client.vaultRef.trim() : 'main';
+    const platformHost = vault.cfgGet(cwd, 'platform.host', null);
+    const targetHost = client && typeof client.vaultHost === 'string' && client.vaultHost.trim()
+        ? client.vaultHost.trim()
+        : typeof platformHost === 'string' && platformHost.trim()
+            ? platformHost.trim()
+            : 'gitlab.com';
+    // 6. Write-target guard — assertVaultWriteTarget is called verbatim and
+    // unmodified (D-05); this arm never re-derives, wraps, relaxes, or
+    // reimplements any of its three refusals.
+    try {
+        vault.assertVaultWriteTarget(cwd, targetRepo);
+    }
+    catch (e) {
+        const msg = (e instanceof Error ? e.message : String(e)).replace(/^vault write refused:\s*/, '');
+        return refusal(PROMOTE_GUARD.WRITE_TARGET, ERROR_REASON.VAULT_PROMOTE_TARGET_REFUSED, `This practice was not promoted: ${msg} Check client.vaultRepo in .platform-bindings.json and run the promotion again.`);
+    }
+    // Destination is derived from the stable frontmatter id — never the
+    // local filename, never an operator-supplied value (D-04).
+    const destination = node_path_1.default.posix.join('practices', `${parsed.practice.id}.md`);
+    return {
+        status: 'ok',
+        practice: parsed.practice,
+        raw,
+        repo: targetRepo,
+        ref: targetRef,
+        host: targetHost,
+        destination,
+    };
+}
+// ─── Preview (read-only half of the write path) ─────────────────────────────────
+/**
+ * Build the opaque `expect` token that pins BOTH what the operator confirmed
+ * locally and what the vault held at that moment, without any state file
+ * across two separate process invocations: the hex sha256 of the local raw
+ * content, a period, then either the hex sha256 of the remote baseline or
+ * the literal `absent` when the destination file does not (yet) exist in
+ * the vault. Callers must treat the result as opaque.
+ */
+function buildExpectToken(localRaw, remoteBaseline) {
+    const localHash = node_crypto_1.default.createHash('sha256').update(localRaw).digest('hex');
+    const remoteHash = remoteBaseline === null ? 'absent' : node_crypto_1.default.createHash('sha256').update(remoteBaseline).digest('hex');
+    return `${localHash}.${remoteHash}`;
+}
+/**
+ * Preview a promotion: clone the client vault into a disposable temp
+ * directory, capture the destination's current content as a pinned
+ * baseline, stage the promoted content, and ask git for a diff (update) or
+ * hand back the full content (create). Runs the full 29-01 preflight guard
+ * chain first and returns its refusal unchanged, with no clone attempted,
+ * on any refusal. Never creates a commit, never moves a remote ref, and
+ * never reads or writes the project's own vault read cache (a fresh
+ * mkdtemp working copy is used and always removed, even on a thrown error).
+ */
+/**
+ * True when `value` is already something git can clone directly.
+ *
+ * MUST mirror `isLiteralCloneTarget` in `src/vault.cts`.
+ *
+ * Security (T-29-26): a value that git would read as an OPTION must never take
+ * the verbatim branch. Two rules enforce that:
+ *   - the scheme test is anchored at the START (`^scheme://`). An earlier
+ *     version used `value.includes('://')`, so `--upload-pack=…#x://` — a git
+ *     option carrying `://` anywhere — passed through untouched and reached
+ *     `git clone` as a flag.
+ *   - the scp-style test may not begin with `-`. `[\w.-]+@` accepted a leading
+ *     hyphen, so `--config=core.sshCommand=…@x` matched too.
+ * A leading `-` is additionally refused outright by `flagShapedRepoRefusal`, and
+ * every clone call site passes `--` before the target, so all three would have
+ * to fail together for an option to reach git.
+ */
+function isLiteralCloneTarget(value) {
+    if (value.startsWith('-'))
+        return false;
+    return (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(value) ||
+        /^[\w.][\w.-]*@/.test(value) ||
+        value.startsWith('/') ||
+        value.startsWith('./') ||
+        value.startsWith('../') ||
+        value.startsWith('~') ||
+        /^[A-Za-z]:[\\/]/.test(value));
+}
+/**
+ * Resolve a configured vault repo value into something `git clone` can reach.
+ *
+ * `client.vaultRepo` carries two legitimate shapes, and before this resolver
+ * existed only the first one worked on the write path:
+ *
+ *   - a literal clone target — an absolute path, a `file://`/`https://`/`ssh://`
+ *     URL, or scp-style `git@host:group/project` — used verbatim. Every test
+ *     fixture and every disposable bare-repo harness uses this shape, which is
+ *     why the gap below stayed invisible to the suite.
+ *   - a `group/project` slug, which is the ONLY shape
+ *     `schemas/platform-bindings.schema.json` (`vaultRepo.pattern`) and its own
+ *     documented example `pareto4-clients/acme/acme-vault` actually permit. A
+ *     slug handed straight to `git clone` is read as a RELATIVE PATH and fails
+ *     with "repository does not exist" — so the write-back arm could never
+ *     reach a real client vault, and the refusal blamed the operator's access.
+ *
+ * The URL built for a slug mirrors `cloneTier` in `src/vault.cts` byte for byte
+ * (`https://<host>/<repo>.git`), so the read and write paths address the same
+ * remote instead of disagreeing about what `client.vaultRepo` means.
+ */
+function resolveCloneTarget(repo, host) {
+    const value = repo.trim();
+    if (isLiteralCloneTarget(value))
+        return value;
+    return `https://${host}/${value}.git`;
+}
+function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGit;
+    // 1. Run the full preflight guard chain; refuse unchanged with no clone.
+    const pre = promotePreflight({ cwd, filePath, _vault, _practices });
+    if (pre.status !== 'ok')
+        return pre;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = _vault ?? require('./vault.cjs');
+    const notes = [];
+    // The disposable working copy is a fresh mkdtemp directory — never the
+    // read cache, which is often a shallow/sparse clone from a different tier
+    // and is refreshed independently after a push. Removed on every exit path.
+    let cloneDir = null;
+    try {
+        cloneDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'pp-vault-promote-'));
+        // 2. Clone the resolved client repo at the resolved ref — a full
+        // single-branch clone (no shallow-depth flag: the confirmed path needs
+        // real history to fast-forward against). The target goes through
+        // resolveCloneTarget so a `group/project` slug becomes a real URL on the
+        // resolved host instead of a relative path git cannot find.
+        const cl = gitExec(['clone', '--branch', pre.ref, '--single-branch', '--', resolveCloneTarget(pre.repo, pre.host), cloneDir], { timeout: 120_000 });
+        if (cl.exitCode !== 0) {
+            const cause = boundedToken((cl.stderr || '').split(/\r?\n/)[0] || 'unknown error');
+            return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `This practice was not pushed: git could not reach the vault (${cause}). Check your access to the vault and run the promotion again.`);
+        }
+        // 3. Capture the baseline BEFORE writing — an id already present in the
+        // client vault is an update, not a refusal and not an opt-in flag
+        // (D-06). The baseline captured here is what 29-03's concurrent-edit
+        // check pins against.
+        const destAbs = node_path_1.default.join(cloneDir, pre.destination);
+        const baselineExists = node_fs_1.default.existsSync(destAbs);
+        const baseline = baselineExists ? node_fs_1.default.readFileSync(destAbs, 'utf-8') : null;
+        const mode = baselineExists ? 'update' : 'create';
+        // 4. Write the raw content unchanged — no reformatting, no
+        // re-serialization, no line-ending normalization.
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(destAbs), { recursive: true });
+        node_fs_1.default.writeFileSync(destAbs, pre.raw, 'utf-8');
+        // 5. Ask git for the preview rather than computing one. `core.quotepath=off`
+        // so a non-ASCII destination path is not escaped in operator-read output.
+        let diff;
+        let content;
+        if (mode === 'update') {
+            const diffRes = gitExec(['-c', 'core.quotepath=off', 'diff', '--', pre.destination], { cwd: cloneDir });
+            diff = diffRes.stdout;
+        }
+        else {
+            content = pre.raw;
+        }
+        // 6. Shared-shadow lookup — resolve through the vault module's cfgGet so
+        // the existing defaults apply. Skipped entirely (flag stays false) when
+        // the shared repo is unset or equals the client repo.
+        let sharedShadow = false;
+        let sharedShadowNote = null;
+        const sharedRepoRaw = vault.cfgGet(cwd, 'vault.fallback_repo', '');
+        const sharedRefRaw = vault.cfgGet(cwd, 'vault.fallback_ref', 'main');
+        const sharedRepo = typeof sharedRepoRaw === 'string' ? sharedRepoRaw : '';
+        const sharedRef = typeof sharedRefRaw === 'string' && sharedRefRaw ? sharedRefRaw : 'main';
+        if (sharedRepo && sharedRepo !== pre.repo) {
+            let sharedDir = null;
+            try {
+                sharedDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'pp-vault-shared-'));
+                // Shallow single-branch: only file presence matters, no history needed.
+                // The shared vault is addressed on the PLATFORM host, not the client's
+                // — mirroring the fallback tier in src/vault.cts's cloneTier, so a
+                // client with a custom vaultHost never sends the shared-shadow lookup
+                // to their own host.
+                const sharedPlatformHostRaw = vault.cfgGet(cwd, 'platform.host', null);
+                const sharedHost = typeof sharedPlatformHostRaw === 'string' && sharedPlatformHostRaw.trim()
+                    ? sharedPlatformHostRaw.trim()
+                    : 'gitlab.com';
+                const sc = gitExec([
+                    'clone',
+                    '--depth',
+                    '1',
+                    '--branch',
+                    sharedRef,
+                    '--single-branch',
+                    '--',
+                    resolveCloneTarget(sharedRepo, sharedHost),
+                    sharedDir,
+                ], { timeout: 120_000 });
+                if (sc.exitCode === 0) {
+                    if (node_fs_1.default.existsSync(node_path_1.default.join(sharedDir, pre.destination))) {
+                        sharedShadow = true;
+                        sharedShadowNote =
+                            "This practice id already exists in the shared Pareto vault. After this promotion the client's version is the one that applies for this client.";
+                    }
+                }
+                else {
+                    // An unreachable/failed shared vault must never block, fail, or
+                    // slow-fail a preview — leave the flag false and note it.
+                    notes.push('the shared vault could not be checked');
+                }
+            }
+            catch {
+                notes.push('the shared vault could not be checked');
+            }
+            finally {
+                if (sharedDir)
+                    node_fs_1.default.rmSync(sharedDir, { recursive: true, force: true });
+            }
+        }
+        // 7 & 8. Pin both sides in the opaque expect token, then return.
+        const expect = buildExpectToken(pre.raw, baseline);
+        return {
+            status: 'preview',
+            repo: pre.repo,
+            ref: pre.ref,
+            destination: pre.destination,
+            mode,
+            id: boundedToken(pre.practice.id),
+            diff,
+            content,
+            sharedShadow,
+            sharedShadowNote,
+            expect,
+            notes,
+        };
+    }
+    finally {
+        if (cloneDir)
+            node_fs_1.default.rmSync(cloneDir, { recursive: true, force: true });
+    }
+}
+// ─── Confirm (write half of the write path) ──────────────────────────────────────
+/** Build a TRANSPORT refusal from a failed git invocation's stderr (first line only). */
+function transportRefusal(res) {
+    const cause = boundedToken((res.stderr || '').split(/\r?\n/)[0] || 'unknown error');
+    return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, `This practice was not pushed: git could not reach the vault (${cause}). Check your access to the vault and run the promotion again.`);
+}
+/**
+ * Confirm a promotion: re-run the full 29-01 preflight chain (never trust
+ * the preview), re-verify the opaque `expect` token against a freshly read
+ * local file AND a freshly cloned remote baseline, absorb unrelated remote
+ * movement with a fast-forward-only pull, then stage/commit/push exactly
+ * the destination path with no force flag on any code path. On success,
+ * refreshes the local read cache via `./vault.cjs`'s `vaultFetch` verbatim.
+ *
+ * Deliberate deviation from a literal `git show`-based remote-baseline read
+ * (Rule 1 bug avoidance): `execGit`'s shared `_spawnResult` unconditionally
+ * `.trim()`s captured stdout, which would silently strip a file's trailing
+ * newline and make every legitimate hash comparison spuriously mismatch.
+ * Instead this re-derives the remote baseline from the filesystem AFTER the
+ * fast-forward-only pull (the same fs-read technique `previewPromotion`
+ * already uses for its own baseline capture) — byte-exact, and the pull
+ * step the plan already requires does the "sync to the fetched ref" work
+ * for free, so no separate `git show`/`cat-file` call is needed.
+ */
+function confirmPromotion({ cwd, filePath, expect, _exec, _vault, _practices }) {
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGit;
+    // 1. Full preflight re-run — never trust the preview. Re-derives repo,
+    // ref, host, and destination from scratch; never accepts a caller-
+    // supplied id/destination/repo/ref.
+    const pre = promotePreflight({ cwd, filePath, _vault, _practices });
+    if (pre.status !== 'ok')
+        return pre;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = _vault ?? require('./vault.cjs');
+    // 2. Missing/empty token → refuse before any clone.
+    if (!expect || typeof expect !== 'string' || expect.length === 0) {
+        return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, 'This practice was not pushed: the confirmation is missing the preview token it needs. ' +
+            'Run the promotion without confirming first, then pass the token it prints.');
+    }
+    // 3. Split the token; a malformed token (no separator) naturally fails the
+    // local-hash comparison below rather than needing a distinct code path.
+    const sepIdx = expect.indexOf('.');
+    const pinnedLocal = sepIdx === -1 ? expect : expect.slice(0, sepIdx);
+    const pinnedRemote = sepIdx === -1 ? '' : expect.slice(sepIdx + 1);
+    // 4. Recompute the local hash from the FRESHLY read content (pre.raw came
+    // from this invocation's own promotePreflight, not the preview's). A
+    // mismatch means the local file changed since the operator previewed it —
+    // this is what makes D-10's byte-identity claim hold across two separate
+    // process invocations (T-29-13).
+    const localHash = node_crypto_1.default.createHash('sha256').update(pre.raw).digest('hex');
+    if (localHash !== pinnedLocal) {
+        return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, 'This practice was not pushed: the file on your machine changed after you previewed it. ' +
+            'Run the promotion again to preview the new version.');
+    }
+    // 5. Clone into a fresh disposable mkdtemp directory — exactly as the
+    // preview does, but NEVER the preview's own clone directory and NEVER the
+    // read cache.
+    let cloneDir = null;
+    try {
+        cloneDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'pp-vault-confirm-'));
+        const cl = gitExec(['clone', '--branch', pre.ref, '--single-branch', '--', resolveCloneTarget(pre.repo, pre.host), cloneDir], { timeout: 120_000 });
+        if (cl.exitCode !== 0)
+            return transportRefusal(cl);
+        // 6. Fetch the resolved ref from origin, then absorb any unrelated
+        // remote movement with a fast-forward-only pull. The file-scoped
+        // baseline check below runs AFTER this on purpose: a target-file race
+        // is still caught by the hash comparison, and a race that instead
+        // defeats the transport layer (an unrelated push landing between this
+        // pull and this module's own push, below) fails closed on the push
+        // itself — the intended structural backstop (T-29-04), never retried.
+        const ft = gitExec(['fetch', 'origin', pre.ref], { cwd: cloneDir, timeout: 120_000 });
+        if (ft.exitCode !== 0)
+            return transportRefusal(ft);
+        const pull = gitExec(['pull', '--ff-only', 'origin', pre.ref], { cwd: cloneDir, timeout: 120_000 });
+        if (pull.exitCode !== 0)
+            return transportRefusal(pull);
+        // 7. Re-derive the remote baseline from the now fast-forwarded working
+        // tree (fs-level read, byte-exact — never git-stdout-derived, which is
+        // silently trimmed by the shared exec helper). Scoped to the
+        // destination file only (D-15): commit/tree shas are never compared,
+        // so an unrelated promotion never blocks this one.
+        const destAbs = node_path_1.default.join(cloneDir, pre.destination);
+        const remoteExists = node_fs_1.default.existsSync(destAbs);
+        const remoteContent = remoteExists ? node_fs_1.default.readFileSync(destAbs, 'utf-8') : null;
+        const remoteHash = remoteContent === null ? 'absent' : node_crypto_1.default.createHash('sha256').update(remoteContent).digest('hex');
+        if (remoteHash !== pinnedRemote) {
+            return refusal(PROMOTE_GUARD.CONCURRENT_EDIT, ERROR_REASON.VAULT_PROMOTE_CONCURRENT_EDIT, `This practice was not pushed: someone else changed ${boundedToken(pre.destination)} in the vault since you previewed it. ` +
+                'Run the promotion again to see their version before you push.');
+        }
+        const mode = remoteExists ? 'update' : 'create';
+        // 8. Write the promoted content, then stage exactly that one path.
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(destAbs), { recursive: true });
+        node_fs_1.default.writeFileSync(destAbs, pre.raw, 'utf-8');
+        const add = gitExec(['add', '--', pre.destination], { cwd: cloneDir });
+        if (add.exitCode !== 0)
+            return transportRefusal(add);
+        // 9. Configure identity only if git reports none — preserve an
+        // operator's own configured identity when present.
+        const idCheck = gitExec(['config', 'user.email'], { cwd: cloneDir });
+        if (idCheck.exitCode !== 0 || !idCheck.stdout.trim()) {
+            gitExec(['config', 'user.email', 'pp-core-vault-promote@pareto.local'], { cwd: cloneDir });
+            gitExec(['config', 'user.name', 'pp-core vault promote'], { cwd: cloneDir });
+        }
+        // 10. Commit once.
+        const id = pre.practice.id;
+        const commitMessage = `practice(${mode}): ${boundedToken(id)}\n\nPromoted from this project via pp-core's vault write-back arm.`;
+        const commitRes = gitExec(['commit', '-m', commitMessage], { cwd: cloneDir });
+        if (commitRes.exitCode !== 0)
+            return transportRefusal(commitRes);
+        // 11. Push once — origin, local HEAD mapped to the resolved ref. No
+        // force flag, no lease flag, no short-form alias, not on this call, not
+        // on a retry. A non-fast-forward rejection is the intended structural
+        // backstop for a race that defeats the file-scoped check above; never
+        // re-run, never looped, never escalated.
+        const push = gitExec(['push', 'origin', `HEAD:${pre.ref}`], { cwd: cloneDir, timeout: 120_000 });
+        if (push.exitCode !== 0) {
+            return refusal(PROMOTE_GUARD.TRANSPORT, ERROR_REASON.VAULT_PROMOTE_TRANSPORT_FAILED, 'This practice was not pushed: the vault moved ahead while the push was running. ' +
+                'Run the promotion again to preview against the current version.');
+        }
+        const shaRes = gitExec(['rev-parse', '--short', 'HEAD'], { cwd: cloneDir });
+        const commit = shaRes.stdout.trim();
+        // 12. Refresh the local read cache by reusing vaultFetch verbatim
+        // (D-11) — no new caching logic, never a direct write into
+        // .planning/vault/. A refresh failure is non-fatal: the push already
+        // succeeded and must be reported as such.
+        //
+        // vaultFetch has its own TTL-based freshness short-circuit (returns the
+        // PRIOR manifest untouched when it is recent and the ref matches — see
+        // src/vault.cts, frozen/unmodified here). Left alone, a promote that
+        // runs shortly after any recent fetch (routine — e.g. the plan:pre gate
+        // fetched minutes ago) would short-circuit on the now-stale prior
+        // manifest and serve pre-promotion content, defeating D-11's entire
+        // purpose ("the operator's next plan/review/ship sees the promoted
+        // practice"). Clearing ONLY the staleness marker (never writing cache
+        // content — that stays vaultFetch's job) forces a genuine re-fetch.
+        try {
+            node_fs_1.default.rmSync(node_path_1.default.join(cwd, '.planning', 'vault', '.manifest.json'), { force: true });
+        }
+        catch {
+            /* best-effort; a failed clear just means vaultFetch may short-circuit below */
+        }
+        let cacheRefreshed = false;
+        const notes = [];
+        try {
+            const manifest = vault.vaultFetch(cwd);
+            cacheRefreshed = !!manifest && manifest.source === 'fetched';
+        }
+        catch {
+            cacheRefreshed = false;
+        }
+        if (!cacheRefreshed) {
+            notes.push('the local copy could not be refreshed; the next fetch will pick it up');
+        }
+        return {
+            status: 'pushed',
+            repo: pre.repo,
+            ref: pre.ref,
+            destination: pre.destination,
+            mode,
+            id: boundedToken(id),
+            commit,
+            cacheRefreshed,
+            notes,
+        };
+    }
+    finally {
+        if (cloneDir)
+            node_fs_1.default.rmSync(cloneDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Single entry point 29-04's router calls: dispatches to `confirmPromotion`
+ * when `confirmed` is true, otherwise to `previewPromotion`.
+ */
+function promotePractice({ cwd, filePath, confirmed, expect, _exec, _vault, _practices, }) {
+    if (confirmed) {
+        return confirmPromotion({ cwd, filePath, expect, _exec, _vault, _practices });
+    }
+    return previewPromotion({ cwd, filePath, _exec, _vault, _practices });
+}
+// ─── Report rendering (human-readable half of the D-16 output contract) ────────
+/**
+ * Render any verdict `promotePractice` can produce as plain English (the
+ * COMM-01 bar, `docs/practices-plain-english-standard.md`) — the form 29-04's
+ * CLI router selects when `--raw` is absent. Every vault-authored token (id,
+ * repo, destination, notes) passes through `boundedToken` before
+ * interpolation (T-29-07) — these values ultimately derive from an
+ * operator-supplied practice file, not this module's own logic. For a
+ * refusal this is exactly the single sentence `refusal()` already built. For
+ * a preview it states the target repo, the destination path, whether the
+ * promotion creates or updates a practice, the shared-vault disclosure
+ * sentence when that flag is set, a line stating the secret scan found
+ * nothing, the token line the confirmed run needs, and then the complete
+ * diff or complete content under a heading — never elided, because the
+ * operator is confirming exactly these bytes. For a push it states the
+ * repo, the destination, the new commit, and whether the local copy was
+ * refreshed.
+ */
+function renderPromoteReport(verdict) {
+    if (verdict.status === 'refused') {
+        return verdict.message;
+    }
+    if (verdict.status === 'preview') {
+        const lines = [];
+        const action = verdict.mode === 'create' ? 'creates a new practice' : 'updates an existing practice';
+        lines.push(`This promotes "${boundedToken(verdict.id)}" to ${boundedToken(verdict.repo)} at ${boundedToken(verdict.destination)}.`);
+        lines.push(`This ${action} in the vault.`);
+        if (verdict.sharedShadow && verdict.sharedShadowNote) {
+            lines.push(boundedToken(verdict.sharedShadowNote));
+        }
+        lines.push('The secret scan found nothing to flag.');
+        // NOT boundedToken: the expect token is generated by buildExpectToken (a
+        // sha256 pair, fixed length, no untrusted input), and it is the one value
+        // on this page the operator must copy VERBATIM. Bounding it truncated the
+        // remote half with an ellipsis on every update — create mode escaped only
+        // because its remote half is the short literal "absent" — and pasting the
+        // truncated value produced the concurrent-edit refusal, telling the
+        // operator someone else had changed the practice when nobody had.
+        lines.push(`To push this, run the promotion again with --confirmed --expect ${verdict.expect}.`);
+        for (const note of verdict.notes) {
+            lines.push(`Note: ${boundedToken(note)}`);
+        }
+        lines.push('');
+        if (verdict.mode === 'update') {
+            lines.push('## Full diff');
+            lines.push(verdict.diff && verdict.diff.length > 0 ? verdict.diff : '(no changes)');
+        }
+        else {
+            lines.push('## Full content');
+            lines.push(verdict.content ?? '');
+        }
+        return lines.join('\n');
+    }
+    // verdict.status === 'pushed'
+    const pushedLines = [];
+    pushedLines.push(`Pushed "${boundedToken(verdict.id)}" to ${boundedToken(verdict.repo)} at ${boundedToken(verdict.destination)} — commit ${boundedToken(verdict.commit)}.`);
+    pushedLines.push(verdict.cacheRefreshed
+        ? 'Your local copy was refreshed with the new content.'
+        : 'Your local copy was not refreshed automatically; the next fetch will pick it up.');
+    for (const note of verdict.notes) {
+        pushedLines.push(`Note: ${boundedToken(note)}`);
+    }
+    return pushedLines.join('\n');
+}
+module.exports = {
+    SECRET_SHAPES,
+    scanForSecrets,
+    PROMOTE_GUARD,
+    promotePreflight,
+    refusal,
+    buildExpectToken,
+    previewPromotion,
+    confirmPromotion,
+    promotePractice,
+    renderPromoteReport,
+};