arkgate 4.8.10 → 4.8.11

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here or
 in the immutable pre-2.0 archive linked below.
 
+## 4.8.11 — 2026-09-02
+
+**Patch** over **4.8.10**. Nested `--config` with `--root` stays inside that
+tree. Library Shape splits `adapterContract` and `agentProjection` so the AI
+edits one concern at a time. **Write. Check. Ship.** **No required config migration.**
+No `schemaVersion` bump. Does not close `K01` / `Z09`. No new skill names.
+
+**Status: prepared** (tree candidate; npm `latest` remains **4.8.10** until the
+signed-tag provenance workflow succeeds).
+
+### Fixed
+- Nested `--config` is a file path: `ark-check --root examples/app --config
+  examples/app/ark.config.json` no longer treats the nested config as a
+  walk-up filename and no longer scans the invoker `cwd` (`include` is relative
+  to `--root`). Basename walk-up still applies when `--config` is
+  `ark.config.json`.
+- `doctorResidentWarm` CI budget ceiling is 680ms (~12% headroom after the
+  adapterContract split). Still far below one-shot doctor.
+
+### Changed
+- Domain Shape: `adapterContract` types/schema and finding-ref helpers are
+  their own modules; the public facade stays under the god-module floors.
+  Callers still import `src/domain/adapterContract.ts`. CLI pure helpers follow
+  the DF03 split.
+- Domain Shape: `agentProjection` types/markers, body/meta formatters, and
+  merge/stamp are their own modules; the public facade re-exports. Callers still
+  import `src/domain/agentProjection.ts`. Generated CLI children stay in
+  DomainModel so the facade does not import Tooling.
+- Dev-tree pins: `browserslist` 4.28.8 (GHSA-73wf-gq98-2v4g) and `fast-uri`
+  3.1.7 (GHSA-5jgf-p345-68v8 and siblings). These are lock/override pins, not a
+  consumer API change.
+
 ## 4.8.10 — 2026-09-02
 
 **Patch** over **4.8.9**. Amarilla first-aggregate sensors. Incomplete analysis
@@ -10,8 +42,7 @@ never looks green: an enforced sensor that cannot see its scope is not a pass.
 **Write. Check. Ship.** **No required config migration.** No `schemaVersion` bump.
 Does not close `K01` / `Z09`. No new skill names.
 
-**Status: prepared** (tree candidate; npm `latest` remains **4.8.9** until the
-signed-tag provenance workflow succeeds).
+**Status: published** (on npm `latest`; see `docs/releases/4.8.10.md`).
 
 ### Added
 - `arkgate report` / `ark report` on the existing dual bins: draft an upstream GitHub issue for

package/README.md

@@ -37,7 +37,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.10** is prepared on this tree; npm `latest` remains **4.8.9**.
+> **ArkGate 4.8.11** is prepared on this tree; npm `latest` remains **4.8.10**.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
@@ -45,7 +45,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD;
 > later pattern change is `proposeRelease` then `apply`.
 > `@arkgate/runtime` is deprecated.
-> [4.8.10 prepared](docs/releases/4.8.10.md) · [4.8.9 published](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.11 prepared](docs/releases/4.8.11.md) · [4.8.10 published](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -342,8 +342,9 @@ Rename the three keys. Compact starters leave it off. Details:
 | 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) |
-| Prepared (4.8.10; not published) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.9 on npm `latest`) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.11; not published) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.10 on npm `latest`) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |
 | Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |

package/bin/ark-check-runtime.mjs

