@jokerized/getresearchdone 0.4.1

package/dist/lib/verify.js

@@ -0,0 +1,1153 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { safeReadFile, execGit, findPhaseInternal, validateGitRef, output, error, } = require('./utils');
+const { extractFrontmatter, parseMustHavesBlock, } = require('./frontmatter');
+// Module-level cache for file reads within a single process invocation.
+// Safe for verify functions since they never write files.
+const _fileReadCache = new Map();
+function readFileCached(fullPath) {
+    if (!_fileReadCache.has(fullPath)) {
+        _fileReadCache.set(fullPath, safeReadFile(fullPath));
+    }
+    return _fileReadCache.get(fullPath);
+}
+/** Clear the module-level file read cache. Call in test beforeEach to prevent stale reads across tests. */
+function clearVerifyCache() {
+    _fileReadCache.clear();
+}
+// ─── Verification Command Functions ──────────────────────────────────────────
+/**
+ * CLI command: Verify SUMMARY.md structure including file existence, commit hashes, and self-check.
+ * @param cwd - Project working directory
+ * @param summaryPath - Relative path to the SUMMARY.md file
+ * @param checkFileCount - Number of mentioned files to spot-check for existence
+ * @param raw - Output raw 'passed'/'failed' instead of JSON
+ */
+function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
+    if (!summaryPath) {
+        error('summary-path required');
+    }
+    const fullPath = path.join(cwd, summaryPath);
+    const checkCount = checkFileCount || 2;
+    // Check 1: Summary exists
+    let content;
+    try {
+        content = fs.readFileSync(fullPath, 'utf-8');
+    }
+    catch {
+        const result = {
+            passed: false,
+            checks: {
+                summary_exists: false,
+                files_created: { checked: 0, found: 0, missing: [] },
+                commits_exist: false,
+                self_check: 'not_found',
+            },
+            errors: ['SUMMARY.md not found'],
+        };
+        output(result, raw, 'failed');
+        return;
+    }
+    const errors = [];
+    // Check 2: Spot-check files mentioned in summary
+    const mentionedFiles = new Set();
+    const patterns = [
+        /`([^`]+\.[a-zA-Z]+)`/g,
+        /(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`]+\.[a-zA-Z]+)`?/gi,
+    ];
+    for (const pattern of patterns) {
+        let m;
+        while ((m = pattern.exec(content)) !== null) {
+            const filePath = m[1];
+            if (filePath && !filePath.startsWith('http') && filePath.includes('/')) {
+                mentionedFiles.add(filePath);
+            }
+        }
+    }
+    const filesToCheck = Array.from(mentionedFiles).slice(0, checkCount);
+    const missing = [];
+    for (const file of filesToCheck) {
+        if (!fs.existsSync(path.join(cwd, file))) {
+            missing.push(file);
+        }
+    }
+    // Check 3: Commits exist. Codex r15 P2: every referenced commit must
+    // exist (was sampling 3 and passing if any one resolved). Check the
+    // first ~10 unique hashes to keep the cost bounded but catch
+    // partial-failure cases.
+    // Codex r27 P2: a context-free hex-token regex also matches
+    // checksums, cache keys, content-hash IDs, and other non-commit
+    // hex strings. Anchor on explicit commit labels first (commit:,
+    // SHA:, ref:, hash:, parent:, `**Commit**`, hyperlinks to
+    // /commit/<sha>, conventional `(abcdef1)` parens), and only fall
+    // back to the bare hex scan if the labelled set is empty AND the
+    // SUMMARY explicitly mentions "commit" somewhere (so we keep the
+    // backward-compatible behaviour without false-failing on summaries
+    // that legitimately reference no commits).
+    // Codex r28 P2: a labelled `Commits: <a>, <b>, <c>` list contains
+    // multiple hashes. Capture the full label line (up to newline or
+    // next section) and pull every hex token from it, instead of only
+    // matching one hash per label.
+    // Codex r30 P2: only collect hex tokens that appear in commit
+    // contexts. Three kinds of context count:
+    //   1. Labelled lines: `Commit: <sha>`, `SHA: <sha>`, etc., and
+    //      multi-hash lists like `Commits: <a>, <b>`. The line itself
+    //      is the context; harvest every hex token on it.
+    //   2. /commit/<sha> hyperlinks.
+    //   3. A commits-block heading (`## (Task )?Commits`, `### Commits`,
+    //      `# Commits`) — harvest every hex token in lines until the
+    //      next heading at the same or shallower level, or the next
+    //      blank line followed by a non-list line.
+    // Bare `(deadbeef)` parens and the prior whole-document scan are
+    // dropped — they re-introduced the false positives r27 was trying
+    // to fix.
+    const labelledHashes = [];
+    // Codex r32 P2: accept bold/bulleted label forms documented in
+    // agents/grd-executor.md, e.g.:
+    //   - **Commits:** abc, def
+    //   **Commits:**
+    //     - abc
+    // Match the *label line* generically, then if it's a bare label
+    // (no hash on the same line) sweep subsequent bullet rows.
+    const linesAll = content.split('\n');
+    for (let i = 0; i < linesAll.length; i++) {
+        const line = linesAll[i];
+        // Codex r34 P2: also accept colonless forms used in real
+        // SUMMARYs:
+        //   - `Commit 29c6883 exists`           (label + space + hash)
+        //   - `### Task 1 ... (29c6883)`        (paren-suffix on a
+        //                                         heading/task line)
+        //   - `- [x] Task X completed (abc1234)` (paren-suffix on a
+        //                                         checklist line)
+        const isColonLabel = /(?:[-*]\s+|^|\*\*)\s*(?:commit|sha|ref|hash|parent)s?\s*[:*]/i.test(line);
+        // Codex r38 P2: colonless `Commits a, b, c` should capture every
+        // hash on the line, not just the first. Detect the colonless
+        // label and then harvest *all* hex tokens from the line.
+        // Codex r39 P2: also accept backticked hashes after a colonless
+        // label, e.g. `- [x] Commit \`8880489\` exists`. Allow optional
+        // backticks between the label and the hash.
+        const hasColonlessLabel = /\b(?:commit|sha|ref|hash|parent)s?\s+`?[0-9a-f]{7,40}`?\b/i.test(line);
+        const colonlessHashes = hasColonlessLabel
+            ? line.match(/\b[0-9a-f]{7,40}\b/gi) ?? []
+            : [];
+        // Codex r35 P2: paren-suffix `(<sha>)` is ambiguous — it's also
+        // used for checksums/artifact IDs. Require the line itself to
+        // mention something commit-flavored OR be a task-completion
+        // checklist marker (`- [x]`). Plain headings like
+        // `### Artifact checksum (deadbeef)` are no longer matched.
+        const isCheckedTask = /^\s*[-*]\s+\[x\]\s+/i.test(line);
+        const lineHasCommitWord = /\b(?:commit|merge|landed|shipped)\b/i.test(line);
+        // Codex r41 P2: also accept task-heading paren suffixes such as
+        // `### Task 1: add parser (deadbee)`. The heading-with-"Task"
+        // signal disambiguates from `### Artifact checksum (deadbeef)`.
+        const isTaskHeading = /^#{1,6}\s+(?:Task|Step|Plan|Phase|Subtask)\b/i.test(line);
+        const parenSuffixMatch = (isCheckedTask || lineHasCommitWord || isTaskHeading)
+            ? line.match(/\(([0-9a-f]{7,40})\)\s*$/i)
+            : null;
+        for (const h of colonlessHashes) {
+            labelledHashes.push(h.toLowerCase());
+        }
+        if (parenSuffixMatch) {
+            labelledHashes.push(parenSuffixMatch[1].toLowerCase());
+        }
+        if (!isColonLabel) {
+            continue;
+        }
+        // Codex r36 P2: use word boundaries so a SHA-256 artifact hash
+        // (64 hex chars) isn't truncated to its first 40 and treated as
+        // a commit. Boundary-aware match is consistent with the table
+        // and block scanners below.
+        const hashesOnLine = line.match(/\b[0-9a-f]{7,40}\b/gi) ?? [];
+        if (hashesOnLine.length > 0) {
+            for (const h of hashesOnLine)
+                labelledHashes.push(h.toLowerCase());
+            continue;
+        }
+        // Bare label — sweep following bullet lines until indent drops
+        // back or a non-bullet line appears.
+        for (let j = i + 1; j < linesAll.length; j++) {
+            const row = linesAll[j];
+            if (/^\s*$/.test(row))
+                continue;
+            if (!/^\s*[-*]\s+/.test(row))
+                break;
+            for (const h of row.match(/\b[0-9a-f]{7,40}\b/gi) ?? []) {
+                labelledHashes.push(h.toLowerCase());
+            }
+        }
+    }
+    for (const m of content.matchAll(/\/commit\/([0-9a-f]{7,40})\b/gi)) {
+        labelledHashes.push(m[1].toLowerCase());
+    }
+    // Codex r35 P2: a `## Commits` section can contain nested `### Task N`
+    // subheadings with the actual hashes. The prior pattern stopped at
+    // any heading of any depth, missing those. Walk lines explicitly:
+    // when we hit a `## Commits` heading at depth D, harvest hashes
+    // from following lines until we see a heading at depth ≤ D
+    // (siblings or shallower).
+    const headingRe = /^(#{1,6})\s+(?:Task\s+)?Commits?\s*$/i;
+    for (let i = 0; i < linesAll.length; i++) {
+        const headingMatch = linesAll[i].match(headingRe);
+        if (!headingMatch)
+            continue;
+        const depth = headingMatch[1].length;
+        for (let j = i + 1; j < linesAll.length; j++) {
+            const nextHeading = linesAll[j].match(/^(#{1,6})\s+/);
+            if (nextHeading && nextHeading[1].length <= depth)
+                break;
+            for (const h of linesAll[j].match(/\b[0-9a-f]{7,40}\b/gi) ?? []) {
+                labelledHashes.push(h.toLowerCase());
+            }
+        }
+    }
+    // Codex r31 P2 / r33 P2: markdown tables with a `Commit` column
+    // header. Find the commit-column INDEX from the header row, then
+    // only harvest hex tokens from that specific cell in each row —
+    // otherwise a `| task | commit | checksum |` table would also try
+    // to validate the unrelated `checksum` column against git.
+    const lines = content.split('\n');
+    // Codex r37 P2: only drop the trailing-pipe artifact when one
+    // actually exists. Otherwise tables without a trailing `|`
+    // (`| Task | Commit` / `| 1 | deadbeef`) lose their last real
+    // cell — the Commit column — and the scanner misses every hash.
+    const splitCells = (s) => {
+        const trimmed = s.trimEnd();
+        const hasTrailingPipe = trimmed.endsWith('|');
+        const cells = trimmed.split('|').map((c) => c.trim());
+        cells.shift(); // drop leading empty before first `|`
+        if (hasTrailingPipe)
+            cells.pop();
+        return cells;
+    };
+    for (let i = 0; i < lines.length; i++) {
+        // Codex r40 P2: trim leading whitespace before checking for table
+        // start — indented tables (inside a list or quoted block) also
+        // need their commit column scanned.
+        const line = lines[i].trimStart();
+        if (!line.startsWith('|') ||
+            !/\bcommit\b/i.test(line) ||
+            !lines[i + 1]?.match(/^\s*\|?\s*[-:]+/)) {
+            continue;
+        }
+        const headerCells = splitCells(line);
+        const commitColIdx = headerCells.findIndex((c) => /\bcommit\b/i.test(c));
+        if (commitColIdx === -1)
+            continue;
+        for (let j = i + 2; j < lines.length; j++) {
+            const row = lines[j].trimStart();
+            if (!row.startsWith('|'))
+                break;
+            const rowCells = splitCells(row);
+            const cell = rowCells[commitColIdx] ?? '';
+            for (const h of cell.match(/\b[0-9a-f]{7,40}\b/gi) ?? []) {
+                labelledHashes.push(h.toLowerCase());
+            }
+        }
+    }
+    const hashes = Array.from(new Set(labelledHashes));
+    let commitsExist = false;
+    const invalidHashes = [];
+    if (hashes.length > 0) {
+        const uniqueHashes = Array.from(new Set(hashes)).slice(0, 10);
+        let allValid = true;
+        for (const hash of uniqueHashes) {
+            try {
+                validateGitRef(hash);
+            }
+            catch {
+                allValid = false;
+                invalidHashes.push(hash);
+                continue;
+            }
+            const result = execGit(cwd, ['cat-file', '-t', hash]);
+            if (!(result.exitCode === 0 && result.stdout === 'commit')) {
+                allValid = false;
+                invalidHashes.push(hash);
+            }
+        }
+        commitsExist = allValid;
+    }
+    // Check 4: Self-check section
+    let selfCheck = 'not_found';
+    const selfCheckPattern = /##\s*(?:Self[- ]?Check|Verification|Quality Check)/i;
+    if (selfCheckPattern.test(content)) {
+        const passPattern = /(?:all\s+)?(?:pass|✓|✅|complete|succeeded)/i;
+        const failPattern = /(?:fail|✗|❌|incomplete|blocked)/i;
+        const checkSection = content.slice(content.search(selfCheckPattern));
+        if (failPattern.test(checkSection)) {
+            selfCheck = 'failed';
+        }
+        else if (passPattern.test(checkSection)) {
+            selfCheck = 'passed';
+        }
+    }
+    if (missing.length > 0)
+        errors.push('Missing files: ' + missing.join(', '));
+    if (!commitsExist && hashes.length > 0)
+        errors.push(invalidHashes.length > 0
+            ? `Referenced commit hashes not found in git history: ${invalidHashes.join(', ')}`
+            : 'Referenced commit hashes not found in git history');
+    if (selfCheck === 'failed')
+        errors.push('Self-check section indicates failure');
+    const checks = {
+        summary_exists: true,
+        files_created: {
+            checked: filesToCheck.length,
+            found: filesToCheck.length - missing.length,
+            missing,
+        },
+        commits_exist: commitsExist,
+        self_check: selfCheck,
+    };
+    const passed = missing.length === 0 && selfCheck !== 'failed' && (commitsExist || hashes.length === 0);
+    const result = { passed, checks, errors };
+    output(result, raw, passed ? 'passed' : 'failed');
+}
+/**
+ * CLI command: Verify PLAN.md structure, frontmatter fields, and task element completeness.
+ * @param cwd - Project working directory
+ * @param filePath - Path to the PLAN.md file to validate
+ * @param raw - Output raw 'valid'/'invalid' instead of JSON
+ */
+function cmdVerifyPlanStructure(cwd, filePath, raw) {
+    if (!filePath) {
+        error('file path required');
+    }
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+    const content = readFileCached(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: filePath }, raw);
+        return;
+    }
+    const fm = extractFrontmatter(content);
+    const errors = [];
+    const warnings = [];
+    // Check required frontmatter fields
+    const required = [
+        'phase',
+        'plan',
+        'type',
+        'wave',
+        'depends_on',
+        'files_modified',
+        'autonomous',
+        'must_haves',
+    ];
+    const missingFields = [];
+    for (const field of required) {
+        if (fm[field] === undefined) {
+            errors.push(`Missing required frontmatter field: ${field}`);
+            missingFields.push(field);
+        }
+    }
+    // Include found frontmatter fields context when fields are missing
+    if (missingFields.length > 0) {
+        const foundFields = Object.keys(fm);
+        if (foundFields.length > 0) {
+            errors.push(`Found frontmatter fields: ${foundFields.join(', ')}`);
+        }
+    }
+    // Parse and check task elements
+    const taskPattern = /<task[^>]*>([\s\S]*?)<\/task>/g;
+    const tasks = [];
+    let taskMatch;
+    while ((taskMatch = taskPattern.exec(content)) !== null) {
+        const taskContent = taskMatch[1];
+        const nameMatch = taskContent.match(/<name>([\s\S]*?)<\/name>/);
+        const taskName = nameMatch ? nameMatch[1].trim() : 'unnamed';
+        const hasFiles = /<files>/.test(taskContent);
+        const hasAction = /<action>/.test(taskContent);
+        const hasVerify = /<verify>/.test(taskContent);
+        const hasDone = /<done>/.test(taskContent);
+        if (!nameMatch)
+            errors.push('Task missing <name> element');
+        if (!hasAction)
+            errors.push(`Task '${taskName}' missing <action>`);
+        if (!hasVerify)
+            warnings.push(`Task '${taskName}' missing <verify>`);
+        if (!hasDone)
+            warnings.push(`Task '${taskName}' missing <done>`);
+        if (!hasFiles)
+            warnings.push(`Task '${taskName}' missing <files>`);
+        tasks.push({ name: taskName, hasFiles, hasAction, hasVerify, hasDone });
+    }
+    if (tasks.length === 0)
+        warnings.push('No <task> elements found');
+    // Wave/depends_on consistency
+    if (fm.wave &&
+        parseInt(String(fm.wave)) > 1 &&
+        (!fm.depends_on || (Array.isArray(fm.depends_on) && fm.depends_on.length === 0))) {
+        warnings.push('Wave > 1 but depends_on is empty');
+    }
+    // Autonomous/checkpoint consistency
+    const hasCheckpoints = /<task\s+type=["']?checkpoint/.test(content);
+    // fm.autonomous may arrive as boolean or string from YAML parsing -- check both
+    const autonomousVal = fm.autonomous;
+    if (hasCheckpoints && autonomousVal !== 'false' && autonomousVal !== false) {
+        errors.push('Has checkpoint tasks but autonomous is not false');
+    }
+    // Extract markdown headings for found_sections
+    const headingPattern = /^#{1,6}\s+.+$/gm;
+    const found_sections = (content.match(headingPattern) || []).map((h) => h.trim());
+    const result = {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        task_count: tasks.length,
+        tasks,
+        frontmatter_fields: Object.keys(fm),
+        found_sections,
+    };
+    output(result, raw, errors.length === 0 ? 'valid' : 'invalid');
+}
+/**
+ * CLI command: Check that all plans in a phase have corresponding summaries.
+ * @param cwd - Project working directory
+ * @param phase - Phase number to check
+ * @param raw - Output raw 'complete'/'incomplete' instead of JSON
+ */
+function cmdVerifyPhaseCompleteness(cwd, phase, raw) {
+    if (!phase) {
+        error('phase required');
+    }
+    const phaseInfo = findPhaseInternal(cwd, phase);
+    if (!phaseInfo || !phaseInfo.found) {
+        output({ error: 'Phase not found', phase }, raw);
+        return;
+    }
+    const errors = [];
+    const warnings = [];
+    const phaseDir = path.join(cwd, phaseInfo.directory);
+    // List plans and summaries
+    let files;
+    try {
+        files = fs.readdirSync(phaseDir);
+    }
+    catch {
+        output({ error: 'Cannot read phase directory' }, raw);
+        return;
+    }
+    const plans = files.filter((f) => f.match(/-PLAN\.md$/i));
+    const summaries = files.filter((f) => f.match(/-SUMMARY\.md$/i));
+    // Extract plan IDs (everything before -PLAN.md)
+    const planIds = new Set(plans.map((p) => p.replace(/-PLAN\.md$/i, '')));
+    const summaryIds = new Set(summaries.map((s) => s.replace(/-SUMMARY\.md$/i, '')));
+    // Plans without summaries
+    const incompletePlans = [...planIds].filter((id) => !summaryIds.has(id));
+    if (incompletePlans.length > 0) {
+        errors.push(`Plans without summaries: ${incompletePlans.join(', ')}`);
+    }
+    // Summaries without plans (orphans)
+    const orphanSummaries = [...summaryIds].filter((id) => !planIds.has(id));
+    if (orphanSummaries.length > 0) {
+        warnings.push(`Summaries without plans: ${orphanSummaries.join(', ')}`);
+    }
+    const result = {
+        complete: errors.length === 0,
+        phase: phaseInfo.phase_number,
+        plan_count: plans.length,
+        summary_count: summaries.length,
+        incomplete_plans: incompletePlans,
+        orphan_summaries: orphanSummaries,
+        errors,
+        warnings,
+    };
+    output(result, raw, errors.length === 0 ? 'complete' : 'incomplete');
+}
+/**
+ * CLI command: Validate @-references and backtick file paths in a markdown file.
+ * @param cwd - Project working directory
+ * @param filePath - Path to the markdown file to check
+ * @param raw - Output raw 'valid'/'invalid' instead of JSON
+ */
+function cmdVerifyReferences(cwd, filePath, raw) {
+    if (!filePath) {
+        error('file path required');
+    }
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath);
+    const content = readFileCached(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: filePath }, raw);
+        return;
+    }
+    const found = [];
+    const missing = [];
+    // Find @-references: @path/to/file (must contain / to be a file path)
+    const atRefs = content.match(/@([^\s\n,)]+\/[^\s\n,)]+)/g) || [];
+    for (const ref of atRefs) {
+        const cleanRef = ref.slice(1); // remove @
+        // Skip templated/dynamic refs (e.g. @${CLAUDE_PLUGIN_ROOT}/...) — same
+        // guard used by the backtick-ref branch below.
+        if (cleanRef.includes('${') || cleanRef.includes('{{'))
+            continue;
+        const resolved = cleanRef.startsWith('~/')
+            ? path.join(process.env.HOME || os.homedir() || '', cleanRef.slice(2))
+            : path.join(cwd, cleanRef);
+        if (fs.existsSync(resolved)) {
+            found.push(cleanRef);
+        }
+        else {
+            missing.push(cleanRef);
+        }
+    }
+    // Find backtick file paths that look like real paths (contain / and have extension)
+    const backtickRefs = content.match(/`([^`]+\/[^`]+\.[a-zA-Z]{1,10})`/g) || [];
+    for (const ref of backtickRefs) {
+        const cleanRef = ref.slice(1, -1); // remove backticks
+        if (cleanRef.startsWith('http') || cleanRef.includes('${') || cleanRef.includes('{{'))
+            continue;
+        if (found.includes(cleanRef) || missing.includes(cleanRef))
+            continue; // dedup
+        const resolved = path.join(cwd, cleanRef);
+        if (fs.existsSync(resolved)) {
+            found.push(cleanRef);
+        }
+        else {
+            missing.push(cleanRef);
+        }
+    }
+    const result = {
+        valid: missing.length === 0,
+        found: found.length,
+        missing,
+        total: found.length + missing.length,
+    };
+    output(result, raw, missing.length === 0 ? 'valid' : 'invalid');
+}
+/**
+ * CLI command: Batch verify that git commit hashes exist in the repository.
+ * @param cwd - Project working directory
+ * @param hashes - Array of commit hashes to verify
+ * @param raw - Output raw 'valid'/'invalid' instead of JSON
+ */
+function cmdVerifyCommits(cwd, hashes, raw) {
+    if (!hashes || hashes.length === 0) {
+        error('At least one commit hash required. Usage: verify commits <hash1> [hash2 ...]. Run "git log --oneline" to find commit hashes');
+    }
+    const valid = [];
+    const invalid = [];
+    for (const hash of hashes) {
+        try {
+            validateGitRef(hash);
+        }
+        catch {
+            invalid.push(hash);
+            continue;
+        }
+        const result = execGit(cwd, ['cat-file', '-t', hash]);
+        if (result.exitCode === 0 && result.stdout.trim() === 'commit') {
+            valid.push(hash);
+        }
+        else {
+            invalid.push(hash);
+        }
+    }
+    const verifyResult = {
+        all_valid: invalid.length === 0,
+        valid,
+        invalid,
+        total: hashes.length,
+    };
+    output(verifyResult, raw, invalid.length === 0 ? 'valid' : 'invalid');
+}
+/**
+ * CLI command: Check that must_haves.artifacts from a plan exist on disk with required content.
+ * @param cwd - Project working directory
+ * @param planFilePath - Path to the PLAN.md file containing must_haves.artifacts
+ * @param raw - Output raw 'valid'/'invalid' instead of JSON
+ */
+function cmdVerifyArtifacts(cwd, planFilePath, raw) {
+    if (!planFilePath) {
+        error('plan file path required');
+    }
+    const fullPath = path.isAbsolute(planFilePath)
+        ? planFilePath
+        : path.join(cwd, planFilePath);
+    const content = readFileCached(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: planFilePath }, raw);
+        return;
+    }
+    const artifacts = parseMustHavesBlock(content, 'artifacts');
+    if (artifacts.length === 0) {
+        output({ error: 'No must_haves.artifacts found in frontmatter', path: planFilePath }, raw);
+        return;
+    }
+    const results = [];
+    for (const artifact of artifacts) {
+        if (typeof artifact === 'string')
+            continue; // skip simple string items
+        const artPath = artifact.path;
+        if (!artPath)
+            continue;
+        const artFullPath = path.join(cwd, artPath);
+        const exists = fs.existsSync(artFullPath);
+        const check = {
+            path: artPath,
+            exists,
+            issues: [],
+            passed: false,
+            plan_file: planFilePath,
+            must_haves_field: 'must_haves.artifacts',
+        };
+        if (exists) {
+            const fileContent = safeReadFile(artFullPath) || '';
+            const lineCount = fileContent.split('\n').length;
+            const artTyped = artifact;
+            if (artTyped.min_lines && lineCount < artTyped.min_lines) {
+                check.issues.push(`Only ${lineCount} lines, need ${artTyped.min_lines}`);
+            }
+            if (artTyped.contains && !fileContent.includes(artTyped.contains)) {
+                check.issues.push(`Missing pattern: ${artTyped.contains}`);
+            }
+            if (artTyped.exports) {
+                const exports = Array.isArray(artTyped.exports)
+                    ? artTyped.exports
+                    : [artTyped.exports];
+                for (const exp of exports) {
+                    if (!fileContent.includes(exp))
+                        check.issues.push(`Missing export: ${exp}`);
+                }
+            }
+            check.passed = check.issues.length === 0;
+        }
+        else {
+            check.issues.push('File not found');
+            check.remediation = `Create the missing file at: ${artPath}`;
+        }
+        results.push(check);
+    }
+    const passed = results.filter((r) => r.passed).length;
+    const verifyResult = {
+        all_passed: passed === results.length,
+        passed,
+        total: results.length,
+        artifacts: results,
+    };
+    output(verifyResult, raw, passed === results.length ? 'valid' : 'invalid');
+}
+/**
+ * CLI command: Validate must_haves.key_links patterns between source and target files.
+ * @param cwd - Project working directory
+ * @param planFilePath - Path to the PLAN.md file containing must_haves.key_links
+ * @param raw - Output raw 'valid'/'invalid' instead of JSON
+ */
+function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
+    if (!planFilePath) {
+        error('plan file path required');
+    }
+    const fullPath = path.isAbsolute(planFilePath)
+        ? planFilePath
+        : path.join(cwd, planFilePath);
+    const content = readFileCached(fullPath);
+    if (!content) {
+        output({ error: 'File not found', path: planFilePath }, raw);
+        return;
+    }
+    const keyLinks = parseMustHavesBlock(content, 'key_links');
+    if (keyLinks.length === 0) {
+        output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
+        return;
+    }
+    const results = [];
+    for (const link of keyLinks) {
+        if (typeof link === 'string')
+            continue;
+        const linkTyped = link;
+        const check = {
+            from: linkTyped.from,
+            to: linkTyped.to,
+            via: linkTyped.via || '',
+            verified: false,
+            detail: '',
+        };
+        const sourceContent = safeReadFile(path.join(cwd, linkTyped.from || ''));
+        if (!sourceContent) {
+            check.detail = 'Source file not found';
+        }
+        else if (linkTyped.pattern) {
+            try {
+                const regex = new RegExp(linkTyped.pattern);
+                if (regex.test(sourceContent)) {
+                    check.verified = true;
+                    check.detail = 'Pattern found in source';
+                }
+                else {
+                    const targetContent = safeReadFile(path.join(cwd, linkTyped.to || ''));
+                    if (targetContent && regex.test(targetContent)) {
+                        check.verified = true;
+                        check.detail = 'Pattern found in target';
+                    }
+                    else {
+                        check.detail = `Pattern "${linkTyped.pattern}" not found in source or target`;
+                    }
+                }
+            }
+            catch {
+                check.detail = `Invalid regex pattern: ${linkTyped.pattern}`;
+            }
+        }
+        else {
+            // No pattern: just check source references target
+            if (sourceContent.includes(linkTyped.to || '')) {
+                check.verified = true;
+                check.detail = 'Target referenced in source';
+            }
+            else {
+                check.detail = 'Target not referenced in source';
+            }
+        }
+        results.push(check);
+    }
+    const verified = results.filter((r) => r.verified).length;
+    const verifyResult = {
+        all_verified: verified === results.length,
+        verified,
+        total: results.length,
+        links: results,
+    };
+    output(verifyResult, raw, verified === results.length ? 'valid' : 'invalid');
+}
+/**
+ * Bundle the four PLAN.md mechanical checks (frontmatter, artifacts,
+ * key_links, references) plus a phase-level plan/summary completeness
+ * check into a single aggregated JSON result. Reuses the same helpers
+ * as the discrete verify commands so behavior stays consistent.
+ *
+ * Required PLAN.md frontmatter fields are kept in sync with
+ * cmdVerifyPlanStructure. Frontmatter check passes if all required
+ * fields are present; artifact and key-link checks pass when every
+ * declared item resolves; reference check passes when every @-reference
+ * and backtick path resolves; completeness check passes when every
+ * PLAN has a matching SUMMARY.
+ *
+ * @param cwd - Project working directory
+ * @param phase - Phase number or name passed to findPhaseInternal
+ * @param raw - Output 'pass'/'fail' instead of JSON
+ */
+function cmdVerifyMechanical(cwd, phase, raw) {
+    if (!phase) {
+        error('phase required');
+    }
+    const phaseInfo = findPhaseInternal(cwd, phase);
+    if (!phaseInfo || !phaseInfo.found) {
+        output({ error: 'Phase not found', phase }, raw);
+        return;
+    }
+    const phaseDir = path.join(cwd, phaseInfo.directory);
+    let files;
+    try {
+        files = fs.readdirSync(phaseDir);
+    }
+    catch {
+        output({ error: 'Cannot read phase directory', phase }, raw);
+        return;
+    }
+    // Accept both prefixed (`01-01-PLAN.md`) and bare (`PLAN.md`) filenames —
+    // matches the convention used across the codebase (phase.ts:336, utils.ts:1046,
+    // gates.ts:199, knowledge.ts:230, roadmap.ts:614).
+    const plans = files.filter((f) => /-PLAN\.md$/i.test(f) || f === 'PLAN.md');
+    const summaries = files.filter((f) => /-SUMMARY\.md$/i.test(f) || f === 'SUMMARY.md');
+    const checks = [];
+    // A phase with zero PLAN.md files cannot pass the mechanical gate by
+    // vacuously satisfying every check. Emit an explicit failing check so the
+    // aggregate result correctly reports passed=false.
+    checks.push({
+        check: 'plan_summary_completeness',
+        scope: `phase:${phaseInfo.phase_number}`,
+        passed: plans.length > 0,
+        detail: plans.length > 0
+            ? `Phase has ${plans.length} PLAN.md file(s)`
+            : 'Phase has no PLAN.md files — nothing to verify',
+        data: { plan_count: plans.length },
+    });
+    if (plans.length === 0) {
+        const result = {
+            passed: false,
+            phase: phaseInfo.phase_number,
+            plan_count: 0,
+            total_checks: checks.length,
+            passed_count: 0,
+            failed_count: checks.length,
+            checks,
+        };
+        output(result, raw, 'fail');
+        return;
+    }
+    // The placeholder above will be replaced by the real plan_summary_completeness
+    // check below; pop it so we don't double-report.
+    checks.pop();
+    const requiredFrontmatterFields = [
+        'phase',
+        'plan',
+        'type',
+        'wave',
+        'depends_on',
+        'files_modified',
+        'autonomous',
+        'must_haves',
+    ];
+    for (const planFile of plans) {
+        const planPath = path.join(phaseDir, planFile);
+        const content = readFileCached(planPath);
+        if (!content) {
+            checks.push({
+                check: 'frontmatter',
+                scope: `plan:${planFile}`,
+                passed: false,
+                detail: 'PLAN.md unreadable',
+            });
+            continue;
+        }
+        const fm = extractFrontmatter(content);
+        // frontmatter check
+        const missingFields = requiredFrontmatterFields.filter((f) => fm[f] === undefined);
+        checks.push({
+            check: 'frontmatter',
+            scope: `plan:${planFile}`,
+            passed: missingFields.length === 0,
+            detail: missingFields.length === 0
+                ? `All ${requiredFrontmatterFields.length} required fields present`
+                : `Missing: ${missingFields.join(', ')}`,
+            data: { missing: missingFields, required: [...requiredFrontmatterFields] },
+        });
+        // artifacts check — mirror cmdVerifyArtifacts: existence AND content
+        // constraints (min_lines / contains / exports).
+        const artifacts = parseMustHavesBlock(content, 'artifacts');
+        if (artifacts.length > 0) {
+            const failed = [];
+            for (const art of artifacts) {
+                if (typeof art === 'string')
+                    continue;
+                const artTyped = art;
+                const artPath = artTyped.path;
+                if (!artPath)
+                    continue;
+                const artFullPath = path.join(cwd, artPath);
+                const issues = [];
+                if (!fs.existsSync(artFullPath)) {
+                    issues.push('File not found');
+                }
+                else {
+                    const fileContent = safeReadFile(artFullPath) || '';
+                    const lineCount = fileContent.split('\n').length;
+                    if (artTyped.min_lines && lineCount < artTyped.min_lines) {
+                        issues.push(`Only ${lineCount} lines, need ${artTyped.min_lines}`);
+                    }
+                    if (artTyped.contains && !fileContent.includes(artTyped.contains)) {
+                        issues.push(`Missing pattern: ${artTyped.contains}`);
+                    }
+                    if (artTyped.exports) {
+                        const exps = Array.isArray(artTyped.exports)
+                            ? artTyped.exports
+                            : [artTyped.exports];
+                        for (const exp of exps) {
+                            if (!fileContent.includes(exp))
+                                issues.push(`Missing export: ${exp}`);
+                        }
+                    }
+                }
+                if (issues.length > 0)
+                    failed.push({ path: artPath, issues });
+            }
+            checks.push({
+                check: 'artifacts',
+                scope: `plan:${planFile}`,
+                passed: failed.length === 0,
+                detail: failed.length === 0
+                    ? `All ${artifacts.length} artifacts present and satisfy content constraints`
+                    : `Failed: ${failed.map((f) => `${f.path} (${f.issues.join('; ')})`).join('; ')}`,
+                data: { failed },
+            });
+        }
+        // key_links check
+        const keyLinks = parseMustHavesBlock(content, 'key_links');
+        if (keyLinks.length > 0) {
+            const failed = [];
+            for (const link of keyLinks) {
+                if (typeof link === 'string')
+                    continue;
+                const linkTyped = link;
+                const fromContent = safeReadFile(path.join(cwd, linkTyped.from || ''));
+                const toPath = path.join(cwd, linkTyped.to || '');
+                let verified = false;
+                if (fromContent) {
+                    if (linkTyped.pattern) {
+                        try {
+                            const regex = new RegExp(linkTyped.pattern);
+                            if (regex.test(fromContent))
+                                verified = true;
+                            else {
+                                const toContent = safeReadFile(toPath);
+                                if (toContent && regex.test(toContent))
+                                    verified = true;
+                            }
+                        }
+                        catch {
+                            verified = false;
+                        }
+                    }
+                    else {
+                        verified = fromContent.includes(linkTyped.to || '');
+                    }
+                }
+                if (!verified)
+                    failed.push(`${linkTyped.from} → ${linkTyped.to}`);
+            }
+            checks.push({
+                check: 'key_links',
+                scope: `plan:${planFile}`,
+                passed: failed.length === 0,
+                detail: failed.length === 0
+                    ? `All ${keyLinks.length} key links verified`
+                    : `Failed: ${failed.join('; ')}`,
+                data: { failed },
+            });
+        }
+        // references check
+        const missingRefs = [];
+        const atRefs = content.match(/@([^\s\n,)]+\/[^\s\n,)]+)/g) || [];
+        for (const ref of atRefs) {
+            const cleanRef = ref.slice(1);
+            // Skip templated/dynamic refs (e.g. @${CLAUDE_PLUGIN_ROOT}/...) — they
+            // are not literal paths. Same guard the backtick branch uses below.
+            if (cleanRef.includes('${') || cleanRef.includes('{{'))
+                continue;
+            const resolved = cleanRef.startsWith('~/')
+                ? path.join(process.env.HOME || os.homedir() || '', cleanRef.slice(2))
+                : path.join(cwd, cleanRef);
+            if (!fs.existsSync(resolved))
+                missingRefs.push(cleanRef);
+        }
+        const backtickRefs = content.match(/`([^`]+\/[^`]+\.[a-zA-Z]{1,10})`/g) || [];
+        for (const ref of backtickRefs) {
+            const cleanRef = ref.slice(1, -1);
+            if (cleanRef.startsWith('http') || cleanRef.includes('${') || cleanRef.includes('{{'))
+                continue;
+            if (missingRefs.includes(cleanRef))
+                continue;
+            if (!fs.existsSync(path.join(cwd, cleanRef)))
+                missingRefs.push(cleanRef);
+        }
+        const totalRefs = atRefs.length + backtickRefs.length;
+        if (totalRefs > 0) {
+            checks.push({
+                check: 'references',
+                scope: `plan:${planFile}`,
+                passed: missingRefs.length === 0,
+                detail: missingRefs.length === 0
+                    ? `All ${totalRefs} references resolve`
+                    : `Missing: ${missingRefs.join(', ')}`,
+                data: { missing: missingRefs, total: totalRefs },
+            });
+        }
+    }
+    // phase-level: plan/summary completeness — bare PLAN.md / SUMMARY.md
+    // normalise to '' so they pair off.
+    const stripPlanId = (n) => n === 'PLAN.md' ? '' : n.replace(/-PLAN\.md$/i, '');
+    const stripSummaryId = (n) => n === 'SUMMARY.md' ? '' : n.replace(/-SUMMARY\.md$/i, '');
+    const planIds = new Set(plans.map(stripPlanId));
+    const summaryIds = new Set(summaries.map(stripSummaryId));
+    const incomplete = [...planIds].filter((id) => !summaryIds.has(id));
+    checks.push({
+        check: 'plan_summary_completeness',
+        scope: `phase:${phaseInfo.phase_number}`,
+        passed: incomplete.length === 0,
+        detail: incomplete.length === 0
+            ? `All ${plans.length} plans have summaries`
+            : `Plans without summaries: ${incomplete.join(', ')}`,
+        data: { incomplete, plan_count: plans.length, summary_count: summaries.length },
+    });
+    const passedCount = checks.filter((c) => c.passed).length;
+    const failedCount = checks.length - passedCount;
+    const result = {
+        passed: failedCount === 0,
+        phase: phaseInfo.phase_number,
+        plan_count: plans.length,
+        total_checks: checks.length,
+        passed_count: passedCount,
+        failed_count: failedCount,
+        checks,
+    };
+    output(result, raw, failedCount === 0 ? 'pass' : 'fail');
+}
+/**
+ * CLI command: Diagnose a failed phase by reading VERIFICATION.md, plan files,
+ * and running git diff to produce a ranked root-cause list.
+ *
+ * Intended as a quick forensics tool after `gd verify-phase N` fails.
+ * Reads:
+ *   - .planning/milestones/{m}/phases/{N}/VERIFICATION.md (verdict + failed checks)
+ *   - *-PLAN.md files in phase dir (detect plans without summaries)
+ *   - `git diff HEAD` (scope estimate of uncommitted changes)
+ * Ranks causes by heuristic signal strength.
+ *
+ * @param cwd - Project working directory
+ * @param phase - Phase number or name
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdDiagnosePhase(cwd, phase, raw) {
+    if (!phase) {
+        error('phase required. Usage: gd diagnose <phase>');
+    }
+    const phaseInfo = findPhaseInternal(cwd, phase);
+    if (!phaseInfo || !phaseInfo.found) {
+        output({ error: 'Phase not found', phase }, raw);
+        return;
+    }
+    const phaseDir = path.join(cwd, phaseInfo.directory);
+    // Codex r20 P2: scaffold/execution flow produces prefixed names like
+    // `75-VERIFICATION.md`. Match both forms.
+    let verificationPath = path.join(phaseDir, 'VERIFICATION.md');
+    try {
+        const files = require('fs').readdirSync(phaseDir);
+        const prefixed = files.find((f) => /-VERIFICATION\.md$/.test(f));
+        if (prefixed && !require('fs').existsSync(verificationPath)) {
+            verificationPath = path.join(phaseDir, prefixed);
+        }
+    }
+    catch { /* fall through */ }
+    const verificationContent = safeReadFile(verificationPath);
+    // Parse failed checks from VERIFICATION.md
+    const failedChecks = [];
+    let verdict = 'unknown';
+    if (verificationContent) {
+        const verdictMatch = verificationContent.match(/\*\*verdict\*\*[:\s]*([^\n]+)/i);
+        if (verdictMatch)
+            verdict = verdictMatch[1].trim();
+        // Extract lines starting with ❌ or [FAIL] or "- FAIL"
+        const failLines = verificationContent.match(/^(?:❌|[-*]\s*\[?FAIL[^]]*]?).*$/gim) || [];
+        for (const line of failLines) {
+            const clean = line.replace(/^[-*\s❌✗x]+/i, '').trim();
+            if (clean)
+                failedChecks.push(clean);
+        }
+        // Also parse "check: X passed: false" patterns in JSON-like blocks
+        const checkFailMatches = verificationContent.match(/"check"\s*:\s*"([^"]+)"[^}]*"passed"\s*:\s*false/g) || [];
+        for (const m of checkFailMatches) {
+            const nameMatch = m.match(/"check"\s*:\s*"([^"]+)"/);
+            if (nameMatch && !failedChecks.includes(nameMatch[1])) {
+                failedChecks.push(nameMatch[1]);
+            }
+        }
+    }
+    // Check for plans without summaries
+    let files = [];
+    try {
+        files = fs.readdirSync(phaseDir);
+    }
+    catch {
+        // phase dir unreadable
+    }
+    const plans = files.filter((f) => /-PLAN\.md$/i.test(f) || f === 'PLAN.md');
+    const summaries = files.filter((f) => /-SUMMARY\.md$/i.test(f) || f === 'SUMMARY.md');
+    const planIds = plans.map((f) => (f === 'PLAN.md' ? '' : f.replace(/-PLAN\.md$/i, '')));
+    const summaryIds = new Set(summaries.map((f) => (f === 'SUMMARY.md' ? '' : f.replace(/-SUMMARY\.md$/i, ''))));
+    const plansMissingSummaries = planIds.filter((id) => !summaryIds.has(id)).length;
+    // Measure uncommitted git diff size
+    let gitDiffLines = 0;
+    try {
+        const diffResult = execGit(cwd, ['diff', 'HEAD', '--stat'], { allowBlocked: true });
+        if (diffResult.stdout) {
+            gitDiffLines = (diffResult.stdout.match(/\n/g) || []).length;
+        }
+    }
+    catch {
+        // git not available or not a repo
+    }
+    // Build ranked root causes
+    const rootCauses = [];
+    let rank = 1;
+    if (plansMissingSummaries > 0) {
+        rootCauses.push({
+            rank: rank++,
+            cause: `${plansMissingSummaries} plan(s) missing SUMMARY.md`,
+            evidence: `Found ${plans.length} PLAN.md files, ${summaries.length} SUMMARY.md files`,
+            suggestion: 'Run gd execute-phase N or manually write SUMMARY.md for each incomplete plan',
+        });
+    }
+    if (!verificationContent) {
+        rootCauses.push({
+            rank: rank++,
+            cause: 'VERIFICATION.md not found',
+            evidence: `Expected at ${path.relative(cwd, verificationPath)}`,
+            suggestion: 'Run gd verify-phase N to generate VERIFICATION.md before diagnosing',
+        });
+    }
+    else if (verdict.toLowerCase().includes('fail') || verdict === 'unknown') {
+        rootCauses.push({
+            rank: rank++,
+            cause: `Verification verdict: ${verdict}`,
+            evidence: `${failedChecks.length} failed check(s) recorded`,
+            suggestion: `Address failed checks: ${failedChecks.slice(0, 3).join(', ')}${failedChecks.length > 3 ? '...' : ''}`,
+        });
+    }
+    for (const check of failedChecks.slice(0, 5)) {
+        const cause = `Failed check: ${check}`;
+        if (rootCauses.some((c) => c.cause === cause))
+            continue;
+        rootCauses.push({
+            rank: rank++,
+            cause,
+            evidence: `Recorded in VERIFICATION.md`,
+            suggestion: _checkSuggestion(check),
+        });
+    }
+    if (gitDiffLines > 10) {
+        rootCauses.push({
+            rank: rank,
+            cause: `${gitDiffLines} uncommitted lines in working tree`,
+            evidence: 'git diff HEAD --stat shows pending changes',
+            suggestion: 'Commit or stash changes before re-running verification',
+        });
+    }
+    if (rootCauses.length === 0) {
+        rootCauses.push({
+            rank: 1,
+            cause: 'No obvious failure signals found',
+            evidence: 'VERIFICATION.md exists, no missing summaries, no large diffs',
+            suggestion: 'Review VERIFICATION.md manually or re-run gd verify-phase N for details',
+        });
+    }
+    const result = {
+        phase: phaseInfo.phase_number,
+        verdict,
+        root_causes: rootCauses,
+        failed_checks: failedChecks,
+        git_diff_lines: gitDiffLines,
+        plans_missing_summaries: plansMissingSummaries,
+    };
+    const summary = `Phase ${phaseInfo.phase_number}: ${rootCauses.length} root cause(s) — top: ${rootCauses[0].cause}`;
+    output(result, raw, summary);
+}
+/** Map a failed check name to a human-readable next-step suggestion. */
+function _checkSuggestion(check) {
+    if (/frontmatter/i.test(check))
+        return 'Ensure PLAN.md has all required frontmatter fields (phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves)';
+    if (/artifact/i.test(check))
+        return 'Verify all must_haves artifacts exist at the declared paths with required content';
+    if (/reference/i.test(check))
+        return 'Fix broken @file or `path` references in PLAN.md';
+    if (/key.?link/i.test(check))
+        return 'Confirm all key_links pairs are wired together in source/target files';
+    if (/summary|completeness/i.test(check))
+        return 'Write a SUMMARY.md for each PLAN.md in the phase directory';
+    return `Review the "${check}" section in VERIFICATION.md for details`;
+}
+// ─── Exports ─────────────────────────────────────────────────────────────────
+module.exports = {
+    cmdVerifySummary,
+    cmdVerifyPlanStructure,
+    cmdVerifyPhaseCompleteness,
+    cmdVerifyReferences,
+    cmdVerifyCommits,
+    cmdVerifyArtifacts,
+    cmdVerifyKeyLinks,
+    cmdVerifyMechanical,
+    cmdDiagnosePhase,
+    clearVerifyCache,
+};
+//# sourceMappingURL=verify.js.map