@popoverai/dotrequirements 0.38.3 → 0.39.0

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

@@ -12,7 +12,8 @@
  * images and demo scripts `next` saves in the checkout (SIGHT-9.3, 13.1).
  */
 export type Brief = {
-    kind: "step" | "review";
+    /** `request`: what the solution's agent asked it, which it answers (CONVO-11). */
+    kind: "step" | "review" | "request";
     /** The outcome the agent took; `label` is its name too. */
     step: {
         label: string;

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

@@ -0,0 +1,12 @@
+import { type WhereOptions } from "./run-file.js";
+/**
+ * `dotreq solution change --comment "<what changed and why>"`: a made
+ * outcome's drafter, asked by the solution's agent to change it, records
+ * the change in place (VERB-8). Its commits are pushed first, as before any
+ * record (VERB-8.1, SOLBRANCH-3); the outcome stays made, and its history
+ * says what changed and why, at the solution's agent's request.
+ */
+export declare function changeCommand(options: WhereOptions & {
+    comment?: string;
+}): Promise<void>;
+//# sourceMappingURL=change.d.ts.map

package/dist/commands/solution/change.js

@@ -0,0 +1,29 @@
+import { api } from "../../convex.js";
+import { solutionClient } from "./client.js";
+import { pushBeforeRecord } from "./pushing.js";
+import { requireWhere } from "./run-file.js";
+/**
+ * `dotreq solution change --comment "<what changed and why>"`: a made
+ * outcome's drafter, asked by the solution's agent to change it, records
+ * the change in place (VERB-8). Its commits are pushed first, as before any
+ * record (VERB-8.1, SOLBRANCH-3); the outcome stays made, and its history
+ * says what changed and why, at the solution's agent's request.
+ */
+export async function changeCommand(options) {
+    const comment = options.comment?.trim();
+    // VERB-8.3: what it says is all the history shows of the change.
+    if (!comment) {
+        throw new Error("Say what changed and why with --comment: what you say is what the outcome's history shows of the change.");
+    }
+    const where = requireWhere(options);
+    const client = solutionClient();
+    await pushBeforeRecord(client, where);
+    const { done } = await client.mutation(api.solutions.mutations.changeInPlace, {
+        solutionId: where.solutionId,
+        agent: where.agent,
+        ...(where.outcome ? { outcome: where.outcome } : {}),
+        comment,
+    });
+    console.log(done);
+}
+//# sourceMappingURL=change.js.map

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

@@ -5,5 +5,5 @@
  * request is validated against; the CLI can't import the backend, so this
  * is that text, and a test keeps the two the same.
  */
-export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. The person may answer in their own words instead of picking an option, and their words are then the decision you work from. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with `dotreq solution approval complete <decision>`. Leave it out for anything you may do yourself.\n      tool (text, up to 200 characters): The action, by name. The one that needs the person's permission is \"fix\", starting a fix.\n      args (object): The action's arguments, as it takes them: a fix's are below.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.\n\nThe args of a \"fix\" action:\n  name (text, up to 120 characters): A short name for the fix, from what it puts right, as \"dice below the controls\".\n  words (text, up to 2000 characters): What you found, in your own words.\n  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.\n  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.\n    outcome (text, up to 200 characters): An outcome to redo, by its name.\n    change (text, up to 2000 characters): What would change in it.\n  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.";
+export declare const REQUEST_CONTRACT = "Ask the person to decide something about the outcome you are drafting or reviewing. A choice presents options with a recommendation. The person may answer in their own words instead of picking an option, and their words are then the decision you work from. One decision per request: if two things need deciding, ask twice.\n\nA request is JSON with a \"kind\" and the fields of that kind:\n\nchoice:\n  question (text, up to 200 characters): The question, phrased as a question in the words the person will read it, not as a topic.\n  options (list, at least 2): The live alternatives. More than four makes deciding harder; give more only when each is a genuine choice. Leave out anything you have already ruled out.\n    name (text, up to 200 characters): The option as you would say it to the person: a noun phrase they can repeat back, not a label.\n    benefits (list of text, each up to 200 characters): What is better if this option is taken. One line each, in your own words.\n    costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.\n    note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.\n    action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with `dotreq solution approval complete <decision>`. Leave it out for anything you may do yourself.\n      tool (text, up to 200 characters): The action, by name. Those that need the person's permission: \"fix\", starting a fix, and \"make with you\", making the outcome you're on with the person and the solution's agent instead (args: { outcome }), when it needs their judgement more than your best guess (CONVO-8).\n      args (object): The action's arguments, as it takes them: a fix's are below.\n  recommendation (object): Which option you would take, and the one reason why.\n    option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.\n    because (text, up to 200 characters): The one reason that carries it, in one line. The full reasoning belongs in background.\n  background (text, up to 4000 characters): What the person needs to know to decide well that the options do not already say. Include only context that would substantially change the quality of the decision. The person reads this after the options, so do not reiterate them.\n\nThe args of a \"fix\" action:\n  name (text, up to 120 characters): A short name for the fix, from what it puts right, as \"dice below the controls\".\n  words (text, up to 2000 characters): What you found, in your own words.\n  plan (text, up to 2000 characters): The fix as you would put it to the person, in a sentence or two.\n  redo (list, at least 1): The outcomes the fix redoes, and what would change in each.\n    outcome (text, up to 200 characters): An outcome to redo, by its name.\n    change (text, up to 2000 characters): What would change in it.\n  rerun (list of text, each up to 200 characters): The outcomes that await the ones redone and should run again from them. Empty when none should.";
 //# sourceMappingURL=contract.d.ts.map

package/dist/commands/solution/contract.js

@@ -17,7 +17,7 @@ choice:
     costs (list of text, each up to 200 characters): What is worse if this option is taken: what it would take to build, and what the person lives with afterwards. Effort is a cost like any other.
     note (text, up to 600 characters, optional): Anything you learned or checked about this option that is not a benefit or a cost. Leave it out when there is nothing to add.
     action (object, optional): An action you may take only with the person's permission, which choosing this option gives. Once they choose it, take it with \`dotreq solution approval complete <decision>\`. Leave it out for anything you may do yourself.
-      tool (text, up to 200 characters): The action, by name. The one that needs the person's permission is "fix", starting a fix.
+      tool (text, up to 200 characters): The action, by name. Those that need the person's permission: "fix", starting a fix, and "make with you", making the outcome you're on with the person and the solution's agent instead (args: { outcome }), when it needs their judgement more than your best guess (CONVO-8).
       args (object): The action's arguments, as it takes them: a fix's are below.
   recommendation (object): Which option you would take, and the one reason why.
     option (text, up to 200 characters): The name of the option you recommend, exactly as it appears in options.

package/dist/commands/solution/index.js

@@ -2,6 +2,7 @@ import { Option } from "commander";
 import { approvalCompleteCommand } from "./approval.js";
 import { askCommand } from "./ask.js";
 import { authorCommand } from "./author.js";
+import { changeCommand } from "./change.js";
 import { checkoutCommand, pushCommand } from "./checkout.js";
 import { REQUEST_CONTRACT } from "./contract.js";
 import { createCommand } from "./create.js";
@@ -269,6 +270,11 @@ export function registerSolution(program) {
     whereOptions(solution
         .command("things <name>", HIDDEN)
         .description("What an outcome or an input holds now, or the outcomes a checkpoint presents: one reference a line")).action(wrap(thingsCommand));
+    whereOptions(solution
+        .command("change", HIDDEN)
+        .description("Record a change you made in place to a made outcome, as the solution's agent asked: what changed and why. The outcome stays made"))
+        .option("--comment <text>", "What changed and why: what the outcome's history shows of the change (required)")
+        .action(wrap(changeCommand));
     whereOptions(solution
         .command("stall <reason>", HIDDEN)
         .description("Your work cannot go on, and no decision would fix that: what has to change before it can be started again"))

package/dist/convex.d.ts

@@ -101,6 +101,7 @@ export declare const api: {
             ask: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             completeApproval: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             stall: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            changeInPlace: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             answer: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             approveCheckpoint: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             removeRehearsal: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -115,6 +115,8 @@ export const api = {
             // DECIDE-4: the action on the option the owner chose, taken once.
             completeApproval: mutation("solutions/mutations:completeApproval"),
             stall: mutation("solutions/mutations:stall"),
+            // VERB-8: a made outcome's drafter's change in place.
+            changeInPlace: mutation("solutions/mutations:changeInPlace"),
             answer: mutation("solutions/mutations:answer"),
             // A rehearsal's scripted approval of a checkpoint (CHECKPOINT-1.1).
             approveCheckpoint: mutation("solutions/mutations:approveCheckpoint"),

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, stripFrontmatterBlock, } from "./parser-core.js";
+export { DELIMITER_PATTERN, type ExtractedRequirementBlock, extractFrontmatterBlock, 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";

package/dist/schema/browser.js

@@ -8,12 +8,14 @@ export { buildRequirementMarkdown, buildRequirementsMarkdown, DEFAULT_DELIMITER,
 export { buildMetadata, constructKey, convexToRequirements, extractRequirementKeys, groupByRoot, parseKey, requirementsToConvex, } from "./conversions.js";
 // Parser core (pure TypeScript - browser-safe, no fs dependency)
 // These functions parse markdown strings directly without file I/O
-export { DELIMITER_PATTERN, extractRequirementBlocks, findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, parseRequirementBlocksFromMarkdown, parseRootLine, 
+export { DELIMITER_PATTERN, 
+// With stripFrontmatterBlock: a requirements file read from a repository
+// in the browser (SOLDOC-12), and one the solution's agent submits, read
+// from its checkout (BRANCH-1.0).
+extractFrontmatterBlock, 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, 
-// A requirements file read from a repository in the browser (SOLDOC-12).
-stripFrontmatterBlock, } from "./parser-core.js";
+ROOT_LABEL_MARKER, splitRequirementFenceContent, 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";

package/package.json

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