@@ -1066,6 +1066,12 @@ function applyConfigRootWalkUp(args) {
   args.configRoot = effective.configRoot;
   args.configFound = effective.configFound;
   args.writeRoot = effective.writeRoot;
+  // Nested relative --config (`examples/app/ark.config.json`) must stay a resolved
+  // file path under --root. Leaving the relative string makes readConfig join it
+  // again and miss; walk-up used to latch the parent instead.
+  if (effective.configFound && typeof effective.configPath === 'string') {
+    args.config = effective.configPath;
+  }
   if (effective.walkedUp && effective.root !== path.resolve(args.root)) {
     // Read paths (or write + --follow-config-root): adopt discovered config root.
     args.root = effective.root;

package/bin/ark-check.mjs

@@ -41,6 +41,9 @@ function residentArgs(argv) {
   // Same monorepo walk-up as full runtime (NEW-MONOREPO-CWD-WALKUP).
   const effective = resolveEffectiveProjectRoot(args.root, { configName: args.config });
   args.configRoot = effective.configRoot;
+  if (effective.configFound && typeof effective.configPath === 'string') {
+    args.config = effective.configPath;
+  }
   if (effective.walkedUp) {
     args.root = effective.root;
     args.configWalkedUp = true;

package/bin/lib/adapter-contract-types.mjs

@@ -0,0 +1,137 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/adapterContractTypes.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/adapter-contract-types.mjs). Zero Node I/O.
+ */
+
+/**
+ * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
+ * `findingRef`, `targetKey` (baseline-compatible), `docsCodePath`.
+ * 1.4 added optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03).
+ */
+export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.5';
+/** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
+export const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH = 'docs/diagnostics.md';
+export const ARK_ANALYSIS_RESULT_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json',
+    title: 'ArkGate analysis result',
+    type: 'object',
+    additionalProperties: false,
+    required: [
+        'schemaVersion',
+        'mode',
+        'valid',
+        'completeness',
+        'completenessReasons',
+        'diagnostics',
+    ],
+    allOf: [
+        {
+            if: {
+                properties: { completeness: { enum: ['partial', 'unavailable'] } },
+                required: ['completeness'],
+            },
+            then: { properties: { valid: { const: false } } },
+        },
+        {
+            if: {
+                properties: {
+                    mode: { const: 'resolved-candidate-facts' },
+                    completeness: { enum: ['complete', 'partial'] },
+                },
+                required: ['mode', 'completeness'],
+            },
+            then: {
+                required: ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash'],
+            },
+        },
+        {
+            if: {
+                properties: { completeness: { const: 'complete' } },
+                required: ['completeness'],
+            },
+            then: { properties: { completenessReasons: { maxItems: 0 } } },
+            else: { properties: { completenessReasons: { minItems: 1 } } },
+        },
+    ],
+    properties: {
+        schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
+        mode: { enum: ['lexical-compatibility', 'resolved-candidate-facts'] },
+        valid: { type: 'boolean' },
+        completeness: { enum: ['complete', 'partial', 'unavailable'] },
+        completenessReasons: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['code', 'message'],
+                properties: {
+                    code: { type: 'string', minLength: 1 },
+                    message: { type: 'string', minLength: 1 },
+                    file: { type: 'string', minLength: 1 },
+                },
+            },
+        },
+        policyHash: { type: 'string', minLength: 1 },
+        resolverIdentity: { type: 'string', minLength: 1 },
+        factsHash: { type: 'string', minLength: 1 },
+        candidateTreeHash: { type: 'string', minLength: 1 },
+        diagnostics: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['ruleId', 'severity', 'message', 'location', 'evidence'],
+                properties: {
+                    ruleId: { type: 'string', minLength: 1 },
+                    severity: { enum: ['error', 'warning'] },
+                    message: { type: 'string', minLength: 1 },
+                    location: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['file', 'line', 'column'],
+                        properties: {
+                            file: { type: 'string', minLength: 1 },
+                            line: { type: 'integer', minimum: 1 },
+                            column: { type: 'integer', minimum: 1 },
+                        },
+                    },
+                    evidence: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            target: { type: 'string' },
+                            fromLayer: { type: 'string' },
+                            toLayer: { type: 'string' },
+                            typeOnly: { type: 'boolean' },
+                            targetTypeOnlyExports: { type: 'boolean' },
+                            sourcePureTypeModule: { type: 'boolean' },
+                            namedBindingsTypeOnly: { type: 'boolean' },
+                            portProofEligible: { type: 'boolean' },
+                            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 },
+                    /** ACS06 — compact multi-turn id; always derived from targetKey when emitted. */
+                    findingRef: { type: 'string', minLength: 1, pattern: '^fnv1a-[0-9a-f]{8}$' },
+                    /**
+                     * ACS06 — baseline-compatible freeze identity
+                     * (`ruleId|file|from|to|target` with optional `#N` occurrence suffix).
+                     */
+                    targetKey: { type: 'string', minLength: 1 },
+                    /** ACS06 — package-relative diagnostics anchor path. */
+                    docsCodePath: { type: 'string', minLength: 1 },
+                },
+            },
+        },
+    },
+};

package/bin/lib/adapter-contract.mjs

@@ -9,73 +9,16 @@
  */
 
 import { deterministicNextAction } from './remediation.mjs';
