kibi-cli 2.21.2 → 2.22.1

package/dist/cli-register-foundation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-register-foundation.d.ts","sourceRoot":"","sources":["../src/cli-register-foundation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqJjE"}
+{"version":3,"file":"cli-register-foundation.d.ts","sourceRoot":"","sources":["../src/cli-register-foundation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAezC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyJjE"}

package/dist/cli-register-foundation.js

@@ -12,6 +12,7 @@ export function registerFoundationCommands(program) {
         .option("--no-hooks", "Do not install git hooks (hooks installed by default)")
         .option("--github", "Scaffold the GitHub Pages badge + requirement-health report workflow")
         .option("--badge-only", "With --github, publish only the badge (opt out of the full report)")
+        .option("--print-hook <hook>", "Print a snippet that delegates an existing hook (pre-commit, post-checkout, post-merge, post-rewrite) to kibi, and write nothing")
         .action(withExitCode(async (options) => (await import("./commands/init.js")).initCommand(options)));
     program
         .command("migrate")

package/dist/commands/check.d.ts

@@ -25,5 +25,4 @@ export declare function checkDomainContradictions(prolog: PrologProcess): Promis
 export declare function checkStrictFactShape(prolog: PrologProcess): Promise<Violation[]>;
 export declare function checkStrictReqFactPairing(prolog: PrologProcess): Promise<Violation[]>;
 export declare function checkStrictReadiness(prolog: PrologProcess): Promise<Violation[]>;
-export declare function checkSymbolCoverage(prolog: PrologProcess): Promise<Violation[]>;
 //# sourceMappingURL=check.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA8E7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA8gBD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA8nB/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA+BtB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAqCA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgF7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AA8gBD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,EAC5B,MAAM,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAC3B,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAMpB;AAGD,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqlB/B;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAoDtB;AAID,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,EAAE,CAAC,CAiBnB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAkEtB;AAID,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAmGtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAyCtB;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAgDtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CA0BtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,SAAS,EAAE,CAAC,CAqBtB"}

package/dist/commands/check.js

@@ -41,7 +41,7 @@ import { classifyKibiImpactEvidence, isBehaviorSourceEdit, parseKibiImpactOverri
 import { assessStagedSymbolsManifest, collectStagedAuthoredSymbolsManifestEvidence, } from "../traceability/staged-symbols-manifest.js";
 import { createManifestLookupSentinelKey, extractSymbolsFromStagedFileAsync, } from "../traceability/symbol-extract.js";
 import { cleanupTempKb, consultOverlay, createOverlayFacts, createTempKb, projectStagedEntities, } from "../traceability/temp-kb.js";
-import { formatViolations as formatStagedViolations, validateStagedSymbols, } from "../traceability/validate.js";
+import { formatCoverageViolations, formatViolations as formatStagedViolations, validateStagedSymbolCoverage, validateStagedSymbols, } from "../traceability/validate.js";
 import { resolveReadBranchAttachment } from "../utils/branch-resolver.js";
 import { CANONICAL_ENTITY_PATHS, isEntityLanePath } from "../utils/kb-paths.js";
 import { safeCleanupProlog } from "../utils/prolog-cleanup.js";
@@ -708,122 +708,82 @@ export async function checkCommand(options) {
                         : {}),
                     symbolsByFile,
                 }), ...createSemanticReviewDiagnostics({ symbolsByFile }), ...createStagedEntityIdStyleDiagnostics(markdownFiles));
