@wairon/cli 5.1.1-dev.42 → 5.1.1-dev.44

package/dist/cli/index.js

@@ -65,7 +65,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.42";
+    WAIRON_VERSION = "5.1.1-dev.44";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -890,6 +890,31 @@ var init_project = __esm({
       kind: CarriedDebtKindSchema,
       /** The reason itself, in the author's own words — what is true here, and what paying it would take. */
       why: import_zod4.z.string().min(1),
+      /**
+       * This classification is PROVISIONAL, and this is what would settle it.
+       *
+       * A confident-sounding `why` that is wrong is worse than a missing one: it
+       * reads as settled, so nobody looks again, and the register keeps counting
+       * the finding under a kind that was never true. Nothing can check a reason
+       * for truth — `kind` and `why` are prose, and STALE_CARRIED_FINDING only
+       * ever catches "this stopped applying", never "this still applies for a
+       * reason that has become false". What a register CAN do is let an author say
+       * out loud that they are not sure yet, and then keep saying it: every run
+       * counts the groups marked here beside the kind totals, so the uncertainty
+       * is as loud as the debt.
+       *
+       * It is deliberately a SENTENCE and not a flag, and deliberately on the
+       * reason GROUP rather than the finding: what is provisional is the reason,
+       * and a reader deciding whether to pick this up needs to know what to
+       * measure — "is the adapter really realized by the file that consumes it, or
+       * is that a modelling error?" — not merely that somebody once hesitated. A
+       * finding whose own classification is uncertain while its neighbours' is not
+       * is a different reason, and belongs in its own group.
+       *
+       * There is no counterpart on `lint.allow`, and that is a decision, not an
+       * omission: see the note on ConformanceRuleConfig.carried.
+       */
+      revisit: import_zod4.z.string().min(1).optional(),
       /** The findings this reason explains. */
       findings: import_zod4.z.array(CarriedFindingSchema)
     });
@@ -935,6 +960,17 @@ var init_project = __esm({
        *   • every entry states its kind and its reason, and `wairon validate`
        *     prints the running total, so the debt is loud where a suppression is
        *     silent.
+       *
+       * A reason group may also declare itself PROVISIONAL (`revisit`), and the
+       * total says how many did. There is no such marker on a `lint.allow`, and
+       * the asymmetry is the point: an entry here does not silence anything — the
+       * finding is counted out loud on every run — so marking one uncertain adds a
+       * second dial to something already visible. An allow DOES silence, and a
+       * "provisional allow" would buy the silence and defer the decision, which is
+       * the one combination that cannot be reviewed: the finding is gone and the
+       * doubt is in a field nobody opens. The mechanism for a decision nobody has
+       * taken is to not take it — leave the warning firing — or, where the code is
+       * carryable, an entry of kind `undecided`, which is exactly that sentence.
        */
       carried: import_zod4.z.array(CarriedDebtSchema).optional()
     });
@@ -1251,6 +1287,11 @@ function passesIntentFloor(text2, methodName) {
   if (norm(t) === norm(methodName)) return false;
   return true;
 }
+function parseDeclaredCall(ref) {
+  const at = ref.lastIndexOf(".");
+  if (at <= 0 || at === ref.length - 1) return null;
+  return { compId: ref.slice(0, at), methodName: ref.slice(at + 1) };
+}
 function methodSourceFile(method2, implementationSourcePath) {
   return method2.sourcePath || implementationSourcePath || void 0;
 }
