@rryando/arcs 3.1.2 → 3.2.1

package/dist/utils/diagram-store.js

@@ -0,0 +1,99 @@
+/**
+ * Diagram store — encapsulates the manage-diagram.mjs subprocess.
+ *
+ * CLI command handlers should call into this module rather than spawning
+ * the script directly. Centralizes:
+ *   - script discovery (repo-local vs ~/.config/opencode)
+ *   - diagram file path resolution
+ *   - subprocess invocation with consistent stdio + timeout
+ *   - task-status → diagram-status namespace mapping
+ */
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { getDataDir } from "./paths.js";
+/**
+ * Locate the manage-diagram.mjs script. Search order:
+ *   1. Repo-local bundle (development checkout)
+ *   2. OpenCode skill install (~/.config/opencode/skills/arcs/to-diagram/...)
+ *   3. Claude Code skill install (~/.claude/skills/arcs-to-diagram/...)
+ *
+ * The Claude Code path uses the `arcs-` prefix because Claude Code skills
+ * are flat under ~/.claude/skills/ — see scripts/deploy-claudecode-bundle.mjs.
+ */
+export function findDiagramScript() {
+    const candidates = [
+        resolve(import.meta.dirname, "../../opencode/arcs/skills/to-diagram/scripts/manage-diagram.mjs"),
+        resolve(homedir(), ".config/opencode/skills/arcs/to-diagram/scripts/manage-diagram.mjs"),
+        resolve(homedir(), ".claude/skills/arcs-to-diagram/scripts/manage-diagram.mjs"),
+    ];
+    for (const path of candidates) {
+        if (existsSync(path))
+            return path;
+    }
+    return undefined;
+}
+export function resolveDiagramPath(slug, planId) {
+    const dataDir = getDataDir();
+    return resolve(dataDir, "projects", slug, "plans", `${planId}.diagram.mmd`);
+}
+/**
+ * Run the manage-diagram.mjs script and return trimmed stdout.
+ * Throws on non-zero exit; caller is responsible for error mapping.
+ */
+export function runDiagramScript(scriptPath, subcommand, diagramPath, extraArgs = []) {
+    const argsStr = extraArgs.map((a) => `"${a}"`).join(" ");
+    return execSync(`node "${scriptPath}" ${subcommand} "${diagramPath}"${argsStr ? ` ${argsStr}` : ""}`, {
+        encoding: "utf-8",
+        timeout: 10000,
+        // Capture stderr so script error output never leaks to the parent's
+        // stderr — keeps --json output clean and parseable for agents.
+        stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+}
+/**
+ * Map task status (snake_case in the ARCS task model) to diagram classDef
+ * status (camelCase in the Mermaid script). The two namespaces are
+ * intentionally distinct — task statuses follow Python/JSON convention,
+ * diagram statuses match the classDef identifiers.
+ */
+export function taskStatusToDiagramStatus(status) {
+    switch (status) {
+        case "in_progress":
+            return "inProgress";
+        case "done":
+            return "done";
+        case "cancelled":
+            return "blocked";
+        case "backlog":
+            return "backlog";
+    }
+}
+/**
+ * Best-effort diagram node status update. Returns a structured result
+ * rather than throwing — callers expect this to fail gracefully when
+ * the diagram or script is absent.
+ */
+export function attemptDiagramUpdate(slug, planId, nodeId, status) {
+    const diagramPath = resolveDiagramPath(slug, planId);
+    if (!existsSync(diagramPath)) {
+        return { diagramUpdated: false, diagramError: "Diagram file not found" };
+    }
+    const scriptPath = findDiagramScript();
+    if (!scriptPath) {
+        return { diagramUpdated: false, diagramError: "manage-diagram.mjs script not found" };
+    }
+    try {
+        runDiagramScript(scriptPath, "status", diagramPath, [
+            nodeId,
+            taskStatusToDiagramStatus(status),
+        ]);
+        return { diagramUpdated: true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.stderr || err.message : String(err);
+        return { diagramUpdated: false, diagramError: msg };
+    }
+}
+//# sourceMappingURL=diagram-store.js.map

package/dist/utils/diagram-store.js.map

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

package/dist/utils/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,qBAAa,QAAS,SAAQ,KAAK;aAEf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAEtD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE3D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAKpD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAKxE;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,QAAQ,CAKzE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAK9D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE3D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAExD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEvD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,MAAM,EACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,QAAQ,CAKV;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE5F;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEnE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAE7E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAExF;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAM9D;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAMtF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAK3D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ;;;;;;EAExC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,qBAAa,QAAS,SAAQ,KAAK;aAEf,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAEtD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE3D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAKpD;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAKxE;AAED,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,QAAQ,CAKzE;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAE9D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,QAAQ,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAE1D;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAE3D;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAExD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEvD;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,MAAM,EACzC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,QAAQ,CAKV;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE5F;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAEnE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAE7E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAExF;AAED,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAM9D;AAED,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAMtF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAK3D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAKvD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ;;;;;;EAExC"}

package/dist/utils/errors.js.map

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

package/dist/utils/graphify-knowledge.d.ts

@@ -1,6 +1,22 @@
 import type { KnowledgeProposal } from "./graphify.js";
-export declare function persistProposals(slug: string, proposals: KnowledgeProposal[]): Promise<{
-    created: number;
-    skipped: number;
+/**
+ * Convert graphify ingestion output into a `proposals/graphify.json` payload
+ * and persist it through `proposal-store.writeProposals()`.
+ *
+ * Replaces the legacy direct-write path that used to populate
+ * `knowledge/index.json` and `knowledge/<id>.md` at ingest time. Graphify
+ * proposals now sit in the proposals gate until a skill-aware host enriches
+ * them into durable knowledge entries.
+ *
+ * Merge semantics: if a proposals file already exists, proposals from the
+ * existing file with ids NOT present in the new extraction are preserved.
+ * This protects backfilled proposals (with empty structuralFacts) and any
+ * other pending entries from being clobbered when graphify re-runs. The new
+ * extraction wins on collisions — a fresh extraction produces fresher facts.
+ */
+export declare function writeProposalsFile(slug: string, proposals: KnowledgeProposal[], graphJsonContent: string): Promise<{
+    written: number;
+    fingerprint: string;
+    preserved: number;
 }>;
 //# sourceMappingURL=graphify-knowledge.d.ts.map

package/dist/utils/graphify-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphify-knowledge.d.ts","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAwCvD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,iBAAiB,EAAE,GAC7B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAoD/C"}
+{"version":3,"file":"graphify-knowledge.d.ts","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAUvD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,iBAAiB,EAAE,EAC9B,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAmCtE"}

package/dist/utils/graphify-knowledge.js

@@ -1,60 +1,47 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { getProjectDir } from "./paths.js";
-function slugifyTitle(title) {
-    return title
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "")
-        .slice(0, 80);
-}
-async function readJsonSafe(filePath) {
-    try {
-        return JSON.parse(await readFile(filePath, "utf-8"));
-    }
-    catch {
-        return undefined;
-    }
-}
-async function writeJson(filePath, data) {
-    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
-}
-export async function persistProposals(slug, proposals) {
-    const projectDir = getProjectDir(slug);
-    const knowledgeDir = join(projectDir, "knowledge");
-    await mkdir(knowledgeDir, { recursive: true });
-    const indexPath = join(knowledgeDir, "index.json");
-    const index = (await readJsonSafe(indexPath)) ?? { entries: [] };
-    const existingIds = new Set(index.entries.map((e) => e.id));
-    let created = 0;
-    let skipped = 0;
-    for (const proposal of proposals) {
-        const id = slugifyTitle(proposal.title);
-        if (existingIds.has(id)) {
-            skipped++;
-            continue;
-        }
-        const ts = new Date().toISOString();
-        const bodyFile = join("knowledge", `${id}.md`);
-        const meta = {
-            id,
-            normalizedId: id,
-            title: proposal.title,
-            kind: proposal.kind,
-            keywords: proposal.keywords,
-            summary: proposal.summary,
-            sourceFiles: proposal.sourceFiles,
-            file: bodyFile,
-            createdAt: ts,
-            updatedAt: ts,
-        };
-        await writeJson(join(knowledgeDir, `${id}.meta.json`), meta);
-        await writeFile(join(knowledgeDir, `${id}.md`), `# ${proposal.title}\n\n${proposal.summary}\n`, "utf-8");
-        index.entries.push(meta);
-        existingIds.add(id);
-        created++;
-    }
-    await writeJson(indexPath, index);
-    return { created, skipped };
+import { annotateDedupCandidates, computeGraphFingerprint, readProposals, writeProposals, } from "./proposal-store.js";
+/**
+ * Convert graphify ingestion output into a `proposals/graphify.json` payload
+ * and persist it through `proposal-store.writeProposals()`.
+ *
+ * Replaces the legacy direct-write path that used to populate
+ * `knowledge/index.json` and `knowledge/<id>.md` at ingest time. Graphify
+ * proposals now sit in the proposals gate until a skill-aware host enriches
+ * them into durable knowledge entries.
+ *
+ * Merge semantics: if a proposals file already exists, proposals from the
+ * existing file with ids NOT present in the new extraction are preserved.
+ * This protects backfilled proposals (with empty structuralFacts) and any
+ * other pending entries from being clobbered when graphify re-runs. The new
+ * extraction wins on collisions — a fresh extraction produces fresher facts.
+ */
+export async function writeProposalsFile(slug, proposals, graphJsonContent) {
+    // Map ingestion shape → storage shape. The storage `Proposal` adds an
+    // initially-empty `suggestedDedupCandidates`; `annotateDedupCandidates`
+    // populates it from the existing knowledge index.
+    const draft = proposals.map((p) => ({
+        id: p.id,
+        kind: p.kind,
+        label: p.label,
+        structuralFacts: p.structuralFacts,
+        sourceFiles: p.sourceFiles,
+        suggestedDedupCandidates: [],
+    }));
+    const annotated = await annotateDedupCandidates(slug, draft);
+    // Preserve existing proposals not present in the new extraction. This
+    // protects the lossy backfill payload (structuralFacts: {}) and any other
+    // pending agent-enrichment work from being silently dropped on the next
+    // graphify-sync. New extraction wins on id collisions.
+    const existing = await readProposals(slug);
+    const newIds = new Set(annotated.map((p) => p.id));
+    const preserved = existing ? existing.proposals.filter((p) => !newIds.has(p.id)) : [];
+    const fingerprint = computeGraphFingerprint(graphJsonContent);
+    const payload = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        graphFingerprint: fingerprint,
+        proposals: [...annotated, ...preserved],
+    };
+    await writeProposals(slug, payload);
+    return { written: proposals.length, fingerprint, preserved: preserved.length };
 }
 //# sourceMappingURL=graphify-knowledge.js.map

package/dist/utils/graphify-knowledge.js.map

@@ -1 +1 @@
-{"version":3,"file":"graphify-knowledge.js","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"graphify-knowledge.js","sourceRoot":"","sources":["../../src/utils/graphify-knowledge.ts"],"names":[],"mappings":"AACA,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EAGvB,aAAa,EACb,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,SAA8B,EAC9B,gBAAwB;IAExB,sEAAsE;IACtE,wEAAwE;IACxE,kDAAkD;IAClD,MAAM,KAAK,GAAe,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC9C,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,eAAe,EAAE,CAAC,CAAC,eAAqD;QACxE,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,wBAAwB,EAAE,EAAE;KAC7B,CAAC,CAAC,CAAC;IAEJ,MAAM,SAAS,GAAG,MAAM,uBAAuB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAE7D,sEAAsE;IACtE,0EAA0E;IAC1E,wEAAwE;IACxE,uDAAuD;IACvD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEtF,MAAM,WAAW,GAAG,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;IAE9D,MAAM,OAAO,GAAkB;QAC7B,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrC,gBAAgB,EAAE,WAAW;QAC7B,SAAS,EAAE,CAAC,GAAG,SAAS,EAAE,GAAG,SAAS,CAAC;KACxC,CAAC;IAEF,MAAM,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAEpC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC;AACjF,CAAC"}

package/dist/utils/graphify.d.ts

@@ -14,16 +14,71 @@ export interface ExtractionError {
     code?: string;
 }
 export type ExtractionOutcome = ExtractionResult | ExtractionError;
+/**
+ * A graphify-derived knowledge proposal.
+ *
+ * Carries STRUCTURAL FACTS only — not prose. The calling agent (which has LLM
+ * tokens) is responsible for producing the final `title`/`summary`/`keywords`
+ * during the proposal-promote step. See plan
+ * `2026-06-02-graphify-proposal-gate-implementation-plan` §Proposal Shape.
+ *
+ * `suggestedDedupCandidates` is intentionally NOT on this type — that's
+ * computed by the proposal-store layer when proposals are written to disk,
+ * not at ingest time.
+ */
 export interface KnowledgeProposal {
-    title: string;
+    /** Stable id, e.g. "graphify-cluster-src-utils". */
+    id: string;
     kind: "architecture" | "module" | "gotcha" | "pattern";
-    summary: string;
-    keywords: string[];
+    /** Human-friendly label. Agents will write the final title. */
+    label: string;
+    structuralFacts: ProposalStructuralFacts;
     sourceFiles: Array<{
         path: string;
         anchor?: string;
     }>;
 }
+export interface ProposalStructuralFacts {
+    memberCount?: number;
+    fileCount?: number;
+    /** e.g. { code: 260, document: 0 } */
+    fileTypeBreakdown?: Record<string, number>;
+    topHubs?: Array<{
+        label: string;
+        file: string;
+        in: number;
+        out: number;
+    }>;
+    topFilesByEntityCount?: Array<{
+        file: string;
+        count: number;
+    }>;
+    incomingFromOtherClusters?: number;
+    outgoingToOtherClusters?: number;
+    nodeFile?: string;
+    nodeIn?: number;
+    nodeOut?: number;
+    topCallers?: Array<{
+        label: string;
+        file: string;
+    }>;
+    topCallees?: Array<{
+        label: string;
+        file: string;
+    }>;
+    couplingA?: {
+        label: string;
+        file: string;
+        degree: number;
+    };
+    couplingB?: {
+        label: string;
+        file: string;
+        degree: number;
+    };
+    /** Edge relation types (e.g. ["imports_from", "calls"]). */
+    relations?: string[];
+}
 export interface IngestionResult {
     proposals: KnowledgeProposal[];
     stats: {

package/dist/utils/graphify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphify.d.ts","sourceRoot":"","sources":["../../src/utils/graphify.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,IAAI,YAAY,CAyB7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAInE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,oBAAoB,EAAE,MAAM,CAAC;QAC7B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAsHD,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAwGjF;AAID,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,IAAI,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;AAEpD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY,CA0BhF;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY,CA0BjG;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,iBAAiB,CAsDtE"}
+{"version":3,"file":"graphify.d.ts","sourceRoot":"","sources":["../../src/utils/graphify.ts"],"names":[],"mappings":"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"}