@popoverai/dotrequirements 0.34.0 → 0.34.1

package/README.md

@@ -251,13 +251,13 @@ Browser testing needs a Stagehand model and the API key for that model's provide
 {
   "defaultURL": "https://your-app.com",
   "browserTest": {
-    "modelName": "gateway/anthropic/claude-haiku-4-5",
+    "modelName": "gateway/anthropic/claude-haiku-5.5",
     "modelApiKey": "your-api-key"
   }
 }
 ```
 
-Pick any Stagehand-supported model. Example values: `gateway/anthropic/claude-haiku-4-5` (Vercel AI Gateway key), `google/gemini-3-flash-preview` (Gemini key).
+Pick any Stagehand-supported model. Example values: `gateway/anthropic/claude-haiku-5.5` (Vercel AI Gateway key), `google/gemini-3-flash-preview` (Gemini key).
 
 Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjectId`. Setting both Browserbase fields switches runs from LOCAL (spawns Playwright on your machine) to BROWSERBASE (managed cloud browsers).
 

package/dist/commands/acceptance-test.js

@@ -52,7 +52,7 @@ export async function acceptanceTestCommand(requirementKey, url, options) {
         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' +
+            '    "modelName": "gateway/anthropic/claude-haiku-5.5",\n' +
             '    "modelApiKey": "..."\n' +
             "  }\n" +
             "to .requirements/project-settings.json. See the docs for supported models.");

package/dist/commands/solution/index.js

@@ -73,8 +73,9 @@ outcome at .requirements/solutions/<solution>/<outcome>.md. With a repository
 connected, a file kept on the pull request is committed and submitted as
 file:<path>, unsynced, since it reaches the project's requirements when the
 pull request merges; one kept in the app is synced alone with
