kibi-cli 2.21.0 → 2.21.2

package/dist/cli-operation-metadata.d.ts

@@ -75,7 +75,7 @@ export declare const CLI_OPERATION_METADATA: readonly [{
 }, {
     readonly name: "kb_delete";
     readonly cliName: "delete";
-    readonly description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.";
+    readonly description: "Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.";
 }, {
     readonly name: "kb_check";
     readonly cliName: "check";

package/dist/cli-operation-metadata.js

@@ -90,7 +90,7 @@ export const CLI_OPERATION_METADATA = [
     {
         name: "kb_delete",
         cliName: "delete",
-        description: "Delete entities by ID. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. Side effects: mutates and saves KB; skips entities with dependents.",
+        description: "Delete entities by ID, or exact relationship triples. Use only for intentional removals after dependency checks. Do not use as a bulk cleanup shortcut. An entity authored in a Markdown or YAML source is not deleted directly: the call writes nothing and returns outcome plan_returned with a hash-bound deletionPlan and a nextActions entry holding the exact kb_apply_plan input ({plan, approvedPlanHash}); apply that unmodified, or repeat this call with approvedPlanHash = deletionPlan.planHash to apply the freshly computed plan in one step (a stale or different hash fails with DELETE_PLAN_HASH_MISMATCH and writes nothing). Authored requirements are never deleted: outcome supersession_required points to kb_upsert with a supersedes relationship. dryRun:true previews any delete and writes nothing. Side effects: mutates and saves KB and authored sources; skips entities with dependents; dryRun and plan_returned write nothing.",
     },
     {
         name: "kb_check",

package/dist/commands/doctor.js

@@ -598,10 +598,15 @@ function checkKbDirectory() {
 function checkKbManifest() {
     const status = readKbManifestStatus(process.cwd());
     if (status.state === "missing") {
+        // 'kibi init' on a legacy layout would claim the latest schema and skip
+        // the legacy migration steps; migrate writes the manifest itself.
+        const legacy = planLegacyStorageMigration(process.cwd());
         return {
             passed: false,
             message: "Not found",
-            remediation: "Run: kibi init",
+            remediation: legacy.legacyConfig === "absent"
+                ? "Run: kibi init"
+                : "Run: kibi migrate --yes (it creates the manifest from the legacy .kb/config.json; do not run kibi init first)",
         };
     }
     if (status.state !== "ok") {
@@ -626,6 +631,13 @@ function checkLegacyStorage() {
                 "Repair or remove the legacy .kb/config.json, then run: kibi migrate --yes",
         };
     }
+    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`,
+        };
+    }
     if (plan.legacyConfig === "present" || plan.moves.length > 0) {
         return {
             passed: false,

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

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

package/dist/commands/init.js

@@ -21,6 +21,7 @@ import { fileURLToPath } from "node:url";
 import { classifyActivation } from "../operations/bootstrap/activation.js";
 import { nodeFilesystem } from "../public/operations/node-ports.js";
 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";
@@ -172,14 +173,23 @@ export async function initCommand(options) {
         }
         // A directory left by a tool or interrupted setup is not a complete KB.
         // Reconcile missing infrastructure on every invocation, preserving sources.
+        // A legacy .kb/config.json belongs to 'kibi migrate': a fresh manifest
+        // would claim the latest schema (skipping the legacy steps) and a fresh
+        // symbols manifest would block the move of the real one.
+        const legacyConfig = readLegacyKbConfig(projectRoot).kind !== "none";
         createKbDirectoryStructure(kbDir, currentBranch);
-        if (!existsSync(path.join(kbDir, "manifest.json"))) {
+        if (!legacyConfig && !existsSync(path.join(kbDir, "manifest.json"))) {
             createManifestFile(kbDir);
         }
         updateGitIgnore(projectRoot);
         const schemaSourceDir = path.resolve(__dirname, "..", "..", "schema");
         await copySchemaFiles(kbDir, schemaSourceDir);
-        ensureSymbolsManifestFile(projectRoot);
+        if (legacyConfig) {
+            console.log("! Legacy .kb/config.json found; left .kb/manifest.json and .kb/symbols.yaml to 'kibi migrate --yes', which moves the existing knowledge and runs every schema step.");
+        }
+        else {
+            ensureSymbolsManifestFile(projectRoot);
+        }
         if (options.hooks) {
             if (!repoContext) {
                 console.error("Warning: No git repository found, skipping hooks");
@@ -209,7 +219,9 @@ export async function initCommand(options) {
         if (kbExists) {
             console.log("  Existing Kibi source knowledge was preserved.");
         }
-        console.log((await initNextAction(projectRoot)).message);
+        console.log(legacyConfig
+            ? "  Next: run 'kibi migrate --yes' to move the legacy knowledge into .kb/."
+            : (await initNextAction(projectRoot)).message);
         console.log("  Optional diagnostic: run 'kibi doctor' if setup appears degraded.");
         if (options.github === true) {
             scaffoldGitHubIntegration({

package/dist/commands/legacy-storage-migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacy-storage-migration.d.ts","sourceRoot":"","sources":["../../src/commands/legacy-storage-migration.ts"],"names":[],"mappings":"AAoCA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxD,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B;AA2BD,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAqH5E;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAqDxB;AA+BD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AAED,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAI/D"}
+{"version":3,"file":"legacy-storage-migration.d.ts","sourceRoot":"","sources":["../../src/commands/legacy-storage-migration.ts"],"names":[],"mappings":"AAoCA,OAAO,EACL,KAAK,uBAAuB,EAI7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAI9B;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,4CAA4C;IAC5C,YAAY,EAAE,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IACjD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uBAAuB,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACxD,kEAAkE;IAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9B;AA2BD,6DAA6D;AAC7D,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAwH5E;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CAClD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,oBAAoB,GACzB,sBAAsB,CAwDxB;AA+BD,wEAAwE;AACxE,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,SAAS,oBAAoB,EAAE,GACrC,MAAM,CAwCR;AA8BD,wEAAwE;AACxE,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOhE;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,CAI/D"}

package/dist/commands/legacy-storage-migration.js

@@ -128,6 +128,9 @@ export function planLegacyStorageMigration(cwd) {
         const destinationAbsolute = path.resolve(cwd, move.to);
         if (!existsSync(destinationAbsolute))
             continue;
+        // 'kibi init' seeds an empty symbols manifest; the legacy one replaces it.
+        if (move.lane === "symbols" && isEmptySymbolsStub(destinationAbsolute))
+            continue;
         blockers.push(`Destination ${move.to} already exists; resolve the conflict manually before migrating ${move.from}.`);
     }
     // Duplicate destinations (two legacy sources collapsing onto one target).
@@ -174,10 +177,13 @@ export function applyLegacyStorageMigration(cwd, plan) {
     const backfill = plan.semanticAdvisorBackfill ??
         existing?.semanticAdvisorBackfill ??
         "pending";
+    // Record the generation the knowledge was written for, not the latest
+    // one: 'kibi migrate' raises it after the schema steps, so a run
+    // interrupted between the move and those steps still replays them.
     const manifest = {
         ...(existing ?? defaultKbManifest()),
         manifestVersion: defaultKbManifest().manifestVersion,
-        schemaVersion: LATEST_KB_SCHEMA_VERSION,
+        schemaVersion: sourceSchemaVersion(plan.schemaVersion, existing),
         semanticAdvisorBackfill: backfill,
     };
     const manifestPath = writeKbManifest(cwd, manifest);
@@ -264,6 +270,25 @@ export function rewritePendingSourceReceiptPaths(cwd, moves) {
     }
     return rewritten;
 }
+// implements REQ-cli-schema-migration
+function isEmptySymbolsStub(filePath) {
+    try {
+        const statements = readFileSync(filePath, "utf8")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith("#"));
+        return (statements.length === 1 &&
+            /^symbols:\s*\[\s*\]$/.test(statements[0] ?? ""));
+    }
+    catch {
+        return false;
+    }
+}
+// implements REQ-cli-schema-migration
+function sourceSchemaVersion(legacyVersion, existing) {
+    const known = [legacyVersion, existing?.schemaVersion].filter((version) => typeof version === "number" && Number.isInteger(version) && version > 0);
+    return known.length > 0 ? Math.min(...known) : LATEST_KB_SCHEMA_VERSION;
+}
 /** True when the workspace still needs the legacy storage migration. */
 export function needsLegacyStorageMigration(cwd) {
     const plan = planLegacyStorageMigration(cwd);

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

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAiEA,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;AAuKD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsXD,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,CAiW/B"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAkEA,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;AA8KD,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,MAAM,CAUR;AAsXD,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,CAgZ/B"}

package/dist/commands/migrate.js

@@ -15,6 +15,7 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { load as parseYAML } from "js-yaml";
@@ -79,6 +80,12 @@ const SCHEMA_MIGRATION_STEPS = [
         to: 8,
         description: "Pin semantic_text on requirements that lack it (computed from the body before context sections stop counting), and tag current entities without body context review:context-missing; front matter only, bodies are preserved.",
     },
+    {
+        id: "decision-firmness-v9",
+        from: 8,
+        to: 9,
+        description: "Accept firmness on requirements and ADRs, and acknowledge in the manifest the current supersedes recorded without a 'Why this changed' section; no source file is rewritten and no reason is invented.",
+    },
 ];
 function migrationStepsFor(fromVersion) {
     const start = Math.max(0, fromVersion ?? 0);
@@ -421,9 +428,13 @@ export async function migrateCommand(options = {}) {
     }
     const manifestStatus = readKbManifestStatus(cwd);
     const storagePlan = planLegacyStorageMigration(cwd);
-    // Baseline for fresh workspaces driven by the internal plan executor.
+    // Baseline for fresh workspaces driven by the internal plan executor. A
+    // legacy layout carries its own schema generation; a baseline would claim
+    // the latest one and skip every legacy step.
     if (options.initializeMissingConfig === true &&
-        manifestStatus.state === "missing") {
+        manifestStatus.state === "missing" &&
+        storagePlan.moves.length === 0 &&
+        storagePlan.legacyConfig === "absent") {
         writeKbManifest(cwd, defaultKbManifest());
     }
     if (manifestStatus.state === "missing" &&
@@ -435,7 +446,12 @@ export async function migrateCommand(options = {}) {
     const { branch, warnings: branchWarnings } = branchResult;
     const currentManifest = readKbManifest(cwd);
     const legacySchemaVersion = normalizeSchemaVersion(storagePlan.schemaVersion);
-    const currentVersion = currentManifest?.schemaVersion ?? legacySchemaVersion;
+    // While a legacy config is still present, its schemaVersion is the
+    // generation the knowledge was written for; a manifest created beside it
+    // (by an older 'kibi init') must not skip the steps in between.
+    const currentVersion = storagePlan.legacyConfig !== "absent" && legacySchemaVersion !== null
+        ? Math.min(currentManifest?.schemaVersion ?? legacySchemaVersion, legacySchemaVersion)
+        : (currentManifest?.schemaVersion ?? legacySchemaVersion);
     const normalizedVersion = normalizeSchemaVersion(currentVersion);
     const configStatus = getSchemaVersionStatus(normalizedVersion === null
         ? undefined
@@ -503,6 +519,8 @@ export async function migrateCommand(options = {}) {
     const { planPolarityValueBackfill, applyPolarityValueBackfill } = await import("../operations/migration/polarity-values.js");
     const polarityBackfill = planPolarityValueBackfill(cwd);
     const bodyContextStep = migrationSteps.some((step) => step.id === "entity-body-context-v8");
+    const decisionFirmnessStep = migrationSteps.some((step) => step.id === "decision-firmness-v9");
+    const { mergeSupersedesAcknowledgements, planSupersedesReasonAcknowledgement, } = await import("../operations/migration/supersedes-reason.js");
     const { acknowledgedContextIds, applyContextMissingTags, applySemanticTextPins, countByType, planContextMissingTags, planSemanticTextPins, } = await import("../operations/migration/entity-body-context.js");
     if (options.dryRun) {
         if (polarityBackfill.length > 0)
@@ -519,6 +537,11 @@ export async function migrateCommand(options = {}) {
             for (const skip of [...pins.skipped, ...tags.skipped])
                 printWarning(`Cannot edit ${skip.path}: ${skip.reason}.`);
         }
+        if (decisionFirmnessStep) {
+            const unexplained = planSupersedesReasonAcknowledgement(cwd);
+            if (unexplained.length > 0)
+                console.log(`dry run: would acknowledge ${unexplained.length} supersede(s) recorded without a 'Why this changed' section (manifest only; no reason is written).`);
+        }
         if (storagePlan.moves.length > 0) {
             console.log(`dry run: would move ${storagePlan.moves.length} legacy knowledge file(s) into .kb/:`);
             for (const move of storagePlan.moves) {
@@ -558,6 +581,9 @@ export async function migrateCommand(options = {}) {
         const storageResult = applyLegacyStorageMigration(cwd, storagePlan);
         if (storageResult.movedFiles.length > 0) {
             console.log(`Moved ${storageResult.movedFiles.length} knowledge file(s) into the canonical .kb/ layout.`);
+            const untracked = untrackedFiles(cwd, storageResult.movedFiles);
+            if (untracked > 0)
+                printWarning(`${untracked} moved file(s) are not tracked by Git yet, and kibi sync compiles only tracked sources: until you stage them (git add .kb, plus the removals under the legacy folders) the KB compiles without them and plans report them as missing.`);
         }
         if (storageResult.retiredLegacyConfig) {
             console.log("Retired legacy .kb/config.json.");
@@ -599,6 +625,9 @@ export async function migrateCommand(options = {}) {
         : { written: [], skipped: [], previouslyStamped: 0 };
     rederiveDriftedInventories(cwd, false);
     const lifecycle = repairLifecycleFindings(cwd, false);
+    const supersedesUnexplained = decisionFirmnessStep
+        ? planSupersedesReasonAcknowledgement(cwd)
+        : [];
     const existingManifest = readKbManifest(cwd) ?? defaultKbManifest();
     writeKbManifest(cwd, {
         ...existingManifest,
@@ -614,7 +643,14 @@ export async function migrateCommand(options = {}) {
                 ].sort(),
             }
             : {}),
+        ...(supersedesUnexplained.length > 0
+            ? {
+                supersedesReasonAcknowledged: mergeSupersedesAcknowledgements(existingManifest.supersedesReasonAcknowledged, supersedesUnexplained),
+            }
+            : {}),
     });
+    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({
         branch,
         manifestPath: KB_MANIFEST_RELATIVE,
@@ -759,7 +795,53 @@ async function buildWorkspaceMigrationPlan(workspaceRoot = process.cwd()) {
             ],
         });
     }
-    return mergeMigrationPlans(plans);
+    return orderStoreSyncAfterSourceRewrites({ buildMigrationPlan, migrationAction }, mergeMigrationPlans(plans), fragment.sourceRewriteActionIds, fragment.actions
+        .filter((action) => action.code === "semantic_inventory_review")
+        .map((action) => action.id));
+}
+/** Status actions that run 'kibi sync' over the authored sources. */
+const STORE_SYNC_ACTION_IDS = new Set([
+    "branch-store-compile",
+    "freshness-resync",
+]);
+/**
+ * A sync compiles the authored sources, so it must run after the source
+ * rewrites that make them ingestible. While a requirement still needs a
+ * manual inventory review the sync would fail on it, so it waits on that
+ * review just as the migration sync does.
+ */
+// implements REQ-cli-schema-migration
+function orderStoreSyncAfterSourceRewrites(builders, plan, rewriteActionIds, reviewActionIds) {
+    const affected = plan.actions.some((action) => STORE_SYNC_ACTION_IDS.has(action.id) && action.state === "ready");
+    if (!affected ||
+        (rewriteActionIds.length === 0 && reviewActionIds.length === 0))
+        return plan;
+    const actions = plan.actions.map((action) => {
+        if (!STORE_SYNC_ACTION_IDS.has(action.id) || action.state !== "ready")
+            return action;
+        if (reviewActionIds.length > 0)
+            return builders.migrationAction({
+                ...action,
+                state: "blocked",
+                autoApplicable: false,
+                evidence: {
+                    ...action.evidence,
+                    blockedBy: [...reviewActionIds],
+                    reason: "kibi sync rejects a requirement until its semantic inventory review is fixed; rerun kibi migrate afterwards.",
+                },
+            });
+        return builders.migrationAction({
+            ...action,
+            dependsOn: [...action.dependsOn, ...rewriteActionIds],
+        });
+    });
+    return builders.buildMigrationPlan({
+        expected: plan.expected,
+        evaluatedDomains: plan.scope.evaluatedDomains,
+        incompleteDomains: plan.scope.incompleteDomains,
+        actions,
+        diagnostics: plan.diagnostics,
+    });
 }
 /**
  * The action ids approved on the command line. The CLI parser stores
@@ -776,6 +858,42 @@ function approvedActionIdsOf(options) {
         .filter((id) => id.length > 0);
     return [...new Set(ids)];
 }
+/** How many of `files` Git does not track; 0 outside a repository. */
+// implements REQ-cli-schema-migration
+function untrackedFiles(cwd, files) {
+    let tracked;
+    try {
+        tracked = new Set(execFileSync("git", ["-C", cwd, "ls-files", "-z", "--", ".kb"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+        })
+            .split("\0")
+            .filter((file) => file.length > 0));
+    }
+    catch {
+        return 0;
+    }
+    return files.filter((file) => !tracked.has(file)).length;
+}
+/** The table rendering of an apply result; --format json prints it whole. */
+// implements REQ-cli-schema-migration
+function printApplySummary(content) {
+    if (content === null || typeof content !== "object")
+        return;
+    const result = content;
+    if (result.outcome !== undefined)
+        console.log(`Outcome: ${result.outcome}`);
+    for (const action of result.actionResults ?? []) {
+        console.log(`- ${action.outcome} ${action.actionId}: ${action.detail}`);
+    }
+    const remaining = result.remainingPlan;
+    if (remaining !== undefined) {
+        const ready = remaining.actions.filter((action) => action.state === "ready" && action.autoApplicable).length;
+        console.log(`Remaining plan ${remaining.planHash}: ${remaining.status}; actions: ${remaining.summary.actionCount}; automatic-ready: ${ready}`);
+    }
+    console.log("Run 'kibi migrate' for the remaining actions, or add --format json for the full result.");
+}
 async function migratePlanCommand(options) {
     const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
     const plan = await buildWorkspaceMigrationPlan(workspaceRoot);
@@ -830,7 +948,7 @@ async function migratePlanCommand(options) {
         }
         else {
             console.log(result.content[0]?.text ?? "Migration applied.");
-            console.log(JSON.stringify(result.structuredContent, null, 2));
+            printApplySummary(result.structuredContent);
         }
         return {
             exitCode: result.structuredContent?.outcome === "applied" ? 0 : 1,

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2HrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAuFD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA8QvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2HrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAuFD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAoRvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}

package/dist/commands/sync/persistence.js

@@ -377,6 +377,10 @@ prolog, results, entityIds, options = {}) {
             if (entity.type === "req" && entity.proof_exempt !== undefined) {
                 props.push(`proof_exempt=${entity.proof_exempt}`);
             }
+            if ((entity.type === "req" || entity.type === "adr") &&
+                entity.firmness !== undefined) {
+                props.push(`firmness=${toPrologAtom(entity.firmness)}`);
+            }
             if (entity.type === "scenario" && entity.expects !== undefined) {
                 props.push(`expects=${toPrologAtom(entity.expects)}`);
             }

package/dist/decision-firmness.d.ts

@@ -0,0 +1,39 @@
+/** Firmness values, firmest first. */
+export declare const FIRMNESS_VALUES: readonly ["firm", "default", "exploratory"];
+export type Firmness = (typeof FIRMNESS_VALUES)[number];
+/** The firmness of a decision that does not state one. */
+export declare const DEFAULT_FIRMNESS: Firmness;
+/** Entity types that carry firmness. */
+export declare const FIRMNESS_TYPES: readonly ["req", "adr"];
+/** A supersede must explain itself under a heading starting with this. */
+export declare const WHY_THIS_CHANGED_HEADING = "Why this changed";
+/** The explanation needs at least this many words of prose. */
+export declare const MIN_WHY_CHANGED_WORDS = 12;
+/**
+ * How the manifest records one acknowledged supersede edge. Edges, not ids,
+ * are acknowledged, so a supersede added later to the same entity still has
+ * to explain itself.
+ */
+export declare function supersedeAcknowledgement(from: string, to: string): string;
+export declare function isFirmness(value: unknown): value is Firmness;
+export declare function carriesFirmness(type: unknown): boolean;
+/**
+ * The firmness a decision is read with: the authored value, else `default`.
+ * Undefined for types that carry no firmness.
+ */
+export declare function effectiveFirmness(type: unknown, value: unknown): Firmness | undefined;
+/**
+ * The reference that makes a firm decision traceable to a human's words:
+ * `origin.ref`, or `approval_ref` on a requirement.
+ */
+export declare function firmnessRef(entity: {
+    type?: unknown;
+    origin?: unknown;
+    approval_ref?: unknown;
+}): string | undefined;
+/**
+ * Words of prose under the body's "Why this changed" heading (nested
+ * headings included), or 0 when the body has no such section.
+ */
+export declare function whyThisChangedWords(body: string): number;
+//# sourceMappingURL=decision-firmness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decision-firmness.d.ts","sourceRoot":"","sources":["../src/decision-firmness.ts"],"names":[],"mappings":"AA4BA,sCAAsC;AAEtC,eAAO,MAAM,eAAe,6CAA8C,CAAC;AAG3E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,0DAA0D;AAE1D,eAAO,MAAM,gBAAgB,EAAE,QAAoB,CAAC;AAEpD,wCAAwC;AAExC,eAAO,MAAM,cAAc,yBAA0B,CAAC;AAEtD,0EAA0E;AAE1E,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D,+DAA+D;AAE/D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAIxC;;;;GAIG;AAEH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAEzE;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAK5D;AAGD,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKtD;AAED;;;GAGG;AAEH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,QAAQ,GAAG,SAAS,CAGtB;AAED;;;GAGG;AAEH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAClC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,GAAG,SAAS,CAcrB;AAMD;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkBxD"}

package/dist/decision-firmness.js

@@ -0,0 +1,115 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+/**
+ * Decision firmness: how firmly a requirement or ADR was decided, which tells
+ * a later agent whether it may supersede the decision on evidence or must ask
+ * a human first. This module is the one place that knows the values, the
+ * default and what a supersede must explain, so extraction, checks, search,
+ * query and migration agree.
+ */
+import { parseBodySections } from "./entity-body-context.js";
+/** Firmness values, firmest first. */
+// implements REQ-kb-decision-firmness
+export const FIRMNESS_VALUES = ["firm", "default", "exploratory"];
+/** The firmness of a decision that does not state one. */
+// implements REQ-kb-decision-firmness
+export const DEFAULT_FIRMNESS = "default";
+/** Entity types that carry firmness. */
+// implements REQ-kb-decision-firmness
+export const FIRMNESS_TYPES = ["req", "adr"];
+/** A supersede must explain itself under a heading starting with this. */
+// implements REQ-kb-decision-firmness
+export const WHY_THIS_CHANGED_HEADING = "Why this changed";
+/** The explanation needs at least this many words of prose. */
+// implements REQ-kb-decision-firmness
+export const MIN_WHY_CHANGED_WORDS = 12;
+const WHY_THIS_CHANGED = /^why\s+this\s+changed\b/i;
+/**
+ * How the manifest records one acknowledged supersede edge. Edges, not ids,
+ * are acknowledged, so a supersede added later to the same entity still has
+ * to explain itself.
+ */
+// implements REQ-kb-decision-firmness
+export function supersedeAcknowledgement(from, to) {
+    return `${from} -> ${to}`;
+}
+// implements REQ-kb-decision-firmness
+export function isFirmness(value) {
+    return (typeof value === "string" &&
+        FIRMNESS_VALUES.includes(value));
+}
+// implements REQ-kb-decision-firmness
+export function carriesFirmness(type) {
+    return (typeof type === "string" &&
+        FIRMNESS_TYPES.includes(type));
+}
+/**
+ * The firmness a decision is read with: the authored value, else `default`.
+ * Undefined for types that carry no firmness.
+ */
+// implements REQ-kb-decision-firmness
+export function effectiveFirmness(type, value) {
+    if (!carriesFirmness(type))
+        return undefined;
+    return isFirmness(value) ? value : DEFAULT_FIRMNESS;
+}
+/**
+ * The reference that makes a firm decision traceable to a human's words:
+ * `origin.ref`, or `approval_ref` on a requirement.
+ */
+// implements REQ-kb-decision-firmness
+export function firmnessRef(entity) {
+    const origin = entity.origin;
+    if (origin !== null && typeof origin === "object") {
+        const ref = origin.ref;
+        if (typeof ref === "string" && ref.trim() !== "")
+            return ref.trim();
+    }
+    if (entity.type === "req" &&
+        typeof entity.approval_ref === "string" &&
+        entity.approval_ref.trim() !== "") {
+        return entity.approval_ref.trim();
+    }
+    return undefined;
+}
+function wordCount(text) {
+    return text.split(/\s+/).filter((word) => /[\p{L}\p{N}]/u.test(word)).length;
+}
+/**
+ * Words of prose under the body's "Why this changed" heading (nested
+ * headings included), or 0 when the body has no such section.
+ */
+// implements REQ-kb-decision-firmness
+export function whyThisChangedWords(body) {
+    const sections = parseBodySections(body);
+    let level = null;
+    let words = 0;
+    for (const section of sections) {
+        if (level !== null && section.level > 0 && section.level <= level) {
+            level = null;
+        }
+        if (level === null &&
+            section.level > 0 &&
+            WHY_THIS_CHANGED.test(section.heading.replace(/^[*_`\s]+/, ""))) {
+            level = section.level;
+        }
+        if (level !== null)
+            words += wordCount(section.text);
+    }
+    return words;
+}

