kibi-cli 2.21.0 → 2.22.0

package/dist/commands/migrate.js

@@ -15,14 +15,13 @@
  * 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 { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, renameSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
-import { load as parseYAML } from "js-yaml";
 import { applySafeInventoryRederivations, planInventoryRederivation, } from "../operations/migration/inventory-rederive.js";
 import { applyOriginBackfill, planOriginBackfill, } from "../operations/migration/origin-backfill.js";
 import { applySourcePathRepairs, findSourceRepairs, } from "../operations/migration/source-paths.js";
 import { applySupersededClosures, planSupersededClosures, } from "../operations/migration/superseded-closure.js";
-import { extractSymbolsFromStagedFile } from "../traceability/symbol-extract.js";
+import { applySymbolLegacyLinks, planSymbolLegacyLinks, } from "../operations/migration/symbol-legacy-links.js";
 import { resolveBranchAttachment } from "../utils/branch-resolver.js";
 import { defaultKbManifest, readKbManifest, readKbManifestStatus, writeKbManifest, } from "../utils/kb-manifest.js";
 import { CANONICAL_ENTITY_PATHS } from "../utils/kb-paths.js";
@@ -79,6 +78,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);
@@ -155,137 +160,25 @@ function normalizeSemanticAdvisorBackfill(value) {
         ? value
         : null;
 }