-\`dotreq sync --repo-contributes <path>\`, which writes the document id into its
-frontmatter, and submitted as document:<id>. With none, submit file:<path>: it
+\`dotreq sync <path> --repo-wins\`, which writes the document id into its
+frontmatter and lets a revision replace the version before it, and submitted
+as document:<id>. With none, submit file:<path>: it
 is saved on the solution's branch, and the document id is written into its
 frontmatter.
 

package/dist/commands/solution/run-file.d.ts

@@ -1,11 +1,12 @@
 /**
  * Which solution and agent a verb is for (VERB-4). Inside a runner the run
  * itself says — the runner writes a run file and names it in
- * `DOTREQ_RUN_FILE`: `{ solutionId, agent, branch }` — so an agent types no
- * ids. Outside one, the agent names them with `--solution` and `--agent`,
- * which win wherever they are given. The outcome is the backend's to work
- * out — the one the agent is at — unless `--outcome` names it, as an agent
- * at more than one does.
+ * `DOTREQ_RUN_FILE`: `{ solutionId, agent, branch, outcome }` — so an agent
+ * types no ids. Outside one, the agent names them with `--solution` and
+ * `--agent`, which win wherever they are given. The outcome is the one the
+ * run was handed, so a verb records on the outcome the agent is at even
+ * when it drafts one outcome and reviews another (VERB-3.4, 6.0);
+ * `--outcome` names another. Outside a run, the backend works it out.
  */
 /** The options every solution verb an agent runs carries. */
 export type WhereOptions = {
@@ -19,7 +20,7 @@ export type Where = {
     solutionId: string;
     /** The agent working: a plan's named agent, or one dedicated to an outcome ("Pitch/drafter"). */
     agent: string;
-    /** The outcome, when the agent named it; otherwise the one the agent is at. */
+    /** The outcome the agent named, or the one its run was handed; otherwise the backend's to work out. */
     outcome?: string;
     /**
      * The solution's branch, which the runner has checked out (SOLBRANCH-1):

package/dist/commands/solution/run-file.js

@@ -17,11 +17,12 @@ function fromRun() {
     }
     if (!parsed || typeof parsed !== "object")
         return {};
-    const { solutionId, agent, branch } = parsed;
+    const { solutionId, agent, branch, outcome } = parsed;
     return {
         solutionId: typeof solutionId === "string" ? solutionId : undefined,
         agent: typeof agent === "string" && agent ? agent : undefined,
         branch: typeof branch === "string" && branch ? branch : undefined,
+        outcome: typeof outcome === "string" && outcome ? outcome : undefined,
     };
 }
 /** The outcome named, by `--outcome` or its old name `--step`; blank is none. */
@@ -31,10 +32,15 @@ function outcomeNamed(options) {
 /** The run's own, with anything the agent named winning over it. */
 export function whereOf(options) {
     const run = fromRun();
+    const agent = options.agent?.trim() || run.agent;
+    // The run's outcome is its own agent's on its own solution: naming
+    // another is working outside the run.
+    const inTheRun = (options.solution === undefined || options.solution === run.solutionId) &&
+        agent === run.agent;
     return {
         solutionId: options.solution ?? run.solutionId,
-        agent: options.agent?.trim() || run.agent,
-        outcome: outcomeNamed(options),
+        agent,
+        outcome: outcomeNamed(options) ?? (inTheRun ? run.outcome : undefined),
         // The run's branch is the run's solution's: naming another solution
         // is working outside the run.
         branch: options.solution === undefined || options.solution === run.solutionId

package/dist/commands/solution/start.d.ts

@@ -1,8 +1,11 @@
 /**
  * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
- * hand. A stalled agent is started again, and it takes the part of an
- * outcome's work it has due: the one `--outcome` names, or its first in the
- * plan's order.
+ * hand. A stalled agent is started again. With the project's agent
+ * connected, it is sent for and its runner takes the first part it has
+ * due, in the plan's order, as after Start again in the app; `--outcome`
+ * naming any other is refused. With none connected, it takes the part of
+ * an outcome's work it has due itself: the one `--outcome` names, or its
+ * first in the plan's order (STEP-REVIEW-24.10, 24.11).
  */
 export declare function startCommand(solutionId: string, agent: string, options: {
     outcome?: string;

package/dist/commands/solution/start.js

@@ -3,18 +3,29 @@ import { solutionClient } from "./client.js";
 import { onOutcome } from "./run-file.js";
 /**
  * `dotreq solution start <solution-id> <agent>`: begin an agent's work by
- * hand. A stalled agent is started again, and it takes the part of an
- * outcome's work it has due: the one `--outcome` names, or its first in the
- * plan's order.
+ * hand. A stalled agent is started again. With the project's agent
+ * connected, it is sent for and its runner takes the first part it has
+ * due, in the plan's order, as after Start again in the app; `--outcome`
+ * naming any other is refused. With none connected, it takes the part of
+ * an outcome's work it has due itself: the one `--outcome` names, or its
+ * first in the plan's order (STEP-REVIEW-24.10, 24.11).
  */
 export async function startCommand(solutionId, agent, options) {
     const outcome = (options.outcome ?? options.step)?.trim() || undefined;
     const client = solutionClient();
-    await client.mutation(api.solutions.mutations.start, {
+    const started = await client.mutation(api.solutions.mutations.start, {
         solutionId,
         agent,
         ...(outcome ? { outcome } : {}),
     });
-    console.log(`Started ${agent}${onOutcome(outcome)}.`);
+    if (!started) {
+        // A backend from before it said what it did.
+        console.log(`Started ${agent}${onOutcome(outcome)}.`);
+        return;
+    }
+    const work = `${started.part === "review" ? "review" : "draft"} "${started.outcome}"`;
+    console.log(started.sentFor
+        ? `Sent for ${agent}: its runner will ${work}.`
+        : `Started ${agent}: it can ${work}.`);
 }
 //# sourceMappingURL=start.js.map

package/dist/schema/browser.d.ts

@@ -7,6 +7,7 @@ export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER,
 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, stripFrontmatterBlock, } from "./parser-core.js";
+export { carriesBranchVersion } from "./provenance.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

@@ -14,6 +14,9 @@ export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flatt
 ROOT_LABEL_MARKER, splitRequirementFenceContent, 
 // A requirements file read from a repository in the browser (SOLDOC-12).
 stripFrontmatterBlock, } from "./parser-core.js";
+// Whether a publish that says it lands a branch version matches it
+// (BRANCH-7.11), checked by the web app's merge and by the backend alike
+export { carriesBranchVersion } from "./provenance.js";
 // Schemas and types (uses zod - browser-safe)
 export { buildRequirementKey, canonicalRequirementKey, 
 // Zod schemas

package/dist/schema/provenance.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Whether a publish that says it lands a branch version matches that version
+ * (BRANCH-7.11): its title, its default prefix, and each of its requirements,
+ * key and wording, in the same tree and order. Pure and browser-safe, so the web
+ * app's merge checks every document before landing any, and the backend
+ * checks each publish, by the same rule.
+ *
+ * The merge publishes each version as the app's editor stores it, so the
+ * comparison is of what the editor keeps, not of the text:
+ * - a criterion's position is its place in the tree, since the editor
+ *   numbers criteria from 0 in order, and a label is compared without case,
+ *   since it writes a Gherkin keyword as `Given` however it was written;
+ * - the title is the leading heading however it is written, `#` or
+ *   underlined, falling back to the version's own title as the merge does;
+ * - the writing between requirements isn't compared at all (7.11.0): the
+ *   editor lays lists and tables out its own way and drops what it doesn't
+ *   keep, such as an HTML comment (BRANCH-2.2).
+ */
+export declare function carriesBranchVersion(published: {
+    markdownContent: string;
+    defaultPrefix?: string;
+}, version: {
+    markdownContent: string;
+    title?: string;
+    defaultPrefix?: string;
+}): boolean;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/schema/provenance.js

