@pareto4/pp-core 1.5.0

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

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Template — Template selection and fill operations
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/template.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 ioMod = require("./io.cjs");
+const { output, error } = ioMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsMod = require("./core-utils.cjs");
+const { toPosixPath, generateSlugInternal } = coreUtilsMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { normalizePhaseName } = phaseIdMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { findPhaseInternal } = phaseLocatorMod;
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { reconstructFrontmatter } = frontmatter;
+// ─── cmdTemplateSelect ────────────────────────────────────────────────────────
+function cmdTemplateSelect(cwd, planPath, raw) {
+    if (!planPath) {
+        error('plan-path required');
+    }
+    try {
+        const fullPath = node_path_1.default.join(cwd, planPath);
+        const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
+        // Simple heuristics
+        const taskMatch = content.match(/###\s*Task\s*\d+/g) || [];
+        const taskCount = taskMatch.length;
+        const decisionMatch = content.match(/decision/gi) || [];
+        const hasDecisions = decisionMatch.length > 0;
+        // Count file mentions
+        const fileMentions = new Set();
+        const filePattern = /`([^`]+\.[a-zA-Z]+)`/g;
+        let m;
+        while ((m = filePattern.exec(content)) !== null) {
+            if (m[1].includes('/') && !m[1].startsWith('http')) {
+                fileMentions.add(m[1]);
+            }
+        }
+        const fileCount = fileMentions.size;
+        let template = 'templates/summary-standard.md';
+        let type = 'standard';
+        if (taskCount <= 2 && fileCount <= 3 && !hasDecisions) {
+            template = 'templates/summary-minimal.md';
+            type = 'minimal';
+        }
+        else if (hasDecisions || fileCount > 6 || taskCount > 5) {
+            template = 'templates/summary-complex.md';
+            type = 'complex';
+        }
+        const result = { template, type, taskCount, fileCount, hasDecisions };
+        output(result, raw, template);
+    }
+    catch (e) {
+        // Fallback to standard
+        output({ template: 'templates/summary-standard.md', type: 'standard', error: e.message }, raw, 'templates/summary-standard.md');
+    }
+}
+// ─── cmdTemplateFill ──────────────────────────────────────────────────────────
+function cmdTemplateFill(cwd, templateType, options, raw) {
+    if (!templateType) {
+        error('template type required: summary, plan, or verification');
+    }
+    if (!options.phase) {
+        error('--phase required');
+    }
+    const phaseInfo = findPhaseInternal(cwd, options.phase);
+    if (!phaseInfo || !phaseInfo.found) {
+        output({ error: 'Phase not found', phase: options.phase }, raw, undefined);
+        return;
+    }
+    const padded = normalizePhaseName(options.phase);
+    const today = new Date().toISOString().split('T')[0];
+    const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
+    const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
+    const phaseId = `${padded}-${phaseSlug}`;
+    const planNum = (options.plan || '01').padStart(2, '0');
+    const fields = options.fields || {};
+    let frontmatterObj;
+    let body;
+    let fileName;
+    switch (templateType) {
+        case 'summary': {
+            frontmatterObj = {
+                phase: phaseId,
+                plan: planNum,
+                subsystem: '[primary category]',
+                tags: [],
+                provides: [],
+                affects: [],
+                'tech-stack': { added: [], patterns: [] },
+                'key-files': { created: [], modified: [] },
+                'key-decisions': [],
+                'patterns-established': [],
+                duration: '[X]min',
+                completed: today,
+                ...fields,
+            };
+            body = [
+                `# Phase ${options.phase}: ${phaseName} Summary`,
+                '',
+                '**[Substantive one-liner describing outcome]**',
+                '',
+                '## Performance',
+                '- **Duration:** [time]',
+                '- **Tasks:** [count completed]',
+                '- **Files modified:** [count]',
+                '',
+                '## Accomplishments',
+                '- [Key outcome 1]',
+                '- [Key outcome 2]',
+                '',
+                '## Task Commits',
+                '1. **Task 1: [task name]** - `hash`',
+                '',
+                '## Files Created/Modified',
+                '- `path/to/file.ts` - What it does',
+                '',
+                '## Decisions & Deviations',
+                '[Key decisions or "None - followed plan as specified"]',
+                '',
+                '## Next Phase Readiness',
+                '[What\'s ready for next phase]',
+            ].join('\n');
+            fileName = `${padded}-${planNum}-SUMMARY.md`;
+            break;
+        }
+        case 'plan': {
+            const planType = options.type || 'execute';
+            const wave = parseInt(String(options.wave), 10) || 1;
+            frontmatterObj = {
+                phase: phaseId,
+                plan: planNum,
+                type: planType,
+                wave,
+                depends_on: [],
+                files_modified: [],
+                autonomous: true,
+                user_setup: [],
+                must_haves: { truths: [], artifacts: [], key_links: [] },
+                ...fields,
+            };
+            const planBase = planningDir(cwd);
+            const projectRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'PROJECT.md')));
+            const roadmapRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'ROADMAP.md')));
+            const stateRef = toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(planBase, 'STATE.md')));
+            body = [
+                `# Phase ${options.phase} Plan ${planNum}: [Title]`,
+                '',
+                '## Objective',
+                '- **What:** [What this plan builds]',
+                '- **Why:** [Why it matters for the phase goal]',
+                '- **Output:** [Concrete deliverable]',
+                '',
+                '## Context',
+                `@${projectRef}`,
+                `@${roadmapRef}`,
+                `@${stateRef}`,
+                '',
+                '## Tasks',
+                '',
+                '<task type="code">',
+                '  <name>[Task name]</name>',
+                '  <files>[file paths]</files>',
+                '  <action>[What to do]</action>',
+                '  <verify>[How to verify]</verify>',
+                '  <done>[Definition of done]</done>',
+                '</task>',
+                '',
+                '## Verification',
+                '[How to verify this plan achieved its objective]',
+                '',
+                '## Success Criteria',
+                '- [ ] [Criterion 1]',
+                '- [ ] [Criterion 2]',
+            ].join('\n');
+            fileName = `${padded}-${planNum}-PLAN.md`;
+            break;
+        }
+        case 'verification': {
+            frontmatterObj = {
+                phase: phaseId,
+                verified: new Date().toISOString(),
+                status: 'pending',
+                score: '0/0 must-haves verified',
+                ...fields,
+            };
+            body = [
+                `# Phase ${options.phase}: ${phaseName} — Verification`,
+                '',
+                '## Observable Truths',
+                '| # | Truth | Status | Evidence |',
+                '|---|-------|--------|----------|',
+                '| 1 | [Truth] | pending | |',
+                '',
+                '## Required Artifacts',
+                '| Artifact | Expected | Status | Details |',
+                '|----------|----------|--------|---------|',
+                '| [path] | [what] | pending | |',
+                '',
+                '## Key Link Verification',
+                '| From | To | Via | Status | Details |',
+                '|------|----|----|--------|---------|',
+                '| [source] | [target] | [connection] | pending | |',
+                '',
+                '## Requirements Coverage',
+                '| Requirement | Status | Blocking Issue |',
+                '|-------------|--------|----------------|',
+                '| [req] | pending | |',
+                '',
+                '## Result',
+                '[Pending verification]',
+            ].join('\n');
+            fileName = `${padded}-VERIFICATION.md`;
+            break;
+        }
+        default:
+            error(`Unknown template type: ${templateType}. Available: summary, plan, verification`);
+            return;
+    }
+    const fullContent = `---\n${reconstructFrontmatter(frontmatterObj)}\n---\n\n${body}\n`;
+    const outPath = node_path_1.default.join(cwd, phaseInfo.directory, fileName);
+    if (node_fs_1.default.existsSync(outPath)) {
+        output({ error: 'File already exists', path: toPosixPath(node_path_1.default.relative(cwd, outPath)) }, raw, undefined);
+        return;
+    }
+    (0, shell_command_projection_cjs_1.platformWriteSync)(outPath, fullContent);
+    const relPath = toPosixPath(node_path_1.default.relative(cwd, outPath));
+    output({ created: true, path: relPath, template: templateType }, raw, relPath);
+}
+module.exports = { cmdTemplateSelect, cmdTemplateFill };

