agentweaver 0.1.14 → 0.1.15

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 };

package/dist/runtime/plan-revise-input-contract.js

@@ -0,0 +1,144 @@
+import { existsSync } from "node:fs";
+import { designFile, designJsonFile, designReviewFile, designReviewJsonFile, 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 resolveLatestDesignReviewIteration(taskKey) {
+    const latestMd = latestArtifactIteration(taskKey, "design-review", "md");
+    const latestJson = latestArtifactIteration(taskKey, "design-review", "json");
+    const maxIteration = Math.max(latestMd ?? 0, latestJson ?? 0);
+    if (maxIteration === 0) {
+        throw new TaskRunnerError("Plan-revise requires at least one completed design-review iteration, but no design-review artifacts were found.");
+    }
+    for (let iteration = maxIteration; iteration >= 1; iteration -= 1) {
+        const mdPath = designReviewFile(taskKey, iteration);
+        const jsonPath = designReviewJsonFile(taskKey, iteration);
+        if (existsSync(mdPath) && existsSync(jsonPath)) {
+            return iteration;
+        }
+    }
+    const fallbackMd = designReviewFile(taskKey, maxIteration);
+    const fallbackJson = designReviewJsonFile(taskKey, maxIteration);
+    requireArtifacts([fallbackMd, fallbackJson], "Plan-revise requires design-review markdown and JSON artifacts from the latest completed design-review run.");
+    throw new TaskRunnerError("Unreachable plan-revise design-review artifact resolution state.");
+}
+function resolveLatestCompletedPlanningIteration(taskKey) {
+    const latestDesignMd = latestArtifactIteration(taskKey, "design", "md") ?? 0;
+    const latestDesignJson = latestArtifactIteration(taskKey, "design", "json") ?? 0;
+    const latestPlanMd = latestArtifactIteration(taskKey, "plan", "md") ?? 0;
+    const latestPlanJson = latestArtifactIteration(taskKey, "plan", "json") ?? 0;
+    const maxIteration = Math.max(latestDesignMd, latestDesignJson, latestPlanMd, latestPlanJson);
+    for (let iteration = maxIteration; iteration >= 1; iteration -= 1) {
+        const paths = [
+            designFile(taskKey, iteration),
+            designJsonFile(taskKey, iteration),
+            planFile(taskKey, iteration),
+            planJsonFile(taskKey, iteration),
+        ];
+        if (paths.every((candidate) => existsSync(candidate))) {
+            return iteration;
+        }
+    }
+    const fallbackIteration = maxIteration || 1;
+    const fallbackPaths = [
+        designFile(taskKey, fallbackIteration),
+        designJsonFile(taskKey, fallbackIteration),
+        planFile(taskKey, fallbackIteration),
+        planJsonFile(taskKey, fallbackIteration),
+    ];
+    requireArtifacts(fallbackPaths, "Plan-revise requires design and plan markdown/JSON artifacts from the latest completed planning run.");
+    throw new TaskRunnerError("Unreachable plan-revise 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 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], "Plan-revise accepts QA artifacts only as a complete markdown/JSON pair for the source planning iteration.");
+    }
+    validateStructuredArtifacts([{ path: jsonPath, schemaId: "qa-plan/v1" }], "Plan-revise QA structured artifact is invalid.");
+    return {
+        hasQaArtifacts: true,
+        qaFilePath: markdownPath,
+        qaJsonFilePath: jsonPath,
+        qaFile: markdownPath,
+        qaJsonFile: jsonPath,
+    };
+}
+export function resolvePlanReviseInputContract(taskKey) {
+    const reviewIteration = resolveLatestDesignReviewIteration(taskKey);
+    const reviewMd = designReviewFile(taskKey, reviewIteration);
+    const reviewJson = designReviewJsonFile(taskKey, reviewIteration);
+    requireArtifacts([reviewMd, reviewJson], "Plan-revise requires design-review markdown and JSON artifacts.");
+    validateStructuredArtifacts([{ path: reviewJson, schemaId: "design-review/v1" }], "Plan-revise design-review structured artifact is invalid.");
+    const sourcePlanningIteration = resolveLatestCompletedPlanningIteration(taskKey);
+    const srcDesignMd = designFile(taskKey, sourcePlanningIteration);
+    const srcDesignJson = designJsonFile(taskKey, sourcePlanningIteration);
+    const srcPlanMd = planFile(taskKey, sourcePlanningIteration);
+    const srcPlanJson = planJsonFile(taskKey, sourcePlanningIteration);
+    requireArtifacts([srcDesignMd, srcDesignJson, srcPlanMd, srcPlanJson], "Plan-revise requires design and plan markdown/JSON artifacts from the source planning iteration.");
+    validateStructuredArtifacts([
+        { path: srcDesignJson, schemaId: "implementation-design/v1" },
+        { path: srcPlanJson, schemaId: "implementation-plan/v1" },
+    ], "Plan-revise source planning structured artifacts are invalid.");
+    const outputIteration = sourcePlanningIteration + 1;
+    const qaArtifacts = resolveOptionalQaPair(taskKey, sourcePlanningIteration);
+    const jiraTask = resolveOptionalPromptFile(jiraTaskFile(taskKey));
+    const jiraAttachmentsManifest = resolveOptionalPromptFile(jiraAttachmentsManifestFile(taskKey));
+    const jiraAttachmentsContext = resolveOptionalPromptFile(jiraAttachmentsContextFile(taskKey));
+    const planningAnswers = resolveOptionalPromptFile(planningAnswersJsonFile(taskKey));
+    return {
+        reviewIteration,
+        reviewFile: reviewMd,
+        reviewJsonFile: reviewJson,
+        sourcePlanningIteration,
+        outputIteration,
+        designFile: srcDesignMd,
+        designJsonFile: srcDesignJson,
+        planFile: srcPlanMd,
+        planJsonFile: srcPlanJson,
+        ...qaArtifacts,
+        revisedDesignFile: designFile(taskKey, outputIteration),
+        revisedDesignJsonFile: designJsonFile(taskKey, outputIteration),
+        revisedPlanFile: planFile(taskKey, outputIteration),
+        revisedPlanJsonFile: planJsonFile(taskKey, outputIteration),
+        revisedQaFile: qaFile(taskKey, outputIteration),
+        revisedQaJsonFile: qaJsonFile(taskKey, outputIteration),
+        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,
+    };
+}

package/dist/runtime/ready-to-merge.js

@@ -0,0 +1,10 @@
+import { existsSync, rmSync } from "node:fs";
+import { readyToMergeFile } from "../artifacts.js";
+export function clearReadyToMergeFile(taskKey) {
+    const filePath = readyToMergeFile(taskKey);
+    if (!existsSync(filePath)) {
+        return false;
+    }
+    rmSync(filePath);
+    return true;
+}

package/dist/scope.js

@@ -43,7 +43,7 @@ export function detectGitBranchName() {
 export function detectProjectRoot() {
     return gitOutput(["rev-parse", "--show-toplevel"]) ?? process.cwd();
 }
-export function buildProjectScopeKey(explicitScope) {
+export function buildProjectScopeKey(explicitScope, jiraIssueKey) {
     const projectRoot = detectProjectRoot();
     const worktreeHash = shortHash(projectRoot);
     if (explicitScope?.trim()) {
@@ -54,6 +54,14 @@ export function buildProjectScopeKey(explicitScope) {
             projectRoot,
         };
     }
+    if (jiraIssueKey?.trim()) {
+        return {
+            scopeKey: `${sanitizeScopeName(jiraIssueKey)}@${worktreeHash}`,
+            gitBranchName: detectGitBranchName(),
+            worktreeHash,
+            projectRoot,
+        };
+    }
     const branchName = detectGitBranchName();
     const branchSlug = sanitizeScopeName(branchName ?? "detached-head");
     return {
@@ -72,7 +80,8 @@ export function parseJiraContext(jiraRef) {
     };
 }
 export function resolveProjectScope(explicitScope, jiraRef) {
-    const { scopeKey, gitBranchName, worktreeHash, projectRoot } = buildProjectScopeKey(explicitScope);
+    const jiraIssueKey = jiraRef?.trim() ? extractIssueKey(jiraRef) : undefined;
+    const { scopeKey, gitBranchName, worktreeHash, projectRoot } = buildProjectScopeKey(explicitScope, jiraIssueKey);
     ensureScopeWorkspaceDir(scopeKey);
     const baseScope = {
         scopeType: "project",

package/dist/structured-artifact-schema-registry.js

@@ -6,6 +6,7 @@ export const STRUCTURED_ARTIFACT_SCHEMA_IDS = [
     "bug-analysis/v1",
     "bug-fix-design/v1",
     "bug-fix-plan/v1",
+    "design-review/v1",
     "gitlab-mr-diff/v1",
     "gitlab-review/v1",
     "implementation-design/v1",

package/dist/structured-artifact-schemas.json

@@ -485,6 +485,123 @@
     },
     "required": ["summary", "test_scenarios", "non_functional_checks"]
   },
+  "design-review/v1": {
+    "type": "object",
+    "properties": {
+      "summary": { "type": "string", "nonEmpty": true },
+      "status": {
+        "type": "string",
+        "enum": ["approved", "approved_with_warnings", "needs_revision"]
+      },
+      "blocking_findings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "nonEmpty": true },
+            "description": { "type": "string", "nonEmpty": true },
+            "affected_artifacts": {
+              "type": "array",
+              "items": { "type": "string", "nonEmpty": true },
+              "minItems": 1
+            }
+          },
+          "required": ["title", "description", "affected_artifacts"]
+        }
+      },
+      "major_findings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "nonEmpty": true },
+            "description": { "type": "string", "nonEmpty": true },
+            "affected_artifacts": {
+              "type": "array",
+              "items": { "type": "string", "nonEmpty": true },
+              "minItems": 1
+            }
+          },
+          "required": ["title", "description", "affected_artifacts"]
+        }
+      },
+      "warnings": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "nonEmpty": true },
+            "description": { "type": "string", "nonEmpty": true },
+            "affected_artifacts": {
+              "type": "array",
+              "items": { "type": "string", "nonEmpty": true },
+              "minItems": 1
+            }
+          },
+          "required": ["title", "description", "affected_artifacts"]
+        }
+      },
+      "missing_information": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "nonEmpty": true },
+            "description": { "type": "string", "nonEmpty": true },
+            "affected_artifacts": {
+              "type": "array",
+              "items": { "type": "string", "nonEmpty": true },
+              "minItems": 1
+            }
+          },
+          "required": ["title", "description", "affected_artifacts"]
+        }
+      },
+      "consistency_checks": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string", "nonEmpty": true },
+            "status": { "type": "string", "nonEmpty": true },
+            "details": { "type": "string", "nonEmpty": true }
+          },
+          "required": ["name", "status", "details"]
+        }
+      },
+      "qa_coverage_gaps": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "title": { "type": "string", "nonEmpty": true },
+            "description": { "type": "string", "nonEmpty": true },
+            "affected_artifacts": {
+              "type": "array",
+              "items": { "type": "string", "nonEmpty": true },
+              "minItems": 1
+            }
+          },
+          "required": ["title", "description", "affected_artifacts"]
+        }
+      },
+      "recommended_actions": {
+        "type": "array",
+        "items": { "type": "string", "nonEmpty": true }
+      }
+    },
+    "required": [
+      "summary",
+      "status",
+      "blocking_findings",
+      "major_findings",
+      "warnings",
+      "missing_information",
+      "consistency_checks",
+      "qa_coverage_gaps",
+      "recommended_actions"
+    ]
+  },
   "review-findings/v1": {
     "type": "object",
     "properties": {

package/dist/structured-artifacts.js

@@ -11,6 +11,9 @@ function schemaLabel(node) {
     }
     switch (node.type) {
         case "string":
+            if (node.enum && node.enum.length > 0) {
+                return `one of: ${node.enum.join(", ")}`;
+            }
             return node.nonEmpty ? "a non-empty string" : "a string";
         case "boolean":
             return "a boolean";
@@ -43,6 +46,9 @@ function validateNode(value, schema, currentPath) {
             if (typeof value !== "string" || (schema.nonEmpty && value.trim().length === 0)) {
                 return [`${currentPath} must be ${schemaLabel(schema)}`];
             }
+            if (schema.enum && !schema.enum.includes(value)) {
+                return [`${currentPath} must be ${schemaLabel(schema)}`];
+            }
             return [];
         case "boolean":
             return typeof value === "boolean" ? [] : [`${currentPath} must be a boolean`];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentweaver",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "CLI orchestrator for Jira/Codex engineering workflows",
   "keywords": [
     "agent",