-const TRACEABILITY_RELATIONSHIP_TYPES = new Set([
-    "implements",
-    "covered_by",
-    "executable_for",
-]);
-function hasTraceabilityRelationship(symbol) {
-    if (Array.isArray(symbol.links) && symbol.links.length > 0) {
-        return true;
-    }
-    if (!Array.isArray(symbol.relationships)) {
-        return false;
-    }
-    return symbol.relationships.some((relationship) => {
-        if (relationship === null ||
-            typeof relationship !== "object" ||
-            Array.isArray(relationship)) {
-            return false;
-        }
-        const type = relationship.type;
-        return (typeof type === "string" && TRACEABILITY_RELATIONSHIP_TYPES.has(type));
-    });
-}
-function getGranularNames(cwd, sourceFile) {
-    const absolutePath = path.isAbsolute(sourceFile)
-        ? sourceFile
-        : path.join(cwd, sourceFile);
-    if (!existsSync(absolutePath)) {
-        return new Set();
-    }
-    const symbols = extractSymbolsFromStagedFile({
-        path: sourceFile,
-        status: "M",
-        hunkRanges: [{ start: 1, end: Number.MAX_SAFE_INTEGER }],
-        content: readFileSync(absolutePath, "utf8"),
-    });
-    return new Set(symbols.map((symbol) => symbol.name));
-}
-function addLegacyReasonsToManifestText(content, symbolIds) {
-    if (symbolIds.size === 0)
-        return content;
-    const lines = content.split("\n");
-    const output = [];
-    let activeId = null;
-    let activeHasReason = false;
-    let activePropertyIndent = "";
-    const flushLegacyReason = () => {
-        if (activeId !== null &&
-            symbolIds.has(activeId) &&
-            !activeHasReason &&
-            activePropertyIndent.length > 0) {
-            output.push(`${activePropertyIndent}granularity_reason: legacy-link`);
-            activeHasReason = true;
-        }
-    };
-    for (const line of lines) {
-        const idMatch = line.match(/^(\s*)-\s+id:\s+(.+)\s*$/);
-        if (idMatch) {
-            flushLegacyReason();
-            activeId = idMatch[2]?.trim() ?? null;
-            activeHasReason = false;
-            activePropertyIndent = `${idMatch[1] ?? ""}  `;
-        }
-        if (activeId !== null && /^\s+granularity_reason:\s+/.test(line)) {
-            activeHasReason = true;
-        }
-        if (activeId !== null &&
-            symbolIds.has(activeId) &&
-            !activeHasReason &&
-            /^\s+status:\s+/.test(line)) {
-            const indent = line.match(/^\s*/)?.[0] ?? "";
-            output.push(`${indent}granularity_reason: legacy-link`);
-            activeHasReason = true;
-        }
-        output.push(line);
-    }
-    flushLegacyReason();
-    return output.join("\n");
-}
-function migrateSymbolGranularity(options) {
-    const manifestPath = options.manifestPath ??
-        path.join(options.cwd, CANONICAL_ENTITY_PATHS.symbols);
-    if (!existsSync(manifestPath)) {
-        return { count: 0, manifestPath };
-    }
-    const manifestContent = readFileSync(manifestPath, "utf8");
-    const parsed = parseYAML(manifestContent);
-    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return { count: 0, manifestPath };
-    }
-    const manifest = parsed;
-    if (!Array.isArray(manifest.symbols)) {
-        return { count: 0, manifestPath };
-    }
-    let count = 0;
-    const migratedSymbolIds = new Set();
-    const granularNamesByFile = new Map();
-    for (const symbol of manifest.symbols) {
-        if (symbol === null ||
-            typeof symbol !== "object" ||
-            Array.isArray(symbol)) {
-            continue;
-        }
-        const record = symbol;
-        if (typeof record.sourceFile !== "string")
-            continue;
-        if (typeof record.title !== "string")
-            continue;
-        if (typeof record.id !== "string")
-            continue;
-        if (record.granularity_reason !== undefined)
-            continue;
-        if (!hasTraceabilityRelationship(record))
-            continue;
-        let granularNames = granularNamesByFile.get(record.sourceFile);
-        if (granularNames === undefined) {
-            granularNames = getGranularNames(options.cwd, record.sourceFile);
-            granularNamesByFile.set(record.sourceFile, granularNames);
-        }
-        if (granularNames.size === 0 || granularNames.has(record.title)) {
-            continue;
-        }
-        count += 1;
-        if (!options.dryRun) {
-            record.granularity_reason = "legacy-link";
-            migratedSymbolIds.add(record.id);
-        }
-    }
-    if (count > 0 && !options.dryRun) {
-        writeTextAtomically(manifestPath, addLegacyReasonsToManifestText(manifestContent, migratedSymbolIds));
-    }
-    return { count, manifestPath };
+/**
+ * Mark the coarse symbol links the staged granularity gate would block as
+ * legacy-link. Runs at any schema version: the rule can call a link coarse
+ * that an older run (or a KB that skipped the schema 2 step) left unmarked.
+ */
+// implements REQ-cli-schema-migration, REQ-symbol-behavioral-anchors
+function markLegacySymbolLinks(cwd, dryRun, manifestPath) {
+    if (dryRun) {
+        const count = planSymbolLegacyLinks(cwd, manifestPath).targets.length;
+        if (count > 0)
+            console.log(`dry run: would mark ${count} coarse symbol link(s) as legacy-link (granularity_reason), so the staged check accepts them.`);
+        return count;
+    }
+    const { marked, unmarked } = applySymbolLegacyLinks(cwd);
+    if (marked.length > 0)
+        console.log(`Marked ${marked.length} existing coarse symbol link(s) as legacy-link.`);
+    if (unmarked.length > 0)
+        printWarning(`Could not mark ${unmarked.join(", ")} as legacy-link in place; add granularity_reason: legacy-link to them in ${CANONICAL_ENTITY_PATHS.symbols} by hand.`);
+    return marked.length;
 }
 function describeRederivation(plan) {
     const { keptModeled, roleChanges, newlyUnresolved, downgradedModeled } = plan.summary;
@@ -293,7 +186,7 @@ function describeRederivation(plan) {
 }
 function printManualRederivations(plans) {
     for (const plan of plans) {
-        printWarning(`${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and needs a manual fix: ${plan.reasons.join("; ")}. Run 'kibi migrate --format json' for the exact repair steps.`);
+        printWarning(`${plan.requirementId} (${plan.path}) no longer matches the current semantic advisor and needs a manual fix: ${plan.reasons.join("; ")}. Run 'kibi migrate --format json' for the exact repair steps.${plan.rederivableByDroppingGrounding ? ` Or approve semantic-inventory-rederive-drop-grounding-${plan.requirementId} with --apply-safe --approved-action to drop the ${plan.orphanedGrounding.length} orphaned grounding link(s).` : ""}`);
     }
 }
 /**
@@ -421,9 +314,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,12 +332,19 @@ 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
         : { schemaVersion: normalizedVersion });
-    const needsStorageMigration = storagePlan.moves.length > 0 || storagePlan.legacyConfig !== "absent";
+    const needsStorageMigration = storagePlan.moves.length > 0 ||
+        storagePlan.removals.length > 0 ||
+        storagePlan.legacyConfig !== "absent";
     const needsSchemaUpgrade = configStatus.needsMigration || normalizedVersion === null;
     const migrationWarning = manifestStatus.state === "invalid" || manifestStatus.state === "future"
         ? manifestStatus.warning
@@ -473,7 +377,9 @@ export async function migrateCommand(options = {}) {
         // and lifecycle findings block kibi check at any version.
         const drift = rederiveDriftedInventories(cwd, options.dryRun === true);
         const lifecycle = repairLifecycleFindings(cwd, options.dryRun === true);
+        const legacyLinks = markLegacySymbolLinks(cwd, options.dryRun === true);
         const rewroteSources = polarityCount > 0 ||
+            legacyLinks > 0 ||
             drift.rederived.length > 0 ||
             lifecycle.closed > 0 ||
             lifecycle.rewritten > 0 ||
@@ -497,12 +403,13 @@ export async function migrateCommand(options = {}) {
     }
     const fromVersionLabel = formatSchemaVersion(currentVersion, normalizedVersion);
     const migrationSteps = migrationStepsFor(configStatus.currentVersion);
-    const symbolGranularityStep = migrationSteps.some((step) => step.id === "symbol-granularity-v2");
     const semanticBackfillStep = migrationSteps.some((step) => step.id === "semantic-backfill-v4");
     const originBackfillStep = migrationSteps.some((step) => step.id === "entity-origin-v6");
     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,27 +426,28 @@ 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) {
                 console.log(`  ${move.from} -> ${move.to}`);
             }
         }
+        if (storagePlan.removals.length > 0) {
+            console.log(`dry run: would remove ${storagePlan.removals.length} legacy cop(ies) identical to their .kb/ file:`);
+            for (const removal of storagePlan.removals) {
+                console.log(`  ${removal.path} (same as ${removal.duplicateOf})`);
+            }
+        }
         if (storagePlan.legacyConfig !== "absent") {
             console.log("dry run: would retire legacy .kb/config.json after moving knowledge into .kb/.");
         }
         console.log(`dry run: would set schemaVersion from ${fromVersionLabel} to ${LATEST_KB_SCHEMA_VERSION} in .kb/manifest.json.`);
-        if (symbolGranularityStep) {
-            const symbolsSource = storagePlan.moves.find((move) => move.to === CANONICAL_ENTITY_PATHS.symbols)?.from ?? CANONICAL_ENTITY_PATHS.symbols;
-            const preview = migrateSymbolGranularity({
-                cwd,
-                dryRun: true,
-                manifestPath: path.join(cwd, symbolsSource),
-            });
-            if (preview.count > 0) {
-                console.log(`dry run: would mark ${preview.count} legacy coarse symbol link(s) as legacy-link.`);
-            }
-        }
+        markLegacySymbolLinks(cwd, true, storagePlan.moves.find((move) => move.to === CANONICAL_ENTITY_PATHS.symbols)?.from);
         if (originBackfillStep) {
             const backfill = planOriginBackfill(cwd);
             if (backfill.targets.length > 0) {
@@ -558,17 +466,18 @@ 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 = storageResult.untrackedMovedFiles.length;
+            if (untracked > 0)
+                printWarning(`${untracked} moved file(s) are not tracked by Git yet. Kibi recorded a pending-source receipt for each, so kibi sync compiles them now; stage them before you commit (git add .kb, plus the removals under the legacy folders). Each receipt retires once Git tracks its file.`);
+        }
+        if (storageResult.removedFiles.length > 0) {
+            console.log(`Removed ${storageResult.removedFiles.length} legacy cop(ies) identical to their .kb/ file: ${storageResult.removedFiles.join(", ")}.`);
         }
         if (storageResult.retiredLegacyConfig) {
             console.log("Retired legacy .kb/config.json.");
         }
     }
-    const symbolGranularityMigration = symbolGranularityStep
-        ? migrateSymbolGranularity({
-            cwd,
-            dryRun: options.yes !== true,
-        })
-        : { count: 0 };
+    const legacyLinksMarked = markLegacySymbolLinks(cwd, false);
     const semanticAdvisorBackfill = normalizeSemanticAdvisorBackfill(readKbManifest(cwd)?.semanticAdvisorBackfill) ??
         normalizeSemanticAdvisorBackfill(storagePlan.semanticAdvisorBackfill) ??
         (semanticBackfillStep || needsStorageMigration
@@ -599,6 +508,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,14 +526,21 @@ 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,
         fromVersion: configStatus.currentVersion,
         migratedAt,
         semanticAdvisorBackfill,
-        symbolGranularityLegacyLinks: symbolGranularityMigration.count,
+        symbolGranularityLegacyLinks: legacyLinksMarked,
         entityOriginBackfill: originBackfill.written.length + originBackfill.previouslyStamped,
         supersededRequirementsClosed: lifecycle.closed,
         sourcePathsRewritten: lifecycle.rewritten,
@@ -630,9 +549,6 @@ export async function migrateCommand(options = {}) {
         steps: migrationSteps.map((step) => step.id),
     }));
     console.log(`Migrated the KB to schemaVersion ${LATEST_KB_SCHEMA_VERSION} on the canonical .kb/ layout (was ${fromVersionLabel}).`);
-    if (symbolGranularityMigration.count > 0) {
-        console.log(`Marked ${symbolGranularityMigration.count} existing coarse symbol link(s) as legacy-link.`);
-    }
     if (semanticAdvisorBackfill === "pending") {
         console.log(`Marked semantic advisor backfill as pending in ${KB_MANIFEST_RELATIVE}.`);
     }
@@ -714,9 +630,13 @@ async function buildWorkspaceMigrationPlan(workspaceRoot = process.cwd()) {
     if (checkable && storeSynced) {
         const checkResult = await executeOperation(runtime, checkSpec, {});
         if (checkResult.structuredContent?.migrationPlan !== undefined) {
-            // Lifecycle repairs and their sync are planned above from authored
-            // sources, which may be newer than the compiled store.
-            plans.push(withoutActionCodes(checkResult.structuredContent.migrationPlan, SOURCE_PLANNED_LIFECYCLE_CODES));
+            // Lifecycle repairs, their sync and requirement status mappings are
+            // planned above from authored sources, which may be newer than the
+            // compiled store.
+            plans.push(withoutActionCodes(checkResult.structuredContent.migrationPlan, new Set([
+                ...SOURCE_PLANNED_LIFECYCLE_CODES,
+                "check_req-status-vocabulary",
+            ])));
         }
         const coverageInputs = [
             { by: "req", limit: 10_000, offset: 0 },
@@ -759,7 +679,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 +742,24 @@ function approvedActionIdsOf(options) {
         .filter((id) => id.length > 0);
     return [...new Set(ids)];
 }
+/** 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 +814,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/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAG5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAaF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AAoHD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAED;;;;;;;;GAQG;AAEH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/manifest.ts"],"names":[],"mappings":"AAkBA,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,SAAS,CAAC;AAE9D,OAAO,EAML,uBAAuB,EACxB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,mBAAmB,EACxB,uBAAuB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,0BAA0B,EAG3B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAG5E,UAAU,YAAY;IACpB,QAAQ,EAAE,OAAO,QAAQ,CAAC;IAC1B,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,SAAS,EAAE,OAAO,SAAS,CAAC;IAC5B,YAAY,EAAE,OAAO,YAAY,CAAC;IAClC,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,2BAA2B,EAAE,OAAO,2BAA2B,CAAC;CACjE;AAkBD,eAAO,MAAM,8BAA8B,QAc1C,CAAC;AAeF;;;;;;;;;GASG;AACH,OAAO,EAAE,0BAA0B,EAAE,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAG7E;AA2HD,wBAAsB,0BAA0B,CAE9C,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG;IAC7B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,GACA,OAAO,CAAC,IAAI,CAAC,CA0Mf;AAED;;;;;;;;GAQG;AAEH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,MAAM,GAAG,IAAI,CAWf;AAED,wBAAgB,0BAA0B,CAExC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAOT;AAED,wBAAgB,8BAA8B,CAE5C,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC3B,OAAO,CAUT"}

package/dist/commands/sync/manifest.js

@@ -63,6 +63,8 @@ const GENERATED_COORD_FIELDS = [
 const GENERATED_MANIFEST_FIELDS = new Set([
     ...GENERATED_COORD_FIELDS,
     "coordinatesGeneratedAt",
+    // Transient refresh outcome from the coordinate enricher; never authored.
+    "coordinateRefreshFailure",
 ]);
 /**
  * Coarse symbol anchors for which AST per-declaration coordinates are not
@@ -159,7 +161,14 @@ function manifestEntryIdentity(entry) {
  * granularity_reason (so the whole-file fallback is gated off) or the
  * fallback itself produced no span.
  */
+// implements REQ-generated-coordinate-persistence
 function coarseAnchorFailureReason(entry) {
+    // The enricher names the cause when the title is a declaration the symbol
+    // extractor never produces (a private class member): no refresh can bind
+    // it, so the remedy is to re-point or remove the symbol.
+    if (typeof entry.coordinateRefreshFailure === "string") {
+        return entry.coordinateRefreshFailure;
+    }
     const reason = entry.granularity_reason;
     if (!isCoarseGranularityReason(reason)) {
         return `extractor produced no coordinates; add symbol_role and granularity_reason ${COARSE_GRANULARITY_REASONS_PARENTHESIZED} to enable the whole-file coarse fallback`;

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"}