kibi-cli 0.10.0 → 0.11.0

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAuCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAwCA,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/cli.js

@@ -30,6 +30,7 @@ import { queryCommand } from "./commands/query.js";
 import { searchCommand } from "./commands/search.js";
 import { statusCommand } from "./commands/status.js";
 import { syncCommand } from "./commands/sync.js";
+import { usageMetricsCommand } from "./commands/usage-metrics.js";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 const VERSION = packageJson.version ?? "0.1.0";
 // implements REQ-003
@@ -66,10 +67,12 @@ program
     .command("sync")
     .description("Sync entities from documents")
     .option("--validate-only", "Perform validation without mutations")
+    .option("--refresh-symbol-coordinates", "Refresh generated symbol coordinates")
     .option("--rebuild", "Rebuild branch snapshot from scratch (discards current KB)")
     .action(withExitCode(async (options) => {
     return syncCommand(options);
 }));
+program;
 program
     .command("query [type]")
     .description("Query knowledge base")
@@ -165,6 +168,14 @@ program
     .command("doctor")
     .description("Diagnose KB setup and configuration")
     .action(withExitCode(async () => doctorCommand()));
+program
+    .command("usage-metrics")
+    .description("Report usage and quality metrics from .kb/usage.log")
+    .option("--format <format>", "Output format: json|table", "table")
+    .option("--limit <n>", "Limit top zero-result source files", "10")
+    .action(withExitCode(async (options) => {
+    return usageMetricsCommand(options);
+}));
 program
     .command("branch")
     .description("Manage branch KBs")

package/dist/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAuDA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+GD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA0R/B"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AA8EA,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,SAAS,EAAE,CAAC;AAI1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA+UD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmU/B"}

package/dist/commands/check.js

@@ -22,8 +22,12 @@ import { extractFromManifest, extractFromManifestString, } from "../extractors/m
 import { extractFromMarkdownString, } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import { escapeAtom, parseTriples, parseViolationRows, } from "../prolog/codec.js";
-import { getStagedFiles } from "../traceability/git-staged.js";
+import { getStagedFiles, } from "../traceability/git-staged.js";
+import { KIBI_NO_IMPACT_DECLARATION, KIBI_SYMBOLS_MANIFEST_PATH, } from "../traceability/evidence-model.js";
 import { validateStagedMarkdown } from "../traceability/markdown-validate.js";
+import { collectStagedKibiDiagnostics, } from "../traceability/staged-diagnostics.js";
+import { classifyKibiImpactEvidence, isBehaviorSourceEdit, parseKibiImpactOverride, } from "../traceability/staged-impact-contract.js";
+import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEvidence, } from "../traceability/staged-symbols-manifest.js";
 import { createManifestLookupSentinelKey, extractSymbolsFromStagedFile, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projectStagedEntities, } from "../traceability/temp-kb.js";
 import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
@@ -112,6 +116,173 @@ function buildManifestLookup(stagedFiles) {
     }
     return { manifestLookup, manifestResults };
 }