package/dist/extractors/markdown.d.ts

@@ -1,3 +1,4 @@
+import { type Firmness } from "../decision-firmness.js";
 import { type EntityOrigin } from "../public/entity-origin.js";
 import { type ProofBinding, type ProofContract } from "../public/proof-protocol.js";
 import { type ProofReceipt } from "../public/proof-receipt.js";
@@ -15,6 +16,7 @@ export interface ExtractedEntity {
     severity?: string;
     text_ref?: string;
     origin?: EntityOrigin;
+    firmness?: Firmness;
     semantic_text?: string;
     logic_claims?: string[];
     semantic_clauses?: string[];

package/dist/extractors/markdown.d.ts.map

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

package/dist/extractors/markdown.js

@@ -19,6 +19,7 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import Ajv from "ajv";
 import { load as yamlLoad } from "js-yaml";
+import { FIRMNESS_VALUES, carriesFirmness, isFirmness, } from "../decision-firmness.js";
 import { withoutContextSections } from "../entity-body-context.js";
 import { deriveFactClaimKey, semanticClaimKey, } from "../operations/semantic-advisor/clauses.js";
 import { normalizeEntityOrigin, } from "../public/entity-origin.js";
@@ -511,6 +512,19 @@ function extractFromMarkdownContent(content, filePath) {
             }
             entity.rationale = data.rationale;
         }
