@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/codebase-to-spec/summary.js

@@ -0,0 +1,183 @@
+/**
+ * Pipeline summary generation.
+ *
+ * Reads cached artifacts to assemble a structured summary of what the
+ * pipeline produced. Surfaced both as JSON (parseable by wrappers like the
+ * skill) and as a short human-readable block.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-4: Final pipeline summary is surfaced
+ * - CTS-OBSERVE-2 (partial): structured failure information available
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { sanitizeAreaName } from "./fan-out.js";
+import { parseOutlineReview, parseSpecReview, } from "./schemas.js";
+/**
+ * Count top-level requirements in a file by counting fenced
+ * \`\`\`dotrequirements blocks. Each block represents one root requirement
+ * (CTS-OBSERVE-2 counts each requirement ID once, excluding child criteria).
+ */
+function countRequirementsInFile(path) {
+    if (!existsSync(path))
+        return 0;
+    const content = readFileSync(path, "utf-8");
+    const matches = content.match(/```dotrequirements\b/g);
+    return matches ? matches.length : 0;
+}
+/**
+ * Look at outline-review-N.json files in the cache and return how many turns
+ * ran and what the final verdict was. Returns {turnsUsed: 0, finalVerdict: null}
+ * if no review artifacts exist.
+ */
+function summarizeOutlineReview(paths) {
+    let n = 0;
+    let lastReviewPath = null;
+    while (true) {
+        const path = paths.outlineReviewTurn(n + 1);
+        if (!existsSync(path))
+            break;
+        n++;
+        lastReviewPath = path;
+    }
+    if (!lastReviewPath)
+        return { turnsUsed: 0, finalVerdict: null, residualNotes: [] };
+    try {
+        const review = parseOutlineReview(readFileSync(lastReviewPath, "utf-8"));
+        const notes = [];
+        // Surface unresolved findings as residual notes if verdict isn't 'approved'.
+        if (review.verdict !== "approved") {
+            for (const cat of [
+                ["coverage_gap", review.coverage_gaps],
+                ["framing_error", review.framing_errors],
+                ["granularity", review.granularity_issues],
+                ["file_assignment", review.file_assignment_issues],
+            ]) {
+                for (const note of cat[1]) {
+                    notes.push(`outline.${cat[0]}: ${note}`);
+                }
+            }
+        }
+        return { turnsUsed: n, finalVerdict: review.verdict, residualNotes: notes };
+    }
+    catch {
+        return { turnsUsed: n, finalVerdict: null, residualNotes: [] };
+    }
+}
+function summarizeSpecReview(paths) {
+    let n = 0;
+    let lastReviewPath = null;
+    while (true) {
+        const path = paths.specReviewTurn(n + 1);
+        if (!existsSync(path))
+            break;
+        n++;
+        lastReviewPath = path;
+    }
+    if (!lastReviewPath)
+        return { turnsUsed: 0, finalVerdict: null, residualNotes: [] };
+    try {
+        const review = parseSpecReview(readFileSync(lastReviewPath, "utf-8"));
+        const notes = [];
+        if (review.verdict !== "approved") {
+            for (const cat of [
+                ["coverage_gap", review.coverage_gaps],
+                ["framing_error", review.framing_errors],
+                ["cross_area", review.cross_area_issues],
+                ["internal_mechanics", review.internal_mechanics_drift],
+            ]) {
+                for (const note of cat[1]) {
+                    notes.push(`spec.${cat[0]}: ${note}`);
+                }
+            }
+        }
+        return { turnsUsed: n, finalVerdict: review.verdict, residualNotes: notes };
+    }
+    catch {
+        return { turnsUsed: n, finalVerdict: null, residualNotes: [] };
+    }
+}
+function summarizeSpecifiers(outline, paths) {
+    let completed = 0;
+    const missingAreas = [];
+    for (const area of outline.areas) {
+        const partialPath = paths.partial(sanitizeAreaName(area.name));
+        if (!existsSync(partialPath)) {
+            missingAreas.push(area.name);
+            continue;
+        }
+        const content = readFileSync(partialPath, "utf-8").trim();
+        if (!content ||
+            content.startsWith("_(missing partial") ||
+            content.startsWith("_(no files")) {
+            missingAreas.push(area.name);
+            continue;
+        }
+        completed++;
+    }
+    return { completed, missing: missingAreas.length, missingAreas };
+}
+export function buildPipelineSummary(input) {
+    const { outline, paths, outputPaths } = input;
+    const outlineReview = summarizeOutlineReview(paths);
+    const specReview = summarizeSpecReview(paths);
+    const specifiers = summarizeSpecifiers(outline, paths);
+    // Count top-level requirements across all written .requirements/ files.
+    let totalRequirements = 0;
+    for (const path of outputPaths) {
+        totalRequirements += countRequirementsInFile(path);
+    }
+    // Fall back to counting the final cached spec if nothing was written (e.g.
+    // dry-run / interrupted) — that way the summary still reflects what the
+    // pipeline produced.
+    if (totalRequirements === 0 && existsSync(paths.specFinal)) {
+        totalRequirements = countRequirementsInFile(paths.specFinal);
+    }
+    return {
+        totalAreas: outline.areas.length,
+        totalRequirements,
+        outline: outlineReview,
+        specifiers,
+        specReview,
+        outputs: { paths: outputPaths },
+    };
+}
+/**
+ * Render a short human-readable block for the summary. Designed to fit on a
+ * small number of lines (CTS-PRESENT-4.2). Wrappers that want richer
+ * presentation can read the JSON form instead.
+ */
+export function renderSummaryText(summary) {
+    const lines = [];
+    lines.push(`Pipeline summary:`);
+    lines.push(`  Areas:               ${summary.totalAreas}`);
+    lines.push(`  Top-level reqs:      ${summary.totalRequirements}`);
+    lines.push(`  Outline review:      ${summary.outline.turnsUsed} turn(s), verdict: ${summary.outline.finalVerdict ?? "n/a"}`);
+    lines.push(`  Specifiers:          ${summary.specifiers.completed} completed, ${summary.specifiers.missing} missing`);
+    lines.push(`  Spec review:         ${summary.specReview.turnsUsed} turn(s), verdict: ${summary.specReview.finalVerdict ?? "n/a"}`);
+    lines.push(`  Output files:`);
+    for (const path of summary.outputs.paths) {
+        lines.push(`    - ${path}`);
+    }
+    if (summary.outline.residualNotes.length ||
+        summary.specReview.residualNotes.length) {
+        lines.push(``);
+        lines.push(`  Residual notes (worth reviewing manually):`);
+        for (const note of [
+            ...summary.outline.residualNotes,
+            ...summary.specReview.residualNotes,
+        ]) {
+            lines.push(`    - ${note}`);
+        }
+    }
+    if (summary.specifiers.missingAreas.length) {
+        lines.push(``);
+        lines.push(`  Missing specifier output for:`);
+        for (const area of summary.specifiers.missingAreas) {
+            lines.push(`    - ${area}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Suppress unused-var warning. */
+void statSync;
+//# sourceMappingURL=summary.js.map

package/dist/codebase-to-spec/validate.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Local schema validation for a partial-spec file.
+ *
+ * Mirrors the existing `dotrequirements validate` path (and the
+ * `mcp__dotrequirements__validate_requirements` MCP tool), but works on
+ * partial files — which lack YAML frontmatter — by synthesizing a minimal
+ * wrapper before running the canonical parser.
+ *
+ * This is a deterministic syntax check: it catches things like missing
+ * `→`/`->` arrows, malformed position paths, indentation/position mismatches,
+ * and duplicate IDs — things the AI-driven style-check is not guaranteed
+ * to notice.
+ *
+ * Convention from CLAUDE.md: validate before style-check. Validate is the
+ * cheap, deterministic gate; style-check is the AI clarity pass.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local schema validator on its draft,
+ *   then a local style-check, applying feedback from each.
+ */
+export interface ValidateOptions {
+    /** Path to the partial-spec file to validate. */
+    partialPath: string;
+}
+export interface ValidateResult {
+    /** True if the partial parsed cleanly. */
+    ok: boolean;
+    /** Human-readable error message when `ok === false`. */
+    error?: string;
+    /** Number of requirement blocks found (when `ok === true`). */
+    requirementCount?: number;
+}
+/**
+ * Validate a partial-spec file. Reads the file, synthesizes a frontmatter
+ * envelope, and delegates to the canonical parser. Errors are surfaced as
+ * a single human-readable string so the calling agent can act on them as
+ * MUST FIX items.
+ */
+export declare function runValidate(options: ValidateOptions): ValidateResult;
+/**
+ * Format a ValidateResult as the Markdown feedback block the specifier
+ * agent reads on stdout. Mirrors the severity-categorized shape produced
+ * by `runStyleCheck`, so the prompt can describe them uniformly.
+ */
+export declare function formatValidateFeedback(result: ValidateResult): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/codebase-to-spec/validate.js

@@ -0,0 +1,130 @@
+/**
+ * Local schema validation for a partial-spec file.
+ *
+ * Mirrors the existing `dotrequirements validate` path (and the
+ * `mcp__dotrequirements__validate_requirements` MCP tool), but works on
+ * partial files — which lack YAML frontmatter — by synthesizing a minimal
+ * wrapper before running the canonical parser.
+ *
+ * This is a deterministic syntax check: it catches things like missing
+ * `→`/`->` arrows, malformed position paths, indentation/position mismatches,
+ * and duplicate IDs — things the AI-driven style-check is not guaranteed
+ * to notice.
+ *
+ * Convention from CLAUDE.md: validate before style-check. Validate is the
+ * cheap, deterministic gate; style-check is the AI clarity pass.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local schema validator on its draft,
+ *   then a local style-check, applying feedback from each.
+ */
+import { readFileSync } from "node:fs";
+import { parseRequirementsFile } from "../schema/parser.js";
+import { ValidationError } from "../schema/schemas.js";
+/**
+ * Wrap a partial in a synthetic frontmatter envelope so the canonical
+ * Markdown-with-frontmatter parser can validate it.
+ */
+function wrapPartial(partialBody) {
+    return [
+        "---",
+        "document:",
+        '  title: "Codebase-to-spec partial"',
+        "---",
+        "",
+        partialBody,
+    ].join("\n");
+}
+/**
+ * Validate a partial-spec file. Reads the file, synthesizes a frontmatter
+ * envelope, and delegates to the canonical parser. Errors are surfaced as
+ * a single human-readable string so the calling agent can act on them as
+ * MUST FIX items.
+ */
+export function runValidate(options) {
+    let content;
+    try {
+        content = readFileSync(options.partialPath, "utf-8");
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: `Could not read ${options.partialPath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Sanity check: the partial should contain at least one fenced
+    // dotrequirements block. A partial with no blocks is also a syntax error
+    // worth surfacing as MUST FIX.
+    if (!/```dotrequirements\s/.test(content)) {
+        return {
+            ok: false,
+            error: "No `dotrequirements` fenced code blocks found in partial. Every requirement must live inside a ```dotrequirements ... ``` block.",
+        };
+    }
+    try {
+        const parsed = parseRequirementsFile(wrapPartial(content));
+        return {
+            ok: true,
+            requirementCount: parsed.requirements.length,
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: describeValidationError(err),
+        };
+    }
+}
+/**
+ * The canonical parser wraps low-level failures (e.g. "Each criterion line
+ * must contain the delimiter `->` or `→`") inside a high-level ValidationError
+ * (e.g. "Failed to parse requirement FOO-001"). We want both — the high-level
+ * context tells the agent which block to fix, the low-level reason tells it
+ * what to fix.
+ */
+function describeValidationError(err) {
+    if (err instanceof ValidationError) {
+        const parts = [err.message];
+        let cursor = err.cause;
+        while (cursor instanceof Error) {
+            // Don't repeat the same message twice if the wrapper just rethrew.
+            if (cursor.message && cursor.message !== parts[parts.length - 1]) {
+                parts.push(cursor.message);
+            }
+            cursor = cursor.cause;
+        }
+        return parts.join(" — ");
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
+/**
+ * Format a ValidateResult as the Markdown feedback block the specifier
+ * agent reads on stdout. Mirrors the severity-categorized shape produced
+ * by `runStyleCheck`, so the prompt can describe them uniformly.
+ */
+export function formatValidateFeedback(result) {
+    if (result.ok) {
+        return [
+            "# Schema validation: PASS",
+            "",
+            `${result.requirementCount ?? 0} requirement block(s) parsed cleanly.`,
+            "",
+            "No syntax issues. Proceed to the style-check step.",
+            "",
+        ].join("\n");
+    }
+    return [
+        "# Schema validation: FAIL",
+        "",
+        "## MUST FIX",
+        "",
+        `- ${result.error}`,
+        "",
+        "Fix the syntax issue above with the Edit tool, then re-run validate.",
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/acceptance-test.d.ts

@@ -0,0 +1,6 @@
+interface AcceptanceTestOptions {
+    json?: boolean;
+}
+export declare function acceptanceTestCommand(requirementKey: string, url: string | undefined, options: AcceptanceTestOptions): Promise<void>;
+export {};
+//# sourceMappingURL=acceptance-test.d.ts.map

package/dist/commands/{browsertest.js → acceptance-test.js}

@@ -1,30 +1,30 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
-import { getProjectInfo, readProjectSettings, } from '../utils/project-settings.js';
-import { loadAllRequirements, getRequirementTree, formatRequirement, } from '../mcp/requirements.js';
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { formatRequirement, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
+import { getProjectInfo, readProjectSettings, } from "../utils/project-settings.js";
 const execFileAsync = promisify(execFile);
 function extractResults(parsed) {
     if (Array.isArray(parsed))
         return parsed;
-    if (parsed && typeof parsed === 'object') {
+    if (parsed && typeof parsed === "object") {
         const obj = parsed;
         // { results: [...] } format
         if (Array.isArray(obj.results))
             return obj.results;
         // { structured_output: { results: [...] } } format
-        if (obj.structured_output && typeof obj.structured_output === 'object') {
+        if (obj.structured_output && typeof obj.structured_output === "object") {
             const so = obj.structured_output;
             if (Array.isArray(so.results))
                 return so.results;
         }
     }
-    throw new Error('Unexpected browser-automation output format');
+    throw new Error("Unexpected browser-automation output format");
 }
-export async function browserTestCommand(requirementKey, url, options) {
+export async function acceptanceTestCommand(requirementKey, url, options) {
     // 1. Find project and load settings
     const projectInfo = getProjectInfo();
     if (!projectInfo) {
-        console.error('Error: No dotrequirements project found.');
+        console.error("Error: No dotrequirements project found.");
         console.log('Run "dotrequirements init" to create one.');
         process.exit(1);
     }
@@ -40,7 +40,7 @@ export async function browserTestCommand(requirementKey, url, options) {
     // 2. Determine URL
     const targetURL = url || settings?.defaultURL;
     if (!targetURL) {
-        console.error('Error: No URL provided and no defaultURL in project-settings.json.');
+        console.error("Error: No URL provided and no defaultURL in project-settings.json.");
         console.log('Either provide a URL argument or add "defaultURL" to .requirements/project-settings.json');
         process.exit(1);
     }
@@ -49,23 +49,23 @@ export async function browserTestCommand(requirementKey, url, options) {
     const modelApiKey = settings?.browserTest?.modelApiKey;
     const geminiApiKey = settings?.browserTest?.geminiApiKey;
     if (!modelName && !modelApiKey && !geminiApiKey) {
-        console.error('Error: no browser-test model configured in project-settings.json.');
-        console.log('Add a block like:\n' +
+        console.error("Error: no browser-test model configured in project-settings.json.");
+        console.log("Add a block like:\n" +
             '  "browserTest": {\n' +
             '    "modelName": "gateway/anthropic/claude-haiku-4-5",\n' +
             '    "modelApiKey": "..."\n' +
-            '  }\n' +
-            'to .requirements/project-settings.json. See the docs for supported models.');
+            "  }\n" +
+            "to .requirements/project-settings.json. See the docs for supported models.");
         process.exit(1);
     }
     if ((modelName && !modelApiKey) || (modelApiKey && !modelName)) {
-        console.error('Error: browserTest.modelName and browserTest.modelApiKey must be set together.');
+        console.error("Error: browserTest.modelName and browserTest.modelApiKey must be set together.");
         process.exit(1);
     }
     // 4. Load requirements
     const { flattened } = await loadAllRequirements(projectInfo.rootPath);
     if (flattened.length === 0) {
-        console.error('Error: No requirements found in .requirements/');
+        console.error("Error: No requirements found in .requirements/");
         process.exit(1);
     }
     // 5. Find the requirement tree
@@ -86,7 +86,8 @@ export async function browserTestCommand(requirementKey, url, options) {
         env.GEMINI_API_KEY = geminiApiKey;
     }
     if (settings?.browserTest?.vercelBypassSecret) {
-        env.VERCEL_AUTOMATION_BYPASS_SECRET = settings.browserTest.vercelBypassSecret;
+        env.VERCEL_AUTOMATION_BYPASS_SECRET =
+            settings.browserTest.vercelBypassSecret;
     }
     if (settings?.browserTest?.browserbaseApiKey) {
         env.BROWSERBASE_API_KEY = settings.browserTest.browserbaseApiKey;
@@ -99,8 +100,14 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
     }
     try {
-        const modelFlags = modelName ? ['--modelName', modelName] : [];
-        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', ...modelFlags, targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        const modelFlags = modelName ? ["--modelName", modelName] : [];
+        const { stdout } = await execFileAsync("npx", [
+            "@popoverai/browser-automation",
+            "test",
+            ...modelFlags,
+            targetURL,
+            ...assertions,
+        ], { env, maxBuffer: 10 * 1024 * 1024 });
         // 9. Parse results
         let results;
         try {
@@ -108,7 +115,7 @@ export async function browserTestCommand(requirementKey, url, options) {
             results = extractResults(parsed);
         }
         catch (parseErr) {
-            console.error('Error: Could not parse browser-automation output');
+            console.error("Error: Could not parse browser-automation output");
             console.error(parseErr.message);
             console.error(stdout);
             process.exit(1);
@@ -121,7 +128,7 @@ export async function browserTestCommand(requirementKey, url, options) {
             displayResults(requirementTree, results);
         }
         // 11. Exit with appropriate code
-        const failedCount = results.filter((r) => r.status !== 'passed').length;
+        const failedCount = results.filter((r) => r.status !== "passed").length;
         if (failedCount > 0) {
             process.exit(1);
         }
@@ -143,7 +150,7 @@ export async function browserTestCommand(requirementKey, url, options) {
             }
             catch {
                 // Not JSON, show raw output
-                console.error('browser-automation error:');
+                console.error("browser-automation error:");
                 if (error.stdout)
                     console.error(error.stdout);
                 if (error.stderr)
@@ -170,14 +177,14 @@ function displayResults(requirements, results) {
             failedCount++;
             continue;
         }
-        const indent = '  '.repeat(req.path.length);
-        const label = req.label ? ` (${req.label})` : '';
-        const icon = result.status === 'passed' ? '\u2713' : '\u2717';
+        const indent = "  ".repeat(req.path.length);
+        const label = req.label ? ` (${req.label})` : "";
+        const icon = result.status === "passed" ? "\u2713" : "\u2717";
         console.log(`${indent}${icon} ${req.id}${label}: ${req.content}`);
-        if (result.status !== 'passed' && result.notes) {
+        if (result.status !== "passed" && result.notes) {
             console.log(`${indent}  \u2192 ${result.notes}`);
         }
-        if (result.status === 'passed') {
+        if (result.status === "passed") {
             passedCount++;
         }
         else {
@@ -197,9 +204,9 @@ function outputJson(requirements, results) {
         id: req.id,
         label: req.label || null,
         content: req.content,
-        status: results[i]?.status || 'blocked',
+        status: results[i]?.status || "blocked",
         notes: results[i]?.notes || null,
     }));
     console.log(JSON.stringify(combined, null, 2));
 }
-//# sourceMappingURL=browsertest.js.map
+//# sourceMappingURL=acceptance-test.js.map

package/dist/commands/ai-setup.d.ts

@@ -0,0 +1,5 @@
+/**
+ * AI setup command - configures the MCP server for AI assistants
+ */
+export declare function aiSetupCommand(): Promise<void>;
+//# sourceMappingURL=ai-setup.d.ts.map