+const KIBI_ENTITY_TYPES = new Set([
+    "req",
+    "scenario",
+    "test",
+    "adr",
+    "flag",
+    "event",
+    "symbol",
+    "fact",
+]);
+function isKibiEntityType(value) {
+    return KIBI_ENTITY_TYPES.has(value);
+}
+function isStagedManifestPath(filePath) {
+    if (filePath.endsWith("/symbols.yaml") ||
+        filePath.endsWith("/symbols.yml") ||
+        filePath.endsWith("/symbol-coordinates.yaml") ||
+        filePath === "symbols.yaml" ||
+        filePath === "symbols.yml" ||
+        filePath === "symbol-coordinates.yaml") {
+        return true;
+    }
+    try {
+        const config = loadConfig(process.cwd());
+        if (config.paths.symbols) {
+            const relSymbols = config.paths.symbols;
+            const configuredBase = relSymbols.split(/[\\/]/).pop();
+            if (filePath === relSymbols ||
+                (configuredBase && filePath.endsWith(`/${configuredBase}`))) {
+                return true;
+            }
+        }
+    }
+    catch {
+        // ignore config read errors
+    }
+    return false;
+}
+function isTestOnlySourcePath(filePath) {
+    return (filePath.startsWith("tests/") ||
+        filePath.includes("/tests/") ||
+        filePath.endsWith(".test.ts") ||
+        filePath.endsWith(".test.tsx") ||
+        filePath.endsWith(".test.js") ||
+        filePath.endsWith(".test.jsx") ||
+        filePath.endsWith(".spec.ts") ||
+        filePath.endsWith(".spec.tsx") ||
+        filePath.endsWith(".spec.js") ||
+        filePath.endsWith(".spec.jsx"));
+}
+function getStagedDiffText(stagedFile) {
+    return stagedFile.diffText ?? "";
+}
+function formatStagedKibiDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        const lines = [`[${diagnostic.id}] ${diagnostic.message}`];
+        if (diagnostic.files.length > 0) {
+            lines.push(`  Files: ${diagnostic.files.join(", ")}`);
+        }
+        if (diagnostic.docs.length > 0) {
+            lines.push(`  Docs: ${diagnostic.docs.join(", ")}`);
+        }
+        lines.push(`  Suggestion: ${diagnostic.suggestion}`);
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+function buildStagedKibiImpactEvidence(options) {
+    const { stagedFiles, sourceFiles, markdownFiles, markdownResults, symbolsByFile, symbolsManifestPath, } = options;
+    const sourceChanges = sourceFiles.map((file) => {
+        const symbolsForFile = symbolsByFile.get(file.path) ?? [];
+        const behaviorCandidate = !isTestOnlySourcePath(file.path) &&
+            isBehaviorSourceEdit({
+                path: file.path,
+                diffText: getStagedDiffText(file),
+                intersectsBehaviorBearingSymbol: symbolsForFile.length > 0,
+                knownUserFacingSurface: false,
+            });
+        return {
+            path: file.path,
+            kind: behaviorCandidate
+                ? "behavior_source_edit"
+                : "non_behavior_source_edit",
+        };
+    });
+    const behaviorSourcePaths = sourceChanges
+        .filter((change) => change.kind === "behavior_source_edit")
+        .map((change) => change.path);
+    const allSourcePaths = sourceChanges.map((change) => change.path);
+    const behaviorSourceFiles = sourceFiles.filter((file) => behaviorSourcePaths.includes(file.path));
+    const stagedSymbolsManifest = assessStagedSymbolsManifest({
+        symbolsManifestPath,
+        stagedFiles,
+        sourceFiles: behaviorSourceFiles,
+    });
+    const stagedAuthoredSymbolsEvidence = collectStagedAuthoredSymbolsManifestEvidence({
+        stagedFiles,
+        sourceFiles: behaviorSourceFiles,
+    });
+    const markdownResultsByPath = new Map();
+    for (const [index, file] of markdownFiles.entries()) {
+        const result = markdownResults[index];
+        if (result) {
+            markdownResultsByPath.set(file.path, result);
+        }
+    }
+    const resolvedKbArtifacts = [];
+    let override = null;
+    for (const file of markdownFiles) {
+        const parsedOverride = parseKibiImpactOverride(file.content ?? "");
+        const evidenceKind = classifyKibiImpactEvidence({
+            filePath: file.path,
+            extractionOutputChanged: false,
+            overrideDeclared: parsedOverride.declared,
+            overrideRationale: parsedOverride.rationale,
+        });
+        if (evidenceKind === "entity_markdown") {
+            const result = markdownResultsByPath.get(file.path);
+            if (result && isKibiEntityType(result.entity.type)) {
+                resolvedKbArtifacts.push({
+                    kind: "entity_markdown",
+                    path: file.path,
+                    entityTypes: [result.entity.type],
+                    entityIds: [result.entity.id],
+                    sourcePaths: [...behaviorSourcePaths],
+                });
+            }
+            continue;
+        }
+        if (!parsedOverride.declared || override !== null) {
+            continue;
+        }
+        override = {
+            declaration: KIBI_NO_IMPACT_DECLARATION,
+            path: file.path,
+            sourcePaths: [...allSourcePaths],
+            reason: "non_behavioral_source_edit",
+            rationale: parsedOverride.rationale ?? "",
+        };
+    }
+    if (stagedAuthoredSymbolsEvidence.entries.length > 0) {
+        resolvedKbArtifacts.push({
+            kind: "symbols_manifest",
+            path: stagedAuthoredSymbolsEvidence.path,
+            entityTypes: ["symbol"],
+            entityIds: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.flatMap((entry) => entry.entityIds)),
+            sourcePaths: uniqueSorted(stagedAuthoredSymbolsEvidence.entries.map((entry) => entry.sourcePath)),
+        });
+    }
+    return {
+        sourceChanges,
+        symbolsManifest: {
+            path: stagedSymbolsManifest.path,
+            state: stagedSymbolsManifest.state,
+            sourcePaths: stagedSymbolsManifest.sourcePaths,
+        },
+        mode: resolvedKbArtifacts.length > 0
+            ? { kind: "kb_changes", kbArtifacts: resolvedKbArtifacts }
+            : override
+                ? { kind: "no_impact_override", override }
+                : { kind: "missing" },
+    };
+}
 // implements REQ-006
 export async function checkCommand(options) {
     let prolog = null;
@@ -147,7 +318,8 @@ export async function checkCommand(options) {
                     return { exitCode: 0 };
                 }
                 const { manifestLookup, manifestResults } = buildManifestLookup(stagedFiles);
-                const codeFiles = stagedFiles.filter((f) => !f.path.endsWith(".md"));
+                const symbolsManifestPath = loadConfig(process.cwd()).paths.symbols ?? KIBI_SYMBOLS_MANIFEST_PATH;
+                const sourceFiles = stagedFiles.filter((file) => !file.path.endsWith(".md") && !isStagedManifestPath(file.path));
                 const markdownFiles = stagedFiles.filter((f) => f.path.endsWith(".md"));
                 const markdownErrors = [];
                 for (const f of markdownFiles) {
@@ -168,9 +340,11 @@ export async function checkCommand(options) {
                     return { exitCode: 1 };
                 }
                 const allSymbols = [];
-                for (const f of codeFiles) {
+                const symbolsByFile = new Map();
+                for (const f of sourceFiles) {
                     try {
                         const symbols = extractSymbolsFromStagedFile(f, manifestLookup);
+                        symbolsByFile.set(f.path, symbols);
                         if (symbols?.length) {
                             allSymbols.push(...symbols);
                         }
@@ -184,11 +358,27 @@ export async function checkCommand(options) {
                     ...manifestResults,
                     ...markdownResults,
                 ];
+                const stagedKibiEvidence = buildStagedKibiImpactEvidence({
+                    stagedFiles,
+                    sourceFiles,
+                    markdownFiles,
+                    markdownResults,
+                    symbolsByFile,
+                    symbolsManifestPath,
+                });
+                const stagedKibiDiagnostics = collectStagedKibiDiagnostics(stagedKibiEvidence);
                 if (allSymbols.length === 0 && stagedEntityResults.length === 0) {
                     console.log("No exported symbols or staged entities found in staged files.");
                     return { exitCode: 0 };
                 }
                 if (allSymbols.length === 0) {
+                    if (stagedKibiDiagnostics.length > 0) {
+                        console.log(formatStagedKibiDiagnostics(stagedKibiDiagnostics));
+                        if (options.dryRun) {
+                            return { exitCode: 0 };
+                        }
+                        return { exitCode: 1 };
+                    }
                     console.log("✓ No violations found in staged files.");
                     return { exitCode: 0 };
                 }
@@ -207,6 +397,10 @@ export async function checkCommand(options) {
                     prolog: tempCtx.prolog,
                 });
                 const violationsFormatted = formatStagedViolations(violationsRaw);
+                if (stagedKibiDiagnostics.length > 0) {
+                    console.log(formatStagedKibiDiagnostics(stagedKibiDiagnostics));
+                    console.log();
+                }
                 if (violationsRaw && violationsRaw.length > 0) {
                     console.log(violationsFormatted);
                     await cleanupTempKb(tempCtx.tempDir);
@@ -215,6 +409,13 @@ export async function checkCommand(options) {
                     }
                     return { exitCode: 1 };
                 }
+                if (stagedKibiDiagnostics.length > 0) {
+                    await cleanupTempKb(tempCtx.tempDir);
+                    if (options.dryRun) {
+                        return { exitCode: 0 };
+                    }
+                    return { exitCode: 1 };
+                }
                 console.log("✓ No violations found in staged symbols.");
                 await cleanupTempKb(tempCtx.tempDir);
                 return { exitCode: 0 };

package/dist/commands/init-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAuGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AAoGA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMpD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsBjD;AAGD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAYf;AASD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkCnE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAiBpD"}

package/dist/commands/init-helpers.js

@@ -27,6 +27,8 @@ const POST_CHECKOUT_HOOK = `#!/bin/sh
 # branch_flag is 1 for branch checkout, 0 for file checkout
 # Refresh branch/worktree assumptions after checkout so advisory plugin state
 # starts from synced KB data instead of stale in-memory cache assumptions.
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 old_ref=$1
 new_ref=$2
@@ -48,6 +50,8 @@ const POST_MERGE_HOOK = `#!/bin/sh
 # post-merge hook for kibi
 # Parameter: squash_flag (not used)
 # Refresh KB state after merge so branch-level assumptions remain current.
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 kibi sync
 `;
@@ -55,6 +59,8 @@ const POST_REWRITE_HOOK = `#!/bin/sh
 # post-rewrite hook for kibi
 # Triggered after git rebase, git commit --amend, etc.
 # Parameter: rewrite_type (rebase or amend)
+# Uses default non-coordinate-writing sync to avoid writing
+# committed symbol artifacts during automatic hook execution.
 
 rewrite_type=$1
 
@@ -66,23 +72,14 @@ const PRE_COMMIT_HOOK = `#!/bin/sh
 # pre-commit hook for kibi
 # Hard enforcement boundary: commits are blocked only here via kibi check.
 # The OpenCode plugin remains advisory and must not replace this gate.
+# Behavior-changing source edits require staged Kibi impact evidence
+# (KB entity docs, authored symbols metadata, or refreshed symbol
+# coordinates). Test-only and docs-only edits are exempt.
+# Refresh with:
+#   kibi sync --refresh-symbol-coordinates && git add documentation/symbol-coordinates.yaml documentation/symbols.yaml
 
 set -e
 
-symbols_manifest="documentation/symbols.yaml"
-
-if [ ! -f "$symbols_manifest" ]; then
-  echo "Kibi symbols manifest is missing: $symbols_manifest" >&2
-  echo "Run 'kibi init' to create it, then stage and commit it." >&2
-  exit 1
-fi
-
-if ! git diff --quiet -- "$symbols_manifest"; then
-  echo "Kibi symbols manifest has unstaged changes: $symbols_manifest" >&2
-  echo "Stage and commit documentation/symbols.yaml with the code changes that refreshed it." >&2
-  exit 1
-fi
-
 kibi check --staged
 `;
 export async function getCurrentBranch(cwd = process.cwd()) {

package/dist/commands/sync/manifest.d.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { type ManifestSymbolEntry, enrichSymbolCoordinates } from "../../extractors/symbols-coordinator.js";
+import { writeCoordinateArtifact } from "../../extractors/symbol-coordinates.js";
+import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
 interface ManifestDeps {
     dumpYAML: typeof dumpYAML;
     enrichSymbolCoordinates: typeof enrichSymbolCoordinates;
@@ -8,9 +10,13 @@ interface ManifestDeps {
     parseYAML: typeof parseYAML;
     readFileSync: typeof readFileSync;
     writeFileSync: typeof writeFileSync;
+    writeCoordinateArtifact: typeof writeCoordinateArtifact;
+    resolveSymbolsManifestPaths: typeof resolveSymbolsManifestPaths;
 }
-export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# GENERATED fields (never edit manually \u2014 overwritten by kibi sync and kb.symbols.refresh):\n#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, coordinatesGeneratedAt\n# Run `kibi sync` or call the `kb.symbols.refresh` MCP tool to refresh coordinates.\n";
-export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps>): Promise<void>;
+export declare const SYMBOLS_MANIFEST_COMMENT_BLOCK = "# symbols.yaml\n# AUTHORED fields (edit freely):\n#   id, title, sourceFile, links, status, tags, owner, priority\n# GENERATED fields (never edit manually \u2014 overwritten by kibi sync and kb.symbols.refresh):\n#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn\n# Run `kibi sync` or call the `kb.symbols.refresh` MCP tool to refresh coordinates.\n";
+export declare function refreshManifestCoordinates(manifestPath: string, workspaceRoot: string, deps?: Partial<ManifestDeps> & {
+    refreshSymbolCoordinates?: boolean;
+}): Promise<void>;
 export declare function hasAllGeneratedCoordinates(entry: ManifestSymbolEntry): boolean;
 export declare function isEligibleForCoordinateRefresh(sourceFile: string | undefined, workspaceRoot: string, deps?: Partial<ManifestDeps>): boolean;
 export {};

package/dist/commands/sync/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AAEjD,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;CACrC;AAcD,eAAO,MAAM,8BAA8B,qYAM1C,CAAC;AAqBF,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAST;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAElE,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAE5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAgBD,eAAO,MAAM,8BAA8B,6WAM1C,CAAC;AAoBF,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAE,GACpE,OAAO,CAAC,IAAI,CAAC,CAmIf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

package/dist/commands/sync/manifest.js

@@ -14,11 +14,13 @@
 
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
+*/
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { enrichSymbolCoordinates, } from "../../extractors/symbols-coordinator.js";
+import { writeCoordinateArtifact } from "../../extractors/symbol-coordinates.js";
+import { resolveSymbolsManifestPaths } from "../../utils/manifest-paths.js";
 function resolveDeps(overrides) {
     return {
         dumpYAML,
@@ -27,6 +29,8 @@ function resolveDeps(overrides) {
         parseYAML,
         readFileSync,
         writeFileSync,
+        writeCoordinateArtifact,
+        resolveSymbolsManifestPaths,
         ...overrides,
     };
 }
@@ -34,7 +38,7 @@ export const SYMBOLS_MANIFEST_COMMENT_BLOCK = `# symbols.yaml
 # AUTHORED fields (edit freely):
 #   id, title, sourceFile, links, status, tags, owner, priority
 # GENERATED fields (never edit manually — overwritten by kibi sync and kb.symbols.refresh):
-#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn, coordinatesGeneratedAt
+#   sourceLine, sourceColumn, sourceEndLine, sourceEndColumn
 # Run \`kibi sync\` or call the \`kb.symbols.refresh\` MCP tool to refresh coordinates.
 `;
 const SYMBOL_COORD_EXTENSIONS = new Set([
@@ -52,12 +56,12 @@ const GENERATED_COORD_FIELDS = [
     "sourceColumn",
     "sourceEndLine",
     "sourceEndColumn",
-    "coordinatesGeneratedAt",
 ];
 export async function refreshManifestCoordinates(
 // implements REQ-003
 manifestPath, workspaceRoot, deps) {
     const resolved = resolveDeps(deps);
+    const shouldRefreshCoordinates = deps?.refreshSymbolCoordinates ?? false;
     const rawContent = resolved.readFileSync(manifestPath, "utf8");
     const parsed = resolved.parseYAML(rawContent);
     if (!isRecord(parsed)) {
@@ -69,11 +73,54 @@ manifestPath, workspaceRoot, deps) {
         console.warn(`Warning: symbols manifest ${manifestPath} has no symbols array; skipping coordinate refresh`);
         return;
     }
-    const before = rawSymbols.map((entry) => isRecord(entry)
-        ? { ...entry }
-        : {});
+    const before = rawSymbols.map((entry) => isRecord(entry) ? { ...entry } : {});
     const enriched = await resolved.enrichSymbolCoordinates(before, workspaceRoot);
-    parsed.symbols = enriched;
+    // Build coordinates map keyed by symbol id
+    const coordinatesMap = {};
+    for (const entry of enriched) {
+        const id = typeof entry?.id === "string" ? entry.id : undefined;
+        if (!id)
+            continue;
+        if (typeof entry.sourceFile === "string" &&
+            typeof entry.sourceLine === "number" &&
+            typeof entry.sourceColumn === "number" &&
+            typeof entry.sourceEndLine === "number" &&
+            typeof entry.sourceEndColumn === "number") {
+            coordinatesMap[id] = {
+                sourceFile: entry.sourceFile,
+                sourceLine: entry.sourceLine,
+                sourceColumn: entry.sourceColumn,
+                sourceEndLine: entry.sourceEndLine,
+                sourceEndColumn: entry.sourceEndColumn,
+            };
+        }
+    }
+    // Optionally write the coordinate artifact to the coordinates path when explicitly requested
+    if (shouldRefreshCoordinates) {
+        try {
+            const coordinatesPath = resolved.resolveSymbolsManifestPaths(workspaceRoot).coordinatesPath;
+            const artifactContent = resolved.writeCoordinateArtifact(coordinatesMap);
+            resolved.writeFileSync(coordinatesPath, artifactContent, "utf8");
+        }
+        catch (err) {
+            console.warn(`Warning: Failed to write symbol-coordinates artifact: ${String(err)}`);
+        }
+    }
+    // Strip generated fields from symbols.yaml entries only if original had them
+    const strippedEnriched = enriched.map((current, idx) => {
+        const prev = before[idx] ?? {};
+        const out = { ...current };
+        const originalHadGenerated = GENERATED_COORD_FIELDS.some((f) => prev[f] !== undefined);
+        if (originalHadGenerated) {
+            for (const field of GENERATED_COORD_FIELDS) {
+                delete out[field];
+            }
+        }
+        // Ensure we never write coordinatesGeneratedAt
+        delete out["coordinatesGeneratedAt"];
+        return out;
+    });
+    parsed.symbols = strippedEnriched;
     let refreshed = 0;
     let failed = 0;
     let unchanged = 0;
@@ -106,7 +153,7 @@ manifestPath, workspaceRoot, deps) {
     if (rawContent !== nextContent) {
         resolved.writeFileSync(manifestPath, nextContent, "utf8");
     }
-    console.log(`✓ Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
+    console.log(`\u2713 Refreshed symbol coordinates in ${path.relative(workspaceRoot, manifestPath)} (refreshed=${refreshed}, unchanged=${unchanged}, failed=${failed})`);
 }
 export function hasAllGeneratedCoordinates(
 // implements REQ-003
@@ -114,9 +161,7 @@ entry) {
     return (typeof entry.sourceLine === "number" &&
         typeof entry.sourceColumn === "number" &&
         typeof entry.sourceEndLine === "number" &&
-        typeof entry.sourceEndColumn === "number" &&
-        typeof entry.coordinatesGeneratedAt === "string" &&
-        entry.coordinatesGeneratedAt.length > 0);
+        typeof entry.sourceEndColumn === "number");
 }
 export function isEligibleForCoordinateRefresh(
 // implements REQ-003

package/dist/commands/sync.d.ts

@@ -25,6 +25,7 @@ interface SyncCommandRuntime {
 export declare function syncCommand(options?: {
     validateOnly?: boolean;
     rebuild?: boolean;
+    refreshSymbolCoordinates?: boolean;
 }, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

package/dist/commands/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAejE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,EAC3D,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAmbrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAejE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA4B7C,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAGD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;CAChE;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;CAAO,EAC/F,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CAkbrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -140,13 +140,15 @@ export async function syncCommand(options = {}, runtime = {}) {
             }
         }
         if (!validateOnly) {
-            for (const file of manifestFiles) {
-                try {
-                    await refreshManifestCoordinates(file, process.cwd());
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.warn(`Warning: Failed to refresh symbol coordinates in ${file}: ${message}`);
+            if (options.refreshSymbolCoordinates) {
+                for (const file of manifestFiles) {
+                    try {
+                        await refreshManifestCoordinates(file, process.cwd(), { refreshSymbolCoordinates: options.refreshSymbolCoordinates });
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        console.warn(`Warning: Failed to refresh symbol coordinates in ${file}: ${message}`);
+                    }
                 }
             }
         }

package/dist/commands/usage-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { CommandResult } from "../cli.js";
+interface UsageMetricsOptions {
+    format?: "json" | "table";
+    limit?: string;
+}
+export declare function usageMetricsCommand(options: UsageMetricsOptions): Promise<CommandResult | undefined>;
+export {};
+//# sourceMappingURL=usage-metrics.d.ts.map

package/dist/commands/usage-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-metrics.d.ts","sourceRoot":"","sources":["../../src/commands/usage-metrics.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,UAAU,mBAAmB;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAkED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAuBpC"}