@pareto4/pp-core 1.13.0 → 1.17.1

package/pp-core/bin/lib/vault-update.cjs

@@ -1,8 +1,8 @@
 "use strict";
 /**
- * src/vault-update.cts — `pp-tools vault update [<tag>] [--yes]`.
+ * src/vault-update.cts — `pp-tools vault update [<tag>] [--yes]` (PBI 74316).
  *
- * Moves a project to another version of its client vault. The
+ * FORK-ONLY. Moves a project to another version of its client vault. The
  * vault version is a PROJECT property: `client.vaultRef` in the committed
  * `.platform-bindings.json` is the one place it lives, so no pp-core release
  * can move it — changing it is a deliberate act, and this is its command.
@@ -20,15 +20,6 @@
  * vault version a project picks implies a minimum pp-core, never the reverse).
  * It never commits: the command it prints is the operator's to run.
  *
- * With no `<tag>` it proposes the newest stable `vX.Y.Z` tag of the configured
- * vault repository, listed with `git ls-remote` at the same clone target the
- * fetch uses (`resolveClientCoordinates` + `composeCloneTarget`). Nothing here
- * reads an org profile for a version: the vault version is the project's.
- *
- * Every repository coordinate it prints goes through `redactCloneTarget`, and
- * every value it echoes from the bindings file or the command line is
- * bounded to one short line.
- *
  * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
  * compiles to the git-ignored `pp-core/bin/lib/vault-update.cjs`.
  */
@@ -48,8 +39,8 @@ const compose_bindings_cjs_1 = require("./compose-bindings.cjs");
 const git_provider_cjs_1 = require("./git-provider.cjs");
 const vault_coordinates_cjs_1 = require("./vault-coordinates.cjs");
 const platform_bindings_cjs_1 = require("./platform-bindings.cjs");
-// The one coordinate redactor. Cycle-free — src/vault.cts imports nothing from
-// this module; the lazy `require` in runFetch exists for the `_fetch` seam default.
+// VAULT-EGRESS-1 (quick 261005-8py): the one coordinate redactor. Cycle-free — src/vault.cts imports
+// nothing from this module; the lazy `require` in runFetch exists for the `_fetch` seam default.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const vaultModule = require("./vault.cjs");
 const { redactCloneTarget } = vaultModule;
