@popoverai/dotrequirements 0.23.0 → 0.24.0

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

@@ -0,0 +1,111 @@
+/**
+ * Slice extraction: given a Repomix pack and a list of file paths (or
+ * directory-prefix paths), produce a smaller pack containing only the matching
+ * files.
+ *
+ * Pack format (from Repomix --style plain):
+ *
+ *   ================
+ *   File: path/to/file
+ *   ================
+ *   <file contents>
+ *
+ *   ================
+ *   File: next/file
+ *   ================
+ *   ...
+ *
+ * We preserve the pack header (everything before the first File: section) and
+ * the matching sections.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: CLI fans out one specifier worker per area; each worker
+ *   receives a slice extracted from the uncompressed pack
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+const SEPARATOR = "================";
+const FILE_PREFIX = "File: ";
+/**
+ * Return true when `path` matches one of the entries in `wanted`.
+ *
+ * Each entry can be:
+ * - An exact file path (e.g., `src/foo.ts`) — matches that exact path.
+ * - A directory prefix ending in `/` (e.g., `src/services/browser/`) — matches
+ *   any file under that directory tree.
+ */
+export function pathMatchesWanted(path, wanted) {
+    for (const w of wanted) {
+        if (w === path)
+            return true;
+        if (w.endsWith("/") && path.startsWith(w))
+            return true;
+    }
+    return false;
+}
+/**
+ * Extract sections matching `wanted` from the pack at `inputPath` and write
+ * them to `outputPath`. Preserves the pack header (Repomix metadata).
+ */
+export function extractSlice(inputPath, outputPath, wanted) {
+    const wantedSet = new Set(wanted);
+    const text = readFileSync(inputPath, "utf-8");
+    return extractSliceFromText(text, outputPath, wantedSet);
+}
+/**
+ * Pure variant operating on already-loaded text. Useful for tests.
+ */
+export function extractSliceFromText(text, outputPath, wanted) {
+    const wantedSet = wanted instanceof Set ? wanted : new Set(wanted);
+    const lines = text.split("\n");
+    const out = [];
+    // Find the start of the first File: section.
+    let firstFileIdx = -1;
+    for (let i = 0; i + 1 < lines.length; i++) {
+        if (lines[i].trim() === SEPARATOR && lines[i + 1].startsWith(FILE_PREFIX)) {
+            firstFileIdx = i;
+            break;
+        }
+    }
+    if (firstFileIdx === -1) {
+        throw new Error("Input pack has no File: sections");
+    }
+    // Preserve the pack header (lines 0..firstFileIdx-1).
+    for (let i = 0; i < firstFileIdx; i++) {
+        out.push(lines[i]);
+    }
+    let matched = 0;
+    let total = 0;
+    let i = firstFileIdx;
+    while (i < lines.length) {
+        if (lines[i].trim() === SEPARATOR &&
+            i + 1 < lines.length &&
+            lines[i + 1].startsWith(FILE_PREFIX)) {
+            const path = lines[i + 1].slice(FILE_PREFIX.length).trim();
+            total++;
+            // Find the end of this section (next ====/File: pair or EOF).
+            let j = i + 3; // past the closing separator
+            while (j < lines.length) {
+                if (lines[j].trim() === SEPARATOR &&
+                    j + 1 < lines.length &&
+                    lines[j + 1].startsWith(FILE_PREFIX)) {
+                    break;
+                }
+                j++;
+            }
+            const contentEnd = j; // exclusive
+            if (pathMatchesWanted(path, wantedSet)) {
+                matched++;
+                for (let k = i; k < contentEnd; k++) {
+                    out.push(lines[k]);
+                }
+            }
+            i = j;
+        }
+        else {
+            i++;
+        }
+    }
+    writeFileSync(outputPath, out.join("\n"), "utf-8");
+    return { matched, total };
+}
+//# sourceMappingURL=slice.js.map

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

