@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/core/validation/dependencies.js

@@ -0,0 +1,113 @@
+/**
+ * Validate task dependency graph in blueprint markdown.
+ *
+ * Checks:
+ * - No dangling dependency references (Task X.Y that doesn't exist)
+ * - No circular dependencies (A → B → A)
+ */
+import { parseTaskBlocks } from './task-blocks.js';
+const TASK_ID_IN_DEPENDS_REGEX = /Task\s+(\d+\.\d+)/g;
+/** Extract task IDs and their dependencies from markdown using line-by-line parsing */
+function extractTaskDeps(markdown) {
+    const taskDeps = new Map();
+    function finalizeBlock(taskId, block) {
+        const deps = [];
+        const dependsMatch = /\*\*Depends:\*\*\s*(.*)/m.exec(block);
+        if (dependsMatch?.[1]) {
+            const dependsText = dependsMatch[1];
+            let refMatch;
+            const regex = new RegExp(TASK_ID_IN_DEPENDS_REGEX.source, 'g');
+            while ((refMatch = regex.exec(dependsText)) !== null) {
+                if (refMatch[1]) {
+                    deps.push(refMatch[1]);
+                }
+            }
+        }
+        taskDeps.set(taskId, deps);
+    }
+    for (const { taskId, block } of parseTaskBlocks(markdown)) {
+        finalizeBlock(taskId, block);
+    }
+    return taskDeps;
+}
+/** Find dangling references — deps that reference non-existent tasks */
+function findDanglingRefs(taskDeps) {
+    const knownIds = new Set(taskDeps.keys());
+    const dangling = [];
+    for (const [taskId, deps] of taskDeps) {
+        for (const dep of deps) {
+            if (!knownIds.has(dep)) {
+                dangling.push(`Task ${taskId} → Task ${dep} (does not exist)`);
+            }
+        }
+    }
+    return dangling;
+}
+/** Detect circular dependencies using DFS. Returns cycle descriptions. */
+function findCycles(taskDeps) {
+    const WHITE = 0; // unvisited
+    const GRAY = 1; // in current DFS path
+    const BLACK = 2; // fully visited
+    const color = new Map();
+    const cycles = [];
+    for (const id of taskDeps.keys()) {
+        color.set(id, WHITE);
+    }
+    function dfs(node, path) {
+        color.set(node, GRAY);
+        path.push(node);
+        for (const neighbor of taskDeps.get(node) ?? []) {
+            if (!color.has(neighbor))
+                continue; // dangling ref, skip
+            if (color.get(neighbor) === GRAY) {
+                // Found cycle — trace back to where cycle starts
+                const cycleStart = path.indexOf(neighbor);
+                if (cycleStart !== -1) {
+                    const cycle = [...path.slice(cycleStart), neighbor];
+                    cycles.push(cycle.map((id) => `Task ${id}`).join(' → '));
+                }
+            }
+            else if (color.get(neighbor) === WHITE) {
+                dfs(neighbor, path);
+            }
+        }
+        path.pop();
+        color.set(node, BLACK);
+    }
+    for (const id of taskDeps.keys()) {
+        if (color.get(id) === WHITE) {
+            dfs(id, []);
+        }
+    }
+    return cycles;
+}
+/**
+ * Validate task dependency graph in blueprint markdown.
+ */
+export function validateTaskDependencies(markdown) {
+    const taskDeps = extractTaskDeps(markdown);
+    if (taskDeps.size === 0) {
+        return { valid: true };
+    }
+    const danglingRefs = findDanglingRefs(taskDeps);
+    const cycles = findCycles(taskDeps);
+    if (!danglingRefs.length && !cycles.length) {
+        return { valid: true };
+    }
+    const errorParts = [];
+    if (cycles.length > 0) {
+        errorParts.push(`Circular dependencies detected: ${cycles.join('; ')}`);
+    }
+    if (danglingRefs.length > 0) {
+        errorParts.push(`Dangling dependency references: ${danglingRefs.join('; ')}`);
+    }
+    return {
+        valid: false,
+        error: errorParts.join('. '),
+        details: {
+            cycles: cycles.length > 0 ? cycles : undefined,
+            danglingRefs: danglingRefs.length > 0 ? danglingRefs : undefined,
+        },
+    };
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/esm/blueprint/core/validation/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared plan validation utilities for CLI tools.
+ */
+export type { CriteriaResult, ValidationResult } from '#core/types';
+export { checkAcceptanceCriteria } from './criteria.js';
+export type { DependencyValidationResult } from './dependencies.js';
+export { validateTaskDependencies } from './dependencies.js';
+export { checkChangelog, validatePlanLinks } from './links.js';
+export { validateEmbeddedPhases } from './phases.js';
+export { validatePlanState } from './state.js';
+export { validatePlanTemplate } from './template.js';
+export { validateTaskSections } from './task-sections.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/blueprint/core/validation/index.js

@@ -0,0 +1,11 @@
+/**
+ * Shared plan validation utilities for CLI tools.
+ */
+export { checkAcceptanceCriteria } from './criteria.js';
+export { validateTaskDependencies } from './dependencies.js';
+export { checkChangelog, validatePlanLinks } from './links.js';
+export { validateEmbeddedPhases } from './phases.js';
+export { validatePlanState } from './state.js';
+export { validatePlanTemplate } from './template.js';
+export { validateTaskSections } from './task-sections.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/blueprint/core/validation/links.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Validate internal plan links.
+ */
+/**
+ * Validate internal plan links.
+ */
+export declare function validatePlanLinks(markdown: string, filePath: string): {
+    valid: boolean;
+    brokenLinks: string[];
+};
+/**
+ * Check for CHANGELOG.md in completed plans.
+ */
+export declare function checkChangelog(filePath: string): {
+    hasChangelog: boolean;
+    warning?: string;
+};
+//# sourceMappingURL=links.d.ts.map

package/dist/esm/blueprint/core/validation/links.js

@@ -0,0 +1,47 @@
+/**
+ * Validate internal plan links.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Validate internal plan links.
+ */
+export function validatePlanLinks(markdown, filePath) {
+    const linkRegex = /\[([^\]]+)\]\((\.\.[^)]+|\.\/[^)]+)\)/g;
+    const matches = Array.from(markdown.matchAll(linkRegex));
+    const brokenLinks = [];
+    const planDir = dirname(filePath);
+    for (const match of matches) {
+        const linkPath = match[2];
+        if (!linkPath)
+            continue;
+        if (linkPath.startsWith('http') || linkPath.startsWith('#'))
+            continue;
+        const targetPath = resolve(planDir, linkPath);
+        if (!existsSync(targetPath)) {
+            brokenLinks.push(linkPath);
+        }
+    }
+    return {
+        valid: !brokenLinks.length,
+        brokenLinks,
+    };
+}
+/**
+ * Check for CHANGELOG.md in completed plans.
+ */
+export function checkChangelog(filePath) {
+    if (!filePath.includes('/completed/')) {
+        return { hasChangelog: true };
+    }
+    const planDir = dirname(filePath);
+    const changelogPath = join(planDir, 'CHANGELOG.md');
+    if (!existsSync(changelogPath)) {
+        return {
+            hasChangelog: false,
+            warning: 'Completed plan missing CHANGELOG.md (recommended)',
+        };
+    }
+    return { hasChangelog: true };
+}
+//# sourceMappingURL=links.js.map

