@yuaone/core 0.9.8 → 0.9.10

package/dist/agent-reputation.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @module agent-reputation
+ * @description Agent Reputation / Trust Layer for role agents.
+ * Tracks performance of specialized role agents and enables AgentCoordinator
+ * to route tasks to the best-performing agent for each context.
+ *
+ * Storage: ~/.yuan/reputation/agent-reputation.json
+ *
+ * Wilson score lower bound (95% CI) is used as reputationScore for robustness
+ * against small sample sizes.
+ */
+import { EventEmitter } from "node:events";
+export type RoleAgentType = "planner" | "researcher" | "coder" | "reviewer" | "verifier" | "incident";
+export interface AgentPerformanceRecord {
+    agentType: RoleAgentType;
+    taskType: string;
+    environment?: string;
+    successes: number;
+    failures: number;
+    avgLatencyMs: number;
+    avgTokenCost: number;
+    /** Wilson score confidence interval lower bound — robust to small samples. 0..1 */
+    reputationScore: number;
+    lastUpdated: string;
+}
+export interface RoutingRecommendation {
+    taskType: string;
+    environment?: string;
+    recommended: RoleAgentType;
+    score: number;
+    alternatives: Array<{
+        agentType: RoleAgentType;
+        score: number;
+    }>;
+    reason: string;
+}
+export declare class AgentReputation extends EventEmitter {
+    private readonly storageFile;
+    private records;
+    constructor(storageDir?: string);
+    /**
+     * Record a task outcome for a role agent.
+     * Updates avgLatencyMs, avgTokenCost, and reputationScore (Wilson lower bound).
+     */
+    record(agentType: RoleAgentType, taskType: string, outcome: {
+        success: boolean;
+        latencyMs: number;
+        tokenCost: number;
+        environment?: string;
+    }): void;
+    /**
+     * Get routing recommendation for a task type (and optional environment).
+     * Sorts candidates by Wilson score. Falls back to default routing if no data.
+     */
+    recommend(taskType: string, environment?: string): RoutingRecommendation;
+    /**
+     * Get all performance records for a given agent type.
+     */
+    getRecords(agentType: RoleAgentType): AgentPerformanceRecord[];
+    /**
+     * Get a summary of average reputation scores and total task counts per agent type.
+     */
+    getSummary(): Record<RoleAgentType, {
+        avgScore: number;
+        totalTasks: number;
+    }>;
+    private _key;
+    private _keyOf;
+    private _load;
+    private _save;
+}
+//# sourceMappingURL=agent-reputation.d.ts.map

package/dist/agent-reputation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-reputation.d.ts","sourceRoot":"","sources":["../src/agent-reputation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,YAAY,GACZ,OAAO,GACP,UAAU,GACV,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,aAAa,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AA0DD,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,OAAO,CAA2B;gBAE9B,UAAU,CAAC,EAAE,MAAM;IAS/B;;;OAGG;IACH,MAAM,CACJ,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GACA,IAAI;IAgDP;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,qBAAqB;IAmDxE;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,aAAa,GAAG,sBAAsB,EAAE;IAI9D;;OAEG;IACH,UAAU,IAAI,MAAM,CAAC,aAAa,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAmB7E,OAAO,CAAC,IAAI;IAIZ,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,KAAK;IAcb,OAAO,CAAC,KAAK;CAUd"}

package/dist/agent-reputation.js

