kibi-cli 2.22.0 → 2.22.1

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAgGA,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,6 +29,7 @@ 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 { 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";
 /**
@@ -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}`,

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

@@ -1,7 +1,8 @@
 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";

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;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"}
+{"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 = [

package/dist/commands/migrate.d.ts

@@ -11,12 +11,49 @@ interface MigrateOptions {
     /** Internal migration-plan executor: create only the canonical baseline manifest. */
     initializeMissingConfig?: boolean;
 }
+export interface MigrationAuditRecord {
+    auditVersion: number;
+    branch: string;
+    manifestPath: string;
+    fromVersion: number | null;
+    migratedAt: string;
+    semanticAdvisorBackfill: "pending" | "completed" | "not_applicable" | null;
+    status: "applied";
+    symbolGranularityLegacyLinks: number;
+    /** Entities carrying origin {kind: migration, ref: 'kibi migrate v5->v6'}. */
+    entityOriginBackfill: number;
+    /** Superseded requirements this run set to status: closed. */
+    supersededRequirementsClosed: number;
+    /** Pre-canonical source paths this run pointed at their .kb/ file. */
+    sourcePathsRewritten: number;
+    /** Authored source values this run removed: they named the entity's own file or nothing. */
+    sourcePathsRemoved: number;
+    toVersion: number;
+    /** The schema warning the KB showed before this run migrated it. */
+    preMigrationWarning: string | null;
+    steps: readonly string[];
+}
+/** What one applied `kibi migrate --yes` run changed, for plan apply results. */
+export interface MigrationRunSummary {
+    /** Workspace-relative path of the audit record this run wrote. */
+    auditPath: string;
+    audit: MigrationAuditRecord;
+    /** Whether this run added the canonical derived entries to .gitignore. */
+    gitignoreUpdated: boolean;
+}
 export declare function formatSchemaVersion(rawSchemaVersion: unknown, normalized: number | null): string;
 export declare function warnMigrationRequiredWithoutYes(): {
     exitCode: number;
 };
 export declare function migrateCommand(options?: MigrateOptions): Promise<{
     exitCode: number;
+    summary?: MigrationRunSummary;
 }>;
+/**
+ * One line naming what an applied migration run changed, read from the audit
+ * record it wrote: a count of zero shows a pass that had nothing left to do
+ * (for example legacy links an earlier plan action already marked).
+ */
+export declare function describeMigrationRun(summary: MigrationRunSummary): string;
 export {};
 //# sourceMappingURL=migrate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAmEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AA+JD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsOD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2Y/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAmEA,UAAU,cAAc;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,GAAG,IAAI,CAAC;IAC3E,MAAM,EAAE,SAAS,CAAC;IAClB,4BAA4B,EAAE,MAAM,CAAC;IACrC,8EAA8E;IAC9E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,4BAA4B,EAAE,MAAM,CAAC;IACrC,sEAAsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;IAC5B,0EAA0E;IAC1E,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAyID,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsOD,wBAAgB,+BAA+B,IAAI;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAKtE;AAGD,wBAAsB,cAAc,CAClC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAgZ9D;AAED;;;;GAIG;AAEH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAGzE"}

package/dist/commands/migrate.js

@@ -149,7 +149,7 @@ function buildMigrationAuditRecord(args) {
         sourcePathsRewritten: args.sourcePathsRewritten,
         sourcePathsRemoved: args.sourcePathsRemoved,
         toVersion: LATEST_KB_SCHEMA_VERSION,
-        warning: args.warning,
+        preMigrationWarning: args.preMigrationWarning,
         steps: args.steps,
     };
 }
@@ -534,7 +534,7 @@ export async function migrateCommand(options = {}) {
     });
     if (supersedesUnexplained.length > 0)
         console.log(`Acknowledged ${supersedesUnexplained.length} supersede(s) recorded without a 'Why this changed' section; new supersedes must explain themselves.`);
