arkgate 4.2.1 → 4.4.0

package/bin/lib/ci-and-commands.mjs

@@ -11,10 +11,16 @@ import {
   DEFAULT_INTENT_PREFIXES,
   DEFAULT_LAYER_DIRECTORIES,
 } from '../ark-shared.mjs';
+import {
+  DEFAULT_AGENT_PROJECTION_RULE_IDS,
+  buildAgentProjectionBlock,
+} from './agent-projection.mjs';
+import { getDiagnosticCatalogEntry } from './diagnostic-catalog.mjs';
 import { falseGreenAdoptionGap } from './field-install.mjs';
 import { renderHostSupportMatrixMarkdown } from './host-support-matrix.mjs';
 import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
 import { hasCheckArchitectureScript, readPackageJson } from './gate-files.mjs';
+import { arkPackageVersion } from './skill-install.mjs';
 
 // Field-install helpers re-exported for callers that import from this module.
 export {
@@ -250,6 +256,37 @@ export function loadConfigLayersForAgents(root) {
   }
 }
 
+/**
+ * ACS04 — version-matched projection block embedded in install AGENTS templates.
+ * Labeled non-authoritative; never a gate input.
+ * @param {string} root
+ * @param {{ host?: string|null, profile?: 'compact'|'full' }} [opts]
+ */
+export function agentProjectionBlockForRoot(root, opts = {}) {
+  const liveLayers = loadConfigLayersForAgents(root);
+  const layerSummaries = Array.isArray(liveLayers)
+    ? liveLayers.map((layer) => ({
+        name: layer.name ?? layer.layer ?? 'Unknown',
+        patterns: layer.patterns ?? [],
+        intentPrefixes: layer.intentPrefixes ?? layer.prefixes ?? [],
+      }))
+    : [];
+  const catalogShortList = DEFAULT_AGENT_PROJECTION_RULE_IDS.map((ruleId) => {
+    const entry = getDiagnosticCatalogEntry(ruleId);
+    return { ruleId, title: entry?.title ?? ruleId };
+  });
+  const version = arkPackageVersion() || 'unknown';
+  return buildAgentProjectionBlock({
+    arkgateVersion: version,
+    checkCommand: arkCheckCommand(root),
+    layers: layerSummaries,
+    catalogShortList,
+    host: opts.host ?? null,
+    profile: opts.profile === 'compact' ? 'compact' : 'full',
+    diagnosticsDocsPath: 'docs/diagnostics.md',
+  });
+}
+
 export function agentInstructions(root) {
   const checkCmd = arkCheckCommand(root);
   const startCmd = arkCommand(root, 'ark', 'start');
@@ -259,6 +296,7 @@ export function agentInstructions(root) {
     .join('\n');
   const liveLayers = loadConfigLayersForAgents(root);
   const placementTable = layerPlacementTable(liveLayers);
+  const projectionBlock = agentProjectionBlockForRoot(root, { profile: 'full' });
   const placementBody = liveLayers
     ? `\`ark.config.json\` is authoritative for this project. Place new code in these **${liveLayers.length}** configured layer(s) — do not invent an ungoverned location or assume the stock 11-layer layout:
 
@@ -273,6 +311,7 @@ an ungoverned location:
 ${placementTable}`;
   return `# Ark Enforcement
 
+${projectionBlock}
 ## Default agent flow (if unsure, do only this)
 
 1. Status anytime: \`${doctorCmd}\` — **control plane** (one status light, one next action; not a mode picker).
@@ -350,19 +389,30 @@ export function compactAgentInstructions(root, host = null) {
     'ark-check',
     `--install-agent-gates --skills-only --tools ${selectedHost === 'none' ? '<host>' : selectedHost}`
   );
+  const projectionBlock = agentProjectionBlockForRoot(root, {
+    host: selectedHost === 'none' ? null : selectedHost,
+    profile: 'compact',
+  });
   // Progressive disclosure: primary path only. Full /ark-* catalog is expert depth
   // (install via --skills-only). See docs/product-voice.md.
   return `# Ark Enforcement
 
 <!-- arkgate:compact-router host=${selectedHost} -->
+${projectionBlock}
 ## Compact router
 
 **Primary path (do this):**
 
-1. Status anytime: \`${doctorCmd}\` — one status light, one next action (control plane).
-2. Before trusting MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means the process is stale: restart the host and use the local CLI meanwhile.
-3. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
-4. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+1. Status anytime: \`${doctorCmd}\` — one status light, one primary next action (control plane).
+2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
+3. Before trusting MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means the process is stale: restart the host and use the local CLI meanwhile.
+4. Day to day: call \`ark_manifest\` with the same project expectation; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified/non-authoritative. On a gate deny, fix the architecture — do not weaken the contract.
+5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+
+**Single door when residual remains:**
+- **Edges debt** (import/capability violations) → fix with the gate / plan; skill pack only if doctor names a skill.
+- **Design-weak / residual shape lenses** (compass residual while edges may look green) → map first, then guided apply with user OK — never “you’re done” on green edges alone.
+- Empty plan A + residual lenses / design-weak → **not finished**.
 
 The selected host is \`${selectedHost}\`. Host registration and CI are installed with this file.
 This compact router is enough for normal feature work.
@@ -370,7 +420,7 @@ This compact router is enough for normal feature work.
 ## Expert depth (optional)
 
 Full \`/ark-*\` skills (including guided end-to-end \`/ark-autopilot\`) are **not** the default
-curriculum. Install them only when doctor top action #1 or a STOP handoff names a skill:
+curriculum. Install them only when doctor top action #1, residual compass, or a STOP handoff names a skill:
 
 \`${installSkills}\`
 `;

package/bin/lib/diagnostic-catalog.mjs

@@ -0,0 +1,155 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/diagnosticCatalog.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/diagnostic-catalog.mjs). Zero Node I/O.
+ */
+
+/** Product-relative docs path (shipped in the npm tarball when listed in package files). */
+export const DIAGNOSTIC_DOCS_RELATIVE_PATH = 'docs/diagnostics.md';
+/** Schema id for serializing the catalog snapshot (agents / install projection). */
+export const DIAGNOSTIC_CATALOG_SCHEMA_VERSION = '1.0';
+function entry(ruleId, category, title, why, fix, extras) {
+    return {
+        ruleId,
+        title,
+        why,
+        fix,
+        docsAnchor: ruleId,
+        category,
+        ...(extras?.oftenAdvisory ? { oftenAdvisory: true } : {}),
+    };
+}
+/**
+ * Closed public catalog. Order is stable (category groups, then ruleId) for
+ * deterministic serialization and docs generation.
+ *
+ * Every production-emitted `ruleId` must appear here. Remediation switch cases
+ * and adapter nextAction branches are parity-tested against this list.
+ */
+export const DIAGNOSTIC_CATALOG = Object.freeze([
+    // ── layer / graph ────────────────────────────────────────────────────────
+    entry('LAYER_IMPORT_VIOLATION', 'layer', 'Layer import not allowed', 'A module import (or re-export) crosses a layer edge that ark.config.json does not allow. The architecture contract forbids that dependency direction so outer infrastructure cannot leak into pure or inner layers.', 'Define a port in the source layer, inject the outer-layer implementation, or move/share the type with `import type` when the edge is type-only — then preflight again. Do not weaken the layer rule without a hash-bound policy acknowledgement.'),
+    entry('LAYER_INTENT_REFERENCE_VIOLATION', 'layer', 'Intent referenced across a blocked layer edge', 'A string intent (or intent-like reference) names a layer that the file’s layer may not reach under the contract rules — the same plane as import edges, for event/intent coupling.', 'Reference that intent from a layer allowed to know about it (usually an adapter or application layer), or relocate the reference — then preflight again.'),
+    entry('LAYER_REFERENCE_VIOLATION', 'layer', 'Layer reference blocked (snippet / AI gate)', 'Snippet analysis found an intent or string reference that would couple layers in a direction the architecture profile forbids.', 'Move the reference to an allowed layer or introduce a port/event boundary, then re-run the snippet gate.'),
+    entry('CIRCULAR_DEPENDENCY', 'layer', 'Dependency cycle', 'Two or more modules import each other in a loop. Cycles make ownership unclear and break stable layer direction.', 'Extract the shared dependency into a third module, invert one edge behind a port, or merge units that are truly one — then preflight again.'),
+    // ── capability / ambient ─────────────────────────────────────────────────
+    entry('FORBIDDEN_GLOBAL', 'capability', 'Forbidden ambient global or dual import', 'The file’s layer lists this ambient (or its exact import dual, e.g. process / node:process) in forbiddenGlobals. Pure layers must not reach wall-clock, network, process, or similar effects directly.', 'Inject the capability through a small port (Clock, HttpPort, Config, …), bind the implementation outside the walled layer, then preflight again.'),
+    entry('CAPABILITY_VIOLATION', 'capability', 'Denied effect capability', 'The layer denies an effect capability (network, filesystem, clock, randomness, environment, process, persistence) and the candidate uses that effect via ambient or import evidence.', 'Define a capability port in the walled layer, bind the implementation in an adapter layer, then preflight again. Never mechanical-safe — port shape is a design decision.'),
+    // ── publish / intents ────────────────────────────────────────────────────
+    entry('RAW_EVENT_PUBLISH', 'publish', 'Raw event publish', 'Publish went through a raw string or object instead of a registered intent creator, bypassing Ark intent contracts and tooling.', 'Publish through a registered intent creator, then run Ark again.'),
+    entry('PUBLISH_MISSING_SOURCE', 'publish', 'Publish missing metadata.source', 'A strict Ark publish call omitted metadata.source, so the publishing layer cannot be verified.', 'Add metadata.source to the publish call, then run Ark again.'),
+    entry('PUBLISH_SOURCE_LAYER_MISMATCH', 'publish', 'Publish source layer mismatch', 'metadata.source resolves to a different layer than the file performing the publish.', 'Use a source intent owned by the same layer as this file, or move the publish call to the owning layer.'),
+    entry('UNKNOWN_INTENT', 'publish', 'Unknown intent reference', 'Snippet analysis saw an intent string that is not registered in the intent registry / profile under check.', 'Register the intent or use a known intent name from the project registry, then re-run the gate.'),
+    // ── safety thresholds / dynamic ──────────────────────────────────────────
+    entry('DYNAMIC_IMPORT_NOT_ALLOWLISTED', 'safety', 'Non-literal dynamic import', 'A dynamic import(expr) cannot be resolved statically and the file is not on dynamicImportAllowlist. Unresolved dynamics can hide layer edges.', 'Rewrite to a static import when possible, or add only reviewed files to dynamicImportAllowlist after human sign-off.'),
+    entry('DYNAMIC_REQUIRE_NOT_ALLOWLISTED', 'safety', 'Non-literal require', 'A require(expr) cannot be resolved statically and is not allowlisted — same hide-the-edge risk as dynamic import.', 'Prefer static import, or allowlist only reviewed files after sign-off.'),
+    entry('TS_SUPPRESSION_THRESHOLD_EXCEEDED', 'safety', '@ts-ignore / @ts-nocheck threshold', 'Count of TypeScript suppressions in governed production source exceeds safety.maxTsSuppressions.', 'Remove suppressions by fixing types, or raise the threshold only with an explicit production exception in ark.config.json.'),
+    entry('ANY_CAST_THRESHOLD_EXCEEDED', 'safety', 'Explicit any cast threshold', 'Count of explicit any casts exceeds safety.maxAnyCasts.', 'Replace any with precise types, or raise the threshold only with a documented exception.'),
+    entry('IN_MEMORY_STORE_IN_PRODUCTION_SOURCE', 'safety', 'In-memory store in production source', 'Governed production source references an Ark InMemory* store without safety.allowInMemory — durable systems should not ship ephemeral stores by accident.', 'Provide a durable store implementation, or set safety.allowInMemory only for an explicitly ephemeral service.'),
+    entry('PEER_ISOLATION_DISABLED', 'safety', 'peerIsolation disabled on a rule', 'A same-layer or peer rule disables peerIsolation (or omits it where required), which allows cross-slice coupling the contract otherwise blocks.', 'Restore peerIsolation: true, or set safety.allowDisabledPeerIsolation only with a documented production exception.'),
+    // ── ArkRules ─────────────────────────────────────────────────────────────
+    entry('ARKRULE_STRUCTURE', 'arkrules', 'ArkRule structure sensor failed', 'An opt-in ArkRules structure sensor (private state, factory shape, event publish, …) failed on a governed file for a declared arkruleId.', 'Restore the declared structure for the ArkRule (see arkruleSource), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.'),
+    entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
+    entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
+    entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Missing test globs report partial — never fake green.'),
+    // ── atomic preflight / change set ────────────────────────────────────────
+    entry('INVALID_CHANGE_PATH', 'preflight', 'Unsafe change path', 'A change set entry is not a safe, non-empty project-relative path (absolute, escape, empty, or NUL).', 'Use canonical project-relative paths only in the atomic change set, then preflight again.'),
+    entry('DUPLICATE_CHANGE_PATH', 'preflight', 'Duplicate path in change set', 'The atomic change set lists more than one operation for the same path.', 'Collapse to one create/update/delete per path, then preflight again.'),
+    entry('DELETE_TARGET_MISSING', 'preflight', 'Delete target missing', 'A delete operation targets a path that is not present in the supplied base tree.', 'Remove the delete, or include the file in the base tree facts, then preflight again.'),
+    entry('CHANGE_SET_EMPTY', 'preflight', 'Empty change set', 'Atomic preflight was invoked with no create, update, or delete operations.', 'Provide at least one change operation, then preflight again.'),
+    entry('FACTS_IDENTITY_MISMATCH', 'preflight', 'Base/candidate facts identity mismatch', 'Base and candidate resolved facts disagree on resolver, compiler, evidence requirements, or package identity — verdicts would not be comparable.', 'Regenerate both fact snapshots with the same resolver/compiler/evidence requirements, then preflight again.'),
+    entry('CANDIDATE_DELETE_NOT_APPLIED', 'preflight', 'Candidate still contains deleted path', 'Facts claim a delete, but the candidate tree still includes the path.', 'Ensure the candidate facts apply the delete (path absent), then preflight again.'),
+    entry('CANDIDATE_CHANGE_MISSING', 'preflight', 'Declared change missing from candidate', 'The change set declares a create/update whose path is missing from candidate facts.', 'Include the new content in the candidate facts (or drop the operation), then preflight again.'),
+    entry('CANDIDATE_CONTENT_HASH_MISMATCH', 'preflight', 'Candidate content hash mismatch', 'The candidate file content hash does not match the hash expected for the declared change.', 'Rebuild candidate facts from the exact proposed content, then preflight again.'),
+    entry('UNDECLARED_CANDIDATE_CHANGE', 'preflight', 'Undeclared candidate change', 'Candidate facts differ from base for a path that was not listed in the explicit change set.', 'Declare every path that changes in the atomic change set, then preflight again.'),
+    entry('ATOMIC_PREFLIGHT_UNAVAILABLE', 'preflight', 'Atomic preflight unavailable', 'The host/MCP path could not run the atomic preflight engine (missing facts, incomplete setup, or unsupported mode).', 'Use resolved-candidate facts / ark_prepare_change with a complete batch, or fall back to ark-check on disk. Do not treat missing preflight as green.'),
+    entry('DESIGN_SMELL_REGRESSION', 'preflight', 'Design smell regression on base-relative ratchet', 'Compared to the base ref, the candidate introduces or worsens a blocking design-smell class (e.g. domain-logic-in-ui) under --fail-on-new-smells.', 'Revert the regression or redesign so the smell does not worsen versus base, then re-run with the same base ref.'),
+    // ── analysis completeness / host ─────────────────────────────────────────
+    entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; analysis is partial and must not paint green.', 'Fix syntax/parse errors in governed files (or restore a usable TypeScript host), then re-run. Partial never means pass.'),
+    entry('ANALYSIS_HOST_UNAVAILABLE', 'analysis', 'Analysis host unavailable', 'No usable TypeScript / analysis host was available for this invocation.', 'Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.'),
+    entry('ADAPTER_NOT_ALLOWED_FOR_PORT', 'adapter', 'Adapter not allowed for port', 'Runtime/port wiring selected an adapter implementation that the architecture profile does not allow for that port.', 'Bind an allowed adapter for the port, or adjust the profile with an explicit policy decision — then re-run.'),
+    // ── AI snippet gate policy surface ───────────────────────────────────────
+    entry('FORBIDDEN_PATTERN', 'snippet-policy', 'Forbidden regex pattern', 'Snippet content matched a project or profile forbiddenPatterns rule.', 'Remove or rewrite the matching code so the pattern no longer matches, then re-run the snippet gate.'),
+    entry('FORBIDDEN_SUBSTRING', 'snippet-policy', 'Forbidden substring', 'Snippet content contained a forbidden substring from the AI gate options/profile.', 'Remove the forbidden substring, then re-run the snippet gate.'),
+    entry('FORBIDDEN_IMPORT', 'snippet-policy', 'Forbidden import target', 'Snippet imported or required a module listed as forbidden for the active profile.', 'Import an allowed module or inject the dependency behind a port, then re-run.'),
+    entry('POLICY_VIOLATION', 'snippet-policy', 'Policy engine violation', 'A registered Policy failed on the snippet or generated code under evaluation.', 'Adjust the code to satisfy the named policy, or change the policy only through an explicit contract decision.'),
+    entry('EXTENSION_ERROR', 'snippet-policy', 'AI gate extension error', 'A registered AICodeGate extension threw while analyzing the snippet.', 'Fix or remove the failing extension; do not ignore extension failures as pass.'),
+    entry('AST_ANALYZER_ERROR', 'snippet-policy', 'AST analyzer error', 'Built-in AST/symbol analysis failed (host error or unexpected analyzer exception).', 'Ensure TypeScript host and snippet are valid; re-run. If the analyzer crashes on valid input, file a bug with a minimal fixture.'),
+    // ── config diagnostics ───────────────────────────────────────────────────
+    entry('CONFIG_INVALID_DYNAMIC_IMPORT_ALLOWLIST', 'config', 'Invalid dynamicImportAllowlist', 'dynamicImportAllowlist is present but not an array of file globs.', 'Set dynamicImportAllowlist to an array of project-relative globs (or omit it).', { oftenAdvisory: true }),
+    entry('CONFIG_INVALID_SAFETY', 'config', 'Invalid safety object', 'The safety field is present but not an object.', 'Use a safety object with optional maxTsSuppressions, maxAnyCasts, allowInMemory, allowDisabledPeerIsolation.', { oftenAdvisory: true }),
+    entry('CONFIG_INVALID_SAFETY_THRESHOLD', 'config', 'Invalid safety threshold', 'A safety threshold (maxTsSuppressions / maxAnyCasts) is not a non-negative integer.', 'Set each threshold to a non-negative integer.', { oftenAdvisory: true }),
+    entry('CONFIG_NO_LAYERS', 'config', 'No layers configured', 'ark.config.json has no file layers, so import-boundary enforcement cannot classify files.', 'Declare at least one layer with name + patterns (or run ark start / a preset).', { oftenAdvisory: true }),
+    entry('CONFIG_LAYER_WITHOUT_NAME', 'config', 'Layer missing name', 'A configured layer entry has no name.', 'Give every layer a unique non-empty name.', { oftenAdvisory: true }),
+    entry('CONFIG_INVALID_FORBIDDEN_GLOBALS', 'config', 'Invalid forbiddenGlobals', 'A layer’s forbiddenGlobals is not an array of strings; the entry is ignored.', 'Use an array of strings (e.g. ["fetch", "Date.now"]).', { oftenAdvisory: true }),
+    entry('CONFIG_LAYER_WITHOUT_PATTERNS', 'config', 'Layer without patterns', 'A named layer has no file patterns and will never classify files.', 'Add patterns globs that match the layer’s source tree.', { oftenAdvisory: true }),
+    entry('CONFIG_INVALID_LAYER_PATTERN', 'config', 'Invalid layer pattern', 'A layer pattern is not a valid glob / failed to compile.', 'Fix the pattern syntax for that layer.', { oftenAdvisory: true }),
+    entry('CONFIG_LAYER_PATTERN_NO_MATCHES', 'config', 'Layer pattern matched no files', 'A layer pattern matched zero included files (often a typo or include mismatch).', 'Adjust the pattern or include roots so governed files match.', { oftenAdvisory: true }),
+    entry('CONFIG_DUPLICATE_LAYER', 'config', 'Duplicate layer name', 'The same layer name appears more than once in configuration.', 'Rename or merge duplicate layer entries.', { oftenAdvisory: true }),
+    entry('CONFIG_RULE_UNKNOWN_FROM_LAYER', 'config', 'Rule unknown from layer', 'A dependency rule references a source layer name that is not declared.', 'Fix the rule’s from field to a declared layer name.', { oftenAdvisory: true }),
+    entry('CONFIG_RULE_UNKNOWN_TO_LAYER', 'config', 'Rule unknown to layer', 'A dependency rule references a target layer name that is not declared.', 'Fix the rule’s to field to a declared layer name.', { oftenAdvisory: true }),
+    entry('CONFIG_AMBIGUOUS_LAYERS', 'config', 'Ambiguous layer classification', 'Some files match multiple layers at equal specificity; classification falls back to declaration order.', 'Disambiguate overlapping patterns so each file has one clear layer owner.', { oftenAdvisory: true }),
+    entry('CONFIG_UNCLASSIFIED_FILES', 'config', 'Unclassified included files', 'Included source files match no layer pattern; import rules will not enforce on them.', 'Extend layer patterns or narrow include so every governed file is classified.', { oftenAdvisory: true }),
+    // ── meta ─────────────────────────────────────────────────────────────────
+    entry('ARK_UNKNOWN', 'meta', 'Unknown diagnostic', 'A diagnostic lacked a stable ruleId/code; adapters may emit this fallback so agents never see an empty id.', 'Resolve the underlying finding without weakening ark.config.json, then run Ark again. Prefer fixing the producer to emit a catalogued ruleId.'),
+]);
+const BY_ID = new Map(DIAGNOSTIC_CATALOG.map((item) => [item.ruleId, item]));
+/** All public ruleIds in catalog order. */
+export const DIAGNOSTIC_RULE_IDS = Object.freeze(DIAGNOSTIC_CATALOG.map((item) => item.ruleId));
+export function isKnownDiagnosticCode(ruleId) {
+    return typeof ruleId === 'string' && ruleId.length > 0 && BY_ID.has(ruleId);
+}
+/**
+ * True when the code is catalogued or is an ArkRule-family id handled by the
+ * ARKRULE_* prefix fallback in remediation (structure sensors may add members later
+ * only via catalog + ROADMAP — prefix alone is not a license for free-form ids).
+ */
+export function isCataloguedOrArkRuleFamily(ruleId) {
+    if (typeof ruleId !== 'string' || ruleId.length === 0)
+        return false;
+    if (BY_ID.has(ruleId))
+        return true;
+    return ruleId.startsWith('ARKRULE_');
+}
+export function getDiagnosticCatalogEntry(ruleId) {
+    if (typeof ruleId !== 'string' || ruleId.length === 0)
+        return undefined;
+    return BY_ID.get(ruleId);
+}
+/** Fragment for docs links, e.g. `#LAYER_IMPORT_VIOLATION`. */
+export function diagnosticDocsFragment(ruleId) {
+    const entryOrId = getDiagnosticCatalogEntry(ruleId)?.docsAnchor ?? ruleId;
+    return `#${entryOrId}`;
+}
+/**
+ * Repo-relative docs path with fragment (for agents and JSON).
+ * Package consumers resolve against the installed package root or GitHub tree.
+ */
+export function diagnosticDocsPath(ruleId) {
+    return `${DIAGNOSTIC_DOCS_RELATIVE_PATH}${diagnosticDocsFragment(ruleId)}`;
+}
+/** Catalog snapshot for JSON export / agent projection (stable field order). */
+export function serializeDiagnosticCatalog() {
+    return {
+        schemaVersion: DIAGNOSTIC_CATALOG_SCHEMA_VERSION,
+        docsPath: DIAGNOSTIC_DOCS_RELATIVE_PATH,
+        codes: DIAGNOSTIC_CATALOG,
+    };
+}
+/**
+ * Static catalog fix for a ruleId when no live violation context is available.
+ * Live adapters should still use deterministicNextAction for specialized edges.
+ */
+export function catalogFixForRuleId(ruleId) {
+    return getDiagnosticCatalogEntry(ruleId)?.fix;
+}
+/**
+ * Static catalog why for a ruleId (agent “why” surface).
+ */
+export function catalogWhyForRuleId(ruleId) {
+    return getDiagnosticCatalogEntry(ruleId)?.why;
+}

package/bin/lib/doctor-plan.mjs

@@ -62,6 +62,10 @@ import { computeDoctorAdvisories, printDoctorAdvisories } from './doctor-advisor
 import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement, normalizeAnalysisCompleteness } from './analysis-completeness.mjs';
 import { designDeltaDoctorLines } from './design-delta.mjs';
 import { enforcementDoctorLines } from './enforcement-state.mjs';
