kibi-cli 2.1.0 → 2.3.0

package/dist/traceability/temp-kb.js

@@ -107,6 +107,14 @@ function serializeTypedFactFields(entity) {
     if (ruleIr !== undefined && ruleIr !== null) {
         fields.push(`rule_ir=${toPrologString(JSON.stringify(ruleIr))}`);
     }
+    // Predicate-schema vocabularies are objects; like rule_ir they travel as
+    // JSON strings and are decoded again at the public boundary.
+    for (const field of ["argument_constants", "argument_aliases"]) {
+        const value = getEntityField(entity, field);
+        if (value !== undefined && value !== null) {
+            fields.push(`${field}=${toPrologString(JSON.stringify(value))}`);
+        }
+    }
     for (const field of FACT_ATOM_FIELDS) {
         const value = getEntityField(entity, field);
         if (value !== undefined && value !== null) {
@@ -258,29 +266,62 @@ async function consultOverlay(ctx) {
     }
 }
 export { consultOverlay };
+const PROJECTION_BATCH_SIZE = 128;
+// implements REQ-014
+function contextualProjectionGoal(goal, context) {
+    const label = toPrologString(context);
+    // A failed goal must abort the transaction just like an exception. Keep the
+    // individual record in the error even when it belongs to a larger batch.
+    // Use the existing structured validation-error transport; unrecognized error
+    // terms can lose their record context during generic error classification.
+    return `catch((${goal} -> true ; throw(staged_goal_failed)), ProjectionError, (message_to_string(ProjectionError, ProjectionDetail), format(atom(ProjectionMessage), '~s: ~s', [${label}, ProjectionDetail]), throw(error(validation_error(ProjectionMessage), context(projectStagedEntities, ${label})))))`;
+}
 // implements REQ-014
 export async function projectStagedEntities(prolog, results) {
-    for (const { entity, sourceFile } of results) {
-        // Retract stale relationships before re-asserting entity
-        // (kb_assert_entity_no_audit preserves relationships on upsert)
-        await prolog.query(`kb_retract_entity_relationships('${entity.id}')`);
-        const assertEntityResult = await prolog.query(buildEntityAssertionGoal(entity, sourceFile));
-        if (!assertEntityResult.success) {
-            throw new Error(`Failed to assert staged entity ${entity.id}: ${assertEntityResult.error || "unknown error"}`);
+    for (let offset = 0; offset < results.length; offset += PROJECTION_BATCH_SIZE) {
+        const batch = results.slice(offset, offset + PROJECTION_BATCH_SIZE);
+        const goals = batch.flatMap(({ entity, sourceFile }) => [
+            // Upserts preserve relationships, so replace them with snapshot edges.
+            contextualProjectionGoal(`kb_retract_entity_relationships(${toPrologAtom(entity.id)})`, `retract staged relationships for entity ${entity.id}`),
+            contextualProjectionGoal(buildEntityAssertionGoal(entity, sourceFile), `assert staged entity ${entity.id}`),
+        ]);
+        // query(array) wraps the batch in an RDF transaction and saves once.
+        const result = await prolog.query(goals);
+        if (!result.success) {
+            const label = batch.map(({ entity }) => entity.id).join(", ");
+            throw new Error(`Failed to assert staged entity ${label}: ${result.error || "unknown error"}`);
         }
     }
+    // Finish every entity before adding any relationships, including endpoints
+    // in later batches. Keep only one bounded batch of relationship goals.
+    let relationshipGoals = [];
+    let relationshipLabels = [];
+    // implements REQ-014
+    const flushRelationships = async () => {
+        if (relationshipGoals.length === 0)
+            return;
+        const result = await prolog.query(relationshipGoals);
+        if (!result.success) {
+            const label = relationshipLabels.join(", ");
+            throw new Error(`Failed to assert staged relationship ${label}: ${result.error || "unknown error"}`);
+        }
+        relationshipGoals = [];
+        relationshipLabels = [];
+    };
     for (const { relationships } of results) {
         for (const relationship of relationships) {
-            const assertRelationshipResult = await prolog.query(buildRelationshipAssertionGoal(relationship));
-            if (!assertRelationshipResult.success) {
-                throw new Error(`Failed to assert staged relationship ${relationship.type} ${relationship.from} -> ${relationship.to}: ${assertRelationshipResult.error || "unknown error"}`);
-            }
+            const label = `${relationship.type} ${relationship.from} -> ${relationship.to}`;
+            relationshipLabels.push(label);
+            relationshipGoals.push(contextualProjectionGoal(buildRelationshipAssertionGoal(relationship), `assert staged relationship ${label}`));
+            if (relationshipGoals.length === PROJECTION_BATCH_SIZE)
+                await flushRelationships();
         }
     }
+    await flushRelationships();
 }
 export async function createTempKb(baseKbPath) {
     // implements REQ-014
-    if (!existsSync(baseKbPath)) {
+    if (baseKbPath !== undefined && !existsSync(baseKbPath)) {
         throw new Error(`Base KB path does not exist: ${baseKbPath}`);
     }
     // Use crypto.randomUUID() for uniqueness across concurrent calls
@@ -290,7 +331,10 @@ export async function createTempKb(baseKbPath) {
     trace(`creating temp KB directory ${tempDir}`);
     await mkdir(tempDir, { recursive: true });
     trace(`copying base KB ${baseKbPath} -> ${kbPath}`);
-    await cp(baseKbPath, kbPath, { recursive: true });
+    if (baseKbPath !== undefined)
+        await cp(baseKbPath, kbPath, { recursive: true });
+    else
+        await mkdir(kbPath, { recursive: true });
     await writeFile(overlayPath, "", "utf8");
     const prolog = _createProlog({ timeout: 120000, oneShot: false });
     await prolog.start();

package/dist/traceability/trusted-pr-event.d.ts

@@ -0,0 +1,13 @@
+export type TrustedPullRequestSnapshot = Readonly<{
+    repository: string;
+    targetRef: string;
+    targetCommit: string;
+    targetTree: string;
+    headCommit: string;
+    headTree: string;
+    mergeBaseCommit: string;
+    mergeBaseTree: string;
+}>;
+/** Verify a GitHub pull_request_target envelope against the protected checkout. */
+export declare function resolveTrustedPullRequestSnapshot(workspaceRoot: string, environment?: NodeJS.ProcessEnv): TrustedPullRequestSnapshot;
+//# sourceMappingURL=trusted-pr-event.d.ts.map

package/dist/traceability/trusted-pr-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-pr-event.d.ts","sourceRoot":"","sources":["../../src/traceability/trusted-pr-event.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAkDH,mFAAmF;AACnF,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,EACrB,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,0BAA0B,CAqF5B"}

package/dist/traceability/trusted-pr-event.js

@@ -0,0 +1,105 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+const OBJECT_ID = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+function runGit(root, args) {
+    return execFileSync("git", [...args], {
+        cwd: root,
+        encoding: "utf8",
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+function resolveCommit(root, input) {
+    if (!OBJECT_ID.test(input))
+        throw new Error("PR event contains an invalid Git object ID");
+    const resolved = runGit(root, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${input}^{commit}`,
+    ]);
+    if (!OBJECT_ID.test(resolved))
+        throw new Error("Git returned an invalid commit ID");
+    return resolved;
+}
+function resolveTree(root, commit) {
+    const tree = runGit(root, [
+        "rev-parse",
+        "--verify",
+        "--end-of-options",
+        `${commit}^{tree}`,
+    ]);
+    if (!OBJECT_ID.test(tree))
+        throw new Error("Git returned an invalid tree ID");
+    return tree;
+}
+/** Verify a GitHub pull_request_target envelope against the protected checkout. */
+export function resolveTrustedPullRequestSnapshot(workspaceRoot, environment = process.env) {
+    if (environment.GITHUB_EVENT_NAME !== "pull_request_target")
+        throw new Error("Trusted impact gate requires pull_request_target context");
+    const eventPath = environment.GITHUB_EVENT_PATH;
+    const repository = environment.GITHUB_REPOSITORY;
+    const trustedTargetRef = environment.KIBI_IMPACT_TRUSTED_TARGET_REF;
+    const githubSha = environment.GITHUB_SHA;
+    if (!eventPath || !repository || !trustedTargetRef || !githubSha)
+        throw new Error("Trusted PR event, repository, target ref and GitHub event SHA are required");
+    if (!/^[^/]+\/[^/]+$/.test(repository))
+        throw new Error("GitHub repository identity is invalid");
+    if (!/^refs\/heads\/[A-Za-z0-9._/-]+$/.test(trustedTargetRef))
+        throw new Error("Trusted target must be a full refs/heads/... name");
+    const payload = JSON.parse(readFileSync(eventPath, "utf8"));
+    const request = payload.pull_request;
+    const base = request?.base;
+    const head = request?.head;
+    const baseRef = base?.ref;
+    const targetInput = base?.sha;
+    const headInput = head?.sha;
+    if (typeof baseRef !== "string" ||
+        typeof targetInput !== "string" ||
+        typeof headInput !== "string" ||
+        base?.repo?.full_name !== repository)
+        throw new Error("PR event does not identify this repository's base and head");
+    if (trustedTargetRef !== `refs/heads/${baseRef}`)
+        throw new Error("PR target does not match the configured protected branch");
+    if (payload.repository?.full_name !== repository)
+        throw new Error("PR event repository identity does not match the trusted checkout");
+    const targetCommit = resolveCommit(workspaceRoot, targetInput);
+    const headCommit = resolveCommit(workspaceRoot, headInput);
+    if (resolveCommit(workspaceRoot, githubSha) !== targetCommit)
+        throw new Error("GitHub event target SHA does not match its trusted payload");
+    const checkoutCommit = resolveCommit(workspaceRoot, runGit(workspaceRoot, ["rev-parse", "HEAD"]));
+    if (checkoutCommit !== targetCommit)
+        throw new Error("Trusted evaluator checkout is not the PR target commit");
+    if (runGit(workspaceRoot, ["rev-parse", "--is-shallow-repository"]) !== "false")
+        throw new Error("Complete Git history is required for impact evaluation");
+    const missing = runGit(workspaceRoot, [
+        "rev-list",
+        "--objects",
+        "--missing=print",
+        targetCommit,
+        headCommit,
+    ]);
+    if (missing.split("\n").some((line) => line.startsWith("?")))
+        throw new Error("PR target or head has missing reachable Git objects");
+    const mergeBases = runGit(workspaceRoot, [
+        "merge-base",
+        "--all",
+        targetCommit,
+        headCommit,
+    ])
+        .split("\n")
+        .filter(Boolean);
+    if (mergeBases.length !== 1)
+        throw new Error("PR target and head must have exactly one merge base");
+    const mergeBaseCommit = resolveCommit(workspaceRoot, mergeBases[0] ?? "");
+    return {
+        repository,
+        targetRef: trustedTargetRef,
+        targetCommit,
+        targetTree: resolveTree(workspaceRoot, targetCommit),
+        headCommit,
+        headTree: resolveTree(workspaceRoot, headCommit),
+        mergeBaseCommit,
+        mergeBaseTree: resolveTree(workspaceRoot, mergeBaseCommit),
+    };
+}

package/dist/traceability/validate.js

@@ -153,7 +153,7 @@ export function formatViolations(violations) {
         const loc = `${v.file}:${v.line}`;
         const name = `${v.name}()`;
         // Suggest adding requirement links with role-specific guidance
-        const suggestion = "Add ownership: implements: REQ-001 (production code), use covered_by for production coverage, or executable_for for executable test code";
+        const suggestion = "Add ownership: implements: REQ-<area>-<behavior> (production code), use covered_by for production coverage, or executable_for for executable test code";
         lines.push(`${loc}  ${name}  -> ${suggestion}`);
     }
     return lines.join("\n");

package/dist/types/entities.d.ts

@@ -39,6 +39,8 @@ export interface FactFields {
     argument_names?: string[];
     argument_types?: string[];
     argument_descriptions?: string[];
+    argument_constants?: Record<string, string[]>;
+    argument_aliases?: Record<string, Record<string, string>>;
     aliases?: string[];
     examples?: string[];
     predicate_args?: string[];

package/dist/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}

package/dist/types/relationships.d.ts

@@ -1,5 +1,5 @@
 export interface BaseRelationship {
-    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "relates_to";
+    type: "depends_on" | "specified_by" | "verified_by" | "validates" | "implements" | "covered_by" | "executable_for" | "constrained_by" | "constrains" | "requires_property" | "requires_predicate" | "requires_rule" | "guards" | "publishes" | "consumes" | "supersedes" | "restates" | "relates_to";
     from: string;
     to: string;
     created_at?: string;

package/dist/types/relationships.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/types/relationships.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,YAAY,GACZ,cAAc,GACd,aAAa,GACb,WAAW,GACX,YAAY,GACZ,YAAY,GACZ,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,oBAAoB,GACpB,eAAe,GACf,QAAQ,GACR,WAAW,GACX,UAAU,GACV,YAAY,GACZ,UAAU,GACV,YAAY,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAe,gBAAgB,CAAC"}

package/dist/utils/canonical-path.d.ts

@@ -0,0 +1,3 @@
+/** Resolve filesystem aliases while preserving a suffix that does not exist yet. */
+export declare function canonicalFilesystemPath(candidate: string): string;
+//# sourceMappingURL=canonical-path.d.ts.map

package/dist/utils/canonical-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-path.d.ts","sourceRoot":"","sources":["../../src/utils/canonical-path.ts"],"names":[],"mappings":"AAGA,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAwBjE"}

package/dist/utils/canonical-path.js

@@ -0,0 +1,33 @@
+import { lstatSync, realpathSync } from "node:fs";
+import path from "node:path";
+/** Resolve filesystem aliases while preserving a suffix that does not exist yet. */
+export function canonicalFilesystemPath(candidate) {
+    let existing = path.resolve(candidate);
+    const missing = [];
+    for (;;) {
+        try {
+            return path.resolve(realpathSync.native(existing), ...missing);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            // A dangling symlink is an existing entry, not a missing path segment.
+            // Refuse it rather than allowing a later write to follow an unknown target.
+            let entry;
+            try {
+                entry = lstatSync(existing);
+            }
+            catch (statError) {
+                if (statError.code !== "ENOENT")
+                    throw statError;
+            }
+            if (entry !== undefined)
+                throw error;
+            const parent = path.dirname(existing);
+            if (parent === existing)
+                throw error;
+            missing.unshift(path.basename(existing));
+            existing = parent;
+        }
+    }
+}

package/dist/utils/entity-id-style.d.ts

@@ -0,0 +1,27 @@
+/** Purely numeric entity ID such as `REQ-001` or `ADR-12`. */
+export declare const NUMERIC_ENTITY_ID_PATTERN: RegExp;
+export type EntityIdStyleIssue = Readonly<{
+    code: "numeric_id" | "stem_mismatch";
+    message: string;
+    suggestion: string;
+}>;
+export declare function isNumericEntityId(id: string): boolean;
+/**
+ * Filename stem for an authored Markdown source, or undefined for non-Markdown
+ * sources (symbol manifests, code files, runtime `mcp://` provenance).
+ */
+export declare function markdownSourceStem(sourcePath: string | undefined): string | undefined;
+/**
+ * Style issues for one newly created entity. Callers decide whether the entity
+ * is new; this function never inspects the KB.
+ */
+export declare function entityIdStyleIssues(input: {
+    readonly id: string;
+    readonly sourcePath?: string | undefined;
+}): EntityIdStyleIssue[];
+/** Plain-text warnings for mutation receipts. */
+export declare function entityIdStyleWarnings(input: {
+    readonly id: string;
+    readonly sourcePath?: string | undefined;
+}): string[];
+//# sourceMappingURL=entity-id-style.d.ts.map

package/dist/utils/entity-id-style.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-id-style.d.ts","sourceRoot":"","sources":["../../src/utils/entity-id-style.ts"],"names":[],"mappings":"AAiCA,8DAA8D;AAE9D,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AAGxD,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,IAAI,EAAE,YAAY,GAAG,eAAe,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAGH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;GAGG;AAEH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,SAAS,CAOpB;AAED;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,kBAAkB,EAAE,CAoBvB;AAED,iDAAiD;AAEjD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C,GAAG,MAAM,EAAE,CAIX"}

package/dist/utils/entity-id-style.js

@@ -0,0 +1,81 @@
+/*
+ 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/>.
+*/
+/**
+ * Entity naming style (`entity-id-style`).
+ *
+ * Entities are named by what they govern (`REQ-cli-gc`), never by "the next
+ * number". The compiled KB cannot tell a legacy numbered entity from a new one
+ * (`created_at` is stamped at sync time when frontmatter omits it), so purely
+ * numeric IDs are reported only at creation boundaries: a `kb_upsert` that
+ * creates the entity, and staged added/renamed entity Markdown. Committed
+ * legacy entities such as `REQ-003` are therefore never flagged. The Prolog
+ * half of the rule (`check_entity_id_style/1`) reports filename-stem/`id`
+ * mismatches over the whole KB.
+ */
+import * as path from "node:path";
+/** Purely numeric entity ID such as `REQ-001` or `ADR-12`. */
+// implements REQ-kibi-entity-id-style
+export const NUMERIC_ENTITY_ID_PATTERN = /^[A-Z]+-\d+$/;
+// implements REQ-kibi-entity-id-style
+export function isNumericEntityId(id) {
+    return NUMERIC_ENTITY_ID_PATTERN.test(id.trim());
+}
+/**
+ * Filename stem for an authored Markdown source, or undefined for non-Markdown
+ * sources (symbol manifests, code files, runtime `mcp://` provenance).
+ */
+// implements REQ-kibi-entity-id-style
+export function markdownSourceStem(sourcePath) {
+    if (sourcePath === undefined)
+        return undefined;
+    const normalized = sourcePath.trim().replaceAll("\\", "/");
+    if (!normalized.endsWith(".md") || normalized.includes("://")) {
+        return undefined;
+    }
+    return path.posix.basename(normalized, ".md");
+}
+/**
+ * Style issues for one newly created entity. Callers decide whether the entity
+ * is new; this function never inspects the KB.
+ */
+// implements REQ-kibi-entity-id-style
+export function entityIdStyleIssues(input) {
+    const id = input.id.trim();
+    const issues = [];
+    if (isNumericEntityId(id)) {
+        issues.push({
+            code: "numeric_id",
+            message: `Entity ID ${id} is a sequence number; parallel branches pick the same next number and collide.`,
+            suggestion: "Name the entity by what it governs: <TYPE>-<area>-<behavior> in kebab-case (for example REQ-cli-gc). kb_search the area first and update or supersede an existing entity when one already covers the behavior.",
+        });
+    }
+    const stem = markdownSourceStem(input.sourcePath);
+    if (stem !== undefined && stem !== id) {
+        issues.push({
+            code: "stem_mismatch",
+            message: `Entity ID ${id} does not match its filename stem ${stem}.`,
+            suggestion: `Rename the file to ${id}.md or set frontmatter id: ${stem} so the file name and identity stay aligned.`,
+        });
+    }
+    return issues;
+}
+/** Plain-text warnings for mutation receipts. */
+// implements REQ-kibi-entity-id-style
+export function entityIdStyleWarnings(input) {
+    return entityIdStyleIssues(input).map((issue) => `entity-id-style: ${issue.message} ${issue.suggestion}`);
+}

package/dist/utils/git-repository-context.d.ts

@@ -0,0 +1,50 @@
+export interface GitRepositoryContext {
+    /** Root of the current working tree (the worktree, when linked). */
+    worktreeRoot: string;
+    /** Absolute Git directory of the current worktree. */
+    gitDir: string;
+    /** Absolute repository-common Git directory (shared across worktrees). */
+    commonGitDir: string;
+    /** Absolute hooks directory Git will actually execute (honors core.hooksPath). */
+    effectiveHooksDir: string;
+    isLinkedWorktree: boolean;
+    /**
+     * Primary checkout root, only when it can be validated as a real checkout
+     * (`git -C <candidate> rev-parse --show-toplevel` resolves to the
+     * candidate). Null for bare repositories, separate-git-dir layouts, and any
+     * candidate that is not itself a working tree.
+     */
+    primaryWorktreeRoot: string | null;
+    /** Raw core.hooksPath value when configured, else null. */
+    hooksPathConfig: string | null;
+    /** Config origin line (from --show-origin) for the configured hooksPath. */
+    hooksPathOrigin: string | null;
+}
+export type GitRepositoryResolution = {
+    status: "ok";
+    context: GitRepositoryContext;
+} | {
+    status: "not-a-repository";
+} | {
+    status: "git-unavailable";
+} | {
+    status: "git-refused";
+    /** First Git diagnostic (or fs detail) explaining the refusal. */
+    reason: string;
+} | {
+    status: "unsupported";
+    reason: string;
+};
+/**
+ * Resolve the effective Git repository context for `cwd` by asking Git
+ * instead of assuming `<cwd>/.git`. The result distinguishes "no repository"
+ * (callers may fall back to standalone-workspace behavior) from repositories
+ * Kibi must not touch (bare repositories) and directories where Git refused
+ * operationally (dubious ownership, unreadable `.git`, access failures) — the
+ * last must never be mistaken for "no repository", because that would send
+ * callers into standalone workspace writes.
+ *
+ * implements REQ-git-hook-effective-install
+ */
+export declare function resolveGitRepository(cwd?: string): GitRepositoryResolution;
+//# sourceMappingURL=git-repository-context.d.ts.map

package/dist/utils/git-repository-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-repository-context.d.ts","sourceRoot":"","sources":["../../src/utils/git-repository-context.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAC9B;IAAE,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC7B;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAqH9C;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,GAC1B,uBAAuB,CAmJzB"}