agentweaver 0.1.13 → 0.1.15

package/README.md

@@ -10,6 +10,8 @@ Typical usage looks like:
 
 The important part is not that exact chain. The point is that AgentWeaver lets you design, operate, and evolve durable agent harnesses instead of accumulating one-off prompts and shell glue.
 
+Для planning-heavy задач типовой путь теперь может включать и `plan -> design-review -> implement`, где `design-review` проверяет качество артефактов планирования до начала кодинга.
+
 ## What It Does
 
 - Fetches Jira issue context by issue key or browse URL
@@ -69,25 +71,26 @@ This keeps workflow design in JSON while keeping implementation details in typed
 
 User-invokable built-in commands currently map to these flow specs:
 
-- `plan`
-- `task-describe`
-- `implement`
-- `review`
-- `review-fix`
-- `review-loop`
-- `bug-analyze`
-- `bug-fix`
-- `git-commit`
-- `gitlab-diff-review`
-- `gitlab-review`
-- `mr-description`
-- `run-go-tests-loop`
-- `run-go-linter-loop`
-- `auto-golang`
-- `auto-common`
-- `doctor`
-
-There are also built-in nested/helper flows that are loaded declaratively but are not direct top-level CLI commands, for example `review-project`.
+- `plan` — 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
+- `design-review` — выполняет структурированную критику planning artifacts и пишет dedicated artifact `design-review/v1`; статус `approved_with_warnings` считается ready-to-proceed и по-прежнему допускает `ready-to-merge.md`
+- `task-describe` — 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
+- `implement` — runs LLM-backed implementation based on previously approved design and plan artifacts; executes code changes locally in the project working directory
+- `review` — 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
+- `review-fix` — 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
+- `review-loop` — 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
+- `bug-analyze` — fetches a Bug-type Jira issue, validates the issue type, generates or reuses a cached task summary, and produces structured bug analysis: root cause hypothesis, fix design, and step-by-step fix plan
+- `bug-fix` — applies the fix designed in bug-analyze; uses the root cause hypothesis, fix design, and fix plan artifacts as the source of truth to implement code changes locally
+- `git-commit` — four-phase commit workflow: collects git status and diff, generates a commit message via LLM, presents a file selection form, then shows the editable message for confirmation and executes the commit
+- `gitlab-diff-review` — prompts for a GitLab merge request URL, fetches the MR diff via GitLab API, and runs LLM-backed code review producing structured findings with severity levels and a ready-to-merge verdict
+- `gitlab-review` — prompts for a GitLab merge request URL, fetches existing code review comments via GitLab API, assesses which findings are fair and which can be dismissed, then runs review-fix to apply fixes for the accepted findings
+- `mr-description` — generates a concise merge request description based on the task context and current code changes; produces both markdown and structured JSON artifacts
+- `run-go-tests-loop` — runs `run_go_tests.py` and analyzes failures; if tests fail, sends the error output to LLM for a fix and retries; repeats up to 5 attempts, stopping early on success
+- `run-go-linter-loop` — runs `run_go_linter.py` and analyzes output; if the linter reports issues, sends them to LLM for a fix and retries; repeats up to 5 attempts, stopping early on success
+- `auto-golang` — end-to-end resumable pipeline for Go projects: plan → implement → linter loop → test loop → review loop → final linter loop → final test loop; supports `--from` to restart from a specific phase and `auto-status`/`auto-reset` for state management
+- `auto-common` — end-to-end resumable pipeline without language-specific checks: plan → implement → review loop; simplified alternative to auto-golang for projects that do not need Go linter/test loops
+- `doctor` — diagnostics command that runs system, executor, and flow readiness health checks; supports filtering by category or check ID and JSON output
+
+There are also built-in nested/helper flows that are loaded declaratively but are not direct top-level CLI commands, for example `review-project` (project-level code review used internally when no prior design/plan artifacts are present).
 
 ## Requirements
 
@@ -201,6 +204,7 @@ Direct flow execution:
 
 ```bash
 agentweaver plan DEMO-1234
+agentweaver design-review DEMO-1234
 agentweaver task-describe DEMO-1234
 agentweaver implement DEMO-1234
 agentweaver review DEMO-1234
@@ -225,6 +229,7 @@ From a source checkout:
 
 ```bash
 node dist/index.js plan DEMO-1234
+node dist/index.js design-review DEMO-1234
 node dist/index.js implement DEMO-1234
 node dist/index.js review DEMO-1234
 node dist/index.js auto-golang DEMO-1234

package/dist/artifacts.js