+import {
+  buildDoctorImprovementCompass,
+  printImprovementCompassSection,
+} from './improvement-compass-doctor.mjs';
 
 const color = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
@@ -640,6 +644,23 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         packageVersionTruth?.code === 'PACKAGE_PIN_SELF_HOST',
     });
 
+  // Improvement compass: projection only — never feeds ok/valid/goal.met.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion: doctorAdvisories.physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists,
+    baselineStale: analysisComplete ? staleBaseline : null,
+    frozenResidual: baseline.exists ? baseline.keys.size : null,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: cov.suggestions?.length ?? 0,
+    emptyLayerCount: cov.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
+
   if (asJson) {
     (options.writeJson ?? console.log)(
       JSON.stringify(
@@ -654,6 +675,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
             // Path-correct ENFORCE can still be design-weak (P02).
             designFitness,
             designSmells,
+            // Improvement compass (lenses; notAScore; never a gate input).
+            improvementCompass,
             ...(options.designDelta ? { designDelta: options.designDelta } : {}),
             // Q01: primary next action when Shape residual dominates (null if not design-weak).
             postGreenPath,
@@ -846,6 +869,8 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     }
   }
 
+  printImprovementCompassSection(improvementCompass, { line, warn, ok, color });
+
   console.log('');
   console.log(color.bold('Design fitness'));
   if (designSmells.length === 0) {

package/bin/lib/html-report-advisories.mjs

@@ -10,6 +10,7 @@
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
 import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
+import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -247,10 +248,42 @@ function rulesUnderContractHtml(section) {
   return formatRulesUnderContractHtml(section, esc);
 }
 
+/** Improvement compass — advisory lenses only; never a score bar or gate input. */
+function improvementCompassHtml(compass) {
+  if (!compass || compass.notAScore !== true || !Array.isArray(compass.lenses)) return '';
+  const residual = Array.isArray(compass.topResidual) ? compass.topResidual : [];
+  const residualLine =
+    residual.length === 0
+      ? '<p class="muted">Residual: none on instrumented lenses (not a score — green edges ≠ finished design).</p>'
+      : `<p><span class="tag warn">residual</span> ${residual
+          .map((id) => {
+            const lens = compass.lenses.find((l) => l.id === id);
+            return `<code>${esc(id)}</code>${lens?.summary ? ` — ${esc(lens.summary)}` : ''}`;
+          })
+          .join('<br/>')}</p>`;
+  const oos = compass.lenses
+    .filter((l) => l && l.status === 'out-of-scope')
+    .map((l) => `<code>${esc(l.id)}</code>`)
+    .join(' · ');
+  // Same primary next as doctor human: severity-ordered topResidual, not lens-id order.
+  const next = primaryImprovementCompassNextAction(compass);
+  const nextLine = next
+    ? `<p class="muted">Next: <code>${esc(next.ref)}</code> — ${esc(next.summary)}</p>`
+    : '';
+  return `
+  <section class="section card" data-advisory="improvementCompass">
+    <h2>Improvement compass <span class="muted">(not a score — projection only; never changes the verdict)</span></h2>
+    ${residualLine}
+    <p class="muted">Out of scope (honest): ${oos || 'scalability · resilience · security'}</p>
+    ${nextLine}
+  </section>`;
+}
+
 export function renderAdvisorySections(advisories, escape) {
   if (!advisories || typeof advisories !== 'object') return '';
   if (typeof escape === 'function') esc = escape;
   return [
+    improvementCompassHtml(advisories.improvementCompass),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

package/bin/lib/html-report-depth.mjs

@@ -21,6 +21,8 @@ import {
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { readBaseline, baselineOccurrenceKeys } from './violations.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
+import { computePhysicalCohesion } from './physical-cohesion.mjs';
 
 function esc(value) {
   return String(value)
@@ -43,6 +45,7 @@ function esc(value) {
  *   frozenKeys?: number,
  *   activeCount?: number,
  *   activeBlockingCount?: number,
+ *   baselineStale?: number | null,
  * }} [baselineSplit] same numbers doctor uses (do not recompute from active-only list)
  */
 export function buildReportDepthPayload(
@@ -155,6 +158,26 @@ export function buildReportDepthPayload(
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
   });
+  // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  const baselineStale =
+    typeof baselineSplit.baselineStale === 'number' ? baselineSplit.baselineStale : null;
+  // Improvement compass — same projection as doctor; notAScore; never a gate input.
+  const improvementCompass = buildDoctorImprovementCompass({
+    designSmells,
+    violations: activeViolations,
+    designWeak: designFitness.designWeak === true,
+    physicalCohesion,
+    rulesUnderContract,
+    baselineExists: baseline.exists || frozenKeys > 0,
+    baselineStale,
+    frozenResidual: frozenKeys,
+    dirtyBaselineRisk: productHonesty?.reasonIds?.includes?.('dirty-baseline') === true,
+    ungovernedDirCount: coverage?.suggestions?.length ?? 0,
+    emptyLayerCount: coverage?.emptyLayers?.length ?? 0,
+    goldenPatternPresent: goldenPattern.present === true,
+    arkRulesLoaded: rulesUnderContract?.active === true,
+  });
   return {
     adoption,
     designDepth: {
@@ -166,6 +189,7 @@ export function buildReportDepthPayload(
       // P0-B / P1-M — folded into designDepth so --report stays a single payload.
       productHonesty,
       mergePlanes: rulesUnderContract?.mergePlanes ?? null,
+      improvementCompass,
     },
   };
 }

package/bin/lib/improvement-compass-doctor.mjs

@@ -0,0 +1,106 @@
+/**
+ * Doctor adapter for the Domain improvement compass (notAScore projection).
+ * Keeps doctor-plan.mjs inside its module budget; pure assembly only.
+ */
+import {
+  buildImprovementCompass,
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+} from './improvement-compass.mjs';
+
+/**
+ * @param {{
+ *   designSmells?: object[],
+ *   violations?: object[],
+ *   designWeak?: boolean,
+ *   physicalCohesion?: { findings?: object[] } | null,
+ *   rulesUnderContract?: object | null,
+ *   baselineExists?: boolean,
+ *   baselineStale?: number | null,
+ *   frozenResidual?: number | null,
+ *   dirtyBaselineRisk?: boolean,
+ *   ungovernedDirCount?: number,
+ *   emptyLayerCount?: number,
+ *   goldenPatternPresent?: boolean,
+ *   arkRulesLoaded?: boolean,
+ * }} input
+ */
+export function buildDoctorImprovementCompass(input = {}) {
+  const violations = Array.isArray(input.violations) ? input.violations : [];
+  const ruleId = (v) => String(v?.ruleId ?? v?.code ?? '');
+
+  let cycleCount = 0;
+  let peerIsolationCount = 0;
+  let pureOrCapabilityResidual = 0;
+  let forbiddenGlobalResidual = 0;
+  let arkRulesStructureResidual = 0;
+
+  for (const v of violations) {
+    const id = ruleId(v).toUpperCase();
+    if (!id) continue;
+    if (id.includes('CYCLE') || id === 'CIRCULAR_DEPENDENCY') cycleCount += 1;
+    if (id.includes('PEER_ISOLATION')) peerIsolationCount += 1;
+    if (id === 'CAPABILITY_VIOLATION') pureOrCapabilityResidual += 1;
+    if (id === 'FORBIDDEN_GLOBAL' || id.startsWith('FORBIDDEN_')) forbiddenGlobalResidual += 1;
+    if (id.startsWith('ARKRULE_') || id === 'INVARIANT_UNCOVERED') arkRulesStructureResidual += 1;
+  }
+
+  const pcFindings = input.physicalCohesion?.findings;
+  const physicalCohesionFindingCount = Array.isArray(pcFindings) ? pcFindings.length : 0;
+
+  const arkRulesLoaded =
+    input.arkRulesLoaded === true ||
+    input.rulesUnderContract?.active === true ||
+    (typeof input.rulesUnderContract?.structureRules === 'number' &&
+      input.rulesUnderContract.structureRules > 0);
+
+  return buildImprovementCompass({
+    designSmells: Array.isArray(input.designSmells) ? input.designSmells : [],
+    violations: violations.map((v) => ({
+      ruleId: ruleId(v) || undefined,
+      message: typeof v?.message === 'string' ? v.message : undefined,
+      file: typeof v?.file === 'string' ? v.file : typeof v?.path === 'string' ? v.path : undefined,
+      fromLayer: v?.fromLayer,
+      toLayer: v?.toLayer,
+      failsStrict: v?.failsStrict,
+      typeOnly: v?.typeOnly === true || v?.namedBindingsTypeOnly === true || undefined,
+    })),
+    cycleCount,
+    peerIsolationCount,
+    physicalCohesionFindingCount,
+    arkRulesLoaded,
+    arkRulesStructureResidual,
+    designWeak: input.designWeak === true,
+    baselineExists: input.baselineExists === true,
+    baselineStale: input.baselineStale ?? null,
+    frozenResidual: input.frozenResidual ?? null,
+    dirtyBaselineRisk: input.dirtyBaselineRisk === true,
+    pureOrCapabilityResidual,
+    forbiddenGlobalResidual,
+    ungovernedDirCount: Number(input.ungovernedDirCount) || 0,
+    emptyLayerCount: Number(input.emptyLayerCount) || 0,
+    goldenPatternPresent: input.goldenPatternPresent === true,
+    // Doctor path is TypeScript-oriented (ArkGate product surface).
+    stackKind: 'typescript',
+  });
+}
+
+export {
+  formatImprovementCompassDoctorLines,
+  primaryImprovementCompassNextAction,
+};
+
+/**
+ * Human doctor section (never a score bar).
+ * @param {import('./improvement-compass.mjs').ImprovementCompass} compass
+ * @param {{ line: Function, warn: string, ok: string, color: { bold: Function } }} io
+ */
+export function printImprovementCompassSection(compass, io) {
+  const { line, warn, ok, color } = io;
+  console.log('');
+  console.log(color.bold('Improvement compass (not a score)'));
+  const mark = compass.topResidual.length > 0 ? warn : ok;
+  for (const text of formatImprovementCompassDoctorLines(compass)) {
+    line(mark, text);
+  }
+}