@@ -0,0 +1,60 @@
+/**
+ * Specifier worker: run a single specifier for one area.
+ *
+ * The specifier is given its slice + the outline + a target partial path, and
+ * it orchestrates its own work via tools (Read, Write, Edit, Grep, Glob, Bash).
+ * Self-style-check happens via `Bash dotrequirements cts style-check <path>`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: per-area worker invocation
+ * - CTS-SPEC-2: write partial to known path via Write tool
+ * - CTS-SPEC-3: self-style-check via Bash
+ * - CTS-SPEC-4: access to the full pack for cross-area context
+ * - CTS-SPEC-5: failure detection and retry orchestrated by fan-out (this file
+ *   produces a single attempt; fan-out wraps it with retry policy)
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { Area, Outline } from "./schemas.js";
+export interface SpecifierContext {
+    outline: Outline;
+    area: Area;
+    /** Path to the area's slice (extracted from the uncompressed pack). */
+    slicePath: string;
+    /** Path to the full uncompressed pack (for cross-area discovery). */
+    fullPackPath: string;
+    /** Where the specifier should write its partial. */
+    partialPath: string;
+    /**
+     * The command the specifier should run to invoke schema validation on its
+     * own partial — typically `dotrequirements cts validate`. Run BEFORE
+     * style-check.
+     */
+    validateCommand: string;
+    /**
+     * The command the specifier should run to invoke style-check on its own
+     * partial — typically `dotrequirements cts style-check`. Run AFTER
+     * validate.
+     */
+    styleCheckCommand: string;
+    /** Directories the agent should have read+write access to. */
+    addDirs: string[];
+    runner?: ClaudeRunner;
+    model?: string;
+}
+export interface SpecifierResult {
+    /** True if the agent wrote a non-empty partial file at the expected path. */
+    wrotePartial: boolean;
+    /** Size of the partial in bytes, or 0 if missing. */
+    partialBytes: number;
+    /** Process exit code. */
+    exitCode: number;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+}
+/**
+ * Run a single specifier. Returns details about whether it succeeded.
+ */
+export declare function runSpecifier(ctx: SpecifierContext): Promise<SpecifierResult>;
+//# sourceMappingURL=specifier.d.ts.map

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

