agentweaver 0.1.14 → 0.1.16

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.
 
+For planning-heavy work, a typical path can now include `plan -> design-review -> implement`, where `design-review` critiques planning artifacts before coding starts.
+
 ## What It Does
 
 - Fetches Jira issue context by issue key or browse URL
@@ -60,7 +62,7 @@ This keeps workflow design in JSON while keeping implementation details in typed
 - `src/pipeline/` — declarative flow loading, compilation, validation, runtime, and built-in flow specs
 - `src/pipeline/nodes/` — reusable runtime nodes used by flow specs
 - `src/runtime/` — shared runtime services such as command resolution and subprocess execution
-- `src/interactive-ui.ts` — full-screen interactive UI
+- `src/interactive/` — Ink-based interactive session, controller, state, and view-model logic
 - `src/markdown.ts` — markdown rendering for terminal output
 - `src/structured-artifact-schemas.json` — schemas for machine-readable artifacts
 - `tests/` — automated tests for pipeline behavior
@@ -70,6 +72,7 @@ This keeps workflow design in JSON while keeping implementation details in typed
 User-invokable built-in commands currently map to these flow specs:
 
 - `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` — performs a structured critique of the latest planning artifacts and writes a dedicated `design-review/v1` artifact; `approved_with_warnings` is treated as ready to proceed and may still produce `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
@@ -84,7 +87,8 @@ User-invokable built-in commands currently map to these flow specs:
 - `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