+        // implements REQ-kb-decision-firmness
+        // How firmly a requirement or ADR was decided; absent reads as default.
+        if (data.firmness !== undefined) {
+            if (!carriesFirmness(type) || !isFirmness(data.firmness)) {
+                throw new FrontmatterError(carriesFirmness(type)
+                    ? `Invalid firmness; expected one of ${FIRMNESS_VALUES.join(", ")}`
+                    : "firmness is only allowed on type: req or adr", filePath, {
+                    classification: "Invalid Firmness",
+                    hint: "Use firm only for a rule a human stated (with origin.ref to their words), default for a delegated or agent choice, exploratory for a flagged guess; remove the field from other entity types.",
+                });
+            }
+            entity.firmness = data.firmness;
+        }
         if (type === "req" && Array.isArray(data.exempts_claims)) {
             entity.exempts_claims = data.exempts_claims.filter((value) => typeof value === "string");
         }

package/dist/operations/migration/schema6.d.ts

@@ -4,6 +4,8 @@ import { CLOSE_SUPERSEDED_REQUIREMENTS_CODE, MIGRATION_SYNC_ACTION_ID, MIGRATION
 export declare const ORIGIN_SCHEMA_VERSION = 6;
 /** The KB schema generation that requires body context on current entities. */
 export declare const BODY_CONTEXT_SCHEMA_VERSION = 8;
+/** The KB schema generation that adds decision firmness. */
+export declare const DECISION_FIRMNESS_SCHEMA_VERSION = 9;
 /** Automatic: re-derive a drifted inventory with the current advisor. */
 export declare const SEMANTIC_INVENTORY_REDERIVE_CODE = "semantic_inventory_rederive";
 /** Review: a drifted inventory Kibi cannot re-derive safely. */