@@ -1411,8 +1452,28 @@ var init_specs = __esm({
     LintAllowSchema = import_zod7.z.object({
       /** The issue code being allowed (see `wairon rules list`). */
       code: import_zod7.z.string(),
+      /**
+       * The SITE inside this spec the allow covers, named exactly as the finding
+       * names it (a contract method, an import edge "from -> to", a declared edge
+       * "component -> target"). A finding that names a site is covered ONLY by an
+       * allow naming that same site; a finding that names none is covered only by
+       * an allow that names none either.
+       */
+      at: import_zod7.z.string().min(1).optional(),
+      /**
+       * The units of an AGGREGATING finding this allow covers — the steps of one
+       * CALL_STEP_UNREALIZED, the crossings of one UNDECLARED_COLOCATED_CALL —
+       * each named the way the finding's own message names it. The allow silences
+       * the finding only when it lists EVERY unit reported, so a unit nobody
+       * decided on surfaces on the day it appears instead of inheriting a decision
+       * taken about its neighbours. Meaningless without `at`, and refused there.
+       */
+      covers: import_zod7.z.array(import_zod7.z.string()).optional(),
       /** Why this finding is acceptable here (e.g. "dispatcher — fan-out is the point"). */
       reason: import_zod7.z.string().min(1)
+    }).refine((a) => !a.covers?.length || !!a.at, {
+      message: "`covers` names the units of ONE finding, so it needs the `at` that says which finding \u2014 add the site, or drop covers.",
+      path: ["covers"]
     });
     LintConfigSchema = import_zod7.z.object({
       allow: import_zod7.z.array(LintAllowSchema).default([])
@@ -1861,6 +1922,31 @@ var init_specs = __esm({
       intent: import_zod7.z.string().optional(),
       /** Conformance tier for THIS method (overrides the spec-level default). */
       conformance: ConformanceTierSchema.optional(),
+      /**
+       * The calls this method makes, when its narrative does not show them.
+       *
+       * The mirror of the contract's `invokedBy`: that declares the caller
+       * OUTSIDE the modeled graph, this declares the callees INSIDE it. It lives
+       * here and not on the L3 method because what a method CALLS is a property
+       * of the realization — the detail dial that hides the steps is here, and two
+       * implementations of one contract may reach different collaborators —
+       * whereas an external caller is a fact about the contract's role that must
+       * hold for every realization.
+       *
+       * Each entry names one target the way the debt register and a lint allow
+       * name a unit: `<component>.<method>` (a `covers` entry is the same
+       * spelling with the step number a declaration has no equivalent of). A
+       * third vocabulary for "which method" would be the worse outcome.
+       *
+       * The narrative graph walk takes exactly these edges for a method with no
+       * narrative, and NOTHING else: an undeclared collaborator is not reached,
+       * so a lower detail dial no longer vouches for everything the component
+       * declares. Each entry gets the same target validation a `call` step gets
+       * (the component resolves, the caller declares it, the method is on its
+       * contract). Refused beside a non-empty narrative, where the steps already
+       * say what is called and a second spelling could only disagree.
+       */
+      calls: import_zod7.z.array(import_zod7.z.string().min(1)).optional(),
       /**
        * The code-level name realizing this contract method in the sourcePath
        * file, when it legitimately differs from the intent-language contract
@@ -1897,7 +1983,16 @@ var init_specs = __esm({
        * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
        */
       technologies: import_zod7.z.array(import_zod7.z.string()).optional(),
-      methods: import_zod7.z.array(MethodImplementationSchema).default([]),
+      methods: import_zod7.z.array(MethodImplementationSchema).default([]).superRefine((methods, ctx) => {
+        methods.forEach((m, i) => {
+          if (!m.calls?.length || m.narrative.length === 0) return;
+          ctx.addIssue({
+            code: import_zod7.z.ZodIssueCode.custom,
+            path: [i, "calls"],
+            message: `Method "${m.name}" declares calls AND a narrative \u2014 \`calls\` says what a method calls when its narrative does not show it, and this one has ${m.narrative.length} step(s) that already do. Add the call step, or drop the declaration.`
+          });
+        });
+      }),
       /** Spec-level narrative detail default for all methods (each may override). */
       detail: NarrativeDetailSchema.optional(),
       /** Spec-level conformance tier default (each method may override). */
@@ -9694,10 +9789,10 @@ var init_lint_allows = __esm({
     "use strict";
     lintAllowsRule = {
       name: "lint-allows",
-      description: "Per-spec lint suppressions (lint.allow) must name real issue codes and actually suppress a finding \u2014 unknown codes and stale allows are flagged. Allows silence warnings only; errors always surface.",
+      description: "Per-spec lint suppressions (lint.allow) must name real issue codes and actually suppress a finding \u2014 unknown codes and stale allows are flagged. An allow covers exactly the occurrence it names: a finding that reports a site is silenced only by an allow whose `at` is that site, a finding that reports none only by an allow that names none, and an aggregating finding only by an allow whose `covers` lists every unit it reports \u2014 a unit nobody listed is named back as new instead of inheriting a decision taken about its neighbours. So a coarse allow left on a rule that names sites, and an allow whose site the run no longer reports, are both UNUSED_LINT_ALLOW, and the finding names the sites that did fire. Allows silence warnings only; errors always surface.",
       codes: [
         { code: "UNKNOWN_LINT_ALLOW_CODE", defaultSeverity: "warning", summary: "lint.allow names an issue code no registered rule emits" },
-        { code: "UNUSED_LINT_ALLOW", defaultSeverity: "warning", summary: "lint.allow entry matched no finding this run \u2014 remove the stale allow" }
+        { code: "UNUSED_LINT_ALLOW", defaultSeverity: "warning", summary: "lint.allow entry matched no finding this run \u2014 the code never fired, or it fired at sites this allow does not name" }
       ],
       check(ctx) {
         for (const a of ctx.lintAllows) {
@@ -9710,14 +9805,24 @@ var init_lint_allows = __esm({
             );
             continue;
           }
-          if (!a.used) {
-            ctx.addIssue(
-              "warning",
-              "UNUSED_LINT_ALLOW",
-              `Spec "${a.specId}" allows "${a.code}" (reason: ${a.reason}) but no such finding fired this run \u2014 remove the stale allow.`,
-              a.specId
-            );
+          if (a.used) continue;
+          const reported = ctx.sitesReported(a.specId, a.code);
+          const at = a.at ? ` at "${a.at}"` : "";
+          let why;
+          if (a.at && reported.unsited && reported.sites.length === 0) {
+            why = `findings of "${a.code}" on this spec name no site at all, so this allow must not name one \u2014 drop the \`at\``;
+          } else if (reported.sites.length > 0) {
+            const sites = reported.sites.map((s) => `"${s}"`).join("; ");
+            why = a.at ? `that code fired at ${sites} instead \u2014 retarget the allow, or remove it` : `that code fired at ${sites}, and a sited finding is covered only by an allow naming its site \u2014 give this allow an \`at\` (one per site, each with its own reason), or remove it`;
+          } else {
+            why = "no such finding fired this run \u2014 remove the stale allow";
           }
+          ctx.addIssue(
+            "warning",
+            "UNUSED_LINT_ALLOW",
+            `Spec "${a.specId}" allows "${a.code}"${at} (reason: ${a.reason}), but ${why}.`,
+            a.specId
+          );
         }
       }
     };
@@ -9772,16 +9877,36 @@ var init_contract_symmetry = __esm({
 });
 
 // src/core/rules/narrative/narrative-target-references.ts
-var narrativeTargetReferencesRule;
+var targetsOf, narrativeTargetReferencesRule;
 var init_narrative_target_references = __esm({
   "src/core/rules/narrative/narrative-target-references.ts"() {
     "use strict";
+    init_models();
+    targetsOf = (implMethod) => {
+      const entries = [];
+      for (const step of implMethod.narrative) {
+        if (step.type !== "call" && step.type !== "dispatch" && step.type !== "register") continue;
+        entries.push({
+          kind: step.type,
+          stepNumber: step.stepNumber,
+          targetComponent: step.targetComponent,
+          targetMethod: step.targetMethod,
+          assertsGuarantees: step.assertsGuarantees
+        });
+      }
+      for (const ref of implMethod.calls ?? []) {
+        const parsed = parseDeclaredCall(ref);
+        entries.push(parsed ? { kind: "declared", targetComponent: parsed.compId, targetMethod: parsed.methodName } : { kind: "declared", unparsed: ref });
+      }
+      return entries;
+    };
     narrativeTargetReferencesRule = {
       name: "narrative-target-references",
-      description: "A narrative call, dispatch or register step must name a target component, and a target method unless it dispatches. A target this tree contains must be a collaborator the calling component declares, must carry the named method on one of its interfaces, and that method must declare every semantic guarantee the step asserts.",
+      description: `A narrative call, dispatch or register step must name a target component, and a target method unless it dispatches; a method's declared calls name the same pair as one "<component>.<method>" reference, the spelling the conformance debt register and a lint allow name a unit with. A target this tree contains must be a collaborator the calling component declares, must carry the named method on one of its interfaces, and that method must declare every semantic guarantee the entry asserts.`,
       codes: [
         { code: "MISSING_TARGET_COMPONENT", defaultSeverity: "error", summary: "Call/register step missing targetComponent" },
         { code: "MISSING_TARGET_METHOD", defaultSeverity: "error", summary: "Call/register step missing targetMethod" },
+        { code: "MALFORMED_DECLARED_CALL", defaultSeverity: "error", summary: 'Declared call that is not a "<component>.<method>" reference' },
         { code: "UNDECLARED_DEPENDENCY_CALL", defaultSeverity: "error", summary: "Call step targets a component the caller does not depend on or own" },
         { code: "INVALID_TARGET_METHOD_REFERENCE", defaultSeverity: "error", summary: "Call step targets a method not on any target interface" },
         { code: "NARRATIVE_SEMANTIC_UNBACKED", defaultSeverity: "warning", summary: "Narrative asserts a guarantee the called contract does not declare" }
@@ -9793,25 +9918,35 @@ var init_narrative_target_references = __esm({
           const isDraftCtx = ctx.isImplementationDraft(impl);
           const caller = ctx.componentMap.get(contract.component);
           for (const implMethod of impl.methods) {
-            for (const step of implMethod.narrative) {
-              if (step.type !== "call" && step.type !== "dispatch" && step.type !== "register") continue;
-              if (!step.targetComponent) {
+            for (const entry of targetsOf(implMethod)) {
+              const where = entry.stepNumber === void 0 ? "" : ` (step ${entry.stepNumber})`;
+              if (entry.unparsed !== void 0) {
+                ctx.addIssue(
+                  "error",
+                  "MALFORMED_DECLARED_CALL",
+                  `Method "${implMethod.name}" in implementation "${impl.id}" declares the call "${entry.unparsed}", which is not a "<component>.<method>" reference \u2014 the spelling the conformance debt register and a lint allow name a unit with.`,
+                  impl.id,
+                  isDraftCtx
+                );
+                continue;
+              }
+              if (!entry.targetComponent) {
                 ctx.addIssue(
                   "error",
                   "MISSING_TARGET_COMPONENT",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${step.type} step (${step.stepNumber}) missing "targetComponent".`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${entry.kind} step (${entry.stepNumber}) missing "targetComponent".`,
                   impl.id,
                   isDraftCtx
                 );
                 continue;
               }
-              const target = step.targetComponent;
-              const verb = step.type === "dispatch" ? "dispatches through" : step.type === "register" ? "registers callback" : "calls";
-              if (step.type !== "dispatch" && !step.targetMethod) {
+              const target = entry.targetComponent;
+              const verb = entry.kind === "dispatch" ? "dispatches through" : entry.kind === "register" ? "registers callback" : entry.kind === "declared" ? "declares a call to" : "calls";
+              if (entry.kind !== "dispatch" && !entry.targetMethod) {
                 ctx.addIssue(
                   "error",
                   "MISSING_TARGET_METHOD",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${step.type} step (${step.stepNumber}) missing "targetMethod".`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${entry.kind} step (${entry.stepNumber}) missing "targetMethod".`,
                   impl.id,
                   isDraftCtx
                 );
@@ -9822,16 +9957,16 @@ var init_narrative_target_references = __esm({
                 ctx.addIssue(
                   "error",
                   "UNDECLARED_DEPENDENCY_CALL",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" (component "${caller.id}") ${verb} component "${target}" (step ${step.stepNumber}) but component "${caller.id}" does not list "${target}" as a dependency.`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" (component "${caller.id}") ${verb} component "${target}"${where} but component "${caller.id}" does not list "${target}" as a dependency.`,
                   impl.id,
                   isDraftCtx || ctx.isComponentDraft(caller.id)
                 );
               }
-              if (step.type === "dispatch") continue;
+              if (entry.kind === "dispatch") continue;
               const targetInterfaces = ctx.interfacesByComponent.get(target) ?? [];
               let targetMethodSpec;
               for (const targetIntf of targetInterfaces) {
-                const found = targetIntf.methods.find((m) => m.name === step.targetMethod);
+                const found = targetIntf.methods.find((m) => m.name === entry.targetMethod);
                 if (found) {
                   targetMethodSpec = found;
                   break;
@@ -9841,19 +9976,19 @@ var init_narrative_target_references = __esm({
                 ctx.addIssue(
                   "error",
                   "INVALID_TARGET_METHOD_REFERENCE",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} method "${step.targetMethod}" on component "${target}" which is not defined on any of its interfaces (step ${step.stepNumber}).`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} method "${entry.targetMethod}" on component "${target}" which is not defined on any of its interfaces${where}.`,
                   impl.id,
                   isDraftCtx || ctx.isComponentDraft(target)
                 );
                 continue;
               }
               const declared = new Set(targetMethodSpec.guarantees ?? []);
-              for (const g of step.assertsGuarantees ?? []) {
+              for (const g of entry.assertsGuarantees ?? []) {
                 if (!declared.has(g)) {
                   ctx.addIssue(
                     "warning",
                     "NARRATIVE_SEMANTIC_UNBACKED",
-                    `Step ${step.stepNumber} of "${implMethod.name}" in implementation "${impl.id}" explicitly asserts guarantee "${g}", but the method it calls \u2014 "${step.targetMethod}" on "${target}" \u2014 does not list "${g}" among its L3 contract guarantees. Declare it on that method (and ensure its shape can deliver it), or revise the narrative.`,
+                    `Step ${entry.stepNumber} of "${implMethod.name}" in implementation "${impl.id}" explicitly asserts guarantee "${g}", but the method it calls \u2014 "${entry.targetMethod}" on "${target}" \u2014 does not list "${g}" among its L3 contract guarantees. Declare it on that method (and ensure its shape can deliver it), or revise the narrative.`,
                     impl.id,
                     isDraftCtx || ctx.isComponentDraft(target)
                   );
@@ -12544,15 +12679,11 @@ function walk(ctx, seeds, options = {}) {
         if (edge.methodName) enqueueMethod(edge.compId, edge.methodName);
       }
     }
-    if (methodImpl.narrative.length === 0) {
-      const comp = ctx.componentMap.get(compId);
-      if (comp && effectiveDetail(methodImpl, impl, comp).level !== "full") {
-        for (const depId of [...comp.dependsOn, ...comp.owns]) {
-          if (!ctx.componentMap.has(depId)) continue;
-          reachComponent(depId);
-          enqueueAllMethods(depId);
-        }
-      }
+    for (const ref of methodImpl.calls ?? []) {
+      const parsed = parseDeclaredCall(ref);
+      if (!parsed || !ctx.componentMap.has(parsed.compId)) continue;
+      reachComponent(parsed.compId);
+      enqueueMethod(parsed.compId, parsed.methodName);
     }
   }
   return {
@@ -12617,7 +12748,9 @@ var init_unused_detection = __esm({
                 "INVOKED_BY_REDUNDANT",
                 `Method "${m.name}" on component "${intf.component}" declares invokedBy (${m.invokedBy.kind}), but the internal narrative walk already reaches it \u2014 the declaration is stale; remove it.`,
                 intf.id,
-                isDraftCtx
+                isDraftCtx,
+                void 0,
+                { at: m.name }
               );
             }
           }
@@ -12645,7 +12778,11 @@ var init_unused_detection = __esm({
                   "UNUSED_METHOD",
                   `Method "${m.name}" on component "${comp.id}" is defined but never called by any narrative step.`,
                   intf.id,
-                  isDraftCtx
+                  isDraftCtx,
+                  void 0,
+                  // The site is the method, so an allow covers exactly the one it
+                  // names - never its neighbours on the same interface.
+                  { at: m.name }
                 );
               }
             }
@@ -13736,7 +13873,13 @@ var init_dependency_conformance = __esm({
               "UNDECLARED_DEPENDENCY",
               `"${fromPath}" (realizing ${fromComponents.map((c) => c.id).join(", ")}) imports "${toPath}" (realizing ${toComponents.map((c) => c.id).join(", ")}) but no declared dependsOn/owns edge justifies it \u2014 declare the collaboration on the component that actually uses it, or route the cross-subsystem hop through the target's published surface.`,
               realization.implementationsAt(fromPath)[0]?.id,
-              draftAt(fromPath) || draftAt(toPath)
+              draftAt(fromPath) || draftAt(toPath),
+              void 0,
+              // One import edge, one indivisible fact — but one implementation
+              // maps many files and many edges, so the EDGE is the site, not the
+              // spec. Without it a single allow on the spec covers every crossing
+              // that file ever grows.
+              { at: `${fromPath} -> ${toPath}` }
             );
           }
         }
@@ -13763,7 +13906,12 @@ var init_dependency_conformance = __esm({
               "UNREALIZED_DEPENDENCY",
               `Component "${component.id}" declares ${relation} "${targetId}", but no runtime import connects their source files (${fromFiles.join(", ")} \u219B ${crossSubsystem ? `subsystem ${target.subsystem}` : filesOf(targetId).join(", ")}) \u2014 either the collaboration is wired indirectly (DI) or the declared edge is stale.`,
               impls[0]?.id ?? component.id,
-              draft
+              draft,
+              void 0,
+              // One declared edge, one indivisible fact. A component declares many,
+              // and they all anchor on its one implementation spec, so the EDGE is
+              // the site.
+              { at: `${component.id} -> ${targetId}` }
             );
           }
         }
@@ -14122,7 +14270,7 @@ var init_carried_debt = __esm({
     "use strict";
     carriedDebtRule = {
       name: "carried-debt",
-      description: "The conformance debt register (`rules.conformance.carried`) holds the code\u2194spec findings this tree carries as declared, classified debt \u2014 `unclaimed`'s one-way shape, for findings about code a spec does name. It is not a second lint.allow: an allow says a finding is wrong here by design, an entry here says the finding is right and unpaid, and each entry states which of the three kinds it is (drift: spec and code disagree; undecided: the fix waits on a modelling decision nobody has taken; unreadable: the analysis cannot follow the shape the code is written in) and why. Only a code a rule declares CARRYABLE may appear, and naming any other is an error, so the register can never widen into general-purpose suppression. An entry carries a finding only when it lists EVERY unit that finding reports, so an aggregating finding cannot grow behind it; an entry that matched nothing, that duplicates another, that names a spec the tree does not hold, or that lists a unit no longer reported is STALE_CARRIED_FINDING, so the register only shrinks. The audit is silent in a run that could not have fired the findings at all: one that built no code model, the specs outside a scoped run, and a code the project switched off.",
+      description: "The conformance debt register (`rules.conformance.carried`) holds the code\u2194spec findings this tree carries as declared, classified debt \u2014 `unclaimed`'s one-way shape, for findings about code a spec does name. It is not a second lint.allow: an allow says a finding is wrong here by design, an entry here says the finding is right and unpaid, and each entry states which of the three kinds it is (drift: spec and code disagree; undecided: the fix waits on a modelling decision nobody has taken; unreadable: the analysis cannot follow the shape the code is written in) and why. Only a code a rule declares CARRYABLE may appear, and naming any other is an error, so the register can never widen into general-purpose suppression. An entry carries a finding only when it lists EVERY unit that finding reports, so an aggregating finding cannot grow behind it; an entry that matched nothing, that duplicates another, that names a spec the tree does not hold, or that lists a unit no longer reported is STALE_CARRIED_FINDING, so the register only shrinks. The audit is silent in a run that could not have fired the findings at all: one that built no code model, the specs outside a scoped run, and a code the project switched off. Nothing can check a reason for TRUTH \u2014 a stale entry is one that stopped applying, never one that still applies for a reason that has become false \u2014 so a reason group may declare its own classification provisional (`revisit`: what would settle it), and every run counts those findings beside the kind totals.",
       codes: [
         { code: "UNCARRYABLE_FINDING", defaultSeverity: "error", summary: "The conformance debt register names an issue code no rule emits, or one no rule declares carryable \u2014 the register holds measured code\u2194spec debt, never a design rule somebody wants quiet" },
         { code: "STALE_CARRIED_FINDING", defaultSeverity: "warning", summary: "An entry of the conformance debt register carries a finding that no longer fires, or lists a unit that finding no longer reports \u2014 delete it, the register only shrinks" }
@@ -16496,12 +16644,20 @@ function buildRuleContext(opts) {
   const allowLookup = /* @__PURE__ */ new Map();
   const collectAllows = (specId, lint) => {
     for (const a of lint?.allow ?? []) {
-      const entry = { specId, code: a.code, reason: a.reason, used: false };
+      const entry = { specId, code: a.code, at: a.at, covers: a.covers, reason: a.reason, used: false };
       lintAllows.push(entry);
       if (!allowLookup.has(specId)) allowLookup.set(specId, /* @__PURE__ */ new Map());
-      allowLookup.get(specId).set(a.code, entry);
+      const forSpec = allowLookup.get(specId);
+      const forCode = forSpec.get(a.code) ?? [];
+      forCode.push(entry);
+      forSpec.set(a.code, forCode);
     }
   };
+  const sitesSeen = /* @__PURE__ */ new Map();
+  const sitesReported = (specId, code) => {
+    const seen = sitesSeen.get(`${specId}\0${code}`);
+    return { sites: [...seen?.sites ?? []], unsited: seen?.unsited ?? false };
+  };
   for (const s of subsystems) collectAllows(s.id, s.lint);
   for (const c of components) collectAllows(c.id, c.lint);
   for (const i of interfaces) collectAllows(i.id, i.lint);
@@ -16538,15 +16694,29 @@ function buildRuleContext(opts) {
     }
     const severity = getRuleSeverity(code, defaultSeverity, isDraftContext, owner);
     if (severity === "off") return;
+    let text2 = message;
+    if (specId) {
+      const key = `${specId}\0${code}`;
+      let seen = sitesSeen.get(key);
+      if (!seen) sitesSeen.set(key, seen = { sites: /* @__PURE__ */ new Set(), unsited: false });
+      if (parts) seen.sites.add(parts.at);
+      else seen.unsited = true;
+    }
+    let allowClaimed = false;
     if (specId) {
-      const allow = allowLookup.get(specId)?.get(code);
+      const allow = (allowLookup.get(specId)?.get(code) ?? []).find((a) => parts ? a.at === parts.at : a.at === void 0);
       if (allow) {
         allow.used = true;
-        if (severity === "warning") return;
+        allowClaimed = true;
+        const grew = (parts?.covers ?? []).filter((unit) => !(allow.covers ?? []).includes(unit));
+        if (grew.length === 0) {
+          if (severity === "warning") return;
+        } else {
+          text2 = `${text2} A lint.allow covers this site, but not ${grew.length} part(s) of it \u2014 ${grew.map((u) => `"${u}"`).join("; ")} ${grew.length === 1 ? "is" : "are"} new. Decide on them: add them to the allow's \`covers\` with a reason that is actually true, or fix them.`;
+        }
       }
     }
-    let text2 = message;
-    if (specId && parts && severity === "warning") {
+    if (specId && parts && severity === "warning" && !allowClaimed) {
       const entry = carriedLookup.get(carriedKey(specId, code, parts.at));
       if (entry) {
         entry.fired = true;
@@ -16639,6 +16809,7 @@ function buildRuleContext(opts) {
     codeModel: opts.codeModel ?? emptyCodeModel(),
     roundTripIssues: opts.roundTripIssues,
     lintAllows,
+    sitesReported,
     knownIssueCodes: opts.knownIssueCodes,
     carriedFindings,
     carryableIssueCodes: opts.carryableIssueCodes ?? /* @__PURE__ */ new Set(),
@@ -24400,9 +24571,11 @@ function identityKeyOf(field, item) {
       return `${String(o.topic)} ${o.event === void 0 ? "" : String(o.event)}`;
     case "trustedLinks":
       return str(o.subsystem);
+    // lint.allow: an allow is one decision about one OCCURRENCE, so several
+    // may share a code on one spec, each naming its own site. Keyed by code
+    // alone a delta for one site would overwrite its neighbours.
     case "allow":
-      return str(o.code);
-    // lint.allow
+      return `${String(o.code)} ${o.at === void 0 ? "" : String(o.at)}`;
     case "findings":
       return str(o.code);
     // an interface method's findings
@@ -24490,6 +24663,7 @@ function identityFieldsOf(field) {
     case "trustedLinks":
       return ["subsystem"];
     case "allow":
+      return ["code", "at"];
     case "findings":
       return ["code"];
     case "invariants":
@@ -28620,7 +28794,8 @@ function createMcpServer(options = {}) {
     conformance: conformanceEnum.optional().describe("Conformance tier for this method (overrides the spec default)"),
     symbol: import_zod11.z.string().optional().describe("Code-level name realizing this contract method in the sourcePath file, when it legitimately differs from the intent-language contract name (e.g. put realized by saveSnapshot)"),
     ext: import_zod11.z.record(import_zod11.z.unknown()).optional().describe("Opaque pack/tool extension data for this method (namespaced keys) \u2014 preserved verbatim"),
-    narrative: import_zod11.z.array(narrativeStepInput).optional()
+    narrative: import_zod11.z.array(narrativeStepInput).optional(),
+    calls: import_zod11.z.array(import_zod11.z.string().min(1)).optional().describe('The calls this method makes, when its narrative does not show them (detail: intent, or calls-only with no steps authored) \u2014 each as "<component>.<method>", the spelling the debt register and lint allows name a unit with. The narrative walk takes exactly these edges and no others, so an undeclared collaborator is NOT reached: this is what keeps unused-detection honest at a lower detail dial. Each entry is validated like a call step (the component resolves, this component declares it, the method is on its contract). Refused beside a non-empty narrative \u2014 add the call step there instead')
   };
   const implMethodInputFields = Object.keys(implMethodShape);
   const implInput = {
@@ -28641,7 +28816,7 @@ function createMcpServer(options = {}) {
     server,
     "sdd_write_narrative",
     {
-      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
+      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). A method whose narrative shows no steps declares the calls it makes in `calls` (one \"<component>.<method>\" each): the reachability walk takes exactly those edges and no others, so an intent-level method that reaches a collaborator must name it or that collaborator is reported unused. Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
       inputSchema: implInput,
       outputSchema: specWriteReceiptOutput
     },
@@ -28964,7 +29139,7 @@ function createMcpServer(options = {}) {
       inputSchema: {
         kind: import_zod11.z.enum(["system", "subsystem", "component", "interface", "implementation", "type"]).describe("The spec kind to update (system = the singleton L0 \u2014 vision, boundaries, globalRequirements, databases, and publicInterfaces: the project gateway surface, each entry {id, name, subsystem, component, type, details, audience: project|department|instance|partner|external}; id is informational)"),
         id: import_zod11.z.string().describe("The ID of the spec to update (namespaced if needed)"),
-        delta: import_zod11.z.record(import_zod11.z.any()).describe(`The partial fields to merge into the spec. ARRAYS UPSERT, they do not replace: an array whose elements carry an identity is merged element-by-element, so a delta naming ONE element leaves the others intact. Identity is "name" or "id" by default, and per field: dispatch by "capability", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", invariants and patterns by "id", lint.allow by "code", an interface method's findings by "code", boundaries by "name", globalRequirements by "description", switch cases by "value", try catches by "error". Identity merging applies at EVERY depth, including an array INSIDE an element (a method's params, a step's catches). Add "action: 'delete'" (or "remove: true") alongside that identity to REMOVE an element \u2014 including a stale lint allow. Arrays of plain STRINGS (owns, dependsOn, guarantees) carry no per-element identity and are replaced wholesale; pass [] to clear any array outright. To REMOVE an optional field entirely, list it in "unset": e.g. {"unset": ["basePath", "variant"]} \u2014 passing null/undefined means "no change" (they are skipped), and writing "" would leave the field present but empty, which is a different and usually wrong spec. Unsetting a required field is refused by schema validation, which names it. For narrative steps, match by "stepNumber" and use "action: 'insert'" (shifts subsequent steps up) or "action: 'delete'" (shifts subsequent steps down and removes it). Step entries apply in ASCENDING stepNumber order, each against the numbering the earlier entries of the SAME delta left behind \u2014 delete step 3 and step 7 becomes step 6 \u2014 so prefer labels, and restate the step's "label" or "description" on a delete to have it checked against the step actually addressed. Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative. A delete is REJECTED when the narrative has no such step, when a jump still targets it (retarget the referrers first), when a restated label/description does not match, or when it is a loop/try/parallel header whose body would be left standing (retype the header first to dissolve the region, then delete it). Changing a step's "type" REBUILDS it for the new type: its description and label are kept and every field the new type cannot carry is dropped (returned as a NOTICE); a delta that retypes AND sets such a field is refused. A step delta is also refused when it carries a marker the merge does not recognise: a non-boolean "remove", an "action" that is neither "insert" nor "delete", a "captureJumps" outside an insert, or no "stepNumber" to address. Inserting AT a jump target relocates those jumps past the inserted step by default (a NOTICE is returned) \u2014 add "captureJumps": true on the inserted step to retarget entry jumps onto it (loop/try endStep region tails always relocate with the body and are never captured). Every jump field has a "*Label" twin (toLabel, onFalseLabel, endLabel, \u2026, and "label" on a cases/catches entry) resolved against step labels AFTER the merge, so a delta may anchor on a label only pre-existing steps carry; a label the delta supplies REPLACES the stored number it twins, while setting the number and its label together in one delta is refused as a contradiction. Reference ids in deltas may use LOCAL names \u2014 they are qualified against the spec's namespace exactly as the loader would. Per-spec lint suppression: set "lint: { allow: [{ code, reason }] }" to silence a WARNING code on this spec only (errors always surface; stale allows are flagged). This delta is deliberately OPEN below its top level \u2014 the shapes nest further than a schema here should restate \u2014 so a key that is not a field at its depth is not refused, it is NAMED BACK under NO EFFECT in the answer, together with any value the spec already held and any "unset" that removed nothing. Read that list: it is where a nested typo shows up.`),
+        delta: import_zod11.z.record(import_zod11.z.any()).describe(`The partial fields to merge into the spec. ARRAYS UPSERT, they do not replace: an array whose elements carry an identity is merged element-by-element, so a delta naming ONE element leaves the others intact. Identity is "name" or "id" by default, and per field: dispatch by "capability", lifecycle by phase+component+method, emits/subscribesTo by topic+event, trustedLinks by "subsystem", invariants and patterns by "id", lint.allow by "code" AND "at" (an allow covers one occurrence, so several may share a code on one spec), an interface method's findings by "code", boundaries by "name", globalRequirements by "description", switch cases by "value", try catches by "error". Identity merging applies at EVERY depth, including an array INSIDE an element (a method's params, a step's catches). Add "action: 'delete'" (or "remove: true") alongside that identity to REMOVE an element \u2014 including a stale lint allow. Arrays of plain STRINGS (owns, dependsOn, guarantees) carry no per-element identity and are replaced wholesale; pass [] to clear any array outright. To REMOVE an optional field entirely, list it in "unset": e.g. {"unset": ["basePath", "variant"]} \u2014 passing null/undefined means "no change" (they are skipped), and writing "" would leave the field present but empty, which is a different and usually wrong spec. Unsetting a required field is refused by schema validation, which names it. For narrative steps, match by "stepNumber" and use "action: 'insert'" (shifts subsequent steps up) or "action: 'delete'" (shifts subsequent steps down and removes it). Step entries apply in ASCENDING stepNumber order, each against the numbering the earlier entries of the SAME delta left behind \u2014 delete step 3 and step 7 becomes step 6 \u2014 so prefer labels, and restate the step's "label" or "description" on a delete to have it checked against the step actually addressed. Renumbering RELOCATES every flow jump field (onTrueStep/onFalseStep/cases.step/defaultStep/endStep/catches.step/finallyStep/toStep) in the same narrative. A delete is REJECTED when the narrative has no such step, when a jump still targets it (retarget the referrers first), when a restated label/description does not match, or when it is a loop/try/parallel header whose body would be left standing (retype the header first to dissolve the region, then delete it). Changing a step's "type" REBUILDS it for the new type: its description and label are kept and every field the new type cannot carry is dropped (returned as a NOTICE); a delta that retypes AND sets such a field is refused. A step delta is also refused when it carries a marker the merge does not recognise: a non-boolean "remove", an "action" that is neither "insert" nor "delete", a "captureJumps" outside an insert, or no "stepNumber" to address. Inserting AT a jump target relocates those jumps past the inserted step by default (a NOTICE is returned) \u2014 add "captureJumps": true on the inserted step to retarget entry jumps onto it (loop/try endStep region tails always relocate with the body and are never captured). Every jump field has a "*Label" twin (toLabel, onFalseLabel, endLabel, \u2026, and "label" on a cases/catches entry) resolved against step labels AFTER the merge, so a delta may anchor on a label only pre-existing steps carry; a label the delta supplies REPLACES the stored number it twins, while setting the number and its label together in one delta is refused as a contradiction. Reference ids in deltas may use LOCAL names \u2014 they are qualified against the spec's namespace exactly as the loader would. Per-spec lint suppression: set "lint: { allow: [{ code, at, covers, reason }] }" to silence a WARNING code on this spec only (errors always surface; stale allows are flagged). An allow covers EXACTLY the occurrence it names: "at" is the site the finding names (a contract method, an import edge "from -> to", a declared edge "component -> target") and is REQUIRED for a code whose findings report one, while a finding that reports no site is covered only by an allow that names none; "covers" lists the units an aggregating finding reports, and the allow silences it only when every one is listed. This delta is deliberately OPEN below its top level \u2014 the shapes nest further than a schema here should restate \u2014 so a key that is not a field at its depth is not refused, it is NAMED BACK under NO EFFECT in the answer, together with any value the spec already held and any "unset" that removed nothing. Read that list: it is where a nested typo shows up.`),
         dryRun: import_zod11.z.boolean().optional().describe("Ask what this delta WOULD do instead of doing it. The whole write runs, the candidate gate included, and the answer is the change report it would have produced \u2014 marked DRY RUN, with nothing stamped and not one byte of the stored file moved. Use it before a delta that renumbers a long narrative.")
       },
       outputSchema: specChangeReportOutput
@@ -31008,6 +31183,20 @@ init_loader();
 init_errors();
 init_core();
 init_validation();
+function carriedDebtSummary(carried) {
+  if (!carried || carried.length === 0) return null;
+  const findings = carried.flatMap((g) => g.findings ?? []);
+  const units = findings.reduce((n, f) => n + (f.covers?.length ?? 1), 0);
+  const perKind = (kind) => carried.filter((g) => g.kind === kind).reduce((n, g) => n + (g.findings?.length ?? 0), 0);
+  const provisional = carried.filter((g) => g.revisit);
+  const unsettled = provisional.reduce((n, g) => n + (g.findings?.length ?? 0), 0);
+  return {
+    line: `Conformance debt register: ${findings.length} finding(s) over ${units} unit(s) carried \u2014 ${perKind("drift")} drift, ${perKind("undecided")} undecided, ${perKind("unreadable")} unreadable (\`rules.conformance.carried\`). Drift and undecided are owed; unreadable is what the analysis cannot follow.` + (unsettled > 0 ? ` ${unsettled} finding(s) in ${provisional.length} group(s) are marked for re-evaluation \u2014 the classification is provisional, not the debt.` : ""),
+    revisits: provisional.map(
+      (g) => `  re-evaluate (${g.kind}, ${g.findings?.length ?? 0} finding(s)): ${g.revisit}`
+    )
+  };
+}
 function isCiDraftWaivable(issue2) {
   if (issue2.severity !== "warning") return false;
   if (issue2.code === "DRAFT_SUBSYSTEM_WARNING") return true;
@@ -31123,15 +31312,11 @@ async function runValidate(options = {}) {
       }
     }
   }
-  const carried = projectConfig.rules?.conformance?.carried ?? [];
-  if (carried.length > 0) {
-    const findings = carried.flatMap((g) => g.findings ?? []);
-    const units = findings.reduce((n, f) => n + (f.covers?.length ?? 1), 0);
-    const perKind = (kind) => carried.filter((g) => g.kind === kind).reduce((n, g) => n + (g.findings?.length ?? 0), 0);
+  const summary = carriedDebtSummary(projectConfig.rules?.conformance?.carried);
+  if (summary) {
     logger.blank();
-    logger.info(import_chalk7.default.yellow(
-      `Conformance debt register: ${findings.length} finding(s) over ${units} unit(s) carried \u2014 ${perKind("drift")} drift, ${perKind("undecided")} undecided, ${perKind("unreadable")} unreadable (\`rules.conformance.carried\`). Drift and undecided are owed; unreadable is what the analysis cannot follow.`
-    ));
+    logger.info(import_chalk7.default.yellow(summary.line));
+    for (const note of summary.revisits) logger.info(import_chalk7.default.gray(note));
   }
   logger.blank();
   if (options.ci && waivedWarnings > 0) {