agentplane 0.3.2 → 0.3.3

package/dist/commands/doctor/archive.js

@@ -0,0 +1,211 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+const DEFAULT_RECENT_DONE_TASK_LIMIT = 200;
+function pluralize(count, singular, plural = `${singular}s`) {
+    return count === 1 ? singular : plural;
+}
+function formatIdExamples(ids, maxExamples = 3) {
+    const shown = ids.slice(0, maxExamples);
+    const remainder = ids.length - shown.length;
+    return remainder > 0 ? `${shown.join(", ")}; +${remainder} more` : shown.join(", ");
+}
+function taskShortId(taskId) {
+    const shortId = taskId.split("-").at(-1) ?? taskId;
+    return shortId.trim().toUpperCase();
+}
+function textOrEmpty(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function collectTaskEvidenceText(task) {
+    const chunks = [
+        textOrEmpty(task.title),
+        textOrEmpty(task.result_summary),
+        textOrEmpty(task.verification?.note),
+        textOrEmpty(task.commit?.message),
+        ...(Array.isArray(task.comments)
+            ? task.comments.map((entry) => textOrEmpty(entry?.body)).filter(Boolean)
+            : []),
+        ...(Array.isArray(task.tags) ? task.tags.filter((tag) => typeof tag === "string") : []),
+    ];
+    return chunks.filter(Boolean).join("\n");
+}
+function classifyUnknownHistoricalHash(task) {
+    void task;
+    return "INFO";
+}
+function classifyCloseCommitReference(task, subject) {
+    if (/\bclose:\s*record task doc\b/iu.test(subject)) {
+        return "INFO";
+    }
+    const evidence = collectTaskEvidenceText(task);
+    if (/(no-op|already implemented|already fixed|already present|without changes|task deemed not актуальна|obsolete|no changes)/iu.test(evidence)) {
+        return "INFO";
+    }
+    const subjectTaskId = /^\s*✅\s+([A-Z0-9]{6})\s+close:/u.exec(subject)?.[1] ?? "";
+    const currentTaskId = typeof task.id === "string" ? taskShortId(task.id) : "";
+    if (subjectTaskId && currentTaskId && subjectTaskId !== currentTaskId) {
+        return "INFO";
+    }
+    if (/\b(epic|roadmap|spike|meta)\b/iu.test(evidence)) {
+        return "INFO";
+    }
+    return "WARN";
+}
+function summarizeHistoricalFindings(findings, opts) {
+    if (findings.length === 0)
+        return [];
+    const prefix = `[${opts.severity}]`;
+    if (findings.length === 1) {
+        const [finding] = findings;
+        const subjectSuffix = opts.includeSubject && finding.subject ? ` (${finding.subject})` : "";
+        return [`${prefix} ${opts.singlePrefix}: ${finding.id} -> ${finding.hash}${subjectSuffix}`];
+    }
+    const grouped = new Map();
+    for (const finding of findings) {
+        const existing = grouped.get(finding.hash);
+        if (existing) {
+            existing.ids.push(finding.id);
+            if (!existing.subject && finding.subject)
+                existing.subject = finding.subject;
+            continue;
+        }
+        grouped.set(finding.hash, {
+            hash: finding.hash,
+            ids: [finding.id],
+            subject: finding.subject,
+        });
+    }
+    const groups = [...grouped.values()].toSorted((left, right) => {
+        const countDelta = right.ids.length - left.ids.length;
+        if (countDelta !== 0)
+            return countDelta;
+        return left.hash.localeCompare(right.hash);
+    });
+    const exampleGroups = groups.slice(0, 3).map((group) => {
+        const subjectSuffix = opts.includeSubject && group.subject ? `; subject: ${group.subject}` : "";
+        return `${group.hash} (${group.ids.length} ${pluralize(group.ids.length, "task")}: ${formatIdExamples(group.ids)}${subjectSuffix})`;
+    });
+    const remainingGroups = groups.length - exampleGroups.length;
+    const groupedSuffix = remainingGroups > 0 ? `; +${remainingGroups} more hash groups` : "";
+    return [
+        `${prefix} Historical task archive contains ${findings.length} DONE tasks with ${opts.summaryLabel} across ${groups.length} distinct commit ${opts.groupLabel}. Examples: ${exampleGroups.join("; ")}${groupedSuffix}`,
+    ];
+}
+export async function checkDoneTaskCommitInvariants(repoRoot, opts = {}) {
+    const tasksPath = path.join(repoRoot, ".agentplane", "tasks.json");
+    let raw = "";
+    try {
+        raw = await fs.readFile(tasksPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [`Invalid JSON snapshot: ${path.relative(repoRoot, tasksPath)}`];
+    }
+    const all = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+    const allDone = all.filter((t) => {
+        const status = typeof t.status === "string" ? t.status : "";
+        return status.toUpperCase() === "DONE";
+    });
+    const done = opts.fullArchive ? allDone : allDone.slice(-DEFAULT_RECENT_DONE_TASK_LIMIT);
+    if (done.length === 0)
+        return [];
+    const problems = [];
+    const unknownHashFindings = [];
+    const closeCommitWarnFindings = [];
+    const closeCommitInfoFindings = [];
+    const hashes = new Set();
+    for (const task of done) {
+        const id = typeof task.id === "string" ? task.id : "<unknown>";
+        const hash = typeof task.commit?.hash === "string" ? task.commit.hash.trim() : "";
+        if (!hash) {
+            problems.push(`DONE task is missing implementation commit hash: ${id} (finish with --commit <hash>).`);
+            continue;
+        }
+        hashes.add(hash);
+    }
+    if (hashes.size === 0)
+        return problems;
+    const subjectByHash = await resolveCommitSubjects(repoRoot, [...hashes]);
+    for (const task of done) {
+        const id = typeof task.id === "string" ? task.id : "<unknown>";
+        const hash = typeof task.commit?.hash === "string" ? task.commit.hash.trim() : "";
+        if (!hash)
+            continue;
+        const subject = subjectByHash.get(hash) ?? "";
+        if (!subject) {
+            unknownHashFindings.push({
+                id,
+                hash,
+                severity: classifyUnknownHistoricalHash(task),
+            });
+            continue;
+        }
+        if (/\bclose:/iu.test(subject)) {
+            const severity = classifyCloseCommitReference(task, subject);
+            const finding = { id, hash, subject, severity };
+            if (severity === "WARN")
+                closeCommitWarnFindings.push(finding);
+            else
+                closeCommitInfoFindings.push(finding);
+        }
+    }
+    problems.push(...summarizeHistoricalFindings(unknownHashFindings, {
+        singlePrefix: "DONE task references unknown historical commit hash",
+        groupLabel: "hashes",
+        summaryLabel: "unknown implementation commit hashes",
+        includeSubject: false,
+        severity: "INFO",
+    }), ...summarizeHistoricalFindings(closeCommitInfoFindings, {
+        singlePrefix: "DONE task implementation commit resolves to a historical close commit reference",
+        groupLabel: "hashes",
+        summaryLabel: "historical close-commit references that were classified as non-actionable archive records",
+        includeSubject: true,
+        severity: "INFO",
+    }), ...summarizeHistoricalFindings(closeCommitWarnFindings, {
+        singlePrefix: "DONE task implementation commit points to a close commit",
+        groupLabel: "hashes",
+        summaryLabel: "implementation commits that point to close commits",
+        includeSubject: true,
+        severity: "WARN",
+    }));
+    return problems;
+}
+async function resolveCommitSubjects(repoRoot, hashes) {
+    const subjectByHash = new Map();
+    if (hashes.length === 0)
+        return subjectByHash;
+    for (const chunk of chunked(hashes, 200)) {
+        try {
+            const { stdout } = await execFileAsync("git", ["show", "-s", "--no-patch", "--format=%H%x00%s%x00", "--ignore-missing", ...chunk], {
+                cwd: repoRoot,
+                env: gitEnv(),
+            });
+            const parts = String(stdout ?? "").split("\u0000");
+            for (let i = 0; i + 1 < parts.length; i += 2) {
+                const hash = parts[i]?.trim() ?? "";
+                const subject = parts[i + 1]?.trim() ?? "";
+                if (!hash)
+                    continue;
+                subjectByHash.set(hash, subject);
+            }
+        }
+        catch {
+            // Preserve old behavior: unknown/unreadable hashes are reported later as empty subject.
+        }
+    }
+    return subjectByHash;
+}
+function chunked(items, size) {
+    const chunks = [];
+    for (let i = 0; i < items.length; i += size) {
+        chunks.push(items.slice(i, i + size));
+    }
+    return chunks;
+}

package/dist/commands/doctor/fixes.d.ts

@@ -0,0 +1,9 @@
+export declare function safeFixGitignore(repoRoot: string): Promise<{
+    changed: boolean;
+    note: string;
+}>;
+export declare function safeFixTaskIndex(repoRoot: string): Promise<{
+    changed: boolean;
+    note: string;
+}>;
+//# sourceMappingURL=fixes.d.ts.map

package/dist/commands/doctor/fixes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixes.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/fixes.ts"],"names":[],"mappings":"AAMA,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAyB7C;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAQ7C"}

package/dist/commands/doctor/fixes.js

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_GITIGNORE_LINES } from "../../shared/runtime-artifacts.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+export async function safeFixGitignore(repoRoot) {
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    let existing = "";
+    try {
+        existing = await fs.readFile(gitignorePath, "utf8");
+    }
+    catch {
+        return { changed: false, note: "Skip: .gitignore not found." };
+    }
+    const lines = existing.split(/\r?\n/);
+    const existingSet = new Set(lines.map((line) => line.trimEnd()));
+    const missing = RUNTIME_GITIGNORE_LINES.filter((line) => !existingSet.has(line));
+    if (missing.length === 0) {
+        return { changed: false, note: "OK: .gitignore already contains agentplane runtime ignores." };
+    }
+    const nextLines = [...lines];
+    if (nextLines.length > 0 && nextLines.at(-1) !== "")
+        nextLines.push("");
+    nextLines.push(...missing, "");
+    const next = `${nextLines.join("\n")}`.replaceAll(/\n{2,}$/g, "\n");
+    await fs.writeFile(gitignorePath, next, "utf8");
+    return {
+        changed: true,
+        note: `Fixed: added agentplane runtime ignores to .gitignore (${missing.length} lines).`,
+    };
+}
+export async function safeFixTaskIndex(repoRoot) {
+    try {
+        const ctx = await loadCommandContext({ cwd: repoRoot, rootOverride: null });
+        await ctx.taskBackend.listTasks();
+        return { changed: true, note: "OK: rebuilt tasks index cache (best-effort)." };
+    }
+    catch {
+        return { changed: false, note: "Skip: could not rebuild tasks index cache." };
+    }
+}

