kibi-mcp 0.2.4 → 0.3.1

package/dist/tools/check.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
@@ -90,6 +63,9 @@ export async function handleKbCheck(prolog, args) {
             "no-cycles",
             "required-fields",
             "symbol-coverage",
+            "symbol-traceability",
+            "deprecated-adr-no-successor",
+            "domain-contradictions",
         ];
         const rulesToRun = rules && rules.length > 0 ? rules : allRules;
         const rulesAllowlist = new Set(rulesToRun);
@@ -137,6 +113,9 @@ export async function handleKbCheck(prolog, args) {
         if (rulesToRun.includes("symbol-coverage")) {
             violations.push(...(await checkSymbolCoverage(prolog)));
         }
+        if (rulesToRun.includes("symbol-traceability")) {
+            violations.push(...(await checkSymbolTraceability(prolog, false)));
+        }
         const diagnostics = violations.map((v) => ({
             category: "SYNC_ERROR",
             severity: "error",
@@ -232,6 +211,32 @@ async function runAggregatedChecks(prolog, rulesAllowlist) {
     }
     return violations;
 }
+async function checkSymbolTraceability(prolog, requireAdr) {
+    const violations = [];
+    const requireAdrStr = requireAdr ? "true" : "false";
+    const result = await prolog.query(`findall(violation(Rule, EntityId, Desc, Sugg, Src), checks:symbol_traceability_violation(${requireAdrStr}, violation(Rule, EntityId, Desc, Sugg, Src)), Violations)`);
+    if (!result.success || !result.bindings.Violations) {
+        return violations;
+    }
+    const violationsStr = result.bindings.Violations;
+    if (violationsStr && violationsStr !== "[]") {
+        const violationRegex = /violation\(([^,]+),'?([^',]+)'?,([^,]+),([^,]+),'?([^']*)'?\)/g;
+        let match;
+        do {
+            match = violationRegex.exec(violationsStr);
+            if (match) {
+                violations.push({
+                    rule: match[1].trim().replace(/^'|'$/g, ""),
+                    entityId: match[2].trim(),
+                    description: match[3].trim().replace(/^"|"$/g, ""),
+                    suggestion: match[4].trim().replace(/^"|"$/g, ""),
+                    source: match[5].trim() || undefined,
+                });
+            }
+        } while (match);
+    }
+    return violations;
+}
 async function checkMustPriorityCoverage(prolog) {
     const violations = [];
     const gapsResult = await prolog.query("setof([Req,Reason], coverage_gap(Req, Reason), Rows)");

package/dist/tools/delete.js

@@ -1,23 +1,4 @@
-/*
- Kibi — repo-local, per-branch, queryable long-term memory for software projects
- Copyright (C) 2026 Piotr Franczyk
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU Affero General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU Affero General Public License for more details.
-
- 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/>.
-*/
-function escapeAtom(value) {
-    return value.replace(/'/g, "''");
-}
+import { escapeAtom } from "kibi-cli/prolog/codec";
 /**
  * Handle kb.delete tool calls
  * Prevents deletion of entities with dependents (referential integrity)

package/dist/tools/prolog-list.js

@@ -15,33 +15,7 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
+// implements REQ-002
 export function parseAtomList(raw) {
     const trimmed = raw.trim();
     if (trimmed === "[]" || trimmed.length === 0) {
@@ -55,6 +29,7 @@ export function parseAtomList(raw) {
         .map((token) => stripQuotes(token.trim()))
         .filter((token) => token.length > 0);
 }
+// implements REQ-002
 export function parsePairList(raw) {
     const rows = parseListRows(raw);
     const pairs = [];
@@ -66,17 +41,6 @@ export function parsePairList(raw) {
     }
     return pairs;
 }
-export function parseTriples(raw) {
-    const rows = parseListRows(raw);
-    const triples = [];
-    for (const row of rows) {
-        const parts = splitTopLevel(row, ",").map((part) => stripQuotes(part.trim()));
-        if (parts.length >= 3) {
-            triples.push([parts[0], parts[1], parts[2]]);
-        }
-    }
-    return triples;
-}
 function parseListRows(raw) {
     const trimmed = raw.trim();
     if (trimmed === "[]" || trimmed.length === 0) {

package/dist/tools/query.js

@@ -1,27 +1,4 @@
-/*
- Kibi — repo-local, per-branch, queryable long-term memory for software projects
- Copyright (C) 2026 Piotr Franczyk
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU Affero General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU Affero General Public License for more details.
-
- 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/>.
-*/
-/**
- * Escape a string for embedding inside a single-quoted Prolog atom.
- * Doubles single-quote characters per ISO Prolog standard.
- */
-function escapeAtomContent(value) {
-    return value.replace(/'/g, "''");
-}
+import { escapeAtomContent, parseEntityFromBinding, parseEntityFromList, parseListOfLists, } from "kibi-cli/prolog/codec";
 export const VALID_ENTITY_TYPES = [
     "req",
     "scenario",
@@ -174,234 +151,3 @@ function dedupeEntities(entities) {
     }
     return deduped;
 }
-/**
- * Parse a Prolog list of lists into a JavaScript array.
- * Input: "[[a,b,c],[d,e,f]]"
- * Output: [["a", "b", "c"], ["d", "e", "f"]]
- */
-export function parseListOfLists(listStr) {
-    const cleaned = listStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    if (cleaned === "") {
-        return [];
-    }
-    const results = [];
-    let depth = 0;
-    let current = "";
-    let currentList = [];
-    for (let i = 0; i < cleaned.length; i++) {
-        const char = cleaned[i];
-        if (char === "[") {
-            depth++;
-            if (depth > 1)
-                current += char;
-        }
-        else if (char === "]") {
-            depth--;
-            if (depth === 0) {
-                if (current) {
-                    currentList.push(current.trim());
-                    current = "";
-                }
-                if (currentList.length > 0) {
-                    results.push(currentList);
-                    currentList = [];
-                }
-            }
-            else {
-                current += char;
-            }
-        }
-        else if (char === "," && depth === 1) {
-            if (current) {
-                currentList.push(current.trim());
-                current = "";
-            }
-        }
-        else if (char === "," && depth === 0) {
-            // Skip comma between lists
-        }
-        else {
-            current += char;
-        }
-    }
-    return results;
-}
-/**
- * Parse a single entity from Prolog binding format.
- * Input: "[abc123, req, [id=abc123, title=\"Test\", ...]]"
- */
-export function parseEntityFromBinding(bindingStr) {
-    const cleaned = bindingStr.trim().replace(/^\[/, "").replace(/\]$/, "");
-    const parts = splitTopLevel(cleaned, ",");
-    if (parts.length < 3) {
-        return {};
-    }
-    const id = parts[0].trim();
-    const type = parts[1].trim();
-    const propsStr = parts.slice(2).join(",").trim();
-    const props = parsePropertyList(propsStr);
-    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
-}
-/**
- * Parse entity from array returned by parseListOfLists.
- * Input: ["abc123", "req", "[id=abc123, title=\"Test\", ...]"]
- */
-export function parseEntityFromList(data) {
-    if (data.length < 3) {
-        return {};
-    }
-    const id = data[0].trim();
-    const type = data[1].trim();
-    const propsStr = data[2].trim();
-    const props = parsePropertyList(propsStr);
-    return { ...props, id: normalizeEntityId(stripOuterQuotes(id)), type };
-}
-/**
- * Parse Prolog property list into JavaScript object.
- */
-export function parsePropertyList(propsStr) {
-    const props = {};
-    let cleaned = propsStr.trim();
-    if (cleaned.startsWith("[")) {
-        cleaned = cleaned.substring(1);
-    }
-    if (cleaned.endsWith("]")) {
-        cleaned = cleaned.substring(0, cleaned.length - 1);
-    }
-    const pairs = splitTopLevel(cleaned, ",");
-    for (const pair of pairs) {
-        const eqIndex = pair.indexOf("=");
-        if (eqIndex === -1)
-            continue;
-        const key = pair.substring(0, eqIndex).trim();
-        const value = pair.substring(eqIndex + 1).trim();
-        if (key === "..." || value === "..." || value === "...|...") {
-            continue;
-        }
-        const parsed = parsePrologValue(value);
-        props[key] = parsed;
-    }
-    return props;
-}
-/**
- * Parse a single Prolog value, handling typed literals and URIs.
- */
-export function parsePrologValue(valueInput) {
-    const value = valueInput.trim();
-    // Handle typed literal: ^^("value", type)
-    if (value.startsWith("^^(")) {
-        const innerStart = value.indexOf("(") + 1;
-        let depth = 1;
-        let innerEnd = innerStart;
-        for (let i = innerStart; i < value.length; i++) {
-            if (value[i] === "(")
-                depth++;
-            if (value[i] === ")") {
-                depth--;
-                if (depth === 0) {
-                    innerEnd = i;
-                    break;
-                }
-            }
-        }
-        const innerContent = value.substring(innerStart, innerEnd);
-        const parts = splitTopLevel(innerContent, ",");
-        if (parts.length >= 2) {
-            let literalValue = parts[0].trim();
-            if (literalValue.startsWith('"') && literalValue.endsWith('"')) {
-                literalValue = literalValue.substring(1, literalValue.length - 1);
-            }
-            // Handle array notation
-            if (literalValue.startsWith("[") && literalValue.endsWith("]")) {
-                const listContent = literalValue.substring(1, literalValue.length - 1);
-                if (listContent === "") {
-                    return [];
-                }
-                return splitTopLevel(listContent, ",").map((item) => item.trim());
-            }
-            return literalValue;
-        }
-    }
-    // Handle URI
-    if (value.startsWith("file:///")) {
-        const lastSlash = value.lastIndexOf("/");
-        if (lastSlash !== -1) {
-            return value.substring(lastSlash + 1);
-        }
-        return value;
-    }
-    // Handle quoted string
-    if (value.startsWith('"') && value.endsWith('"')) {
-        return value.substring(1, value.length - 1);
-    }
-    // Handle quoted atom
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.substring(1, value.length - 1);
-    }
-    // Handle list
-    if (value.startsWith("[") && value.endsWith("]")) {
-        const listContent = value.substring(1, value.length - 1);
-        if (listContent === "") {
-            return [];
-        }
-        const items = splitTopLevel(listContent, ",").map((item) => {
-            return parsePrologValue(item.trim());
-        });
-        return items;
-    }
-    return value;
-}
-/**
- * Split a string by delimiter at the top level (not inside brackets or quotes).
- */
-export function splitTopLevel(str, delimiter) {
-    const results = [];
-    let current = "";
-    let depth = 0;
-    let inQuotes = false;
-    for (let i = 0; i < str.length; i++) {
-        const char = str[i];
-        const prevChar = i > 0 ? str[i - 1] : "";
-        if (char === '"' && prevChar !== "\\") {
-            inQuotes = !inQuotes;
-            current += char;
-        }
-        else if (!inQuotes && (char === "[" || char === "(")) {
-            depth++;
-            current += char;
-        }
-        else if (!inQuotes && (char === "]" || char === ")")) {
-            depth--;
-            current += char;
-        }
-        else if (!inQuotes && depth === 0 && char === delimiter) {
-            if (current) {
-                results.push(current);
-                current = "";
-            }
-        }
-        else {
-            current += char;
-        }
-    }
-    if (current) {
-        results.push(current);
-    }
-    return results;
-}
-function stripOuterQuotes(value) {
-    if (value.startsWith("'") && value.endsWith("'")) {
-        return value.slice(1, -1);
-    }
-    if (value.startsWith('"') && value.endsWith('"')) {
-        return value.slice(1, -1);
-    }
-    return value;
-}
-function normalizeEntityId(value) {
-    if (!value.startsWith("file:///")) {
-        return value;
-    }
-    const idx = value.lastIndexOf("/");
-    return idx === -1 ? value : value.slice(idx + 1);
-}

package/dist/tools/symbols.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";

package/dist/tools/upsert.js

@@ -16,18 +16,10 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import Ajv from "ajv";
+import { escapeAtom, toPrologAtom } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
-function escapeAtom(value) {
-    return value.replace(/'/g, "''");
-}
-function toPrologAtom(value) {
-    const simplePrologAtom = /^[a-z][a-zA-Z0-9_]*$/;
-    return simplePrologAtom.test(value)
-        ? value
-        : `'${value.replace(/'/g, "''")}'`;
-}
 const ajv = new Ajv({ strict: false });
 const validateEntity = ajv.compile(entitySchema);
 const validateRelationship = ajv.compile(relationshipSchema);
@@ -122,11 +114,17 @@ export async function handleKbUpsert(prolog, args) {
             }
             relationshipsCreated++;
         }
-        // Save KB to disk
+        // Note: kb_save is intentionally NOT called here for performance.
+        // Callers that need durability across restarts should explicitly call kb_save.
+        // This allows batching multiple upserts before a single disk write.
+        prolog.invalidateCache();
+        // Save KB to disk to ensure durability across process restarts
         await prolog.query("kb_save");
         prolog.invalidateCache();
+        // multiple upserts and save once at the end for better performance.
+        prolog.invalidateCache();
         let contradictionPairsDetected;
-        if (type === "req") {
+        if (type === "req" && !args._skipContradictionCheck) {
             contradictionPairsDetected = await detectContradictionPairs(prolog, id);
         }
         if (type === "symbol") {

package/dist/tools-config.js

@@ -15,37 +15,11 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 export const TOOLS = [
+    // implements REQ-002
     {
         name: "kb_query",
-        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects.",
+        description: "Read entities from the KB with filters. Use for discovery and lookup before edits. Do not use for writes. No mutation side effects. Tags filter by metadata tags only, not entity IDs.",
         inputSchema: {
             type: "object",
             properties: {
@@ -91,7 +65,7 @@ export const TOOLS = [
     },
     {
         name: "kb_upsert",
-        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`) so consistency and contradiction checks remain queryable. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
+        description: "Create or update one entity and optional relationships. Use for KB mutations after validating intent. Use the `relationships` array for batch creation of multiple links in a single call (e.g., linking a requirement to multiple tests or facts). Prefer modeling requirements as reusable fact links (`constrains`, `requires_property`) so consistency and contradiction checks remain queryable. Relationship endpoints must already exist in KB. Do not use for read-only inspection. Side effects: writes KB, may refresh symbol coordinates.",
         inputSchema: {
             type: "object",
             required: ["type", "id", "properties"],
@@ -124,18 +98,7 @@ export const TOOLS = [
                         },
                         status: {
                             type: "string",
-                            enum: [
-                                "active",
-                                "draft",
-                                "archived",
-                                "deleted",
-                                "approved",
-                                "rejected",
-                                "pending",
-                                "in_progress",
-                                "superseded",
-                            ],
-                            description: "Required lifecycle state. Allowed values are fixed enum options. Example: 'active'.",
+                            description: "Required lifecycle state. Allowed values depend on entity type; backward-compatible legacy statuses are also accepted. Examples: 'open', 'passing', 'accepted', 'active'.",
                         },
                         source: {
                             type: "string",
@@ -228,7 +191,7 @@ export const TOOLS = [
     },
     {
         name: "kb_check",
-        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects.",
+        description: "Run KB validation rules and return violations. Use before or after mutations. Do not use for point lookups. No write side effects. Prefer explicit rules for faster iteration.",
         inputSchema: {
             type: "object",
             properties: {
@@ -238,13 +201,16 @@ export const TOOLS = [
                         type: "string",
                         enum: [
                             "must-priority-coverage",
+                            "symbol-coverage",
+                            "symbol-traceability",
                             "no-dangling-refs",
                             "no-cycles",
                             "required-fields",
-                            "symbol-coverage",
+                            "deprecated-adr-no-successor",
+                            "domain-contradictions",
                         ],
                     },
-                    description: "Optional rule subset. Allowed: must-priority-coverage, no-dangling-refs, no-cycles, required-fields, symbol-coverage. If omitted, server runs all.",
+                    description: "Optional rule subset. Allowed: must-priority-coverage, symbol-coverage, symbol-traceability, no-dangling-refs, no-cycles, required-fields, deprecated-adr-no-successor, domain-contradictions. If omitted, server runs all.",
                 },
             },
         },

package/dist/workspace.js

@@ -15,33 +15,6 @@
  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/>.
 */
-/*
- How to apply this header to source files (examples)
-
- 1) Prepend header to a single file (POSIX shells):
-
-    cat LICENSE_HEADER.txt "$FILE" > "$FILE".with-header && mv "$FILE".with-header "$FILE"
-
- 2) Apply to multiple files (example: the project's main entry files):
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp packages/cli/src/*.ts packages/mcp/src/*.ts; do
-      if [ -f "$f" ]; then
-        cp "$f" "$f".bak
-        (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-      fi
-    done
-
- 3) Avoid duplicating the header: run a quick guard to only add if missing
-
-    for f in packages/cli/bin/kibi packages/mcp/bin/kibi-mcp; do
-      if [ -f "$f" ]; then
-        if ! head -n 5 "$f" | grep -q "Copyright (C) 2026 Piotr Franczyk"; then
-          cp "$f" "$f".bak
-          (cat LICENSE_HEADER.txt; echo; cat "$f" ) > "$f".new && mv "$f".new "$f"
-        fi
-      fi
-    done
-*/
 import fs from "node:fs";
 import path from "node:path";
 const WORKSPACE_ENV_KEYS = [
@@ -50,6 +23,7 @@ const WORKSPACE_ENV_KEYS = [
     "KIBI_ROOT",
 ];
 const KB_PATH_ENV_KEYS = ["KIBI_KB_PATH", "KB_PATH"];
+// implements REQ-002, REQ-012
 export function resolveWorkspaceRoot(startDir = process.cwd()) {
     const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
     if (envRoot) {
@@ -65,21 +39,7 @@ export function resolveWorkspaceRoot(startDir = process.cwd()) {
     }
     return path.resolve(startDir);
 }
-export function resolveWorkspaceRootInfo(startDir = process.cwd()) {
-    const envRoot = readFirstEnv(WORKSPACE_ENV_KEYS);
-    if (envRoot) {
-        return { root: path.resolve(envRoot), reason: "env" };
-    }
-    const kbRoot = findUpwards(startDir, ".kb");
-    if (kbRoot) {
-        return { root: kbRoot, reason: "kb" };
-    }
-    const gitRoot = findUpwards(startDir, ".git");
-    if (gitRoot) {
-        return { root: gitRoot, reason: "git" };
-    }
-    return { root: path.resolve(startDir), reason: "cwd" };
-}
+// implements REQ-002, REQ-012
 export function resolveKbPath(workspaceRoot, branch) {
     const envPath = readFirstEnv(KB_PATH_ENV_KEYS);
     if (envPath) {
@@ -91,6 +51,7 @@ export function resolveKbPath(workspaceRoot, branch) {
     }
     return path.join(workspaceRoot, ".kb", "branches", branch);
 }
+// implements REQ-002
 export function resolveEnvFilePath(envFileName, workspaceRoot) {
     if (path.isAbsolute(envFileName)) {
         return envFileName;