-/** Versioned public result contract shared by every ArkGate enforcement adapter. */
-/**
- * 1.5 adds stable finding refs on every factory-emitted diagnostic (ACS06):
- * `findingRef`, `targetKey` (baseline-compatible), `docsCodePath`.
- * 1.4 added optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03).
- */
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.5';
-/** Repo-relative diagnostics docs path (parity with ACS02 diagnostic catalog). */
-export const ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH = 'docs/diagnostics.md';
+import { ARK_ANALYSIS_RESULT_SCHEMA_VERSION, } from './adapter-contract-types.mjs';
+import { adapterDocsCodePath, adapterFindingOccurrenceTargetKeys, adapterFindingRefFromTargetKey, adapterFindingTargetKey, } from './adapter-finding-refs.mjs';
+export { ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH, ARK_ANALYSIS_RESULT_SCHEMA, ARK_ANALYSIS_RESULT_SCHEMA_VERSION, } from './adapter-contract-types.mjs';
+export { adapterDocsCodePath, adapterFindingOccurrenceTargetKeys, adapterFindingRefFromTargetKey, adapterFindingTargetKey, } from './adapter-finding-refs.mjs';
 function text(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 function positiveInteger(value, fallback) {
     return Number.isInteger(value) && Number(value) > 0 ? Number(value) : fallback;
 }
-/**
- * Baseline-compatible target key for a violation input.
- * Field order and empty-string fallbacks **must** match `baselineKey` in
- * `baselineKey.ts` — parity tests guard this so finding refs never orphan freezes.
- *
- * Note: uses raw ruleId/file strings (including empty) the same way baseline does;
- * display `ruleId` / `location.file` may still normalize to ARK_UNKNOWN / `<unknown>`.
- */
-export function adapterFindingTargetKey(violation) {
-    const ruleId = typeof violation.ruleId === 'string'
-        ? violation.ruleId
-        : typeof violation.code === 'string'
-            ? violation.code
-            : undefined;
-    const file = typeof violation.file === 'string' ? violation.file : undefined;
-    const fromLayer = typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined;
-    const toLayer = typeof violation.toLayer === 'string' ? violation.toLayer : undefined;
-    const target = typeof violation.target === 'string' ? violation.target : undefined;
-    return [
-        ruleId,
-        file,
-        fromLayer ?? '',
-        toLayer ?? '',
-        target ?? '',
-    ].join('|');
-}
-/**
- * Occurrence-aware target keys for a violation list (parity with baselineOccurrenceKeys).
- * First occurrence keeps the historical base key; duplicates get `#N`.
- */
-export function adapterFindingOccurrenceTargetKeys(violations) {
-    const counts = new Map();
-    return violations.map((violation) => {
-        const base = adapterFindingTargetKey(violation);
-        const occurrence = (counts.get(base) ?? 0) + 1;
-        counts.set(base, occurrence);
-        return occurrence === 1 ? base : `${base}#${occurrence}`;
-    });
-}
-/** FNV-1a finding ref from a baseline-compatible targetKey (not a security hash). */
-export function adapterFindingRefFromTargetKey(targetKey) {
-    let hash = 0x811c9dc5;
-    for (let index = 0; index < targetKey.length; index += 1) {
-        hash ^= targetKey.charCodeAt(index);
-        hash = Math.imul(hash, 0x01000193);
-    }
-    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
-}
-/** Package-relative docs path with fragment for a public ruleId. */
-export function adapterDocsCodePath(ruleId) {
-    return `${ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH}#${ruleId}`;
-}
 function nextActionForDiagnostic(ruleId, evidence, violation) {
     return deterministicNextAction({
         ruleId,
@@ -240,122 +183,3 @@ export function createAdapterResult(input) {
     }
     return { ...base, mode, valid: false, completeness, ...evidence };
 }
-export const ARK_ANALYSIS_RESULT_SCHEMA = {
-    $schema: 'https://json-schema.org/draft/2020-12/schema',
-    $id: 'https://unpkg.com/arkgate@3/schemas/ark.analysis-result.schema.json',
-    title: 'ArkGate analysis result',
-    type: 'object',
-    additionalProperties: false,
-    required: [
-        'schemaVersion',
-        'mode',
-        'valid',
-        'completeness',
-        'completenessReasons',
-        'diagnostics',
-    ],
-    allOf: [
-        {
-            if: {
-                properties: { completeness: { enum: ['partial', 'unavailable'] } },
-                required: ['completeness'],
-            },
-            then: { properties: { valid: { const: false } } },
-        },
-        {
-            if: {
-                properties: {
-                    mode: { const: 'resolved-candidate-facts' },
-                    completeness: { enum: ['complete', 'partial'] },
-                },
-                required: ['mode', 'completeness'],
-            },
-            then: {
-                required: ['policyHash', 'resolverIdentity', 'factsHash', 'candidateTreeHash'],
-            },
-        },
-        {
-            if: {
-                properties: { completeness: { const: 'complete' } },
-                required: ['completeness'],
-            },
-            then: { properties: { completenessReasons: { maxItems: 0 } } },
-            else: { properties: { completenessReasons: { minItems: 1 } } },
-        },
-    ],
-    properties: {
-        schemaVersion: { const: ARK_ANALYSIS_RESULT_SCHEMA_VERSION },
-        mode: { enum: ['lexical-compatibility', 'resolved-candidate-facts'] },
-        valid: { type: 'boolean' },
-        completeness: { enum: ['complete', 'partial', 'unavailable'] },
-        completenessReasons: {
-            type: 'array',
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['code', 'message'],
-                properties: {
-                    code: { type: 'string', minLength: 1 },
-                    message: { type: 'string', minLength: 1 },
-                    file: { type: 'string', minLength: 1 },
-                },
-            },
-        },
-        policyHash: { type: 'string', minLength: 1 },
-        resolverIdentity: { type: 'string', minLength: 1 },
-        factsHash: { type: 'string', minLength: 1 },
-        candidateTreeHash: { type: 'string', minLength: 1 },
-        diagnostics: {
-            type: 'array',
-            items: {
-                type: 'object',
-                additionalProperties: false,
-                required: ['ruleId', 'severity', 'message', 'location', 'evidence'],
-                properties: {
-                    ruleId: { type: 'string', minLength: 1 },
-                    severity: { enum: ['error', 'warning'] },
-                    message: { type: 'string', minLength: 1 },
-                    location: {
-                        type: 'object',
-                        additionalProperties: false,
-                        required: ['file', 'line', 'column'],
-                        properties: {
-                            file: { type: 'string', minLength: 1 },
-                            line: { type: 'integer', minimum: 1 },
-                            column: { type: 'integer', minimum: 1 },
-                        },
-                    },
-                    evidence: {
-                        type: 'object',
-                        additionalProperties: false,
-                        properties: {
-                            target: { type: 'string' },
-                            fromLayer: { type: 'string' },
-                            toLayer: { type: 'string' },
-                            typeOnly: { type: 'boolean' },
-                            targetTypeOnlyExports: { type: 'boolean' },
-                            sourcePureTypeModule: { type: 'boolean' },
-                            namedBindingsTypeOnly: { type: 'boolean' },
-                            portProofEligible: { type: 'boolean' },
-                            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 },
-                    /** ACS06 — compact multi-turn id; always derived from targetKey when emitted. */
-                    findingRef: { type: 'string', minLength: 1, pattern: '^fnv1a-[0-9a-f]{8}$' },
-                    /**
-                     * ACS06 — baseline-compatible freeze identity
-                     * (`ruleId|file|from|to|target` with optional `#N` occurrence suffix).
-                     */
-                    targetKey: { type: 'string', minLength: 1 },
-                    /** ACS06 — package-relative diagnostics anchor path. */
-                    docsCodePath: { type: 'string', minLength: 1 },
-                },
-            },
-        },
-    },
-};

package/bin/lib/adapter-finding-refs.mjs

@@ -0,0 +1,63 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/adapterFindingRefs.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/adapter-finding-refs.mjs). Zero Node I/O.
+ */
+
+import { ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH, } from './adapter-contract-types.mjs';
+/**
+ * Baseline-compatible target key for a violation input.
+ * Field order and empty-string fallbacks **must** match `baselineKey` in
+ * `baselineKey.ts` — parity tests guard this so finding refs never orphan freezes.
+ *
+ * Note: uses raw ruleId/file strings (including empty) the same way baseline does;
+ * display `ruleId` / `location.file` may still normalize to ARK_UNKNOWN / `<unknown>`.
+ */
+export function adapterFindingTargetKey(violation) {
+    const ruleId = typeof violation.ruleId === 'string'
+        ? violation.ruleId
+        : typeof violation.code === 'string'
+            ? violation.code
+            : undefined;
+    const file = typeof violation.file === 'string' ? violation.file : undefined;
+    const fromLayer = typeof violation.fromLayer === 'string' ? violation.fromLayer : undefined;
+    const toLayer = typeof violation.toLayer === 'string' ? violation.toLayer : undefined;
+    const target = typeof violation.target === 'string' ? violation.target : undefined;
+    return [
+        ruleId,
+        file,
+        fromLayer ?? '',
+        toLayer ?? '',
+        target ?? '',
+    ].join('|');
+}
+/**
+ * Occurrence-aware target keys for a violation list (parity with baselineOccurrenceKeys).
+ * First occurrence keeps the historical base key; duplicates get `#N`.
+ */
+export function adapterFindingOccurrenceTargetKeys(violations) {
+    const counts = new Map();
+    return violations.map((violation) => {
+        const base = adapterFindingTargetKey(violation);
+        const occurrence = (counts.get(base) ?? 0) + 1;
+        counts.set(base, occurrence);
+        return occurrence === 1 ? base : `${base}#${occurrence}`;
+    });
+}
+/** FNV-1a finding ref from a baseline-compatible targetKey (not a security hash). */
+export function adapterFindingRefFromTargetKey(targetKey) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < targetKey.length; index += 1) {
+        hash ^= targetKey.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+/** Package-relative docs path with fragment for a public ruleId. */
+export function adapterDocsCodePath(ruleId) {
+    return `${ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH}#${ruleId}`;
+}

package/bin/lib/agent-projection-formatters.mjs

@@ -0,0 +1,151 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/agentProjectionFormatters.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/agent-projection-formatters.mjs). Zero Node I/O.
+ */
+
+import { AGENT_PROJECTION_END_MARKER, AGENT_PROJECTION_ENFORCEMENT_SURFACES, AGENT_PROJECTION_NON_ENFORCEMENT_LABEL, ARK_AGENT_PROJECTION_SCHEMA_VERSION, } from './agent-projection-types.mjs';
+/** FNV-1a identity — portable, no Node crypto (same family as stableHash). */
+export function agentProjectionContentIdentity(body) {
+    const normalized = String(body ?? '').replace(/\r\n/g, '\n');
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < normalized.length; index += 1) {
+        hash ^= normalized.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `fnv1a-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}
+export function normalizeNewlines(text) {
+    return String(text ?? '').replace(/\r\n/g, '\n');
+}
+export function ensureTrailingNewline(text) {
+    const normalized = normalizeNewlines(text);
+    return normalized.endsWith('\n') ? normalized : `${normalized}\n`;
+}
+export function safeVersion(version) {
+    if (typeof version !== 'string' || version.trim().length === 0)
+        return 'unknown';
+    // Avoid breaking HTML comments / markdown with control chars.
+    return version.trim().replace(/[>\s]/g, '');
+}
+function resolveProfile(profile) {
+    return profile === 'compact' ? 'compact' : 'full';
+}
+/**
+ * Build the managed begin marker line (includes version + nonAuthoritative stamp).
+ */
+export function buildAgentProjectionBeginMarker(facts) {
+    const version = safeVersion(facts.arkgateVersion);
+    const schema = typeof facts.schemaVersion === 'string' && facts.schemaVersion.trim()
+        ? facts.schemaVersion.trim()
+        : ARK_AGENT_PROJECTION_SCHEMA_VERSION;
+    return `<!-- arkgate:agent-projection:begin schema=${schema} arkgateVersion=${version} nonAuthoritative=true -->`;
+}
+/**
+ * Layer placement rows for the projection (compact markdown table).
+ */
+export function formatAgentProjectionLayers(layers) {
+    if (!Array.isArray(layers) || layers.length === 0) {
+        return '_No project layers loaded — read `ark.config.json` or run `ark start` / `ark_manifest`._';
+    }
+    const rows = layers
+        .map((layer) => {
+        const name = layer.name?.trim() || 'Unknown';
+        const patternList = layer.patterns ?? [];
+        const prefixList = layer.intentPrefixes ?? [];
+        const patterns = patternList.map((pattern) => `\`${pattern}\``).join(', ') || '—';
+        const prefixes = prefixList.map((prefix) => `\`${prefix}\``).join(', ') || '—';
+        return `| ${name} | ${patterns} | ${prefixes} |`;
+    })
+        .join('\n');
+    return `| Layer | Patterns | Intent prefixes |
+|-------|----------|-----------------|
+${rows}`;
+}
+/**
+ * Catalog short-list bullets (ruleId + title). Empty list → pointer only.
+ */
+export function formatAgentProjectionCatalogShortList(entries, docsPath) {
+    const path = docsPath.trim() || 'docs/diagnostics.md';
+    if (!Array.isArray(entries) || entries.length === 0) {
+        return `Full public codes: \`${path}\` (and package \`DIAGNOSTIC_CATALOG\`).`;
+    }
+    const lines = entries
+        .filter((entry) => entry && typeof entry.ruleId === 'string' && entry.ruleId.length > 0)
+        .map((entry) => {
+        const title = typeof entry.title === 'string' && entry.title.trim() ? entry.title.trim() : entry.ruleId;
+        return `- \`${entry.ruleId}\` — ${title}`;
+    });
+    return `${lines.join('\n')}
+
+Full catalog: \`${path}\` (\`#RULE_ID\` anchors).`;
+}
+/**
+ * Projection **body** only (no begin/end markers). Used for content-identity.
+ */
+export function buildAgentProjectionBody(facts) {
+    const version = safeVersion(facts.arkgateVersion);
+    const profile = resolveProfile(facts.profile);
+    const checkCommand = typeof facts.checkCommand === 'string' && facts.checkCommand.trim()
+        ? facts.checkCommand.trim()
+        : 'ark-check --strict-config';
+    const docsPath = typeof facts.diagnosticsDocsPath === 'string' && facts.diagnosticsDocsPath.trim()
+        ? facts.diagnosticsDocsPath.trim()
+        : 'docs/diagnostics.md';
+    const hostRaw = typeof facts.host === 'string' ? facts.host.trim().toLowerCase() : '';
+    const host = hostRaw && hostRaw !== 'unknown' ? hostRaw : null;
+    const layers = Array.isArray(facts.layers) ? facts.layers : [];
+    const catalog = Array.isArray(facts.catalogShortList) ? facts.catalogShortList : [];
+    const lines = [
+        '## ArkGate agent contract projection',
+        '',
+        AGENT_PROJECTION_NON_ENFORCEMENT_LABEL,
+        '',
+        `- **arkgateVersion:** \`${version}\` (must match the installed package; regenerate with \`ark agents-md --write\` after upgrade)`,
+        `- **projectionSchema:** \`${ARK_AGENT_PROJECTION_SCHEMA_VERSION}\``,
+        `- **profile:** \`${profile}\`${host ? ` · **host:** \`${host}\`` : ''}`,
+        `- **after edits:** \`${checkCommand}\``,
+        '',
+    ];
+    if (profile === 'compact') {
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — what is wrong and what to do first. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read the rules file with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix the import, do not weaken the rules file.', '6. Single door: illegal imports → fix; leftover design work → map then one small refactor with user OK.', '', '### Layers (summary)', '', formatAgentProjectionLayers(layers), '');
+    }
+    else {
+        lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: local `ark.config.json` / CLI, or `ark_manifest` after a matched `ark_identity` handshake. Identity is optional when CLI already resolved the root.', '- Host docs: the same projection schema is merged into `AGENTS.md` and `CLAUDE.md` (`ark agents-md --write`).', '');
+    }
+    lines.push('### Enforcement surfaces (authoritative)', '', AGENT_PROJECTION_ENFORCEMENT_SURFACES.map((surface) => `- \`${surface}\``).join('\n'), '');
+    return lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+}
+/**
+ * Full managed block: begin marker + body + end marker.
+ */
+export function buildAgentProjectionBlock(facts) {
+    const body = buildAgentProjectionBody(facts);
+    const begin = buildAgentProjectionBeginMarker({
+        arkgateVersion: facts.arkgateVersion,
+        schemaVersion: ARK_AGENT_PROJECTION_SCHEMA_VERSION,
+    });
+    return `${begin}\n${body}${AGENT_PROJECTION_END_MARKER}\n`;
+}
+/**
+ * Machine meta for CLI `--json` / tests (never a gate input).
+ */
+export function buildAgentProjectionMeta(facts) {
+    const body = buildAgentProjectionBody(facts);
+    const layers = Array.isArray(facts.layers) ? facts.layers : [];
+    const catalog = Array.isArray(facts.catalogShortList) ? facts.catalogShortList : [];
+    return {
+        schemaVersion: ARK_AGENT_PROJECTION_SCHEMA_VERSION,
+        arkgateVersion: safeVersion(facts.arkgateVersion),
+        nonAuthoritative: true,
+        enforcementSurfaces: [...AGENT_PROJECTION_ENFORCEMENT_SURFACES],
+        contentIdentity: agentProjectionContentIdentity(body),
+        layerCount: layers.length,
+        catalogCodeCount: catalog.filter((entry) => entry?.ruleId).length,
+        profile: resolveProfile(facts.profile),
+    };
+}