package/dist/esm/blueprint/core/validation/phases.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Check for embedded phases in plan overview files.
+ */
+/**
+ * Check for embedded phases in _overview.md.
+ */
+export declare function validateEmbeddedPhases(markdown: string): {
+    hasEmbedded: boolean;
+    phases: string[];
+    warning?: string;
+};
+//# sourceMappingURL=phases.d.ts.map

package/dist/esm/blueprint/core/validation/phases.js

@@ -0,0 +1,18 @@
+/**
+ * Check for embedded phases in plan overview files.
+ */
+/**
+ * Check for embedded phases in _overview.md.
+ */
+export function validateEmbeddedPhases(markdown) {
+    const phaseHeaders = markdown.match(/^###? Phase \d+/gm) || [];
+    if (phaseHeaders.length > 0) {
+        return {
+            hasEmbedded: true,
+            phases: phaseHeaders,
+            warning: `Plan has ${phaseHeaders.length} embedded phase(s). Consider using separate phase-N-*.md files`,
+        };
+    }
+    return { hasEmbedded: false, phases: [] };
+}
+//# sourceMappingURL=phases.js.map

package/dist/esm/blueprint/core/validation/state.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validate plan state consistency with folder structure and checkbox status.
+ */
+import type { ValidationResult } from '#core/types';
+/**
+ * Validate plan state consistency.
+ */
+export declare function validatePlanState(markdown: string, filePath?: string): ValidationResult;
+//# sourceMappingURL=state.d.ts.map

package/dist/esm/blueprint/core/validation/state.js

@@ -0,0 +1,123 @@
+/**
+ * Validate plan state consistency with folder structure and checkbox status.
+ */
+import { planStatusSchema } from '#core/schema';
+import { checkAcceptanceCriteria } from './criteria.js';
+/**
+ * Validate plan is in completed/ folder if status is completed.
+ */
+function validateCompletedFolder(status, isInCompleted, criteria) {
+    if (status === 'completed' && !isInCompleted) {
+        return {
+            valid: false,
+            error: 'Plan has status: completed but is not in completed/ folder. Move it with: git mv <path> webpresso/blueprints/completed/',
+        };
+    }
+    if (isInCompleted && status !== 'completed') {
+        return {
+            valid: false,
+            error: `Plan is in completed/ folder but has status: ${status} (expected status: completed)`,
+        };
+    }
+    if (status === 'completed' && !criteria.allChecked) {
+        return {
+            valid: false,
+            error: `Plan has status: completed but only ${criteria.checked}/${criteria.total} acceptance criteria are checked`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate plan is in draft/ folder if status is draft.
+ */
+function validateDraftFolder(status, isInDraft, criteria) {
+    if (status === 'draft' && !isInDraft) {
+        return {
+            valid: false,
+            error: 'Plan has status: draft but is not in draft/ folder. Move it with: git mv <path> webpresso/blueprints/draft/',
+        };
+    }
+    if (isInDraft && status !== 'draft') {
+        return {
+            valid: false,
+            error: `Plan is in draft/ folder but has status: ${status} (expected status: draft)`,
+        };
+    }
+    if (status === 'draft' && criteria.checked > 0) {
+        return {
+            valid: false,
+            error: `Plan has status: draft but ${criteria.checked} acceptance criteria are checked (expected 0)`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate plan is in parked/ folder if status is parked.
+ */
+function validateParkedFolder(status, isInParked) {
+    if (status === 'parked' && !isInParked) {
+        return {
+            valid: false,
+            error: 'Plan has status: parked but is not in parked/ folder. Move it with: git mv <path> webpresso/blueprints/parked/',
+        };
+    }
+    if (isInParked && status !== 'parked') {
+        return {
+            valid: false,
+            error: `Plan is in parked/ folder but has status: ${status} (expected status: parked)`,
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate state without path information.
+ */
+function validateStateOnly(status, criteria) {
+    if (status === 'completed' && !criteria.allChecked) {
+        return { valid: false, error: 'Plan completed but criteria not met' };
+    }
+    if (status === 'draft' && criteria.checked > 0) {
+        return { valid: false, error: 'Plan draft but criteria checked' };
+    }
+    return { valid: true };
+}
+/**
+ * Validate state with path information.
+ */
+function validateStateWithPath(status, filePath, criteria) {
+    const isInCompleted = filePath.includes('/completed/') || filePath.includes('completed/');
+    const isInDraft = filePath.includes('/draft/') || filePath.includes('draft/');
+    const isInParked = filePath.includes('/parked/') || filePath.includes('parked/');
+    const completedResult = validateCompletedFolder(status, isInCompleted, criteria);
+    if (!completedResult.valid)
+        return completedResult;
+    const draftResult = validateDraftFolder(status, isInDraft, criteria);
+    if (!draftResult.valid)
+        return draftResult;
+    const parkedResult = validateParkedFolder(status, isInParked);
+    if (!parkedResult.valid)
+        return parkedResult;
+    return { valid: true };
+}
+/**
+ * Validate plan state consistency.
+ */
+export function validatePlanState(markdown, filePath) {
+    const statusMatch = markdown.match(/^status:\s*(\S+)/m);
+    const status = statusMatch?.[1];
+    if (!status) {
+        return { valid: true };
+    }
+    if (!planStatusSchema.safeParse(status).success) {
+        return {
+            valid: false,
+            error: `Plan has invalid status: ${status}. Valid statuses: ${planStatusSchema.options.join(', ')}`,
+        };
+    }
+    const criteria = checkAcceptanceCriteria(markdown);
+    if (!filePath) {
+        return validateStateOnly(status, criteria);
+    }
+    return validateStateWithPath(status, filePath, criteria);
+}
+//# sourceMappingURL=state.js.map

package/dist/esm/blueprint/core/validation/task-blocks.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+export interface TaskBlock {
+    taskId: string;
+    block: string;
+}
+/**
+ * Zod schema for optional TASK-level frontmatter fields.
+ *
+ * - `runners`: optional list of execution backend ids; absent/empty means all runners allowed.
+ * - `permissions`: access level the task requires; defaults to `'workspace-write'` when absent.
+ */
+export declare const taskFrontmatterSchema: z.ZodObject<{
+    runners: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        "omx-team": "omx-team";
+        "omx-pll-interactive": "omx-pll-interactive";
+        "claude-subagent": "claude-subagent";
+        "codex-exec": "codex-exec";
+        "local-worktree": "local-worktree";
+    }>>>;
+    permissions: z.ZodDefault<z.ZodEnum<{
+        read: "read";
+        "workspace-write": "workspace-write";
+    }>>;
+}, z.core.$strip>;
+export type TaskFrontmatter = z.infer<typeof taskFrontmatterSchema>;
+export declare function parseTaskBlocks(markdown: string): TaskBlock[];
+//# sourceMappingURL=task-blocks.d.ts.map

package/dist/esm/blueprint/core/validation/task-blocks.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { executionBackendSchema } from '#types/execution-backend';
+const TASK_HEADING_REGEX = /^####\s+Task\s+(\d+\.\d+):/;
+/**
+ * Zod schema for optional TASK-level frontmatter fields.
+ *
+ * - `runners`: optional list of execution backend ids; absent/empty means all runners allowed.
+ * - `permissions`: access level the task requires; defaults to `'workspace-write'` when absent.
+ */
+export const taskFrontmatterSchema = z.object({
+    runners: executionBackendSchema.array().optional(),
+    permissions: z.enum(['read', 'workspace-write']).default('workspace-write'),
+});
+export function parseTaskBlocks(markdown) {
+    const taskBlocks = [];
+    const lines = markdown.split('\n');
+    let currentTaskId = null;
+    let currentBlock = '';
+    function finalizeBlock(taskId, block) {
+        taskBlocks.push({ taskId, block });
+    }
+    for (const line of lines) {
+        const taskMatch = TASK_HEADING_REGEX.exec(line);
+        if (taskMatch?.[1]) {
+            if (currentTaskId !== null) {
+                finalizeBlock(currentTaskId, currentBlock);
+            }
+            currentTaskId = taskMatch[1];
+            currentBlock = `${line}\n`;
+            continue;
+        }
+        if (currentTaskId === null) {
+            continue;
+        }
+        if (/^#{1,3}\s/.test(line) && !line.startsWith('####')) {
+            finalizeBlock(currentTaskId, currentBlock);
+            currentTaskId = null;
+            currentBlock = '';
+            continue;
+        }
+        currentBlock += `${line}\n`;
+    }
+    if (currentTaskId !== null) {
+        finalizeBlock(currentTaskId, currentBlock);
+    }
+    return taskBlocks;
+}
+//# sourceMappingURL=task-blocks.js.map

package/dist/esm/blueprint/core/validation/task-sections.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validate per-task required sections in blueprint markdown.
+ *
+ * Checks (for type: blueprint only, not parent-roadmap):
+ * - Each accepted task block (`#### [lane] Task X.Y:` or `#### Task X.Y:`) has **Depends:** line
+ * - Each accepted task block has **Acceptance:** with at least one checkbox
+ */
+import type { ValidationResult } from '#core/types';
+/**
+ * Validate per-task required sections.
+ * Only validates blueprints with type: blueprint (skips parent-roadmap).
+ */
+export declare function validateTaskSections(markdown: string, docType?: string): ValidationResult;
+//# sourceMappingURL=task-sections.d.ts.map

package/dist/esm/blueprint/core/validation/task-sections.js

@@ -0,0 +1,60 @@
+/**
+ * Validate per-task required sections in blueprint markdown.
+ *
+ * Checks (for type: blueprint only, not parent-roadmap):
+ * - Each accepted task block (`#### [lane] Task X.Y:` or `#### Task X.Y:`) has **Depends:** line
+ * - Each accepted task block has **Acceptance:** with at least one checkbox
+ */
+import { parseTaskBlocks } from './task-blocks.js';
+const DEPENDS_REGEX = /\*\*Depends:\*\*/;
+const ACCEPTANCE_WITH_CHECKBOX_REGEX = /\*\*Acceptance(?:\s+Criteria)?:\*\*[\s\S]*?- \[[ x]\]/;
+/** Extract doc type from frontmatter */
+function extractDocType(markdown) {
+    const match = /^type:\s*(\S+)/m.exec(markdown);
+    return match?.[1] ?? null;
+}
+/** Find task blocks missing required sections */
+function findTaskSectionIssues(markdown) {
+    const issues = [];
+    function checkBlock(taskId, block) {
+        const missingDepends = !DEPENDS_REGEX.test(block);
+        const missingAcceptance = !ACCEPTANCE_WITH_CHECKBOX_REGEX.test(block);
+        if (missingDepends || missingAcceptance) {
+            issues.push({ taskId, missingDepends, missingAcceptance });
+        }
+    }
+    for (const { taskId, block } of parseTaskBlocks(markdown)) {
+        checkBlock(taskId, block);
+    }
+    return issues;
+}
+/**
+ * Validate per-task required sections.
+ * Only validates blueprints with type: blueprint (skips parent-roadmap).
+ */
+export function validateTaskSections(markdown, docType) {
+    // Determine doc type from parameter or frontmatter
+    const type = docType ?? extractDocType(markdown);
+    // Only validate blueprint type documents, not parent-roadmap
+    if (type !== 'blueprint') {
+        return { valid: true };
+    }
+    const issues = findTaskSectionIssues(markdown);
+    if (!issues.length) {
+        return { valid: true };
+    }
+    const errorMessages = [];
+    for (const issue of issues) {
+        const missing = [];
+        if (issue.missingDepends)
+            missing.push('**Depends:**');
+        if (issue.missingAcceptance)
+            missing.push('**Acceptance:** with checkbox');
+        errorMessages.push(`Task ${issue.taskId} missing required sections: ${missing.join(', ')}`);
+    }
+    return {
+        valid: false,
+        error: errorMessages.join('; '),
+    };
+}
+//# sourceMappingURL=task-sections.js.map

package/dist/esm/blueprint/core/validation/template.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validate plan has required template sections.
+ */
+import type { ValidationResult } from '#core/types';
+/**
+ * Validate plan has required template sections.
+ */
+export declare function validatePlanTemplate(markdown: string): ValidationResult;
+//# sourceMappingURL=template.d.ts.map

package/dist/esm/blueprint/core/validation/template.js

@@ -0,0 +1,65 @@
+/**
+ * Validate plan has required template sections.
+ */
+import { checkAcceptanceCriteria } from './criteria.js';
+/**
+ * Check for required overview sections.
+ */
+function checkRequiredOverview(markdown) {
+    const hasOverview = /^## Overview/m.test(markdown) ||
+        /^## Problem Statement/m.test(markdown) ||
+        /^## Problem & Goal/m.test(markdown);
+    if (!hasOverview) {
+        return {
+            valid: false,
+            error: 'Plan missing required section: ## Overview (or ## Problem Statement)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Check for required acceptance criteria.
+ */
+function checkRequiredCriteria(markdown) {
+    const hasAcceptanceCriteria = /^## Acceptance Criteria/m.test(markdown);
+    const criteria = checkAcceptanceCriteria(markdown);
+    if (!hasAcceptanceCriteria && criteria.total === 0) {
+        return {
+            valid: false,
+            error: 'Plan missing required section: ## Acceptance Criteria (with checkboxes)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Check for required implementation sections.
+ */
+function checkRequiredImplementation(markdown) {
+    const hasImplementation = /^## Phases/m.test(markdown) ||
+        /^## Tasks/m.test(markdown) ||
+        /^## Implementation/m.test(markdown) ||
+        /^### Phase \d/m.test(markdown);
+    if (!hasImplementation) {
+        return {
+            valid: false,
+            error: 'Plan missing required section: ## Phases (or ## Tasks or ## Implementation)',
+        };
+    }
+    return { valid: true };
+}
+/**
+ * Validate plan has required template sections.
+ */
+export function validatePlanTemplate(markdown) {
+    const hasOverview = checkRequiredOverview(markdown);
+    if (!hasOverview.valid)
+        return hasOverview;
+    const hasCriteria = checkRequiredCriteria(markdown);
+    if (!hasCriteria.valid)
+        return hasCriteria;
+    const hasImplementation = checkRequiredImplementation(markdown);
+    if (!hasImplementation.valid)
+        return hasImplementation;
+    return { valid: true };
+}
+//# sourceMappingURL=template.js.map

package/dist/esm/blueprint/cross-repo/allowlist.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cross-org correlation allowlist loader.
+ *
+ * Reads `.agent/correlate.allow.yaml` from the repo root.
+ * The file declares which orgs this repo permits cross-org correlation with.
+ * Both sides must allowlist each other for a dependency to resolve.
+ *
+ * File format:
+ *   permits:
+ *     - other-org
+ *     - trusted-partner
+ */
+import type { AllowlistEntry } from './resolver.js';
+export type { AllowlistEntry };
+/**
+ * Reads `.agent/correlate.allow.yaml` from `cwd`, validates it, and returns
+ * a flat array of `AllowlistEntry` rows ready for SQL insert.
+ *
+ * The source_org is derived from the git remote of `cwd`.
+ * Missing file or invalid YAML returns an empty array (no error thrown).
+ */
+export declare function loadAllowlist(cwd: string): AllowlistEntry[];
+/**
+ * Returns true when both `sourceOrg` and `targetOrg` have allowlisted each
+ * other in the provided entries.
+ */
+export declare function bothSidesAllowlist(sourceOrg: string, targetOrg: string, allowlist: readonly AllowlistEntry[]): boolean;
+//# sourceMappingURL=allowlist.d.ts.map