akm-cli 0.9.0-beta.2 → 0.9.0-beta.27

package/dist/output/renderers.js

@@ -468,6 +468,44 @@ const sessionMdRenderer = {
         };
     },
 };
+// ── 9. fact-md ───────────────────────────────────────────────────────────────
+/**
+ * Renderer for the `fact` asset type. A fact is durable stash-level semantic
+ * knowledge (personal/team/project details, coding conventions, stash-meta).
+ * It carries `category` (personal|team|project|convention|meta) and an
+ * optional `pinned` flag marking it as part of the always-injected core. The
+ * renderer surfaces a one-liner (category + pinned marker) so an agent can tell
+ * at a glance what kind of fact it is and whether it is core context.
+ */
+const factMdRenderer = {
+    name: "fact-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
+        const fm = parsed.data;
+        const category = asNonEmptyString(fm.category);
+        const description = asNonEmptyString(fm.description);
+        const pinned = fm.pinned === true;
+        const headerParts = [
+            category ? `category: ${category}` : undefined,
+            pinned ? "pinned (core context)" : undefined,
+        ].filter((p) => !!p);
+        const action = [
+            "Durable stash fact — apply it as background context.",
+            headerParts.length > 0 ? headerParts.join("  ") : undefined,
+        ]
+            .filter((p) => !!p)
+            .join("\n");
+        return {
+            type: "fact",
+            name,
+            path: ctx.absPath,
+            action,
+            description,
+            content: parsed.content,
+        };
+    },
+};
 function applySessionMetadata(entry, ctx) {
     try {
         const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
@@ -501,6 +539,34 @@ function applyTocMetadata(entry, ctx) {
         // Non-fatal: skip TOC if file can't be read
     }
 }
+/**
+ * Fact metadata: surface `category` and the `pinned` core marker as tags +
+ * search hints (no dedicated DB columns — same encoding pattern as session /
+ * task). `pinned` is mirrored to both a `pinned` tag and a `pinned` search
+ * hint so the ranking contributor can detect it and queries can target it.
+ */
+function applyFactMetadata(entry, ctx) {
+    try {
+        const fm = applyFrontmatterDescriptionAndTags(entry, ctx);
+        const tags = new Set([...(entry.tags ?? []), "fact"]);
+        const hints = new Set(entry.searchHints ?? []);
+        const category = asNonEmptyString(fm.category);
+        if (category) {
+            tags.add(category);
+            hints.add(`category:${category}`);
+        }
+        if (fm.pinned === true) {
+            tags.add("pinned");
+            hints.add("pinned");
+        }
+        entry.tags = Array.from(tags).filter(Boolean);
+        if (hints.size > 0)
+            entry.searchHints = Array.from(hints).filter(Boolean);
+    }
+    catch {
+        // Non-fatal: skip metadata extraction on parse error
+    }
+}
 /**
  * Parse frontmatter, apply description (if not already set) and merge tags
  * into `entry`. Returns the raw frontmatter data object so callers can access
@@ -660,6 +726,11 @@ registerMetadataContributor({
     appliesTo: ({ rendererName }) => rendererName === "session-md",
     contribute: (entry, ctx) => applySessionMetadata(entry, ctx.renderContext),
 });
+registerMetadataContributor({
+    name: "fact-md-metadata",
+    appliesTo: ({ rendererName }) => rendererName === "fact-md",
+    contribute: (entry, ctx) => applyFactMetadata(entry, ctx.renderContext),
+});
 // ── Registration ─────────────────────────────────────────────────────────────
 /** All built-in renderers. */
 const builtinRenderers = [
@@ -676,6 +747,7 @@ const builtinRenderers = [
     secretFileRenderer,
     taskMdRenderer,
     sessionMdRenderer,
+    factMdRenderer,
 ];
 /**
  * Register all built-in renderers with the file-context registry.
@@ -687,4 +759,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, envFileRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, envFileRenderer, factMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, secretFileRenderer, skillMdRenderer, wikiMdRenderer, workflowMdRenderer, };

package/dist/output/shapes/curate.js

@@ -5,7 +5,7 @@ import { capDescription, NORMAL_DESCRIPTION_LIMIT, pickFields } from "./helpers.
 // Curation is a small, high-signal top-N. Even at `brief` we keep `followUp`
 // (the actionable `akm show <ref>` command) and `reason` (why this asset was
 // selected) — these are the point of curate, unlike a bulk search listing.
-const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "followUp", "reason"];
+const BRIEF_FIELDS = ["source", "type", "name", "ref", "id", "supportRefs", "followUp", "reason"];
 const NORMAL_FIELDS = [
     "source",
     "type",
@@ -17,12 +17,24 @@ const NORMAL_FIELDS = [
     "keys",
     "parameters",
     "run",
+    "supportRefs",
     "followUp",
     "reason",
     "score",
 ];
 // Agent shape: the minimal field set an LLM needs to decide and act.
-const AGENT_FIELDS = ["source", "type", "name", "ref", "id", "description", "followUp", "reason", "score"];
+const AGENT_FIELDS = [
+    "source",
+    "type",
+    "name",
+    "ref",
+    "id",
+    "description",
+    "supportRefs",
+    "followUp",
+    "reason",
+    "score",
+];
 function shapeCurateItem(item, detail, shape) {
     if (shape === "agent") {
         return capDescription(pickFields(item, AGENT_FIELDS), NORMAL_DESCRIPTION_LIMIT);

package/dist/output/shapes/helpers.js

@@ -41,7 +41,21 @@ export function shapeProposalEntry(entry, detail) {
         return pickFields(entry, ["id", "ref", "status", "source", "createdAt"]);
     }
     if (detail === "normal") {
-        return pickFields(entry, ["id", "ref", "status", "source", "sourceRun", "createdAt", "updatedAt", "review"]);
+        // `confidence` and `gateDecision` (#577) explain why a proposal is pending,
+        // so they are projected at `normal` for `akm proposal list/show` — both are
+        // optional and absent on legacy proposals.
+        return pickFields(entry, [
+            "id",
+            "ref",
+            "status",
+            "source",
+            "sourceRun",
+            "createdAt",
+            "updatedAt",
+            "confidence",
+            "gateDecision",
+            "review",
+        ]);
     }
     // full: project everything including the payload.
     return pickFields(entry, [
@@ -52,6 +66,8 @@ export function shapeProposalEntry(entry, detail) {
         "sourceRun",
         "createdAt",
         "updatedAt",
+        "confidence",
+        "gateDecision",
         "payload",
         "review",
     ]);

package/dist/output/text/helpers.js

@@ -235,6 +235,50 @@ export function formatProposalProducerPlain(command, r) {
     const status = String(proposal.status ?? "pending");
     return `${command}: queued proposal ${id} (${ref}) [${status}]`;
 }
+/**
+ * Render a one-line gate-decision summary for the proposal list / show surfaces
+ * (#577), e.g. `gate=deferred:below-threshold (0.72 < 0.90)`. Returns the empty
+ * string for a missing or malformed decision so legacy proposals render cleanly.
+ */
+export function formatGateDecisionSummary(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return "";
+    const d = raw;
+    const outcome = typeof d.outcome === "string" ? d.outcome : undefined;
+    if (!outcome)
+        return "";
+    const reason = typeof d.reason === "string" && d.reason.length > 0 ? `:${d.reason}` : "";
+    const cmp = formatGateThresholdComparison(d);
+    return `gate=${outcome}${reason}${cmp ? ` (${cmp})` : ""}`;
+}
+/**
+ * Reconstruct the threshold comparison the gate applied, when both sides are
+ * present (e.g. confidence 0.72 vs. autoAccept 0.90 → "0.72 < 0.90"). Returns
+ * the empty string when the decision lacks the operands.
+ */
+function formatGateThresholdComparison(d) {
+    const thresholds = (typeof d.thresholds === "object" && d.thresholds !== null ? d.thresholds : {});
+    const confidence = typeof d.confidence === "number" ? d.confidence : undefined;
+    const autoAccept = typeof thresholds.autoAccept === "number" ? thresholds.autoAccept : undefined;
+    if (confidence !== undefined && autoAccept !== undefined) {
+        const op = confidence >= autoAccept ? ">=" : "<";
+        return `${confidence.toFixed(2)} ${op} ${autoAccept.toFixed(2)}`;
+    }
+    // Drain bands: when the measured value is present, render the full comparison
+    // ("210 > 200" / "1 < 5"); otherwise fall back to the bound alone (#577).
+    const measured = typeof d.measured === "number" ? d.measured : undefined;
+    if (typeof thresholds.maxDiffLines === "number") {
+        return measured !== undefined
+            ? `${measured} > ${thresholds.maxDiffLines}`
+            : `maxDiffLines=${thresholds.maxDiffLines}`;
+    }
+    if (typeof thresholds.minContentLines === "number") {
+        return measured !== undefined
+            ? `${measured} < ${thresholds.minContentLines}`
+            : `minContentLines=${thresholds.minContentLines}`;
+    }
+    return "";
+}
 export function formatProposalListPlain(r) {
     const proposals = Array.isArray(r.proposals) ? r.proposals : [];
     const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
@@ -248,7 +292,11 @@ export function formatProposalListPlain(r) {
         const status = String(p.status ?? "?");
         const source = String(p.source ?? "?");
         const created = String(p.createdAt ?? "?");
-        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}`);
+        // #577: surface the gate verdict inline so the queue explains itself
+        // ("deferred: below-threshold"). Legacy proposals carry no gateDecision.
+        const gate = formatGateDecisionSummary(p.gateDecision);
+        const gateSuffix = gate ? `  ${gate}` : "";
+        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}${gateSuffix}`);
     }
     return lines.join("\n").trimEnd();
 }
