kibi-cli 0.1.7 → 0.2.2

package/dist/diagnostics.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Diagnostic categories for drift detection and sync failures
+ *
+ * These categories provide stable identifiers for common failure modes,
+ * making it easier for both CLI users and MCP consumers to understand
+ * and respond to issues programmatically.
+ */
+export type DiagnosticCategory = "BRANCH_RESOLUTION_FAILURE" | "KB_MISSING" | "DOCS_NOT_INDEXED" | "INVALID_AUTHORING" | "SYNC_ERROR" | "EXTRACTION_ERROR" | "RELATIONSHIP_ERROR";
+export interface Diagnostic {
+    category: DiagnosticCategory;
+    severity: "error" | "warning";
+    message: string;
+    file?: string;
+    suggestion?: string;
+}
+export interface SyncSummary {
+    branch: string;
+    commit?: string;
+    timestamp: string;
+    entityCounts: Record<string, number>;
+    relationshipCount: number;
+    success: boolean;
+    published: boolean;
+    failures: Diagnostic[];
+    durationMs?: number;
+}
+/**
+ * Branch resolution error codes mapping to diagnostic categories
+ */
+export type BranchErrorCode = "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "ENV_OVERRIDE" | "UNKNOWN_ERROR";
+/**
+ * Convert branch error code to diagnostic category
+ */
+export declare function branchErrorToDiagnostic(code: BranchErrorCode, message: string, branch?: string): Diagnostic;
+/**
+ * Create KB_MISSING diagnostic
+ */
+export declare function createKbMissingDiagnostic(branch: string, path: string): Diagnostic;
+/**
+ * Create DOCS_NOT_INDEXED diagnostic
+ */
+export declare function createDocsNotIndexedDiagnostic(docCount: number, entityCount: number): Diagnostic;
+/**
+ * Create INVALID_AUTHORING diagnostic for embedded entities
+ */
+export declare function createInvalidAuthoringDiagnostic(filePath: string, embeddedTypes: string[]): Diagnostic;
+/**
+ * Format sync summary for CLI output
+ */
+export declare function formatSyncSummary(summary: SyncSummary): string;
+/**
+ * Format diagnostics for MCP structured response
+ */
+export declare function formatDiagnosticsForMcp(diagnostics: Diagnostic[]): Array<{
+    category: string;
+    severity: string;
+    message: string;
+    file?: string;
+    suggestion?: string;
+}>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,YAAY,GACZ,kBAAkB,GAClB,mBAAmB,GACnB,YAAY,GACZ,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,cAAc,GACd,eAAe,CAAC;AAEpB;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CASZ;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,CAOZ;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EAAE,GACtB,UAAU,CAQZ;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAmD9D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,UAAU,EAAE,GACxB,KAAK,CAAC;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAQD"}

package/dist/diagnostics.js