@@ -0,0 +1,66 @@
+import { parseRequirementBlocksFromMarkdown } from "./parser-core.js";
+import { splitLeadingH1 } from "./title-markdown.js";
+/**
+ * Whether a publish that says it lands a branch version matches that version
+ * (BRANCH-7.11): its title, its default prefix, and each of its requirements,
+ * key and wording, in the same tree and order. Pure and browser-safe, so the web
+ * app's merge checks every document before landing any, and the backend
+ * checks each publish, by the same rule.
+ *
+ * The merge publishes each version as the app's editor stores it, so the
+ * comparison is of what the editor keeps, not of the text:
+ * - a criterion's position is its place in the tree, since the editor
+ *   numbers criteria from 0 in order, and a label is compared without case,
+ *   since it writes a Gherkin keyword as `Given` however it was written;
+ * - the title is the leading heading however it is written, `#` or
+ *   underlined, falling back to the version's own title as the merge does;
+ * - the writing between requirements isn't compared at all (7.11.0): the
+ *   editor lays lists and tables out its own way and drops what it doesn't
+ *   keep, such as an HTML comment (BRANCH-2.2).
+ */
+export function carriesBranchVersion(published, version) {
+    const theirs = requirementsOf(published.markdownContent);
+    const ours = requirementsOf(version.markdownContent);
+    return (theirs !== null &&
+        ours !== null &&
+        theirs.length === ours.length &&
+        theirs.every((each, i) => each === ours[i]) &&
+        (titleOf(published.markdownContent) ?? "") ===
+            (titleOf(version.markdownContent) ?? version.title ?? "") &&
+        (published.defaultPrefix ?? "") === (version.defaultPrefix ?? ""));
+}
+/** Each requirement as the editor keeps it, in order; null when a block doesn't parse. */
+function requirementsOf(markdown) {
+    let trees;
+    try {
+        trees = parseRequirementBlocksFromMarkdown(markdown);
+    }
+    catch {
+        return null;
+    }
+    const out = [];
+    const walk = (node, path) => {
+        out.push([path, node.label.trim().toLowerCase(), squash(node.content)].join("\u0000"));
+        node.children.forEach((child, index) => {
+            walk(child, `${path}.${index}`);
+        });
+    };
+    for (const tree of trees)
+        walk(tree, tree.id.split(".")[0]);
+    return out;
+}
+function squash(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/** The leading heading's text, `#` or underlined with `=`; undefined when there is none. */
+function titleOf(markdown) {
+    const atx = splitLeadingH1(markdown).title;
+    if (atx != null)
+        return squash(atx);
+    const lines = markdown.replace(/^\s*\n/, "").split("\n");
+    if (lines.length >= 2 && lines[0].trim() && /^=+\s*$/.test(lines[1])) {
+        return squash(lines[0]);
+    }
+    return undefined;
+}
+//# sourceMappingURL=provenance.js.map

package/dist/sync/execute.js

@@ -435,7 +435,8 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
 /**
  * SOLDOC-6: where a pulled document lands. A file it is already linked to
  * keeps its path (SYNC-DISCOVERY-2.0); a document that belongs to a solution
- * lands in that solution's directory, named for its outcome; a document
+ * lands in that solution's directory, named for its outcome (SOLDOC-19 when
+ * the outcome holds more than one); a document
  * that is not a requirements document and belongs to no solution has no
  * place, and the pull says so rather than guessing.
  */
@@ -445,13 +446,11 @@ function placeCloudDocument(cloudDoc, existingPath, usedPaths, requirementsDir)
     const isRequirementsDoc = cloudDoc.isRequirementsDoc !== false;
     if (cloudDoc.solution) {
         // SOLDOC-9: the solution's own directory name; a backend from before it
-        // was sent leaves it out, and the title's slug stands in.
-        const candidate = solutionDocumentPath(requirementsDir, cloudDoc.solution.directory ??
-            sanitizeFileName(cloudDoc.solution.title ?? cloudDoc.solution.solutionId), cloudDoc.solution.outcome, isRequirementsDoc);
-        if (usedPaths.has(candidate) || fs.existsSync(candidate)) {
-            throw new Error(`"${cloudDoc.title}" belongs at ${path.relative(path.dirname(requirementsDir), candidate)}, but another file is already there.`);
-        }
-        return candidate;
+        // was sent leaves it out, and the title's slug stands in. SOLDOC-19: the
+        // file name the backend gives it, or the next free one when another file
+        // is there.
+        return solutionDocumentPath(requirementsDir, cloudDoc.solution.directory ??
+            sanitizeFileName(cloudDoc.solution.title ?? cloudDoc.solution.solutionId), cloudDoc.solution.outcome, isRequirementsDoc, cloudDoc.solution.fileName, (candidate) => usedPaths.has(candidate) || fs.existsSync(candidate));
     }
     if (!isRequirementsDoc) {
         throw new Error(`"${cloudDoc.title}" is not a requirements document and belongs to no solution, so the pull has nowhere to put it.`);

package/dist/sync/solution-documents.d.ts

@@ -55,10 +55,20 @@ export declare function resolveBelonging(filePath: string, frontmatter: {
     outcome?: string;
 }, claim: PathClaim | undefined, solutions: SolutionForSync[] | undefined): Resolved;
 /**
- * SOLDOC-6, SOLDOC-9: where a pulled document that belongs to a solution
- * lands when it has no file yet: in the solution's own directory, named for
- * its outcome, with the `.requirements.md` name when it is a requirements
- * document.
+ * SOLDOC-4, SOLDOC-19: the outcome a file's stem names, of those given: the
+ * one whose slug the stem is, or else the one whose slug it is followed by a
+ * suffix from -2 up, as an outcome's later documents are named. So `spec-2`
+ * is Spec 2's when there is a Spec 2, and the Spec's otherwise.
  */
-export declare function solutionDocumentPath(requirementsDir: string, solutionDirectory: string, outcome: string, isRequirementsDoc: boolean): string;
+export declare function outcomeNamedBy(stem: string, outcomes: readonly string[]): string | undefined;
+/**
+ * SOLDOC-6, SOLDOC-9, SOLDOC-19: where a pulled document that belongs to a
+ * solution lands when it has no file yet: in the solution's own directory,
+ * at the file name the backend gives it, which counts the outcome's other
+ * documents. A backend from before it was sent leaves it out, and the
+ * outcome's plain name stands in: its slug, with the `.requirements.md` name
+ * when it is a requirements document. When that file is taken, the document
+ * takes the outcome's next free name from -2 up.
+ */
+export declare function solutionDocumentPath(requirementsDir: string, solutionDirectory: string, outcome: string, isRequirementsDoc: boolean, fileName?: string | null, taken?: (candidate: string) => boolean): string;
 //# sourceMappingURL=solution-documents.d.ts.map

package/dist/sync/solution-documents.js

@@ -60,7 +60,12 @@ export function resolveBelonging(filePath, frontmatter, claim, solutions) {
                 warning: `${name}: its path names a different solution than its frontmatter ("${owner.title}"); the frontmatter's belonging is kept.`,
             };
         }
-        if (sanitizeFileName(declared.outcome) !== claim.outcomeSlug) {
+        // Read against the solution's other outcomes too: `spec-2` names Spec 2,
+        // not the Spec, when the plan has both.
+        if (outcomeNamedBy(claim.outcomeSlug, [
+            ...(owner?.outcomes ?? []),
+            declared.outcome,
+        ]) !== declared.outcome) {
             return {
                 belonging: declared,
                 warning: `${name}: its filename names a different outcome than its frontmatter ("${declared.outcome}"); the frontmatter's belonging is kept.`,
@@ -78,20 +83,53 @@ export function resolveBelonging(filePath, frontmatter, claim, solutions) {
         throw new Error(`${name}: its directory "${claim.solutionSlug}" matches more than one solution (${matches.map((s) => `"${s.title}"`).join(", ")}), so it can't be placed.`);
     }
     const [solution] = matches;
-    const outcome = solution.outcomes.find((o) => sanitizeFileName(o) === claim.outcomeSlug);
+    const outcome = outcomeNamedBy(claim.outcomeSlug, solution.outcomes);
     if (!outcome) {
         throw new Error(`${name}: "${claim.outcomeSlug}" matches no outcome of "${solution.title}". Its plan produces: ${solution.outcomes.map((o) => `${o} (${sanitizeFileName(o)}.md)`).join(", ")}.`);
     }
     return { belonging: { solutionId: solution.solutionId, outcome } };
 }
 /**
- * SOLDOC-6, SOLDOC-9: where a pulled document that belongs to a solution
- * lands when it has no file yet: in the solution's own directory, named for
- * its outcome, with the `.requirements.md` name when it is a requirements
- * document.
+ * SOLDOC-4, SOLDOC-19: the outcome a file's stem names, of those given: the
+ * one whose slug the stem is, or else the one whose slug it is followed by a
+ * suffix from -2 up, as an outcome's later documents are named. So `spec-2`
+ * is Spec 2's when there is a Spec 2, and the Spec's otherwise.
  */
-export function solutionDocumentPath(requirementsDir, solutionDirectory, outcome, isRequirementsDoc) {
+export function outcomeNamedBy(stem, outcomes) {
+    const plain = outcomes.find((o) => sanitizeFileName(o) === stem);
+    if (plain !== undefined)
+        return plain;
+    const later = /^(.+)-([1-9]\d*)$/.exec(stem);
+    if (!later || Number(later[2]) < 2)
+        return undefined;
+    return outcomes.find((o) => sanitizeFileName(o) === later[1]);
+}
+/**
+ * SOLDOC-6, SOLDOC-9, SOLDOC-19: where a pulled document that belongs to a
+ * solution lands when it has no file yet: in the solution's own directory,
+ * at the file name the backend gives it, which counts the outcome's other
+ * documents. A backend from before it was sent leaves it out, and the
+ * outcome's plain name stands in: its slug, with the `.requirements.md` name
+ * when it is a requirements document. When that file is taken, the document
+ * takes the outcome's next free name from -2 up.
+ */
+export function solutionDocumentPath(requirementsDir, solutionDirectory, outcome, isRequirementsDoc, fileName, taken = () => false) {
     const suffix = isRequirementsDoc ? ".requirements.md" : ".md";
-    return path.join(requirementsDir, SOLUTIONS_DIR, solutionDirectory || "solution", `${sanitizeFileName(outcome) || "outcome"}${suffix}`);
+    const directory = path.join(requirementsDir, SOLUTIONS_DIR, solutionDirectory || "solution");
+    const slug = sanitizeFileName(outcome) || "outcome";
+    // Only a plain file name of the document's kind, never a path.
+    const given = fileName &&
+        fileName === path.basename(fileName) &&
+        !fileName.startsWith(".") &&
+        stemOf(fileName) !== "" &&
+        fileName.endsWith(suffix) &&
+        (isRequirementsDoc || !fileName.endsWith(".requirements.md"))
+        ? fileName
+        : `${slug}${suffix}`;
+    let candidate = path.join(directory, given);
+    for (let n = 2; taken(candidate); n++) {
+        candidate = path.join(directory, `${slug}-${n}${suffix}`);
+    }
+    return candidate;
 }
 //# sourceMappingURL=solution-documents.js.map

package/dist/sync/types.d.ts

@@ -56,6 +56,8 @@ export interface CloudDocument {
         title: string | null;
         /** SOLDOC-9: the solution's directory name; absent from an older backend. */
         directory?: string | null;
+        /** SOLDOC-19: the document's file name in that directory; absent from an older backend. */
+        fileName?: string | null;
     };
     /** SOLDOC-2/3: absent means a requirements document. */
     isRequirementsDoc?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "description": "Requirements as testable, human-readable data — CLI and test harness for spec-driven development with AI coding agents",
   "type": "module",
   "bin": {