+- `auto-common` — planning-aware pipeline with a mandatory design-review gate before implementation: plan → design-review loop → implement → review loop; design-review can iterate with `plan-revise` up to 3 times, and if the final verdict still requires revision the operator must explicitly choose whether to continue with the latest planning artifacts or stop
+- `auto-simple` — preserved simplified pipeline equivalent to the legacy auto-common behavior: plan → implement → review loop; no planning review gate, suitable for projects that do not need design review before coding
 - `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).
@@ -201,6 +205,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
@@ -216,6 +221,7 @@ agentweaver run-go-tests-loop DEMO-1234
 agentweaver run-go-linter-loop DEMO-1234
 agentweaver auto-golang DEMO-1234
 agentweaver auto-common DEMO-1234
+agentweaver auto-simple DEMO-1234
 agentweaver doctor
 agentweaver doctor --json
 agentweaver doctor <category>|<check-id>
@@ -225,6 +231,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
@@ -238,6 +245,7 @@ agentweaver --help
 agentweaver --version
 agentweaver auto-golang --help-phases
 agentweaver auto-common --help-phases
+agentweaver auto-simple --help-phases
 agentweaver auto-golang --from <phase> DEMO-1234
 agentweaver auto-status DEMO-1234
 agentweaver auto-reset DEMO-1234
@@ -252,13 +260,13 @@ Notes:
 - `--prompt <text>` appends extra instructions to the prompt
 - `--scope <name>` is supported by scope-flexible flows such as `implement`, `review`, `review-fix`, `review-loop`, `run-go-tests-loop`, `run-go-linter-loop`, `gitlab-review`, and `gitlab-diff-review`
 - `--md-lang <en|ru>` currently applies to `plan`
-- `--force` only affects interactive mode and forces regeneration of task summary in Jira-backed flows
+- `--force` only affects interactive mode: it skips loading cached summary-pane content on startup so Jira-backed flows that regenerate summary artifacts can repopulate it during the run
 - Jira-backed flows ask for Jira input interactively when it is omitted
 - `task-describe` can also work from manual task description input without Jira
 - `gitlab-review` and `gitlab-diff-review` ask for a GitLab merge request URL interactively
 - `auto-status` and `auto-reset` currently operate on persisted state for `auto-golang`
 
-## `auto-golang` and `auto-common`
+## `auto-golang`, `auto-common`, and `auto-simple`
 
 `auto-golang` is the main resumable end-to-end automation flow. It stores persisted execution state and supports:
 
@@ -268,7 +276,9 @@ Notes:
 - reset via `auto-reset`
 - resume validation against saved launch profile and required artifacts
 
-`auto-common` is a separate built-in automation flow with its own phase list, but it does not currently have dedicated `auto-status` or `auto-reset` commands.
+`auto-common` is the planning-aware built-in automation flow. After `plan`, it runs a `design-review` loop and blocks implementation until the verdict is `approved` or `approved_with_warnings`. When the verdict is `needs_revision`, it runs `plan-revise` and then another `design-review`, for up to 3 design-review iterations total. If the final verdict still requires revision, the pipeline asks the operator whether to continue with the latest planning artifacts or stop before `implement`.
+
+`auto-simple` is the preserved simplified pipeline: `plan → implement → review loop`, with no planning review gate and no revise rounds. It is behaviorally equivalent to the legacy `auto-common` before the planning gate was introduced.
 
 ## Launch Profiles and Resume
 
@@ -295,7 +305,12 @@ The runtime uses artifacts as the contract between stages, including markdown ou
 
 ## Interactive TUI
 
-Running without a command opens the full-screen TUI. It acts as the operator console for the harness: browsing flows, launching them in scope, following activity, and reviewing summaries.
+Running without a command opens the full-screen TUI. It acts as the operator console for the harness: browsing flows, launching them in scope, following current execution, and reviewing summaries.
+
+Interactive mode is Ink-only. It requires:
+
+- a real TTY for both stdin and stdout
+- installed runtime dependencies from `npm install`
 
 Current navigation:
 
@@ -303,10 +318,17 @@ Current navigation:
 - `Left` / `Right` — collapse or expand folders
 - `Enter` — toggle folder or run selected flow
 - `Tab` / `Shift+Tab` — switch panes
-- `PgUp` / `PgDn` / `Home` / `End` — scroll focused pane
+- `PgUp` / `PgDn` — scroll focused pane
 - `h` — open help
 - `q` or `Ctrl+C` — exit
 
+Current layout:
+
+- left column: `Flows`, `Flow Description`, `Status`
+- right column: `Current Flow`, optional `Task Summary`, `Activity`
+- `Current Flow` is intentionally tall and scrollable; in the current layout it uses the same height budget as `Flows`
+- the `Task Summary` pane is runtime-driven and shows whichever markdown artifact the active flow publishes into summary state, such as a normalized task context or a cached task summary
+
 Flow discovery behavior:
 
 - built-in flows are loaded from `src/pipeline/flow-specs/`

package/dist/artifact-manifest.js

@@ -0,0 +1,219 @@
+import path from "node:path";
+import { TaskRunnerError } from "./errors.js";
+import { validateStructuredArtifactValue } from "./structured-artifacts.js";
+export const ARTIFACT_MANIFEST_SCHEMA_ID = "artifact-manifest/v1";
+export const ARTIFACT_MANIFEST_SCHEMA_VERSION = 1;
+export const ARTIFACT_LIFECYCLE_STATUSES = ["ready", "superseded", "stale"];
+export const ARTIFACT_PAYLOAD_FAMILIES = [
+    "structured-json",
+    "markdown",
+    "plain-text",
+    "helper-json",
+    "opaque-file",
+];
+const STRUCTURED_JSON_SCHEMAS_BY_PREFIX = [
+    { prefix: "bug-analyze-", schemaId: "bug-analysis/v1" },
+    { prefix: "bug-fix-design-", schemaId: "bug-fix-design/v1" },
+    { prefix: "bug-fix-plan-", schemaId: "bug-fix-plan/v1" },
+    { prefix: "design-review-", schemaId: "design-review/v1" },
+    { prefix: "design-", schemaId: "implementation-design/v1" },
+    { prefix: "gitlab-diff-", schemaId: "gitlab-mr-diff/v1" },
+    { prefix: "gitlab-review-", schemaId: "gitlab-review/v1" },
+    { prefix: "jira-description-", schemaId: "jira-description/v1" },
+    { prefix: "mr-description-", schemaId: "mr-description/v1" },
+    { prefix: "plan-", schemaId: "implementation-plan/v1" },
+    { prefix: "planning-questions-", schemaId: "planning-questions/v1" },
+    { prefix: "qa-", schemaId: "qa-plan/v1" },
+    { prefix: "review-assessment-", schemaId: "review-assessment/v1" },
+    { prefix: "review-fix-", schemaId: "review-fix-report/v1" },
+    { prefix: "review-", schemaId: "review-findings/v1" },
+    { prefix: "task-context-", schemaId: "task-context/v1" },
+    { prefix: "task-", schemaId: "task-summary/v1" },
+];
+const LOGICAL_KEY_PATTERN = "^[a-z0-9][a-z0-9._/-]*$";
+const CONTENT_HASH_PATTERN = "^sha256:[a-f0-9]{64}$";
+const ARTIFACT_ID_PATTERN = /^(?<scope>.+):(?<logicalKey>[a-z0-9][a-z0-9._/-]*):v(?<version>[1-9]\d*)$/;
+const LOGICAL_REF_PATTERN = /^(?<logicalKey>[a-z0-9][a-z0-9._/-]*)@(?<selector>latest|v[1-9]\d*)$/;
+export function parseSchemaVersion(schemaId) {
+    const match = /\/v(\d+)$/.exec(schemaId);
+    return match ? Number.parseInt(match[1] ?? "1", 10) : 1;
+}
+function normalizePathSeparators(value) {
+    return value.replace(/\\/g, "/");
+}
+function removeScopeSuffix(baseName, scopeKey) {
+    if (!scopeKey) {
+        return baseName;
+    }
+    const ext = path.extname(baseName);
+    const stem = ext ? baseName.slice(0, -ext.length) : baseName;
+    const escapedScope = scopeKey.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const patterns = [
+        new RegExp(`-${escapedScope}-iter-\\d+$`),
+        new RegExp(`-${escapedScope}-\\d+$`),
+        new RegExp(`-${escapedScope}$`),
+    ];
+    for (const pattern of patterns) {
+        if (pattern.test(stem)) {
+            return `${stem.replace(pattern, "")}${ext}`;
+        }
+    }
+    if (stem === scopeKey) {
+        return `scope${ext}`;
+    }
+    return baseName;
+}
+export function buildLogicalKeyForPayload(scopeKey, payloadPath) {
+    const normalized = normalizePathSeparators(payloadPath);
+    const normalizedScopeKey = typeof scopeKey === "string" && scopeKey.trim().length > 0 ? scopeKey : null;
+    const scopeMarker = normalizedScopeKey
+        ? normalizePathSeparators(`/.agentweaver/scopes/${normalizedScopeKey}/`)
+        : null;
+    const markerIndex = scopeMarker ? normalized.lastIndexOf(scopeMarker) : -1;
+    const artifactsMarker = normalizePathSeparators("/.artifacts/");
+    const artifactsIndex = normalized.lastIndexOf(artifactsMarker);
+    const relative = markerIndex >= 0 && scopeMarker
+        ? normalized.slice(markerIndex + scopeMarker.length)
+        : artifactsIndex >= 0
+            ? normalized.slice(artifactsIndex + 1)
+            : path.basename(normalized);
+    const directory = path.posix.dirname(relative);
+    const baseName = path.posix.basename(relative);
+    const normalizedBaseName = removeScopeSuffix(baseName, normalizedScopeKey)
+        .replace(/-\d+(?=\.[^.]+$)/, "")
+        .replace(/[^a-zA-Z0-9._/-]+/g, "-")
+        .replace(/-+/g, "-")
+        .toLowerCase();
+    const combined = directory === "." ? normalizedBaseName : `${directory}/${normalizedBaseName}`;
+    return combined.replace(/^\.artifacts\//, "artifacts/");
+}
+export function buildPublicationKey(input) {
+    return `${input.publicationRunId ?? input.runId}:${input.flowId}:${input.phaseId}:${input.stepId}:${input.logicalKey}`;
+}
+export function buildArtifactId(scopeKey, logicalKey, version) {
+    return `${scopeKey}:${logicalKey}:v${version}`;
+}
+export function parseArtifactId(value) {
+    const match = ARTIFACT_ID_PATTERN.exec(value);
+    if (!match?.groups) {
+        return null;
+    }
+    const scopeKey = match.groups.scope;
+    const logicalKey = match.groups.logicalKey;
+    const versionText = match.groups.version;
+    if (!scopeKey || !logicalKey || !versionText) {
+        return null;
+    }
+    return {
+        scopeKey,
+        logicalKey,
+        version: Number.parseInt(versionText, 10),
+    };
+}
+export function parseArtifactReference(value) {
+    const parsedId = parseArtifactId(value);
+    if (parsedId) {
+        return {
+            kind: "artifact-id",
+            artifactId: value,
+            parsedId,
+        };
+    }
+    const match = LOGICAL_REF_PATTERN.exec(value);
+    if (!match?.groups) {
+        return null;
+    }
+    const logicalKey = match.groups.logicalKey;
+    const selector = match.groups.selector;
+    if (!logicalKey || !selector) {
+        return null;
+    }
+    return {
+        kind: "logical-ref",
+        logicalKey,
+        version: selector === "latest" ? "latest" : Number.parseInt(selector.slice(1), 10),
+    };
+}
+export function inferPayloadContract(scopeKey, payloadPath, override) {
+    if (override?.payloadFamily && override.schemaId && override.schemaVersion) {
+        return {
+            payloadFamily: override.payloadFamily,
+            schemaId: override.schemaId,
+            schemaVersion: override.schemaVersion,
+        };
+    }
+    const baseName = path.basename(payloadPath);
+    if (override?.schemaId) {
+        return {
+            payloadFamily: override.payloadFamily ?? "structured-json",
+            schemaId: override.schemaId,
+            schemaVersion: override.schemaVersion ?? parseSchemaVersion(override.schemaId),
+        };
+    }
+    if (payloadPath.endsWith(".json")) {
+        if (baseName === `${scopeKey}.json` || baseName === `${scopeKey}-enriched.json`) {
+            return { payloadFamily: "helper-json", schemaId: "helper-json/v1", schemaVersion: 1 };
+        }
+        if (baseName.startsWith("jira-attachments-")) {
+            return { payloadFamily: "helper-json", schemaId: "helper-json/v1", schemaVersion: 1 };
+        }
+        if (baseName.startsWith("planning-answers-")) {
+            return { payloadFamily: "structured-json", schemaId: "user-input/v1", schemaVersion: 1 };
+        }
+        if (baseName.startsWith("instant-task-input-")) {
+            return { payloadFamily: "structured-json", schemaId: "user-input/v1", schemaVersion: 1 };
+        }
+        for (const candidate of STRUCTURED_JSON_SCHEMAS_BY_PREFIX) {
+            if (baseName.startsWith(candidate.prefix)) {
+                return {
+                    payloadFamily: "structured-json",
+                    schemaId: candidate.schemaId,
+                    schemaVersion: parseSchemaVersion(candidate.schemaId),
+                };
+            }
+        }
+        return { payloadFamily: "helper-json", schemaId: "helper-json/v1", schemaVersion: 1 };
+    }
+    if (payloadPath.endsWith(".md")) {
+        return { payloadFamily: "markdown", schemaId: "markdown/v1", schemaVersion: 1 };
+    }
+    if (payloadPath.endsWith(".txt")) {
+        return { payloadFamily: "plain-text", schemaId: "plain-text/v1", schemaVersion: 1 };
+    }
+    return { payloadFamily: "opaque-file", schemaId: "opaque-file/v1", schemaVersion: 1 };
+}
+export function createProducerSummary(input) {
+    const parts = [input.node];
+    if (input.executor) {
+        parts.push(`via ${input.executor}`);
+    }
+    if (input.model) {
+        parts.push(`model ${input.model}`);
+    }
+    return parts.join(" ");
+}
+export function validateArtifactManifest(manifest, label = "$") {
+    validateStructuredArtifactValue(manifest, ARTIFACT_MANIFEST_SCHEMA_ID, label);
+    if (!new RegExp(LOGICAL_KEY_PATTERN).test(manifest.logical_key)) {
+        throw new TaskRunnerError(`Structured artifact ${label} failed schema ${ARTIFACT_MANIFEST_SCHEMA_ID} validation:\n${label}.logical_key must be a string with the expected format`);
+    }
+    if (!new RegExp(CONTENT_HASH_PATTERN).test(manifest.content_hash)) {
+        throw new TaskRunnerError(`Structured artifact ${label} failed schema ${ARTIFACT_MANIFEST_SCHEMA_ID} validation:\n${label}.content_hash must be a string with the expected format`);
+    }
+}
+export function diagnosticsForManifest(manifest, validatePayload) {
+    try {
+        validatePayload(manifest.schema_id, manifest.payload_path);
+        return [];
+    }
+    catch (error) {
+        const message = error.message;
+        return [
+            {
+                code: message.includes("not registered") ? "missing-schema" : "invalid-schema",
+                severity: "error",
+                message,
+            },
+        ];
+    }
+}

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");
@@ -25,6 +24,12 @@ export function scopeArtifactsDir(scopeKey) {
 export function scopeArtifactsFile(scopeKey, fileName) {
     return path.join(scopeArtifactsDir(scopeKey), fileName);
 }
+export function artifactManifestSidecarPath(payloadPath) {
+    return `${payloadPath}.manifest.json`;
+}
+export function artifactIndexFile(scopeKey) {
+    return scopeArtifactsFile(scopeKey, "artifact-index.json");
+}
 export function taskWorkspaceDir(taskKey) {
     return scopeWorkspaceDir(taskKey);
 }
@@ -152,9 +157,18 @@ export function jiraDescriptionFile(taskKey, iteration) {
 export function jiraDescriptionJsonFile(taskKey, iteration) {
     return versionedJsonArtifactFile(taskKey, "jira-description", iteration);
 }
+export function taskContextFile(taskKey, iteration) {
+    return versionedMarkdownArtifactFile(taskKey, "task-context", iteration);
+}
+export function taskContextJsonFile(taskKey, iteration) {
+    return versionedJsonArtifactFile(taskKey, "task-context", iteration);
+}
 export function taskDescribeInputJsonFile(taskKey) {
     return taskArtifactsFile(taskKey, `task-describe-input-${taskKey}.json`);
 }
+export function instantTaskInputJsonFile(taskKey) {
+    return taskArtifactsFile(taskKey, `instant-task-input-${taskKey}.json`);
+}
 export function gitStatusJsonFile(taskKey) {
     return taskArtifactsFile(taskKey, `git-status-${taskKey}.json`);
 }
@@ -219,6 +233,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];