package/pp-core/bin/lib/uat-predicate.cjs

@@ -0,0 +1,329 @@
+"use strict";
+/**
+ * UAT Predicate — Pure-computation UAT pass/fail evaluation
+ *
+ * Evaluates all *-UAT.md and *-VERIFICATION.md files in a phase directory and
+ * returns a typed report. Used by `phase uat-passed` to harden against the
+ * naive whole-file regex in cmdPhaseComplete which false-matches `result:` lines
+ * inside frontmatter, fenced code blocks, blockquotes, and HTML comments.
+ *
+ * Issue #247 — phase uat-passed predicate
+ *
+ * ADR-457 build-at-publish: compiled by tsc to gsd-core/bin/lib/uat-predicate.cjs.
+ */
+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 frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+// ─── Blocking state sets (documented for maintainability) ─────────────────────
+// UAT file frontmatter `status` values that indicate the file is not fully done
+const BLOCKING_UAT_FM_STATUSES = new Set([
+    'partial', 'diagnosed', 'pending', 'blocked', 'in_progress', 'failed',
+]);
+// UAT file frontmatter `result` values that indicate failure
+const BLOCKING_UAT_FM_RESULTS = new Set(['pending', 'blocked', 'failed']);
+// VERIFICATION file frontmatter `status` values that indicate passing
+const PASSING_VERIFICATION_STATUSES = new Set([
+    'complete', 'verified', 'passed', 'human_passed',
+]);
+// VERIFICATION file frontmatter `status` values that explicitly block
+const BLOCKING_VERIFICATION_FM_STATUSES = new Set([
+    'human_needed', 'gaps_found', 'pending', 'blocked', 'partial',
+    'failed', 'in_progress',
+]);
+// UAT test-item `result` values that count as passing
+const PASSING_RESULTS = new Set(['passed', 'pass']);
+// ─── stripFalsePositiveContexts ───────────────────────────────────────────────
+/**
+ * Remove contexts that can contain `result: ...` lines that are NOT real test results:
+ *   (a) leading frontmatter block at byte 0
+ *   (b) HTML comments (unterminated comments swallow to EOF — fail-closed)
+ *   (c) fenced code blocks (backtick and tilde, indented too) via CommonMark state machine
+ *   (d) blockquote lines
+ *
+ * Each step is a composable function (Kernighan's Law — independently testable).
+ * Returns surviving lines joined by '\n'. Robust to CRLF input.
+ */
+function stripFalsePositiveContexts(content) {
+    // Step (a): strip leading frontmatter block only at byte 0
+    let stripped = content.replace(/^---\r?\n[\s\S]*?\r?\n---[ \t]*(\r?\n|$)/, '');
+    // Step (b): remove HTML comments anywhere; unterminated comment swallows to EOF
+    stripped = stripped.replace(/<!--[\s\S]*?(?:-->|$)/g, '');
+    // Step (c): remove fenced code blocks via CommonMark-style state machine (handles CRLF + indented fences)
+    stripped = _stripFencedBlocks(stripped).text;
+    // Step (d): remove blockquote lines
+    stripped = stripped
+        .split('\n')
+        .filter(line => !/^\s*>/.test(line))
+        .join('\n');
+    return stripped;
+}
+/**
+ * CommonMark-style fenced-code-block stripper.
+ * Tracks the opening delimiter char and length so that a ~~~ line inside a
+ * ``` fence is correctly treated as fence content, not a closing delimiter.
+ *
+ * Opening rule: first delimiter line with char+len sets openFence.
+ * Closing rule: delimiter line with SAME char, run length >= openFence.len,
+ *   and NO trailing non-whitespace text closes the fence.
+ * All delimiter and content lines are dropped; non-fence lines are kept.
+ * Returns the kept text plus unterminatedFence:true if EOF inside a fence.
+ */
+function _stripFencedBlocks(content) {
+    const lines = content.split('\n');
+    const kept = [];
+    let openFence = null;
+    const delimRe = /^(\s*)(`{3,}|~{3,})(.*)$/;
+    for (const rawLine of lines) {
+        // Tolerate CRLF: strip trailing \r for matching, but we work on split-by-\n lines
+        // (the outer caller joined by \n already; we just handle a stray \r in the last char)
+        const line = rawLine.replace(/\r$/, '');
+        const m = delimRe.exec(line);
+        if (m) {
+            const char = m[2][0];
+            const len = m[2].length;
+            const trailing = m[3];
+            if (openFence === null) {
+                // Opening delimiter — drop this line and record the fence
+                openFence = { char, len };
+            }
+            else if (char === openFence.char && len >= openFence.len && /^\s*$/.test(trailing)) {
+                // Closing delimiter (same char, sufficient length, no trailing text) — drop and close
+                openFence = null;
+            }
+            // else: mismatched delimiter inside fence (e.g. ~~~ inside ```) — drop as content
+            continue; // delimiter lines are always dropped
+        }
+        if (openFence === null) {
+            kept.push(rawLine);
+        }
+        // Lines inside fence are dropped
+    }
+    return { text: kept.join('\n'), unterminatedFence: openFence !== null };
+}
+/**
+ * Analyse raw markdown for structural anomalies (unterminated fence / comment).
+ * Exported for unit-testability and used by evaluateUatPassed for per-file malformed detection.
+ *
+ * FIX C: properly balanced comments are stripped before checking for a dangling <!--,
+ * so an earlier closed comment does not mask a later unterminated one.
+ */
+function analyzeMarkdown(raw) {
+    // Detect an unterminated HTML comment via a paired scan: every `<!--` must
+    // have a following `-->`. Using indexOf (not a regex .replace of the comment
+    // token) avoids the js/incomplete-multi-character-sanitization pattern — and
+    // is exact: a closed earlier comment never masks a later unterminated one.
+    let unterminatedComment = false;
+    for (let i = 0;;) {
+        const open = raw.indexOf('<!--', i);
+        if (open === -1)
+            break;
+        const close = raw.indexOf('-->', open + 4);
+        if (close === -1) {
+            unterminatedComment = true;
+            break;
+        }
+        i = close + 3;
+    }
+    // Fence state machine gives the accurate unterminated-fence signal.
+    const { unterminatedFence } = _stripFencedBlocks(raw);
+    return { unterminatedFence, unterminatedComment };
+}
+// ─── parseUatResultItems ──────────────────────────────────────────────────────
+/**
+ * HEADING-BLOCK parser: scan the CLEANED body (after stripFalsePositiveContexts)
+ * for UAT test blocks.
+ *
+ * For each ### N. Name heading, the block spans until the next ### heading or EOF.
+ * Within each block, find a column-0 anchored result line (rejects indented YAML
+ * block-scalar bodies and inline/quoted fakes).
+ *
+ * - If a heading block has NO column-0 result line → emit result:'missing' (blocker).
+ * - Support bracketed [passed] and bare passed (#2273).
+ * - Returns ALL items (both passing and non-passing).
+ */
+function parseUatResultItems(cleanContent) {
+    const items = [];
+    // Find all ### N. Name headings (line-anchored)
+    const headingPattern = /^###\s*(\d+)\.\s*(.+)$/gm;
+    const headings = [];
+    let hMatch;
+    while ((hMatch = headingPattern.exec(cleanContent)) !== null) {
+        headings.push({
+            index: hMatch.index + hMatch[0].length,
+            test: parseInt(hMatch[1], 10),
+            name: hMatch[2].trim(),
+        });
+    }
+    for (let i = 0; i < headings.length; i++) {
+        const h = headings[i];
+        const blockStart = h.index;
+        // More precise: find next heading's position in the original string
+        // We'll slice from current heading end to the position just before next heading's "###"
+        const nextHeadingMatch = i + 1 < headings.length
+            ? cleanContent.lastIndexOf('\n###', headings[i + 1].index)
+            : -1;
+        const blockContent = nextHeadingMatch >= blockStart
+            ? cleanContent.slice(blockStart, nextHeadingMatch)
+            : cleanContent.slice(blockStart);
+        // Column-0 anchored result line: /^result:[ \t]*\[?([\w-]+)\]?/mi
+        // Uses [ \t]* (not \s*) so the captured value must sit on the SAME line as result:.
+        // A result: key with the value on a subsequent line yields no match → 'missing' (blocker).
+        const resultMatch = /^result:[ \t]*\[?([\w-]+)\]?/mi.exec(blockContent);
+        if (resultMatch) {
+            items.push({
+                test: h.test,
+                name: h.name,
+                result: resultMatch[1].toLowerCase(),
+            });
+        }
+        else {
+            // No column-0 result line → emit 'missing' (a non-passing state)
+            items.push({
+                test: h.test,
+                name: h.name,
+                result: 'missing',
+            });
+        }
+    }
+    return items;
+}
+// ─── evaluateUatPassed ────────────────────────────────────────────────────────
+/**
+ * Evaluate all UAT/VERIFICATION files in a phase directory.
+ * Returns a UatPassedReport with the locked, stable shape defined by the interface.
+ *
+ * FAIL-CLOSED: any absence/ambiguity/malformed input → NOT passed.
+ * Pass requires at least one real passing check AND no blockers.
+ */
+function evaluateUatPassed(phaseFullDir, opts) {
+    const requireVerification = opts?.policy?.requireVerification === true;
+    const blockers = [];
+    const checks = [];
+    const uatFiles = [];
+    const verificationFiles = [];
+    // Read the directory — if unreadable, treat as no files (fail-closed: no artifacts → not passed)
+    let dirEntries = [];
+    try {
+        dirEntries = node_fs_1.default.readdirSync(phaseFullDir);
+    }
+    catch {
+        // Unreadable dir — no_uat_artifacts:true, passed:false
+        const no_uat_artifacts = true;
+        if (requireVerification) {
+            blockers.push('policy: verification required but no passing *-VERIFICATION.md found');
+        }
+        return {
+            passed: false,
+            uat_files: [],
+            verification_files: [],
+            checks: [],
+            blockers,
+            no_uat_artifacts,
+            policy: { require_verification: requireVerification },
+        };
+    }
+    // Filter UAT and VERIFICATION files using the same filter as cmdPhaseComplete
+    const uatFileNames = dirEntries.filter(f => f.includes('-UAT') && f.endsWith('.md'));
+    const verFileNames = dirEntries.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'));
+    // ── Process UAT files ──────────────────────────────────────────────────────
+    for (const file of uatFileNames) {
+        uatFiles.push(file);
+        let raw = '';
+        try {
+            raw = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
+        }
+        catch {
+            blockers.push(`${file}: could not read file`);
+            continue;
+        }
+        // ── Per-file malformed markdown guard ──────────────────────────────────
+        // FIX D: use accurate signals from analyzeMarkdown instead of heuristics.
+        // unterminatedFence: CommonMark state machine detects a genuinely unclosed fence.
+        // unterminatedComment: strips balanced comments first, then checks for leftover <!--.
+        const { unterminatedFence, unterminatedComment } = analyzeMarkdown(raw);
+        if (unterminatedFence || unterminatedComment) {
+            blockers.push(`${file}: malformed markdown (unterminated fence or comment)`);
+        }
+        const fm = extractFrontmatter(raw);
+        // File-level frontmatter status check
+        if (fm['status'] && BLOCKING_UAT_FM_STATUSES.has(fm['status'])) {
+            blockers.push(`${file}: frontmatter status=${fm['status']}`);
+        }
+        // File-level frontmatter result check
+        if (fm['result'] && BLOCKING_UAT_FM_RESULTS.has(fm['result'])) {
+            blockers.push(`${file}: frontmatter result=${fm['result']}`);
+        }
+        // Parse test items from the cleaned body (hardened against false positives)
+        const cleanContent = stripFalsePositiveContexts(raw);
+        const items = parseUatResultItems(cleanContent);
+        for (const item of items) {
+            const passing = PASSING_RESULTS.has(item.result);
+            checks.push({
+                file,
+                test: item.test,
+                name: item.name,
+                result: item.result,
+                passing,
+            });
+            if (!passing) {
+                blockers.push(`${file}: test ${item.test} (${item.result})`);
+            }
+        }
+    }
+    // ── Process VERIFICATION files ─────────────────────────────────────────────
+    let hasPassingVerification = false;
+    for (const file of verFileNames) {
+        verificationFiles.push(file);
+        let raw = '';
+        try {
+            raw = node_fs_1.default.readFileSync(node_path_1.default.join(phaseFullDir, file), 'utf-8');
+        }
+        catch {
+            blockers.push(`${file}: could not read verification file`);
+            continue;
+        }
+        const vfm = extractFrontmatter(raw);
+        const vStatus = vfm['status'];
+        if (vStatus && BLOCKING_VERIFICATION_FM_STATUSES.has(vStatus)) {
+            blockers.push(`${file}: verification status=${vStatus}`);
+        }
+        else if (vStatus && PASSING_VERIFICATION_STATUSES.has(vStatus)) {
+            // Allowlist: only explicitly-passing statuses count
+            hasPassingVerification = true;
+        }
+        // Missing or unknown status: does NOT count as passing, does NOT push a blocker
+        // (handled by the requireVerification policy check below if needed)
+    }
+    // ── Policy: requireVerification ───────────────────────────────────────────
+    if (requireVerification && !hasPassingVerification) {
+        blockers.push('policy: verification required but no passing *-VERIFICATION.md found');
+    }
+    // ── Determine no_uat_artifacts and passed ─────────────────────────────────
+    // no_uat_artifacts: true when no real UAT test items were parsed from any file
+    const no_uat_artifacts = checks.length === 0;
+    // FIX 1: require positive passing evidence; no vacuous pass
+    // passed = no blockers AND at least one check AND all checks passing
+    const passed = blockers.length === 0 && checks.length > 0 && checks.every(c => c.passing);
+    return {
+        passed,
+        uat_files: uatFiles,
+        verification_files: verificationFiles,
+        checks,
+        blockers,
+        no_uat_artifacts,
+        policy: {
+            require_verification: requireVerification,
+        },
+    };
+}
+module.exports = {
+    stripFalsePositiveContexts,
+    parseUatResultItems,
+    analyzeMarkdown,
+    evaluateUatPassed,
+};