@@ -0,0 +1,114 @@
+/**
+ * Diagnostic categories for drift detection and sync failures
+ *
+ * These categories provide stable identifiers for common failure modes,
+ * making it easier for both CLI users and MCP consumers to understand
+ * and respond to issues programmatically.
+ */
+/**
+ * Convert branch error code to diagnostic category
+ */
+export function branchErrorToDiagnostic(code, message, branch) {
+    return {
+        category: "BRANCH_RESOLUTION_FAILURE",
+        severity: "error",
+        message: `Failed to resolve active branch: ${message}`,
+        suggestion: branch
+            ? `Detected branch: ${branch}. Set KIBI_BRANCH environment variable to explicitly specify the branch.`
+            : "Set KIBI_BRANCH environment variable or ensure you're in a git repository with a valid checked-out branch.",
+    };
+}
+/**
+ * Create KB_MISSING diagnostic
+ */
+export function createKbMissingDiagnostic(branch, path) {
+    return {
+        category: "KB_MISSING",
+        severity: "warning",
+        message: `Branch KB does not exist for '${branch}'`,
+        suggestion: `Run 'kibi sync' to create the KB at ${path}`,
+    };
+}
+/**
+ * Create DOCS_NOT_INDEXED diagnostic
+ */
+export function createDocsNotIndexedDiagnostic(docCount, entityCount) {
+    return {
+        category: "DOCS_NOT_INDEXED",
+        severity: "warning",
+        message: `${docCount} markdown files found but only ${entityCount} entities in KB`,
+        suggestion: "Some documents may have extraction errors. Run 'kibi sync --validate-only' to check.",
+    };
+}
+/**
+ * Create INVALID_AUTHORING diagnostic for embedded entities
+ */
+export function createInvalidAuthoringDiagnostic(filePath, embeddedTypes) {
+    return {
+        category: "INVALID_AUTHORING",
+        severity: "error",
+        message: `Requirement contains embedded ${embeddedTypes.join(" and ")} fields`,
+        file: filePath,
+        suggestion: `Move ${embeddedTypes.join(" and ")} to separate entity files and link them using 'links' with relationship types like 'specified_by' or 'verified_by'.`,
+    };
+}
+/**
+ * Format sync summary for CLI output
+ */
+export function formatSyncSummary(summary) {
+    const lines = [];
+    lines.push("═══ Sync Summary ═══");
+    lines.push(`Branch: ${summary.branch}`);
+    if (summary.commit) {
+        lines.push(`Commit: ${summary.commit.slice(0, 8)}`);
+    }
+    lines.push(`Timestamp: ${summary.timestamp}`);
+    lines.push("");
+    // Entity counts by type
+    lines.push("Entity Counts:");
+    const sortedTypes = Object.keys(summary.entityCounts).sort();
+    if (sortedTypes.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        for (const type of sortedTypes) {
+            lines.push(`  ${type}: ${summary.entityCounts[type]}`);
+        }
+    }
+    lines.push(`Total Relationships: ${summary.relationshipCount}`);
+    lines.push("");
+    // Status
+    lines.push(`Status: ${summary.success ? "✓ Success" : "✗ Failed"}`);
+    lines.push(`Published: ${summary.published ? "Yes" : "No"}`);
+    if (summary.durationMs !== undefined) {
+        lines.push(`Duration: ${summary.durationMs}ms`);
+    }
+    // Failures
+    if (summary.failures.length > 0) {
+        lines.push("");
+        lines.push(`Failures (${summary.failures.length}):`);
+        for (const failure of summary.failures) {
+            lines.push(`  [${failure.category}] ${failure.severity.toUpperCase()}: ${failure.message}`);
+            if (failure.file) {
+                lines.push(`    File: ${failure.file}`);
+            }
+            if (failure.suggestion) {
+                lines.push(`    Suggestion: ${failure.suggestion}`);
+            }
+        }
+    }
+    lines.push("═══ End Summary ═══");
+    return lines.join("\n");
+}
+/**
+ * Format diagnostics for MCP structured response
+ */
+export function formatDiagnosticsForMcp(diagnostics) {
+    return diagnostics.map((d) => ({
+        category: d.category,
+        severity: d.severity,
+        message: d.message,
+        file: d.file,
+        suggestion: d.suggestion,
+    }));
+}

package/dist/extractors/markdown.d.ts

@@ -34,6 +34,7 @@ export declare class FrontmatterError extends Error {
     });
     toString(): string;
 }
+export declare function detectEmbeddedEntities(data: Record<string, unknown>, entityType: string): string[];
 export declare function extractFromMarkdown(filePath: string): ExtractionResult;
 export declare function inferTypeFromPath(filePath: string): string | null;
 //# sourceMappingURL=markdown.d.ts.map

