@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/gap-checker.cjs

@@ -0,0 +1,260 @@
+"use strict";
+/**
+ * Post-planning gap analysis (#2493).
+ *
+ * Reads REQUIREMENTS.md (planning-root) and CONTEXT.md (per-phase) and compares
+ * each REQ-ID and D-ID against the concatenated text of all PLAN.md files in
+ * the phase directory. Emits a unified `Source | Item | Status` report.
+ *
+ * Gated on workflow.post_planning_gaps (default true). When false, returns
+ * { enabled: false } and does not scan.
+ *
+ * Coverage detection uses word-boundary regex matching to avoid false positives
+ * (REQ-1 must not match REQ-10).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/gap-checker.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict types are added.
+ */
+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 } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseId = require("./phase-id.cjs");
+const { escapeRegex } = phaseId;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningPaths, planningDir, findContextMdIn } = planningWorkspace;
+const decisions_cjs_1 = require("./decisions.cjs");
+/**
+ * Parse REQ-IDs from REQUIREMENTS.md content.
+ *
+ * Supports both checkbox (`- [ ] **REQ-NN** ...`) and traceability table
+ * (`| REQ-NN | ... |`) formats.
+ */
+function parseRequirements(reqMd) {
+    if (!reqMd || typeof reqMd !== 'string')
+        return [];
+    const out = [];
+    const seen = new Set();
+    // Prefix-agnostic ID format: REQ-01, TST-01, BACK-07, INSP-04, etc.
+    const ID_PATTERN = '[A-Z][A-Z0-9]*-[A-Za-z0-9_-]+';
+    const checkboxRe = new RegExp(`^\\s*-\\s*\\[[x ]\\]\\s*\\*\\*(${ID_PATTERN})\\*\\*\\s*(.*)$`, 'gm');
+    let cm = checkboxRe.exec(reqMd);
+    while (cm !== null) {
+        const id = cm[1];
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push({ id, text: (cm[2] || '').trim() });
+        }
+        cm = checkboxRe.exec(reqMd);
+    }
+    const tableFirstCellRe = new RegExp(`^\\s*\\|\\s*(${ID_PATTERN})\\s*\\|`);
+    const separatorRowRe = /^\s*\|[\s:|-]+\|\s*$/;
+    const lines = reqMd.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (!line.includes('|'))
+            continue;
+        // Skip markdown table separator rows and header rows immediately preceding them.
+        if (separatorRowRe.test(line))
+            continue;
+        if (i + 1 < lines.length && separatorRowRe.test(lines[i + 1]))
+            continue;
+        const tm = tableFirstCellRe.exec(line);
+        if (!tm)
+            continue;
+        const id = tm[1];
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push({ id, text: '' });
+        }
+    }
+    return out;
+}
+function detectCoverage(items, planText) {
+    return items.map(it => {
+        const re = new RegExp('\\b' + escapeRegex(it.id) + '\\b');
+        return {
+            source: it.source,
+            item: it.id,
+            status: re.test(planText) ? 'Covered' : 'Not covered',
+        };
+    });
+}
+function naturalKey(s) {
+    return String(s).replace(/(\d+)/g, (_, n) => n.padStart(8, '0'));
+}
+function sortRows(rows) {
+    const sourceOrder = { 'REQUIREMENTS.md': 0, 'CONTEXT.md': 1 };
+    return rows.slice().sort((a, b) => {
+        const so = (sourceOrder[a.source] ?? 99) - (sourceOrder[b.source] ?? 99);
+        if (so !== 0)
+            return so;
+        return naturalKey(a.item).localeCompare(naturalKey(b.item));
+    });
+}
+function formatGapTable(rows) {
+    if (rows.length === 0) {
+        return '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n';
+    }
+    const header = '| Source | Item | Status |\n|--------|------|--------|';
+    const body = rows.map(r => {
+        const tick = r.status === 'Covered' ? '✓ Covered'
+            : r.status === 'Missing from REQUIREMENTS.md' ? '⚠ Missing from REQUIREMENTS.md'
+                : '✗ Not covered';
+        return `| ${r.source} | ${r.item} | ${tick} |`;
+    }).join('\n');
+    return `## Post-Planning Gap Analysis\n\n${header}\n${body}\n`;
+}
+function readGate(cwd) {
+    const cfgPath = node_path_1.default.join(planningDir(cwd), 'config.json');
+    try {
+        const raw = JSON.parse(node_fs_1.default.readFileSync(cfgPath, 'utf-8'));
+        if (raw && typeof raw === 'object' && 'workflow' in raw) {
+            const wf = raw['workflow'];
+            if (wf && typeof wf === 'object' && 'post_planning_gaps' in wf) {
+                const val = wf['post_planning_gaps'];
+                if (typeof val === 'boolean')
+                    return val;
+            }
+        }
+    }
+    catch { /* fall through */ }
+    return true;
+}
+/**
+ * Normalize a raw `--phase-req-ids` argument into the scoping signal used by
+ * runGapAnalysis (#447). Mirrors §13's null/TBD skip semantics.
+ *
+ *   undefined           → flag absent: compare the whole REQUIREMENTS.md (back-compat)
+ *   null | '' | TBD     → no requirements mapped to this phase: skip the comparison
+ *   "REQ-01,REQ-02"     → restrict the comparison to these IDs
+ *
+ * Tolerates JSON-array-ish input (`["REQ-01","REQ-02"]`) since callers may pass
+ * the roadmap value through verbatim.
+ */
+function normalizePhaseReqIds(rawVal) {
+    if (rawVal === undefined)
+        return undefined;
+    if (rawVal === null)
+        return null;
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const v = String(rawVal).replace(/["'[\]()]/g, '').trim();
+    if (v === '' || /^(null|tbd|none)$/i.test(v))
+        return null;
+    // Tolerate comma-, space-, or newline-separated lists (callers may pass the
+    // roadmap value verbatim, whose serialization is not guaranteed).
+    const ids = v.split(/[\s,]+/).map(s => s.trim()).filter(Boolean);
+    return ids.length === 0 ? null : ids;
+}
+function runGapAnalysis(cwd, phaseDir, options = {}) {
+    const phaseReqIds = normalizePhaseReqIds(options.phaseReqIds);
+    if (!readGate(cwd)) {
+        return {
+            enabled: false,
+            rows: [],
+            table: '',
+            summary: 'workflow.post_planning_gaps disabled — skipping post-planning gap analysis',
+            counts: { total: 0, covered: 0, uncovered: 0 },
+        };
+    }
+    const absPhaseDir = node_path_1.default.isAbsolute(phaseDir) ? phaseDir : node_path_1.default.join(cwd, phaseDir);
+    const reqPath = planningPaths(cwd).requirements;
+    const reqMd = node_fs_1.default.existsSync(reqPath) ? node_fs_1.default.readFileSync(reqPath, 'utf-8') : '';
+    let reqItems = parseRequirements(reqMd).map(r => ({ ...r, source: 'REQUIREMENTS.md' }));
+    // Scope the requirements comparison to the phase's mapped REQ-IDs (#447).
+    // A phase that maps no requirements (phase_req_ids null/TBD) must not report
+    // every unrelated project REQ-ID as a gap — mirror §13's skip behavior.
+    // CONTEXT.md decisions (below) are always in scope regardless.
+    let ghostReqIds = [];
+    if (phaseReqIds === null) {
+        reqItems = [];
+    }
+    else if (Array.isArray(phaseReqIds)) {
+        const wanted = new Set(phaseReqIds);
+        const foundIds = new Set(reqItems.map(r => r.id));
+        reqItems = reqItems.filter(r => wanted.has(r.id));
+        ghostReqIds = phaseReqIds.filter(id => !foundIds.has(id));
+    }
+    // Read the phase directory once; reuse the listing for both context detection
+    // and plan-file enumeration (avoids redundant readdirSync calls).
+    let phaseDirFiles = [];
+    try {
+        if (node_fs_1.default.existsSync(absPhaseDir))
+            phaseDirFiles = node_fs_1.default.readdirSync(absPhaseDir);
+    }
+    catch { /* unreadable */ }
+    const ctxFile = findContextMdIn(phaseDirFiles);
+    const ctxPath = ctxFile ? node_path_1.default.join(absPhaseDir, ctxFile) : null;
+    const ctxMd = ctxPath ? node_fs_1.default.readFileSync(ctxPath, 'utf-8') : '';
+    const dItems = (0, decisions_cjs_1.parseDecisions)(ctxMd).map(d => ({ ...d, source: 'CONTEXT.md' }));
+    const items = [...reqItems, ...dItems];
+    let planText = '';
+    try {
+        if (phaseDirFiles.length > 0) {
+            const files = phaseDirFiles.filter(f => /-PLAN\.md$/.test(f));
+            planText = files.map(f => {
+                try {
+                    return node_fs_1.default.readFileSync(node_path_1.default.join(absPhaseDir, f), 'utf-8');
+                }
+                catch {
+                    return '';
+                }
+            }).join('\n');
+        }
+    }
+    catch { /* unreadable */ }
+    if (items.length === 0) {
+        return {
+            enabled: true,
+            rows: [],
+            table: '## Post-Planning Gap Analysis\n\nNo requirements or decisions to check.\n',
+            summary: 'no requirements or decisions to check',
+            counts: { total: 0, covered: 0, uncovered: 0 },
+        };
+    }
+    const rows = sortRows([
+        ...detectCoverage(items, planText),
+        ...ghostReqIds.map(id => ({ source: 'REQUIREMENTS.md', item: id, status: 'Missing from REQUIREMENTS.md' })),
+    ]);
+    const covered = rows.filter(r => r.status === 'Covered').length;
+    const uncovered = rows.length - covered;
+    const summary = uncovered === 0
+        ? `✓ All ${rows.length} items covered by plans`
+        : `⚠ ${uncovered} of ${rows.length} items not covered by any plan`;
+    return {
+        enabled: true,
+        rows,
+        table: formatGapTable(rows) + '\n' + summary + '\n',
+        summary,
+        counts: { total: rows.length, covered, uncovered },
+    };
+}
+function cmdGapAnalysis(cwd, args, raw) {
+    const idx = args.indexOf('--phase-dir');
+    if (idx === -1 || !args[idx + 1]) {
+        error('Usage: gap-analysis --phase-dir <path-to-phase-directory>');
+    }
+    const phaseDir = args[idx + 1];
+    // Optional --phase-req-ids scopes the requirements comparison (#447).
+    // Absent → compare the whole REQUIREMENTS.md (back-compat).
+    const reqIdx = args.indexOf('--phase-req-ids');
+    const phaseReqIds = reqIdx === -1 ? undefined : (args[reqIdx + 1] ?? '');
+    const result = runGapAnalysis(cwd, phaseDir, { phaseReqIds });
+    output(result, raw, result.table || result.summary);
+}
+module.exports = {
+    parseRequirements,
+    detectCoverage,
+    formatGapTable,
+    sortRows,
+    normalizePhaseReqIds,
+    runGapAnalysis,
+    cmdGapAnalysis,
+};

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

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Git Base-Branch Resolver — issue #1146.
+ *
+ * Single source of truth for detecting the repository's default branch.
+ * Replaces the duplicated per-workflow bash detection that only consulted
+ * `refs/remotes/origin/HEAD` then hardcoded `:-main`, which silently
+ * returned "main" for repos whose default branch is "master" whenever
+ * origin/HEAD was unset (git init + remote add / fetch without set-head /
+ * most CI checkouts / many worktrees).
+ *
+ * Precedence ladder (highest to lowest):
+ *   1. `git.base_branch` config override from .planning/config.json
+ *   2. `git symbolic-ref --short refs/remotes/origin/HEAD`  (fast, no network)
+ *   3. `git remote show origin` HEAD branch  ← AUTHORITATIVE; works when #2 unset
+ *   4. Local branch existence: "master" present + "main" absent → "master";
+ *      "main" present → "main"
+ *   5. "main"  (last-resort default)
+ *
+ * Every git subprocess is bounded with a timeout (≤ 30 s); on timeout/error
+ * the resolver degrades gracefully to the next tier — it never throws.
+ *
+ * Pure/testable: all I/O is injectable via the `deps` argument so unit
+ * tests can run without touching the real filesystem or spawning real git.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConfigBaseBranch = readConfigBaseBranch;
+exports.trySymbolicRef = trySymbolicRef;
+exports.tryRemoteShow = tryRemoteShow;
+exports.tryLocalBranch = tryLocalBranch;
+exports.resolveBaseBranch = resolveBaseBranch;
+exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
+exports.cmdGitBaseBranch = cmdGitBaseBranch;
+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 ──────────────────────────────────────────────────────────────────
+/**
+ * Safely look up `git.base_branch` from the project's config.json.
+ * Returns the configured value (a non-empty, non-null string) or null.
+ */
+function readConfigBaseBranch(planningDir, deps) {
+    const readFile = deps?.readFile ??
+        ((p) => { try {
+            return node_fs_1.default.readFileSync(p, 'utf8');
+        }
+        catch {
+            return null;
+        } });
+    const configPath = node_path_1.default.join(planningDir, 'config.json');
+    const raw = readFile(configPath);
+    if (!raw)
+        return null;
+    let cfg;
+    try {
+        cfg = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
+        return null;
+    const top = cfg;
+    // Support both "git.base_branch" (nested) and "base_branch" (flat legacy)
+    const gitSection = top.git;
+    if (gitSection && typeof gitSection === 'object' && !Array.isArray(gitSection)) {
+        const nested = gitSection.base_branch;
+        if (typeof nested === 'string' && nested.trim())
+            return nested.trim();
+    }
+    const flat = top.base_branch;
+    if (typeof flat === 'string' && flat.trim())
+        return flat.trim();
+    return null;
+}
+/**
+ * Try `git symbolic-ref --short refs/remotes/origin/HEAD` (no network).
+ * Strips the `origin/` prefix to return just the branch name.
+ * Returns null if unset or on error/timeout.
+ */
+function trySymbolicRef(cwd, execGit) {
+    try {
+        const r = execGit(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], { cwd, timeout: 5_000 });
+        if (r.exitCode !== 0 || !r.stdout)
+            return null;
+        // Output is e.g. "origin/main" — strip the prefix
+        const branch = r.stdout.trim().replace(/^origin\//, '');
+        return branch || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Try `git remote show origin` to read the HEAD branch.
+ * This is authoritative when origin/HEAD is unset locally.
+ * Requires network access but succeeds in the common CI case where
+ * origin/HEAD was never set after `git init && git remote add origin`.
+ *
+ * Parses the line:  `HEAD branch: <name>`
+ * Returns null on error, timeout, or if the output is malformed.
+ */
+function tryRemoteShow(cwd, execGit) {
+    try {
+        const r = execGit(['remote', 'show', 'origin'], { cwd, timeout: 15_000 });
+        if (r.exitCode !== 0 || !r.stdout)
+            return null;
+        // The line looks like: "  HEAD branch: master"
+        const m = r.stdout.match(/^\s*HEAD branch:\s*(\S+)\s*$/m);
+        if (!m)
+            return null;
+        const branch = m[1];
+        // git emits "(unknown)" when the remote is offline but the local cache
+        // resolved it; treat that as non-authoritative and fall through.
+        if (!branch || branch === '(unknown)')
+            return null;
+        return branch;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Detect local branch existence as a tie-breaker when no remote info is available.
+ *
+ * Rules:
+ *   - "master" present AND "main" absent → "master"
+ *   - "main" present → "main"
+ *   - Neither → null (fall through to default)
+ *
+ * Returns null on error/timeout.
+ */
+function tryLocalBranch(cwd, execGit) {
+    try {
+        const r = execGit(['branch', '--list', 'main', 'master'], { cwd, timeout: 5_000 });
+        if (r.exitCode !== 0 || !r.stdout)
+            return null;
+        // `git branch --list main master` outputs one line per matching branch
+        const lines = r.stdout.split('\n').map(l => l.trim().replace(/^\*\s*/, ''));
+        const hasMain = lines.includes('main');
+        const hasMaster = lines.includes('master');
+        if (hasMaster && !hasMain)
+            return 'master';
+        if (hasMain)
+            return 'main';
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the default/base branch for the repository at `cwd`.
+ *
+ * Consults the full precedence ladder and always returns a non-empty string.
+ * Never throws.
+ */
+function resolveBaseBranch(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
+    const configured = readConfigBaseBranch(planningDir, deps);
+    if (configured)
+        return configured;
+    // 2. symbolic-ref (fast, no network)
+    const symref = trySymbolicRef(cwd, execGit);
+    if (symref)
+        return symref;
+    // 3. git remote show origin (authoritative when origin/HEAD unset)
+    const remoteShow = tryRemoteShow(cwd, execGit);
+    if (remoteShow)
+        return remoteShow;
+    // 4. Local branch existence
+    const local = tryLocalBranch(cwd, execGit);
+    if (local)
+        return local;
+    // 5. Last-resort default
+    return 'main';
+}
+/**
+ * Detect whether `cwd` sits inside a git worktree, and if so, return the
+ * absolute path of the worktree root.
+ */
+function gitWorktreeInfoInternal(cwd) {
+    try {
+        const insideResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 5000 });
+        if (insideResult.exitCode !== 0) {
+            return { inside: false, worktreeRoot: null };
+        }
+        const insideStdout = String(insideResult.stdout || '').trim();
+        if (insideStdout !== 'true') {
+            return { inside: false, worktreeRoot: null };
+        }
+        const rootResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 });
+        if (rootResult.exitCode !== 0) {
+            return { inside: true, worktreeRoot: null };
+        }
+        const root = String(rootResult.stdout || '').trim();
+        return { inside: true, worktreeRoot: root || null };
+    }
+    catch {
+        return { inside: false, worktreeRoot: null };
+    }
+}
+// ─── CLI entry point ──────────────────────────────────────────────────────────
+/**
+ * CLI command: `gsd-tools git base-branch`
+ * Resolves the default branch and writes it to stdout (raw string, newline-terminated).
+ * Called by workflows via `gsd_run query git.base-branch`.
+ */
+function cmdGitBaseBranch(cwd, _args, deps) {
+    const branch = resolveBaseBranch(cwd, deps);
+    const write = deps?.write ?? ((s) => process.stdout.write(s));
+    write(branch + '\n');
+    return branch;
+}

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

@@ -0,0 +1,72 @@
+'use strict';
+/**
+ * Graphify command router — CLI subcommand dispatcher for `gsd-tools graphify`.
+ *
+ * ADR-959 (phase 4d-impl-2) pilot: first real capability command cutover.
+ * Extracted from the hardcoded `case 'graphify':` arm in gsd-tools.cjs.
+ * Behaviour is preserved byte-for-behaviour from the prior inline case;
+ * the dispatch path now flows: default → dispatchCapabilityCommand →
+ * require(graphify-command-router.cjs) → routeGraphifyCommand.
+ *
+ * Router signature: { args, cwd, raw, error } — identical to the 12 existing
+ * host routers. No new handler/arg convention; the capability registry
+ * discovers this router by name.
+ *
+ * Arg indexing (preserved exactly from the original case):
+ *   args[0] = 'graphify'  (family — matched by dispatchCapabilityCommand)
+ *   args[1] = subcommand  (query | status | diff | build)
+ *   args[2] = term (query) | 'snapshot' (build snapshot)
+ *   args.indexOf('--budget') + 1 = budget value
+ *
+ * Test seam: pass `_graphify` in the options object to inject a recording mock
+ * instead of the real graphify module. The `_`-prefix follows the repo's
+ * established seam convention (see other routers). Production callers omit it.
+ */
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const graphify = require("./graphify.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, ERROR_REASON } = io;
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeGraphifyCommand({ args, cwd, raw, error, _graphify }) {
+    const subcommand = args[1];
+    const g = _graphify ?? graphify;
+    if (subcommand === 'query') {
+        const term = args[2];
+        if (!term) {
+            error('Usage: gsd-tools graphify query <term>', ERROR_REASON.USAGE);
+            return;
+        }
+        const budgetIdx = args.indexOf('--budget');
+        let budget = null;
+        if (budgetIdx !== -1) {
+            const rawBudget = args[budgetIdx + 1];
+            if (rawBudget === undefined || Number.isNaN(parseInt(rawBudget, 10))) {
+                error('Usage: gsd-tools graphify query <term> [--budget <N>]', ERROR_REASON.USAGE);
+                return;
+            }
+            budget = parseInt(rawBudget, 10);
+        }
+        output(g.graphifyQuery(cwd, term, { budget }), raw);
+    }
+    else if (subcommand === 'status') {
+        output(g.graphifyStatus(cwd), raw);
+    }
+    else if (subcommand === 'diff') {
+        output(g.graphifyDiff(cwd), raw);
+    }
+    else if (subcommand === 'build') {
+        if (args[2] === 'snapshot') {
+            output(g.writeSnapshot(cwd), raw);
+        }
+        else {
+            output(g.graphifyBuild(cwd), raw);
+        }
+    }
+    else {
+        error('Unknown graphify subcommand. Available: build, query, status, diff', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}
+module.exports = {
+    routeGraphifyCommand,
+};