@felixdotgo/aidlc-kit 0.0.1

package/dist/src/cli.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+import { stdin, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { installableAdapters } from "./adapters.js";
+import { applyPlan, detectedAgents, doctor, formatPlan, planInit, planUninstall, selectAgents, status } from "./installer.js";
+import { loadProjectConfig, resolveProfiles } from "./profiles.js";
+import { applyUpgrade, planUpgrade } from "./upgrade.js";
+import { packageVersion } from "./workflow.js";
+import { applyMcpSetup, planMcpSetup } from "./mcp-setup.js";
+const usage = `Usage:
+  npx @felixdotgo/aidlc-kit init [path] [--agent <name[,name]> | --all] [--yes] [--dry-run] [--force]
+  npx @felixdotgo/aidlc-kit upgrade [path] [--dry-run]
+  npx @felixdotgo/aidlc-kit uninstall [path] [--yes] [--dry-run]
+  npx @felixdotgo/aidlc-kit status [path]
+  npx @felixdotgo/aidlc-kit doctor [path] [--strict]
+  npx @felixdotgo/aidlc-kit profile validate [path]
+  npx @felixdotgo/aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--enable]`;
+const interactive = () => Boolean(stdin.isTTY && stdout.isTTY);
+const prompts = async () => import("@inquirer/prompts");
+const value = (args, name) => {
+    const index = args.indexOf(name);
+    return index < 0 ? undefined : args[index + 1];
+};
+const flags = (args) => new Set(args.filter((item) => item.startsWith("--")));
+const valueFlags = new Set(["--agent", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers"]);
+const positional = (args) => {
+    const result = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (valueFlags.has(args[index])) {
+            index += 1;
+            continue;
+        }
+        if (!args[index].startsWith("--"))
+            result.push(args[index]);
+    }
+    return result;
+};
+const rootArg = (args, fallback = ".") => positional(args).find((item) => !["init", "upgrade", "uninstall", "status", "doctor", "validate", "run", "list"].includes(item)) ?? fallback;
+const initOptions = (args) => ({
+    root: rootArg(args),
+    agents: (value(args, "--agent") ?? "").split(",").filter(Boolean),
+    all: flags(args).has("--all"),
+    dryRun: flags(args).has("--dry-run"),
+    yes: flags(args).has("--yes"),
+    force: flags(args).has("--force")
+});
+const chooseAgents = async (options) => {
+    const selected = selectAgents(options);
+    if (selected.length)
+        return { ...options, agents: selected };
+    const detected = detectedAgents(options.root);
+    if (detected.length === 1)
+        return { ...options, agents: detected };
+    if (!interactive())
+        throw new Error(`Unable to select an agent automatically. Use --agent <name> or --all. Detected: ${detected.join(", ") || "none"}`);
+    const { checkbox } = await prompts();
+    const choices = installableAdapters();
+    const agents = await checkbox({
+        message: "Select one or more agents",
+        choices: choices.map((adapter) => ({
+            name: `${adapter.displayName}${detected.includes(adapter.id) ? " (detected)" : ""}`,
+            value: adapter.id
+        })),
+        required: true
+    });
+    return { ...options, agents };
+};
+const preview = (operation, plan) => {
+    console.log(`◆ ${operation} preview — changes have NOT been applied`);
+    console.log(formatPlan(plan));
+};
+const confirmGeneral = async (options, operation) => {
+    if (options.dryRun)
+        return false;
+    if (options.yes)
+        return true;
+    if (!interactive())
+        return false;
+    const { confirm } = await prompts();
+    return confirm({ message: `${operation} this plan?`, default: false });
+};
+const mcpSetupOptions = async (args) => {
+    const selected = {
+        deployment: value(args, "--deployment"),
+        storage: value(args, "--storage"),
+        bind: value(args, "--bind"),
+        workspace: value(args, "--workspace"),
+        pollMs: Number(value(args, "--poll-ms") ?? 30_000),
+        tokenEnv: value(args, "--token-env") ?? "AIDLC_MCP_TOKEN",
+        providers: (value(args, "--providers") ?? "").split(",").filter(Boolean)
+    };
+    if ((!selected.deployment || !selected.storage || !selected.bind || !selected.workspace) && !interactive())
+        throw new Error("mcp setup outside a TTY requires --deployment, --storage, --bind and --workspace");
+    if (interactive()) {
+        const { input, select, checkbox } = await prompts();
+        selected.deployment ??= await select({ message: "State service deployment", choices: [{ name: "Docker on this machine", value: "docker" }, { name: "Remote service (configure endpoint later)", value: "remote" }] });
+        selected.storage ??= await select({ message: "Database", choices: [{ name: "SQLite (local Docker volume)", value: "sqlite" }, { name: "PostgreSQL (multi-host production)", value: "postgres" }] });
+        selected.bind ??= await select({ message: "Network binding", choices: [{ name: "localhost only", value: "localhost" }, { name: "network (requires token/TLS)", value: "network" }] });
+        selected.workspace ??= await input({ message: "Workspace ID", default: "default", required: true });
+        if (!selected.providers.length)
+            selected.providers = await checkbox({ message: "Project-management connectors to configure", choices: ["jira", "trello", "github-issues"].map((value) => ({ name: value, value })) });
+    }
+    if (!Number.isInteger(selected.pollMs) || selected.pollMs < 1_000 || selected.pollMs > 3_600_000)
+        throw new Error("--poll-ms must be an integer from 1000 to 3600000");
+    return { root: rootArg(args), template: join(fileURLToPath(new URL("../services/aidlc-coordination", import.meta.url))), dryRun: flags(args).has("--dry-run"), deployment: selected.deployment, storage: selected.storage, bind: selected.bind, workspace: selected.workspace, pollMs: selected.pollMs, tokenEnv: selected.tokenEnv, providers: selected.providers, enable: flags(args).has("--enable") };
+};
+const main = async () => {
+    const [command = "help", ...args] = process.argv.slice(2);
+    if (command === "help" || command === "--help")
+        return void console.log(usage);
+    if (command === "status")
+        return void console.log(status(rootArg(args)));
+    if (command === "doctor") {
+        const result = doctor(rootArg(args), flags(args).has("--strict"));
+        console.log(result);
+        if (result.startsWith("ERROR:"))
+            process.exitCode = 1;
+        return;
+    }
+    if (command === "init") {
+        const options = await chooseAgents(initOptions(args));
+        const plan = planInit(options);
+        preview("INIT", plan);
+        if (plan.some((item) => item.action === "conflict"))
+            throw new Error("No files were written because the plan contains conflicts.");
+        if (!await confirmGeneral(options, "Apply"))
+            return;
+        const migratesLegacyData = plan.some((item) => item.action === "migrate" || item.action === "delete");
+        if (migratesLegacyData) {
+            const result = applyUpgrade(options.root, plan);
+            console.log(`Installed local AI-DLC workflow assets and migrated legacy data. Backup: ${result.backup}; changed: ${result.changed}`);
+        }
+        else {
+            applyPlan(options.root, plan);
+            console.log("Installed local AI-DLC workflow assets.");
+        }
+        return;
+    }
+    if (command === "uninstall") {
+        const options = initOptions(args);
+        const plan = planUninstall(options.root);
+        preview("UNINSTALL", plan);
+        if (!await confirmGeneral(options, "Remove"))
+            return;
+        applyPlan(options.root, plan);
+        console.log("Removed eligible managed assets; project config and state were preserved.");
+        return;
+    }
+    if (command === "upgrade") {
+        if (flags(args).has("--yes") || flags(args).has("--force"))
+            throw new Error("upgrade does not support --yes or --force; apply requires a human interactive TTY confirmation");
+        const root = rootArg(args);
+        const plan = planUpgrade(root);
+        preview("UPGRADE", plan);
+        if (plan.some((item) => item.action === "conflict"))
+            throw new Error("Upgrade contains conflicts; no files were written.");
+        if (flags(args).has("--dry-run"))
+            return;
+        if (!interactive())
+            throw new Error("Upgrade apply requires an interactive TTY. AI and non-interactive processes must not apply upgrades.");
+        const expected = packageVersion();
+        const { input } = await prompts();
+        if ((await input({ message: `Type ${expected} to apply this user-initiated upgrade` })).trim() !== expected)
+            throw new Error("Upgrade confirmation did not match the target version");
+        const result = applyUpgrade(root, plan);
+        console.log(`Upgrade complete. Backup: ${result.backup}; changed: ${result.changed}`);
+        return;
+    }
+    if (command === "mcp" && args[0] === "setup") {
+        const options = await mcpSetupOptions(args.slice(1));
+        const plan = planMcpSetup(options);
+        console.log(`◆ MCP SETUP preview — ${options.dryRun ? "no files will be written" : "review before applying"}`);
+        console.log(JSON.stringify(plan, null, 2));
+        if (options.dryRun)
+            return;
+        if (!await confirmGeneral({ ...initOptions(args), root: options.root }, "Apply MCP setup"))
+            return;
+        applyMcpSetup(options);
+        console.log(`MCP setup written to ${plan.target}. MCP remains ${options.enable ? "enabled" : "disabled"}; start Docker explicitly with docker compose --env-file .env -f ${join(plan.target, "compose.yaml")} up -d.`);
+        return;
+    }
+    if (command === "profile" && args[0] === "validate") {
+        const root = rootArg(args.slice(1));
+        const config = loadProjectConfig(root);
+        const profiles = resolveProfiles(root, config.extends);
+        console.log(`OK: ${profiles.map((item) => item.id).join(" → ")}`);
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+};
+main().catch((error) => { console.error(`aidlc-workflow: ${error instanceof Error ? error.message : String(error)}`); process.exitCode = 1; });

package/dist/src/context.d.ts

@@ -0,0 +1,14 @@
+import type { Phase, ProjectConfig, TaskState } from "./model.js";
+export interface ContextPacket {
+    content: string;
+    chars: number;
+    estimatedTokens: number;
+    omittedRules: string[];
+}
+export interface ContextOptions {
+    mode?: "standard" | "economy";
+    itemId?: string;
+}
+export declare const compileContext: (root: string, config: ProjectConfig, task: TaskState, phase: Phase, options?: ContextOptions) => ContextPacket;
+export declare const writeableContextFormat: (packet: ContextPacket, format: "markdown" | "json") => string;
+export declare const contextAssetsAvailable: () => boolean;

package/dist/src/context.js

@@ -0,0 +1,90 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { includedRuleFiles, resolveEffectiveConfig } from "./profiles.js";
+import { loadMemoryRegistry, nextAction, selectAgenticMemory } from "./state.js";
+const assetRoot = fileURLToPath(new URL("../assets/.agents/aidlc", import.meta.url));
+const phaseFile = (phase) => phase === "done" ? "phase-wrap.md" : `phase-${phase}.md`;
+const readAsset = (path) => readFileSync(join(assetRoot, path), "utf8");
+const requiredEvidence = (task) => task.evidence.filter((item, index, entries) => {
+    const key = `${item.kind}:${item.area ?? ""}:${item.gate ?? ""}`;
+    return !entries.slice(index + 1).some((candidate) => `${candidate.kind}:${candidate.area ?? ""}:${candidate.gate ?? ""}` === key);
+}).map(({ detail: _detail, ...item }) => item);
+const compactTask = (task, itemId) => JSON.stringify({
+    id: task.id,
+    title: task.title,
+    type: task.type,
+    phase: task.phase,
+    gate: task.gate,
+    status: task.status,
+    risk: task.risk,
+    areas: task.areas,
+    handoff: task.handoff,
+    closure: task.closure,
+    predecessorTaskId: task.predecessorTaskId,
+    successorTaskId: task.successorTaskId,
+    decisions: task.decisions.map(({ id, label, status }) => ({ id, label, status })),
+    tasks: itemId ? task.tasks.filter((item) => item.id === itemId) : task.tasks,
+    evidence: requiredEvidence(task),
+    lessonDisposition: task.lessonDisposition,
+    artifacts: task.artifacts
+}, null, 2);
+const profileSummary = (profiles) => profiles.map((item) => JSON.stringify({ id: item.id, topology: item.topology, discovery: item.discovery, specs: item.specs, commands: item.commands })).join("\n");
+export const compileContext = (root, config, task, phase, options = {}) => {
+    if (!["clarify", "plan", "build", "wrap", "done"].includes(phase))
+        throw new Error(`Unsupported phase: ${phase}`);
+    const effective = resolveEffectiveConfig(root, config);
+    const profiles = effective.profiles;
+    const ruleFiles = includedRuleFiles(root, effective.rules.include);
+    if (options.itemId && !task.tasks.some((item) => item.id === options.itemId))
+        throw new Error(`Unknown task item: ${options.itemId}`);
+    const taskState = compactTask(task, options.itemId);
+    const actionableItems = options.itemId ? task.tasks.filter((item) => item.status === "in_progress" || item.status === "todo").map((item) => item.id) : [];
+    const invariants = [
+        options.itemId ? `- Focused item context does not narrow the workplan: actionable items are ${actionableItems.join(", ") || "none"}; after this item, execute nextAction immediately.` : "",
+        "- Continue after a non-terminal transition or item/evidence mutation; yield only at a human gate, real blocker, or completion.",
+        "- Item completion is progress for commentary, never a final response while nextAction is run_phase.",
+        "- Never omit approved decisions, spec anchors, safety constraints, or applicable verification evidence.",
+        "- Agents may run configured build/test/lint commands, but workflow installation and upgrades remain human-only npm/npx operations."
+    ].filter(Boolean).join("\n");
+    const action = JSON.stringify(nextAction(task, root), null, 2);
+    const required = [
+        `# AI-DLC phase packet — ${phase}`,
+        `mode: ${options.mode ?? "standard"}${options.itemId ? ` · item: ${options.itemId}` : ""}`,
+        "## Next action / stop contract",
+        action,
+        "## Phase contract",
+        readAsset(phaseFile(phase)),
+        "## Canonical task state",
+        taskState,
+        "## Resolved profiles",
+        profileSummary(profiles),
+        "## Project configuration",
+        JSON.stringify({ discovery: effective.discovery, specs: effective.specs, commands: effective.commands, risk: effective.risk, context: effective.context }, null, 2),
+        "## Invariants",
+        invariants
+    ].join("\n\n");
+    if (required.length > config.context.maxChars)
+        throw new Error("Context budget is too small for the full phase contract, next action, canonical task state, and mandatory invariants");
+    let content = required;
+    const omittedRules = [];
+    for (const path of ruleFiles) {
+        const relative = path.slice(resolve(root).length + 1);
+        const block = `\n\n## Project rule — ${relative}\n${readFileSync(path, "utf8")}`;
+        if (content.length + block.length <= config.context.maxChars)
+            content += block;
+        else
+            omittedRules.push(relative);
+    }
+    try {
+        const memory = selectAgenticMemory(loadMemoryRegistry(root), task.areas, phase === "done" ? "wrap" : phase, config.context.maxChars - content.length - "\n\n## Advisory project memory\n".length);
+        if (memory.length)
+            content += `\n\n## Advisory project memory\n${memory.map((entry) => `- ${entry.id} — ${entry.summary} — guidance: ${entry.guidance} — source: ${entry.sourceTaskId}/${entry.sourceLessonId}`).join("\n")}`;
+    }
+    catch (error) {
+        omittedRules.push(`memory:unavailable:${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { content, chars: content.length, estimatedTokens: Math.ceil(content.length / 4), omittedRules };
+};
+export const writeableContextFormat = (packet, format) => format === "json" ? `${JSON.stringify(packet, null, 2)}\n` : `${packet.content}\n\n---\nchars: ${packet.chars} · estimated tokens: ${packet.estimatedTokens} · omitted rules: ${packet.omittedRules.length}\n`;
+export const contextAssetsAvailable = () => existsSync(assetRoot);

package/dist/src/gate.d.ts

@@ -0,0 +1,40 @@
+import type { Diagnostic, Gate, TaskState, WorkflowState } from "./model.js";
+export declare const checkGate: (root: string, state: WorkflowState, taskId: string, gate: Gate) => Diagnostic[];
+export declare const approveAndAdvance: (root: string, state: WorkflowState, taskId: string, gate: Gate, source: string, recordedAt?: string) => {
+    task: TaskState;
+    nextAction: import("./state.js").NextAction;
+    idempotent: boolean;
+};
+export declare const formatDiagnostics: (diagnostics: Diagnostic[]) => string;
+export type GateViewFormat = "markdown" | "plain" | "json";
+export declare const gateView: (task: TaskState, diagnostics: Diagnostic[]) => {
+    schemaVersion: number;
+    gate: "G0_confirm" | "G1_review" | "G2_codereview";
+    icon: string;
+    title: string;
+    action: string;
+    task: {
+        id: string;
+        title: string;
+        status: "blocked_on_user";
+        risk: import("./model.js").RiskLevel;
+        areas: string[];
+    };
+    artifacts: {
+        name: string;
+        path: string;
+    }[];
+    decisions: Record<string, number>;
+    execution: Record<string, number>;
+    evidence: {
+        kind: "approval" | "spec" | "test" | "lint" | "review" | "diagnostic";
+        result: "skip" | "pass" | "fail";
+        source: string;
+    }[];
+    diagnostics: {
+        level: "ERROR" | "WARN" | "INFO";
+        code: string;
+        message: string;
+    }[];
+};
+export declare const formatGateView: (task: TaskState, diagnostics: Diagnostic[], format?: GateViewFormat) => string;

package/dist/src/gate.js

@@ -0,0 +1,176 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolveProjectPathWithoutSymlinks } from "./project-path.js";
+import { hasAreaVerification, hasReview, isLegacyG2Wait, nextAction, repairBounds, transitionDiagnostics, transitionTask } from "./state.js";
+const safeArtifactTarget = (root, path) => resolveProjectPathWithoutSymlinks(root, path, "Unsafe artifact path", "Artifact path crosses a symlink");
+const artifactContent = (root, path) => {
+    if (!path)
+        return undefined;
+    try {
+        const target = safeArtifactTarget(root, path);
+        return existsSync(target) ? readFileSync(target, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+const artifactDiagnostics = (root, task, names) => names.flatMap((name) => {
+    const path = task.artifacts[name];
+    if (!path)
+        return [{ level: "ERROR", code: "ARTIFACT_REFERENCE", message: `${String(name)} artifact is not referenced` }];
+    try {
+        return existsSync(safeArtifactTarget(root, path)) ? [] : [{ level: "ERROR", code: "ARTIFACT_MISSING", message: `${path} does not exist` }];
+    }
+    catch (error) {
+        return [{ level: "ERROR", code: "ARTIFACT_UNSAFE", message: error instanceof Error ? error.message : String(error) }];
+    }
+});
+export const checkGate = (root, state, taskId, gate) => {
+    const task = state.tasks[taskId];
+    if (!task)
+        return [{ level: "ERROR", code: "TASK_UNKNOWN", message: `Unknown task: ${taskId}` }];
+    const diagnostics = [];
+    if (task.gate !== gate)
+        diagnostics.push({ level: "ERROR", code: "GATE_STATE", message: `Task is at ${task.gate}, not ${gate}` });
+    if (task.status === "closed" || task.status === "superseded")
+        diagnostics.push({ level: "ERROR", code: "TASK_TERMINAL", message: `Terminal task cannot approve ${gate}` });
+    if (task.handoff)
+        diagnostics.push({ level: "ERROR", code: "TASK_HANDOFF", message: `Task has unresolved handoff: ${task.handoff.reason}` });
+    if (task.id !== taskId)
+        diagnostics.push({ level: "ERROR", code: "TASK_ID", message: "Task key and id differ" });
+    if (!task.title.trim() || !task.areas.length)
+        diagnostics.push({ level: "ERROR", code: "TASK_FIELDS", message: "Task title and affected areas are required" });
+    if (gate === "G0_confirm") {
+        diagnostics.push(...artifactDiagnostics(root, task, ["intent"]));
+        const content = artifactContent(root, task.artifacts.intent);
+        if (content !== undefined)
+            for (const heading of ["## 📋 Problem", "## 🗺️ Affected areas", "## 💭 Assumptions", "## ❓ Open questions", "## 🎯 Scope"])
+                if (!content.includes(heading))
+                    diagnostics.push({ level: "ERROR", code: "INTENT_HEADING", message: `Intent is missing ${heading}` });
+    }
+    if (gate === "G1_review") {
+        diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"]));
+        diagnostics.push(...transitionDiagnostics(task, "build").filter((item) => item.code === "UNRESOLVED_DECISION"));
+        const content = artifactContent(root, task.artifacts.design);
+        if (content !== undefined)
+            for (const heading of ["## 🧩 Solution per affected area", "## 📌 Spec traceability", "## 🔗 Cross-service contracts", "## ⚠️ Risks / edge cases"])
+                if (!content.includes(heading))
+                    diagnostics.push({ level: "ERROR", code: "DESIGN_HEADING", message: `Design is missing ${heading}` });
+    }
+    if (gate === "G2_codereview") {
+        diagnostics.push(...artifactDiagnostics(root, task, ["intent", "design", "workplan"]));
+        if (task.tasks.some((item) => item.status !== "done" && item.status !== "deferred"))
+            diagnostics.push({ level: "ERROR", code: "TASKS_OPEN", message: "Build tasks remain open" });
+        for (const area of task.areas)
+            if (!hasAreaVerification(task, area))
+                diagnostics.push({ level: "ERROR", code: "VERIFY_EVIDENCE", message: `Latest post-G1 verification evidence must pass for affected area: ${area}` });
+        if (!hasReview(task))
+            diagnostics.push({ level: "ERROR", code: "REVIEW_EVIDENCE", message: "Latest post-G1 review evidence must pass" });
+        const bounds = repairBounds(task);
+        if (!isLegacyG2Wait(task) && (bounds.verifyExhausted || bounds.reviewExhausted))
+            diagnostics.push({ level: "ERROR", code: "REPAIR_BOUND", message: "Repair bound exhausted; record a durable handoff instead of presenting G2" });
+    }
+    if (!diagnostics.length)
+        diagnostics.push({ level: "INFO", code: "GATE_OK", message: `${gate} checks passed for ${taskId}` });
+    return diagnostics;
+};
+const gateTarget = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
+export const approveAndAdvance = (root, state, taskId, gate, source, recordedAt = new Date().toISOString()) => {
+    const task = state.tasks[taskId];
+    if (!task)
+        throw new Error(`Unknown task: ${taskId}`);
+    if (task.status === "closed" || task.status === "superseded" || task.handoff)
+        throw new Error(`Terminal or handed-off task cannot approve ${gate}`);
+    const target = gateTarget[gate];
+    if (!target)
+        throw new Error(`Gate ${gate} cannot be approved`);
+    if (task.phase === target)
+        return { task, nextAction: nextAction(task, root), idempotent: true };
+    if (task.gate !== gate || task.status !== "blocked_on_user")
+        throw new Error(`Task must be blocked_on_user at ${gate}`);
+    const errors = checkGate(root, state, taskId, gate).filter((item) => item.level === "ERROR");
+    if (errors.length)
+        throw new Error(errors.map((item) => item.message).join("; "));
+    task.evidence.push({ kind: "approval", gate, result: "pass", source, recordedAt });
+    transitionTask(state, taskId, target);
+    return { task, nextAction: nextAction(task, root), idempotent: false };
+};
+export const formatDiagnostics = (diagnostics) => diagnostics.map((item) => `${item.level} ${item.code}: ${item.message}`).join("\n");
+const oneLine = (value) => value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").replace(/ACTION\s+REQUIRED/gi, "ACTION-REQUIRED").trim();
+const markdownText = (value) => oneLine(value).replace(/([\\`*_{}\[\]()<>#+.!|>~])/g, "\\$1");
+const gateMeta = {
+    G0_confirm: { icon: "🟢", title: "GATE G0 · CONFIRM INTENT", action: "Reply `ok` to approve intent, or state changes." },
+    G1_review: { icon: "🔵", title: "GATE G1 · REVIEW PLAN", action: "Reply `approve` to start build, or state decision changes." },
+    G2_codereview: { icon: "🟣", title: "GATE G2 · REVIEW CODE", action: "Approve to wrap, or point out what to fix." }
+};
+const artifactRows = (task) => Object.entries(task.artifacts).flatMap(([name, path]) => path ? [{ name: oneLine(name), path: oneLine(path) }] : []);
+const markdownLinkTarget = (value) => encodeURI(value).replace(/[()#?]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+export const gateView = (task, diagnostics) => {
+    if (task.gate === "none")
+        throw new Error(`Task has no human gate: ${task.id}`);
+    if (task.status !== "blocked_on_user")
+        throw new Error(`Task must be blocked_on_user before presenting ${task.gate}`);
+    const errors = diagnostics.filter((item) => item.level === "ERROR");
+    if (errors.length)
+        throw new Error(errors.map((item) => item.message).join("; "));
+    const meta = gateMeta[task.gate];
+    const decisions = task.decisions.reduce((counts, item) => ({ ...counts, [item.status]: (counts[item.status] ?? 0) + 1 }), {});
+    const latestEvidence = task.evidence.filter((item) => item.kind === "test" || item.kind === "lint" || item.kind === "review").slice(-5).map((item) => ({ kind: item.kind, result: item.result, source: oneLine(item.source) }));
+    return {
+        schemaVersion: 1,
+        gate: task.gate,
+        icon: meta.icon,
+        title: meta.title,
+        action: meta.action,
+        task: { id: task.id, title: oneLine(task.title), status: task.status, risk: task.risk, areas: task.areas },
+        artifacts: artifactRows(task),
+        decisions,
+        execution: task.tasks.reduce((counts, item) => ({ ...counts, [item.status]: (counts[item.status] ?? 0) + 1 }), {}),
+        evidence: latestEvidence,
+        diagnostics: diagnostics.filter((item) => item.level !== "INFO").map((item) => ({ level: item.level, code: item.code, message: oneLine(item.message) }))
+    };
+};
+export const formatGateView = (task, diagnostics, format = "markdown") => {
+    const view = gateView(task, diagnostics);
+    if (format === "json")
+        return `${JSON.stringify(view, null, 2)}\n`;
+    const artifactText = view.artifacts.length ? view.artifacts.map((item) => format === "markdown" ? `- **${markdownText(item.name)}:** [${markdownText(item.path)}](${markdownLinkTarget(item.path)})` : `- ${item.name}: ${item.path}`).join("\n") : "- none";
+    const decisionText = Object.entries(view.decisions).map(([status, count]) => `${count} ${status}`).join(" · ") || "none";
+    const executionText = Object.entries(view.execution).map(([status, count]) => `${count} ${status}`).join(" · ") || "none";
+    const evidenceText = view.evidence.length ? view.evidence.map((item) => `- ${item.kind}: ${item.result} — ${format === "markdown" ? markdownText(item.source) : item.source}`).join("\n") : "- none yet";
+    const warningText = view.diagnostics.length ? `\n\n${view.diagnostics.map((item) => `- ${item.level} ${item.code}: ${format === "markdown" ? markdownText(item.message) : item.message}`).join("\n")}` : "";
+    if (format === "plain")
+        return [
+            `[IMPORTANT] ${view.icon} ${view.title}`,
+            `Task: ${view.task.id} — ${view.task.title}`,
+            `Status: ${view.task.status} · Risk: ${view.task.risk} · Areas: ${view.task.areas.join(", ")}`,
+            "",
+            "Review artifacts",
+            artifactText,
+            "",
+            `Decisions: ${decisionText}`,
+            `Execution: ${executionText}`,
+            "Evidence",
+            evidenceText,
+            warningText,
+            "",
+            `ACTION REQUIRED -> ${oneLine(view.action)}`
+        ].filter((line) => line !== undefined).join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+    return [
+        "> [!IMPORTANT]",
+        `> ${view.icon} **${view.title}**`,
+        `> **Task:** \`${view.task.id}\` — ${markdownText(view.task.title)}`,
+        `> **Status:** \`${view.task.status}\` · **Risk:** \`${view.task.risk}\` · **Areas:** ${view.task.areas.map((area) => `\`${markdownText(area)}\``).join(", ")}`,
+        "",
+        "### Review artifacts",
+        artifactText,
+        "",
+        `**Decisions:** ${decisionText}  `,
+        `**Execution:** ${executionText}`,
+        "",
+        "### Verification evidence",
+        evidenceText,
+        warningText,
+        "",
+        `> **ACTION REQUIRED →** ${view.action}`
+    ].join("\n").replace(/\n{3,}/g, "\n\n") + "\n";
+};

package/dist/src/installer.d.ts

@@ -0,0 +1,11 @@
+import type { AgentId, FileSpec, InitOptions, PlannedWrite, WorkflowManifest } from "./model.js";
+export declare const managedContentHash: (spec: Pick<FileSpec, "owner" | "strategy">, content: string) => string | undefined;
+export declare const readManifest: (root: string) => WorkflowManifest | undefined;
+export declare const detectedAgents: (root: string) => AgentId[];
+export declare const selectAgents: (options: Pick<InitOptions, "root" | "agents" | "all">) => AgentId[];
+export declare const planInit: (options: InitOptions) => PlannedWrite[];
+export declare const applyPlan: (root: string, plan: PlannedWrite[]) => void;
+export declare const formatPlan: (plan: PlannedWrite[]) => string;
+export declare const planUninstall: (root: string) => PlannedWrite[];
+export declare const status: (root: string) => string;
+export declare const doctor: (root: string, strict?: boolean) => string;