package/dist/extractors/markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASM,QAAQ;CAUlB;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAqHtE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE"}
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/extractors/markdown.ts"],"names":[],"mappings":"AAiDA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,qBAAqB,EAAE,CAAC;CACxC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAOhC,QAAQ,EAAE,MAAM;IANlB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;gBAG5B,OAAO,EAAE,MAAM,EACR,QAAQ,EAAE,MAAM,EACvB,OAAO,CAAC,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB;IASM,QAAQ;CAUlB;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CA8CV;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAkItE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASjE"}

package/dist/extractors/markdown.js

@@ -69,6 +69,45 @@ export class FrontmatterError extends Error {
         return msg;
     }
 }
+export function detectEmbeddedEntities(data, entityType) {
+    if (entityType !== "req") {
+        return [];
+    }
+    const detected = [];
+    const scenarioFields = ["scenarios", "given", "when", "then", "steps"];
+    for (const field of scenarioFields) {
+        if (field in data) {
+            const value = data[field];
+            if (value !== null &&
+                value !== undefined &&
+                (Array.isArray(value) ||
+                    typeof value === "object" ||
+                    typeof value === "string")) {
+                if (!detected.includes("scenario")) {
+                    detected.push("scenario");
+                }
+                break;
+            }
+        }
+    }
+    const testFields = ["tests", "testCases", "assertions", "testSteps"];
+    for (const field of testFields) {
+        if (field in data) {
+            const value = data[field];
+            if (value !== null &&
+                value !== undefined &&
+                (Array.isArray(value) ||
+                    typeof value === "object" ||
+                    typeof value === "string")) {
+                if (!detected.includes("test")) {
+                    detected.push("test");
+                }
+                break;
+            }
+        }
+    }
+    return detected;
+}
 export function extractFromMarkdown(filePath) {
     let content;
     try {
@@ -101,6 +140,14 @@ export function extractFromMarkdown(filePath) {
                 hint: "Add a 'title: ...' field to the YAML frontmatter.",
             });
         }