@@ -265,6 +313,26 @@ export function formatProposalShowPlain(r) {
         lines.push(`createdAt: ${String(p.createdAt)}`);
     if (p.updatedAt)
         lines.push(`updatedAt: ${String(p.updatedAt)}`);
+    if (typeof p.confidence === "number")
+        lines.push(`confidence: ${p.confidence.toFixed(2)}`);
+    // #577: gate decision (auto-accepted / deferred / auto-rejected + reason +
+    // thresholds). Absent on legacy proposals — render "unknown" so the field is
+    // always present and the operator never sees a silent gap.
+    const gate = p.gateDecision;
+    if (gate && typeof gate.outcome === "string") {
+        lines.push(`gate.decision: ${String(gate.outcome)}`);
+        lines.push(`gate.reason: ${gate.reason ? String(gate.reason) : "unknown"}`);
+        const cmp = formatGateThresholdComparison(gate);
+        if (cmp)
+            lines.push(`gate.thresholds: ${cmp}`);
+        if (gate.gate)
+            lines.push(`gate.by: ${String(gate.gate)}`);
+        if (gate.decidedAt)
+            lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
+    }
+    else {
+        lines.push("gate.decision: unknown");
+    }
     const review = p.review;
     if (review) {
         lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);
@@ -937,6 +1005,15 @@ export function formatCuratePlain(r, detail) {
             lines.push(`  run: ${String(item.run)}`);
         if (item.followUp)
             lines.push(`  show: ${String(item.followUp)}`);
+        if (Array.isArray(item.supportRefs) && item.supportRefs.length > 0) {
+            for (const support of item.supportRefs) {
+                if (!support.ref)
+                    continue;
+                const label = typeof support.type === "string" ? `[${support.type}] ` : "";
+                const why = typeof support.reason === "string" ? ` — ${support.reason}` : "";
+                lines.push(`  support: ${label}${String(support.ref)}${why}`);
+            }
+        }
         if (detail !== "brief" && item.reason)
             lines.push(`  why: ${String(item.reason)}`);
     }

package/dist/runtime.js

@@ -22,7 +22,7 @@
  */
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { createWriteStream } from "node:fs";
+import { createWriteStream, statfsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { Readable } from "node:stream";
@@ -200,6 +200,30 @@ export function resolveModule(spec, from) {
 export function getDirname(importMetaUrl) {
     return path.dirname(fileURLToPath(importMetaUrl));
 }
+// ── Filesystem type probe ─────────────────────────────────────────────────────
+/**
+ * Best-effort filesystem-type probe: return the numeric `f_type` magic of the
+ * filesystem backing `path`, or `undefined` on any error (ENOENT/EPERM/
+ * unsupported). Used (via injection) by the SQLite journal-mode network-FS
+ * fallback (#628).
+ *
+ * This is a runtime primitive (a `statfs` filesystem-type probe) and therefore
+ * lives here, per the runtime boundary, even though it uses only `node:fs`. The
+ * "magic-number → is-network" classification stays a pure helper elsewhere.
+ *
+ * `fs.statfsSync` is a stable `node:fs` API (Node ≥ 18.15) and is implemented
+ * under Bun as well. It THROWS ENOENT on a non-existent path, so callers should
+ * probe an already-created directory — the swallowed error simply yields
+ * `undefined` (treated as "not network").
+ */
+export function statfsType(path) {
+    try {
+        return statfsSync(path).type;
+    }
+    catch {
+        return undefined;
+    }
+}
 // ── Sleep ───────────────────────────────────────────────────────────────────
 /**
  * Block the current thread for `ms` without busy-spinning. On Bun uses the real