-    writeJsonAtomically(auditPath, buildMigrationAuditRecord({
+    const auditRecord = buildMigrationAuditRecord({
         branch,
         manifestPath: KB_MANIFEST_RELATIVE,
         fromVersion: configStatus.currentVersion,
@@ -545,9 +545,10 @@ export async function migrateCommand(options = {}) {
         supersededRequirementsClosed: lifecycle.closed,
         sourcePathsRewritten: lifecycle.rewritten,
         sourcePathsRemoved: lifecycle.removed,
-        warning: migrationWarning,
+        preMigrationWarning: migrationWarning,
         steps: migrationSteps.map((step) => step.id),
-    }));
+    });
+    writeJsonAtomically(auditPath, auditRecord);
     console.log(`Migrated the KB to schemaVersion ${LATEST_KB_SCHEMA_VERSION} on the canonical .kb/ layout (was ${fromVersionLabel}).`);
     if (semanticAdvisorBackfill === "pending") {
         console.log(`Marked semantic advisor backfill as pending in ${KB_MANIFEST_RELATIVE}.`);
@@ -560,8 +561,25 @@ export async function migrateCommand(options = {}) {
     }
     console.log(`Wrote migration audit metadata to ${toRelativePath(cwd, auditPath)}.`);
     console.log("Migration complete. Future 'kibi migrate' runs will be a no-op.");
-    updateGitIgnore(cwd);
-    return { exitCode: 0 };
+    const gitignoreUpdated = updateGitIgnore(cwd);
+    return {
+        exitCode: 0,
+        summary: {
+            auditPath: toRelativePath(cwd, auditPath),
+            audit: auditRecord,
+            gitignoreUpdated,
+        },
+    };
+}
+/**
+ * One line naming what an applied migration run changed, read from the audit
+ * record it wrote: a count of zero shows a pass that had nothing left to do
+ * (for example legacy links an earlier plan action already marked).
+ */
+// implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration
+export function describeMigrationRun(summary) {
+    const { audit } = summary;
+    return `Migrated schema ${audit.fromVersion ?? "none"} -> ${audit.toVersion} (audit ${summary.auditPath}): legacy-link marks ${audit.symbolGranularityLegacyLinks}, origin backfill ${audit.entityOriginBackfill}, superseded requirements closed ${audit.supersededRequirementsClosed}, source paths rewritten ${audit.sourcePathsRewritten}, source paths removed ${audit.sourcePathsRemoved}; .gitignore ${summary.gitignoreUpdated ? "updated" : "unchanged"}.`;
 }
 const KB_MANIFEST_RELATIVE = ".kb/manifest.json";
 // implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration

package/dist/operations/mutation/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAU5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA8L/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA6DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -64,9 +64,51 @@ function unknownEntityProperties(entity) {
     const known = upsertEntitySchema.properties;
     return Object.keys(entity).filter((key) => !Object.hasOwn(known, key));
 }
+/**
+ * The fields a type-conditional `else: { not: ... }` branch of the entity
+ * schema forbids, and the types that may carry them; null for any other
+ * schema path.
+ */
+function typeRestrictedFields(schemaPath) {
+    const match = /^#\/allOf\/(\d+)\/else\/not$/.exec(schemaPath);
+    if (match === null)
+        return null;
+    const allOf = upsertEntitySchema.allOf;
+    const branch = Array.isArray(allOf) ? allOf[Number(match[1])] : undefined;
+    if (branch === null || typeof branch !== "object")
+        return null;
+    const record = branch;
+    const typeRule = record.if?.properties?.type;
+    const types = Array.isArray(typeRule?.enum)
+        ? typeRule.enum.map(String)
+        : typeof typeRule?.const === "string"
+            ? [typeRule.const]
+            : [];
+    const not = record.else?.not;
+    const requiredLists = [
+        not?.required,
+        ...(Array.isArray(not?.anyOf)
+            ? not.anyOf.map((entry) => entry?.required)
+            : []),
+    ];
+    const fields = requiredLists.flatMap((list) => Array.isArray(list) ? list.map(String) : []);
+    return types.length > 0 && fields.length > 0 ? { fields, types } : null;
+}
 // implements REQ-upsert-unknown-field-guidance
 function formatEntityErrors(entity, errors) {
-    const messages = errors.map((error) => {
+    // A field only some entity types carry fails a type-conditional `not`
+    // branch; AJV then reports "must NOT be valid" plus the "else" it chose.
+    const restricted = new Set(errors.flatMap((error) => error.keyword === "not" && typeRestrictedFields(error.schemaPath)
+        ? [error.schemaPath.replace(/\/else\/not$/, "/if")]
+        : []));
+    const visible = errors.filter((error) => !(error.keyword === "if" && restricted.has(error.schemaPath)));
+    const messages = visible.map((error) => {
+        const restriction = error.keyword === "not" ? typeRestrictedFields(error.schemaPath) : null;
+        if (restriction !== null) {
+            const present = restriction.fields.filter((field) => Object.hasOwn(entity, field));
+            const named = present.length > 0 ? present : restriction.fields;
+            return `${named.join(", ")} ${named.length === 1 ? "is" : "are"} only valid on ${restriction.types.join(" and ")} entities; remove ${named.length === 1 ? "it" : "them"} from this ${String(entity.type ?? "entity")}`;
+        }
         const params = error.params;
         const path = error.instancePath || "root";
         if (error.keyword === "additionalProperties" && params.additionalProperty) {

package/dist/operations/planning/apply-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAiE/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAi1BD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAmDD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AASlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AAiE/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AAi1BD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB;AACzB;;;GAGG;AACH,WAAW,GAAE,MAAM,IAAsB,GACxC,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAmDD"}

package/dist/operations/planning/apply-plan.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { OperationError } from "../../cli-errors.js";
 import { branchEnsureCommand, branchMigrateCommand, branchRecoverCommand, } from "../../commands/branch.js";
-import { migrateCommand } from "../../commands/migrate.js";
+import { describeMigrationRun, migrateCommand, } from "../../commands/migrate.js";
 import { syncCommand } from "../../commands/sync.js";
 import { PROOF_INTEGRATION_CONFIGURE, applyProofIntegrationAction, } from "../../proof/integration-plan.js";
 import { loadEntities } from "../../public/operations/discovery-entities.js";
@@ -2155,12 +2155,12 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
             continue;
         }
         try {
-            await applyMigrationAction(action, context);
+            const detail = await applyMigrationAction(action, context);
             onCommitted();
             results.push({
                 actionId: action.id,
                 outcome: "applied",
-                detail: `Applied ${action.code}.`,
+                detail: detail ?? `Applied ${action.code}.`,
             });
         }
         catch (error) {
@@ -2292,6 +2292,10 @@ async function applyMigrationPlan(args, context, onCommitted = () => undefined)
         structuredContent: payload,
     };
 }
+/**
+ * Run one approved migration action. Returns a detail line for the action
+ * result when the executor reports what it changed.
+ */
 async function applyMigrationAction(action, context) {
     switch (action.code) {
         case "legacy_branch_storage":
@@ -2342,14 +2346,19 @@ async function applyMigrationAction(action, context) {
             return;
         case "schema_version_upgrade":
         case "invalid_schema_version":
-        case "legacy_storage_migration":
-            if ((await migrateCommand({
+        case "legacy_storage_migration": {
+            // implements REQ-agent-guided-migration-orchestration
+            const run = await migrateCommand({
                 yes: true,
                 workspaceRoot: context.workspaceRoot,
                 initializeMissingConfig: true,
-            })).exitCode !== 0)
+            });
+            if (run.exitCode !== 0)
                 throw new Error("Schema migration did not complete successfully.");
-            return;
+            return run.summary !== undefined
+                ? describeMigrationRun(run.summary)
+                : undefined;
+        }
         case "symbol_refresh_coordinates":
         case "coverage_source_coordinates": {
             const result = await syncCommand({

package/dist/operations/semantic-advisor/ingestion-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoDD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}
+{"version":3,"file":"ingestion-boundary.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/ingestion-boundary.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAG3E,OAAO,EACL,KAAK,OAAO,EAOb,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,sBAAsB,EAAuB,MAAM,YAAY,CAAC;AAgB9E,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,CAAC,CAAC;AAuEH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,+BAA+B,CA0IjC;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAWN;AAoFD;;;;GAIG;AAEH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAC9D,MAAM,GAAG,IAAI,CAUf;AAGD,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,SAAS,oBAAoB,EAAE,EAC9C,MAAM,CAAC,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE,CAAC,GACD,OAAO,CAAC,IAAI,CAAC,CAwBf"}

package/dist/operations/semantic-advisor/ingestion-boundary.js

@@ -192,9 +192,33 @@ function groundingClaimKeyError(modeledClaimKeys, grounded) {
         return `Proposition-complete ingestion failed: claim '${duplicate}' has more than one logical grounding relationship.`;
     if (groundedClaimKeys.length !== modeledClaimKeys.length ||
         modeledClaimKeys.some((claimKey) => !groundedClaimKeys.includes(claimKey)))
-        return "Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly.";
+        return `Proposition-complete ingestion failed: modeled proposition claim_keys must match logical grounding target claim_keys exactly. ${claimKeyMismatchDetail(modeledClaimKeys, grounded)}`;
     return null;
 }
+/**
+ * Why the mismatch names both sides: a claim_key is derived from the clause
+ * text, so a requirement whose prose was reworded (or analyzed from another
+ * field than the stored semantic_text) carries keys none of its grounding
+ * facts declare. Listing the unmatched modeled keys and the facts with the
+ * keys they still declare lets the agent see the drift and pick the remedy
+ * without diffing the KB by hand.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+function claimKeyMismatchDetail(modeledClaimKeys, grounded) {
+    const groundedClaimKeys = grounded.map(([, claimKey]) => claimKey);
+    const ungrounded = modeledClaimKeys.filter((claimKey) => !groundedClaimKeys.includes(claimKey));
+    const stale = grounded.filter(([, claimKey]) => !modeledClaimKeys.includes(claimKey));
+    const parts = [
+        ungrounded.length > 0
+            ? `Modeled claims with no grounding fact declaring their claim_key: ${ungrounded.map((claimKey) => `'${claimKey}'`).join(", ")}.`
+            : "",
+        stale.length > 0
+            ? `Grounding facts whose claim_key the inventory no longer models: ${stale.map(([target, claimKey]) => `${target} ('${claimKey}')`).join(", ")}.`
+            : "",
+        "A claim_key is derived from the clause text, so reworded prose (or prose analyzed from a field other than the stored semantic_text) yields new keys. Keep the stored semantic_text wording, or kb_upsert each grounding fact with the new claim_key and claim_text (same fact id) before this write; for a change of meaning, supersede the requirement instead.",
+    ];
+    return parts.filter(Boolean).join(" ");
+}
 /**
  * The write-time claim_key check, run against planned writes only. Returns
  * null when it passes or when a target is outside the plan (the write-time

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts

@@ -0,0 +1,19 @@
+import type { PrologPort } from "../../public/operations/runtime-types.js";
+import type { SemanticAdvisorReceipt } from "./types.js";
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+export declare function storedLedgerDriftWarning(prolog: Pick<PrologPort, "query">, id: string, text: string, receipt: SemanticAdvisorReceipt): Promise<string | null>;
+//# sourceMappingURL=stored-ledger-drift.d.ts.map

package/dist/operations/semantic-advisor/stored-ledger-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-ledger-drift.d.ts","sourceRoot":"","sources":["../../../src/operations/semantic-advisor/stored-ledger-drift.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAwCzD;;;;;;;;;;;;;;GAcG;AAEH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,EACjC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAkDxB"}

package/dist/operations/semantic-advisor/stored-ledger-drift.js

@@ -0,0 +1,78 @@
+import { escapeAtom, parseListOfLists, parsePrologValue, } from "../../prolog/codec.js";
+import { loadEntities } from "../../public/operations/discovery-entities.js";
+import { SEMANTIC_INVENTORY_VERSION, isRecord, stringValue } from "./shared.js";
+const LOGICAL_RELATIONSHIPS = [
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+function atom(value) {
+    return stringValue(parsePrologValue(value ?? "")).replace(/^['"]|['"]$/g, "");
+}
+function quoted(text) {
+    return text ? ` ("${text}")` : "";
+}
+async function groundingFactsOf(prolog, id) {
+    const result = await prolog.query(`findall([Type,To,ClaimKey], (member(Type, [${LOGICAL_RELATIONSHIPS.join(",")}]), kb_relationship(Type, '${escapeAtom(id)}', To), ((kb_entity(To, fact, _DriftProps), memberchk(claim_key=_DriftRaw, _DriftProps), normalize_term_atom(_DriftRaw, ClaimKey)) -> true ; ClaimKey = '')), Rows)`);
+    if (!result.success)
+        return [];
+    return parseListOfLists(result.bindings.Rows ?? "[]").map(([type, target, claimKey]) => ({
+        type: atom(type),
+        target: atom(target),
+        claimKey: atom(claimKey),
+    }));
+}
+/**
+ * Why `kb_model mode: analyze` with the `id` of a stored requirement compares
+ * its ledger with the stored one: a claim_key is derived from the clause
+ * text, so analyzing reworded prose, or the title instead of the stored
+ * `semantic_text`, yields keys that none of the requirement's grounding
+ * facts declare. The write that follows such a receipt is refused by the
+ * proposition-complete check, long after the agent picked the wording. The
+ * receipt therefore warns at analysis time, naming the stored modeled
+ * clauses the analysis no longer states, the facts that ground them, and the
+ * clauses the analysis adds, so the agent can keep the stored wording or
+ * re-ground the facts before writing.
+ *
+ * Returns null when the requirement is not stored, carries no recorded
+ * ledger, or every stored modeled clause is still among the analyzed ones.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+export async function storedLedgerDriftWarning(prolog, id, text, receipt) {
+    const [stored] = await loadEntities(prolog, { id, type: "req" });
+    if (!stored ||
+        stored.semantic_inventory_version !== SEMANTIC_INVENTORY_VERSION ||
+        !Array.isArray(stored.semantic_inventory))
+        return null;
+    const storedInventory = stored.semantic_inventory.filter(isRecord);
+    const storedKeys = new Set(storedInventory.map((entry) => stringValue(entry.claim_key)));
+    const analyzedKeys = new Set(receipt.propositions.map(({ claim_key }) => claim_key));
+    const drifted = storedInventory
+        .filter((entry) => stringValue(entry.status) === "modeled" &&
+        !analyzedKeys.has(stringValue(entry.claim_key)))
+        .map((entry) => ({
+        claimKey: stringValue(entry.claim_key),
+        claimText: stringValue(entry.claim_text),
+    }));
+    if (drifted.length === 0)
+        return null;
+    const facts = await groundingFactsOf(prolog, id);
+    const groundedBy = (claimKey) => {
+        const matches = facts.filter((fact) => fact.claimKey === claimKey);
+        return matches.length > 0
+            ? `, grounded by ${matches.map((fact) => `${fact.target} via ${fact.type}`).join(" and ")}`
+            : "";
+    };
+    const missing = drifted
+        .map(({ claimKey, claimText }) => `'${claimKey}'${quoted(claimText)}${groundedBy(claimKey)}`)
+        .join("; ");
+    const added = receipt.propositions
+        .filter(({ claim_key }) => !storedKeys.has(claim_key))
+        .map(({ claim_key, claim_text }) => `'${claim_key}'${quoted(claim_text)}`)
+        .join("; ");
+    const storedText = stringValue(stored.semantic_text);
+    const cause = storedText && storedText !== text
+        ? `The analyzed prose differs from the stored semantic_text of ${id}.`
+        : "The stored clause keys were derived from different prose.";
+    return `Claim-key drift against the stored ledger of ${id}: stored modeled clause(s) not stated by this analysis: ${missing}.${added ? ` Clause(s) this analysis adds without a stored grounding: ${added}.` : ""} ${cause} A kb_upsert of ${id} with this ledger fails the proposition-complete claim_key check unless each affected grounding fact is first re-written with the new claim_key and claim_text (same fact id). Keep the stored semantic_text wording to keep the keys, or supersede the requirement for a change of meaning.`;
+}

package/dist/public/operations/decision-firmness.d.ts

@@ -28,7 +28,9 @@ export declare function unexplainedSupersedes(entities: readonly AuthoredEntity[
 /** The supersede edges of an entity, as the manifest acknowledges them. */
 export declare function supersedeAcknowledgements(id: string, edges: ReadonlyMap<string, Set<string>>): string[];
 /** Evaluate the firmness rules over authored requirements and ADRs. */
-export declare function evaluateDecisionFirmness(entities: readonly AuthoredEntity[], edges: ReadonlyMap<string, Set<string>>, rules?: ReadonlySet<string>, acknowledged?: ReadonlySet<string>): Violation[];
+export declare function evaluateDecisionFirmness(entities: readonly AuthoredEntity[], edges: ReadonlyMap<string, Set<string>>, rules?: ReadonlySet<string>, acknowledged?: ReadonlySet<string>, options?: Readonly<{
+    schemaVersion?: number | null;
+}>): Violation[];
 /** Read the authored decisions once and evaluate the selected rules. */
 export declare function collectDecisionFirmnessViolations(rules: ReadonlySet<string>, workspaceRoot: string): Violation[];
 //# sourceMappingURL=decision-firmness.d.ts.map

package/dist/public/operations/decision-firmness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../../../src/public/operations/decision-firmness.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,qBAAqB,CAAC;AAE7B,wEAAwE;AAExE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAC5E,qEAAqE;AAErE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AACxE,oEAAoE;AAEpE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,6EAA6E;AAE7E,eAAO,MAAM,mCAAmC,mCACd,CAAC;AAGnC,eAAO,MAAM,uBAAuB,oIAK1B,CAAC;AAIX,0CAA0C;AAE1C,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,EAAE,CAS5E;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+B1B;AASD;;;;;GAKG;AAEH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,cAAc,EAAE,CAQlB;AAED,2EAA2E;AAE3E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAIV;AAED,uEAAuE;AAEvE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACvC,KAAK,GAAE,WAAW,CAAC,MAAM,CAAoC,EAC7D,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,GAC5C,SAAS,EAAE,CAiGb;AAED,wEAAwE;AAExE,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,aAAa,EAAE,MAAM,GACpB,SAAS,EAAE,CASb"}
+{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../../../src/public/operations/decision-firmness.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,qBAAqB,CAAC;AAE7B,wEAAwE;AAExE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAC5E,qEAAqE;AAErE,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AACxE,oEAAoE;AAEpE,eAAO,MAAM,8BAA8B,8BAA8B,CAAC;AAC1E,6EAA6E;AAE7E,eAAO,MAAM,mCAAmC,mCACd,CAAC;AAGnC,eAAO,MAAM,uBAAuB,oIAK1B,CAAC;AAcX,0CAA0C;AAE1C,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,EAAE,CAS5E;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CA+B1B;AASD;;;;;GAKG;AAEH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,cAAc,EAAE,CAQlB;AAED,2EAA2E;AAE3E,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,GACtC,MAAM,EAAE,CAIV;AAED,uEAAuE;AAEvE,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,cAAc,EAAE,EACnC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,EACvC,KAAK,GAAE,WAAW,CAAC,MAAM,CAAoC,EAC7D,YAAY,GAAE,WAAW,CAAC,MAAM,CAAa,EAC7C,OAAO,GAAE,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAM,GACxD,SAAS,EAAE,CAoGb;AAED,wEAAwE;AAExE,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,aAAa,EAAE,MAAM,GACpB,SAAS,EAAE,CAWb"}

package/dist/public/operations/decision-firmness.js

@@ -41,6 +41,13 @@ export const DECISION_FIRMNESS_RULES = [
     SUPERSEDES_REASON_ACKNOWLEDGED_RULE,
 ];
 const DECISION_LANES = ["requirements", "adr"];
+/** The schema version from which a supersede must explain itself. */
+const SUPERSEDES_REASON_SCHEMA_VERSION = 9;
+/**
+ * Told on a KB older than schema 9: the pending schema upgrade acknowledges
+ * supersedes recorded before the rule existed, so no edit is required now.
+ */
+const PRE_SCHEMA9_SUPERSEDES_NOTE = " Supersedes recorded before schema 9 are acknowledged by the plan's schema-config-upgrade (kibi migrate --yes); add the reason only when you next touch the requirement.";
 /** Every authored requirement and ADR. */
 // implements REQ-kb-decision-firmness
 export function listDecisionEntities(workspaceRoot) {
@@ -123,7 +130,9 @@ export function supersedeAcknowledgements(id, edges) {
 }
 /** Evaluate the firmness rules over authored requirements and ADRs. */
 // implements REQ-kb-decision-firmness
-export function evaluateDecisionFirmness(entities, edges, rules = new Set(DECISION_FIRMNESS_RULES), acknowledged = new Set()) {
+export function evaluateDecisionFirmness(entities, edges, rules = new Set(DECISION_FIRMNESS_RULES), acknowledged = new Set(), options = {}) {
+    const preSchema9 = typeof options.schemaVersion === "number" &&
+        options.schemaVersion < SUPERSEDES_REASON_SCHEMA_VERSION;
     const findings = [];
     const superseded = supersededIds(edges);
     const byId = new Map(entities.map((entity) => [entity.id, entity]));
@@ -186,7 +195,7 @@ export function evaluateDecisionFirmness(entities, edges, rules = new Set(DECISI
                 rule: SUPERSEDES_REASON_MISSING_RULE,
                 entityId: entity.id,
                 description: `${entity.id} supersedes ${unacknowledged.join(", ")} without a '## ${WHY_THIS_CHANGED_HEADING}' section of at least ${MIN_WHY_CHANGED_WORDS} words`,
-                suggestion: `Add '## ${WHY_THIS_CHANGED_HEADING}' to the body: name the evidence (a failing test, a measured cost, a constraint the old decision missed, a new requirement) and answer the superseded decision's reasoning. A preference is not evidence; propose it instead of superseding.`,
+                suggestion: `Add '## ${WHY_THIS_CHANGED_HEADING}' to the body: name the evidence (a failing test, a measured cost, a constraint the old decision missed, a new requirement) and answer the superseded decision's reasoning. A preference is not evidence; propose it instead of superseding.${preSchema9 ? PRE_SCHEMA9_SUPERSEDES_NOTE : ""}`,
                 source: entity.path,
                 evidence: { type: entity.type, supersedes: unacknowledged },
             });
@@ -212,5 +221,6 @@ export function collectDecisionFirmnessViolations(rules, workspaceRoot) {
     if (!DECISION_FIRMNESS_RULES.some((rule) => rules.has(rule)))
         return [];
     const entities = listDecisionEntities(workspaceRoot);
-    return evaluateDecisionFirmness(entities, authoredSupersedes(workspaceRoot, entities), rules, new Set(readKbManifest(workspaceRoot)?.supersedesReasonAcknowledged ?? []));
+    const manifest = readKbManifest(workspaceRoot);
+    return evaluateDecisionFirmness(entities, authoredSupersedes(workspaceRoot, entities), rules, new Set(manifest?.supersedesReasonAcknowledged ?? []), { schemaVersion: manifest?.schemaVersion ?? null });
 }

package/dist/public/operations/discovery-executors.d.ts.map

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

package/dist/public/operations/discovery-executors.js

@@ -774,6 +774,13 @@ export async function executeStatus(_input, context) {
                 : { proofSnapshotError: snapshotEvidence.error }),
         };
         const schemaStatus = readMigrationConfigStatus(context.workspaceRoot);
+        // implements REQ-agent-guided-migration-orchestration
+        // A schema upgrade plans the source rewrites kibi migrate performs with
+        // it; the planner loads only when an upgrade is due.
+        const sourcePlanner = schemaStatus.needsMigration
+            ? (await import("../../operations/migration/schema6.js"))
+                .buildSchema6MigrationFragment
+            : undefined;
         const migrationPlan = buildActionsFromStatus({
             workspaceRoot: context.workspaceRoot,
             branchAttachment: attachment,
@@ -788,6 +795,14 @@ export async function executeStatus(_input, context) {
                 ? snapshotEvidence.snapshot.hash
                 : null,
             configStatus: schemaStatus,
+            ...(sourcePlanner !== undefined
+                ? {
+                    planSchemaUpgradeSources: (currentSchemaVersion) => sourcePlanner({
+                        workspaceRoot: context.workspaceRoot,
+                        currentSchemaVersion,
+                    }),
+                }
+                : {}),
         });
         const listed = context.fs?.glob
             ? await context.fs.glob([

package/dist/public/operations/migration-plan.d.ts

@@ -87,6 +87,13 @@ export declare function buildActionsFromCoverage(input: {
     repairPlan?: Readonly<Record<string, unknown>>;
     symbolRepairPlan?: Readonly<Record<string, unknown>>;
 }): MigrationAction[];
+/** Source-rewrite actions a schema upgrade performs, as its planner returns them. */
+export type SchemaUpgradeSourceActions = Readonly<{
+    actions: readonly MigrationAction[];
+    /** Automatic actions that rewrite authored sources; the upgrade waits on them. */
+    sourceRewriteActionIds: readonly string[];
+    diagnostics: readonly string[];
+}>;
 export type MigrationConfigStatus = Readonly<{
     status: "missing" | "invalid" | "older" | "current" | "newer";
     currentVersion: number | null;
@@ -108,6 +115,12 @@ export declare function buildActionsFromStatus(input: {
     kbSnapshotId?: string | null;
     workspaceSnapshot?: string | null;
     configStatus?: MigrationConfigStatus;
+    /**
+     * Plans the authored-source rewrites `kibi migrate --yes` performs on its
+     * way to the latest schema (the planner `kibi migrate` itself uses), so
+     * the schema upgrade declares every file it touches. Read-only.
+     */
+    planSchemaUpgradeSources?: (currentSchemaVersion: number | null) => SchemaUpgradeSourceActions;
 }): MigrationPlan;
 export {};
 //# sourceMappingURL=migration-plan.d.ts.map

package/dist/public/operations/migration-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-plan.d.ts","sourceRoot":"","sources":["../../../src/public/operations/migration-plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migration-plan.d.ts","sourceRoot":"","sources":["../../../src/public/operations/migration-plan.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,sBAAsB,EAAG,wBAAiC,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AACvD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAChF,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAC3B,QAAQ,CAAC;IACP,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,KAAK,CAAC;IACZ,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,EAAE,QAAQ,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEP,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EACJ,SAAS,GACT,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,WAAW,GACX,cAAc,GACd,QAAQ,GACR,UAAU,GACV,OAAO,GACP,SAAS,CAAC;IACd,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,UAAU,EAAE,mBAAmB,CAAC;IAChC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,cAAc,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC7D,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,cAAc,EAAE,OAAO,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACtD,CAAC,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACvD,QAAQ,EAAE,QAAQ,CAAC;QACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,KAAK,EAAE,QAAQ,CAAC;QACd,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;QACpC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;QACrC,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC,CAAC;IACH,OAAO,EAAE,QAAQ,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,oBAAoB,EAAE,MAAM,CAAC;KAC9B,CAAC,CAAC;IACH,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH,KAAK,SAAS,GAAG,QAAQ,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IAC9C,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC,CAAC;AAuBH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAIxD;AAeD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,GACzC,MAAM,CAOR;AAuED,wBAAgB,kBAAkB,CAAC,KAAK,GAAE,SAAc,GAAG,aAAa,CAsCvE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,aAAa,EAAE,GAC9B,aAAa,CA0Bf;AAED;;;GAGG;AAEH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GACzB,aAAa,CASf;AA6BD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,MAAM,CAAC,GACrE,eAAe,CAEjB;AAkDD,uEAAuE;AACvE,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E,sEAAsE;AACtE,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AA4D9E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,UAAU,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC1D,kBAAkB,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CACnE,GAAG,eAAe,EAAE,CAqEpB;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC/C,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD,GAAG,eAAe,EAAE,CAgFpB;AAED,qFAAqF;AACrF,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,kFAAkF;IAClF,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IAC9D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,GACpB,qBAAqB,CA8BvB;AAwBD,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAcnD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD,YAAY,CAAC,EAAE,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;IAC5D,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,CACzB,oBAAoB,EAAE,MAAM,GAAG,IAAI,KAChC,0BAA0B,CAAC;CACjC,GAAG,aAAa,CA0VhB"}

package/dist/public/operations/migration-plan.js

@@ -521,6 +521,7 @@ const RESYNC_REASON_CODES = new Set([
 ]);
 export function buildActionsFromStatus(input) {
     const actions = [];
+    const diagnostics = [];
     const attachment = input.branchAttachment;
     const store = input.branchStore;
     const configStatus = input.configStatus ?? readMigrationConfigStatus(input.workspaceRoot);
@@ -611,6 +612,20 @@ export function buildActionsFromStatus(input) {
     }
     if (configStatus.needsMigration || legacyStorageMigrationRequired) {
         const operatorOnly = configStatus.status === "newer" || legacyStorageBlocked;
+        // implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration
+        // The source rewrites the migrate run performs (legacy-link marks, origin
+        // backfill, lifecycle repairs, ...) are planned as their own actions with
+        // their own files, and the upgrade waits on them, so approving it means
+        // approving them. Knowledge still outside .kb/ is planned after it moves.
+        const sources = !operatorOnly &&
+            !legacyStorageMigrationRequired &&
+            input.planSchemaUpgradeSources !== undefined
+            ? input.planSchemaUpgradeSources(configStatus.currentVersion)
+            : null;
+        if (sources !== null) {
+            actions.push(...sources.actions);
+            diagnostics.push(...sources.diagnostics);
+        }
         actions.push(migrationAction({
             id: "schema-config-upgrade",
             code: configStatus.status === "invalid"
@@ -631,11 +646,20 @@ export function buildActionsFromStatus(input) {
                 ".kb/manifest.json",
                 ".kb/migrations",
                 ".kb/config.json",
+                // The migrate run keeps the canonical derived entries ignored.
+                ".gitignore",
+                // Unplanned source rewrites can touch any authored .kb/ file.
+                ...(sources === null ? [".kb/"] : []),
                 ...legacyStorage.moves.map((move) => move.from),
                 ...legacyStorage.removals.map((removal) => removal.path),
             ],
             evidence: {
                 configStatus,
+                ...(sources === null
+                    ? {
+                        sourceRewrites: "Not planned as separate actions: kibi migrate --yes also marks coarse symbol links legacy-link, backfills origin and repairs lifecycle findings in authored .kb/ sources. The plan lists them as their own actions once the upgrade can run automatically on the canonical .kb/ layout.",
+                    }
+                    : {}),
                 ...(legacyStorageMigrationRequired
                     ? {
                         legacyStorage: {
@@ -648,7 +672,10 @@ export function buildActionsFromStatus(input) {
                     }
                     : {}),
             },
-            dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
+            dependsOn: [
+                ...(storeState === "missing" ? ["branch-store-ensure"] : []),
+                ...(sources?.sourceRewriteActionIds ?? []),
+            ],
             autoApplicable: !operatorOnly,
         }));
     }
@@ -784,5 +811,6 @@ export function buildActionsFromStatus(input) {
         ],
         incompleteDomains,
         actions,
+        diagnostics,
     });
 }

package/dist/public/operations/specs/semantic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/semantic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,mBAAmB,EACnB,8BAA8B,EAC/B,MAAM,+CAA+C,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAmB5D,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,8BAA8B,CAAC,CA2FzC;AAED,iBAAe,2BAA2B,CACxC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,8BAA8B,CAAC,CAiCzC;AAED,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2EE,CAAC"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../../../src/public/operations/specs/semantic.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,mBAAmB,EACnB,8BAA8B,EAE/B,MAAM,+CAA+C,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAc,MAAM,qBAAqB,CAAC;AA8CxE,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,8BAA8B,CAAC,CAiGzC;AAED,iBAAe,2BAA2B,CACxC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,8BAA8B,CAAC,CAiCzC;AAED,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2EE,CAAC"}

package/dist/public/operations/specs/semantic.js

@@ -1,5 +1,6 @@
 import { InputError } from "../../../cli-errors.js";
 import { analyzeSemanticAdvisorInputWithPlugins } from "../../../operations/semantic-advisor/plugin-orchestration.js";
+import { storedLedgerDriftWarning } from "../../../operations/semantic-advisor/stored-ledger-drift.js";
 import { publicCapabilityStamp } from "../../../plugins/compose-semantic-classifier.js";
 function requiredText(value) {
     const text = typeof value === "string" ? value.trim() : "";
@@ -12,6 +13,29 @@ function optionalString(value) {
     const text = typeof value === "string" ? value.trim() : "";
     return text || undefined;
 }
+/**
+ * The stored-ledger comparison runs only for a requirement the caller named
+ * and only when the host can open the branch engine; analysis without a KB
+ * (a preview, a unit test, a workspace before `kibi sync`) stays as it was.
+ * A store that cannot be read is not an analysis failure, so the warning is
+ * simply absent then.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+async function storedLedgerWarnings(args, text, receipt, context) {
+    const id = optionalString(args.id);
+    if (!id || (optionalString(args.type) ?? "req") !== "req")
+        return [];
+    try {
+        const prolog = context?.prolog ?? (await context?.ensureProlog?.());
+        if (!prolog)
+            return [];
+        const warning = await storedLedgerDriftWarning(prolog, id, text, receipt);
+        return warning ? [warning] : [];
+    }
+    catch {
+        return [];
+    }
+}
 export async function executeSemanticAdvisor(args, context) {
     const text = requiredText(args.text);
     const id = optionalString(args.id) ?? "REQ-SEMANTIC-ADVISOR-PREVIEW";
@@ -39,6 +63,7 @@ export async function executeSemanticAdvisor(args, context) {
             : {}),
     });
     const result = orchestrated.analysis;
+    const ledgerWarnings = await storedLedgerWarnings(args, text, result.receipt, context);
     const pluginWarnings = orchestrated.stamps.length > 0
         ? [
             `Capability plugins consulted: ${orchestrated.stamps
@@ -87,7 +112,7 @@ export async function executeSemanticAdvisor(args, context) {
         ],
         structuredContent: {
             receipt: result.receipt,
-            warnings: [...result.warnings, ...pluginWarnings],
+            warnings: [...result.warnings, ...ledgerWarnings, ...pluginWarnings],
             ...(capabilityPlugins ? { capabilityPlugins } : {}),
         },
     };

package/dist/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.16.0
+version: 2.16.1
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -286,8 +286,13 @@ authored. Each one is the order the write path accepts.
    existing entity, whose stored ledger Kibi keeps.
 2. **Changing the text of a grounded requirement.** New prose means new
    claim keys, so a bare rewrite is refused with `modeled proposition
-   claim_keys must match logical grounding target claim_keys exactly`.
-   Prefer supersession for a change of meaning: analyze the new prose,
+   claim_keys must match logical grounding target claim_keys exactly`; the
+   error names the modeled keys no fact declares and the facts whose keys
+   the ledger dropped. Analyze the new prose with the requirement's `id`
+   first: the receipt warns `Claim-key drift against the stored ledger`
+   and names the grounded clauses the new wording drops (the title worded
+   differently from the stored `semantic_text` is the usual cause), before
+   any write. Prefer supersession for a change of meaning: analyze the new prose,
    write its facts, write the new requirement (`-v2`) with `supersedes` to
    the old one, then set the old one to `status: closed`. Its scenario
    follows the same rule as in recipe 1: create the new scenario (with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-cli",
-  "version": "2.22.0",
+  "version": "2.22.1",
   "type": "module",
   "description": "Kibi CLI for knowledge base management",
   "engines": {

package/src/public/operations/decision-firmness.ts

@@ -63,6 +63,16 @@ export const DECISION_FIRMNESS_RULES = [
 
 const DECISION_LANES = ["requirements", "adr"] as const;
 
+/** The schema version from which a supersede must explain itself. */
+const SUPERSEDES_REASON_SCHEMA_VERSION = 9;
+
+/**
+ * Told on a KB older than schema 9: the pending schema upgrade acknowledges
+ * supersedes recorded before the rule existed, so no edit is required now.
+ */
+const PRE_SCHEMA9_SUPERSEDES_NOTE =
+  " Supersedes recorded before schema 9 are acknowledged by the plan's schema-config-upgrade (kibi migrate --yes); add the reason only when you next touch the requirement.";
+
 /** Every authored requirement and ADR. */
 // implements REQ-kb-decision-firmness
 export function listDecisionEntities(workspaceRoot: string): AuthoredEntity[] {
@@ -164,7 +174,11 @@ export function evaluateDecisionFirmness(
   edges: ReadonlyMap<string, Set<string>>,
   rules: ReadonlySet<string> = new Set(DECISION_FIRMNESS_RULES),
   acknowledged: ReadonlySet<string> = new Set(),
+  options: Readonly<{ schemaVersion?: number | null }> = {},
 ): Violation[] {
+  const preSchema9 =
+    typeof options.schemaVersion === "number" &&
+    options.schemaVersion < SUPERSEDES_REASON_SCHEMA_VERSION;
   const findings: Violation[] = [];
   const superseded = supersededIds(edges);
   const byId = new Map(entities.map((entity) => [entity.id, entity]));
@@ -241,7 +255,7 @@ export function evaluateDecisionFirmness(
         rule: SUPERSEDES_REASON_MISSING_RULE,
         entityId: entity.id,
         description: `${entity.id} supersedes ${unacknowledged.join(", ")} without a '## ${WHY_THIS_CHANGED_HEADING}' section of at least ${MIN_WHY_CHANGED_WORDS} words`,
-        suggestion: `Add '## ${WHY_THIS_CHANGED_HEADING}' to the body: name the evidence (a failing test, a measured cost, a constraint the old decision missed, a new requirement) and answer the superseded decision's reasoning. A preference is not evidence; propose it instead of superseding.`,
+        suggestion: `Add '## ${WHY_THIS_CHANGED_HEADING}' to the body: name the evidence (a failing test, a measured cost, a constraint the old decision missed, a new requirement) and answer the superseded decision's reasoning. A preference is not evidence; propose it instead of superseding.${preSchema9 ? PRE_SCHEMA9_SUPERSEDES_NOTE : ""}`,
         source: entity.path,
         evidence: { type: entity.type, supersedes: unacknowledged },
       });
@@ -271,10 +285,12 @@ export function collectDecisionFirmnessViolations(
 ): Violation[] {
   if (!DECISION_FIRMNESS_RULES.some((rule) => rules.has(rule))) return [];
   const entities = listDecisionEntities(workspaceRoot);
+  const manifest = readKbManifest(workspaceRoot);
   return evaluateDecisionFirmness(
     entities,
     authoredSupersedes(workspaceRoot, entities),
     rules,
-    new Set(readKbManifest(workspaceRoot)?.supersedesReasonAcknowledged ?? []),
+    new Set(manifest?.supersedesReasonAcknowledged ?? []),
+    { schemaVersion: manifest?.schemaVersion ?? null },
   );
 }

package/src/public/operations/discovery-executors.ts

@@ -1121,6 +1121,13 @@ export async function executeStatus(
         : { proofSnapshotError: snapshotEvidence.error }),
     };
     const schemaStatus = readMigrationConfigStatus(context.workspaceRoot);
+    // implements REQ-agent-guided-migration-orchestration
+    // A schema upgrade plans the source rewrites kibi migrate performs with
+    // it; the planner loads only when an upgrade is due.
+    const sourcePlanner = schemaStatus.needsMigration
+      ? (await import("../../operations/migration/schema6.js"))
+          .buildSchema6MigrationFragment
+      : undefined;
     const migrationPlan = buildActionsFromStatus({
       workspaceRoot: context.workspaceRoot,
       branchAttachment: attachment,
@@ -1135,6 +1142,15 @@ export async function executeStatus(
         ? snapshotEvidence.snapshot.hash
         : null,
       configStatus: schemaStatus,
+      ...(sourcePlanner !== undefined
+        ? {
+            planSchemaUpgradeSources: (currentSchemaVersion: number | null) =>
+              sourcePlanner({
+                workspaceRoot: context.workspaceRoot,
+                currentSchemaVersion,
+              }),
+          }
+        : {}),
     });
     const listed = context.fs?.glob
       ? await context.fs.glob(

package/src/public/operations/migration-plan.ts

@@ -616,6 +616,14 @@ export function buildActionsFromCoverage(input: {
   return actions;
 }
 
+/** Source-rewrite actions a schema upgrade performs, as its planner returns them. */
+export type SchemaUpgradeSourceActions = Readonly<{
+  actions: readonly MigrationAction[];
+  /** Automatic actions that rewrite authored sources; the upgrade waits on them. */
+  sourceRewriteActionIds: readonly string[];
+  diagnostics: readonly string[];
+}>;
+
 export type MigrationConfigStatus = Readonly<{
   status: "missing" | "invalid" | "older" | "current" | "newer";
   currentVersion: number | null;
@@ -706,8 +714,17 @@ export function buildActionsFromStatus(input: {
   kbSnapshotId?: string | null;
   workspaceSnapshot?: string | null;
   configStatus?: MigrationConfigStatus;
+  /**
+   * Plans the authored-source rewrites `kibi migrate --yes` performs on its
+   * way to the latest schema (the planner `kibi migrate` itself uses), so
+   * the schema upgrade declares every file it touches. Read-only.
+   */
+  planSchemaUpgradeSources?: (
+    currentSchemaVersion: number | null,
+  ) => SchemaUpgradeSourceActions;
 }): MigrationPlan {
   const actions: MigrationAction[] = [];
+  const diagnostics: string[] = [];
   const attachment = input.branchAttachment;
   const store = input.branchStore;
   const configStatus =
@@ -813,6 +830,21 @@ export function buildActionsFromStatus(input: {
   if (configStatus.needsMigration || legacyStorageMigrationRequired) {
     const operatorOnly =
       configStatus.status === "newer" || legacyStorageBlocked;
+    // implements REQ-agent-guided-migration-orchestration, REQ-cli-schema-migration
+    // The source rewrites the migrate run performs (legacy-link marks, origin
+    // backfill, lifecycle repairs, ...) are planned as their own actions with
+    // their own files, and the upgrade waits on them, so approving it means
+    // approving them. Knowledge still outside .kb/ is planned after it moves.
+    const sources =
+      !operatorOnly &&
+      !legacyStorageMigrationRequired &&
+      input.planSchemaUpgradeSources !== undefined
+        ? input.planSchemaUpgradeSources(configStatus.currentVersion)
+        : null;
+    if (sources !== null) {
+      actions.push(...sources.actions);
+      diagnostics.push(...sources.diagnostics);
+    }
     actions.push(
       migrationAction({
         id: "schema-config-upgrade",
@@ -835,11 +867,21 @@ export function buildActionsFromStatus(input: {
           ".kb/manifest.json",
           ".kb/migrations",
           ".kb/config.json",
+          // The migrate run keeps the canonical derived entries ignored.
+          ".gitignore",
+          // Unplanned source rewrites can touch any authored .kb/ file.
+          ...(sources === null ? [".kb/"] : []),
           ...legacyStorage.moves.map((move) => move.from),
           ...legacyStorage.removals.map((removal) => removal.path),
         ],
         evidence: {
           configStatus,
+          ...(sources === null
+            ? {
+                sourceRewrites:
+                  "Not planned as separate actions: kibi migrate --yes also marks coarse symbol links legacy-link, backfills origin and repairs lifecycle findings in authored .kb/ sources. The plan lists them as their own actions once the upgrade can run automatically on the canonical .kb/ layout.",
+              }
+            : {}),
           ...(legacyStorageMigrationRequired
             ? {
                 legacyStorage: {
@@ -852,7 +894,10 @@ export function buildActionsFromStatus(input: {
               }
             : {}),
         },
-        dependsOn: storeState === "missing" ? ["branch-store-ensure"] : [],
+        dependsOn: [
+          ...(storeState === "missing" ? ["branch-store-ensure"] : []),
+          ...(sources?.sourceRewriteActionIds ?? []),
+        ],
         autoApplicable: !operatorOnly,
       }),
     );
@@ -1021,5 +1066,6 @@ export function buildActionsFromStatus(input: {
     ],
     incompleteDomains,
     actions,
+    diagnostics,
   });
 }

package/src/public/operations/specs/semantic.ts

@@ -1,11 +1,13 @@
 import { InputError } from "../../../cli-errors.js";
 import { analyzeSemanticAdvisorInputWithPlugins } from "../../../operations/semantic-advisor/plugin-orchestration.js";
+import { storedLedgerDriftWarning } from "../../../operations/semantic-advisor/stored-ledger-drift.js";
 import type {
   SemanticAdvisorArgs,
   SemanticAdvisorOperationResult,
+  SemanticAdvisorReceipt,
 } from "../../../operations/semantic-advisor/types.js";
 import { publicCapabilityStamp } from "../../../plugins/compose-semantic-classifier.js";
-import type { OperationContext } from "../runtime-types.js";
+import type { OperationContext, PrologPort } from "../runtime-types.js";
 import type { OperationSpec } from "../types.js";
 
 function requiredText(value: unknown): string {
@@ -24,6 +26,33 @@ function optionalString(value: unknown): string | undefined {
   return text || undefined;
 }
 
+/**
+ * The stored-ledger comparison runs only for a requirement the caller named
+ * and only when the host can open the branch engine; analysis without a KB
+ * (a preview, a unit test, a workspace before `kibi sync`) stays as it was.
+ * A store that cannot be read is not an analysis failure, so the warning is
+ * simply absent then.
+ */
+// implements REQ-kibi-proposition-complete-ingestion
+async function storedLedgerWarnings(
+  args: SemanticAdvisorArgs,
+  text: string,
+  receipt: SemanticAdvisorReceipt,
+  context?: OperationContext,
+): Promise<readonly string[]> {
+  const id = optionalString(args.id);
+  if (!id || (optionalString(args.type) ?? "req") !== "req") return [];
+  try {
+    const prolog: PrologPort | undefined =
+      context?.prolog ?? (await context?.ensureProlog?.());
+    if (!prolog) return [];
+    const warning = await storedLedgerDriftWarning(prolog, id, text, receipt);
+    return warning ? [warning] : [];
+  } catch {
+    return [];
+  }
+}
+
 export async function executeSemanticAdvisor(
   args: SemanticAdvisorArgs,
   context?: OperationContext,
@@ -57,6 +86,12 @@ export async function executeSemanticAdvisor(
     },
   );
   const result = orchestrated.analysis;
+  const ledgerWarnings = await storedLedgerWarnings(
+    args,
+    text,
+    result.receipt,
+    context,
+  );
   const pluginWarnings =
     orchestrated.stamps.length > 0
       ? [
@@ -114,7 +149,7 @@ export async function executeSemanticAdvisor(
     ],
     structuredContent: {
       receipt: result.receipt,
-      warnings: [...result.warnings, ...pluginWarnings],
+      warnings: [...result.warnings, ...ledgerWarnings, ...pluginWarnings],
       ...(capabilityPlugins ? { capabilityPlugins } : {}),
     },
   };

package/src/public/skills/kibi-usage/SKILL.md

@@ -2,7 +2,7 @@
 id: kibi-usage
 name: Kibi Usage
 description: Use Kibi's source-first, exact-Git, migration-aware, proof-aware operations safely across MCP or the trusted local CLI, including partial completion repair.
-version: 2.16.0
+version: 2.16.1
 kibiCompatibility: ">=1.0.0"
 tags:
   - kibi
@@ -286,8 +286,13 @@ authored. Each one is the order the write path accepts.
    existing entity, whose stored ledger Kibi keeps.
 2. **Changing the text of a grounded requirement.** New prose means new
    claim keys, so a bare rewrite is refused with `modeled proposition
-   claim_keys must match logical grounding target claim_keys exactly`.
-   Prefer supersession for a change of meaning: analyze the new prose,
+   claim_keys must match logical grounding target claim_keys exactly`; the
+   error names the modeled keys no fact declares and the facts whose keys
+   the ledger dropped. Analyze the new prose with the requirement's `id`
+   first: the receipt warns `Claim-key drift against the stored ledger`
+   and names the grounded clauses the new wording drops (the title worded
+   differently from the stored `semantic_text` is the usual cause), before
+   any write. Prefer supersession for a change of meaning: analyze the new prose,
    write its facts, write the new requirement (`-v2`) with `supersedes` to
    the old one, then set the old one to `status: closed`. Its scenario
    follows the same rule as in recipe 1: create the new scenario (with