@@ -2,7 +2,6 @@ import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { TaskRunnerError } from "./errors.js";
-export const REVIEW_FILE_RE = /^review-(.+)-(\d+)\.md$/;
 export const READY_TO_MERGE_FILE = "ready-to-merge.md";
 export function scopesRootDir() {
     return path.join(process.cwd(), ".agentweaver", "scopes");
@@ -219,6 +218,12 @@ export function reviewFile(taskKey, iteration) {
 export function reviewJsonFile(taskKey, iteration) {
     return artifactJsonFile("review", taskKey, iteration);
 }
+export function designReviewFile(taskKey, iteration) {
+    return artifactFile("design-review", taskKey, iteration);
+}
+export function designReviewJsonFile(taskKey, iteration) {
+    return artifactJsonFile("design-review", taskKey, iteration);
+}
 export function reviewFixFile(taskKey, iteration) {
     return artifactFile("review-fix", taskKey, iteration);
 }

package/dist/doctor/checks/cwd-context.js

@@ -1,7 +1,6 @@
 import { accessSync, constants, existsSync } from "node:fs";
-import { DoctorStatus } from "../types.js";
+import { DoctorImpact, DoctorStatus } from "../types.js";
 import { CATEGORY } from "./category.js";
-const SOFT_CHECK_ID = "cwd-context-01";
 export const cwdContextCheck = {
     id: "cwd-context-01",
     category: CATEGORY.CWD_CONTEXT,
@@ -37,6 +36,7 @@ export const cwdContextCheck = {
         if (permissionStatus === DoctorStatus.Ok && gitStatus === DoctorStatus.Ok) {
             return {
                 id: "cwd-context-01",
+                impact: DoctorImpact.Blocking,
                 status: DoctorStatus.Ok,
                 title: "cwd-context",
                 message: `${permissionMessage}; ${gitStatusMessage}`,
@@ -46,6 +46,7 @@ export const cwdContextCheck = {
         if (permissionStatus === DoctorStatus.Ok && gitStatus === DoctorStatus.Warn) {
             return {
                 id: "cwd-context-01",
+                impact: DoctorImpact.Advisory,
                 status: DoctorStatus.Warn,
                 title: "cwd-context",
                 message: `${permissionMessage}; ${gitStatusMessage} (soft warning)`,
@@ -55,6 +56,7 @@ export const cwdContextCheck = {
         }
         const result = {
             id: "cwd-context-01",
+            impact: DoctorImpact.Blocking,
             status: permissionStatus,
             title: "cwd-context",
             message: permissionMessage,
@@ -66,4 +68,3 @@ export const cwdContextCheck = {
         return result;
     },
 };
-export const SOFT_CHECK_IDS = [SOFT_CHECK_ID];

package/dist/doctor/checks/env-diagnostics.js

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { DoctorStatus } from "../types.js";
+import { DoctorImpact, DoctorStatus } from "../types.js";
 import { CATEGORY } from "./category.js";
+import { detectJiraDeployment } from "../../jira.js";
 const MONITORED_KEYS = [
     "JIRA_API_KEY",
     "JIRA_USERNAME",
@@ -17,19 +18,16 @@ const MONITORED_KEYS = [
 ];
 const SECRET_KEYS = new Set(["JIRA_API_KEY", "GITLAB_TOKEN"]);
 const JIRA_AUTH_MODE_ALLOWED_VALUES = ["auto", "basic", "bearer"];
-function maskSecret(value) {
-    if (value.length <= 6) {
-        if (value.length <= 3) {
-            return "***";
-        }
-        const start = value.slice(0, Math.ceil(value.length / 2));
-        const end = value.slice(Math.ceil(value.length / 2));
-        return `${start}***${end}`;
-    }
-    const start = value.slice(0, 3);
-    const end = value.slice(-3);
-    return `${start}***${end}`;
-}
+const KEY_NOTES = {
+    JIRA_API_KEY: "Required for Jira-backed flows.",
+    JIRA_USERNAME: "Required only for Jira Cloud basic auth.",
+    GITLAB_TOKEN: "Required for GitLab-backed flows.",
+    AGENTWEAVER_HOME: "Optional override for the AgentWeaver package home.",
+    CODEX_BIN: "Optional override for the codex executable path.",
+    CODEX_MODEL: "Optional fallback model override for Codex-backed executors.",
+    OPENCODE_BIN: "Optional override for the opencode executable path.",
+    OPENCODE_MODEL: "Optional fallback model override for OpenCode-backed executors.",
+};
 function globalConfigDir() {
     return path.join(os.homedir(), ".agentweaver");
 }
@@ -69,101 +67,200 @@ function getProjectEnvPath() {
 function getGlobalEnvPath() {
     return path.join(globalConfigDir(), ".env");
 }
-function determineSource(key, shellSnapshot, currentValue) {
+function determineSource(key, shellSnapshot, projectEnv, globalEnv, currentValue) {
     if (currentValue === null) {
         return "missing";
     }
-    const isInShellSnapshot = shellSnapshot.hasOwnProperty(key);
-    if (isInShellSnapshot) {
+    if (Object.prototype.hasOwnProperty.call(shellSnapshot, key)) {
         return "shell";
     }
-    const globalEnv = parseEnvFileRaw(getGlobalEnvPath());
-    if (globalEnv.hasOwnProperty(key)) {
-        return "global";
-    }
-    const projectEnv = parseEnvFileRaw(getProjectEnvPath());
-    if (projectEnv.hasOwnProperty(key)) {
+    if (Object.prototype.hasOwnProperty.call(projectEnv, key)) {
         return "project-local";
     }
+    if (Object.prototype.hasOwnProperty.call(globalEnv, key)) {
+        return "global";
+    }
     return "shell";
 }
-function getDefaultValue(key) {
-    switch (key) {
-        case "AGENTWEAVER_HOME":
-            return path.join(os.homedir(), ".agentweaver");
-        default:
-            return null;
+function defaultNote(key) {
+    if (key === "JIRA_AUTH_MODE") {
+        return "Defaults to auto.";
     }
+    return null;
 }
 function validateJiraAuthMode(value) {
     if (value === null) {
         return true;
     }
-    return JIRA_AUTH_MODE_ALLOWED_VALUES.includes(value);
+    return JIRA_AUTH_MODE_ALLOWED_VALUES.includes(value.trim().toLowerCase());
+}
+function keyNote(key) {
+    return KEY_NOTES[key];
+}
+function formatKeyLine(info) {
+    const source = info.state === "unset" ? "unset" : info.source === "default" ? "default" : info.source;
+    const secretLabel = info.isSecret ? ", secret" : "";
+    const noteLabel = info.note ? `, ${info.note}` : "";
+    return `- ${info.key} (${source}${secretLabel}${noteLabel})`;
+}
+function buildDetails(configured, defaulted, unset, invalid, warnings) {
+    const lines = [];
+    if (warnings.length > 0) {
+        lines.push("warnings:");
+        for (const warning of warnings) {
+            lines.push(`- ${warning}`);
+        }
+    }
+    if (configured.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("configured:");
+        for (const info of configured) {
+            lines.push(formatKeyLine(info));
+        }
+    }
+    if (defaulted.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("defaulted:");
+        for (const info of defaulted) {
+            lines.push(formatKeyLine(info));
+        }
+    }
+    if (unset.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("unset:");
+        for (const info of unset) {
+            lines.push(formatKeyLine(info));
+        }
+    }
+    if (invalid.length > 0) {
+        if (lines.length > 0) {
+            lines.push("");
+        }
+        lines.push("invalid:");
+        for (const info of invalid) {
+            lines.push(formatKeyLine(info));
+        }
+    }
+    return lines.join("\n");
 }
 function checkEnvDiagnostics() {
     const shellSnapshot = {};
     for (const key of Object.keys(process.env)) {
-        shellSnapshot[key] = process.env[key];
+        const value = process.env[key];
+        if (value !== undefined) {
+            shellSnapshot[key] = value;
+        }
     }
     const projectEnv = parseEnvFileRaw(getProjectEnvPath());
     const globalEnv = parseEnvFileRaw(getGlobalEnvPath());
     const keyInfos = [];
-    let hasWarnings = false;
+    const warnings = [];
+    const jiraApiKey = process.env.JIRA_API_KEY?.trim() || null;
+    const jiraUsername = process.env.JIRA_USERNAME?.trim() || null;
+    const jiraAuthModeRaw = process.env.JIRA_AUTH_MODE?.trim() || null;
+    const jiraBaseUrl = process.env.JIRA_BASE_URL?.trim() || null;
     for (const key of MONITORED_KEYS) {
-        const currentValue = process.env[key] ?? null;
-        const source = determineSource(key, shellSnapshot, currentValue);
+        const currentValue = process.env[key]?.trim() || null;
         const isSecret = SECRET_KEYS.has(key);
-        let maskedValue = null;
-        if (currentValue !== null && isSecret) {
-            maskedValue = maskSecret(currentValue);
+        const source = determineSource(key, shellSnapshot, projectEnv, globalEnv, currentValue);
+        const defaultHint = currentValue === null ? defaultNote(key) : null;
+        let state = "configured";
+        if (currentValue === null && defaultHint) {
+            state = "defaulted";
+        }
+        else if (currentValue === null) {
+            state = "unset";
         }
-        else if (currentValue !== null) {
-            maskedValue = currentValue;
+        if (key === "JIRA_AUTH_MODE" && currentValue !== null && !validateJiraAuthMode(currentValue)) {
+            state = "invalid";
         }
-        const keyInfo = {
+        const note = state === "defaulted" ? defaultHint ?? undefined : keyNote(key);
+        keyInfos.push({
             key,
-            source,
-            value: currentValue,
-            maskedValue,
+            source: state === "defaulted" ? "default" : source,
+            state,
             isSecret,
-        };
-        keyInfos.push(keyInfo);
-        if (source === "missing") {
-            hasWarnings = true;
-        }
-        if (key === "JIRA_AUTH_MODE" && currentValue !== null) {
-            if (!validateJiraAuthMode(currentValue)) {
-                hasWarnings = true;
-            }
-        }
-    }
-    const status = hasWarnings ? DoctorStatus.Warn : DoctorStatus.Ok;
-    const keyCount = keyInfos.length;
-    const missingCount = keyInfos.filter(k => k.source === "missing").length;
-    const secretCount = keyInfos.filter(k => k.isSecret).length;
-    const summaryParts = [];
-    summaryParts.push(`${keyCount} keys checked`);
-    if (missingCount > 0) {
-        summaryParts.push(`${missingCount} missing`);
-    }
-    if (secretCount > 0) {
-        summaryParts.push(`${secretCount} secrets`);
-    }
-    const result = {
+            ...(note ? { note } : {}),
+        });
+    }
+    const jiraHasAnyConfig = !!(jiraApiKey || jiraBaseUrl || jiraUsername || jiraAuthModeRaw);
+    const jiraHasCorePair = !!(jiraApiKey && jiraBaseUrl);
+    if ((jiraApiKey && !jiraBaseUrl) || (!jiraApiKey && jiraBaseUrl)) {
+        warnings.push("Jira configuration is partial: set both JIRA_API_KEY and JIRA_BASE_URL for Jira-backed flows.");
+    }
+    if (jiraAuthModeRaw !== null && !validateJiraAuthMode(jiraAuthModeRaw)) {
+        warnings.push("JIRA_AUTH_MODE must be one of: auto, basic, bearer.");
+    }
+    if (jiraHasCorePair && jiraBaseUrl) {
+        const authMode = jiraAuthModeRaw?.toLowerCase() || "auto";
+        const isCloud = detectJiraDeployment(jiraBaseUrl) === "cloud";
+        const usesBasicAuth = authMode === "basic" || (authMode === "auto" && isCloud);
+        if (usesBasicAuth && !jiraUsername) {
+            warnings.push("JIRA_USERNAME is required for Jira Cloud basic auth with the current Jira URL and auth mode.");
+        }
+    }
+    else if (jiraHasAnyConfig && jiraUsername && !jiraApiKey && !jiraBaseUrl) {
+        warnings.push("JIRA_USERNAME is set without the Jira API key/base URL pair.");
+    }
+    const configured = keyInfos.filter((info) => info.state === "configured");
+    const defaulted = keyInfos.filter((info) => info.state === "defaulted");
+    const unset = keyInfos.filter((info) => info.state === "unset");
+    const invalid = keyInfos.filter((info) => info.state === "invalid");
+    const status = warnings.length > 0 ? DoctorStatus.Warn : DoctorStatus.Ok;
+    const summary = {
+        checked: keyInfos.length,
+        configured: configured.length,
+        defaulted: defaulted.length,
+        unset: unset.length,
+        invalid: invalid.length,
+        secrets: keyInfos.filter((info) => info.isSecret).length,
+    };
+    const messageParts = [
+        `${summary.checked} keys checked`,
+        `${summary.configured} configured`,
+    ];
+    if (summary.defaulted > 0) {
+        messageParts.push(`${summary.defaulted} defaulted`);
+    }
+    if (summary.unset > 0) {
+        messageParts.push(`${summary.unset} unset`);
+    }
+    if (summary.invalid > 0) {
+        messageParts.push(`${summary.invalid} invalid`);
+    }
+    const details = buildDetails(configured, defaulted, unset, invalid, warnings);
+    const data = {
+        kind: "env-config",
+        summary,
+        warnings,
+        keys: keyInfos,
+    };
+    return {
         id: "env-diagnostics-01",
+        impact: DoctorImpact.Advisory,
         status,
         title: "env-config",
-        message: summaryParts.join(", "),
-        ...(missingCount > 0 ? { hint: `${missingCount} configuration keys are missing` } : {}),
-        details: JSON.stringify(keyInfos),
+        message: messageParts.join(", "),
+        ...(warnings.length > 0
+            ? { hint: `${warnings.length} configuration issue${warnings.length === 1 ? "" : "s"} detected` }
+            : unset.length > 0
+                ? { hint: "Unset keys are optional unless you use the related integrations or overrides" }
+                : {}),
+        details,
+        data,
     };
-    return result;
 }
 export const envDiagnosticsCheck = {
     id: "env-diagnostics-01",
     category: CATEGORY.ENV_DIAGNOSTICS,
     title: "env-config",
+    impact: DoctorImpact.Advisory,
     dependencies: [],
     execute: async () => {
         return checkEnvDiagnostics();