@popoverai/dotrequirements 0.33.0 → 0.34.0

package/dist/rehearsal/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * A rehearsal (docs/working/rehearsing-steps.md): a plan of outcomes, the
+ * artifacts its inputs hold, and who plays each agent the backend sends
+ * for — a real one, or a script that plays it from the brief the agent
+ * would get.
+ */
+export type Thing = {
+    kind: "document";
+    documentId: string;
+} | {
+    kind: "board";
+    boardId: string;
+} | {
+    kind: "mockup";
+    mockupId: string;
+} | {
+    kind: "file";
+    path: string;
+    branch?: string;
+} | {
+    kind: "link";
+    url: string;
+    title?: string;
+}
+/** Something running in the sandbox, with the title a script names it by, if any (SIGHT-12.3). */
+ | {
+    kind: "preview";
+    port: number;
+    page?: string;
+    command: string;
+    title?: string;
+}
+/** The solution's pull request: a script submits it as given, checked against no repository (PULL-3.3). */
+ | {
+    kind: "pull request";
+    url: string;
+    number: number;
+}
+/** An image kept under its file name (SIGHT-9), as a scenario gives one to an input (REHEARSE-4.7). */
+ | {
+    kind: "image";
+    storageId: string;
+    name: string;
+} | ({
+    kind: "scores";
+} & Scores);
+/** One axis of a solution's scores: a whole number from 1 to 5, and why. */
+export type AxisScore = {
+    score: number;
+    reason: string;
+};
+/** A solution's scores, by axis (SCORES-1), as `dotreq scores create` makes them. */
+export type Scores = {
+    costOfDelay: AxisScore;
+    relevance: AxisScore;
+    entities: AxisScore;
+    api: AxisScore;
+    testing: AxisScore;
+    experience: AxisScore;
+    doubt: AxisScore;
+};
+/** A thing as a drafter submits it: where it is, or scores by the id `createScores` gave. */
+export type Submission = Exclude<Thing, {
+    kind: "scores";
+}> | {
+    kind: "scores";
+    scoresId: string;
+};
+/** One outcome in a plan (`PlanOutcome` in packages/convex/solutions/plan/format.ts). */
+export type PlanOutcome = {
+    name: string;
+    /** A surface's name, or another outcome's, as the scores are on the pitch. */
+    on: string;
+    awaits?: string[];
+    reviewAwaits?: string[];
+    against?: string[];
+    /** One of the plan's agents; left out, an agent dedicated to it: "<name>/drafter". */
+    drafter?: string;
+    /** The plan's agents; left out, one dedicated to it: "<name>/reviewer". Empty: no review. */
+    reviewers?: string[];
+    /** The agent the owner makes it with in a conversation. */
+    createdWith?: string;
+    /** Someone outside the product who makes it. */
+    createdBy?: string;
+    model?: string;
+    instructions?: string;
+    reviewInstructions?: string;
+};
+/** The plan in its stored shape (`OutcomePlan` in packages/convex/solutions/plan/format.ts). */
+export type Plan = {
+    format: "outcomes";
+    inputs: string[];
+    surfaces: Array<{
+        name: string;
+        kind: string;
+    }>;
+    phases: Array<{
+        name: string;
+        class?: string;
+        outcomes: PlanOutcome[];
+    }>;
+    checkpoints: Array<{
+        name: string;
+        on: string;
+        presents?: string[];
+    }>;
+    agents: Array<{
+        name: string;
+        model?: string;
+        instructions?: string;
+    }>;
+    loops: Array<{
+        name: string;
+        iterations?: string[];
+        through: string[];
+    }>;
+};
+/**
+ * Part of a plan to rehearse (REHEARSE-1.0, 1.6): some of its outcomes,
+ * each by its name, run as though the outcomes before them were made.
+ */
+export type PlanPart = {
+    from: Plan;
+    outcomes: string[];
+};
+/** What a script does when the agent it plays gets its brief. */
+export type Script = {
+    /** Assert on the brief; throw to fail the rehearsal here (REHEARSE-2.1). */
+    expect?: (brief: unknown) => void;
+    /** Submit these things (drafting), with a comment saying what changed and why. */
+    made?: Submission[];
+    /** Make these scores and submit them (drafting scores), as `dotreq scores create` then `author scores:<id>` do, with the comment. */
+    scores?: Scores;
+    comment?: string;
+    /**
+     * With `made` or `scores`: the drafter's executive summary, which an
+     * outcome no agent reviews asks for (VERB-1.6). A script records as a
+     * real agent does (REHEARSE-1.1), so where the outcome asks for one and
+     * the script gives none, the work is refused.
+     */
+    summary?: string;
+    /**
+     * Give this review result (reviewing), with the comment every result
+     * carries. An approval, with or without revisions, carries an executive
+     * summary (VERB-2.5), and needs revision and escalate carry none; a
+     * script that breaks either is refused, as the agent would be
+     * (REHEARSE-1.1).
+     */
+    review?: {
+        outcome: "approved" | "approved with revisions" | "needs revision" | "escalate";
+        comment: string;
+        summary?: string;
+    };
+    /** Put a decision to the person instead (drafting). */
+    ask?: unknown;
+    /** Stall instead. */
+    stall?: string;
+};
+/** Real, or a script; a list plays one script per turn, the last repeating. */
+export type Party = "real" | Script | Script[];
+/**
+ * What the person answers, in order asked: by an outcome's name, her answer
+ * to a question or an escalation on it; by a checkpoint's name, her
+ * decision there, which a rehearsal gives only as an approval.
+ */
+export type PersonScript = Record<string, Array<{
+    kind: "approval";
+    outcome: "approved" | "needs revision";
+    comment?: string;
+} | {
+    kind: "choice";
+    option: string;
+    because?: string;
+}>>;
+/**
+ * The history a rehearsal starts from (REHEARSE-4.8): an earlier
+ * rehearsal's solution, the outcome it made that the new solution starts
+ * after, and the outcomes it holds as they stood then.
+ */
+export type StartingHistory = {
+    solution: string;
+    after: string;
+    outcomes: string[];
+};
+/** A document published from a scenario's file for an input (REHEARSE-4.1). */
+export type Published = {
+    documentId: string;
+    isRequirementsDoc: boolean;
+};
+export type Scenario = {
+    title: string;
+    /** Live only: the scenario file's name, recorded on the solution so the next run of it replaces this one (REHEARSE-6). */
+    file?: string;
+    /** What the person wrote about the solution beyond its title, as Markdown. */
+    description?: string;
+    /**
+     * The whole plan, or some of its outcomes run on their own (REHEARSE-1.0,
+     * 1.6).
+     */
+    plan: Plan | PlanPart;
+    /** The artifacts the plan's inputs hold, by outcome name. */
+    inputs?: Record<string, Thing[]>;
+    /**
+     * Live only: the documents published from the scenario's files for its
+     * inputs, each with whether its file's name makes it a requirements
+     * document (SOLDOC-3). Each comes to belong to the solution and the input
+     * that names it (REHEARSE-4.1.0).
+     */
+    published?: Published[];
+    /**
+     * Live only: the branch the solution's branch is made from, rather than
+     * the repository's default branch, such as one frozen with the output of
+     * the outcomes before the rehearsed ones (REHEARSE-4.5).
+     */
+    branch?: string;
+    /**
+     * Live only: an earlier rehearsal's solution and an outcome it made,
+     * whose history the solution starts with (REHEARSE-4.8), with the
+     * outcomes that solution holds, which may stand for inputs the scenario
+     * doesn't name.
+     */
+    history?: StartingHistory;
+    /**
+     * Who plays each agent (`partiesOf` in driver.ts): by agent, as
+     * `Code Reviewer` or `Pitch/drafter`; by an outcome's name, its drafter,
+     * or whoever outside makes it; by "<outcome>/reviewer", its reviewers; or
+     * by "<outcome>/<agent>", that agent on that outcome alone. Unnamed
+     * agents are real.
+     */
+    parties: Record<string, Party>;
+    person?: PersonScript;
+    /** How long to wait for a real agent, in ms (live only). */
+    waitMs?: number;
+};
+/** An outcome on the plan panel, as the driver reads it (`getPlan`). */
+export type PanelOutcome = {
+    name: string;
+    status: string;
+    drafter?: string;
+    reviewers?: string[];
+    reason?: string;
+    /** Who it waits on, when someone outside makes it. */
+    party?: string;
+};
+/** The plan panel as the driver reads it: its outcomes by phase, and where each checkpoint stands. */
+export type RehearsalPanel = {
+    phases: Array<{
+        outcomes: PanelOutcome[];
+    }>;
+    checkpoints?: Array<{
+        name: string;
+        stands: string;
+    }>;
+};
+/** The client the driver drives: convex-test in tests, the CLI client live. */
+export type RehearsalClient = {
+    create(args: {
+        title: string;
+        /** The scenario file's name, when the rehearsal runs from one. */
+        scenario?: string;
+        description?: string;
+        plan: Plan;
+        inputs: Array<{
+            name: string;
+            things: Thing[];
+        }>;
+        /** The branch the solution's branch is made from, when the scenario names one. */
+        branch?: string;
+        /** The documents published from the scenario's files for its inputs. */
+        published?: Published[];
+        /** The earlier rehearsal whose history the solution starts with, when the scenario names one. */
+        history?: {
+            solution: string;
+            after: string;
+        };
+    }): Promise<string>;
+    /** The plan panel as it stands (`getPlan`). */
+    panel(solutionId: string): Promise<RehearsalPanel | null>;
+    /** What an agent picks up: its brief for the first part of an outcome's work it has due, or nothing ready. */
+    next(args: {
+        solutionId: string;
+        agent: string;
+    }): Promise<{
+        kind: string;
+        [key: string]: unknown;
+    }>;
+    /** Make scores, as `dotreq scores create` does: their id, to submit as `{ kind: "scores", scoresId }`. */
+    createScores(scores: Scores): Promise<string>;
+    /** Record an agent's work or result on an outcome; with no agent, someone outside closing it. */
+    complete(args: {
+        solutionId: string;
+        agent?: string;
+        outcome: string;
+        made?: Submission[];
+        comment?: string;
+        /** With `made`: the drafter's executive summary (VERB-1.6). */
+        summary?: string;
+        review?: {
+            outcome: "approved" | "approved with revisions" | "needs revision" | "escalate";
+            comment: string;
+            /** With an approval: the executive summary (VERB-2.5). */
+            summary?: string;
+        };
+    }): Promise<void>;
+    ask(args: {
+        solutionId: string;
+        agent: string;
+        outcome: string;
+        request: unknown;
+    }): Promise<void>;
+    stall(args: {
+        solutionId: string;
+        agent: string;
+        outcome: string;
+        reason: string;
+    }): Promise<void>;
+    /** The decision open on an outcome — a question or an escalation — or null. Absent when the client can't answer for the person. */
+    openDecision?(solutionId: string, outcome: string): Promise<{
+        id: string;
+    } | null>;
+    answer?(decisionId: string, answer: unknown): Promise<void>;
+    /** Approve a checkpoint's pass waiting on the person. Absent when the client can't decide for the person. */
+    approveCheckpoint?(solutionId: string, checkpoint: string, words?: string): Promise<void>;
+    thread(solutionId: string, outcome: string): Promise<unknown[]>;
+    things(solutionId: string, outcome: string): Promise<Thing[]>;
+    /** Live only: what a real agent did, from its sessions' logs. */
+    agentLog?(solutionId: string, agent: string): Promise<string | null>;
+    /** Live only: wait between polls. */
+    sleep?(ms: number): Promise<void>;
+};
+export type OutcomeReport = {
+    outcome: string;
+    status: string;
+    reason?: string;
+    things: Thing[];
+    thread: unknown[];
+    /** What each real agent on it did, from its log, by agent. */
+    agentLogs?: Record<string, string | null>;
+};
+/** What a live rehearsal did with the earlier runs of its scenario before it started (REHEARSE-6). */
+export type EarlierRuns = {
+    /** The scenario file's name. */
+    scenario: string;
+    /** How many earlier runs it removed. */
+    removed: number;
+    /** Rehearsed with --keep: the earlier runs were left in place. */
+    keep?: boolean;
+    /** What an earlier run made that stayed: named by these scenario files, or, with none, used by another solution. */
+    kept: Array<{
+        reference: string;
+        namedBy: string[];
+    }>;
+    /** Earlier runs that stayed because these scenario files start from their history (REHEARSE-6.2.0). */
+    keptRuns?: Array<{
+        solutionId: string;
+        namedBy: string[];
+    }>;
+    /**
+     * The branches the earlier runs' solutions made (REHEARSE-6.7 to 6.10):
+     * deleted, already gone, kept and why, or still being deleted when the
+     * new run started.
+     */
+    branches?: Array<{
+        name: string;
+        outcome: "deleted" | "gone" | "kept" | "pending";
+        why?: string;
+    }>;
+};
+export type RehearsalReport = {
+    solutionId: string;
+    /** Live only: the earlier runs of its scenario, and what of theirs stayed. */
+    earlier?: EarlierRuns;
+    /** Why it ended: nothing ready, a decision nobody scripted, a stall, or a script's expectation. */
+    ended: string;
+    outcomes: OutcomeReport[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/rehearsal/types.js

@@ -0,0 +1,8 @@
+/**
+ * A rehearsal (docs/working/rehearsing-steps.md): a plan of outcomes, the
+ * artifacts its inputs hold, and who plays each agent the backend sends
+ * for — a real one, or a script that plays it from the brief the agent
+ * would get.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/requirements/index.d.ts

@@ -26,6 +26,12 @@ export interface ParsedRequirementsFile {
  * Excludes example files, test fixtures, and build artifacts.
  */
 export declare function findRequirementsFiles(workspaceRoot: string): Promise<string[]>;
+/**
+ * Every file a sync carries (SOLDOC-8): requirements files anywhere, plus
+ * the Markdown files directly inside solution directories. Other Markdown
+ * is left alone.
+ */
+export declare function findSyncedFiles(workspaceRoot: string): Promise<string[]>;
 /**
  * Synchronous variant of {@link findRequirementsFiles}. Used by code paths
  * that can't await (e.g. the test-harness lookup-cache builder).

package/dist/requirements/index.js

@@ -6,6 +6,8 @@ import { splitLeadingH1 } from "../schema/title-markdown.js";
  * Glob pattern matching *.requirements.md files.
  */
 const REQUIREMENTS_FILE_PATTERN = "**/*.requirements.md";
+/** SOLDOC-8.1: a solution's other documents, directly inside a solution directory. */
+const SOLUTION_DOCUMENT_PATTERN = "**/.requirements/solutions/*/*.md";
 /**
  * Directories ignored when discovering requirements files.
  * Shared between async and sync discovery so the two never drift.
@@ -15,6 +17,9 @@ const REQUIREMENTS_IGNORE_PATTERNS = [
     "**/dist/**",
     "**/.git/**",
     "**/build/**",
+    // Next.js's build output: a dev server's grows to gigabytes, and walking
+    // it made discovery take most of a minute.
+    "**/.next/**",
     // Exclude example and test fixture directories
     "**/example/**",
     "**/examples/**",
@@ -40,6 +45,25 @@ export async function findRequirementsFiles(workspaceRoot) {
     });
     return matches.map((m) => path.join(workspaceRoot, m));
 }
+/**
+ * Every file a sync carries (SOLDOC-8): requirements files anywhere, plus
+ * the Markdown files directly inside solution directories. Other Markdown
+ * is left alone.
+ */
+export async function findSyncedFiles(workspaceRoot) {
+    const [requirements, solutionDocs] = await Promise.all([
+        findRequirementsFiles(workspaceRoot),
+        glob(SOLUTION_DOCUMENT_PATTERN, {
+            cwd: workspaceRoot,
+            ignore: REQUIREMENTS_IGNORE_PATTERNS,
+            dot: true,
+        }),
+    ]);
+    const all = new Set(requirements);
+    for (const m of solutionDocs)
+        all.add(path.join(workspaceRoot, m));
+    return [...all];
+}
 /**
  * Synchronous variant of {@link findRequirementsFiles}. Used by code paths
  * that can't await (e.g. the test-harness lookup-cache builder).

package/dist/schema/browser.d.ts

@@ -6,7 +6,7 @@
 export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER, } from "./builder.js";
 export type { ConvexRequirement } from "./conversions.js";
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
-export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, splitRequirementFenceContent, } from "./parser-core.js";
+export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, ROOT_LABEL_MARKER, splitRequirementFenceContent, stripFrontmatterBlock, } from "./parser-core.js";
 export type { Metadata, ParsedCriterion, RequirementKey, RequirementNode, RequirementPrefix, RequirementsFile, } from "./schemas.js";
 export { buildRequirementKey, canonicalRequirementKey, MetadataSchema, normalizePrefix, ParsedCriterionSchema, parseRequirementKey, REQUIREMENT_KEY_PATTERN, REQUIREMENT_PREFIX_PATTERN, RequirementKeySchema, RequirementNodeSchema, RequirementPrefixSchema, RequirementsFileSchema, ValidationError, validateKey, validateMetadata, validatePrefix, validateRequirementNode, validateRequirementsFile, } from "./schemas.js";
 export { composeMarkdownWithTitle, effectiveTitle, type SplitMarkdown, splitLeadingH1, } from "./title-markdown.js";

package/dist/schema/browser.js

@@ -11,7 +11,9 @@ export { buildMetadata, constructKey, convexToRequirements, extractRequirementKe
 export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, 
 // The web reaches parser-core only through this entry point, so without this
 // its readers have no way to import the marker and must hard-code it.
-ROOT_LABEL_MARKER, splitRequirementFenceContent, } from "./parser-core.js";
+ROOT_LABEL_MARKER, splitRequirementFenceContent, 
+// A requirements file read from a repository in the browser (SOLDOC-12).
+stripFrontmatterBlock, } from "./parser-core.js";
 // Schemas and types (uses zod - browser-safe)
 export { buildRequirementKey, canonicalRequirementKey, 
 // Zod schemas

package/dist/schema/file-writer.d.ts

@@ -60,6 +60,11 @@ export interface OwnedFrontmatter {
     attachments?: AttachmentsDirective;
     /** The cloud version this content is at. */
     version: number;
+    /** SOLDOC-5: the belonging to write; absent means keep what the file says. */
+    belonging?: {
+        solutionId: string;
+        outcome: string;
+    };
 }
 /**
  * Write `body` to `filePath` under the file's own frontmatter, with the owned

package/dist/schema/file-writer.js

@@ -50,6 +50,10 @@ export function writeRequirementsFile(filePath, owned, body) {
         frontmatter.setIn(["document", "attachments"], 
         // Omit absent titles rather than writing `title: null` into the file.
         attachments.set.map((a) => a.title === undefined ? { url: a.url } : { url: a.url, title: a.title }));
+    if (owned.belonging) {
+        frontmatter.setIn(["document", "solution"], owned.belonging.solutionId);
+        frontmatter.setIn(["document", "outcome"], owned.belonging.outcome);
+    }
     // SYNC-TITLE-1.2: `document.title` is a recognized-but-retired field — the
     // title lives in the body as its leading H1 — so a rewrite drops it rather
     // than carrying it forward as if it were one of the user's own fields.

package/dist/schema/parser.d.ts

@@ -13,7 +13,14 @@ export { findRequirementById, flattenRequirementTree, getAllRequirements, parseC
 /**
  * Parse a complete requirements Markdown file.
  */
-export declare function parseRequirementsFile(markdownContent: string): {
+export declare function parseRequirementsFile(markdownContent: string, options?: {
+    /**
+     * SOLDOC-3/4: a solution's other document (a pitch) carries no
+     * requirement blocks, and may carry no frontmatter yet, and is still a
+     * document.
+     */
+    solutionDocument?: boolean;
+}): {
     metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
     /** The markdown body (frontmatter stripped) — its leading H1 is the document's title (SYNC-TITLE-1). */
@@ -22,7 +29,9 @@ export declare function parseRequirementsFile(markdownContent: string): {
 /**
  * Parse requirements file from disk.
  */
-export declare function parseRequirementsFromFile(filePath: string): {
+export declare function parseRequirementsFromFile(filePath: string, options?: {
+    solutionDocument?: boolean;
+}): {
     metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
     body: string;

package/dist/schema/parser.js

@@ -9,7 +9,7 @@
  */
 import * as fs from "node:fs";
 import YAML from "yaml";
-import { parseRequirementBlocksFromMarkdown, splitFrontmatter, } from "./parser-core.js";
+import { parseRequirementBlocksFromMarkdown, splitFrontmatter, stripFrontmatterBlock, } from "./parser-core.js";
 import { ValidationError, validateMetadata, } from "./schemas.js";
 // Block/criterion parsing and tree utilities live in parser-core; re-exported
 // here so the schema module's public surface is unchanged.
@@ -18,11 +18,15 @@ export { findRequirementById, flattenRequirementTree, getAllRequirements, parseC
  * Extract YAML frontmatter from Markdown content.
  * Returns { frontmatter, body } where frontmatter is the parsed YAML object.
  */
-function extractFrontmatter(content) {
+function extractFrontmatter(content, optional = false) {
     // Single fence match: yaml and body come from the same split, so they can
     // never disagree about where the frontmatter closes.
     const split = splitFrontmatter(content);
     if (split === undefined) {
+        // SOLDOC-4.0: a solution's document written by hand has no frontmatter
+        // yet; the push writes it after the first sync.
+        if (optional)
+            return { frontmatter: {}, body: stripFrontmatterBlock(content) };
         throw new ValidationError("Missing YAML frontmatter (should start with ---)");
     }
     let frontmatter;
@@ -37,14 +41,14 @@ function extractFrontmatter(content) {
 /**
  * Parse a complete requirements Markdown file.
  */
-export function parseRequirementsFile(markdownContent) {
+export function parseRequirementsFile(markdownContent, options = {}) {
     // CRLF normalization (SYNC-FORMAT-1) happens inside the shared parser-core
     // helpers (splitFrontmatter / parseRequirementBlocksFromMarkdown), so every
     // entry point agrees.
-    const { frontmatter, body } = extractFrontmatter(markdownContent);
+    const { frontmatter, body } = extractFrontmatter(markdownContent, options.solutionDocument);
     const metadata = validateMetadata(frontmatter);
     const requirements = parseRequirementBlocksFromMarkdown(body);
-    if (requirements.length === 0) {
+    if (requirements.length === 0 && !options.solutionDocument) {
         throw new ValidationError("No requirement blocks found in document");
     }
     return { metadata, requirements, body };
@@ -52,10 +56,10 @@ export function parseRequirementsFile(markdownContent) {
 /**
  * Parse requirements file from disk.
  */
-export function parseRequirementsFromFile(filePath) {
+export function parseRequirementsFromFile(filePath, options = {}) {
     try {
         const content = fs.readFileSync(filePath, "utf-8");
-        return parseRequirementsFile(content);
+        return parseRequirementsFile(content, options);
     }
     catch (error) {
         if (error instanceof ValidationError) {