@@ -0,0 +1,79 @@
+/**
+ * Specifier worker: run a single specifier for one area.
+ *
+ * The specifier is given its slice + the outline + a target partial path, and
+ * it orchestrates its own work via tools (Read, Write, Edit, Grep, Glob, Bash).
+ * Self-style-check happens via `Bash dotrequirements cts style-check <path>`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1: per-area worker invocation
+ * - CTS-SPEC-2: write partial to known path via Write tool
+ * - CTS-SPEC-3: self-style-check via Bash
+ * - CTS-SPEC-4: access to the full pack for cross-area context
+ * - CTS-SPEC-5: failure detection and retry orchestrated by fan-out (this file
+ *   produces a single attempt; fan-out wraps it with retry policy)
+ */
+import { existsSync, statSync } from "node:fs";
+import { runClaude } from "./claude.js";
+import { SPECIFIER_PROMPT } from "./prompts/specifier.js";
+function buildUserMessage(ctx) {
+    return [
+        `You are specifying ONE area of the system.`,
+        ``,
+        `Area name: ${ctx.area.name}`,
+        `Area description: ${ctx.area.description}`,
+        `Document defaultPrefix: ${ctx.outline.defaultPrefix}`,
+        `Area prefix: ${ctx.area.prefix}`,
+        `Use full requirement IDs of the form: ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-1, ${ctx.outline.defaultPrefix}-${ctx.area.prefix}-2, etc. (sequential, 1-indexed, no zero-padding).`,
+        ``,
+        `## Paths`,
+        `- Slice (your area's files): ${ctx.slicePath}`,
+        `- Full uncompressed pack (for discovering behaviors in tests/recipes/docs): ${ctx.fullPackPath}`,
+        `- Where to write your partial: ${ctx.partialPath}`,
+        `- Validate command (run FIRST after writing your draft — deterministic syntax check):`,
+        `    Bash: ${ctx.validateCommand} ${ctx.partialPath}`,
+        `- Style-check command (run SECOND, only after validate passes — AI clarity feedback):`,
+        `    Bash: ${ctx.styleCheckCommand} ${ctx.partialPath}`,
+        ``,
+        `## Full system outline (so you know what is in scope vs. not)`,
+        `\`\`\`json`,
+        JSON.stringify(ctx.outline, null, 2),
+        `\`\`\``,
+        ``,
+        `Follow the three-phase workflow in your system prompt: draft (Phase A) → validate (Phase B) → style-check (Phase C) → confirm.`,
+    ].join("\n");
+}
+/**
+ * Run a single specifier. Returns details about whether it succeeded.
+ */
+export async function runSpecifier(ctx) {
+    const runner = ctx.runner ?? runClaude;
+    const result = await runner({
+        systemPrompt: SPECIFIER_PROMPT,
+        userMessage: buildUserMessage(ctx),
+        model: ctx.model,
+        tools: ["Read", "Write", "Edit", "Grep", "Glob", "Bash"],
+        addDirs: ctx.addDirs,
+    });
+    // Inspect the partial file to determine whether the specifier wrote
+    // something usable.
+    let wrotePartial = false;
+    let partialBytes = 0;
+    if (existsSync(ctx.partialPath)) {
+        try {
+            partialBytes = statSync(ctx.partialPath).size;
+            wrotePartial = partialBytes > 0;
+        }
+        catch {
+            // ignore; treat as not written
+        }
+    }
+    return {
+        wrotePartial,
+        partialBytes,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+//# sourceMappingURL=specifier.js.map

package/dist/codebase-to-spec/style-check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Local style-check function — produces severity-categorized feedback on a
+ * partial-spec file using a fresh, stateless claude -p call.
+ *
+ * Mirrors the existing cloud `mcp__dotrequirements__style_check` pattern but
+ * runs entirely offline (no cloud credentials, no account required), since
+ * the codebase-to-spec target audience does not yet have a dotrequirements
+ * account.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+import { type ClaudeRunner } from "./claude.js";
+export interface StyleCheckOptions {
+    partialPath: string;
+    runner?: ClaudeRunner;
+    model?: string;
+}
+export interface StyleCheckResult {
+    /** The categorized feedback (Markdown). */
+    feedback: string;
+    /** Process exit code from the claude -p subprocess. */
+    exitCode: number;
+}
+/**
+ * Run a style check on a partial-spec file and return the feedback as Markdown.
+ */
+export declare function runStyleCheck(options: StyleCheckOptions): Promise<StyleCheckResult>;
+//# sourceMappingURL=style-check.d.ts.map

package/dist/codebase-to-spec/style-check.js

@@ -0,0 +1,33 @@
+/**
+ * Local style-check function — produces severity-categorized feedback on a
+ * partial-spec file using a fresh, stateless claude -p call.
+ *
+ * Mirrors the existing cloud `mcp__dotrequirements__style_check` pattern but
+ * runs entirely offline (no cloud credentials, no account required), since
+ * the codebase-to-spec target audience does not yet have a dotrequirements
+ * account.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+import { dirname } from "node:path";
+import { runClaude } from "./claude.js";
+import { STYLE_CHECK_PROMPT } from "./prompts/style-check.js";
+/**
+ * Run a style check on a partial-spec file and return the feedback as Markdown.
+ */
+export async function runStyleCheck(options) {
+    const runner = options.runner ?? runClaude;
+    const result = await runner({
+        systemPrompt: STYLE_CHECK_PROMPT,
+        userMessage: `Run a style check on the partial spec at ${options.partialPath}. Read the file via the Read tool and produce categorized Markdown feedback per your system prompt.`,
+        model: options.model,
+        tools: ["Read"],
+        addDirs: [dirname(options.partialPath)],
+    });
+    return {
+        feedback: result.stdout,
+        exitCode: result.exitCode,
+    };
+}
+//# sourceMappingURL=style-check.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * 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 type { CachePaths } from "./cache.js";
+import { type Outline } from "./schemas.js";
+export interface PipelineSummary {
+    totalAreas: number;
+    totalRequirements: number;
+    outline: {
+        turnsUsed: number;
+        finalVerdict: string | null;
+        residualNotes: string[];
+    };
+    specifiers: {
+        completed: number;
+        missing: number;
+        /** Area names that have no usable partial. */
+        missingAreas: string[];
+    };
+    specReview: {
+        turnsUsed: number;
+        finalVerdict: string | null;
+        residualNotes: string[];
+    };
+    outputs: {
+        /** Paths under .requirements/ that were written. */
+        paths: string[];
+    };
+}
+export interface BuildSummaryInput {
+    outline: Outline;
+    paths: CachePaths;
+    /** Paths the present stage wrote (under .requirements/). */
+    outputPaths: string[];
+}
+export declare function buildPipelineSummary(input: BuildSummaryInput): PipelineSummary;
+/**
+ * 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 declare function renderSummaryText(summary: PipelineSummary): string;
+//# sourceMappingURL=summary.d.ts.map

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