@@ -0,0 +1,222 @@
+/**
+ * @module agent-reputation
+ * @description Agent Reputation / Trust Layer for role agents.
+ * Tracks performance of specialized role agents and enables AgentCoordinator
+ * to route tasks to the best-performing agent for each context.
+ *
+ * Storage: ~/.yuan/reputation/agent-reputation.json
+ *
+ * Wilson score lower bound (95% CI) is used as reputationScore for robustness
+ * against small sample sizes.
+ */
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ─── Helpers ───
+const Z = 1.96; // 95% confidence interval
+/**
+ * Wilson score lower bound (confidence-correct success rate).
+ * Falls back to 0.5 when n < 3 (insufficient data).
+ */
+function wilsonLowerBound(successes, failures) {
+    const n = successes + failures;
+    if (n < 3)
+        return 0.5;
+    const p = successes / n;
+    const z2 = Z * Z;
+    const numerator = p + z2 / (2 * n) - Z * Math.sqrt((p * (1 - p)) / n + z2 / (4 * n * n));
+    const denominator = 1 + z2 / n;
+    return Math.max(0, Math.min(1, numerator / denominator));
+}
+/**
+ * Running average helper: update avg with a new value given prior count.
+ */
+function updatedAvg(currentAvg, currentCount, newValue) {
+    return (currentAvg * currentCount + newValue) / (currentCount + 1);
+}
+/**
+ * Default agent routing when no performance data exists.
+ */
+function defaultAgent(taskType) {
+    const lower = taskType.toLowerCase();
+    if (lower === "bugfix" || lower === "feature" || lower === "refactor")
+        return "coder";
+    if (lower === "research" || lower === "analysis")
+        return "researcher";
+    if (lower === "review" || lower === "qa")
+        return "reviewer";
+    if (lower === "incident" || lower === "debug")
+        return "incident";
+    if (lower === "plan" || lower === "design")
+        return "planner";
+    return "coder";
+}
+const ALL_AGENT_TYPES = [
+    "planner",
+    "researcher",
+    "coder",
+    "reviewer",
+    "verifier",
+    "incident",
+];
+// ─── Class ───
+export class AgentReputation extends EventEmitter {
+    storageFile;
+    records;
+    constructor(storageDir) {
+        super();
+        const dir = storageDir ?? join(homedir(), ".yuan", "reputation");
+        this.storageFile = join(dir, "agent-reputation.json");
+        this.records = this._load(dir);
+    }
+    // ─── Public API ───
+    /**
+     * Record a task outcome for a role agent.
+     * Updates avgLatencyMs, avgTokenCost, and reputationScore (Wilson lower bound).
+     */
+    record(agentType, taskType, outcome) {
+        const now = new Date().toISOString();
+        const key = this._key(agentType, taskType, outcome.environment);
+        let existing = this.records.find((r) => this._keyOf(r) === key);
+        if (!existing) {
+            existing = {
+                agentType,
+                taskType,
+                environment: outcome.environment,
+                successes: 0,
+                failures: 0,
+                avgLatencyMs: 0,
+                avgTokenCost: 0,
+                reputationScore: 0.5,
+                lastUpdated: now,
+            };
+            this.records.push(existing);
+        }
+        const prevCount = existing.successes + existing.failures;
+        // Update running averages
+        existing.avgLatencyMs = updatedAvg(existing.avgLatencyMs, prevCount, outcome.latencyMs);
+        existing.avgTokenCost = updatedAvg(existing.avgTokenCost, prevCount, outcome.tokenCost);
+        if (outcome.success) {
+            existing.successes += 1;
+        }
+        else {
+            existing.failures += 1;
+        }
+        existing.reputationScore = wilsonLowerBound(existing.successes, existing.failures);
+        existing.lastUpdated = now;
+        this._save();
+        this.emit("agent:reputation_updated", {
+            kind: "agent:reputation_updated",
+            agentType,
+            taskType,
+            reputationScore: existing.reputationScore,
+            successes: existing.successes,
+            failures: existing.failures,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Get routing recommendation for a task type (and optional environment).
+     * Sorts candidates by Wilson score. Falls back to default routing if no data.
+     */
+    recommend(taskType, environment) {
+        // Collect records matching taskType (exact match, env-aware)
+        const candidates = this.records.filter((r) => r.taskType === taskType &&
+            (environment === undefined || r.environment === environment || r.environment === undefined));
+        if (candidates.length === 0) {
+            // No data — use default routing
+            const recommended = defaultAgent(taskType);
+            return {
+                taskType,
+                environment,
+                recommended,
+                score: 0.5,
+                alternatives: ALL_AGENT_TYPES.filter((t) => t !== recommended).map((agentType) => ({
+                    agentType,
+                    score: 0.5,
+                })),
+                reason: `No performance data for task "${taskType}". Using default routing.`,
+            };
+        }
+        // Aggregate by agentType (pick best record per agent if multiple envs match)
+        const agentBestScore = new Map();
+        for (const c of candidates) {
+            const current = agentBestScore.get(c.agentType) ?? -1;
+            if (c.reputationScore > current) {
+                agentBestScore.set(c.agentType, c.reputationScore);
+            }
+        }
+        // Sort descending by score
+        const sorted = Array.from(agentBestScore.entries()).sort((a, b) => b[1] - a[1]);
+        const [topAgent, topScore] = sorted[0];
+        const alternatives = sorted.slice(1).map(([agentType, score]) => ({ agentType, score }));
+        const total = candidates.reduce((s, r) => s + r.successes + r.failures, 0);
+        return {
+            taskType,
+            environment,
+            recommended: topAgent,
+            score: topScore,
+            alternatives,
+            reason: `Based on ${total} recorded tasks. ${topAgent} leads with Wilson score ${topScore.toFixed(3)}.`,
+        };
+    }
+    /**
+     * Get all performance records for a given agent type.
+     */
+    getRecords(agentType) {
+        return this.records.filter((r) => r.agentType === agentType);
+    }
+    /**
+     * Get a summary of average reputation scores and total task counts per agent type.
+     */
+    getSummary() {
+        const result = {};
+        for (const agentType of ALL_AGENT_TYPES) {
+            const recs = this.records.filter((r) => r.agentType === agentType);
+            if (recs.length === 0) {
+                result[agentType] = { avgScore: 0.5, totalTasks: 0 };
+            }
+            else {
+                const totalTasks = recs.reduce((s, r) => s + r.successes + r.failures, 0);
+                const avgScore = recs.reduce((s, r) => s + r.reputationScore, 0) / recs.length;
+                result[agentType] = { avgScore, totalTasks };
+            }
+        }
+        return result;
+    }
+    // ─── Internal ───
+    _key(agentType, taskType, environment) {
+        return `${agentType}::${taskType}::${environment ?? ""}`;
+    }
+    _keyOf(record) {
+        return this._key(record.agentType, record.taskType, record.environment);
+    }
+    _load(storageDir) {
+        try {
+            if (!existsSync(storageDir)) {
+                mkdirSync(storageDir, { recursive: true });
+            }
+            if (!existsSync(this.storageFile))
+                return [];
+            const raw = readFileSync(this.storageFile, "utf8");
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed.records) ? parsed.records : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    _save() {
+        const tmpFile = `${this.storageFile}.tmp`;
+        try {
+            const data = { records: this.records };
+            writeFileSync(tmpFile, JSON.stringify(data, null, 2), "utf8");
+            renameSync(tmpFile, this.storageFile);
+        }
+        catch {
+            // Non-fatal: storage failures should not crash the agent loop
+        }
+    }
+}
+//# sourceMappingURL=agent-reputation.js.map

package/dist/agent-reputation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-reputation.js","sourceRoot":"","sources":["../src/agent-reputation.ts"],"names":[],"mappings":"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"}

package/dist/arch-summarizer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module arch-summarizer
+ * @description Architecture Auto-Summarizer.
+ *
+ * Scans the project and generates a concise architecture summary cached at
+ * `.yuan/cache/arch-summary.md`. Refreshes when dependency graph changes
+ * (detected via mtime of package.json / tsconfig.json) or when explicitly
+ * called after a major refactor.
+ *
+ * Design constraints:
+ * - Runs async, never blocks main loop
+ * - Uses only local file system — no LLM calls
+ * - Cache TTL: 24 hours + invalidated by package.json/tsconfig mtime change
+ */
+export declare class ArchSummarizer {
+    private readonly projectPath;
+    private readonly cacheDir;
+    private readonly cachePath;
+    constructor(projectPath: string, cacheBase?: string);
+    /** Path to the cached summary file */
+    get path(): string;
+    /**
+     * Returns cached summary if fresh, otherwise regenerates.
+     * Never throws — returns empty string on failure.
+     */
+    getSummary(): Promise<string>;
+    /**
+     * Force-regenerate the summary and update cache.
+     * Safe to call after a dependency graph change.
+     */
+    regenerate(): Promise<string>;
+    /**
+     * Check if a dependency-graph-relevant file changed since last cache.
+     * Lightweight mtime check — no file reading.
+     */
+    isDirty(): boolean;
+    private loadCache;
+    private isFresh;
+    private getMtime;
+    private buildSummary;
+    private saveCache;
+    private fileExists;
+    private depExists;
+    private devDepExists;
+    private listDirs;
+    private countSourceFiles;
+}
+//# sourceMappingURL=arch-summarizer.d.ts.map

package/dist/arch-summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch-summarizer.d.ts","sourceRoot":"","sources":["../src/arch-summarizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6BH,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJ9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGhB,WAAW,EAAE,MAAM,EACpC,SAAS,CAAC,EAAE,MAAM;IAMpB,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAYnC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAUnC;;;OAGG;IACH,OAAO,IAAI,OAAO;IAYlB,OAAO,CAAC,SAAS;IAcjB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,QAAQ;YAQF,YAAY;IAoF1B,OAAO,CAAC,SAAS;IAajB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,gBAAgB;CAgBzB"}

package/dist/arch-summarizer.js

@@ -0,0 +1,239 @@
+/**
+ * @module arch-summarizer
+ * @description Architecture Auto-Summarizer.
+ *
+ * Scans the project and generates a concise architecture summary cached at
+ * `.yuan/cache/arch-summary.md`. Refreshes when dependency graph changes
+ * (detected via mtime of package.json / tsconfig.json) or when explicitly
+ * called after a major refactor.
+ *
+ * Design constraints:
+ * - Runs async, never blocks main loop
+ * - Uses only local file system — no LLM calls
+ * - Cache TTL: 24 hours + invalidated by package.json/tsconfig mtime change
+ */
+import { mkdirSync, writeFileSync, readFileSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import { homedir } from "node:os";
+import { readdirSync } from "node:fs";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+export class ArchSummarizer {
+    projectPath;
+    cacheDir;
+    cachePath;
+    constructor(projectPath, cacheBase) {
+        this.projectPath = projectPath;
+        this.cacheDir = cacheBase ?? join(homedir(), ".yuan", "cache");
+        this.cachePath = join(this.cacheDir, "arch-summary.md");
+    }
+    /** Path to the cached summary file */
+    get path() {
+        return this.cachePath;
+    }
+    /**
+     * Returns cached summary if fresh, otherwise regenerates.
+     * Never throws — returns empty string on failure.
+     */
+    async getSummary() {
+        try {
+            const cached = this.loadCache();
+            if (cached && this.isFresh(cached)) {
+                return cached.content;
+            }
+            return await this.regenerate();
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * Force-regenerate the summary and update cache.
+     * Safe to call after a dependency graph change.
+     */
+    async regenerate() {
+        try {
+            const summary = await this.buildSummary();
+            this.saveCache(summary);
+            return summary;
+        }
+        catch {
+            return "";
+        }
+    }
+    /**
+     * Check if a dependency-graph-relevant file changed since last cache.
+     * Lightweight mtime check — no file reading.
+     */
+    isDirty() {
+        try {
+            const cached = this.loadCache();
+            if (!cached)
+                return true;
+            return !this.isFresh(cached);
+        }
+        catch {
+            return true;
+        }
+    }
+    // ─── private ───────────────────────────────────────────────────────────────
+    loadCache() {
+        try {
+            const raw = readFileSync(this.cachePath, "utf-8");
+            // Cache header is a JSON comment at the top: <!-- CACHE:{...} -->
+            const match = raw.match(/^<!-- CACHE:(.*?) -->/);
+            if (!match)
+                return null;
+            const meta = JSON.parse(match[1]);
+            meta.content = raw.replace(/^<!-- CACHE:.*? -->\n/, "");
+            return meta;
+        }
+        catch {
+            return null;
+        }
+    }
+    isFresh(cache) {
+        const age = Date.now() - new Date(cache.generatedAt).getTime();
+        if (age > CACHE_TTL_MS)
+            return false;
+        const pkgMtime = this.getMtime(join(this.projectPath, "package.json"));
+        const tscMtime = this.getMtime(join(this.projectPath, "tsconfig.json"));
+        return pkgMtime === cache.packageJsonMtime && tscMtime === cache.tsconfigMtime;
+    }
+    getMtime(filePath) {
+        try {
+            return statSync(filePath).mtimeMs;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async buildSummary() {
+        const projectPath = this.projectPath;
+        // 1. Read package.json
+        let pkg = {};
+        try {
+            pkg = JSON.parse(readFileSync(join(projectPath, "package.json"), "utf-8"));
+        }
+        catch { /* ok */ }
+        // 2. Detect project type
+        const isMonorepo = this.fileExists(join(projectPath, "pnpm-workspace.yaml"))
+            || this.fileExists(join(projectPath, "lerna.json"))
+            || this.fileExists(join(projectPath, "turbo.json"));
+        const hasNextJs = this.depExists(pkg, "next");
+        const hasReact = this.depExists(pkg, "react");
+        const hasExpress = this.depExists(pkg, "express") || this.depExists(pkg, "fastify") || this.depExists(pkg, "hono");
+        const hasTypeScript = this.devDepExists(pkg, "typescript") || this.fileExists(join(projectPath, "tsconfig.json"));
+        const hasPrisma = this.depExists(pkg, "@prisma/client") || this.fileExists(join(projectPath, "prisma/schema.prisma"));
+        const hasVite = this.devDepExists(pkg, "vite");
+        // 3. Collect top-level dirs
+        const topDirs = this.listDirs(projectPath).slice(0, 20);
+        // 4. Count source files
+        const srcFileCount = this.countSourceFiles(projectPath, 3);
+        // 5. Key scripts
+        const scripts = Object.keys(pkg.scripts ?? {}).slice(0, 10);
+        // 6. Build summary
+        const lines = [
+            `# Architecture Summary`,
+            ``,
+            `**Project:** ${pkg.name ?? "unknown"} ${pkg.version ? `v${pkg.version}` : ""}`,
+            pkg.description ? `**Description:** ${pkg.description}` : "",
+            ``,
+            `## Stack`,
+            ``,
+        ];
+        const stackItems = [];
+        if (isMonorepo)
+            stackItems.push("Monorepo (pnpm workspace)");
+        if (hasTypeScript)
+            stackItems.push("TypeScript");
+        if (hasNextJs)
+            stackItems.push("Next.js");
+        if (hasReact && !hasNextJs)
+            stackItems.push("React");
+        if (hasVite)
+            stackItems.push("Vite");
+        if (hasExpress)
+            stackItems.push("Node.js backend (Express/Fastify/Hono)");
+        if (hasPrisma)
+            stackItems.push("Prisma ORM");
+        for (const item of stackItems) {
+            lines.push(`- ${item}`);
+        }
+        lines.push(``, `## Structure`, ``);
+        lines.push(`\`\`\``);
+        for (const dir of topDirs) {
+            lines.push(`${dir}/`);
+        }
+        lines.push(`\`\`\``);
+        lines.push(``, `## Stats`, ``, `- Source files: ~${srcFileCount}`, `- Scripts: ${scripts.join(", ")}`, ``, `## Key Dependencies`, ``);
+        const allDeps = [
+            ...Object.keys(pkg.dependencies ?? {}),
+            ...Object.keys(pkg.devDependencies ?? {}),
+        ].filter(d => !d.startsWith("@types/")).slice(0, 20);
+        for (const dep of allDeps) {
+            lines.push(`- \`${dep}\``);
+        }
+        return lines.filter(l => l !== "").join("\n") + "\n";
+    }
+    saveCache(content) {
+        try {
+            mkdirSync(this.cacheDir, { recursive: true });
+            const meta = {
+                generatedAt: new Date().toISOString(),
+                packageJsonMtime: this.getMtime(join(this.projectPath, "package.json")),
+                tsconfigMtime: this.getMtime(join(this.projectPath, "tsconfig.json")),
+            };
+            const header = `<!-- CACHE:${JSON.stringify(meta)} -->\n`;
+            writeFileSync(this.cachePath, header + content, "utf-8");
+        }
+        catch { /* non-fatal */ }
+    }
+    fileExists(p) {
+        try {
+            statSync(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    depExists(pkg, name) {
+        return name in (pkg.dependencies ?? {});
+    }
+    devDepExists(pkg, name) {
+        return name in (pkg.devDependencies ?? {});
+    }
+    listDirs(dir) {
+        try {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter(e => e.isDirectory() && !e.name.startsWith(".") && e.name !== "node_modules")
+                .map(e => e.name)
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    countSourceFiles(dir, maxDepth) {
+        const SRC_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".py", ".go", ".rs", ".java"]);
+        let count = 0;
+        const walk = (d, depth) => {
+            if (depth > maxDepth)
+                return;
+            try {
+                for (const entry of readdirSync(d, { withFileTypes: true })) {
+                    if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+                        continue;
+                    if (entry.isDirectory())
+                        walk(join(d, entry.name), depth + 1);
+                    else if (SRC_EXTS.has(extname(entry.name)))
+                        count++;
+                }
+            }
+            catch { /* skip unreadable dirs */ }
+        };
+        walk(dir, 0);
+        return count;
+    }
+}
+//# sourceMappingURL=arch-summarizer.js.map

package/dist/arch-summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arch-summarizer.js","sourceRoot":"","sources":["../src/arch-summarizer.ts"],"names":[],"mappings":"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"}

package/dist/autonomous/explicit-planner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module autonomous/explicit-planner
+ * @description ExplicitPlanningEngine — generates an explicit numbered plan before coding
+ * and persists it to .yuan/tasks/<taskId>/plan.json.
+ *
+ * Wraps HierarchicalPlanner: uses its TacticalTask list as plan steps,
+ * adds task-level persistence and event emission.
+ */
+import { EventEmitter } from "node:events";
+import { type HierarchicalPlannerConfig } from "../hierarchical-planner.js";
+import type { BYOKClient } from "../llm-client.js";
+export interface AutonomousPlanStep {
+    index: number;
+    description: string;
+    /** 0-based indices of steps this depends on */
+    dependsOn: number[];
+    /** Files to be modified */
+    targetFiles?: string[];
+}
+export interface ExplicitPlan {
+    taskId: string;
+    goal: string;
+    steps: AutonomousPlanStep[];
+    /** ISO timestamp */
+    createdAt: string;
+    /** Path to this plan file */
+    storedAt: string;
+}
+export interface ExplicitPlannerConfig {
+    plannerConfig?: Partial<HierarchicalPlannerConfig>;
+    tasksDir?: string;
+    projectPath?: string;
+}
+export declare class ExplicitPlanningEngine extends EventEmitter {
+    private readonly tasksDir;
+    private readonly projectPath;
+    constructor(config?: ExplicitPlannerConfig);
+    /**
+     * Generate an explicit plan for a goal using HierarchicalPlanner.
+     * Persists to .yuan/tasks/<taskId>/plan.json and emits agent:plan_generated.
+     */
+    plan(goal: string, llmClient: BYOKClient, taskId?: string, context?: string): Promise<ExplicitPlan>;
+    private emitPlanGenerated;
+}
+//# sourceMappingURL=explicit-planner.d.ts.map

package/dist/autonomous/explicit-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-planner.d.ts","sourceRoot":"","sources":["../../src/autonomous/explicit-planner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAEL,KAAK,yBAAyB,EAE/B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,qBAAa,sBAAuB,SAAQ,YAAY;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,MAAM,GAAE,qBAA0B;IAO9C;;;OAGG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,UAAU,EACrB,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC;IA6DxB,OAAO,CAAC,iBAAiB;CAc1B"}