@pareto4/pp-core 1.9.0 → 1.11.0

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

@@ -0,0 +1,842 @@
+'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 `assertVaultWriteTarget` write-target check. That
+ *   guard's identity is now the resolved `(repo, host)` pair for both
+ *   tiers (Phase 31, CFG-02/D-10) — it gained a required target-host
+ *   parameter, and this arm passes one derived from the coordinate
+ *   resolver rather than a config-only host chain. 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`) —
+ *     this module delegates to `assertVaultWriteTarget` and reimplements
+ *     none of it (D-05); the guard's signature gained a required target
+ *     host in Phase 31 (D-10), which this call site passes from the
+ *     coordinate resolver.
+ *   - `./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");
+const git_provider_cjs_1 = require("./git-provider.cjs");
+const vault_coordinates_cjs_1 = require("./vault-coordinates.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';
+    // Resolve the provider ONCE, here in the preflight (PROV-02/T-30-16) — both
+    // previewPromotion and confirmPromotion re-run this preflight and read the
+    // same `provider` field back off the result, so they cannot compose two
+    // different remotes for the same promotion. Moved ahead of target-host
+    // resolution (Phase 31, D-10): the host now comes from the coordinate
+    // resolver below, which itself takes the provider as an argument.
+    const providerResolution = (0, git_provider_cjs_1.resolveProvider)(cwd);
+    const provider = providerResolution.provider;
+    const providerWarnings = providerResolution.warnings.slice();
+    // Target host — from the coordinate resolver (Phase 31, D-10), not a
+    // config-only host chain. `client.vaultHost` wins when set; otherwise
+    // `.platform-bindings.json`'s `platform.host` (D-09), warned; otherwise
+    // the provider's default host. The `.planning/config.json`-only
+    // `platform.host` read this preflight used to fall back to last is gone
+    // — leaving it in place beside the resolver would not fix D-09, it would
+    // add a third disagreeing source of the same value.
+    const clientCoord = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(cwd, provider);
+    const targetHost = clientCoord.host;
+    if (clientCoord.warnings.length > 0)
+        providerWarnings.push(...clientCoord.warnings);
+    // Shared-tier coordinates — resolved ONCE here in the preflight (D-09,
+    // T-31-09), carried forward on the success shape below rather than
+    // resolved a second time by `previewPromotion`. This is the same
+    // construction already used for `provider` and for `clientCoord` above:
+    // both `previewPromotion` and `confirmPromotion` re-run this preflight and
+    // read fields back off its result, so a promotion cannot end up resolving
+    // two disagreeing answers for its own shared-shadow lookup.
+    //
+    // `applyBuiltInDefault: false` is load-bearing, not a stylistic default.
+    // This path has never applied the built-in shared-vault default — it used
+    // to read `vault.fallback_repo` with an empty-string fallback, so a
+    // project that never set the key performed no shared-shadow clone at all.
+    // Passing `true` here would give every existing gitlab install a shared
+    // clone it does not perform today, breaking ROADMAP SC3. The read-path
+    // ladder and `assertVaultWriteTarget` both pass `true` because both of
+    // them already apply the built-in default today (they always have) — this
+    // is the one caller that deliberately withholds it.
+    const sharedCoord = (0, vault_coordinates_cjs_1.resolveSharedCoordinates)(cwd, provider, { applyBuiltInDefault: false });
+    if (sharedCoord.warnings.length > 0)
+        providerWarnings.push(...sharedCoord.warnings);
+    // D-13/WR-01: read the resolver's OWN verdict straight off `sharedCoord`
+    // — no local re-derivation. Before this fix, `sharedCoord.suppressed` was
+    // unconditionally `false` on this call regardless of provider, because
+    // withholding the built-in default (`applyBuiltInDefault: false`, above)
+    // also disabled the resolver's suppression branch. The resolver now
+    // reports `suppressed`/`suppressedKind` correctly even with the built-in
+    // default withheld, so this module no longer needs to (and must not)
+    // approximate the fact from `sharedRepo`/`provider` itself — that
+    // approximation was exactly the WR-01 defect (PROJECT.md: an operator who
+    // deliberately disabled the shared tier via an empty `vault.fallback_repo`
+    // was shown a note asking them to set the very key they already set,
+    // because this module could not tell that apart from "never configured").
+    const sharedSuppressed = sharedCoord.suppressed;
+    const sharedSuppressedKind = sharedCoord.suppressedKind;
+    // Any warning composing the primary clone target for THIS
+    // provider/repo/host (an operator-supplied `.git` suffix under azure) is
+    // folded in here too, alongside the provider and coordinate warnings
+    // already collected above, so a single `notes` push in the preview
+    // surfaces all of them.
+    if (!(0, git_provider_cjs_1.isLiteralCloneTarget)(targetRepo.trim())) {
+        const composedForWarnings = (0, git_provider_cjs_1.composeCloneTarget)(provider, targetRepo, targetHost);
+        if (composedForWarnings.warnings.length > 0)
+            providerWarnings.push(...composedForWarnings.warnings);
+    }
+    // 6. Write-target guard (D-05, D-10) — this arm delegates to
+    // assertVaultWriteTarget and never re-derives, wraps, relaxes, or
+    // reimplements any of its three refusals; it passes the resolved target
+    // repo and target host straight through.
+    try {
+        vault.assertVaultWriteTarget(cwd, targetRepo, targetHost);
+    }
+    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,
+        provider,
+        providerWarnings,
+        sharedRepo: sharedCoord.repo,
+        sharedRef: sharedCoord.ref,
+        sharedHost: sharedCoord.host,
+        sharedSuppressed,
+        sharedSuppressedKind,
+    };
+}
+// ─── 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).
+ */
+// `isLiteralCloneTarget` and clone-target composition — the single
+// definitions live in `src/git-provider.cts` (imported above) and are shared
+// with the read path (`src/vault.cts`, 30-02). Do NOT reintroduce a local
+// copy of either here: a read/write divergence in this predicate was defect
+// P-1 in Phase 29 (the write path used `client.vaultRepo` verbatim while the
+// read path always composed a URL, so a slug broke writing and a path broke
+// reading) — duplicating the fix a second time is exactly how that class of
+// bug recurs.
+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;
+    // No local `./vault.cjs` handle is needed here any more (Phase 31,
+    // Task 1): the shared-shadow lookup below reads its coordinates off `pre`
+    // instead of calling `vault.cfgGet` directly, so this function no longer
+    // touches the vault module at all — `_vault` is still threaded through to
+    // `promotePreflight` above for the test-seam injection convention.
+    const notes = [];
+    // Surface any warning resolving the provider or composing the primary
+    // clone target produced (an unrecognized `vault.provider` value, or an
+    // operator-supplied `.git` suffix under azure) — visible in the preview an
+    // operator reads before confirming, never a silent degrade.
+    notes.push(...pre.providerWarnings);
+    // 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 the
+        // provider seam's composeCloneTarget so a `group/project` slug becomes a
+        // real URL on the resolved host and provider, instead of a relative path
+        // git cannot find.
+        const cl = gitExec([
+            'clone',
+            '--branch',
+            pre.ref,
+            '--single-branch',
+            '--',
+            (0, git_provider_cjs_1.composeCloneTarget)(pre.provider, pre.repo, pre.host).url,
+            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 — the shared coordinates are resolved exactly
+        // ONCE, in the preflight above, with the built-in default explicitly
+        // withheld (D-09, T-31-09); this function reads them back off `pre`
+        // rather than resolving them a second time. Skipped entirely (flag stays
+        // false) when no shared repo resolved, or it equals the client repo —
+        // the same skip shape as before, now expressed against the resolved
+        // field: a `null` `pre.sharedRepo` is treated the way the empty string
+        // used to be treated.
+        //
+        // The shared vault is addressed on the resolved shared host, in D-03's
+        // order: `vault.fallback_host` first, then the authoritative
+        // `platform.host` (`.platform-bindings.json` first, `.planning/config.json`
+        // as a warned fallback per D-09), then the provider-derived default —
+        // never the client's own `client.vaultHost`, 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. Composed under
+        // the SAME resolved provider as the client clone (deliberate and
+        // symmetric with `cloneTier`'s one-provider-per-fetch rule).
+        //
+        // Per-tier provider selection does NOT arrive with this phase's CFG-01:
+        // D-01 answered that with a deliberate, permanent no. One provider per
+        // project stands — a client does not straddle two providers — and the
+        // fix for the azure-composing-a-gitlab-URL hazard is that the shared
+        // coordinates became per-client config, which is exactly what resolving
+        // them once in the preflight, above, does.
+        let sharedShadow = false;
+        let sharedShadowNote = null;
+        const sharedRepo = pre.sharedRepo;
+        const sharedRef = pre.sharedRef;
+        const sharedHost = pre.sharedHost;
+        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.
+                const sc = gitExec([
+                    'clone',
+                    '--depth',
+                    '1',
+                    '--branch',
+                    sharedRef,
+                    '--single-branch',
+                    '--',
+                    (0, git_provider_cjs_1.composeCloneTarget)(pre.provider, sharedRepo, sharedHost).url,
+                    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 });
+            }
+        }
+        // Suppression note (D-02, D-11, D-13/WR-01) — pushed ONLY when the
+        // shared resolution reports suppression AND the kind is
+        // 'provider-default-unavailable'. A gitlab project with no
+        // `vault.fallback_repo` resolves `sharedSuppressed: false` (nothing was
+        // suppressed — no built-in default was withheld from a provider that
+        // would otherwise have gotten one) and emits nothing here, exactly as it
+        // did before this phase — this note is SC3-safe by construction.
+        //
+        // D-13/WR-01: an operator who set `vault.fallback_repo` to an empty
+        // string deliberately disabled the shared tier — `sharedSuppressedKind`
+        // is `'explicit-opt-out'` for that case, and telling them to set the key
+        // they already set is exactly the defect this closes. NO second note is
+        // added for the opt-out case: silence is the correct output for a
+        // choice the operator already made, and inventing a new note would be
+        // new behaviour rather than a fix. D-11's requirement to surface the
+        // skipped shared check is already met by the write guard's own refusal
+        // sentence (plan 03); this note additionally explains why, in the
+        // read-only preview an operator reads before confirming.
+        if (pre.sharedSuppressed && pre.sharedSuppressedKind === 'provider-default-unavailable') {
+            notes.push(`No shared vault is configured for the ${pre.provider} provider — the built-in Pareto shared default applies only to the gitlab provider. Set vault.fallback_repo to enable the shared tier.`);
+        }
+        // 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',
+            '--',
+            (0, git_provider_cjs_1.composeCloneTarget)(pre.provider, pre.repo, pre.host).url,
+            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,
+};