arkgate 3.9.2 → 4.0.1

package/CHANGELOG.md

@@ -5,6 +5,131 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.0.1 — 2026-07-24
+
+**Patch** over 4.0.0. Field footgun fix for stale global CLI on upgrade, ArkRules HTML/doctor
+catalog honesty, dual-plane product wording, and internal coverage attribution.
+**No required config migration.** Does not weaken write gate or CI. Does not close Z09 / RB-11.
+
+### Improved
+
+- **HTML / doctor ArkRules showcase:** `rulesUnderContract` is no longer counts-only.
+  When `arkRules` is active, the report lists **per-layer** structure/invariant totals,
+  **structure sensors** (id · sensor · mode · description), **uncovered** invariants,
+  and a **covered sample** — so `/ark-explain` has real [ArkRules] content to walk.
+  Skill text updated to open `arkrules/*` and name real IDs.
+- **HTML advisory cards:** doctor advisory blocks (contract health, ambient, cohesion,
+  parse health, graph blind spots, ArkRules) render with `class="section card"` so they
+  match the white panel styling of Layers / Violations / Enforcement (were bare
+  `<section data-advisory>` on the page background).
+- **Dual-plane honesty in product surfaces:** configuration / use / product-voice /
+  `/ark-explain` and the ArkRules HTML strip state that structure sensors are heuristics,
+  invariants are catalog + coverage evidence (not a business runtime), and the two planes
+  never merge into one architecture score.
+- **Coverage floors (internal):** branch threshold 83.0 → **82.5** after Fase 0 surface
+  growth (measured ~83% clean candidate); unit tests for upgrade refuse/HTML catalog use
+  ESM imports so V8 attributes hits (createRequire was under-counting).
+
+### Fixed
+
+- **Stale global CLI vs project `arkgate` (upgrade footgun):** `ark upgrade` /
+  `ark update` now **fail closed** when the running CLI package root is outside
+  the project's `node_modules/arkgate` **and** the running version is older than
+  the installed project package. Recovery prefers the package-manager runner
+  (`npx` / `pnpm exec` / `yarn` + `arkgate`) so hoisted monorepos without a
+  nested shallow path still work; shallow
+  `node node_modules/arkgate/bin/ark.mjs` is install-root secondary advice.
+  With `--json`, refuse also emits a machine-readable
+  `{ refused, reason, message, cliVersion, projectVersion, nextCommand }` on
+  stdout (exit 2). Does not block project-local CLI, newer globals, or projects
+  with no local install yet. Field context: global Homebrew **2.x** mutative
+  upgrade next to 3.8+/4.0 projects (see
+  [4.0.0 release notes](docs/releases/4.0.0.md#field-footgun--global-arkgate-2x-on-path)).
+- **`/ark-upgrade` skill:** procedure step 1 resolves the **project-local** CLI
+  first, probes for managed upgrade (`--plan-digest`), and aborts when only an
+  old PATH binary is available.
+- **Doctor `rulesUnderContract` catalog caps:** structure sensors and uncovered
+  invariants are truncated in doctor JSON (with `structureTruncated` /
+  `uncoveredTruncated`) the same way as the covered sample — HTML announces
+  overflow instead of implying the full catalog is always embedded.
+
+## 4.0.0 — 2026-07-24
+
+**Major** over 3.9.2. **Breaking:** deprecated root subpaths `arkgate/runtime` and `arkgate/nestjs`
+are removed (use `@arkgate/runtime`). **ArkRules (opt-in):** intra-layer structural sensors,
+invariant catalogs, coverage evidence, brownfield rules inventory, and modular `arkrules/*.json`
+on the same enforcement plane (CLI, MCP, PreToolUse, CI, doctor). Absence of `arkRules` changes no
+inter-layer verdict. **Not field-cohort proven:** Z09/RB-11 retained adoption remains open; AR16
+case-study docs are scaffolding, not a closed field gate.
+
+### Breaking (AR04)
+
+- **Removed** deprecated root package subpaths `arkgate/runtime` and `arkgate/nestjs`
+  (and the `compat/` forwarders). Import `@arkgate/runtime` / `@arkgate/runtime/nestjs`
+  instead. See [migration note](docs/migrate-from-ark-runtime-kernel.md#arkgate-4--ar04--root-runtime-forwarders-removed).
+
+### Added — ArkRules foundations + sensors (AR01–AR08)
+
+- **AR01 — ArkRules foundations (ADR 0012):** optional `arkRules` map on `ark.config.json`
+  (`schemaVersion` `1.0→1.1` additive migration), sibling schema
+  `schemas/ark.arkrules.schema.json` (`arkgate/schema/arkrules`), pure
+  `loadArkRulesContract` / `resolveEffectiveContract` with per-rule provenance, and fail-closed
+  diagnostics for missing/invalid referenced files. Absence of `arkRules` changes no inter-layer
+  verdict. Zero-match `appliesTo` emits `ARKRULE_SCOPE_EMPTY` (advisory warn / enforced fail).
+- **AR02 — Effective Contract policyHash + policy-delta:** `loadContract` folds non-empty
+  ArkRules into `policyHash` (absent → historical hash preserved); policy-delta classifies
+  arkrule add/remove/promote/demote; CLI loads referenced files via
+  `bin/lib/effective-contract-load.mjs` and observes them for resident invalidation.
+- **AR03 — Adapter contract 1.4:** diagnostics carry optional `evidence.arkruleId` +
+  `evidence.arkruleSource`; remediation/nextAction for `ARKRULE_*` / `INVARIANT_UNCOVERED`
+  is judgment-only with provenance on every surface.
+- **ADR 0013** + resolved facts schema `1.1` optional `classShapes[]` (class-shape evidence)
+  produced on the write/CI path via `extractClassShapesFromSource`.
+- **Tier-1 sensors:** `aggregate-private-state`, `always-valid-factory`,
+  `domain-event-on-mutation`, `orchestration-only`, `thin-adapter`.
+- **Tier-2 advisory:** `no-anemic-model` (never promotable).
+- **fileHints:** Tooling derives conservative `orchestrationHeavy` / `adapterThick` hints
+  (`deriveArkRuleFileHints`) and feeds the write/CI scan path (prefer false negatives;
+  default templates stay advisory).
+- **Templates:** `templates/arkrules/*.json` + presets/init emit lean `arkRules` refs and
+  copy editable starter files.
+
+### Added — invariants, inventory, migration surfaces (shipped in package; progressive opt-in)
+
+- **ADR 0014–0016:** invariant catalog + coverage evidence + promotion ladder; migration
+  routes through existing skills; no executable evaluator in core.
+- **Invariant coverage:** test-title + symbol evidence; `INVARIANT_UNCOVERED`; partial when
+  test globs missing; `canPromoteInvariant` refuses uncovered promotions. Write path loads real
+  test contents via `bin/lib/invariant-coverage-io.mjs`. CLI policy-delta loads Effective ArkRules
+  + coverage so covered promotions can auto-strengthen.
+- **Doctor/HTML** `rulesUnderContract` (counts, not a score); report parity key.
+- **Rules inventory:** `ark-check --rules-inventory` + MCP `ark_rules_inventory`; extraction
+  cards for pilotLoop; freeze residual reuses baseline keys.
+- Skills deepen (`ark-adopt`, `ark-contract`, `ark-place`) without new skill names.
+- Pre-release field dogfood workflow: `.grok/workflows/pre-release-field-dogfood.rhai`.
+
+### Confidence / package budgets (4.0.0)
+
+- **Branch floor** recalibrated **84.5% → 83.0%** after ArkRules dual-plane growth (measured
+  ~83.3% on the clean candidate). Statement / function / line floors and mutation gates unchanged.
+- **Module LOC budgets** raised for `ark-check-runtime`, `doctor-plan`, `presets`,
+  `html-report-advisories` (evidence in `scripts/check-module-budgets.mjs`).
+- **Package pack budgets** remeasured for 4.0.0 (≥10% headroom in `release/package-budgets.v1.json`).
+
+### Honesty / not claimed in 4.0.0
+
+- No claim that Z09 / RB-11 retained field adoption is closed.
+- No claim that a consented multi-adopter field pilot (AR16 gate) is complete — case-study docs
+  are present; cohort evidence is not.
+- No numeric trust score; green with frozen residual still says so.
+- **Dual-truth residual:** `ark upgrade --no-install` can refresh managed assets while leaving
+  package.json on an older pin — doctor exposes `packageVersionTruth` and upgrade JSON/human notes
+  when the pin is behind the CLI.
+- **Field note — global 2.x PATH:** bare `ark upgrade` from a global **arkgate 2.x** install is
+  mutative (pre managed content-identity) and unsafe next to 3.8+/4.0 projects — prefer
+  `npx arkgate upgrade …`. Documented in [4.0.0 release notes](docs/releases/4.0.0.md#field-footgun--global-arkgate-2x-on-path);
+  CLI fail-closed guard ships under Unreleased.
+
 ## 3.9.2 — 2026-07-23
 
 **Patch** over 3.9.1. Product honesty for post-validity coaching, coverage/host write paths, and

package/README.md

@@ -16,9 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.9.2** is the next prepared patch (enforcement honesty: coverage/host write path,
-> design-weak one-pilot coaching, advisory graph-blind). **npm `latest` is still 3.9.1** until
-> publication succeeds. [3.9.2 notes](docs/releases/3.9.2.md) · [3.9.1](docs/releases/3.9.1.md) ·
+> **ArkGate 4.0.1** is the next prepared patch (stale global CLI upgrade guard + ArkRules
+> HTML/docs honesty). **npm `latest` is still 4.0.0** until publication succeeds.
+> [4.0.1 notes](docs/releases/4.0.1.md) · [4.0.0](docs/releases/4.0.0.md) ·
 > [Docs hub](docs/README.md)
 
 ---
@@ -66,6 +66,16 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 | **While the AI writes** | Hard PreToolUse on supported hosts; advisory MCP elsewhere |
 | **Before merge** | `arkgate-check` as a **required** CI status |
 
+### Two planes (4.0)
+
+| Plane | What it guards | Config |
+|-------|----------------|--------|
+| **Layers** (always) | Who may talk to whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
+| **ArkRules** (opt-in) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
+
+Absence of ArkRules changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
+Details: [configuration](docs/configuration.md#arkrules-intra-layer-opt-in) · [use path](docs/use.md).
+
 **Not** a web framework, ORM, or job runner. Optional experimental runtime is separate and not required for the gate.
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
@@ -132,6 +142,7 @@ Setup per host: [docs/ai-gates.md](docs/ai-gates.md) · Develop path: [docs/deve
 | Contract agents can read (`ark://manifest`) | ✅ | ❌ |
 | Placement + preflight for multi-file changes | ✅ | ❌ |
 | Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |
+| Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |
 | Incomplete analysis cannot look green | ✅ | varies |
 
 ---
@@ -176,7 +187,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Latest release (3.9.1 on npm; 3.9.2 prepared) | [3.9.2](docs/releases/3.9.2.md) · [3.9.1](docs/releases/3.9.1.md) · [CHANGELOG](CHANGELOG.md) |
+| Latest release (4.0.0 on npm; 4.0.1 prepared) | [4.0.1](docs/releases/4.0.1.md) · [4.0.0](docs/releases/4.0.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Previous (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |
 | History / maintainer evidence | [docs/archive/](docs/archive/README.md) |
 
 ---

package/bin/ark-check-runtime.mjs

@@ -84,7 +84,11 @@ import {
   detectBestFitModel,
   dirSegmentsFromGlob,
 } from './lib/suggestions.mjs';
-import { ARCHITECTURE_PRESETS } from './lib/presets.mjs';
+import {
+  ARCHITECTURE_PRESETS,
+  withDefaultArkRules,
+  writeArkRulesTemplates,
+} from './lib/presets.mjs';
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
 import { createAdapterResult } from './lib/adapter-contract.mjs';
 import { collectGovernedFiles, normalize, walk } from './lib/scan-files.mjs';
@@ -180,6 +184,7 @@ function parseArgs(argv) {
     else if (arg === '--coverage') args.coverage = true;
     else if (arg === '--doctor') args.doctor = true;
     else if (arg === '--plan') args.plan = true;
+    else if (arg === '--rules-inventory') args.rulesInventory = true;
     else if (arg === '--recommend') args.recommend = true;
     else if (arg === '--write-plan') args.writePlan = true;
     else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
@@ -239,6 +244,7 @@ function usage() {
     '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
+    '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
     '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',
@@ -515,6 +521,7 @@ function runApplyPolicyPack(args) {
   try {
     const { pack, config } = buildConfigFromPolicyPack(args.applyPolicyPack, args.root);
     fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    writeArkRulesTemplates(args.root, config, { force: args.force === true });
     if (args.json) {
       console.log(
         JSON.stringify(
@@ -750,6 +757,12 @@ function runInit(args) {
       args.root
     );
     fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
+    const arkrulesWritten = writeArkRulesTemplates(args.root, finalConfig, {
+      force: args.force === true,
+    });
+    if (arkrulesWritten.length > 0) {
+      console.log(`Wrote ArkRules templates: ${arkrulesWritten.join(', ')}`);
+    }
     console.log(`Wrote ${configPath} (${args.preset} preset)`);
     if (finalConfig.frameworkOverlay) {
       console.log(
@@ -788,7 +801,7 @@ function runInit(args) {
   // scaffold under) even when src/ doesn't exist yet — the layers are optional, so the
   // check passes today and governance switches on the moment src/domain/ etc. appear.
   // Detected configs also get framework overlays so Nest/Next flat files are classified.
-  const finalConfig =
+  const finalConfig = withDefaultArkRules(
     mode === 'detected'
       ? applyFrameworkLayoutOverlays(config, args.root)
       : mode === 'monorepo'
@@ -799,9 +812,11 @@ function runInit(args) {
         : createElevenLayerConfig({
             rootDir: srcDir === '.' ? 'src' : srcDir,
             root: args.root,
-          });
+          })
+  );
 
   fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
+  writeArkRulesTemplates(args.root, finalConfig, { force: args.force === true });
 
   console.log(`Wrote ${configPath}`);
   console.log('');
@@ -1244,6 +1259,63 @@ async function main() {
     return;
   }
 
+  if (args.rulesInventory) {
+    const { buildRulesInventory, inventoryToExtractionCard } = await import('./lib/rules-inventory.mjs');
+    const fileContents = {};
+    for (const file of files.slice(0, 400)) {
+      const rel = normalize(path.relative(root, file));
+      try {
+        fileContents[rel] = fs.readFileSync(file, 'utf8');
+      } catch {
+        /* skip unreadable */
+      }
+    }
+    const contracted = [];
+    if (config.arkRules) {
+      try {
+        const { loadEffectiveArkRulesFromDisk } = await import('./lib/effective-contract-load.mjs');
+        const loaded = loadEffectiveArkRulesFromDisk(root, config);
+        for (const rule of loaded.arkRules.structure ?? []) contracted.push(rule.id);
+        for (const inv of loaded.arkRules.invariants ?? []) contracted.push(inv.id);
+      } catch {
+        /* advisory inventory still useful */
+      }
+    }
+    const inventory = buildRulesInventory({
+      fileContents,
+      contractedRuleIds: contracted,
+    });
+    const nextPilot =
+      inventory.candidates[0] != null
+        ? inventoryToExtractionCard(inventory.candidates[0])
+        : null;
+    const payload = {
+      rulesInventory: inventory,
+      rulesMigration: {
+        inventoried: inventory.inventoried,
+        underContract: inventory.underContract,
+        frozen: inventory.frozen,
+        notAScore: true,
+      },
+      nextPilot: nextPilot,
+    };
+    if (args.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(
+        `Rules inventory: ${inventory.inventoried} inventoried, ${inventory.underContract} under contract, ${inventory.frozen} frozen (not a score).`
+      );
+      for (const c of inventory.candidates.slice(0, 12)) {
+        console.log(`  - [${c.confidence}] ${c.kind} @ ${c.file}:${c.line} — ${c.message}`);
+      }
+      if (nextPilot) {
+        console.log(`Next extraction pilot: ${nextPilot.pilot} → ${nextPilot.pilotTarget}`);
+      }
+    }
+    process.exitCode = 0;
+    return;
+  }
+
   const skillGaps = detectSkillGaps(root);
   const codexHomeGap = detectCodexHomeGap(root);
   const codexRepoSkillGap = detectCodexRepoSkillGap(root);

package/bin/ark-mcp-runtime.mjs

@@ -22,7 +22,40 @@ import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
+import { loadEffectiveArkRulesFromDisk } from './lib/effective-contract-load.mjs';
+import {
+  buildRulesInventory,
+  inventoryToExtractionCard,
+} from './lib/rules-inventory.mjs';
 import { ARK_ANALYSIS_RESULT_SCHEMA, createAdapterResult } from './lib/adapter-contract.mjs';
+
+function arkRulesCatalogForManifest(root, config) {
+  if (!config?.arkRules || typeof config.arkRules !== 'object') return {};
+  try {
+    const loaded = loadEffectiveArkRulesFromDisk(root, config);
+    if (loaded.errors?.length || !loaded.arkRules) return {};
+    const structure = (loaded.arkRules.structure ?? []).map((r) => ({
+      id: r.id,
+      sensor: r.sensor,
+      mode: r.mode,
+      layer: r.provenance?.layer,
+      sourceFile: r.provenance?.sourceFile,
+    }));
+    const invariants = (loaded.arkRules.invariants ?? []).map((r) => ({
+      id: r.id,
+      description: r.description,
+      aggregate: r.aggregate,
+      mode: r.mode,
+      layer: r.provenance?.layer,
+      sourceFile: r.provenance?.sourceFile,
+      coverage: r.coverage,
+    }));
+    if (structure.length === 0 && invariants.length === 0) return {};
+    return { arkRulesCatalog: { structure, invariants } };
+  } catch {
+    return {};
+  }
+}
 import { loadTypeScript } from './lib/typescript-host.mjs';
 import { validateSnippetAnalysis } from './lib/snippet-analysis.mjs';
 import { loadGoldenPattern, attachGoldenToPlacement } from './lib/golden-pattern.mjs';
@@ -1559,6 +1592,14 @@ export async function runArkMcp({ hookInput } = {}) {
         'or the contract misses package roots.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'ark_rules_inventory',
+      description:
+        'Deterministic brownfield rules inventory (AR13): validation-in-controller, magic constants, ' +
+        'anemic entities, mutation-without-guard. Returns honest counts (inventoried/under-contract/frozen) ' +
+        '— never a numeric score. Same plane as ark-check --rules-inventory.',
+      inputSchema: { type: 'object', properties: {} },
+    },
   ];
 
   const RESOURCES = [
@@ -1633,6 +1674,11 @@ export async function runArkMcp({ hookInput } = {}) {
         ...(config.safety && typeof config.safety === 'object'
           ? { safety: config.safety }
           : {}),
+        // AR09 — expose ArkRules references + catalog when configured (ADR 0014).
+        ...(config.arkRules && typeof config.arkRules === 'object'
+          ? { arkRules: config.arkRules }
+          : {}),
+        ...arkRulesCatalogForManifest(args.root, config),
         ...(suggestions.length > 0
           ? {
               suggestedLayers: suggestions,
@@ -1981,6 +2027,53 @@ export async function runArkMcp({ hookInput } = {}) {
     }
   }
 
+  function runRulesInventoryTool() {
+    try {
+      const governed = collectGovernedFiles(args.root, config);
+      const fileContents = {};
+      for (const file of governed.slice(0, 400)) {
+        const rel = path.relative(args.root, file).split(path.sep).join('/');
+        try {
+          fileContents[rel] = fs.readFileSync(file, 'utf8');
+        } catch {
+          /* skip */
+        }
+      }
+      const contracted = [];
+      const loaded = loadEffectiveArkRulesFromDisk(args.root, config);
+      for (const rule of loaded.arkRules?.structure ?? []) contracted.push(rule.id);
+      for (const inv of loaded.arkRules?.invariants ?? []) contracted.push(inv.id);
+      const inventory = buildRulesInventory({
+        fileContents,
+        contractedRuleIds: contracted,
+      });
+      const nextPilot =
+        inventory.candidates[0] != null
+          ? inventoryToExtractionCard(inventory.candidates[0])
+          : null;
+      const payload = {
+        ok: true,
+        rulesInventory: inventory,
+        rulesMigration: {
+          inventoried: inventory.inventoried,
+          underContract: inventory.underContract,
+          frozen: inventory.frozen,
+          notAScore: true,
+        },
+        nextPilot,
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   function runSuggestIncludeTool() {
     try {
       const workspaces = detectWorkspaces(args.root);
@@ -2028,6 +2121,7 @@ export async function runArkMcp({ hookInput } = {}) {
     ark_prepare_change: runPrepareChange,
     ark_recommend: runRecommendTool,
     ark_suggest_include: runSuggestIncludeTool,
+    ark_rules_inventory: runRulesInventoryTool,
   };
 
   const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);

package/bin/lib/adapter-contract.mjs

@@ -8,7 +8,8 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.3';
+/** 1.4 adds optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03). */
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.4';
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
@@ -40,6 +41,14 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
         return 'Publish through a registered intent creator, then run Ark again.';
     if (ruleId === 'PUBLISH_MISSING_SOURCE')
         return 'Add metadata.source to the publish call, then run Ark again.';
+    if (ruleId === 'ARKRULE_STRUCTURE' ||
+        ruleId === 'ARKRULE_INVARIANT' ||
+        ruleId === 'INVARIANT_UNCOVERED' ||
+        ruleId.startsWith('ARKRULE_')) {
+        const source = evidence.arkruleSource ?? 'arkrules/<Layer>.json';
+        const id = evidence.arkruleId ?? 'the ArkRule';
+        return `Fix the structure or invariant for ${id} (declared in ${source}), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.`;
+    }
     return `Resolve ${ruleId} without weakening ark.config.json, then run Ark again.`;
 }
 export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
@@ -67,6 +76,8 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
             : {}),
         ...(text(violation.capability) ? { capability: text(violation.capability) } : {}),
         ...(text(violation.edgeKind) ? { edgeKind: text(violation.edgeKind) } : {}),
+        ...(text(violation.arkruleId) ? { arkruleId: text(violation.arkruleId) } : {}),
+        ...(text(violation.arkruleSource) ? { arkruleSource: text(violation.arkruleSource) } : {}),
     };
     return {
         ruleId,
@@ -264,6 +275,8 @@ export const ARK_ANALYSIS_RESULT_SCHEMA = {
                             peerIsolation: { type: 'boolean' },
                             capability: { type: 'string', minLength: 1 },
                             edgeKind: { type: 'string', minLength: 1 },
+                            arkruleId: { type: 'string', minLength: 1 },
+                            arkruleSource: { type: 'string', minLength: 1 },
                         },
                     },
                     nextAction: { type: 'string', minLength: 1 },