agentweaver 0.1.13 → 0.1.15

package/dist/pipeline/flow-specs/plan.json

@@ -1,6 +1,7 @@
 {
   "kind": "plan-flow",
   "version": 1,
+  "description": "Fetches Jira task with attachments, generates clarifying questions for the developer, collects answers, and produces design, implementation plan, and QA plan as structured JSON and markdown artifacts.",
   "phases": [
     {
       "id": "plan",
@@ -158,7 +159,7 @@
             "formId": { "const": "planning-questions" },
             "title": { "const": "Planning Questions" },
             "description": {
-              "const": "Ответьте на вопросы модели, если они нужны для точного design/plan. Если вопросов нет, шаг завершится автоматически."
+              "const": "Answer the model's questions if they are needed for an accurate design/plan. If there are no questions, this step will complete automatically."
             }
           }
         },

package/dist/pipeline/flow-specs/review/review-fix.json

@@ -1,6 +1,7 @@
 {
   "kind": "review-fix-flow",
   "version": 1,
+  "description": "Takes review findings, auto-selects blockers and criticals (or lets the developer pick manually), builds a targeted fix prompt, and applies fixes locally. Runs mandatory checks after modifications.",
   "constants": {
     "autoReviewFixExtraPrompt": "Fix only blockers and criticals"
   },

package/dist/pipeline/flow-specs/review/review-loop.json

@@ -1,6 +1,7 @@
 {
   "kind": "review-loop-flow",
   "version": 1,
+  "description": "Iteratively runs review → review-fix cycles up to 5 times. Stops early when ready-to-merge is achieved. Each iteration auto-selects blockers and critical findings for fixing.",
   "constants": {
     "autoReviewFixExtraPrompt": "Fix only blockers and criticals. Skip minor and warning severity."
   },

package/dist/pipeline/flow-specs/review/review-project.json

@@ -1,6 +1,7 @@
 {
   "kind": "review-project-flow",
   "version": 1,
+  "description": "Project-level code review. Runs a single LLM review step using the review-project prompt template. Used internally by the review command when no prior design/plan artifacts are present.",
   "phases": [
     {
       "id": "review",

package/dist/pipeline/flow-specs/review/review.json

@@ -1,6 +1,7 @@
 {
   "kind": "review-flow",
   "version": 1,
+  "description": "Performs code review of current changes against the task design and plan. Produces structured review findings with severity levels and a ready-to-merge verdict.",
   "phases": [
     {
       "id": "review",
@@ -116,7 +117,7 @@
               }
             },
             "panelTitle": { "const": "Ready To Merge" },
-            "foundMessage": { "const": "Изменения готовы к merge\nФайл ready-to-merge.md создан." },
+            "foundMessage": { "const": "Changes are ready to merge.\nFile ready-to-merge.md has been created." },
             "tone": { "const": "green" }
           }
         }

package/dist/pipeline/flow-specs/task-describe.json

@@ -1,6 +1,7 @@
 {
   "kind": "task-describe-flow",
   "version": 1,
+  "description": "Generates a brief task description from a Jira issue or from manual input. When Jira is provided, fetches the issue and summarizes it; otherwise accepts free-form text and analyzes the codebase to produce a richer description.",
   "phases": [
     {
       "id": "task_describe",
@@ -12,7 +13,7 @@
             "formId": { "const": "task-describe-source-input" },
             "title": { "const": "Task Describe Source" },
             "description": {
-              "const": "Укажи либо Jira issue key / browse URL, либо кратко опиши задачу вручную."
+              "const": "Provide a Jira issue key / browse URL, or describe the task manually."
             },
             "submitLabel": { "const": "Generate description" },
             "fields": {
@@ -22,7 +23,7 @@
                     "id": "jira_ref",
                     "type": "text",
                     "label": "Jira issue key or browse URL",
-                    "help": "Например: DEMO-3288 или https://jira.example.ru/browse/DEMO-3288. Оставь пустым, если опишешь задачу вручную.",
+                    "help": "Example: DEMO-3288 or https://jira.example.com/browse/DEMO-3288. Leave empty to describe the task manually.",
                     "required": false
                   }
                 },
@@ -31,11 +32,11 @@
                     "id": "additional_instructions",
                     "type": "text",
                     "label": "Additional instructions",
-                    "help": "Необязательные указания для генерации описания. Например: ссылка на другой локальный репозиторий, связанный проект, ограничения или полезный контекст.",
+                    "help": "Optional instructions for description generation. Example: link to another local repo, related project, constraints, or useful context.",
                     "required": false,
                     "multiline": true,
                     "rows": 4,
-                    "placeholder": "Например: смотри также ../billing-service, описание API есть в docs/task-templates.md"
+                    "placeholder": "e.g. see also ../billing-service, API docs in docs/task-templates.md"
                   }
                 },
                 {
@@ -43,11 +44,11 @@
                     "id": "task_description",
                     "type": "text",
                     "label": "Task description",
-                    "help": "Кратко опиши задачу своими словами. Заполни это поле только если Jira нет.",
+                    "help": "Briefly describe the task in your own words. Fill this field only if Jira is not used.",
                     "required": false,
                     "multiline": true,
                     "rows": 3,
-                    "placeholder": "Например: добавить фильтр по статусу в список заказов и сохранить выбранное значение в URL"
+                    "placeholder": "e.g. add a status filter to the order list and persist the selected value in the URL"
                   }
                 }
               ]
@@ -234,10 +235,37 @@
                 }
               },
               "message": "Task describe mode did not produce the Jira description artifact."
+            }
+          ]
+        },
+        {
+          "id": "ensure_task_describe_json_from_jira_markdown",
+          "node": "ensure-summary-json",
+          "when": {
+            "all": [
+              { "ref": "steps.task_describe.collect_task_source.value.values.jira_ref" },
+              { "not": { "ref": "context.dryRun" } }
+            ]
+          },
+          "params": {
+            "markdownFile": {
+              "artifact": {
+                "kind": "jira-description-file",
+                "taskKey": { "ref": "params.taskKey" },
+                "iteration": { "ref": "params.iteration" }
+              }
             },
+            "outputFile": {
+              "artifact": {
+                "kind": "jira-description-json-file",
+                "taskKey": { "ref": "params.taskKey" },
+                "iteration": { "ref": "params.iteration" }
+              }
+            }
+          },
+          "expect": [
             {
               "kind": "require-structured-artifacts",
-              "when": { "not": { "ref": "context.dryRun" } },
               "items": [
                 {
                   "path": {
@@ -329,10 +357,41 @@
                 }
               },
               "message": "Task describe mode did not produce the Jira description artifact."
+            }
+          ]
+        },
+        {
+          "id": "ensure_task_describe_json_from_input_markdown",
+          "node": "ensure-summary-json",
+          "when": {
+            "all": [
+              {
+                "not": {
+                  "ref": "steps.task_describe.collect_task_source.value.values.jira_ref"
+                }
+              },
+              { "not": { "ref": "context.dryRun" } }
+            ]
+          },
+          "params": {
+            "markdownFile": {
+              "artifact": {
+                "kind": "jira-description-file",
+                "taskKey": { "ref": "params.taskKey" },
+                "iteration": { "ref": "params.iteration" }
+              }
             },
+            "outputFile": {
+              "artifact": {
+                "kind": "jira-description-json-file",
+                "taskKey": { "ref": "params.taskKey" },
+                "iteration": { "ref": "params.iteration" }
+              }
+            }
+          },
+          "expect": [
             {
               "kind": "require-structured-artifacts",
-              "when": { "not": { "ref": "context.dryRun" } },
               "items": [
                 {
                   "path": {

package/dist/pipeline/node-registry.js

@@ -3,6 +3,7 @@ import { buildReviewFixPromptNode } from "./nodes/build-review-fix-prompt-node.j
 import { codexPromptNode } from "./nodes/codex-prompt-node.js";
 import { commandCheckNode } from "./nodes/command-check-node.js";
 import { commitMessageFormNode } from "./nodes/commit-message-form-node.js";
+import { ensureSummaryJsonNode } from "./nodes/ensure-summary-json-node.js";
 import { fetchGitLabDiffNode } from "./nodes/fetch-gitlab-diff-node.js";
 import { fetchGitLabReviewNode } from "./nodes/fetch-gitlab-review-node.js";
 import { fileCheckNode } from "./nodes/file-check-node.js";
@@ -32,6 +33,7 @@ const builtInNodes = {
     "codex-prompt": codexPromptNode,
     "command-check": commandCheckNode,
     "commit-message-form": commitMessageFormNode,
+    "ensure-summary-json": ensureSummaryJsonNode,
     "fetch-gitlab-diff": fetchGitLabDiffNode,
     "fetch-gitlab-review": fetchGitLabReviewNode,
     "file-check": fileCheckNode,
@@ -90,6 +92,12 @@ const builtInNodeMetadata = {
         prompt: "forbidden",
         requiredParams: ["commitMessageFile", "formId", "title", "outputFile"],
     },
+    "ensure-summary-json": {
+        kind: "ensure-summary-json",
+        version: 1,
+        prompt: "forbidden",
+        requiredParams: ["markdownFile", "outputFile"],
+    },
     "fetch-gitlab-diff": {
         kind: "fetch-gitlab-diff",
         version: 1,

package/dist/pipeline/nodes/ensure-summary-json-node.js

@@ -0,0 +1,59 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { TaskRunnerError } from "../../errors.js";
+function toSummaryText(markdown) {
+    return markdown
+        .replace(/\r\n/g, "\n")
+        .replace(/^#{1,6}\s+/gm, "")
+        .replace(/^\s*[-*+]\s+/gm, "- ")
+        .replace(/`([^`]*)`/g, "$1")
+        .replace(/\*\*(.*?)\*\*/g, "$1")
+        .replace(/__(.*?)__/g, "$1")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function hasValidSummaryArtifact(outputFile) {
+    if (!existsSync(outputFile)) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(outputFile, "utf8"));
+        return typeof parsed.summary === "string" && parsed.summary.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export const ensureSummaryJsonNode = {
+    kind: "ensure-summary-json",
+    version: 1,
+    async run(_context, params) {
+        if (hasValidSummaryArtifact(params.outputFile)) {
+            return {
+                value: {
+                    outputFile: params.outputFile,
+                    created: false,
+                    repaired: false,
+                },
+            };
+        }
+        if (!existsSync(params.markdownFile)) {
+            throw new TaskRunnerError(`Cannot create summary JSON ${params.outputFile}: markdown source ${params.markdownFile} was not found.`);
+        }
+        const summary = toSummaryText(readFileSync(params.markdownFile, "utf8"));
+        if (!summary) {
+            throw new TaskRunnerError(`Cannot create summary JSON ${params.outputFile}: markdown source ${params.markdownFile} is empty.`);
+        }
+        mkdirSync(path.dirname(params.outputFile), { recursive: true });
+        const repaired = existsSync(params.outputFile);
+        writeFileSync(params.outputFile, `${JSON.stringify({ summary }, null, 2)}\n`, "utf8");
+        return {
+            value: {
+                outputFile: params.outputFile,
+                created: !repaired,
+                repaired,
+            },
+            outputs: [{ kind: "artifact", path: params.outputFile, required: true }],
+        };
+    },
+};

package/dist/pipeline/nodes/git-commit-node.js

@@ -6,7 +6,7 @@ export const gitCommitNode = {
     async run(context, params) {
         printInfo(params.labelText ?? "Committing changes");
         if (context.dryRun) {
-            printInfo("DRY RUN: git commit не выполнен");
+            printInfo("DRY RUN: git commit was not executed");
             return {
                 value: {
                     output: "",

package/dist/pipeline/nodes/git-status-node.js

@@ -187,7 +187,7 @@ export const gitStatusNode = {
         });
         const files = parsePorcelain(porcelainOutput);
         if (files.length === 0) {
-            throw new TaskRunnerError("Нет изменённых файлов для коммита.");
+            throw new TaskRunnerError("No changed files to commit.");
         }
         const diff = await context.runtime.runCommand(["git", "diff"], {
             dryRun: context.dryRun,

package/dist/pipeline/nodes/review-findings-form-node.js

@@ -48,8 +48,8 @@ export const reviewFindingsFormNode = {
             {
                 id: "apply_all",
                 type: "boolean",
-                label: "Исправить все findings в этой итерации",
-                help: "Если включено, выбор списка ниже не ограничивает scope исправлений.",
+                label: "Fix all findings in this iteration",
+                help: "If enabled, the selection list below does not limit the scope of fixes.",
                 default: selectableFindings.length === 0,
             },
         ];
@@ -57,8 +57,8 @@ export const reviewFindingsFormNode = {
             fields.push({
                 id: "selected_findings",
                 type: "multi-select",
-                label: "Какие findings исправить сейчас",
-                help: "Space переключает пункт. Если apply_all=false, выберите хотя бы один finding.",
+                label: "Which findings to fix now",
+                help: "Space toggles an item. If apply_all is off, select at least one finding.",
                 options: selectableFindings.map((finding) => ({
                     value: finding.title,
                     label: `${finding.title} | ${finding.severity || "-"}`,
@@ -80,17 +80,17 @@ export const reviewFindingsFormNode = {
         fields.push({
             id: "extra_notes",
             type: "text",
-            label: "Дополнительные указания",
-            help: "Короткий комментарий для этой итерации review-fix.",
+            label: "Additional instructions",
+            help: "Short comment for this review-fix iteration.",
             default: "",
-            placeholder: "Например: исправить только блокеры",
+            placeholder: "e.g. fix only blockers",
         });
         return {
             value: {
                 formId: params.formId,
                 title: params.title,
                 ...(params.description ? { description: params.description } : {}),
-                submitLabel: "Запустить review-fix",
+                submitLabel: "Run review-fix",
                 fields,
                 findingCount: selectableFindings.length,
             },

package/dist/pipeline/nodes/user-input-node.js

@@ -46,8 +46,8 @@ function buildTaskDescribePromptSuffix(params, values) {
                 ].join("\n\n")
                 : "",
             summaryText: additionalInstructions
-                ? `Источник задачи: Jira\nJira: ${jiraRef}\n\nДополнительные указания:\n${additionalInstructions}`
-                : `Источник задачи: Jira\nJira: ${jiraRef}`,
+                ? `Task source: Jira\nJira: ${jiraRef}\n\nAdditional instructions:\n${additionalInstructions}`
+                : `Task source: Jira\nJira: ${jiraRef}`,
         };
     }
     return {

package/dist/pipeline/prompt-registry.js

@@ -1,8 +1,9 @@
-import { BUG_ANALYZE_PROMPT_TEMPLATE, COMMIT_MESSAGE_PROMPT_TEMPLATE, GITLAB_DIFF_REVIEW_PROMPT_TEMPLATE, GITLAB_REVIEW_PROMPT_TEMPLATE, BUG_FIX_PROMPT_TEMPLATE, IMPLEMENT_PROMPT_TEMPLATE, JIRA_DESCRIPTION_PROMPT_TEMPLATE, MR_DESCRIPTION_PROMPT_TEMPLATE, PLAN_QUESTIONS_PROMPT_TEMPLATE, PLAN_PROMPT_TEMPLATE, REVIEW_FIX_PROMPT_TEMPLATE, REVIEW_PROJECT_PROMPT_TEMPLATE, REVIEW_PROMPT_TEMPLATE, REVIEW_SUMMARY_PROMPT_TEMPLATE, RUN_GO_LINTER_LOOP_FIX_PROMPT_TEMPLATE, RUN_GO_TESTS_LOOP_FIX_PROMPT_TEMPLATE, TASK_SUMMARY_PROMPT_TEMPLATE, } from "../prompts.js";
+import { BUG_ANALYZE_PROMPT_TEMPLATE, COMMIT_MESSAGE_PROMPT_TEMPLATE, DESIGN_REVIEW_PROMPT_TEMPLATE, GITLAB_DIFF_REVIEW_PROMPT_TEMPLATE, GITLAB_REVIEW_PROMPT_TEMPLATE, BUG_FIX_PROMPT_TEMPLATE, IMPLEMENT_PROMPT_TEMPLATE, JIRA_DESCRIPTION_PROMPT_TEMPLATE, MR_DESCRIPTION_PROMPT_TEMPLATE, PLAN_PROMPT_TEMPLATE, PLAN_QUESTIONS_PROMPT_TEMPLATE, PLAN_REVISE_PROMPT_TEMPLATE, REVIEW_FIX_PROMPT_TEMPLATE, REVIEW_PROJECT_PROMPT_TEMPLATE, REVIEW_PROMPT_TEMPLATE, REVIEW_SUMMARY_PROMPT_TEMPLATE, RUN_GO_LINTER_LOOP_FIX_PROMPT_TEMPLATE, RUN_GO_TESTS_LOOP_FIX_PROMPT_TEMPLATE, TASK_SUMMARY_PROMPT_TEMPLATE, } from "../prompts.js";
 const promptTemplates = {
     "bug-analyze": BUG_ANALYZE_PROMPT_TEMPLATE,
     "bug-fix": BUG_FIX_PROMPT_TEMPLATE,
     "commit-message": COMMIT_MESSAGE_PROMPT_TEMPLATE,
+    "design-review": DESIGN_REVIEW_PROMPT_TEMPLATE,
     "gitlab-diff-review": GITLAB_DIFF_REVIEW_PROMPT_TEMPLATE,
     "gitlab-review": GITLAB_REVIEW_PROMPT_TEMPLATE,
     implement: IMPLEMENT_PROMPT_TEMPLATE,
@@ -10,6 +11,7 @@ const promptTemplates = {
     "mr-description": MR_DESCRIPTION_PROMPT_TEMPLATE,
     "plan-questions": PLAN_QUESTIONS_PROMPT_TEMPLATE,
     plan: PLAN_PROMPT_TEMPLATE,
+    "plan-revise": PLAN_REVISE_PROMPT_TEMPLATE,
     review: REVIEW_PROMPT_TEMPLATE,
     "review-project": REVIEW_PROJECT_PROMPT_TEMPLATE,
     "review-fix": REVIEW_FIX_PROMPT_TEMPLATE,

package/dist/pipeline/spec-types.js

@@ -7,6 +7,8 @@ export const ARTIFACT_REF_KINDS = [
     "bug-fix-plan-json-file",
     "design-file",
     "design-json-file",
+    "design-review-file",
+    "design-review-json-file",
     "gitlab-diff-file",
     "gitlab-diff-json-file",
     "gitlab-diff-review-input-json-file",

package/dist/pipeline/value-resolver.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { artifactFile, bugAnalyzeArtifacts, bugAnalyzeFile, bugAnalyzeJsonFile, bugFixDesignFile, bugFixDesignJsonFile, bugFixPlanFile, bugFixPlanJsonFile, designFile, designJsonFile, gitlabDiffFile, gitlabDiffJsonFile, gitlabDiffReviewInputJsonFile, gitlabReviewFile, gitlabReviewInputJsonFile, gitlabReviewJsonFile, jiraAttachmentsContextFile, jiraAttachmentsManifestFile, jiraDescriptionFile, jiraDescriptionJsonFile, jiraTaskFile, mrDescriptionFile, mrDescriptionJsonFile, planningAnswersJsonFile, planningQuestionsJsonFile, planArtifacts, planFile, planJsonFile, qaFile, qaJsonFile, readyToMergeFile, reviewAssessmentFile, reviewAssessmentJsonFile, reviewFile, reviewFixFile, reviewFixJsonFile, reviewJsonFile, runGoLinterResultJsonFile, runGoTestsResultJsonFile, taskSummaryFile, taskDescribeInputJsonFile, taskSummaryJsonFile, gitStatusJsonFile, gitCommitMessageJsonFile, gitCommitInputJsonFile, selectFilesOutputJsonFile, commitMessageOutputJsonFile, gitDiffFile as gitDiffFileHelper, } from "../artifacts.js";
+import { artifactFile, bugAnalyzeArtifacts, bugAnalyzeFile, bugAnalyzeJsonFile, bugFixDesignFile, bugFixDesignJsonFile, bugFixPlanFile, bugFixPlanJsonFile, designFile, designJsonFile, designReviewFile, designReviewJsonFile, gitlabDiffFile, gitlabDiffJsonFile, gitlabDiffReviewInputJsonFile, gitlabReviewFile, gitlabReviewInputJsonFile, gitlabReviewJsonFile, jiraAttachmentsContextFile, jiraAttachmentsManifestFile, jiraDescriptionFile, jiraDescriptionJsonFile, jiraTaskFile, mrDescriptionFile, mrDescriptionJsonFile, planningAnswersJsonFile, planningQuestionsJsonFile, planArtifacts, planFile, planJsonFile, qaFile, qaJsonFile, readyToMergeFile, reviewAssessmentFile, reviewAssessmentJsonFile, reviewFile, reviewFixFile, reviewFixJsonFile, reviewJsonFile, runGoLinterResultJsonFile, runGoTestsResultJsonFile, taskSummaryFile, taskDescribeInputJsonFile, taskSummaryJsonFile, gitStatusJsonFile, gitCommitMessageJsonFile, gitCommitInputJsonFile, selectFilesOutputJsonFile, commitMessageOutputJsonFile, gitDiffFile as gitDiffFileHelper, } from "../artifacts.js";
 import { TaskRunnerError } from "../errors.js";
 import { formatTemplate } from "../prompts.js";
 function readStepRef(segments, context, originalPath) {
@@ -88,6 +88,16 @@ function resolveArtifact(spec, context) {
             return designFile(taskKey, iteration);
         case "design-json-file":
             return designJsonFile(taskKey, iteration);
+        case "design-review-file":
+            if (iteration === undefined) {
+                throw new TaskRunnerError("design-review-file requires iteration");
+            }
+            return designReviewFile(taskKey, iteration);
+        case "design-review-json-file":
+            if (iteration === undefined) {
+                throw new TaskRunnerError("design-review-json-file requires iteration");
+            }
+            return designReviewJsonFile(taskKey, iteration);
         case "gitlab-diff-file":
             return gitlabDiffFile(taskKey, iteration);
         case "gitlab-diff-json-file":

package/dist/prompts.js

@@ -52,13 +52,32 @@ export const MR_DESCRIPTION_PROMPT_TEMPLATE = "Review the task in {jira_task_fil
     "Prepare a very brief intent description for the merge request without implementation details, file lists, or technical details. " +
     `First write the source-of-truth JSON to {mr_description_json_file}. ${strictSchemaInstruction("{mr_description_json_file}", "mr-description/v1")}Then write the derivative markdown version to {mr_description_file}. `;
 export const IMPLEMENT_PROMPT_TEMPLATE = "Use only structured artifacts as source of truth. " +
-    "Analyze the system design {design_json_file}, implementation plan {plan_json_file}, and proceed with implementation according to the plan. " +
-    "Markdown artifacts are intended only for human reading and should not define the implementation. ";
+    "Analyze the system design {design_json_file}, implementation plan {plan_json_file}, and QA plan {qa_json_file}, then proceed with implementation according to those artifacts. " +
+    "Treat the QA plan as the source of truth for the minimum required test scenarios, edge cases, regression checks, and validation behavior that the implementation must satisfy. " +
+    "When the repository contains automated tests, add or update tests for the key scenarios from the QA plan whenever it is practical in the current codebase. " +
+    "If some QA scenarios cannot be automated in the current change, still implement the code so those scenarios are satisfied and keep them explicit in your reasoning while editing. " +
+    "Markdown artifacts such as {design_file}, {plan_file}, and {qa_file} are intended only for human reading and should not define the implementation. ";
 export const REVIEW_PROMPT_TEMPLATE = "Conduct a code review of the current changes. " +
     "Use only structured artifacts as source of truth: the task in {jira_task_file}, design in {design_json_file}, and plan in {plan_json_file}. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
     "Then write the derivative markdown version to {review_file}. " +
     "If ready_to_merge=true and there are no blockers preventing merge - create the ready-to-merge.md file.";
+export const DESIGN_REVIEW_PROMPT_TEMPLATE = "Conduct a structured planning critique as a specification critic, not as an implementer. " +
+    "Use structured JSON artifacts as the source of truth for semantics. " +
+    "Required planning inputs: design markdown {design_file}, design JSON {design_json_file}, implementation plan markdown {plan_file}, implementation plan JSON {plan_json_file}. " +
+    "Review the markdown files as derivative human-readable renderings of the same planning run, but do not let markdown override the structured JSON. " +
+    "Optional supplemental context is provided through these variables and may contain the literal value 'not provided' when absent: QA markdown {qa_file}, QA JSON {qa_json_file}, Jira task JSON {jira_task_file}, Jira attachments manifest {jira_attachments_manifest_file}, Jira attachments context {jira_attachments_context_file}, planning answers JSON {planning_answers_json_file}. " +
+    "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
+    "Evaluate completeness, consistency, implementation readiness, risk coverage, QA coverage, and scope discipline across the available planning artifacts and optional context. " +
+    "Identify blocking findings, major non-blocking findings, warnings, missing information, consistency check results, QA coverage gaps, and concise recommended actions. " +
+    "Use exactly one status value: approved, approved_with_warnings, or needs_revision. " +
+    "Set status to needs_revision when any blocking finding exists or when required information is missing in a way that blocks safe implementation start. " +
+    "Set status to approved_with_warnings when there are no blocking findings, but there are major findings, warnings, non-blocking missing information items, QA coverage gaps, or non-blocking consistency issues. " +
+    "Set status to approved only when there are no unresolved blocking findings, major findings, warnings, missing information items, or QA coverage gaps. " +
+    `First write the structured design review to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "design-review/v1")}` +
+    "Then write the derivative markdown version to {review_file}. " +
+    "Create ready-to-merge.md only when status is approved or approved_with_warnings. " +
+    "Do not create ready-to-merge.md when status is needs_revision.";
 export const REVIEW_PROJECT_PROMPT_TEMPLATE = "Conduct a code review of current changes in the project without Jira context. " +
     "Evaluate the quality of changes based on current code, tests, regression risks, and overall engineering quality. " +
     `First write the structured result to {review_json_file}. ${strictSchemaInstruction("{review_json_file}", "review-findings/v1")}` +
@@ -116,6 +135,34 @@ export const COMMIT_MESSAGE_PROMPT_TEMPLATE = "Generate a commit message for the
     "3) Include task key from Jira task. " +
     "4) Commit message language: English. " +
     "5) Write JSON to {commit_message_json_file}: {\"subject\": \"...\"}.";
+export const PLAN_REVISE_PROMPT_TEMPLATE = "Revise the planning artifacts based on the design-review verdict. " +
+    "Use structured JSON artifacts as the source of truth for semantics. " +
+    "First revise the structured JSON artifacts; only after the JSON is complete and schema-valid should you write the derivative markdown files. " +
+    "Markdown must not influence JSON structure or types. " +
+    "The design-review verdict JSON {review_json_file} is the primary source of revision instructions — treat its blocking findings, major findings, and recommended actions as mandatory revision targets. " +
+    "The design-review markdown {review_file} is a derivative rendering only and must not override the structured verdict. " +
+    "Required source planning inputs: design JSON {design_json_file}, design markdown {design_file}, plan JSON {plan_json_file}, plan markdown {plan_file}. " +
+    "Optional source QA inputs (may be 'not provided'): QA JSON {qa_json_file}, QA markdown {qa_file}. " +
+    "When QA inputs are 'not provided', synthesize a new QA plan from the revised design and plan. " +
+    "Optional supplemental context (may be 'not provided'): Jira task JSON {jira_task_file}, Jira attachments manifest {jira_attachments_manifest_file}, Jira attachments context {jira_attachments_context_file}, planning answers JSON {planning_answers_json_file}. " +
+    "When an optional variable is 'not provided', treat that source as unavailable and do not invent details from it. " +
+    "For every blocking finding and major finding in the verdict, address it directly in the revised artifacts. " +
+    "Preserve all content from the original artifacts that is not directly addressed by findings in the verdict — do not drop details, sections, or decisions that remain valid. " +
+    "Preserve semantics, not source formatting conventions from the verdict: do not copy verdict-style nested objects into fields whose schemas require plain strings. " +
+    "For implementation-design/v1 specifically, goals, non_goals, components, current_state, target_state, business_rules, migration_strategy, database_changes, api_changes, risks, acceptance_criteria, and open_questions must remain arrays of non-empty strings. " +
+    "Only affected_code and decisions may contain nested objects in implementation-design/v1. " +
+    "If you need to preserve extra detail such as mitigation, resolution, or answer text for a string-array field, fold that detail into a single English sentence string instead of creating an object. " +
+    "Produce the following revised outputs: " +
+    `revised design JSON to {revised_design_json_file}. ${strictSchemaInstruction("{revised_design_json_file}", "implementation-design/v1")}` +
+    "Revised design markdown to {revised_design_file}. " +
+    `revised plan JSON to {revised_plan_json_file}. ${strictSchemaInstruction("{revised_plan_json_file}", "implementation-plan/v1")}` +
+    "Revised plan markdown to {revised_plan_file}. " +
+    `revised QA JSON to {revised_qa_json_file}. ${strictSchemaInstruction("{revised_qa_json_file}", "qa-plan/v1")}` +
+    "Revised QA markdown to {revised_qa_file}. " +
+    "Create ready-to-merge.md only when all blocking findings from the verdict have been addressed in the revised artifacts. " +
+    "Do not create ready-to-merge.md if any blocking finding remains unresolved. " +
+    "JSON files must be valid and contain only JSON without markdown wrapping. " +
+    "Markdown files must be comprehensive derivative representations of the corresponding JSON artifacts.";
 export const AUTO_REVIEW_FIX_EXTRA_PROMPT = "Fix only blockers, criticals, and important issues";
 export function formatTemplate(template, values) {
     let result = template;

package/dist/runtime/design-review-input-contract.js

@@ -0,0 +1,112 @@
+import { existsSync } from "node:fs";
+import { designFile, designJsonFile, jiraAttachmentsContextFile, jiraAttachmentsManifestFile, jiraTaskFile, latestArtifactIteration, planFile, planJsonFile, planningAnswersJsonFile, qaFile, qaJsonFile, requireArtifacts, } from "../artifacts.js";
+import { TaskRunnerError } from "../errors.js";
+import { validateStructuredArtifacts } from "../structured-artifacts.js";
+const OPTIONAL_INPUT_NOT_PROVIDED = "not provided";
+function requiredPlanningArtifactPaths(taskKey, iteration) {
+    return {
+        designFile: designFile(taskKey, iteration),
+        designJsonFile: designJsonFile(taskKey, iteration),
+        planFile: planFile(taskKey, iteration),
+        planJsonFile: planJsonFile(taskKey, iteration),
+    };
+}
+function resolveLatestCompletedPlanningIteration(taskKey) {
+    const latestKnownIteration = Math.max(latestArtifactIteration(taskKey, "design", "md") ?? 0, latestArtifactIteration(taskKey, "design", "json") ?? 0, latestArtifactIteration(taskKey, "plan", "md") ?? 0, latestArtifactIteration(taskKey, "plan", "json") ?? 0);
+    for (let iteration = latestKnownIteration; iteration >= 1; iteration -= 1) {
+        const requiredPaths = Object.values(requiredPlanningArtifactPaths(taskKey, iteration));
+        if (requiredPaths.every((candidate) => existsSync(candidate))) {
+            return iteration;
+        }
+    }
+    const fallbackIteration = latestKnownIteration || 1;
+    const fallbackPaths = Object.values(requiredPlanningArtifactPaths(taskKey, fallbackIteration));
+    requireArtifacts(fallbackPaths, "Design-review requires design and plan markdown/JSON artifacts from the latest completed planning run.");
+    throw new TaskRunnerError("Unreachable design-review planning artifact resolution state.");
+}
+function resolveOptionalPromptFile(filePath) {
+    if (!existsSync(filePath)) {
+        return {
+            present: false,
+            path: null,
+            promptValue: OPTIONAL_INPUT_NOT_PROVIDED,
+        };
+    }
+    return {
+        present: true,
+        path: filePath,
+        promptValue: filePath,
+    };
+}
+function resolveOptionalValidatedStructuredFile(filePath, schemaId, message) {
+    const resolved = resolveOptionalPromptFile(filePath);
+    if (!resolved.present) {
+        return resolved;
+    }
+    validateStructuredArtifacts([{ path: filePath, schemaId }], message);
+    return resolved;
+}
+function resolveOptionalQaPair(taskKey, iteration) {
+    const markdownPath = qaFile(taskKey, iteration);
+    const jsonPath = qaJsonFile(taskKey, iteration);
+    const markdownExists = existsSync(markdownPath);
+    const jsonExists = existsSync(jsonPath);
+    if (!markdownExists && !jsonExists) {
+        return {
+            hasQaArtifacts: false,
+            qaFilePath: null,
+            qaJsonFilePath: null,
+            qaFile: OPTIONAL_INPUT_NOT_PROVIDED,
+            qaJsonFile: OPTIONAL_INPUT_NOT_PROVIDED,
+        };
+    }
+    if (!markdownExists || !jsonExists) {
+        requireArtifacts([markdownPath, jsonPath], "Design-review accepts QA artifacts only as a complete markdown/JSON pair for the selected planning iteration.");
+    }
+    validateStructuredArtifacts([{ path: jsonPath, schemaId: "qa-plan/v1" }], "Design-review QA structured artifact is invalid.");
+    return {
+        hasQaArtifacts: true,
+        qaFilePath: markdownPath,
+        qaJsonFilePath: jsonPath,
+        qaFile: markdownPath,
+        qaJsonFile: jsonPath,
+    };
+}
+/**
+ * Resolves the full design-review input contract from artifacts already present in the task scope.
+ * Required planning artifacts must come from one completed planning iteration. Optional contextual
+ * inputs are exposed as stable prompt values and explicit presence flags so the flow can remain
+ * deterministic when some context is absent.
+ */
+export function resolveDesignReviewInputContract(taskKey) {
+    const planningIteration = resolveLatestCompletedPlanningIteration(taskKey);
+    const requiredArtifacts = requiredPlanningArtifactPaths(taskKey, planningIteration);
+    requireArtifacts(Object.values(requiredArtifacts), "Design-review requires design and plan markdown/JSON artifacts from the latest completed planning run.");
+    validateStructuredArtifacts([
+        { path: requiredArtifacts.designJsonFile, schemaId: "implementation-design/v1" },
+        { path: requiredArtifacts.planJsonFile, schemaId: "implementation-plan/v1" },
+    ], "Design-review required planning structured artifacts are invalid.");
+    const qaArtifacts = resolveOptionalQaPair(taskKey, planningIteration);
+    const jiraTask = resolveOptionalPromptFile(jiraTaskFile(taskKey));
+    const jiraAttachmentsManifest = resolveOptionalPromptFile(jiraAttachmentsManifestFile(taskKey));
+    const jiraAttachmentsContext = resolveOptionalPromptFile(jiraAttachmentsContextFile(taskKey));
+    const planningAnswers = resolveOptionalValidatedStructuredFile(planningAnswersJsonFile(taskKey), "user-input/v1", "Design-review planning answers structured artifact is invalid.");
+    return {
+        planningIteration,
+        ...requiredArtifacts,
+        ...qaArtifacts,
+        hasJiraTaskFile: jiraTask.present,
+        jiraTaskFilePath: jiraTask.path,
+        jiraTaskFile: jiraTask.promptValue,
+        hasJiraAttachmentsManifestFile: jiraAttachmentsManifest.present,
+        jiraAttachmentsManifestFilePath: jiraAttachmentsManifest.path,
+        jiraAttachmentsManifestFile: jiraAttachmentsManifest.promptValue,
+        hasJiraAttachmentsContextFile: jiraAttachmentsContext.present,
+        jiraAttachmentsContextFilePath: jiraAttachmentsContext.path,
+        jiraAttachmentsContextFile: jiraAttachmentsContext.promptValue,
+        hasPlanningAnswersJsonFile: planningAnswers.present,
+        planningAnswersJsonFilePath: planningAnswers.path,
+        planningAnswersJsonFile: planningAnswers.promptValue,
+    };
+}
+export { OPTIONAL_INPUT_NOT_PROVIDED };