-                if (allSymbols.length === 0 && stagedEntityResults.length === 0) {
-                    if (stagedKibiDiagnostics.length > 0) {
-                        const blocking = hasBlockingImpactDiagnostics(stagedKibiDiagnostics);
-                        printStagedResult({
-                            format: options.format,
-                            coverage: stagedCoverage,
-                            qualityDiagnostics: stagedKibiDiagnostics,
-                            messages: [
-                                formatStagedKibiDiagnostics(stagedKibiDiagnostics),
-                                // Advisory-only findings still pass; say so explicitly.
-                                ...(!blocking
-                                    ? ["✓ No violations found in staged files."]
-                                    : []),
-                            ],
-                        });
-                        if (options.dryRun) {
-                            return { exitCode: 0 };
-                        }
-                        return { exitCode: blocking ? 1 : 0 };
-                    }
-                    printSnapshotResult({
-                        format: options.format,
-                        coverage: stagedCoverage,
-                        messages: [noValidatedSymbolsMessage(sourceAnalysis)],
+                // Run the Prolog rules over the staged knowledge: the minLinks
+                // ownership gate for changed source symbols, and full-check
+                // symbol-coverage for every changed symbol (changed source symbols
+                // plus symbols whose staged manifest entry changed).
+                let violationsRaw = [];
+                let coverageViolations = [];
+                if (allSymbols.length > 0 || activeStagedSymbolEntityIds.size > 0) {
+                    tempCtx = await createTempKb();
+                    await projectStagedEntities(tempCtx.prolog, snapshotEntities);
+                    const overlayFacts = createOverlayFacts(allSymbols);
+                    const fs = await import("node:fs/promises");
+                    await fs.writeFile(tempCtx.overlayPath, overlayFacts, "utf8");
+                    await fs.cp(tempCtx.overlayPath, path.join(tempCtx.kbPath, "changed_symbols.pl"));
+                    await consultOverlay(tempCtx);
+                    violationsRaw = await validateStagedSymbols({
+                        minLinks,
+                        prolog: tempCtx.prolog,
                     });
-                    return { exitCode: 0 };
-                }
-                if (allSymbols.length === 0) {
-                    if (stagedKibiDiagnostics.length > 0) {
-                        const blocking = hasBlockingImpactDiagnostics(stagedKibiDiagnostics);
-                        printStagedResult({
-                            format: options.format,
-                            coverage: stagedCoverage,
-                            qualityDiagnostics: stagedKibiDiagnostics,
-                            messages: [
-                                formatStagedKibiDiagnostics(stagedKibiDiagnostics),
-                                // Advisory-only findings still pass; say so explicitly.
-                                ...(!blocking
-                                    ? ["✓ No violations found in staged files."]
-                                    : []),
-                            ],
-                        });
-                        if (options.dryRun) {
-                            return { exitCode: 0 };
-                        }
-                        return { exitCode: blocking ? 1 : 0 };
-                    }
-                    printSnapshotResult({
-                        format: options.format,
-                        coverage: stagedCoverage,
-                        messages: ["✓ No violations found in staged files."],
+                    coverageViolations = await validateStagedSymbolCoverage({
+                        prolog: tempCtx.prolog,
+                        extraSymbolIds: [...activeStagedSymbolEntityIds],
                     });
-                    return { exitCode: 0 };
+                    await cleanupTempKb(tempCtx.tempDir);
                 }
-                // Create temp KB
-                tempCtx = await createTempKb();
-                await projectStagedEntities(tempCtx.prolog, snapshotEntities);
-                const overlayFacts = createOverlayFacts(allSymbols);
-                const fs = await import("node:fs/promises");
-                await fs.writeFile(tempCtx.overlayPath, overlayFacts, "utf8");
-                await fs.cp(tempCtx.overlayPath, path.join(tempCtx.kbPath, "changed_symbols.pl"));
-                await consultOverlay(tempCtx);
-                const violationsRaw = await validateStagedSymbols({
-                    minLinks,
-                    prolog: tempCtx.prolog,
-                });
-                const violationsFormatted = formatStagedViolations(violationsRaw);
-                if (violationsRaw && violationsRaw.length > 0) {
-                    printSnapshotResult({
+                // Without changed source symbols the result was historically printed
+                // without re-asserting the snapshot; keep that behavior.
+                const print = allSymbols.length === 0 ? printStagedResult : printSnapshotResult;
+                const passMessage = allSymbols.length === 0
+                    ? "✓ No violations found in staged files."
+                    : "✓ No violations found in staged symbols.";
+                if (violationsRaw.length > 0 || coverageViolations.length > 0) {
+                    print({
                         format: options.format,
                         coverage: stagedCoverage,
-                        violations: violationsRaw,
+                        violations: [...violationsRaw, ...coverageViolations],
                         qualityDiagnostics: stagedKibiDiagnostics,
                         messages: [
                             ...(stagedKibiDiagnostics.length > 0
                                 ? [formatStagedKibiDiagnostics(stagedKibiDiagnostics)]
                                 : []),
-                            violationsFormatted,
+                            ...(coverageViolations.length > 0
+                                ? [formatCoverageViolations(coverageViolations)]
+                                : []),
+                            ...(violationsRaw.length > 0
+                                ? [formatStagedViolations(violationsRaw)]
+                                : []),
                         ],
                     });
-                    await cleanupTempKb(tempCtx.tempDir);
-                    if (options.dryRun) {
-                        return { exitCode: 0 };
-                    }
-                    return { exitCode: 1 };
+                    return { exitCode: options.dryRun ? 0 : 1 };
                 }
                 if (stagedKibiDiagnostics.length > 0) {
-                    await cleanupTempKb(tempCtx.tempDir);
                     const blocking = hasBlockingImpactDiagnostics(stagedKibiDiagnostics);
-                    printSnapshotResult({
+                    print({
                         format: options.format,
                         coverage: stagedCoverage,
                         qualityDiagnostics: stagedKibiDiagnostics,
                         messages: [
                             formatStagedKibiDiagnostics(stagedKibiDiagnostics),
-                            ...(!blocking
-                                ? ["✓ No violations found in staged symbols."]
-                                : []),
+                            // Advisory-only findings still pass; say so explicitly.
+                            ...(!blocking ? [passMessage] : []),
                         ],
                     });
                     if (options.dryRun) {
                         return { exitCode: 0 };
                     }
-                    if (!blocking) {
-                        return { exitCode: 0 };
-                    }
-                    return {
-                        exitCode: 1,
-                    };
+                    return { exitCode: blocking ? 1 : 0 };
                 }
                 printSnapshotResult({
                     format: options.format,
                     coverage: stagedCoverage,
-                    messages: ["✓ No violations found in staged symbols."],
+                    messages: [
+                        allSymbols.length === 0 && stagedEntityResults.length === 0
+                            ? noValidatedSymbolsMessage(sourceAnalysis)
+                            : passMessage,
+                    ],
                 });
-                await cleanupTempKb(tempCtx.tempDir);
                 return { exitCode: 0 };
             }
             catch (err) {
@@ -1293,27 +1253,3 @@ export async function checkStrictReadiness(prolog) {
     }
     return violations;
 }
-export async function checkSymbolCoverage(prolog) {
-    const violations = [];
-    const uncoveredResult = await prolog.query("setof(Symbol, symbol_no_req_coverage(Symbol, _), Symbols)");
-    if (uncoveredResult.success && uncoveredResult.bindings.Symbols) {
-        const symbolsStr = uncoveredResult.bindings.Symbols;
-        const match = symbolsStr.match(/\[(.*)\]/);
-        const content = getMatchGroup(match)?.trim();
-        if (content) {
-            const symbolMatches = content.matchAll(/'([^']+)'/g);
-            for (const symbolMatch of symbolMatches) {
-                const symbolId = getMatchGroup(symbolMatch);
-                if (!symbolId)
-                    continue;
-                violations.push({
-                    rule: "symbol-coverage",
-                    entityId: symbolId,
-                    description: "Code symbol is not traceable to any functional requirement.",
-                    suggestion: "Update symbols.yaml to link this symbol to a related requirement.",
-                });
-            }
-        }
-    }
-    return violations;
-}

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AA4FA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmH/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAiGA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmH/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}

package/dist/commands/doctor.js

@@ -29,7 +29,8 @@ import { resolveBranchAttachment, resolveReadBranchAttachment, } from "../utils/
 import { branchStoreCompilation, inspectBranchStore, storeLockTakeoverReason, uncompiledBranchStoreReason, } from "../utils/branch-store.js";
 import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { readKbManifestStatus } from "../utils/kb-manifest.js";
-import { hasManagedHooks, outdatedManagedHooks } from "./init-helpers.js";
+import { LATEST_KB_SCHEMA_VERSION } from "../utils/schema-version.js";
+import { KIBI_HOOK_BEGIN, hasManagedHooks, outdatedManagedHooks, } from "./init-helpers.js";
 import { planLegacyStorageMigration } from "./legacy-storage-migration.js";
 /**
  * First-party plugin diagnostics known without importing the package.
@@ -616,6 +617,17 @@ function checkKbManifest() {
             remediation: `Repair .kb/manifest.json: ${status.warning}`,
         };
     }
+    // A knowledge base written by an older Kibi keeps reading and checking
+    // until migrated, but the current CLI expects its own schema: say so here,
+    // where the operator looks first, instead of leaving it to the next
+    // failing check. The migration plan below names the actions.
+    if (status.manifest.schemaVersion < LATEST_KB_SCHEMA_VERSION) {
+        return {
+            passed: false,
+            message: `schemaVersion ${status.manifest.schemaVersion} (this Kibi expects ${LATEST_KB_SCHEMA_VERSION})`,
+            remediation: "Run: kibi migrate (previews the plan), then kibi migrate --yes to apply it, or kibi migrate --apply-safe --approved-plan-hash <planHash> --approved-action <id> for selected actions",
+        };
+    }
     return {
         passed: true,
         message: `schemaVersion ${status.manifest.schemaVersion}`,
@@ -634,15 +646,18 @@ function checkLegacyStorage() {
     if (plan.blockers.length > 0) {
         return {
             passed: false,
-            message: `${plan.moves.length} legacy knowledge file(s) outside .kb/ cannot be moved automatically`,
-            remediation: `${plan.blockers.join(" ")} Compare each legacy copy with its .kb/ copy and keep the current one: replace the .kb/ copy when the legacy one is newer, or remove (git rm) the legacy copy when it is a stale duplicate. Then run: kibi migrate --yes`,
+            message: `${plan.blockers.length} legacy knowledge file(s) outside .kb/ cannot be moved automatically`,
+            remediation: `${plan.blockers.join(" ")} Then run: kibi migrate --yes`,
         };
     }
-    if (plan.legacyConfig === "present" || plan.moves.length > 0) {
+    if (plan.legacyConfig === "present" ||
+        plan.moves.length > 0 ||
+        plan.removals.length > 0) {
+        const outside = plan.moves.length + plan.removals.length;
         return {
             passed: false,
-            message: plan.moves.length > 0
-                ? `${plan.moves.length} legacy knowledge file(s) still outside .kb/`
+            message: outside > 0
+                ? `${outside} legacy knowledge file(s) still outside .kb/${plan.removals.length > 0 ? ` (${plan.removals.length} identical to the .kb/ copy, which kibi migrate removes)` : ""}`
                 : "Legacy .kb/config.json still present",
             remediation: "Run: kibi migrate --yes",
         };
@@ -860,6 +875,66 @@ function checkGitHooks() {
         remediation: "Run: kibi init",
     };
 }
+/**
+ * Individual shell commands of a hook script, ignoring comments. Lines are
+ * split on command separators so `a && b` counts as two commands.
+ */
+// implements REQ-git-hook-effective-install
+function hookCommands(content) {
+    return content
+        .split("\n")
+        .filter((line) => !line.trimStart().startsWith("#"))
+        .flatMap((line) => line.split(/&&|\|\||;|\|/))
+        .map((command) => command.trim())
+        .filter((command) => command.length > 0);
+}
+// Matches `kibi <sub>`, `npx kibi <sub>`, `node_modules/.bin/kibi <sub>` and
+// the template's `"$KIBI_BIN" <sub>`.
+// implements REQ-git-hook-effective-install
+function invokesKibi(command, subcommand) {
+    return new RegExp(`(?:\\bkibi|\\bKIBI_BIN)["'}]*\\s+${subcommand}(?=\\s|$)`).test(command);
+}
+/** The pre-commit gate the managed template runs, as a custom hook must. */
+const PRE_COMMIT_DELEGATIONS = [
+    {
+        label: "kibi check-generated --staged --changed-only",
+        matches: (command) => invokesKibi(command, "check-generated") &&
+            /\s--staged(?=\s|$)/.test(command) &&
+            /\s--changed-only(?=\s|$)/.test(command),
+    },
+    {
+        label: "kibi check --staged",
+        matches: (command) => invokesKibi(command, "check") && /\s--staged(?=\s|$)/.test(command),
+    },
+];
+// implements REQ-git-hook-effective-install
+function checkCustomPreCommitHook(content, executable) {
+    const commands = hookCommands(content);
+    const missing = PRE_COMMIT_DELEGATIONS.filter((delegation) => !commands.some(delegation.matches)).map((delegation) => `'${delegation.label}'`);
+    if (missing.length > 0) {
+        // An unmarked file that still carries the old template header is a Kibi
+        // hook from before managed sections; removing it lets init reinstall it.
+        const oldTemplate = content.includes("# pre-commit hook for kibi")
+            ? " If this file is an old Kibi template, delete it and run 'kibi init' instead."
+            : "";
+        return {
+            passed: false,
+            message: `Custom pre-commit hook (no kibi-managed section) does not run ${missing.join(" or ")}; commits skip Kibi enforcement${hooksPathSuffix()}`,
+            remediation: `Delegate from your hook to both 'kibi check-generated --staged --changed-only' and 'kibi check --staged'. Print a copy-paste snippet that resolves a project-local kibi with: kibi init --print-hook pre-commit (kibi init never edits a custom hook).${oldTemplate}`,
+        };
+    }
+    if (!executable) {
+        return {
+            passed: false,
+            message: `Installed but not executable${hooksPathSuffix()}`,
+            remediation: remediationHookPaths("pre-commit"),
+        };
+    }
+    return {
+        passed: true,
+        message: `Custom hook delegates to 'kibi check-generated --staged --changed-only' and 'kibi check --staged'${hooksPathSuffix()}`,
+    };
+}
 function checkPreCommitHook() {
     const postCheckoutPath = path.join(effectiveHooksDir(), "post-checkout");
     const postMergePath = path.join(effectiveHooksDir(), "post-merge");
@@ -885,6 +960,12 @@ function checkPreCommitHook() {
         const preCommitExecutable = (preCommitStats.mode & 0o111) !== 0;
         // Read hook content to determine whether it's using the new staged check
         const content = readFileSync(preCommitPath, "utf-8");
+        // A hook without a kibi-managed section is the user's own (hand-written,
+        // husky, lefthook, ...). `kibi init` never edits it, so the only useful
+        // check is whether it delegates to the gate the managed template runs.
+        if (!content.includes(KIBI_HOOK_BEGIN)) {
+            return checkCustomPreCommitHook(content, preCommitExecutable);
+        }
         // Current templates resolve the kibi binary into KIBI_BIN before invoking
         // it (git hooks do not get node_modules/.bin on PATH); legacy templates
         // invoked bare `kibi`.
@@ -963,6 +1044,27 @@ function checkPostRewriteHook() {
         // Read hook content to verify it invokes kibi. Current templates invoke
         // the resolved KIBI_BIN; legacy templates invoked bare `kibi sync`.
         const content = readFileSync(postRewritePath, "utf-8");
+        // A custom hook (no kibi-managed section) is never edited by init.
+        // implements REQ-git-hook-effective-install
+        if (!content.includes(KIBI_HOOK_BEGIN)) {
+            if (!hookCommands(content).some((cmd) => invokesKibi(cmd, "sync"))) {
+                return {
+                    passed: false,
+                    message: `Custom post-rewrite hook (no kibi-managed section) does not run 'kibi sync'${hooksPathSuffix()}`,
+                    remediation: "Delegate from your hook to 'kibi sync' after rebases. Print a copy-paste snippet that resolves a project-local kibi with: kibi init --print-hook post-rewrite (kibi init never edits a custom hook).",
+                };
+            }
+            return postRewriteExecutable
+                ? {
+                    passed: true,
+                    message: `Custom hook delegates to 'kibi sync'${hooksPathSuffix()}`,
+                }
+                : {
+                    passed: false,
+                    message: `Installed but not executable${hooksPathSuffix()}`,
+                    remediation: remediationHookPaths("post-rewrite"),
+                };
+        }
         const usesKibi = content.includes('"$KIBI_BIN" sync') || content.includes("kibi sync");
         const resolvesKibi = content.includes("KIBI_BIN=");
         if (!usesKibi) {

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

@@ -1,13 +1,27 @@
 export declare function getCurrentBranch(cwd?: string): Promise<string>;
 export declare function createKbDirectoryStructure(kbDir: string, currentBranch: string): void;
 export declare function createManifestFile(kbDir: string): void;
-export declare function updateGitIgnore(cwd: string): void;
+/** Adds the canonical derived entries to .gitignore; true when it changed the file. */
+export declare function updateGitIgnore(cwd: string): boolean;
 export declare function ensureSymbolsManifestFile(cwd: string): void;
 export declare function copySchemaFiles(kbDir: string, schemaSourceDir: string): Promise<void>;
+export declare const KIBI_HOOK_BEGIN = "# BEGIN kibi-managed";
 export type InstallHookResult = "installed" | "updated" | "skipped-foreign" | "skipped-symlink" | "skipped-unsupported";
+/** Hook names `kibi init` manages, in install order. */
+export declare const MANAGED_HOOK_NAMES: readonly ["post-checkout", "post-merge", "post-rewrite", "pre-commit"];
+export type ManagedHookName = (typeof MANAGED_HOOK_NAMES)[number];
+export declare function isManagedHookName(value: string): value is ManagedHookName;
+/**
+ * A copy-paste snippet for wiring Kibi into a hook that Kibi does not own
+ * (hand-written, husky, lefthook, ...). It reuses the managed template's
+ * KIBI_BIN resolution, so a project-local kibi CLI is found even though git
+ * does not put node_modules/.bin on PATH, and every command propagates its
+ * failure so the delegation is never weaker than the template it replaces.
+ */
+export declare function hookDelegationSnippet(hook: ManagedHookName): string;
 export declare function installHook(hookPath: string, content: string): InstallHookResult;
 export interface GitHookInstallResult {
-    hook: "pre-commit" | "post-checkout" | "post-merge" | "post-rewrite";
+    hook: ManagedHookName;
     result: InstallHookResult;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AA6IA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CA0BN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CA6BjD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAuBf;AASD,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,CAAC;AAoB1B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,CAwEnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,cAAc,CAAC;IACrE,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAiBD;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wEAAwE;AAExE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAChD,oBAAoB,EAAE,CA8CxB"}
+{"version":3,"file":"init-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/init-helpers.ts"],"names":[],"mappings":"AA6IA,wBAAsB,gBAAgB,CACpC,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,MAAM,CAAC,CASjB;AAED,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,IAAI,CA0BN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAGtD;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CA+BpD;AAkDD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU3D;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC,CAuBf;AAED,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAOtD,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,SAAS,GACT,iBAAiB,GACjB,iBAAiB,GACjB,qBAAqB,CAAC;AAE1B,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,wEAKrB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAGlE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED;;;;;;GAMG;AAEH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAqBnE;AAkBD,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,iBAAiB,CAwEnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAiBD;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAU/D;AAED,wEAAwE;AAExE,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAChD,oBAAoB,EAAE,CA8CxB"}

package/dist/commands/init-helpers.js

@@ -155,6 +155,7 @@ export function createManifestFile(kbDir) {
     writeKbManifest(path.dirname(kbDir), defaultKbManifest());
     console.log("✓ Created Kibi lifecycle manifest at .kb/manifest.json");
 }
+/** Adds the canonical derived entries to .gitignore; true when it changed the file. */
 export function updateGitIgnore(cwd) {
     // implements REQ-cli-init-canonical
     const gitignorePath = path.join(cwd, ".gitignore");
@@ -179,7 +180,9 @@ export function updateGitIgnore(cwd) {
     if (updatedContent !== gitignoreContent) {
         writeFileSync(gitignorePath, updatedContent);
         console.log("✓ Configured .gitignore for the canonical .kb/ layout");
+        return true;
     }
+    return false;
 }
 /** Exact derived-runtime entries owned by current Kibi init/migrate. */
 const CANONICAL_DERIVED_GITIGNORE_ENTRIES = [
@@ -258,26 +261,65 @@ export async function copySchemaFiles(kbDir, schemaSourceDir) {
     }
     console.log(`✓ Ensured ${schemaFiles.length} schema files`);
 }
-const KIBI_HOOK_BEGIN = "# BEGIN kibi-managed";
+export const KIBI_HOOK_BEGIN = "# BEGIN kibi-managed";
 const KIBI_HOOK_END = "# END kibi-managed";
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/** Hook names `kibi init` manages, in install order. */
+export const MANAGED_HOOK_NAMES = [
+    "post-checkout",
+    "post-merge",
+    "post-rewrite",
+    "pre-commit",
+];
+// implements REQ-git-hook-effective-install
+export function isManagedHookName(value) {
+    return MANAGED_HOOK_NAMES.includes(value);
+}
+/**
+ * A copy-paste snippet for wiring Kibi into a hook that Kibi does not own
+ * (hand-written, husky, lefthook, ...). It reuses the managed template's
+ * KIBI_BIN resolution, so a project-local kibi CLI is found even though git
+ * does not put node_modules/.bin on PATH, and every command propagates its
+ * failure so the delegation is never weaker than the template it replaces.
+ */
+// implements REQ-git-hook-effective-install
+export function hookDelegationSnippet(hook) {
+    const header = [
+        `# Kibi ${hook} delegation (printed by 'kibi init --print-hook ${hook}').`,
+        `# Paste into your existing ${hook} hook; it runs the same Kibi commands`,
+        "# as the Kibi-managed template.",
+    ].join("\n");
+    const guarded = (condition, commands) => {
+        const body = `${KIBI_BIN_RESOLVER}\n${commands}`.replace(/^(?=.)/gm, "  ");
+        return `${header}\nif ${condition}; then\n${body}\nfi\n`;
+    };
+    switch (hook) {
+        case "pre-commit":
+            return `${header}\n${KIBI_BIN_RESOLVER}\n"$KIBI_BIN" check-generated --staged --changed-only || exit $?\n"$KIBI_BIN" check --staged || exit $?\n`;
+        case "post-checkout":
+            // Only branch checkouts refresh the KB; file checkouts are skipped.
+            return guarded('[ "$3" = "1" ]', '"$KIBI_BIN" sync');
+        case "post-merge":
+            return `${header}\n${KIBI_BIN_RESOLVER}\n"$KIBI_BIN" sync\n`;
+        case "post-rewrite":
+            return guarded('[ "$1" = "rebase" ]', '"$KIBI_BIN" sync');
+    }
+}
 function hookIntegrationRecipe(hook) {
-    // Recipes must reproduce the exact checks the Kibi template runs for that
-    // hook, with failure propagation, or the delegation is weaker than the
-    // template it replaces.
+    // Recipes must name the exact checks the Kibi template runs for that hook;
+    // the printed snippet adds CLI resolution and failure propagation.
+    const printHook = `print a copy-paste snippet that resolves a project-local kibi with 'kibi init --print-hook ${hook}'`;
     switch (hook) {
         case "pre-commit":
-            return "delegate from that hook with 'kibi check-generated --staged --changed-only && kibi check --staged' (both commands must succeed; '&&' propagates the first failure)";
+            return `delegate from that hook to both 'kibi check-generated --staged --changed-only' and 'kibi check --staged' (both must succeed); ${printHook}`;
         case "post-checkout":
-            return "delegate from that hook to 'kibi sync' on branch checkouts (the template skips file checkouts)";
+            return `delegate from that hook to 'kibi sync' on branch checkouts (the template skips file checkouts); ${printHook}`;
         case "post-merge":
-            return "delegate from that hook to 'kibi sync'";
+            return `delegate from that hook to 'kibi sync'; ${printHook}`;
         case "post-rewrite":
-            return "delegate from that hook to 'kibi sync' after rebase/amend rewrites";
-        default:
-            return "delegate to the matching Kibi template command";
+            return `delegate from that hook to 'kibi sync' after rebase rewrites; ${printHook}`;
     }
 }
 export function installHook(hookPath, content) {

package/dist/commands/init.d.ts

@@ -2,6 +2,7 @@ interface InitOptions {
     hooks?: boolean;
     github?: boolean;
     badgeOnly?: boolean;
+    printHook?: string;
 }
 export declare function initCommand(options: InitOptions): Promise<{
     exitCode: number;

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

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAoGA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAkJ/B"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAuGA,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoDD,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgK/B"}

package/dist/commands/init.js

@@ -24,7 +24,7 @@ import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { readLegacyKbConfig } from "../utils/config.js";
 import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { scaffoldGitHubIntegration } from "./github-init.js";
-import { copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, installGitHooks, updateGitIgnore, } from "./init-helpers.js";
+import { MANAGED_HOOK_NAMES, copySchemaFiles, createKbDirectoryStructure, createManifestFile, ensureSymbolsManifestFile, hookDelegationSnippet, installGitHooks, isManagedHookName, updateGitIgnore, } from "./init-helpers.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 /**
@@ -121,6 +121,17 @@ async function initNextAction(projectRoot) {
 // implements REQ-cli-init
 // implements REQ-kibi-github-report-integration
 export async function initCommand(options) {
+    if (options.printHook !== undefined) {
+        // Print-only mode: emit a delegation snippet for a hook Kibi does not
+        // own and touch nothing, not even the repository context.
+        // implements REQ-git-hook-effective-install
+        if (!isManagedHookName(options.printHook)) {
+            console.error(`Error: unknown hook '${options.printHook}' for --print-hook. Expected one of: ${MANAGED_HOOK_NAMES.join(", ")}.`);
+            return { exitCode: 1 };
+        }
+        process.stdout.write(hookDelegationSnippet(options.printHook));
+        return { exitCode: 0 };
+    }
     if (options.badgeOnly === true && options.github !== true) {
         console.error("Error: --badge-only requires --github. The recommended integration is `kibi init --github` (badge + full report).");
         return { exitCode: 1 };