@pareto4/pp-core 1.12.1 → 1.13.0

package/pp-core/bin/lib/clusters.cjs

@@ -44,6 +44,7 @@ exports.CLUSTERS = Object.freeze({
         'eval-review',
         'add-tests',
         'secure-phase',
+        'vault-review',
     ]),
     milestone: Object.freeze([
         'new-milestone',

package/pp-core/bin/lib/command-aliases.cjs

@@ -712,6 +712,13 @@ exports.NON_FAMILY_COMMAND_ALIASES = [
         ],
         "mutation": true
     },
+    {
+        "canonical": "phase.manifest",
+        "aliases": [
+            "phase manifest"
+        ],
+        "mutation": true
+    },
     {
         "canonical": "phase.mvp-mode",
         "aliases": [

package/pp-core/bin/lib/compose-bindings.cjs

@@ -47,6 +47,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COMPOSE_BINDINGS_FLAGS = exports.SEED_VALUE_MAX_LENGTH = void 0;
 exports._resetPlatformTagMemoForTests = _resetPlatformTagMemoForTests;
+exports.listStableTagsAt = listStableTagsAt;
+exports.pickLatestStableTag = pickLatestStableTag;
 exports.resolveCreatedWithFrom = resolveCreatedWithFrom;
 exports.composeBindings = composeBindings;
 exports.redactComposeResultForEmission = redactComposeResultForEmission;
@@ -398,33 +400,7 @@ function resolveLatestPlatformTag(cwd, repo, provider, opts) {
         return cached;
     let result;
     try {
-        const lsOutput = typeof opts._lsRemote === 'function'
-            ? opts._lsRemote(url)
-            : node_child_process_1.default.execFileSync('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', url, 'v*'], {
-                encoding: 'utf-8',
-                timeout: 10_000,
-                maxBuffer: 512 * 1024,
-                windowsHide: true,
-                stdio: ['ignore', 'pipe', 'pipe'],
-            });
-        const tags = lsOutput
-            .split('\n')
-            .map((line) => {
-            const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
-            return m ? m[1].trim() : '';
-        })
-            .filter((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
-        if (tags.length === 0) {
-            result = { tag: null, warnings: [] };
-        }
-        else {
-            let latest = tags[0];
-            for (const t of tags) {
-                if ((0, semver_compare_cjs_1.compareSemverCore)(t, latest) > 0)
-                    latest = t;
-            }
-            result = { tag: latest, warnings: [] };
-        }
+        result = { tag: pickLatestStableTag(listStableTagsAt(url, opts)), warnings: [] };
     }
     catch {
         result = {
@@ -437,6 +413,44 @@ function resolveLatestPlatformTag(cwd, repo, provider, opts) {
     platformTagMemo.set(url, result);
     return result;
 }
+/**
+ * List the stable `vX.Y.Z` tags at `url`, never shell-eval'd (T-34-25):
+ * `git ls-remote` is spawned with an argv array, bounded by
+ * `timeout`/`maxBuffer`/`windowsHide` (T-34-26), with the child's stderr piped
+ * and discarded. `--` ends the options, so a flag-shaped target can never be
+ * read as one. Filtered with `isStableTripletSemver`, the single blessed
+ * predicate. THROWS on any git fault — callers own the degrade policy. Shared
+ * by the platform-tag lookup and `vault update`.
+ */
+function listStableTagsAt(url, opts = {}) {
+    const lsOutput = typeof opts._lsRemote === 'function'
+        ? opts._lsRemote(url)
+        : node_child_process_1.default.execFileSync('git', ['ls-remote', '--tags', '--refs', '--sort=-v:refname', '--', url, 'v*'], {
+            encoding: 'utf-8',
+            timeout: 10_000,
+            maxBuffer: 512 * 1024,
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    return lsOutput
+        .split('\n')
+        .map((line) => {
+        const m = line.match(/\brefs\/tags\/([^\s^]+)$/);
+        return m ? m[1].trim() : '';
+    })
+        .filter((t) => t && (0, semver_compare_cjs_1.isStableTripletSemver)(t));
+}
+/** The highest tag by `compareSemverCore`, or `null` for an empty list. */
+function pickLatestStableTag(tags) {
+    if (tags.length === 0)
+        return null;
+    let latest = tags[0];
+    for (const t of tags) {
+        if ((0, semver_compare_cjs_1.compareSemverCore)(t, latest) > 0)
+            latest = t;
+    }
+    return latest;
+}
 /**
  * Read the first readable, semver-shaped `VERSION` file among the candidate
  * locations resolved against `baseDir`, returning `<binName>@<version>`.

package/pp-core/bin/lib/decisions.cjs

@@ -10,6 +10,7 @@
  * CJS callers that only use {id, text} safely ignore the extra fields.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDecisionsReport = parseDecisionsReport;
 exports.parseDecisions = parseDecisions;
 const DISCRETION_HEADINGS = new Set([
     "claude's discretion",
@@ -17,6 +18,67 @@ const DISCRETION_HEADINGS = new Set([
     'claude discretion',
 ]);
 const NON_TRACKABLE_TAGS = new Set(['informational', 'folded', 'deferred']);
+// ── The decision-bullet grammar ────────────────────────────────────────────────────────────────────────────
+//
+// Why a grammar rather than one regex: this repository writes THREE bullet
+// forms, and originally only the first was readable. The two others were
+// not exotic — they are what `discuss-phase` emits and what hand-authored
+// CONTEXT.md files use — so a parser that reads only form A hands a blocking
+// coverage gate an empty decision set and lets it report a clean pass. That is
+// the defect this grammar retires (todo: decision-coverage-gate-false-pass).
+//
+//   Form A  `- **D-NN:** text`                  → arm A
+//   Form B  `- **D-NN: Title.** text`           → arm B (title may wrap: arm D)
+//   Form C  `- **D-NN** text`                   → arm C
+//
+// HEAD matches the bullet opener and splits off `rest` (everything after the id
+// and its optional `[tags]` group). The id rule is #3575's, unchanged: the first
+// character after `D-` must be alphanumeric, so `D--x` and `D-_x` still fail
+// HEAD and reach the parse-miss guard.
+const BULLET_HEAD_RE = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?(.*)$/;
+// Arm A — form A, widened. The run before the FIRST `:**` may now contain `:`.
+// #1343 wrote that run as `[^:*]*`, which is what dropped every bold-title
+// bullet AND `- **D-07 ratio 3:1:** w` (that miss used to be pinned as a floor;
+// it now parses as D-07 / "w"). Lazy `[^*]*?` still stops at the first `:**`.
+const ARM_A_RE = /^([^*]*?):\*\*\s*(.*)$/;
+// Arm B — form B, the bold title. The title MAY contain `:` because real
+// titles carry backticked loop points (`plan:post`, `execute:post`, `check:`);
+// a title regex that excluded `:` measured four misses across two phases.
+const ARM_B_RE = /^([^*]*?):\s*([^*]*?)\s*\*\*\s*(.*)$/;
+// Arm C — the bold closes with no colon before it (`- **D-VH-1** body`, and
+// `- **D-13 → see D-14.** *(reserved)*`). The only thing this form lacks is
+// punctuation; the id is unambiguous, so it is admitted.
+const ARM_C_RE = /^([^*]*?)\s*\*\*\s*(.*)$/;
+// Arm D — no closing `**` on this line: a form-B title that wraps onto the
+// next line. The existing continuation logic appends the following indented
+// lines, stray `**` included (they are cosmetic in the resulting text).
+const ARM_D_RE = /^([^*]*)$/;
+/**
+ * Read a decision bullet's text out of `rest` (the remainder of the bullet line
+ * after the id and optional `[tags]`), trying arms A → B → C → D; first match
+ * wins. Returns null when no arm matches, which sends the line to the
+ * parse-miss guard.
+ *
+ * The guard is NOT vacuous after this widening: a malformed id fails HEAD, and
+ * a `rest` carrying a `*` in no arm shape (`- **D-01 *italic* no close`)
+ * matches no arm.
+ */
+function readBulletText(rest) {
+    const a = rest.match(ARM_A_RE);
+    if (a)
+        return a[2];
+    const b = rest.match(ARM_B_RE);
+    // Headline first, so a six-word `softPhrase` is drawn from the title.
+    if (b)
+        return (b[2] + ' ' + b[3]).trim();
+    const c = rest.match(ARM_C_RE);
+    if (c)
+        return (c[1] + ' ' + c[2]).trim();
+    const d = rest.match(ARM_D_RE);
+    if (d)
+        return d[1].replace(/^\s*:?\s*/, '').trim();
+    return null;
+}
 /**
  * Strip fenced code blocks from `content` so example `<decisions>` snippets
  * inside ```` ``` ```` do not pollute the parser (review F11).
@@ -40,34 +102,28 @@ function extractDecisionsBlock(content) {
     return matches.map((m) => m[1]).join('\n\n');
 }
 /**
- * Parse trackable decisions from CONTEXT.md content.
+ * Parse CONTEXT.md content into BOTH channels: the decisions that were read,
+ * and the bullets that could not be.
  *
- * Returns ALL D-NN decisions found inside `<decisions>` (including
- * non-trackable ones, with `trackable: false`). Callers that only want the
- * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ * `decisions` holds ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). `unparsed` holds every line
+ * that opened like a decision bullet and matched no arm of the grammar.
+ *
+ * The second channel exists because "the block was empty" and "the parser
+ * could not read any of it" are opposite situations that a coverage gate used
+ * to report identically — as a clean pass on a total of zero.
  */
-function parseDecisions(content) {
+function parseDecisionsReport(content) {
     if (!content || typeof content !== 'string')
-        return [];
+        return { decisions: [], unparsed: [] };
     const block = extractDecisionsBlock(content);
     if (block === null)
-        return [];
+        return { decisions: [], unparsed: [] };
     const lines = block.split(/\r?\n/);
     const out = [];
+    const unparsed = [];
     let category = '';
     let inDiscretion = false;
-    // Bullet line: `- **D-NN[ [tags]]:** text`
-    // Phase 6 (#3575): aligned to CJS regex — accepts alphanumeric IDs (D-01, D-INFRA-01, D-FOO_BAR)
-    // in addition to numeric-only IDs (D-42). The first character after `D-` must
-    // be alphanumeric, so malformed shapes like `D--foo` or `D-_bar` are rejected.
-    // CJS callers consume {id, text} and ignore the optional extras.
-    // #1343: `[^:*]*` replaces the old `\s*` before `:**` so that a freeform run
-    // such as `(parenthetical)`, an em-dash, or other prose between the optional
-    // bracket-tag group and the closing `:**` is tolerated rather than silently
-    // dropping the whole decision. `[^:*]*` subsumes plain whitespace and stops
-    // correctly at `:**`. Capture groups 1 (id), 2 (bracket tags), 3 (text) are
-    // unchanged.
-    const bulletRe = /^\s*-\s+\*\*D-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\s*\[([^\]]+)\])?[^:*]*:\*\*\s*(.*)$/;
     let current = null;
     const flush = () => {
         if (current) {
@@ -94,29 +150,36 @@ function parseDecisions(content) {
             inDiscretion = DISCRETION_HEADINGS.has(normalized);
             continue;
         }
-        const bulletMatch = line.match(bulletRe);
-        if (bulletMatch) {
+        const headMatch = line.match(BULLET_HEAD_RE);
+        const bulletText = headMatch ? readBulletText(headMatch[3]) : null;
+        if (headMatch && bulletText !== null) {
             flush();
-            const id = `D-${bulletMatch[1]}`;
-            const tags = bulletMatch[2]
-                ? bulletMatch[2]
+            const id = `D-${headMatch[1]}`;
+            const tags = headMatch[2]
+                ? headMatch[2]
                     .split(',')
                     .map((t) => t.trim().toLowerCase())
                     .filter(Boolean)
                 : [];
             const trackable = !inDiscretion && !tags.some((t) => NON_TRACKABLE_TAGS.has(t));
-            current = { id, text: bulletMatch[3], category, tags, trackable };
+            current = { id, text: bulletText, category, tags, trackable };
             continue;
         }
         // Parse-miss guard (#1343): a line that looks like a `D-NN` decision bullet
-        // but failed `bulletRe` (e.g. a `:` or `*` inside the pre-colon run) must NOT
+        // but failed HEAD (malformed id) or matched no arm of the grammar must NOT
         // be silently dropped — a narrowed trackable set lets a blocking coverage gate
         // report a false pass. Surface it loudly instead.
+        //
+        // The miss is now recorded as DATA as well, so a gate can fail
+        // on it rather than warning past it. The `console.warn` stays: the stderr
+        // signal is what a human running the command by hand sees, and it is pinned
+        // by the #1343 regression tests.
         if (/^\s*-\s+\*\*D-/.test(line)) {
             // A malformed D-bullet still starts a (failed) new decision, so it ends the
             // previous one — flush before warning so a following continuation line cannot
             // be mis-appended to the prior valid decision.
             flush();
+            unparsed.push({ line: trimmed, category });
             console.warn(`parseDecisions: ignored unparseable decision bullet: ${trimmed}`);
             continue;
         }
@@ -132,5 +195,19 @@ function parseDecisions(content) {
         }
     }
     flush();
-    return out;
+    return { decisions: out, unparsed };
+}
+/**
+ * Parse trackable decisions from CONTEXT.md content.
+ *
+ * Returns ALL D-NN decisions found inside `<decisions>` (including
+ * non-trackable ones, with `trackable: false`). Callers that only want the
+ * gate-enforced decisions should filter `.filter(d => d.trackable)`.
+ *
+ * This signature is unchanged, and so is its behaviour. A caller that must not
+ * treat an unreadable bullet as an ABSENT decision — any gate that reports a
+ * verdict — should call `parseDecisionsReport` and read `unparsed`.
+ */
+function parseDecisions(content) {
+    return parseDecisionsReport(content).decisions;
 }

package/pp-core/bin/lib/dispatch-plan.cjs

@@ -34,7 +34,8 @@
  * here): researcher, pattern mapper,
  * planner (always) and plan checker passes; then code reviewer and fixer,
  * the heavy-tier install run (`phase.install-run`, src/install-run.cts),
- * verifier, security auditor and nyquist auditor. `totals.spawns` counts every agent spawn of every stage, as an upper
+ * verifier, security auditor, nyquist auditor and — heavy tier, vault
+ * practices on — the agent practice review. `totals.spawns` counts every agent spawn of every stage, as an upper
  * bound: entries marked `conditional` run only when the step before them asks
  * for it (a revision after a failed check, a fix after review findings).
  */
@@ -69,6 +70,7 @@ exports.STAGE_AGENTS = Object.freeze({
     codeFixer: 'pp-code-fixer',
     nyquistAuditor: 'pp-nyquist-auditor',
     securityAuditor: 'pp-security-auditor',
+    vaultReviewer: 'pp-vault-reviewer',
 });
 function spawn(id, agent, gate, reason, conditional = false) {
     return { id, kind: 'spawn', agent, gate, reason, conditional };
@@ -79,6 +81,9 @@ function step(id, gate, reason) {
 /**
  * The planning and verification stages of a phase, from its resolved tier.
  * `planBounceScript`: bounce runs only with a configured script.
+ * `vaultReview`: the project's vault practices apply (`vaultReviewApplies`,
+ * src/vault.cts — the caller reads it); the agent practice review is spawned
+ * only when that AND the tier's `vault_review` gate are both on.
  */
 function computeTierStages(tier, opts = {}) {
     const g = tier.gates;
@@ -117,6 +122,9 @@ function computeTierStages(tier, opts = {}) {
         verify.push(spawn('verify-security', exports.STAGE_AGENTS.securityAuditor, 'security_enforcement', 'threat-model verification (SECURITY.md)'));
     if (g.nyquist_validation)
         verify.push(spawn('verify-nyquist', exports.STAGE_AGENTS.nyquistAuditor, 'nyquist_validation', 'validation-gap audit (VALIDATION.md)'));
+    if (g.vault_review && opts.vaultReview === true) {
+        verify.push(spawn('verify-vault-review', exports.STAGE_AGENTS.vaultReviewer, 'vault_review', 'agent practice review of the client vault (VAULT-REVIEW.md); reports, never gates'));
+    }
     return { plan, verify };
 }
 function normalizePath(file) {
@@ -255,6 +263,7 @@ function waveDefects(spawns, byId) {
  * order; `phaseDir` is the phase directory relative to the project root.
  */
 function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOpts = {}) {
+    const contributions = (tierOpts.executorContributions ?? []).map((c) => ({ capId: c.capId, fragment: c.fragment }));
     const byId = new Map(plans.map((p) => [p.id, p]));
     const skippedComplete = plans.filter((p) => p.has_summary).map((p) => p.id);
     const incomplete = plans.filter((p) => !p.has_summary && (!policy.gapsOnly || p.gap_closure === true));
@@ -294,6 +303,7 @@ function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOp
                     build_reason: buildReason(members),
                     checkpoint: members.some((q) => !q.autonomous),
                     expected_summaries: entries.map((e) => e.summary),
+                    contributions: contributions.map((c) => ({ ...c })),
                 });
                 continue;
             }
@@ -311,6 +321,7 @@ function computeDispatchPlan(phase, phaseDir, plans, policy, tier = null, tierOp
                 build_reason: buildReason([p]),
                 checkpoint: !p.autonomous,
                 expected_summaries: [entry.summary],
+                contributions: contributions.map((c) => ({ ...c })),
             });
         }
         const defects = waveDefects(spawns, byId);

package/pp-core/bin/lib/frontmatter.cjs

@@ -216,6 +216,24 @@ function reconstructFrontmatter(obj) {
     }
     return lines.join('\n');
 }
+/**
+ * The raw lines of a top-level `key:` block inside a `---` frontmatter match —
+ * the `key:` line plus every following line that is blank or indented, up to
+ * the next column-0 key — with trailing blank lines dropped, or `null` when the
+ * frontmatter has no such top-level block.
+ */
+function rawTopLevelBlock(frontmatterMatch, key) {
+    const lines = frontmatterMatch.split(/\r?\n/).slice(1, -1);
+    const start = lines.findIndex((l) => l === `${key}:` || new RegExp(`^${key}:\\s*$`).test(l));
+    if (start === -1)
+        return null;
+    let end = start + 1;
+    while (end < lines.length && (lines[end].trim() === '' || /^\s/.test(lines[end])))
+        end += 1;
+    while (end > start + 1 && lines[end - 1].trim() === '')
+        end -= 1;
+    return lines.slice(start, end).join('\n');
+}
 function spliceFrontmatter(content, newObj) {
     const match = content.match(/^---\r?\n[\s\S]+?\r?\n---/);
     if (match) {
@@ -238,6 +256,25 @@ function spliceFrontmatter(content, newObj) {
         catch {
             /* fall through to regeneration on any comparison hiccup */
         }
+        // The practice-trace ledger (`vault:`, docs/vault-trace-format.md) is a list
+        // of maps the lossy serializer cannot re-emit. When the caller left it
+        // untouched — `frontmatter set <plan> wave 2`, the plan-graph write-back —
+        // its raw lines are carried over verbatim instead of being regenerated.
+        const ledger = rawTopLevelBlock(match[0], 'vault');
+        if (ledger !== null) {
+            try {
+                const original = extractFrontmatter(content);
+                if (frontmatterDeepEqual(original.vault, newObj.vault)) {
+                    const rest = { ...newObj };
+                    delete rest.vault;
+                    const restStr = reconstructFrontmatter(rest);
+                    return `---\n${restStr}${restStr === '' ? '' : '\n'}${ledger}\n---` + content.slice(match[0].length);
+                }
+            }
+            catch {
+                /* fall through to regeneration */
+            }
+        }
         const yamlStr = reconstructFrontmatter(newObj);
         return `---\n${yamlStr}\n---` + content.slice(match[0].length);
     }

package/pp-core/bin/lib/git-base-branch.cjs

@@ -27,10 +27,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BASE_BRANCH_REFUSED_REASON = void 0;
+exports.isPlausibleBranchRef = isPlausibleBranchRef;
 exports.readConfigBaseBranch = readConfigBaseBranch;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 exports.tryLocalBranch = tryLocalBranch;
+exports.resolveBaseBranchResult = resolveBaseBranchResult;
 exports.resolveBaseBranch = resolveBaseBranch;
 exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
 exports.cmdGitBaseBranch = cmdGitBaseBranch;
@@ -38,6 +41,99 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * The one thing that makes a base branch dangerous, and the only rule here that
+ * is OURS rather than git's.
+ *
+ * `execGit` uses argv, so a configured base branch is not shell injection. It is
+ * something narrower and worse: a value beginning with `-` is not a revision to
+ * git, it is an OPTION. `git log "--output=<path>..HEAD"` exits 0 and creates
+ * that file; so does `git diff`. A `.planning/config.json` shipped inside a
+ * cloned repository was therefore an arbitrary-file-creation-and-truncation
+ * primitive running as the developer or the CI runner (T-6-49).
+ *
+ * A dash INSIDE a name is an ordinary branch: `feature/-x` is a name git creates
+ * and resolves. Only the leading position turns a value into an option, so only
+ * the leading position is refused.
+ */
+const OPTION_SHAPED = /^-/;
+/**
+ * The characters git itself forbids in a ref name: ASCII control characters and
+ * space (`\x00`-`\x20`), DEL, and `~ ^ : ? * [ \`.
+ *
+ * REFUSING MORE THAN THIS IS ITS OWN DEFECT (W16). The first form of this
+ * validator was an allowlist of `[A-Za-z0-9._/-]`, which reads as prudent and is
+ * not: `feature/a+b`, `feature/a@b` and `café` are all names
+ * `git check-ref-format --branch` accepts and `git branch` creates, and all
+ * three were silently discarded in favour of whatever the ladder found next — a
+ * review computed over a range the project never asked for, which is the exact
+ * failure the ladder exists to end. None of `+ @ % = ( ) ; | $ !` can make git
+ * do anything, because nothing here reaches a shell. So the rule is git's rule,
+ * plus the leading dash, and nothing else.
+ */
+const FORBIDDEN_REF_CHARS = /[\x00-\x20\x7f~^:?*[\\]/;
+/** Sequences git forbids anywhere inside a ref name. */
+const FORBIDDEN_REF_SEQUENCES = ['..', '@{', '//'];
+/** A bound, so a pathological value cannot become a pathological command line. */
+const MAX_REF_LENGTH = 255;
+/**
+ * Is this a name git could actually resolve as a branch?
+ *
+ * The predicate is `git check-ref-format --branch` re-implemented, with a
+ * leading `-` refused on top. Re-implemented rather than shelled out to: this
+ * function is pure, total and called on a path that must never spawn a
+ * subprocess to decide whether it is safe to spawn a subprocess. The equivalence
+ * is not asserted here in prose — `tests/git-base-branch.test.cjs` drives
+ * the admit half from `git check-ref-format --branch` AS THE ORACLE, so git
+ * decides what must be admitted and this comment cannot quietly stop being true.
+ *
+ * Total over any input; never throws. Answering `false` is not an error — it is
+ * the resolver's cue to fall THROUGH to the next tier of the ladder, which is
+ * the behaviour a project with no override already gets.
+ */
+function isPlausibleBranchRef(value) {
+    if (typeof value !== 'string')
+        return false;
+    if (value === '' || value.length > MAX_REF_LENGTH)
+        return false;
+    if (OPTION_SHAPED.test(value))
+        return false;
+    if (FORBIDDEN_REF_CHARS.test(value))
+        return false;
+    for (const bad of FORBIDDEN_REF_SEQUENCES) {
+        if (value.includes(bad))
+            return false;
+    }
+    if (value.startsWith('/') || value.endsWith('/') || value.endsWith('.'))
+        return false;
+    // No path component may be empty, begin with `.`, or end with `.lock`.
+    for (const part of value.split('/')) {
+        if (part === '' || part.startsWith('.') || part.endsWith('.lock'))
+            return false;
+    }
+    // git's branch shorthand refuses this one by name, so this resolver does too.
+    if (value === 'HEAD')
+        return false;
+    return true;
+}
+/**
+ * WHAT A CALLER SAYS WHEN THE OVERRIDE IS REFUSED. One sentence, exported, for
+ * every channel — three call sites state it and none of them spells it.
+ *
+ * A second spelling of this sentence would be a second definition of what the
+ * mechanism did. The `check vault.audit` notes and the `check ship.practices`
+ * message carry these exact bytes.
+ *
+ * The reason carries NO copy of the refused value: the value is client-supplied
+ * and one of its shapes is an absolute filesystem path, so echoing it back onto
+ * an agent-readable surface would trade an injection for a disclosure (CR-03).
+ */
+exports.BASE_BRANCH_REFUSED_REASON = 'the configured git.base_branch is not a name git could resolve as a branch, so it was REJECTED ' +
+    'and the base-branch ladder continued without it. A value beginning with "-" is an option to git ' +
+    'rather than a revision, and options such as --output= make git create and truncate the file they ' +
+    'name; every other rule applied here is git\'s own ref-name grammar, so a name git itself would ' +
+    'refuse is refused too. The refused value is deliberately not repeated: it is client-supplied, ' +
+    'and one of its shapes is a filesystem path.';
 /**
  * Safely look up `git.base_branch` from the project's config.json.
  * Returns the configured value (a non-empty, non-null string) or null.
@@ -153,33 +249,63 @@ function tryLocalBranch(cwd, execGit) {
     }
 }
 /**
- * Resolve the default/base branch for the repository at `cwd`.
+ * Resolve the default/base branch for the repository at `cwd`, and REPORT a
+ * refused config override rather than swallowing it.
  *
- * Consults the full precedence ladder and always returns a non-empty string.
+ * Consults the full precedence ladder and always returns a non-empty branch.
  * Never throws.
+ *
+ * ONLY TIER 1 IS SHAPE-CHECKED, and that is the whole point. Tier 1 is the one
+ * value that comes from a file a cloned repository can carry; tiers 2-4 are
+ * git's own answers about its own refs, and putting them through the same
+ * allowlist would silently demote a legitimate branch whose name this pattern
+ * happens not to describe — trading a closed threat for a new silent failure in
+ * the one function whose job is to stop guessing.
  */
-function resolveBaseBranch(cwd, deps) {
+function resolveBaseBranchResult(cwd, deps) {
     const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     // Derive .planning dir relative to cwd (mirrors planningDir() in planning-workspace.cjs)
     const planningDir = node_path_1.default.join(cwd, '.planning');
-    // 1. Config override
+    // 1. Config override — the only untrusted tier, so the only checked one.
     const configured = readConfigBaseBranch(planningDir, deps);
-    if (configured)
-        return configured;
+    let configRejected = null;
+    if (configured) {
+        if (isPlausibleBranchRef(configured))
+            return { branch: configured, configRejected: null };
+        configRejected = { reason: exports.BASE_BRANCH_REFUSED_REASON };
+    }
     // 2. symbolic-ref (fast, no network)
     const symref = trySymbolicRef(cwd, execGit);
     if (symref)
-        return symref;
+        return { branch: symref, configRejected };
     // 3. git remote show origin (authoritative when origin/HEAD unset)
     const remoteShow = tryRemoteShow(cwd, execGit);
     if (remoteShow)
-        return remoteShow;
+        return { branch: remoteShow, configRejected };
     // 4. Local branch existence
     const local = tryLocalBranch(cwd, execGit);
     if (local)
-        return local;
+        return { branch: local, configRejected };
     // 5. Last-resort default
-    return 'main';
+    return { branch: 'main', configRejected };
+}
+/**
+ * Resolve the default/base branch for the repository at `cwd`.
+ *
+ * Consults the full precedence ladder and always returns a non-empty string.
+ * Never throws.
+ *
+ * The bare-string form. A consumer that computes a range and has a channel to
+ * speak on takes `resolveBaseBranchResult` instead and states the refusal
+ * (`vault-audit.cts`, the blocking audit gate, and `cmdShipPractices`, the
+ * ship:pre check): a gate that ran over a range the project never configured
+ * and said nothing would report success on the wrong input. This form stays
+ * for callers with nowhere to put a sentence, such as `cmdGitBaseBranch`,
+ * whose contract is one branch name on stdout. Either form refuses an
+ * option-shaped override.
+ */
+function resolveBaseBranch(cwd, deps) {
+    return resolveBaseBranchResult(cwd, deps).branch;
 }
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the