@wairon/cli 5.1.1-dev.19 → 5.1.1-dev.20

package/dist/index.js

@@ -500,7 +500,12 @@ var init_project = __esm({
       maxInterfaceMethods: import_zod3.z.number().int().nonnegative().optional(),
       /** Maximum number of dependencies allowed on a single component */
       maxComponentDependencies: import_zod3.z.number().int().nonnegative().optional(),
-      /** Maximum number of narrative steps allowed in a single method implementation */
+      /**
+       * Maximum number of narrative steps allowed in a single method
+       * implementation, reported as a warning. The narrative-complexity rule
+       * applies a default of 25 when this is unset — the default belongs to the
+       * rule, not this schema.
+       */
       maxNarrativeSteps: import_zod3.z.number().int().nonnegative().optional(),
       /** Maximum number of direct components allowed in a single subsystem */
       maxSubsystemComponents: import_zod3.z.number().int().nonnegative().optional(),
@@ -510,7 +515,23 @@ var init_project = __esm({
        * narrative — above it the detail-sufficiency lint fires
        * (UNNARRATED_COMPLEXITY). Default 8 when unset.
        */
-      maxUnnarratedComplexity: import_zod3.z.number().int().nonnegative().optional()
+      maxUnnarratedComplexity: import_zod3.z.number().int().nonnegative().optional(),
+      /**
+       * Step count above which a narrative is an error rather than a warning. No
+       * default: unset means the step count only ever warns.
+       */
+      narrativeStepsHardMax: import_zod3.z.number().int().nonnegative().optional(),
+      /**
+       * The complexity band (linear | simple | moderate | complex | severe) a
+       * narrative may reach before it warns. Defaults to moderate when unset, so
+       * complex and severe warn.
+       */
+      cognitiveWarnAbove: import_zod3.z.string().optional(),
+      /**
+       * The complexity band above which a narrative is an error rather than a
+       * warning. No default: unset means the cognitive band only ever warns.
+       */
+      maxCognitiveLevel: import_zod3.z.string().optional()
     });
     DesignDepthSchema = import_zod3.z.enum(["components", "interfaces", "implementations", "narratives"]);
     RulesConfigSchema = import_zod3.z.object({
@@ -1092,7 +1113,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.19";
+    WAIRON_VERSION = "5.1.1-dev.20";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -1425,6 +1446,17 @@ function holdsState(component) {
 function isRetired(component) {
   return RETIRED_STEREOTYPES.has(component.componentType);
 }
+function headNoun(component) {
+  const words2 = component.id.split(/[-_]/).filter(Boolean);
+  return words2[words2.length - 1] ?? "";
+}
+function conceptNoun(component) {
+  const words2 = component.id.split(/[-_]/).filter(Boolean);
+  for (let i = words2.length - 1; i >= 0; i--) {
+    if (!BLOCK_NOUNS.has(words2[i])) return words2[i];
+  }
+  return "";
+}
 function passesIntentFloor(text, methodName) {
   if (!text) return false;
   const t = text.trim();
@@ -1441,6 +1473,39 @@ function effectiveDetail(method, implementation, component) {
   if (implementation.detail) return { level: implementation.detail, explicit: true };
   return { level: defaultNarrativeDetail(component), explicit: false };
 }
+function cognitiveScore(method) {
+  const steps = method.narrative ?? [];
+  const regions = steps.filter((s) => (s.type === "loop" || s.type === "try" || s.type === "parallel") && s.endStep !== void 0).map((s) => ({ start: s.stepNumber, end: s.endStep }));
+  const nestingDepthAt = (stepNumber) => regions.filter((r) => stepNumber > r.start && stepNumber <= r.end).length;
+  let score = 0;
+  for (const s of steps) {
+    switch (s.type) {
+      case "branch":
+      case "switch":
+      case "loop":
+      case "parallel":
+        score += 1 + nestingDepthAt(s.stepNumber);
+        break;
+      case "try":
+        for (const c of s.catches ?? []) score += 1 + nestingDepthAt(c.step);
+        break;
+      case "jump":
+        score += 1;
+        break;
+      default:
+        break;
+    }
+  }
+  return score;
+}
+function complexityLevel(method) {
+  const score = cognitiveScore(method);
+  if (score >= 20) return "severe";
+  if (score >= 10) return "complex";
+  if (score >= 5) return "moderate";
+  if (score >= 1) return "simple";
+  return "linear";
+}
 function implementationSourceFiles(impl) {
   const files = [];
   const add = (file) => {
@@ -1450,7 +1515,7 @@ function implementationSourceFiles(impl) {
   for (const method of impl.methods ?? []) add(method.sourcePath);
   return files;
 }
-var import_zod8, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, ComponentSpecSchema, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
+var import_zod8, SpecIdSchema, SpecStatusSchema, BoundaryItemSchema, RequirementItemSchema, DatabaseSpecSchema, DiagramConfigSchema, SURFACE_AUDIENCES, SurfaceAudienceSchema, SystemPublicInterfaceSchema, SystemSpecSchema, PublicInterfaceTypeSchema, PublicInterfaceSchema, TrustedLinkSchema, LintAllowSchema, LintConfigSchema, ExtDataSchema, LifecycleEntrypointSchema, SubsystemSpecSchema, ComponentTypeSchema, PATTERN_TYPES, RETIRED_STEREOTYPES, PortalTypeSchema, DispatchBindingSchema, DurabilitySchema, DependencyClassSchema, PatternRefSchema, EventBindingSchema, ExternalLinkTypeSchema, ExternalLinkSchema, PortalAuthSchemeSchema, PortalAuthSchema, ComponentSpecSchema, BLOCK_NOUNS, HttpMethodSchema, TransportSchema, EndpointSchema, SEMANTIC_GUARANTEES, GuaranteeSchema, MethodParamSchema, FindingDeclarationSchema, MethodSignatureSchema, INTENT_FLOOR_MIN_CHARS, InterfaceSpecSchema, NarrativeStepTypeSchema, LoopKindSchema, SwitchCaseSchema, CatchClauseSchema, ParallelBranchSchema, NarrativeStepSchema, NarrativeDetailSchema, ConformanceTierSchema, MethodImplementationSchema, ImplementationSpecSchema, TypeKindSchema, TypeFieldSchema, TypeMethodSchema, InvariantSchema, TypeSpecSchema, SurfaceOriginSchema, SurfaceTypeDefSchema, SurfaceContractEntrySchema, SurfaceSnapshotSchema, NamedOpenApiSpecSchema, GroupSpecSchema;
 var init_specs = __esm({
   "src/models/specs.ts"() {
     "use strict";
@@ -1728,6 +1793,20 @@ var init_specs = __esm({
       createdAt: import_zod8.z.string().datetime(),
       updatedAt: import_zod8.z.string().datetime()
     });
+    BLOCK_NOUNS = /* @__PURE__ */ new Set([
+      "portal",
+      "orchestrator",
+      "supervisor",
+      "actor",
+      "store",
+      "index",
+      "query",
+      "registry",
+      "adapter",
+      "observer",
+      "repository",
+      "view"
+    ]);
     HttpMethodSchema = import_zod8.z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "HEAD"]);
     TransportSchema = import_zod8.z.enum(["HTTP", "gRPC", "GraphQL", "MessageBus", "NamedPipe", "IPC", "CLI", "Custom"]);
     EndpointSchema = import_zod8.z.discriminatedUnion("transport", [
@@ -10780,7 +10859,7 @@ var init_declarative_assertions = __esm({
     "use strict";
     declarativeAssertionsRule = {
       name: "declarative-assertions",
-      description: "Evaluates the declarative rule assertions loaded packs declare (forbid-edge / require-field / endpoint-shape) \u2014 closed kinds instantiated with pack data, the hosted-safe doctrine channel. Findings carry the pack's namespaced code (<PACK>_<CODE>) and its stated reason; severity is the pack's declaration (project sddRuleSeverity still wins, and error downgrades to warning in draft context).",
+      description: "Evaluates the declarative rule assertions loaded packs declare (forbid-edge / require-field / endpoint-shape) \u2014 closed kinds instantiated with pack data, the hosted-safe doctrine channel. Findings carry the pack's namespaced code (<PACK>_<CODE>) and its stated reason; severity is the pack's declaration (project sddRuleSeverity still wins, and error downgrades to warning in draft context). The codes are the packs' own, so no fixed code list applies.",
       // Static codes are unknown here — packs bring their own. The validator
       // gathers every loaded assertion's fullCode into knownIssueCodes.
       codes: [],
@@ -12058,7 +12137,7 @@ var init_hidden_state = __esm({
     isStatelessLogic = (component) => isLogic(component) && !holdsState(component);
     hiddenStateRule = {
       name: "hidden-state",
-      description: "The fields-vs-Store criterion, statically approximated: module-scope mutable bindings (let/var) in a source file mapped EXCLUSIVELY to stateless logic (Orchestrators, and Specialists until they are migrated) \u2014 a component maps every file its implementations and their methods name \u2014 are flagged as hidden held state \u2014 state a logic component keeps for itself is invisible to the spec, the canvas, and every persistence rule. Promote it to a Store (durability: cache for loss-safe memo state), or lint.allow with the reason it is genuinely wiring/ephemeral. Exact analysis grade only; files also mapped to data or boundary components, or to a Supervisor or Actor (which hold runtime state by definition), are exempt (N:1 collapse); const-bound container mutation is beyond this check and the finding says so.",
+      description: "The fields-vs-Store criterion, statically approximated: module-scope mutable bindings (let/var) in a source file mapped EXCLUSIVELY to logic that holds no state (a component whose type isLogic() and not holdsState(): an Orchestrator, or a Specialist until it is retired) are flagged as hidden held state. A component maps every file its implementations and their methods name. State a logic component keeps for itself is invisible to the spec, the canvas, and every persistence rule: promote it to a Store (durability: cache for loss-safe memo state), or lint.allow with the reason it is genuinely wiring or ephemeral. Supervisor and Actor files may hold runtime state. Exact analysis grade only; files also mapped to data or boundary components are exempt (N:1 collapse); const-bound container mutation is beyond this check and the finding says so.",
       codes: [
         { code: "HIDDEN_STATE", defaultSeverity: "warning", summary: "Module-scope mutable binding in a file mapped only to stateless logic (Orchestrators) \u2014 held state hiding outside a Store, Supervisor or Actor" }
       ],
@@ -12669,11 +12748,11 @@ function makeMatcher(tech) {
   const n = parts.length;
   return (text) => {
     if (!text) return false;
-    const words = text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
-    if (words.some((w) => w.includes(joined))) return true;
+    const words2 = text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    if (words2.some((w) => w.includes(joined))) return true;
     if (n < 2) return false;
-    for (let i = 0; i + n <= words.length; i++) {
-      if (words.slice(i, i + n).join("").includes(joined)) return true;
+    for (let i = 0; i + n <= words2.length; i++) {
+      if (words2.slice(i, i + n).join("").includes(joined)) return true;
     }
     return false;
   };
@@ -13079,14 +13158,13 @@ var init_complexity_and_metadata = __esm({
     init_models();
     complexityRule = {
       name: "complexity-and-metadata",
-      description: "Enforces metadata documentation completeness (checking if descriptions are missing or too short) and structural complexity caps (limits on methods per interface, dependencies per component, and narrative steps per method) configured globally or in architectural profiles.",
+      description: "Enforces metadata documentation completeness (checking if descriptions are missing or too short) and structural complexity caps (limits on methods per interface, parameters per method, dependencies per component, and components per subsystem) configured globally or in architectural profiles. A narrative's own length and shape are judged by narrative-complexity.",
       codes: [
         { code: "MISSING_DESCRIPTION", defaultSeverity: "warning", summary: "Required description field is missing or empty" },
         { code: "DESCRIPTION_TOO_SHORT", defaultSeverity: "warning", summary: "Description is shorter than the configured minimum length" },
         { code: "EXCESSIVE_METHODS", defaultSeverity: "warning", summary: "Interface declares more methods than the configured limit" },
         { code: "EXCESSIVE_METHOD_PARAMS", defaultSeverity: "warning", summary: "Interface method declares more parameters than the configured limit" },
         { code: "EXCESSIVE_DEPENDENCIES", defaultSeverity: "warning", summary: "Component has more dependencies than the configured limit" },
-        { code: "EXCESSIVE_NARRATIVE_STEPS", defaultSeverity: "warning", summary: "Method implementation contains more narrative steps than the configured limit" },
         { code: "EXCESSIVE_SUBSYSTEM_COMPONENTS", defaultSeverity: "warning", summary: "Subsystem has more direct components than the configured limit" }
       ],
       check(ctx) {
@@ -13174,25 +13252,6 @@ var init_complexity_and_metadata = __esm({
             }
           }
         }
-        for (const impl of ctx.implementations) {
-          const intf = ctx.interfaceMap.get(impl.contract);
-          const comp = intf ? ctx.componentMap.get(intf.component) : void 0;
-          const complexityConfig = ctx.complexityConfigFor(comp?.subsystem);
-          const isDraft = ctx.isImplementationDraft(impl);
-          if (complexityConfig?.maxNarrativeSteps !== void 0) {
-            for (const m of impl.methods) {
-              if (m.narrative.length > complexityConfig.maxNarrativeSteps) {
-                ctx.addIssue(
-                  "warning",
-                  "EXCESSIVE_NARRATIVE_STEPS",
-                  `Method "${m.name}" in implementation "${impl.id}" contains ${m.narrative.length} narrative steps, exceeding the configured limit of ${complexityConfig.maxNarrativeSteps}.`,
-                  impl.id,
-                  isDraft
-                );
-              }
-            }
-          }
-        }
         for (const t of ctx.types) {
           const docConfig = ctx.documentationConfigFor(t.subsystem);
           checkDescription(
@@ -13232,6 +13291,285 @@ var init_complexity_and_metadata = __esm({
   }
 });
 
+// src/core/rules/heuristic/narrative-complexity.ts
+function bandIndex(band) {
+  return BANDS.indexOf(band ?? "");
+}
+var BANDS, DEFAULT_WARN_ABOVE, DEFAULT_MAX_STEPS, narrativeComplexityRule;
+var init_narrative_complexity = __esm({
+  "src/core/rules/heuristic/narrative-complexity.ts"() {
+    "use strict";
+    init_models();
+    BANDS = ["linear", "simple", "moderate", "complex", "severe"];
+    DEFAULT_WARN_ABOVE = "moderate";
+    DEFAULT_MAX_STEPS = 25;
+    narrativeComplexityRule = {
+      name: "narrative-complexity",
+      description: "Judges a narrative on two independent axes: the cognitive band its shape earns, from branching and nesting, and the number of steps it lists. A flat list of registrations is long but linear; a deeply nested guard is short but severe. Each axis warns above its configured level, and reports an error only where a maximum is configured.",
+      codes: [
+        { code: "NARRATIVE_COMPLEXITY", defaultSeverity: "warning", summary: "Narrative's cognitive band is above the configured level (default: above moderate)" },
+        { code: "NARRATIVE_COMPLEXITY_OVER_MAX", defaultSeverity: "error", summary: "Narrative's cognitive band is above the configured maximum band" },
+        { code: "EXCESSIVE_NARRATIVE_STEPS", defaultSeverity: "warning", summary: "Method implementation contains more narrative steps than the configured limit (default 25)" },
+        { code: "NARRATIVE_STEPS_OVER_MAX", defaultSeverity: "error", summary: "Narrative step count is above the configured hard maximum" }
+      ],
+      check(ctx) {
+        const entries = [];
+        for (const impl of ctx.implementations) {
+          const intf = ctx.interfaceMap.get(impl.contract);
+          const comp = intf ? ctx.componentMap.get(intf.component) : void 0;
+          if (!comp) continue;
+          for (const method of impl.methods) {
+            if ((method.narrative ?? []).length === 0) continue;
+            entries.push({ implementation: impl, method, component: comp, subsystem: comp.subsystem });
+          }
+        }
+        for (const entry of entries) {
+          const cfg = ctx.complexityConfigFor(entry.subsystem);
+          const isDraft = ctx.isImplementationDraft(entry.implementation);
+          const steps = entry.method.narrative.length;
+          const score = cognitiveScore(entry.method);
+          const band = complexityLevel(entry.method);
+          const warnAbove = cfg?.cognitiveWarnAbove ?? DEFAULT_WARN_ABOVE;
+          if (bandIndex(band) > bandIndex(warnAbove)) {
+            ctx.addIssue(
+              "warning",
+              "NARRATIVE_COMPLEXITY",
+              `Method "${entry.method.name}" in implementation "${entry.implementation.id}" has a ${band} narrative (cognitive score ${score}), above the configured "${warnAbove}" band. Split it into steps that call smaller methods.`,
+              entry.implementation.id,
+              isDraft
+            );
+          }
+          if (cfg?.maxCognitiveLevel !== void 0 && bandIndex(band) > bandIndex(cfg.maxCognitiveLevel)) {
+            ctx.addIssue(
+              "error",
+              "NARRATIVE_COMPLEXITY_OVER_MAX",
+              `Method "${entry.method.name}" in implementation "${entry.implementation.id}" has a ${band} narrative (cognitive score ${score}), above the configured maximum band "${cfg.maxCognitiveLevel}". Split it into steps that call smaller methods.`,
+              entry.implementation.id,
+              isDraft
+            );
+          }
+          const maxSteps = cfg?.maxNarrativeSteps ?? DEFAULT_MAX_STEPS;
+          if (steps > maxSteps) {
+            ctx.addIssue(
+              "warning",
+              "EXCESSIVE_NARRATIVE_STEPS",
+              `Method "${entry.method.name}" in implementation "${entry.implementation.id}" contains ${steps} narrative steps, exceeding the configured limit of ${maxSteps}.`,
+              entry.implementation.id,
+              isDraft
+            );
+          }
+          if (cfg?.narrativeStepsHardMax !== void 0 && steps > cfg.narrativeStepsHardMax) {
+            ctx.addIssue(
+              "error",
+              "NARRATIVE_STEPS_OVER_MAX",
+              `Method "${entry.method.name}" in implementation "${entry.implementation.id}" lists ${steps} narrative steps, above the configured hard maximum of ${cfg.narrativeStepsHardMax}. Extract part of the flow into a method of its own.`,
+              entry.implementation.id,
+              isDraft
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/core/rules/heuristic/naming-discipline.ts
+function words(identifier) {
+  return identifier.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[\s\-_]+/).filter(Boolean).map((w) => w.toLowerCase());
+}
+function isSameNoun(word, noun) {
+  if (word === noun) return true;
+  if (word === `${noun}s`) return true;
+  return noun.endsWith("s") && word === noun.slice(0, -1);
+}
+function withoutWord(methodWords, dropIndex) {
+  const kept = methodWords.filter((_, i) => i !== dropIndex);
+  return kept.map((w, i) => i === 0 ? w : w[0].toUpperCase() + w.slice(1)).join("");
+}
+var BLOCK_WORDS, GENERIC_WORDS, MIN_CONCEPT_LENGTH, namingDisciplineRule;
+var init_naming_discipline = __esm({
+  "src/core/rules/heuristic/naming-discipline.ts"() {
+    "use strict";
+    init_models();
+    BLOCK_WORDS = {
+      portal: "Portal",
+      orchestrator: "Orchestrator",
+      supervisor: "Supervisor",
+      actor: "Actor",
+      store: "Store",
+      index: "Index",
+      query: "Query",
+      registry: "Registry",
+      adapter: "Adapter",
+      observer: "Observer",
+      repository: "Repository",
+      view: "View"
+    };
+    GENERIC_WORDS = /* @__PURE__ */ new Set([
+      "manager",
+      "helper",
+      "helpers",
+      "util",
+      "utils",
+      "handler",
+      "service",
+      "processor",
+      "coordinator",
+      "engine",
+      "wrapper",
+      "common",
+      "misc",
+      "data",
+      "info"
+    ]);
+    MIN_CONCEPT_LENGTH = 4;
+    namingDisciplineRule = {
+      name: "naming-discipline",
+      description: "A name says what a thing is and never repeats itself: a component's head noun names its own block, generic role words say nothing, a method does not repeat its component's head noun, and a component with one method is not merely that method's name. Adapters and Portals are exempt from the repetition check, because a forwarder's method mirrors the command or route it exposes.",
+      codes: [
+        { code: "MISLEADING_BLOCK_WORD", defaultSeverity: "warning", summary: "Component's head noun names a building block that is not its componentType" },
+        { code: "GENERIC_COMPONENT_NAME", defaultSeverity: "warning", summary: "Component name or id uses a generic role word that says nothing (manager, helper, utils, handler, service)" },
+        { code: "METHOD_REPEATS_COMPONENT", defaultSeverity: "warning", summary: "Method name repeats its component's head noun; not reported on Adapter or Portal forwarders" },
+        { code: "COMPONENT_IS_ITS_ONLY_METHOD", defaultSeverity: "warning", summary: "Component with a single method is named after that method \u2014 fold it into its caller, or name it for its responsibility" }
+      ],
+      check(ctx) {
+        for (const comp of ctx.components) {
+          const head = headNoun(comp);
+          const isDraft = ctx.isComponentDraft(comp.id);
+          const idWords = [...words(comp.id), ...words(comp.name)];
+          if (BLOCK_WORDS[head] && BLOCK_WORDS[head] !== comp.componentType) {
+            ctx.addIssue(
+              "warning",
+              "MISLEADING_BLOCK_WORD",
+              `Component "${comp.id}" ends in "${head}", which names a ${BLOCK_WORDS[head]}, but it is declared a ${comp.componentType}. Rename it for what it is, or change its componentType.`,
+              comp.id,
+              isDraft
+            );
+          }
+          const generic = [...new Set(idWords.filter((w) => GENERIC_WORDS.has(w)))];
+          if (generic.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "GENERIC_COMPONENT_NAME",
+              `Component "${comp.id}" leans on the generic role word${generic.length > 1 ? "s" : ""} ${generic.map((w) => `"${w}"`).join(", ")}, which says nothing about what it does. Name it for its responsibility.`,
+              comp.id,
+              isDraft
+            );
+          }
+          const methods = ctx.interfaceMethodsOf(comp.id);
+          if (comp.componentType !== "Adapter" && methods.length === 1) {
+            const only = methods[0];
+            const concept = conceptNoun(comp);
+            const onlyWords = words(only.name);
+            if (onlyWords.length > 1 && onlyWords.some((w) => isSameNoun(w, concept))) {
+              ctx.addIssue(
+                "warning",
+                "COMPONENT_IS_ITS_ONLY_METHOD",
+                `Component "${comp.id}" declares one method, "${only.name}", and is named after it. Fold it into its caller, or name the component for the responsibility it holds.`,
+                comp.id,
+                isDraft
+              );
+            }
+          }
+        }
+        const pairs = [];
+        for (const intf of ctx.interfaces) {
+          const comp = ctx.componentMap.get(intf.component);
+          if (!comp || comp.componentType === "Adapter" || comp.componentType === "Portal") continue;
+          const concept = conceptNoun(comp);
+          if (concept.length < MIN_CONCEPT_LENGTH) continue;
+          for (const method of intf.methods) pairs.push({ intf, comp, concept, method });
+        }
+        for (const { intf, comp, concept, method } of pairs) {
+          const methodWords = words(method.name);
+          if (methodWords.length < 2 || !isSameNoun(methodWords[1], concept)) continue;
+          ctx.addIssue(
+            "warning",
+            "METHOD_REPEATS_COMPONENT",
+            `Method "${method.name}" on component "${comp.id}" repeats the component's concept "${concept}" \u2014 the call site says it twice. Name it "${withoutWord(methodWords, 1)}".`,
+            intf.id,
+            ctx.isComponentDraft(comp.id)
+          );
+        }
+      }
+    };
+  }
+});
+
+// src/core/rules/heuristic/method-cohesion.ts
+function groupsSharingCollaborators(calledBy) {
+  const parent = /* @__PURE__ */ new Map();
+  const find = (m) => {
+    let root = m;
+    while (parent.get(root) !== root) root = parent.get(root);
+    return root;
+  };
+  const union = (a, b) => {
+    const [ra, rb] = [find(a), find(b)];
+    if (ra !== rb) parent.set(ra, rb);
+  };
+  const methods = [...calledBy.keys()];
+  for (const m of methods) parent.set(m, m);
+  for (let i = 0; i < methods.length; i++) {
+    for (let j = i + 1; j < methods.length; j++) {
+      const shares = [...calledBy.get(methods[i])].some((c) => calledBy.get(methods[j])?.has(c));
+      if (shares) union(methods[i], methods[j]);
+    }
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const m of methods) {
+    const root = find(m);
+    groups.set(root, [...groups.get(root) ?? [], m]);
+  }
+  return [...groups.values()];
+}
+var methodCohesionRule;
+var init_method_cohesion = __esm({
+  "src/core/rules/heuristic/method-cohesion.ts"() {
+    "use strict";
+    methodCohesionRule = {
+      name: "method-cohesion",
+      description: "An Orchestrator's methods share collaborators; when they split into groups that call no component in common, the component holds more than one responsibility. Reported only where two or more groups each hold two or more methods, so a single specialized method is not a finding.",
+      codes: [
+        { code: "INCOHESIVE_METHODS", defaultSeverity: "warning", summary: "Orchestrator's methods form two or more groups of two or more that share no called component" }
+      ],
+      check(ctx) {
+        const subjects = [];
+        for (const impl of ctx.implementations) {
+          const intf = ctx.interfaceMap.get(impl.contract);
+          const comp = intf ? ctx.componentMap.get(intf.component) : void 0;
+          if (!comp || comp.componentType !== "Orchestrator") continue;
+          const calledBy = /* @__PURE__ */ new Map();
+          for (const method of impl.methods) {
+            const reached = /* @__PURE__ */ new Set();
+            for (const step of method.narrative ?? []) {
+              if ((step.type === "call" || step.type === "dispatch") && step.targetComponent) reached.add(step.targetComponent);
+            }
+            if (reached.size > 0) calledBy.set(method.name, reached);
+          }
+          subjects.push({ implementation: impl, component: comp, calledBy });
+        }
+        for (const { component, calledBy } of subjects) {
+          if (calledBy.size < 2) continue;
+          const groups = groupsSharingCollaborators(calledBy).filter((g) => g.length >= 2);
+          if (groups.length < 2) continue;
+          const described = groups.map((g) => {
+            const collaborators = [...new Set(g.flatMap((m) => [...calledBy.get(m)]))].sort();
+            return `${g.join(", ")} (calling ${collaborators.join(", ")})`;
+          }).join("; ");
+          ctx.addIssue(
+            "warning",
+            "INCOHESIVE_METHODS",
+            `Orchestrator "${component.id}" holds ${groups.length} groups of methods that share no called component: ${described}. Split it along those groups, or acknowledge a deliberate facade with a reasoned lint.allow for INCOHESIVE_METHODS.`,
+            component.id,
+            ctx.isComponentDraft(component.id)
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/repository.ts
 function addRule(rule) {
   ruleSet.push(rule);
@@ -13308,6 +13646,9 @@ var init_repository = __esm({
     init_technology_boundaries();
     init_naming_conventions();
     init_complexity_and_metadata();
+    init_narrative_complexity();
+    init_naming_discipline();
+    init_method_cohesion();
     SDD_RULES = [
       hierarchyRule,
       // Namespace integrity right after hierarchy: unresolvable/unwritable ids
@@ -13383,6 +13724,12 @@ var init_repository = __esm({
       technologyRule,
       namingRule,
       complexityRule,
+      // The doctrine heuristics ride with the structural caps: same subject
+      // (size, name, shape), judgements rather than errors, and they read the
+      // same complexity dial.
+      narrativeComplexityRule,
+      namingDisciplineRule,
+      methodCohesionRule,
       // Pack resolution and reproducibility run late: they are about project
       // CONFIGURATION (does the declared pack set resolve, and can it be reproduced
       // elsewhere?) rather than spec content.
@@ -13467,13 +13814,13 @@ function analyzeWithPatterns(text, patterns) {
   };
 }
 function analyzeGeneric(text) {
-  const words = /* @__PURE__ */ new Set();
-  for (const m of text.matchAll(IDENTIFIER_RE)) words.add(m[0]);
-  const anchors = new Set(words);
+  const words2 = /* @__PURE__ */ new Set();
+  for (const m of text.matchAll(IDENTIFIER_RE)) words2.add(m[0]);
+  const anchors = new Set(words2);
   for (const s of collectStrings(text)) anchors.add(s);
   return {
     analysisGrade: "generic",
-    declaredNames: [...words],
+    declaredNames: [...words2],
     anchoredNames: [...anchors],
     exportedNames: [],
     imports: [],
@@ -14103,7 +14450,7 @@ function buildRuleContext(opts) {
     const projectComp = rules?.complexity;
     const packDef = profileDefFor(subsystemId);
     if (packDef?.rules?.complexity) {
-      return { ...projectComp, ...packDef.rules.complexity };
+      return { ...packDef.rules.complexity, ...projectComp };
     }
     return projectComp;
   };
@@ -14111,7 +14458,7 @@ function buildRuleContext(opts) {
     const projectDoc = rules?.documentation;
     const packDef = profileDefFor(subsystemId);
     if (packDef?.rules?.documentation) {
-      return { ...projectDoc, ...packDef.rules.documentation };
+      return { ...packDef.rules.documentation, ...projectDoc };
     }
     return projectDoc;
   };
@@ -14120,11 +14467,11 @@ function buildRuleContext(opts) {
     const packDef = profileDefFor(subsystemId);
     if (packDef?.rules?.naming) {
       return {
-        ...projectNaming,
         ...packDef.rules.naming,
+        ...projectNaming,
         stereotypes: {
-          ...projectNaming?.stereotypes ?? {},
-          ...packDef.rules.naming.stereotypes ?? {}
+          ...packDef.rules.naming.stereotypes ?? {},
+          ...projectNaming?.stereotypes ?? {}
         }
       };
     }
@@ -24157,8 +24504,10 @@ __export(src_exports, {
   captureApprovedSpecs: () => captureApprovedSpecs,
   checkSkillFreshness: () => checkSkillFreshness,
   clearLoaderIssues: () => clearLoaderIssues,
+  cognitiveScore: () => cognitiveScore,
   collectPromotableSpecs: () => collectPromotableSpecs,
   commitStagedTree: () => commitStagedTree,
+  complexityLevel: () => complexityLevel,
   composeAgentBrief: () => composeAgentBrief,
   composeRuleSequence: () => composeRuleSequence,
   composeVariantGuidance: () => composeVariantGuidance,
@@ -24166,6 +24515,7 @@ __export(src_exports, {
   computePackDigest: () => computePackDigest,
   computeStateId: () => computeStateId,
   computeStateIdAt: () => computeStateIdAt,
+  conceptNoun: () => conceptNoun,
   consumedContractInputs: () => consumedContractInputs,
   contextDir: () => contextDir,
   createAgentRecord: () => createAgentRecord,
@@ -24245,6 +24595,7 @@ __export(src_exports, {
   hasAuthoredSpecs: () => hasAuthoredSpecs,
   hasContext: () => hasContext,
   hasSpecTree: () => hasSpecTree,
+  headNoun: () => headNoun,
   holdsState: () => holdsState,
   implementationSourceFiles: () => implementationSourceFiles,
   importSpecTree: () => importSpecTree,
@@ -24871,8 +25222,10 @@ function loadProjectConfig4() {
   captureApprovedSpecs,
   checkSkillFreshness,
   clearLoaderIssues,
+  cognitiveScore,
   collectPromotableSpecs,
   commitStagedTree,
+  complexityLevel,
   composeAgentBrief,
   composeRuleSequence,
   composeVariantGuidance,
@@ -24880,6 +25233,7 @@ function loadProjectConfig4() {
   computePackDigest,
   computeStateId,
   computeStateIdAt,
+  conceptNoun,
   consumedContractInputs,
   contextDir,
   createAgentRecord,
@@ -24959,6 +25313,7 @@ function loadProjectConfig4() {
   hasAuthoredSpecs,
   hasContext,
   hasSpecTree,
+  headNoun,
   holdsState,
   implementationSourceFiles,
   importSpecTree,