package/dist/commands/doctor/layering.d.ts

@@ -0,0 +1,2 @@
+export declare function checkLayering(repoRoot: string): Promise<string[]>;
+//# sourceMappingURL=layering.d.ts.map

package/dist/commands/doctor/layering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layering.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/layering.ts"],"names":[],"mappings":"AA6CA,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmDvE"}

package/dist/commands/doctor/layering.js

@@ -0,0 +1,87 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+async function listTsFiles(rootDir) {
+    const out = [];
+    async function walk(absDir) {
+        const entries = await fs.readdir(absDir, { withFileTypes: true });
+        for (const ent of entries) {
+            if (ent.name.startsWith("."))
+                continue;
+            if (ent.name === "__snapshots__")
+                continue;
+            if (ent.name === "node_modules")
+                continue;
+            const abs = path.join(absDir, ent.name);
+            if (ent.isDirectory()) {
+                await walk(abs);
+                continue;
+            }
+            if (ent.isFile() && ent.name.endsWith(".ts")) {
+                out.push({ absPath: abs, relPath: path.relative(rootDir, abs) });
+            }
+        }
+    }
+    await walk(rootDir);
+    return out;
+}
+function extractImports(source) {
+    const imports = [];
+    const re = /^\s*import\s+(?:type\s+)?(?:[^"']*?\s+from\s+)?["']([^"']+)["']\s*;?/gm;
+    for (const match of source.matchAll(re)) {
+        imports.push(match[1] ?? "");
+    }
+    return imports.filter(Boolean);
+}
+async function isDirectory(absPath) {
+    try {
+        const st = await fs.stat(absPath);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function checkLayering(repoRoot) {
+    const problems = [];
+    const agentplaneSrcRoot = path.join(repoRoot, "packages", "agentplane", "src");
+    if (!(await isDirectory(agentplaneSrcRoot))) {
+        problems.push("Dev source checks requested but packages/agentplane/src was not found in this workspace.");
+        return problems;
+    }
+    const cliRoot = path.join(agentplaneSrcRoot, "cli");
+    const cliFiles = await listTsFiles(cliRoot);
+    for (const f of cliFiles) {
+        const src = await fs.readFile(f.absPath, "utf8");
+        const imports = extractImports(src);
+        const hits = imports.filter((s) => s.includes("/adapters/") ||
+            s.includes("../adapters") ||
+            s.includes("../../adapters") ||
+            s.includes("../../../adapters"));
+        if (hits.length > 0) {
+            problems.push(`${f.relPath} imports adapters directly: ${hits.join(", ")}`);
+        }
+    }
+    const roots = [path.join(agentplaneSrcRoot, "usecases"), path.join(agentplaneSrcRoot, "ports")];
+    const banned = [
+        "node:fs",
+        "node:fs/promises",
+        "fs",
+        "fs/promises",
+        "node:path",
+        "path",
+        "simple-git",
+        "isomorphic-git",
+    ];
+    for (const root of roots) {
+        const files = await listTsFiles(root);
+        for (const f of files) {
+            const src = await fs.readFile(f.absPath, "utf8");
+            const imports = extractImports(src);
+            const hits = imports.filter((s) => banned.some((b) => s === b || s.startsWith(`${b}/`)));
+            if (hits.length > 0) {
+                problems.push(`${f.relPath} imports banned modules: ${hits.join(", ")}`);
+            }
+        }
+    }
+    return problems;
+}

package/dist/commands/doctor/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { AgentplaneConfig } from "@agentplaneorg/core";
+export declare function checkRuntimeSourceFacts(cwd: string, config?: AgentplaneConfig): string[];
+export declare function findingSeverity(problem: string): "ERROR" | "WARN" | "INFO";
+//# sourceMappingURL=runtime.d.ts.map

package/dist/commands/doctor/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAyB5D,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,MAAM,EAAE,CA+BxF;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAM1E"}

package/dist/commands/doctor/runtime.js

@@ -0,0 +1,56 @@
+import { evaluateRepoCliVersionExpectation, } from "../../shared/repo-cli-version.js";
+import { describeRuntimeMode, resolveRuntimeSourceInfo } from "../../shared/runtime-source.js";
+function renderCliVersionFacts(expectation) {
+    if (!expectation.expectedVersion)
+        return [];
+    if (expectation.state === "older_than_expected" ||
+        expectation.state === "active_version_unresolved") {
+        return [
+            `[WARN] ${expectation.summary}`,
+            ...(expectation.recovery ? [`[WARN] Recovery: ${expectation.recovery}`] : []),
+        ];
+    }
+    return [
+        `[INFO] Repository expected agentplane CLI: ${expectation.expectedVersion}`,
+        ...(expectation.summary ? [`[INFO] ${expectation.summary}`] : []),
+    ];
+}
+export function checkRuntimeSourceFacts(cwd, config) {
+    const report = resolveRuntimeSourceInfo({ cwd, entryModuleUrl: import.meta.url });
+    const cliVersionFacts = config
+        ? renderCliVersionFacts(evaluateRepoCliVersionExpectation(config, report))
+        : [];
+    if (!report.framework.inFrameworkCheckout) {
+        return cliVersionFacts;
+    }
+    const warning = report.mode === "global-in-framework"
+        ? "[WARN] Framework checkout detected but the active runtime is still a global installed binary. " +
+            "Update or reinstall agentplane to pick up repo-local handoff, or run the repo-local binary directly."
+        : report.mode === "global-forced-in-framework"
+            ? "[WARN] Framework checkout is forcing the global installed binary via AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1."
+            : null;
+    return [
+        ...(warning ? [warning] : []),
+        ...cliVersionFacts,
+        `[INFO] Runtime mode: ${report.mode} (${describeRuntimeMode(report.mode)})`,
+        `[INFO] Active binary: ${report.activeBinaryPath ?? "unresolved"}`,
+        ...(report.handoffFromBinaryPath
+            ? [`[INFO] Handoff source binary: ${report.handoffFromBinaryPath}`]
+            : []),
+        `[INFO] Resolved agentplane: ${report.agentplane.version ?? "unknown"} @ ${report.agentplane.packageRoot ?? "unresolved"}`,
+        `[INFO] Resolved @agentplaneorg/core: ${report.core.version ?? "unknown"} @ ${report.core.packageRoot ?? "unresolved"}`,
+        `[INFO] Framework repo root: ${report.frameworkSources.repoRoot ?? "unresolved"}`,
+        `[INFO] Framework agentplane root: ${report.frameworkSources.agentplaneRoot ?? "unresolved"}`,
+        `[INFO] Framework core root: ${report.frameworkSources.coreRoot ?? "unresolved"}`,
+    ];
+}
+export function findingSeverity(problem) {
+    const normalized = problem.trimStart();
+    if (normalized.startsWith("[WARN]"))
+        return "WARN";
+    if (normalized.startsWith("[INFO]"))
+        return "INFO";
+    if (normalized.startsWith("[ERROR]"))
+        return "ERROR";
+    return "ERROR";
+}

package/dist/commands/doctor/workflow.d.ts

@@ -0,0 +1,6 @@
+export declare function checkWorkflowContract(repoRoot: string): Promise<string[]>;
+export declare function safeFixWorkflow(repoRoot: string): Promise<{
+    changed: boolean;
+    note: string;
+}>;
+//# sourceMappingURL=workflow.d.ts.map

package/dist/commands/doctor/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/workflow.ts"],"names":[],"mappings":"AAUA,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU/E;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAiD7C"}

package/dist/commands/doctor/workflow.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { emitWorkflowEvent, resolveWorkflowPaths, safeAutofixWorkflowText, validateWorkflowAtPath, } from "../../workflow-runtime/index.js";
+export async function checkWorkflowContract(repoRoot) {
+    const result = await validateWorkflowAtPath(repoRoot);
+    const findings = result.diagnostics.map((d) => `[${d.severity}] ${d.code} ${d.path}: ${d.message}`);
+    emitWorkflowEvent({
+        event: "workflow_doctor_check",
+        details: { ok: result.ok, findings: result.diagnostics.length },
+    });
+    return findings;
+}
+export async function safeFixWorkflow(repoRoot) {
+    const paths = resolveWorkflowPaths(repoRoot);
+    let current = "";
+    let sourcePath = paths.workflowPath;
+    try {
+        current = await fs.readFile(paths.workflowPath, "utf8");
+    }
+    catch {
+        try {
+            current = await fs.readFile(paths.legacyWorkflowPath, "utf8");
+            sourcePath = paths.legacyWorkflowPath;
+        }
+        catch {
+            return { changed: false, note: "Skip: workflow contract file not found." };
+        }
+    }
+    const fixed = safeAutofixWorkflowText(current);
+    if (fixed.diagnostics.some((d) => d.code === "WF_FIX_SKIPPED_UNSAFE")) {
+        const details = fixed.diagnostics.map((d) => `${d.path}`).join(", ");
+        return {
+            changed: false,
+            note: `Skip: unsafe workflow autofix required (unknown keys). Proposed manual review: ${details}`,
+        };
+    }
+    if (!fixed.changed) {
+        if (sourcePath === paths.workflowPath) {
+            return { changed: false, note: "OK: workflow contract already normalized." };
+        }
+        await fs.mkdir(path.dirname(paths.workflowPath), { recursive: true });
+        await fs.writeFile(paths.workflowPath, current, "utf8");
+        await fs.rm(paths.legacyWorkflowPath, { force: true });
+        await fs.mkdir(paths.workflowDir, { recursive: true });
+        await fs.copyFile(paths.workflowPath, paths.lastKnownGoodPath);
+        return {
+            changed: true,
+            note: "Fixed: moved legacy WORKFLOW.md into .agentplane and refreshed last-known-good.",
+        };
+    }
+    await fs.mkdir(path.dirname(paths.workflowPath), { recursive: true });
+    await fs.writeFile(paths.workflowPath, fixed.text, "utf8");
+    if (sourcePath === paths.legacyWorkflowPath) {
+        await fs.rm(paths.legacyWorkflowPath, { force: true });
+    }
+    await fs.mkdir(paths.workflowDir, { recursive: true });
+    await fs.copyFile(paths.workflowPath, paths.lastKnownGoodPath);
+    return {
+        changed: true,
+        note: "Fixed: normalized workflow contract and refreshed last-known-good.",
+    };
+}

package/dist/commands/doctor/workspace.d.ts

@@ -0,0 +1,2 @@
+export declare function checkWorkspace(repoRoot: string): Promise<string[]>;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/commands/doctor/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/workspace.ts"],"names":[],"mappings":"AAqIA,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsDxE"}

package/dist/commands/doctor/workspace.js

@@ -0,0 +1,165 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { renderDiagnosticFinding } from "../../shared/diagnostics.js";
+import { resolvePolicyGatewayForRepo } from "../../shared/policy-gateway.js";
+async function pathExists(absPath) {
+    try {
+        await fs.access(absPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(absPath) {
+    try {
+        const st = await fs.stat(absPath);
+        return st.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function listMissingManagedPolicyFiles(repoRoot) {
+    const manifestPath = fileURLToPath(new URL("../../../assets/framework.manifest.json", import.meta.url));
+    let parsed = {};
+    try {
+        parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const relPaths = Array.isArray(parsed.files)
+        ? parsed.files
+            .filter((entry) => entry?.required === true && typeof entry.path === "string")
+            .map((entry) => String(entry.path).replaceAll("\\", "/").trim())
+            .filter((relPath) => relPath.startsWith(".agentplane/policy/"))
+        : [];
+    const missing = [];
+    for (const relPath of relPaths) {
+        if (!(await pathExists(path.join(repoRoot, relPath)))) {
+            missing.push(relPath);
+        }
+    }
+    return missing.toSorted();
+}
+async function checkTaskReadmeMigrationState(repoRoot) {
+    const tasksPath = path.join(repoRoot, ".agentplane", "tasks.json");
+    let raw = "";
+    try {
+        raw = await fs.readFile(tasksPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+    if (tasks.length === 0)
+        return [];
+    const legacy = tasks.filter((task) => task.doc_version !== 3);
+    if (legacy.length === 0)
+        return [];
+    const legacyActive = legacy.filter((task) => {
+        const status = typeof task.status === "string" ? task.status.trim().toUpperCase() : "";
+        return status !== "DONE";
+    });
+    const v3Count = tasks.length - legacy.length;
+    const exampleIds = legacy
+        .map((task) => (typeof task.id === "string" ? task.id : ""))
+        .filter(Boolean)
+        .slice(0, 5)
+        .join(", ");
+    const hasMixedVersions = v3Count > 0;
+    if (legacyActive.length > 0) {
+        return [
+            renderDiagnosticFinding({
+                severity: "WARN",
+                state: hasMixedVersions
+                    ? "task README migration is incomplete (active v2/v3 mixed state)"
+                    : "task README format is still on legacy v2",
+                likelyCause: "the workspace still contains active task READMEs that were never migrated to the README v3 contract",
+                nextAction: {
+                    command: "agentplane task migrate-doc --all",
+                    reason: "upgrade all task READMEs to doc_version=3 before continuing active work",
+                },
+                details: [
+                    `Legacy tasks: ${legacy.length}; active legacy tasks: ${legacyActive.length}; README v3 tasks: ${v3Count}`,
+                    exampleIds ? `Examples: ${exampleIds}` : "Examples unavailable in tasks snapshot.",
+                ],
+            }),
+        ];
+    }
+    return [
+        renderDiagnosticFinding({
+            severity: "INFO",
+            state: hasMixedVersions
+                ? "historical task archive still mixes README v2 and v3"
+                : "historical task archive still uses README v2",
+            likelyCause: "older DONE tasks were never backfilled to README v3 after the task-document contract changed",
+            nextAction: {
+                command: "agentplane task migrate-doc --all",
+                reason: "normalize archived task READMEs to the README v3 contract when convenient",
+            },
+            details: [
+                `Legacy tasks: ${legacy.length}; active legacy tasks: 0; README v3 tasks: ${v3Count}`,
+                exampleIds ? `Examples: ${exampleIds}` : "Examples unavailable in tasks snapshot.",
+            ],
+        }),
+    ];
+}
+export async function checkWorkspace(repoRoot) {
+    const problems = [];
+    const requiredFiles = [path.join(repoRoot, ".agentplane", "config.json")];
+    for (const filePath of requiredFiles) {
+        if (!(await pathExists(filePath))) {
+            problems.push(`Missing required file: ${path.relative(repoRoot, filePath)}`);
+        }
+    }
+    const gateway = await resolvePolicyGatewayForRepo({
+        gitRoot: repoRoot,
+        fallbackFlavor: "codex",
+    });
+    if (!(await pathExists(gateway.absPath))) {
+        problems.push("Missing required policy gateway file: AGENTS.md or CLAUDE.md");
+    }
+    if (await pathExists(gateway.absPath)) {
+        const missingManagedPolicy = await listMissingManagedPolicyFiles(repoRoot);
+        if (missingManagedPolicy.length > 0) {
+            const listed = missingManagedPolicy.slice(0, 8).join(", ");
+            const more = missingManagedPolicy.length > 8 ? ` (+${missingManagedPolicy.length - 8} more)` : "";
+            problems.push(renderDiagnosticFinding({
+                severity: "ERROR",
+                state: "framework-managed policy tree is incomplete",
+                likelyCause: "the active AGENTS.md/CLAUDE.md gateway expects required policy files that are not installed in this workspace",
+                nextAction: {
+                    command: "agentplane upgrade --yes",
+                    reason: "reinstall the managed policy tree from the currently active framework bundle",
+                },
+                details: [
+                    `Missing required files: ${listed}${more}`,
+                    "If the installed CLI is older than the gateway, update or reinstall agentplane first and then rerun `agentplane upgrade --yes` (or `agentplane upgrade --remote --yes`).",
+                    "Recovery guide: docs/help/legacy-upgrade-recovery.mdx",
+                ],
+            }));
+        }
+    }
+    const agentsDir = path.join(repoRoot, ".agentplane", "agents");
+    if (!(await isDirectory(agentsDir))) {
+        problems.push("Missing required directory: .agentplane/agents");
+        return problems;
+    }
+    const entries = await fs.readdir(agentsDir);
+    const hasJson = entries.some((name) => name.endsWith(".json"));
+    if (!hasJson) {
+        problems.push("No agent profiles found in .agentplane/agents (*.json expected).");
+    }
+    problems.push(...(await checkTaskReadmeMigrationState(repoRoot)));
+    return problems;
+}