@pareto4/pp-core 1.13.0 → 1.18.0

package/pp-core/bin/lib/discovery-vault-check.cjs

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Discovery vault-context check (PBI 75336).
+ *
+ * Each Discovery session selects the client vault documents that bear on its
+ * topics from the vault's own `INDEX.md` (falling back to the engine-written
+ * `SUMMARY.md`), and records the selection in a `## Vault Context` section of
+ * `.planning/discovery/session-NN.md` — one line per document, naming what was
+ * selected and why. This module checks that record at session close:
+ *
+ *   - the section exists and names the index the selection used;
+ *   - every entry is one well-formed line (`- `<path>` — <why>`, or
+ *     `- (none) — <why>` when nothing was selected);
+ *   - every selected document was USED: cited `[vault: <path>]` somewhere in
+ *     the session notes, or marked `— not used: <reason>` on its own line.
+ *
+ * The selection itself is the facilitator's judgement and is not re-derived
+ * here; what is checked is that the record exists, is complete, and that what
+ * was loaded either reached the notes or was explicitly set aside.
+ *
+ * Parsing: the entry head grammar (prefix, closing backtick, separator) and the
+ * vault-path safety rule belong to the vault-index leaf (`src/vault-index.cts`,
+ * D-06/D-07), shared with the INDEX.md parser; only the tail grammar — the
+ * `(none)` entry, `why` and the `— not used:` mark — lives here.
+ *
+ * Content-free contract (the T-02-05 precedent): output names the session
+ * file, vault paths, structured reasons and counts — never note contents.
+ *
+ * Traversal: the only argument is a session NUMBER, resolved against the fixed
+ * convention path `.planning/discovery/session-NN.md`. No caller string is
+ * ever joined into a path (the T-02-08 precedent).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// The entry head split and the vault-path rule are the vault-index leaf's
+// (D-06/D-07). The leaf imports nothing, so this cannot close a cycle.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndexLeaf = require("./vault-index.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const SECTION_HEADING = '## Vault Context';
+const INDEX_PREFIX = 'Index: ';
+/**
+ * `INDEX.md` — the vault-owned index (preferred). `SUMMARY.md` — the
+ * engine-written fallback when the vault ships no `INDEX.md`. `none` — no
+ * cache index at all, so nothing could be selected.
+ */
+const INDEX_VALUES = Object.freeze(['INDEX.md', 'SUMMARY.md', 'none']);
+// Discovery's tail grammar, built on the leaf's separator (one spelling in src/).
+// No trailing space: section lines are trimEnd()-ed, so a mark with an empty
+// reason must still be recognised as a mark (and refused), not read as `why`.
+const NOT_USED_MARKER = vaultIndexLeaf.VAULT_ENTRY_SEPARATOR + 'not used:';
+const NONE_ENTRY_PREFIX = '- (none)' + vaultIndexLeaf.VAULT_ENTRY_SEPARATOR;
+const SESSION_MIN = 1;
+const SESSION_MAX = 13;
+const USAGE = 'Usage: pp-tools discovery vault-check <session 1-13>';
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+/** The `## Vault Context` section's lines (with 1-based file line numbers), or null. */
+function extractSection(content) {
+    const all = content.split(/\r?\n/);
+    const start = all.findIndex((l) => l.trimEnd() === SECTION_HEADING);
+    if (start === -1)
+        return null;
+    const out = [];
+    for (let i = start + 1; i < all.length; i += 1) {
+        if (/^#{1,2} /.test(all[i]))
+            break;
+        out.push({ n: i + 1, text: all[i].trimEnd() });
+    }
+    return out;
+}
+/** Parse one entry line. Returns the entry, or a violation for the line. */
+function parseEntry(n, text) {
+    if (text.startsWith(NONE_ENTRY_PREFIX)) {
+        const why = text.slice(NONE_ENTRY_PREFIX.length).trim();
+        return why === '' ? { reason: 'entry_malformed', line: n } : { line: n, path: null, notUsed: false };
+    }
+    const head = vaultIndexLeaf.splitVaultEntryLine(text);
+    if (head === null || 'malformed' in head)
+        return { reason: 'entry_malformed', line: n };
+    const p = head.path;
+    // The leaf's `rest` starts AFTER the separator, but the not-used marker
+    // begins with that same separator: a remainder that opens `not used:` is a
+    // mark with an empty `why`, and must stay one. So the tail is searched with
+    // the separator re-joined in front, exactly as before the split moved.
+    const sep = vaultIndexLeaf.VAULT_ENTRY_SEPARATOR;
+    const rest = sep + head.rest;
+    const notUsedAt = rest.indexOf(NOT_USED_MARKER);
+    const why = (notUsedAt === -1 ? rest.slice(sep.length) : rest.slice(sep.length, notUsedAt)).trim();
+    if (why === '')
+        return { reason: 'entry_malformed', line: n };
+    if (notUsedAt !== -1 && rest.slice(notUsedAt + NOT_USED_MARKER.length).trim() === '') {
+        return { reason: 'entry_malformed', line: n };
+    }
+    if (!vaultIndexLeaf.isSafeVaultPath(p))
+        return { reason: 'path_unsafe', line: n, path: p };
+    return { line: n, path: p, notUsed: notUsedAt !== -1 };
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+/**
+ * Check one session file's `## Vault Context` record. Pure over `content`.
+ *
+ * A citation counts only OUTSIDE the section: the record naming a path is not
+ * evidence that the path was used.
+ */
+function checkVaultContext(content) {
+    const violations = [];
+    const section = extractSection(content);
+    if (section === null) {
+        return { ok: false, index: null, documents: 0, cited: 0, not_used: 0, violations: [{ reason: 'section_missing' }] };
+    }
+    let index = null;
+    const entries = [];
+    for (const { n, text } of section) {
+        if (text.trim() === '')
+            continue;
+        if (text.startsWith(INDEX_PREFIX)) {
+            const value = text.slice(INDEX_PREFIX.length).trim();
+            if (!INDEX_VALUES.includes(value))
+                violations.push({ reason: 'index_invalid', line: n });
+            else
+                index = value;
+            continue;
+        }
+        const parsed = parseEntry(n, text);
+        if ('reason' in parsed)
+            violations.push(parsed);
+        else
+            entries.push(parsed);
+    }
+    if (index === null && !violations.some((v) => v.reason === 'index_invalid')) {
+        violations.push({ reason: 'index_line_missing' });
+    }
+    if (entries.length === 0 && !violations.some((v) => v.reason === 'entry_malformed' || v.reason === 'path_unsafe')) {
+        violations.push({ reason: 'no_entries' });
+    }
+    const docs = entries.filter((e) => e.path !== null);
+    const nones = entries.filter((e) => e.path === null);
+    if (nones.length > 0 && docs.length > 0) {
+        violations.push({ reason: 'none_mixed', line: nones[0].line });
+    }
+    // Citations are searched in the file with the section's own lines removed.
+    const sectionLines = new Set(section.map((s) => s.n));
+    const notes = content
+        .split(/\r?\n/)
+        .filter((_, i) => !sectionLines.has(i + 1))
+        .join('\n');
+    let cited = 0;
+    let notUsed = 0;
+    for (const doc of docs) {
+        const isCited = notes.includes(`[vault: ${doc.path}]`);
+        if (isCited)
+            cited += 1;
+        if (doc.notUsed)
+            notUsed += 1;
+        if (!isCited && !doc.notUsed) {
+            violations.push({ reason: 'document_unused', line: doc.line, path: doc.path });
+        }
+    }
+    return { ok: violations.length === 0, index, documents: docs.length, cited, not_used: notUsed, violations };
+}
+/** Parse the session argument: a bare integer 1–13, leading zeros allowed (`03` is session 3). */
+function parseSessionArg(raw) {
+    if (typeof raw !== 'string' || !/^\d{1,3}$/.test(raw))
+        return null;
+    const n = Number(raw);
+    return n >= SESSION_MIN && n <= SESSION_MAX ? n : null;
+}
+function sessionFileRel(n) {
+    return `${DISCOVERY_DIR}/session-${String(n).padStart(2, '0')}.md`;
+}
+/** Check the record of session `n` in the project at `cwd`. */
+function checkSessionVaultContext(cwd, n) {
+    const rel = sessionFileRel(n);
+    const abs = node_path_1.default.join(cwd, rel);
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return {
+            ok: false, session: n, file: rel, index: null, documents: 0, cited: 0, not_used: 0,
+            violations: [{ reason: 'session_file_missing' }],
+        };
+    }
+    return { session: n, file: rel, ...checkVaultContext(content) };
+}
+function formatViolation(v) {
+    const where = v.line !== undefined ? `line ${v.line}: ` : '';
+    // The path is facilitator-written text echoed to a terminal: it goes through
+    // the leaf's path display (D-27, T-14-04; 14-REVIEW WR-02), so a control or
+    // bidi character in a refused path is shown as an escape, never emitted raw,
+    // and a path is never echoed under a plausible different name.
+    const what = v.path !== undefined ? ` (${vaultIndexLeaf.displayVaultPath(v.path)})` : '';
+    return `  - ${where}${v.reason}${what}`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools discovery vault-check <session>` (dotted form
+ * `pp-tools query discovery.vault-check <session>`).
+ *
+ * Exit semantics: any violation exits non-zero via
+ * `ERROR_REASON.DISCOVERY_VAULT_CHECK_FAILED`, naming each by line, reason and
+ * vault path. The payload is emitted on stdout first on the failure path too,
+ * so the counts survive alongside the error.
+ */
+function cmdDiscoveryVaultCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'vault-check', <session>].
+    const rest = args.slice(2);
+    const n = rest.length === 1 ? parseSessionArg(rest[0]) : null;
+    if (n === null) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    const result = checkSessionVaultContext(cwd, n);
+    const payload = {
+        ok: result.ok,
+        session: result.session,
+        file: result.file,
+        index: result.index,
+        documents: result.documents,
+        cited: result.cited,
+        not_used: result.not_used,
+    };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        error(`discovery vault-check: ${result.violations.length} violation(s) in ${result.file}:\n` +
+            result.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_VAULT_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    output(payload, raw);
+}
+module.exports = {
+    SECTION_HEADING,
+    INDEX_VALUES,
+    checkVaultContext,
+    checkSessionVaultContext,
+    parseSessionArg,
+    cmdDiscoveryVaultCheck,
+};

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

@@ -216,24 +216,6 @@ 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) {
@@ -256,25 +238,6 @@ 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);
     }
@@ -427,7 +390,7 @@ function parseMustHavesBlock(content, blockName) {
 }
 // ─── Frontmatter CRUD commands ────────────────────────────────────────────────
 const FRONTMATTER_SCHEMAS = {
-    plan: { required: ['phase', 'plan', 'title', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+    plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
     summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
     verification: { required: ['phase', 'verified', 'status', 'score'] },
 };

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

@@ -83,7 +83,7 @@ const MAX_REF_LENGTH = 255;
  * 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
+ * is not asserted here in prose — `tests/vault-review.security.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.
  *
@@ -118,11 +118,11 @@ function isPlausibleBranchRef(value) {
 }
 /**
  * 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.
+ * every channel — a caller states it and never 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.
+ * mechanism did, so every channel that states the refusal carries 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
@@ -295,14 +295,13 @@ function resolveBaseBranchResult(cwd, deps) {
  * 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.
+ * The bare-string form. A consumer that computes a range takes
+ * `resolveBaseBranchResult` instead and states the refusal (W16): a gate that
+ * refused in silence would run over a range the project never configured and
+ * report success on it. What remains here is `cmdGitBaseBranch`, whose entire
+ * contract is one branch name on stdout and which therefore genuinely has
+ * nowhere to put a sentence. A new caller reaching for this form should ask
+ * whether that is true of it as well; if it has a channel, it owes the operator the reason.
  */
 function resolveBaseBranch(cwd, deps) {
     return resolveBaseBranchResult(cwd, deps).branch;

package/pp-core/bin/lib/git-provider.cjs

@@ -14,9 +14,9 @@
  * provider, what environment a clone needs, and whether a host CLI (`glab`)
  * may be spawned at all. It imports node builtins plus `./org-profile.cjs` —
  * still never `./vault.cjs`, `./vault-coordinates.cjs`, `./io.cjs` or
- * `./shell-command-projection.cjs` — so that both `src/vault.cts` and
- * `src/vault-write-back.cts` can import it (since 30-02 and 30-03) without
- * forming a require cycle in the CommonJS graph `require()` loads.
+ * `./shell-command-projection.cjs` — so that `src/vault.cts`, the vault write
+ * path and the other vault modules can import it without forming a require
+ * cycle in the CommonJS graph `require()` loads.
  * `./org-profile.cjs` is the one exception: it is itself a zero-import leaf
  * (node builtins only, see its own header), so importing it here creates no
  * load-time cycle even though it lazily requires this module back at
@@ -43,12 +43,12 @@ const node_path_1 = __importDefault(require("node:path"));
 const org_profile_cjs_1 = require("./org-profile.cjs");
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** The complete, ordered set of supported provider ids. */
-exports.PROVIDERS = Object.freeze(['gitlab', 'azure']);
+exports.PROVIDERS = Object.freeze(['gitlab', 'azure', 'github']);
 /**
  * Every project that has never heard of this phase resolves to this provider
  * (PROV-04): an absent config key is the normal case, not an error.
  */
-exports.DEFAULT_PROVIDER = 'gitlab';
+exports.DEFAULT_PROVIDER = 'github';
 /** The dotted `.planning/config.json` key that selects the provider. */
 exports.PROVIDER_CONFIG_KEY = 'vault.provider';
 // ─── normalizeProvider ───────────────────────────────────────────────────────
@@ -176,9 +176,8 @@ const compiledLiteralCloneTargetPatterns = exports.LITERAL_CLONE_TARGET_PATTERNS
  * absolute path, a scheme-qualified URL, or scp-style `user@host:path` —
  * rather than a `group/project` slug that must be composed onto a host.
  *
- * This is now the SINGLE definition. `src/vault.cts` and
- * `src/vault-write-back.cts` import it from here (30-02, 30-03) rather than
- * each keeping a copy — a read/write divergence in this predicate was defect
+ * This is now the SINGLE definition. `src/vault.cts` imports it from here
+ * (30-02) rather than keeping a copy — a read/write divergence in this predicate was defect
  * P-1 in Phase 29 (the write path used the value verbatim while the read path
  * always composed a URL, so a slug broke writing and a path broke reading).
  *
@@ -244,8 +243,8 @@ function composeCloneTarget(provider, repo, host) {
         }
         return { url, warnings: [] };
     }
-    // gitlab (and, structurally, any future provider that composes the same
-    // shape) — byte-identical to the template this replaces.
+    // gitlab and github compose the same `{host}/{slug}.git` shape —
+    // byte-identical to the template this replaces.
     return { url: `https://${host}/${trimmed}.git`, warnings: [] };
 }
 // ─── cloneEnv ────────────────────────────────────────────────────────────────

package/pp-core/bin/lib/init-command-router.cjs

@@ -30,22 +30,19 @@ function routeInitCommand({ init, args, cwd, raw, error }) {
         unknownMessage: (_subcommand, available) => `Unknown init workflow: ${_subcommand}\nAvailable: ${available.join(', ')}`,
         handlers: {
             'execute-phase': () => {
-                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tier'], ['validate', 'tdd']);
-                init.cmdInitExecutePhase(cwd, args[2], raw, { validate: namedArgs['validate'], tdd: namedArgs['tdd'], tier: namedArgs['tier'] });
+                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['validate', 'tdd']);
+                init.cmdInitExecutePhase(cwd, args[2], raw, { validate: namedArgs['validate'], tdd: namedArgs['tdd'] });
             },
             'plan-phase': () => {
-                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['granularity', 'tier'], ['validate', 'tdd']);
-                init.cmdInitPlanPhase(cwd, args[2], raw, { validate: namedArgs['validate'], tdd: namedArgs['tdd'], granularity: namedArgs['granularity'], tier: namedArgs['tier'] });
+                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['granularity'], ['validate', 'tdd']);
+                init.cmdInitPlanPhase(cwd, args[2], raw, { validate: namedArgs['validate'], tdd: namedArgs['tdd'], granularity: namedArgs['granularity'] });
             },
             'new-project': () => init.cmdInitNewProject(cwd, raw),
             'new-milestone': () => init.cmdInitNewMilestone(cwd, raw),
             quick: () => init.cmdInitQuick(cwd, args.slice(2).join(' '), raw),
             'ingest-docs': () => init.cmdInitIngestDocs(cwd, raw),
             resume: () => init.cmdInitResume(cwd, raw),
-            'verify-work': () => {
-                const namedArgs = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tier'], []);
-                init.cmdInitVerifyWork(cwd, args[2], raw, { tier: namedArgs['tier'] });
-            },
+            'verify-work': () => init.cmdInitVerifyWork(cwd, args[2], raw),
             'phase-op': () => init.cmdInitPhaseOp(cwd, args[2], raw),
             todos: () => init.cmdInitTodos(cwd, args[2], raw),
             'milestone-op': () => init.cmdInitMilestoneOp(cwd, raw),