kibi-cli 2.28.0 → 2.29.0

package/dist/prolog/store-lock.js

@@ -15,6 +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/>.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
@@ -61,6 +62,52 @@ export function isProcessAlive(pid) {
         return code === "EPERM";
     }
 }
+function processInfo(pid) {
+    try {
+        if (process.platform === "linux") {
+            // `comm` is in parentheses; the fields after it are state, ppid, ...
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const open = stat.indexOf("(");
+            const close = stat.lastIndexOf(")");
+            return {
+                command: stat.slice(open + 1, close),
+                parent: Number(stat.slice(close + 2).split(" ")[1]),
+            };
+        }
+        if (process.platform === "win32")
+            return null;
+        const [parent, ...command] = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 })
+            .trim()
+            .split(/\s+/);
+        return { parent: Number(parent), command: basename(command.join(" ")) };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The process to stop for a store lock holder. The lock records the engine's
+ * SWI-Prolog child; its parent (the daemon, or another Kibi process hosting
+ * the session) is what a user ends or stops.
+ */
+// implements REQ-core-journaled-engine-persistence
+export function lockHolderProcess(pid) {
+    const info = processInfo(pid);
+    if (info === null ||
+        !/^swipl/.test(info.command) ||
+        !Number.isInteger(info.parent) ||
+        info.parent <= 1)
+        return { pid };
+    return { pid: info.parent, prologPid: pid };
+}
+/** "pid N", naming the owning Kibi process when N is its SWI-Prolog child. */
+// implements REQ-core-journaled-engine-persistence
+export function describeLockHolderPid(pid) {
+    const holder = lockHolderProcess(pid);
+    return holder.prologPid === undefined
+        ? `pid ${holder.pid}`
+        : `pid ${holder.pid} (through its SWI-Prolog process, pid ${holder.prologPid})`;
+}
 export function classifyStoreLockHolder(owner) {
     if (owner === null || typeof owner.pid !== "number")
         return "unknown";
@@ -356,7 +403,7 @@ export async function retryAttachAfterBreakingStaleLock(prolog, kbPath, failed)
     if (decision.action !== "break") {
         const holderSummary = storeLocked.owner === null
             ? decision.reason
-            : `pid ${storeLocked.owner.pid ?? "?"} (${decision.reason})`;
+            : `${storeLocked.owner.pid === undefined ? "pid ?" : describeLockHolderPid(storeLocked.owner.pid)} (${decision.reason})`;
         return {
             ...failed,
             error: `${failed.error}

package/dist/traceability/commit-amend.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the commit being made replaces a root commit (`git commit --amend`
+ * on a branch with one commit). Such a commit has no parent either, so the
+ * staged gate treats it as a first commit.
+ */
+export declare function amendsRootCommit(workspaceRoot: string, headCommit: string | null): boolean;
+//# sourceMappingURL=commit-amend.d.ts.map

package/dist/traceability/commit-amend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-amend.d.ts","sourceRoot":"","sources":["../../src/traceability/commit-amend.ts"],"names":[],"mappings":"AAsEA;;;;GAIG;AAEH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAmBT"}

package/dist/traceability/commit-amend.js

@@ -0,0 +1,85 @@
+/*
+ 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/>.
+*/
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+/** How far up the process tree to look for the `git commit` running a hook. */
+const MAX_ANCESTORS = 8;
+function processArguments(pid) {
+    try {
+        if (process.platform === "linux") {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const parent = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+            const argv = readFileSync(`/proc/${pid}/cmdline`, "utf8")
+                .split("\0")
+                .filter(Boolean);
+            return { parent, argv };
+        }
+        if (process.platform === "win32")
+            return null;
+        const [parent, ...argv] = execFileSync("ps", ["-o", "ppid=,args=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 2000 })
+            .trim()
+            .split(/\s+/);
+        return { parent: Number(parent), argv };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether this process runs under `git commit --amend`. Git does not tell a
+ * pre-commit hook that it is amending, so the hook's ancestors are read.
+ */
+function runsUnderCommitAmend() {
+    let pid = process.ppid;
+    for (let depth = 0; depth < MAX_ANCESTORS && pid > 1; depth += 1) {
+        const info = processArguments(pid);
+        if (info === null)
+            return false;
+        const [program, ...rest] = info.argv;
+        if (program !== undefined && /^git(\.exe)?$/.test(basename(program)))
+            return rest.includes("commit") && rest.includes("--amend");
+        pid = info.parent;
+    }
+    return false;
+}
+/**
+ * Whether the commit being made replaces a root commit (`git commit --amend`
+ * on a branch with one commit). Such a commit has no parent either, so the
+ * staged gate treats it as a first commit.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export function amendsRootCommit(workspaceRoot, headCommit) {
+    if (headCommit === null)
+        return false;
+    try {
+        const parents = execFileSync("git", ["rev-list", "--parents", "-n", "1", headCommit], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .trim()
+            .split(/\s+/);
+        if (parents.length > 1)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return runsUnderCommitAmend();
+}

package/dist/traceability/staged-inventory-drift.d.ts

@@ -13,12 +13,22 @@ export type StagedInventoryDriftViolation = Readonly<{
  * or in the base tree) whose inventory no longer matches their prose. The
  * next `kibi sync` refuses them under the proposition-complete boundary;
  * the gate applies the same test, so drift is caught at the commit that
- * introduces it instead of after a later merge. Requirements without a
- * contract are left to sync, which decides from its own baseline.
+ * introduces it instead of after a later merge. A requirement the base tree
+ * does not have yet is judged too, as sync judges a source it has never
+ * imported, unless the commit has no parent (a first commit, which sync
+ * imports as its semantic baseline). So is one whose statement (the prose
+ * its inventory covers) differs from the base tree's, as sync judges a
+ * source whose semantic hash changed. Other requirements without a contract,
+ * such as a Context-only edit, are left to sync's baseline.
  */
 export declare function stagedInventoryDriftViolations(input: {
     stagedPaths: ReadonlySet<string>;
     snapshotEntities: readonly ExtractionResult[];
     readBase: (path: string) => string | null;
+    /**
+     * False for a first commit, or an amend of it: sync grandfathers its sources
+     * as a baseline, so only declared contracts are judged.
+     */
+    judgeNewRequirements?: boolean;
 }): StagedInventoryDriftViolation[];
 //# sourceMappingURL=staged-inventory-drift.d.ts.map

package/dist/traceability/staged-inventory-drift.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-inventory-drift.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-inventory-drift.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,iFAAiF;AAEjF,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,OAAO,2BAA2B,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC;AAgCH;;;;;;;GAOG;AAEH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3C,GAAG,6BAA6B,EAAE,CA8BlC"}
+{"version":3,"file":"staged-inventory-drift.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-inventory-drift.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAKlE,iFAAiF;AAEjF,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAGtE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,IAAI,EAAE,OAAO,2BAA2B,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC;AA0CH;;;;;;;;;;;;GAYG;AAEH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,GAAG,6BAA6B,EAAE,CAsClC"}

package/dist/traceability/staged-inventory-drift.js

@@ -34,6 +34,11 @@ function payloadOf(result) {
         relationships: result.relationships,
     };
 }
+/** The hash of the prose a requirement's inventory must cover. */
+function semanticSourceHashOf(result) {
+    const payload = payloadOf(result);
+    return validateSemanticInventoryBoundary(payload, result.relationships, analyzeSemanticAdvisorInput({ payload }).receipt).sourceHash;
+}
 function baseResult(path, readBase) {
     const content = readBase(path);
     if (content === null)
@@ -50,8 +55,13 @@ function baseResult(path, readBase) {
  * or in the base tree) whose inventory no longer matches their prose. The
  * next `kibi sync` refuses them under the proposition-complete boundary;
  * the gate applies the same test, so drift is caught at the commit that
- * introduces it instead of after a later merge. Requirements without a
- * contract are left to sync, which decides from its own baseline.
+ * introduces it instead of after a later merge. A requirement the base tree
+ * does not have yet is judged too, as sync judges a source it has never
+ * imported, unless the commit has no parent (a first commit, which sync
+ * imports as its semantic baseline). So is one whose statement (the prose
+ * its inventory covers) differs from the base tree's, as sync judges a
+ * source whose semantic hash changed. Other requirements without a contract,
+ * such as a Context-only edit, are left to sync's baseline.
  */
 // implements REQ-kibi-proposition-complete-ingestion
 export function stagedInventoryDriftViolations(input) {
@@ -68,16 +78,23 @@ export function stagedInventoryDriftViolations(input) {
         if (boundary.errors.length === 0)
             continue;
         const base = baseResult(source, input.readBase);
-        const enforce = advertisesContract(result.entity) ||
+        const contract = advertisesContract(result.entity) ||
             (base !== null && advertisesContract(base.entity));
-        if (!enforce)
+        const judgeUncontracted = input.judgeNewRequirements ?? true;
+        const isNew = input.readBase(source) === null && judgeUncontracted;
+        const restated = judgeUncontracted &&
+            base !== null &&
+            semanticSourceHashOf(base) !== boundary.sourceHash;
+        if (!contract && !isNew && !restated)
             continue;
         violations.push({
             rule: STAGED_INVENTORY_DRIFT_RULE,
             entityId: result.entity.id,
             source,
             errors: boundary.errors,
-            message: `${result.entity.id} (${source}): the semantic inventory does not match the requirement's prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run 'kibi migrate' to re-derive it, or kb_model mode analyze with the complete prose and keep its inventory contract.`,
+            message: contract
+                ? `${result.entity.id} (${source}): the semantic inventory does not match the requirement's prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run 'kibi migrate' to re-derive it, or kb_model mode analyze with the complete prose and keep its inventory contract.`
+                : `${result.entity.id} (${source}): ${isNew ? "a new requirement" : "a requirement whose statement changes"} needs a semantic inventory that matches its prose, so the next kibi sync rejects it: ${boundary.errors.join("; ")}. Run kb_model mode analyze (CLI: semantic-advisor) with its id and complete semantic_text, then write the returned inventory contract into it (kb_upsert with semantic_inventory, semantic_inventory_version, semantic_source_field, semantic_source_hash and logic_claims).`,
         });
     }
     return violations.sort((left, right) => left.entityId.localeCompare(right.entityId));