@@ -66,11 +57,6 @@ function isObject(v) {
 function usableString(v) {
     return typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
 }
-/** A value from the bindings file or the command line, made safe to print: one line, at most 80 characters. */
-function shown(v) {
-    const flat = v.replace(/[\u0000-\u001F\u007F]+/g, ' ').trim();
-    return flat.length > 80 ? `${flat.slice(0, 80)}…` : flat;
-}
 function resolveRoot(cwd) {
     try {
         return (0, project_root_cjs_1.findProjectRoot)(cwd) || cwd;
@@ -103,7 +89,6 @@ function runFetch(root, opts) {
     return {
         source: typeof manifest.source === 'string' ? manifest.source : 'unknown',
         ref: typeof manifest.ref === 'string' ? manifest.ref : null,
-        tier: typeof manifest.tier === 'string' ? manifest.tier : null,
         warnings,
     };
 }
@@ -173,8 +158,7 @@ function vaultUpdate(cwd, opts = {}) {
     let tags;
     try {
         const provider = (0, git_provider_cjs_1.resolveProvider)(root).provider;
-        // The same host chain the fetch uses (client.vaultHost, platform host, provider default).
-        const host = (0, vault_coordinates_cjs_1.resolveClientCoordinates)(root, provider).host;
+        const host = usableString(client.vaultHost) ?? (0, vault_coordinates_cjs_1.resolvePlatformHost)(root).host ?? (0, vault_coordinates_cjs_1.defaultHostForProvider)(provider);
         const target = (0, git_provider_cjs_1.composeCloneTarget)(provider, repo, host);
         tags = (0, compose_bindings_cjs_1.listStableTagsAt)(target.url, { _lsRemote: opts._lsRemote });
     }
@@ -190,10 +174,10 @@ function vaultUpdate(cwd, opts = {}) {
     const requested = usableString(opts.target);
     const to = requested ? matchRequestedTag(requested, tags) : tags[0];
     if (!to) {
-        return fail('unknown_tag', `The vault repo has no tag "${shown(requested ?? "")}". Available (newest first): ${result.available.join(', ')}.`);
+        return fail('unknown_tag', `The vault repo has no tag "${requested}". Available (newest first): ${result.available.join(', ')}.`);
     }
     result.to = to;
-    const fromLabel = result.from === null ? 'main (unpinned)' : shown(result.from);
+    const fromLabel = result.from ?? 'main (unpinned)';
     if (result.from === to) {
         return { ...result, ok: true, message: `The project is already on vault ${to}.` };
     }
@@ -227,7 +211,7 @@ function vaultUpdate(cwd, opts = {}) {
         applied.fetch = runFetch(root, opts);
     }
     catch {
-        applied.fetch = { source: 'error', ref: null, tier: null, warnings: ['The vault could not be fetched at the new version — run "pp-tools vault fetch" to retry.'] };
+        applied.fetch = { source: 'error', ref: null, warnings: ['The vault could not be fetched at the new version — run "pp-tools vault fetch" to retry.'] };
     }
     try {
         applied.newerSchemaPractices = findNewerSchemaPractices(root, opts);
@@ -244,15 +228,7 @@ function renderVaultUpdate(r) {
         lines.push(`Newest available: ${r.latest}.`);
     }
     if (r.fetch) {
-        if (r.fetch.tier !== null && r.fetch.tier !== 'client' && r.fetch.source !== 'error') {
-            // A fallback-tier fetch is not the client vault at the new version, and
-            // must not read as if it were.
-            lines.push(`The client vault at ${r.to ?? 'the new version'} was NOT loaded: the fetch fell back to the ${r.fetch.tier} tier` +
-                `${r.fetch.ref ? ` at ${r.fetch.ref}` : ''}. Check access to the client vault, then run "pp-tools vault fetch".`);
-        }
-        else {
-            lines.push(`Fetched the vault: ${r.fetch.source}${r.fetch.ref ? ` at ${r.fetch.ref}` : ''}.`);
-        }
+        lines.push(`Fetched the vault: ${r.fetch.source}${r.fetch.ref ? ` at ${r.fetch.ref}` : ''}.`);
         for (const w of r.fetch.warnings)
             lines.push(w);
     }

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

@@ -103,6 +103,8 @@ const PROMOTE_GUARD = Object.freeze({
     WRITE_TARGET: 'write_target',
     CONCURRENT_EDIT: 'concurrent_edit',
     TRANSPORT: 'transport',
+    // 13-07 (D-14): standards mode — write-back has no practice layer to write to.
+    MODE: 'mode',
 });
 // ─── Secret-content scanner (WRB-03 / D-13 / D-14) ──────────────────────────────
 //
@@ -200,7 +202,7 @@ function boundedToken(v, max = 80) {
 }
 // ─── Preflight guard chain ───────────────────────────────────────────────────────
 /**
- * Run the promote preflight guard chain: activation, input, format
+ * Run the promote preflight guard chain: activation, mode (13-07), 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
@@ -211,16 +213,37 @@ function promotePreflight({ cwd, filePath, _vault, _practices }) {
     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) {
+    // 1. Activation — the vault-practices capability must be on. Runs before
+    // any filesystem access; rides the two existing default-false config keys
+    // (no new config key, no capability surface widening). Phase 15 D-24/D-25:
+    // asked of the ONE practices-switch reader, `isPracticesGateActive`, which
+    // resolves both keys exactly as the vault-practices gates' `when` does. The
+    // `cfgGet` pair it replaces read only the root config, so a workstream-scoped
+    // switch refused here while the gates rendered (15-RESEARCH C-1). Read from
+    // the REAL vault leaf, not the `_vault` seam, like the mode guard below: a
+    // mocked config read must not be able to switch promotion on.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const switchOwner = require('./vault.cjs');
+    if (!switchOwner.isPracticesGateActive(cwd)) {
         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.');
     }
+    // 1b. Mode (13-07, D-14, PARK-03) — in standards mode the vault carries
+    // standards documents maintained through its INDEX.md, not practice files,
+    // so there is nothing a promotion could write. Refused here, after the
+    // activation guard and BEFORE the input guard reads `filePath` or any clone
+    // runs, so the preview and `--confirmed` share it (both call this chain
+    // first). Read from the REAL vault leaf, not the `_vault` seam: a governance
+    // decision must not be switchable by a test mock (the 13-06 precedent). The
+    // envelope carries NO mode key — a promote verdict already uses that key for
+    // create/update — so the mode is named in the message only.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const modeOwner = require('./vault.cjs');
+    if (modeOwner.isStandardsModeActive(cwd)) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { notApplicablePromoteMessage } = require('./vault-mode.cjs');
+        return refusal(PROMOTE_GUARD.MODE, ERROR_REASON.VAULT_PROMOTE_NOT_APPLICABLE, notApplicablePromoteMessage());
+    }
     // 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' ||
@@ -242,21 +265,40 @@ function promotePreflight({ cwd, filePath, _vault, _practices }) {
         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.`);
     }
-    // 3b. Degraded-parse refusal. Write-side strictness is deliberate: the read
-    // side keeps a practice it does not fully understand, because it already
-    // governs work and dropping it would silently un-govern that work; promoting
-    // it would push the defect into the shared vault every machine fetches. Both
-    // consumers of DOCUMENTED_FRONTMATTER_KEYS move in the one change that
-    // widened it — had only the reader moved, an unknown key would have quietly
-    // become promotable.
+    // 3b. Degraded-parse refusal (CHECK-02e, 05-01).
+    //
+    // WRITE-SIDE STRICTNESS IS DELIBERATE, and the asymmetry with the read side
+    // is the point. On the READ side a practice the engine does not fully
+    // understand is retained: it came from the vault, it already governs work,
+    // and dropping it would silently un-govern that work (ADR-71924 §5). On the
+    // WRITE side the same practice is refused, because promoting it pushes the
+    // defect INTO the fleet-wide vault that every developer machine and CI runner
+    // fetches — one unreviewed key becomes everyone's degraded warning. The read
+    // side tolerates what the write side refuses.
+    //
+    // Both consumers of DOCUMENTED_FRONTMATTER_KEYS therefore moved in the one
+    // change that widened it (T-4-49): had only the reader moved, an unknown key
+    // would have quietly become promotable.
     if (parsed.degradedWarnings !== undefined && parsed.degradedWarnings.length > 0) {
         const cause = parsed.degradedWarnings[0].replace(/^.*?\s+degraded:\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.`);
     }
-    // 3c. Invalid-check-block refusal. The reader reports this defect on its own
-    // channel (`practice.checkInvalid`), which is neither `!parsed.ok` nor
-    // `degradedWarnings` — discovery folds it into `degraded[]`, but this path
-    // never calls discovery — so both rungs above miss it.
+    // 3c. Invalid-check-block refusal (CR-05 / G-3, 05-11).
+    //
+    // An invalid `check:` block is refused on the write side for the same reason
+    // 3b refuses a degraded parse, and the consequence here is worse. The reader
+    // reports this defect on a THIRD channel — `practice.checkInvalid` — which is
+    // neither `!parsed.ok` nor `degradedWarnings`, so both rungs above miss it;
+    // and the folding of `checkInvalid` into `degraded[]` happens inside
+    // `discoverPracticeFiles`, which this path never calls.
+    //
+    // Once such a practice is in the fleet vault the defect is not a warning for
+    // the next reader: `verdictForPractice`'s FIRST rung maps `checkInvalid` to a
+    // fail-closed FAIL(check_invalid), so it becomes `block: true` at ship:pre and
+    // verify:post on every machine that fetches the vault. One typo would stop the
+    // whole fleet's builds. The refusal covers ANY invalid block regardless of
+    // which assertion kind it declared (D-05-05), because `checkInvalid` is the
+    // single fail-closed signal for both.
     if (typeof parsed.practice.checkInvalid === 'string' && parsed.practice.checkInvalid.length > 0) {
         return refusal(PROMOTE_GUARD.VALIDATION, ERROR_REASON.VAULT_PROMOTE_INVALID_PRACTICE, `This practice was not promoted: ${parsed.practice.checkInvalid} ` +
             'Fix the practice file and run the promotion again.');
@@ -421,7 +463,9 @@ function buildExpectToken(localRaw, remoteBaseline) {
 // 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;
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGitLocal;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment
+    const vault = _vault ?? require('./vault.cjs');
     // 1. Run the full preflight guard chain; refuse unchanged with no clone.
     const pre = promotePreflight({ cwd, filePath, _vault, _practices });
     if (pre.status !== 'ok')
@@ -459,7 +503,7 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
             cloneDir,
         ], { timeout: 120_000 });
         if (cl.exitCode !== 0) {
-            const cause = shownCause(cl.stderr);
+            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
@@ -571,13 +615,13 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
         // 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.`);
+            notes.push(`No shared vault is configured for the ${pre.provider} provider — the built-in Pareto shared default applies only to the github 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: shownRepo(pre.repo),
+            repo: vault.redactCloneTarget(pre.repo),
             ref: pre.ref,
             destination: pre.destination,
             mode,
@@ -596,25 +640,9 @@ function previewPromotion({ cwd, filePath, _exec, _vault, _practices }) {
     }
 }
 // ─── Confirm (write half of the write path) ──────────────────────────────────────
-/**
- * Pack 6 D-07: the display-safe forms used in every verdict and refusal this
- * module EMITS — the one owner in src/vault.cts, lazily required (the
- * module's `_vault` seam stays the fetch seam; redaction is never mocked).
- * Comparisons, the expect token and every git invocation keep the RAW values.
- */
-function shownRepo(repo) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const v = require('./vault.cjs');
-    return v.redactCloneTarget(repo) ?? repo;
-}
-function shownCause(stderr) {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const v = require('./vault.cjs');
-    return boundedToken(v.redactRemoteText((stderr || '').split(/\r?\n/)[0] || 'unknown error'));
-}
 /** Build a TRANSPORT refusal from a failed git invocation's stderr (first line only). */
 function transportRefusal(res) {
-    const cause = shownCause(res.stderr);
+    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.`);
 }
 /**
@@ -636,7 +664,7 @@ function transportRefusal(res) {
  * 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;
+    const gitExec = _exec ?? shell_command_projection_cjs_1.execGitLocal;
     // 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.
@@ -774,7 +802,7 @@ function confirmPromotion({ cwd, filePath, expect, _exec, _vault, _practices })
         }
         return {
             status: 'pushed',
-            repo: shownRepo(pre.repo),
+            repo: vault.redactCloneTarget(pre.repo),
             ref: pre.ref,
             destination: pre.destination,
             mode,