+        const embeddedEntities = detectEmbeddedEntities(data, type);
+        if (embeddedEntities.length > 0) {
+            const entityTypes = embeddedEntities.join(" and ");
+            throw new FrontmatterError(`Invalid embedded entity: requirement contains ${entityTypes} fields`, filePath, {
+                classification: "Embedded Entity Violation",
+                hint: `Move ${entityTypes} to separate entity files and link them using 'links' with relationship types like 'specified_by' or 'verified_by'.`,
+            });
+        }
         const id = data.id || generateId(filePath, data.title);
         const relationships = extractRelationships(data.links || [], id);
         return {

package/dist/prolog.d.ts

@@ -15,6 +15,7 @@ export declare class PrologProcess {
     private outputBuffer;
     private errorBuffer;
     private cache;
+    private interactiveQueryTail;
     private useOneShotMode;
     private attachedKbPath;
     private onProcessExit;

package/dist/prolog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"AAuDA,wBAAgB,eAAe,IAAI,MAAM,CAsCxC;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,cAAc,CACyC;IAC/D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IAKjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAoCd,YAAY;IAyCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAsH1D,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;YAYT,YAAY;IA0B1B,OAAO,CAAC,WAAW;IA8EnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,cAAc;IA8BtB,SAAS,IAAI,OAAO;IAIpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBjC"}
+{"version":3,"file":"prolog.d.ts","sourceRoot":"","sources":["../src/prolog.ts"],"names":[],"mappings":"AAuDA,wBAAgB,eAAe,IAAI,MAAM,CAsCxC;AACD,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,oBAAoB,CAAoC;IAChE,OAAO,CAAC,cAAc,CACyC;IAC/D,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,aAAa,CAA6B;gBAEtC,OAAO,GAAE,aAAkB;IAKjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAoCd,YAAY;IAyCpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA8I1D,eAAe,IAAI,IAAI;IAIvB,OAAO,CAAC,eAAe;YAYT,YAAY;IA0B1B,OAAO,CAAC,WAAW;IA8EnB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,eAAe;IAevB,OAAO,CAAC,cAAc;IA8BtB,SAAS,IAAI,OAAO;IAIpB,MAAM,IAAI,MAAM;IAIV,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBjC"}

package/dist/prolog.js

@@ -85,6 +85,7 @@ export class PrologProcess {
     outputBuffer = "";
     errorBuffer = "";
     cache = new Map();
+    interactiveQueryTail = Promise.resolve();
     useOneShotMode = typeof globalThis.Bun !== "undefined";
     attachedKbPath = null;
     onProcessExit = null;
@@ -174,78 +175,92 @@ export class PrologProcess {
         if (!this.process || !this.process.stdin) {
             throw new Error("Prolog process not started");
         }
-        this.outputBuffer = "";
-        this.errorBuffer = "";
-        this.process.stdin.write(`${goal}.
-`);
-        const debug = !!process.env.KIBI_PROLOG_DEBUG;
-        const normalizedGoal = isSingleGoal
-            ? this.normalizeGoal(goal)
-            : undefined;
-        const start = Date.now();
-        if (debug && normalizedGoal)
-            console.error(`[prolog debug] start query: ${normalizedGoal}`);
-        return new Promise((resolve, reject) => {
-            const timeoutId = setTimeout(() => {
-                const msg = `Query timeout after ${this.timeout / 1000}s`;
-                if (debug) {
-                    const tailOut = this.outputBuffer.slice(-2048);
-                    const tailErr = this.errorBuffer.slice(-2048);
-                    console.error(`[prolog debug] timeout: ${msg}`);
-                    console.error(`[prolog debug] last stdout: ---\n${tailOut}\n---`);
-                    console.error(`[prolog debug] last stderr: ---\n${tailErr}\n---`);
-                }
-                reject(new Error(msg));
-            }, this.timeout);
-            const checkResult = () => {
-                if (this.errorBuffer.length > 0 && this.errorBuffer.includes("ERROR")) {
-                    clearTimeout(timeoutId);
-                    if (debug && normalizedGoal)
-                        console.error(`[prolog debug] query error: ${normalizedGoal} error=${this.errorBuffer.split("\n")[0]}`);
-                    resolve({
-                        success: false,
-                        bindings: {},
-                        error: this.translateError(this.errorBuffer),
-                    });
-                }
-                else if (this.outputBuffer.includes("true.") ||
-                    this.outputBuffer.match(/^[A-Z_][A-Za-z0-9_]*\s*=\s*.+\./m) ||
-                    // Match multi-line output ending with ] (Prolog list/term output without trailing period)
-                    this.outputBuffer.match(/\]\s*$/m)) {
-                    clearTimeout(timeoutId);
-                    const result = {
-                        success: true,
-                        bindings: this.extractBindings(this.outputBuffer),
-                    };
-                    if (cacheable) {
-                        this.cache.set(goalKey, result);
+        const runInteractiveQuery = async () => {
+            this.outputBuffer = "";
+            this.errorBuffer = "";
+            const debug = !!process.env.KIBI_PROLOG_DEBUG;
+            const normalizedGoal = this.normalizeGoal(goal);
+            const wrappedGoal = /^once\s*\(/.test(normalizedGoal)
+                ? normalizedGoal
+                : `once((${normalizedGoal}))`;
+            const start = Date.now();
+            if (debug) {
+                console.error(`[prolog debug] start query: ${normalizedGoal}`);
+            }
+            this.process?.stdin?.write(`${wrappedGoal}.\n`);
+            return new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(() => {
+                    const msg = `Query timeout after ${this.timeout / 1000}s (pid=${this.process?.pid ?? 0}, killed=${this.process?.killed ? "yes" : "no"}, exitCode=${this.process?.exitCode ?? "null"}, goal=${JSON.stringify(normalizedGoal.slice(0, 120))})`;
+                    if (debug) {
+                        const tailOut = this.outputBuffer.slice(-2048);
+                        const tailErr = this.errorBuffer.slice(-2048);
+                        console.error(`[prolog debug] timeout: ${msg}`);
+                        console.error(`[prolog debug] last stdout: ---\n${tailOut}\n---`);
+                        console.error(`[prolog debug] last stderr: ---\n${tailErr}\n---`);
+                    }
+                    reject(new Error(msg));
+                }, this.timeout);
+                const checkResult = () => {
+                    if (this.errorBuffer.length > 0 &&
+                        this.errorBuffer.includes("ERROR")) {
+                        clearTimeout(timeoutId);
+                        if (debug) {
+                            console.error(`[prolog debug] query error: ${normalizedGoal} error=${this.errorBuffer.split("\n")[0]}`);
+                        }
+                        resolve({
+                            success: false,
+                            bindings: {},
+                            error: this.translateError(this.errorBuffer),
+                        });
+                        return;
                     }
-                    if (debug && normalizedGoal) {
-                        console.error(`[prolog debug] query success: ${normalizedGoal} elapsed=${(Date.now() - start) / 1000}s`);
+                    if (this.outputBuffer.includes("true.") ||
+                        this.outputBuffer.match(/^[A-Z_][A-Za-z0-9_]*\s*=\s*.+\./m) ||
+                        this.outputBuffer.match(/\]\s*$/m)) {
+                        clearTimeout(timeoutId);
+                        const result = {
+                            success: true,
+                            bindings: this.extractBindings(this.outputBuffer),
+                        };
+                        if (cacheable) {
+                            this.cache.set(goalKey, result);
+                        }
+                        if (debug) {
+                            console.error(`[prolog debug] query success: ${normalizedGoal} elapsed=${(Date.now() - start) / 1000}s`);
+                        }
+                        resolve(result);
+                        return;
                     }
-                    resolve(result);
-                    // Send newline to exit Prolog's interactive prompt
-                    if (this.process?.stdin) {
-                        this.process.stdin.write("\n");
+                    if (this.outputBuffer.includes("false.") ||
+                        this.outputBuffer.includes("fail.")) {
+                        clearTimeout(timeoutId);
+                        if (debug) {
+                            console.error(`[prolog debug] query failed (false): ${normalizedGoal}`);
+                        }
+                        resolve({
+                            success: false,
+                            bindings: {},
+                            error: "Query failed",
+                        });
+                        return;
                     }
-                }
-                else if (this.outputBuffer.includes("false.") ||
-                    this.outputBuffer.includes("fail.")) {
-                    clearTimeout(timeoutId);
-                    if (debug && normalizedGoal)
-                        console.error(`[prolog debug] query failed (false): ${normalizedGoal}`);
-                    resolve({
-                        success: false,
-                        bindings: {},
-                        error: "Query failed",
-                    });
-                }
-                else {
                     setTimeout(checkResult, 50);
-                }
-            };
-            checkResult();
+                };
+                checkResult();
+            });
+        };
+        const previousQuery = this.interactiveQueryTail;
+        let releaseQuery;
+        this.interactiveQueryTail = new Promise((resolve) => {
+            releaseQuery = resolve;
         });
+        await previousQuery;
+        try {
+            return await runInteractiveQuery();
+        }
+        finally {
+            releaseQuery();
+        }
     }
     invalidateCache() {
         this.cache.clear();

package/dist/public/branch-resolver.d.ts

@@ -0,0 +1,2 @@
+export * from "../utils/branch-resolver.js";
+//# sourceMappingURL=branch-resolver.d.ts.map

package/dist/public/branch-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/public/branch-resolver.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC"}

package/dist/public/branch-resolver.js

@@ -0,0 +1 @@
+export * from "../utils/branch-resolver.js";

package/dist/traceability/git-staged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAS5C;AAoBD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAoBb;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAmF7C;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"git-staged.d.ts","sourceRoot":"","sources":["../../src/traceability/git-staged.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,MAAM,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAS5C;AA8BD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,UAAQ,GAChB,SAAS,EAAE,CAoBb;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,EAAE,CAmF7C;AAED,eAAe,cAAc,CAAC"}

package/dist/traceability/git-staged.js

@@ -6,7 +6,7 @@ function runGit(cmd) {
     catch (err) {
         // wrap common errors
         const e = err;
-        const message = e && e.message ? String(e.message) : String(err);
+        const message = e?.message ? String(e.message) : String(err);
         throw new Error(`git command failed: ${cmd} -> ${message}`);
     }
 }
@@ -34,6 +34,7 @@ const SUPPORTED_EXT = new Set([
     ".mjs",
     ".cjs",
 ]);
+const ENTITY_MARKDOWN_DIRS = ["/requirements/", "/scenarios/", "/tests/"];
 function hasSupportedExt(p) {
     for (const ext of SUPPORTED_EXT) {
         if (p.endsWith(ext))
@@ -41,6 +42,15 @@ function hasSupportedExt(p) {
     }
     return false;
 }
+function isEntityMarkdown(p) {
+    if (!p.endsWith(".md"))
+        return false;
+    for (const dir of ENTITY_MARKDOWN_DIRS) {
+        if (p.includes(dir))
+            return true;
+    }
+    return false;
+}
 /**
  * Parse unified diff hunks (new-file coordinates) from git diff output
  */
@@ -98,7 +108,7 @@ export function getStagedFiles() {
                 path = entry.parts[1];
             }
         }
-        if (!hasSupportedExt(path)) {
+        if (!hasSupportedExt(path) && !isEntityMarkdown(path)) {
             console.debug(`Skipping unsupported extension: ${path}`);
             continue;
         }
@@ -123,7 +133,7 @@ export function getStagedFiles() {
         catch (err) {
             // binary or deleted in index
             const e = err;
-            const em = e && e.message ? String(e.message) : String(err);
+            const em = e?.message ? String(e.message) : String(err);
             console.debug(`Skipping binary/deleted or unreadable staged file ${path}: ${em}`);
             continue;
         }

package/dist/traceability/markdown-validate.d.ts

@@ -0,0 +1,7 @@
+import { FrontmatterError } from "../extractors/markdown.js";
+export interface MarkdownValidationResult {
+    filePath: string;
+    errors: FrontmatterError[];
+}
+export declare function validateStagedMarkdown(filePath: string, content: string): MarkdownValidationResult;
+//# sourceMappingURL=markdown-validate.d.ts.map

package/dist/traceability/markdown-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-validate.d.ts","sourceRoot":"","sources":["../../src/traceability/markdown-validate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,gBAAgB,EAEjB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,wBAAwB,CAgC1B"}

package/dist/traceability/markdown-validate.js

@@ -0,0 +1,35 @@
+import matter from "gray-matter";
+import { FrontmatterError, detectEmbeddedEntities, } from "../extractors/markdown.js";
+export function validateStagedMarkdown(filePath, content) {
+    const errors = [];
+    try {
+        const { data } = matter(content);
+        const type = data.type || inferTypeFromPath(filePath);
+        if (!type) {
+            return { filePath, errors };
+        }
+        const embeddedEntities = detectEmbeddedEntities(data, type);
+        if (embeddedEntities.length > 0) {
+            const entityTypes = embeddedEntities.join(" and ");
+            errors.push(new FrontmatterError(`Invalid embedded entity: requirement contains ${entityTypes} fields`, filePath, {
+                classification: "Embedded Entity Violation",
+                hint: `Move ${entityTypes} to separate entity files and link them using 'links' with relationship types like 'specified_by' or 'verified_by'.`,
+            }));
+        }
+    }
+    catch (error) {
+        if (error instanceof FrontmatterError) {
+            errors.push(error);
+        }
+    }
+    return { filePath, errors };
+}
+function inferTypeFromPath(filePath) {
+    if (filePath.includes("/requirements/"))
+        return "req";
+    if (filePath.includes("/scenarios/"))
+        return "scenario";
+    if (filePath.includes("/tests/"))
+        return "test";
+    return null;
+}

package/dist/utils/branch-resolver.d.ts

@@ -0,0 +1,79 @@
+export type BranchResolutionSuccess = {
+    branch: string;
+};
+export type BranchResolutionError = {
+    error: string;
+    code: BranchErrorCode;
+};
+export type BranchResolutionResult = BranchResolutionSuccess | BranchResolutionError;
+export type BranchErrorCode = "ENV_OVERRIDE" | "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "UNKNOWN_ERROR";
+/**
+ * Resolve the active branch according to ADR-012 precedence:
+ * 1. KIBI_BRANCH env var (if set)
+ * 2. Git active branch (from git branch --show-current)
+ * 3. Diagnostic failure (no silent fallback)
+ *
+ * @param workspaceRoot - The workspace root directory
+ * @returns BranchResolutionResult with either the branch name or an error
+ */
+export declare function resolveActiveBranch(workspaceRoot?: string): BranchResolutionResult;
+/**
+ * Check if the repository is in detached HEAD state.
+ *
+ * @param workspaceRoot - The workspace root directory
+ * @returns true if in detached HEAD, false otherwise
+ */
+export declare function isDetachedHead(workspaceRoot?: string): boolean;
+/**
+ * Get a detailed diagnostic message for branch resolution failures.
+ *
+ * @param branch - The branch that was detected (if any)
+ * @param error - The error message or context
+ * @returns A formatted diagnostic message
+ */
+export declare function getBranchDiagnostic(branch: string | undefined, error: string): string;
+/**
+ * Validate a branch name for safety and correctness.
+ *
+ * @param name - The branch name to validate
+ * @returns true if valid, false otherwise
+ */
+export declare function isValidBranchName(name: string): boolean;
+/**
+ * Copy a clean snapshot from source branch to target branch, excluding
+ * volatile artifacts like sync-cache.json, lock files, and journal files.
+ *
+ * @param sourcePath - Path to the source branch KB directory
+ * @param targetPath - Path to the target branch KB directory
+ * @throws Error if the copy fails
+ */
+export declare function copyCleanSnapshot(sourcePath: string, targetPath: string): void;
+/**
+ * Get the list of files that would be excluded from a clean snapshot copy.
+ * Useful for debugging and testing.
+ *
+ * @returns Array of volatile artifact patterns
+ */
+export declare function getVolatileArtifactPatterns(): string[];
+/**
+ * Resolve the default branch using the following precedence:
+ * 1. Configured defaultBranch from config (if set and valid)
+ * 2. Git remote HEAD (refs/remotes/origin/HEAD)
+ * 3. Fallback to "main"
+ *
+ * Unlike resolveActiveBranch, this does NOT normalize branch names.
+ * Configured names are returned verbatim.
+ *
+ * @param cwd - The working directory to resolve the default branch
+ * @param config - Optional config with defaultBranch
+ * @returns BranchResolutionResult with either the branch name or an error
+ */
+export declare function resolveDefaultBranch(cwd?: string, config?: {
+    defaultBranch?: string;
+}): {
+    branch: string;
+} | {
+    error: string;
+    code: string;
+};
+//# sourceMappingURL=branch-resolver.d.ts.map

package/dist/utils/branch-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"AA4BA,MAAM,MAAM,uBAAuB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,CAAC;AA8BpB;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,GAAE,MAAsB,GACpC,sBAAsB,CAmHxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,GAAE,MAAsB,GAAG,OAAO,CAa7E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CAUN;AA6BD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAMtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,EAC3B,MAAM,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqCtD"}