package/dist/utils/repo-relative-path.d.ts

@@ -15,4 +15,11 @@
  * (the workspace snapshot), the caller compares it in NFC.
  */
 export declare function normalizeRepoRelativePath(workspaceRoot: string, candidate: string): string | null;
+/**
+ * Resolve a recorded source path to an absolute path that is lexically (and,
+ * when the file exists, via realpath) confined under `workspaceRoot`.
+ * Returns null for escapes, empty input, or symlink targets outside the root.
+ * Callers must treat null as "do not read".
+ */
+export declare function resolveWorkspaceSourceAbsolute(workspaceRoot: string, sourceFile: string): string | null;
 //# sourceMappingURL=repo-relative-path.d.ts.map

package/dist/utils/repo-relative-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-relative-path.d.ts","sourceRoot":"","sources":["../../src/utils/repo-relative-path.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAsBf"}
+{"version":3,"file":"repo-relative-path.d.ts","sourceRoot":"","sources":["../../src/utils/repo-relative-path.ts"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;GAeG;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAsBf;AAED;;;;;GAKG;AAEH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAcf"}

package/dist/utils/repo-relative-path.js

@@ -15,6 +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/>.
  */
+import { realpathSync } from "node:fs";
 import path from "node:path";
 /**
  * Canonical repository-relative form of a recorded path, as proof freshness
@@ -56,3 +57,28 @@ export function normalizeRepoRelativePath(workspaceRoot, candidate) {
     }
     return normalized;
 }
+/**
+ * Resolve a recorded source path to an absolute path that is lexically (and,
+ * when the file exists, via realpath) confined under `workspaceRoot`.
+ * Returns null for escapes, empty input, or symlink targets outside the root.
+ * Callers must treat null as "do not read".
+ */
+// implements REQ-symbol-sourcefile-workspace-confinement
+export function resolveWorkspaceSourceAbsolute(workspaceRoot, sourceFile) {
+    const relative = normalizeRepoRelativePath(workspaceRoot, sourceFile);
+    if (relative === null)
+        return null;
+    const absolute = path.resolve(workspaceRoot, relative);
+    try {
+        const realRoot = realpathSync.native(path.resolve(workspaceRoot));
+        const realFile = realpathSync.native(absolute);
+        const confined = path.relative(realRoot, realFile);
+        if (confined.startsWith("..") || path.isAbsolute(confined))
+            return null;
+        return realFile;
+    }
+    catch {
+        // Missing path: lexical confinement from normalizeRepoRelativePath is enough.
+        return absolute;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {
@@ -235,13 +235,13 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-core": "^0.22.3",
-    "kibi-plugin-builtin": "^0.5.2",
+    "kibi-core": "^0.22.4",
+    "kibi-plugin-builtin": "^0.5.3",
     "kibi-plugin-sdk": "^0.5.0",
     "kibi-swipl": "^1.0.1",
     "saxes": "^6.0.0",
     "ignore": "^5.3.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "latest",

package/schema/entities.pl

@@ -29,7 +29,8 @@ entity_property(_, priority, atom).
 entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
-entity_property(_, sourceFile, uri).
+% Workspace-relative source paths only (no absolute / .. escapes).
+entity_property(_, sourceFile, workspace_relpath).
 % Provenance of any authored entity: a JSON object (kind, ref, approved_by,
 % recorded_at) naming who authored it and on what authority.
 entity_property(_, origin, list_or_json).

package/schema/validation.pl

@@ -50,11 +50,26 @@ check_kind(datetime, V) :- string(V). % accept ISO strings for now
 check_kind(list, V) :- is_list(V).
 check_kind(list_or_json, V) :- is_list(V) ; string(V) ; atom(V).
 check_kind(uri, V) :- string(V).
+% Non-empty workspace-relative path: reject absolute forms and `..` segments.
+check_kind(workspace_relpath, V) :-
+    string(V),
+    string_length(V, Len),
+    Len > 0,
+    \+ workspace_relpath_absolute(V),
+    split_string(V, "/\\", "", Parts),
+    \+ member("..", Parts).
 check_kind(integer, V) :- integer(V).
 check_kind(number, V) :- number(V).
 check_kind(boolean, true).
 check_kind(boolean, false).
 
+workspace_relpath_absolute(V) :- sub_string(V, 0, 1, _, "/").
+workspace_relpath_absolute(V) :-
+    string_length(V, Len),
+    Len >= 2,
+    sub_string(V, 1, 1, _, ":").
+workspace_relpath_absolute(V) :- sub_string(V, 0, 2, _, "\\\\").
+
 % Fallback false
 check_kind(_, _) :- fail.