arkgate 4.2.1 → 4.4.0

package/CHANGELOG.md

@@ -5,12 +5,94 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
-## 4.2.1 — 2026-08-08 (prepared)
+## 4.4.0 — 2026-08-09
+
+**Minor** over 4.3.0. Improvement compass (architecture lenses as a `notAScore` projection of
+existing sensors), doctor/HTML residual coaching, deeper skills + compact router for vibe-coder
+and full-AI workflows, and product-only public docs. **No required config migration.** Codex remains
+advisory at write time. Skills and AGENTS projection never enforce. **Status: prepared in tree —
+not published on npm until OIDC publish + `npm view` succeed** (see `docs/releases/4.4.0.md`).
+
+### Added
+
+- **Improvement compass:** doctor human section + `doctor.improvementCompass` JSON — closed set of
+  architecture **lenses** (SoC, DIP, domain alignment, …) with status `ok` / `residual` /
+  `not-instrumented` / `out-of-scope`, evidence refs, optional next action, capped `topResidual`,
+  always **`notAScore: true`**. Projected from existing smells, walls, cohesion, ArkRules, and
+  design-weak signals. Residual lenses never flip `valid`, strict-merge, or `goal.met`.
+  Out-of-scope locked for scalability, app security tooling, and full resilience. Type-only
+  placement debt (`failsStrict: false`) maps to **modularity** residual only (not coupling).
+- **Optional status slice:** thin `improvementCompass.topResidual` on the status manifest schema for
+  Tooling pass-through — **`ark status` does not compute lenses yet**; agents should read doctor.
+- **HTML report:** advisory section `data-advisory="improvementCompass"` (report parity with doctor).
+- **Skills + compact router:** same **13** skill names deepened for vibe-coder outcomes — compass
+  preflight, anti false-done, AI-easy placement cues, out-of-scope honesty, Completion **Compass**
+  bullet. Compact start router surfaces residual lenses and forbids “done” on green edges alone.
+- **Docs:** use / develop / agent-guide describe compass + Align/Stabilize/Shape in product language.
+
+**Freezes held:** no principle scores/ranks; no new skill names; no new ArkRules sensors; no LLM
+verdict; projection never enforces.
+
+## 4.3.0 — 2026-08-09
+
+**Minor** over 4.2.1. Agent contract surface: diagnostic code catalog, unified status snapshot,
+version-matched agent projection, Agent Skills packaging of the existing 13 skills, stable finding
+refs, and maintainer placement A/B eval. **No required config migration.** Codex remains advisory
+at write time. Skills and AGENTS projection never enforce. **Status: published**
+(`arkgate@4.3.0` on npm `latest`).
+
+### Added
+
+- **Diagnostic code catalog (ACS02):** closed public `ruleId` vocabulary with why/fix text and
+  docs anchors (`docs/diagnostics.md#RULE_ID`). Domain source `src/domain/diagnosticCatalog.ts`,
+  generated CLI mirror `bin/lib/diagnostic-catalog.mjs`, root exports (`DIAGNOSTIC_CATALOG`,
+  `getDiagnosticCatalogEntry`, `diagnosticDocsPath`, …). Remediation/parity fixtures forbid
+  unknown production codes. No new rule semantics — cataloguing only.
+- **Unified status manifest (ACS03):** `ark status --json` (+ MCP `ark_status`) returns one
+  session/project snapshot — identity binding, honest write-path activation, last-check summary,
+  ArkRules residual counts, primary next action. Domain `src/domain/statusManifest.ts`, generated
+  pure `bin/lib/status-manifest.mjs`, schema `arkgate/schema/status-manifest`, root exports
+  (`buildStatusManifest`, `ARK_STATUS_MANIFEST_SCHEMA`, …). Never prompts; `CI=1` forces JSON.
+  Optional `--expected-root` / `--expected-project-id` for matched vs stale identity. Not a score.
+- **Version-matched agent projection (ACS04):** `ark agents-md` regenerates a managed
+  AGENTS.md projection block stamped with the installed package version + contract summary
+  (layers, diagnostic short list). Install/upgrade templates (`agentInstructions` /
+  `compactAgentInstructions`) embed the same block. Content-identity merge preserves customized
+  regions outside markers. Explicitly **non-authoritative** — enforcement remains ark-check /
+  hooks / CI; projection is never a gate input. Domain `src/domain/agentProjection.ts`, generated
+  pure `bin/lib/agent-projection.mjs`, root exports (`buildAgentProjectionBlock`,
+  `mergeAgentProjectionDocument`, …). Drift: `ark agents-md --check`.
+- **Agent Skills packaging (ACS05):** the existing **13** `/ark-*` skills ship in an Agent
+  Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat
+  `templates/skills/*.md`). Ecosystem install: `npx skills add ./node_modules/arkgate/templates/agent-skills`
+  (or the GitHub tree). Ark install path unchanged (`--install-agent-gates` / `--skills-only`).
+  Domain `src/domain/agentSkillsPackage.ts` (frozen `ARK_SKILL_NAMES`, frontmatter/layout
+  validation), generated pure `bin/lib/agent-skills-package.mjs`, `npm run generate:agent-skills` /
+  `check:agent-skills`. **No new skill names.** Skills remain non-enforcing.
+- **Stable finding refs (ACS06):** analysis-result schema **`1.5`** — every factory-emitted
+  diagnostic (CLI JSON, MCP, opt-in `ARK_REPAIR_JSON` repair payload) includes `findingRef`
+  (`fnv1a-…`), baseline-compatible `targetKey`, and `docsCodePath`. `targetKey` is exactly the
+  baseline (occurrence) freeze key so multi-turn agent loops never orphan baselined debt.
+  Domain helpers on `adapterContract` / `baselineKey`; multi-turn fixture
+  `tests/fixtures/finding-refs/multi-turn-stability.json`.
+- **Maintainer placement A/B eval (ACS07):** under `eval/placement-ab/`, fixture pairs compare
+  agent placement **with** Ark gates+skills (`ark-place` / `ark-architect` markers) vs
+  **without**. CI-safe dry mode (`npm run eval:placement-ab`) measures real `ark-check` on both
+  arms; results path `eval/placement-ab-report.json` + template
+  `eval/placement-ab/results/RESULTS.template.json`. Live mode optional and never fails when no
+  agent/API key is present. **Not a product score.**
+
+### Docs / claims (ACS08)
+
+- Claims matrix refreshed for 4.3.0 agent-contract statements (**0 Contradicted** on public
+  lanes). Release notes at `docs/releases/4.3.0.md` (**Status: published**). npm `latest` is **4.3.0**.
+
+## 4.2.1 — 2026-08-08 (published)
 
 **Patch** over 4.2.0. Next.js **16.3** field compatibility: root `proxy.ts` (Next 16 network-boundary
 rename of middleware) is scanned and classified; eval fixtures and release-surface pins track
 `next@16.3.0`. **No required config migration.** Codex remains advisory at write time.
-**Status: prepared** (`arkgate@4.2.1` not published yet).
+**Status: published** (`arkgate@4.2.1`; superseded by 4.3.0 on `latest`).
 
 ### Fixed
 
@@ -39,7 +121,7 @@ handshake, and project-bound `ark_manifest`; cross-project/config paths fail bef
 ArkRules analysis; Codex setup distinguishes files configured on disk from a runtime observed
 after restart. **No required config migration.** Legacy MCP calls remain callable but explicitly
 non-authoritative until bound. Codex remains advisory at write time. **Status: published**
-(`arkgate@4.2.0` on npm `latest`).
+(`arkgate@4.2.0`; superseded by 4.2.1 on `latest`).
 
 ### Added
 

package/README.md

@@ -16,9 +16,8 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.2.1** is prepared (Next.js 16.3 root `proxy.ts` scan + fixture pins);
-> **4.2.0** remains on npm `latest` until publication.
-> [4.2.1 candidate](docs/releases/4.2.1.md) · [4.2.0](docs/releases/4.2.0.md) · [4.1.1](docs/releases/4.1.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.3.0** is on npm `latest`. Tree is preparing **4.4.0** (improvement compass) — see [4.4.0 notes](docs/releases/4.4.0.md) (Status: prepared until publish).
+> [4.4.0 notes](docs/releases/4.4.0.md) · [4.3.0](docs/releases/4.3.0.md) · [4.2.1](docs/releases/4.2.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -44,10 +43,13 @@ npx arkgate-check --doctor        # control plane: status light + primary next a
 ```
 
 That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
+Doctor also shows an **improvement compass** (architecture lenses such as separation of concerns and
+dependency inversion — **not a score**). Residual lenses mean Shape work may remain even when edges
+are green. Details: [use.md — Improvement compass](docs/use.md#improvement-compass-not-a-score).
 
 ```text
-start → doctor → day-to-day (place + gate)
-              ↘ optional /ark-autopilot after skill pack
+start → doctor (+ compass) → day-to-day (place + gate)
+                         ↘ optional /ark-autopilot after skill pack
 ```
 
 Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts.
@@ -79,6 +81,15 @@ Details: [configuration](docs/configuration.md#arkrules-intra-layer-opt-in) · [
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
 
+### When not to adopt
+
+ArkGate is overkill for small trees with **no AI agents** and **no multi-layer boundaries**, for
+single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain
+`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. In those
+cases stay with a boundary linter alone (see [Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
+Anyone path: [docs/use.md — When not to adopt](docs/use.md#when-not-to-adopt). Limits of a green
+check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-is--isnt).
+
 ---
 
 ## Status lights (not settings)
@@ -158,14 +169,17 @@ expectation.
 
 ```bash
 npx arkgate start --apply
+npx arkgate status --json          # session/project snapshot (identity, activation, last check)
 npx arkgate-check --doctor
 npx arkgate-check --plan
 npx arkgate-check --coverage
 npx arkgate-check --strict-merge   # CI / required status
 npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
+# optional: same 13 skills via Agent Skills ecosystem (no new names)
+# npx skills add ./node_modules/arkgate/templates/agent-skills
 ```
 
-More: [docs/develop.md](docs/develop.md) · enthusiast track: [docs/enthusiast/](docs/enthusiast/README.md)
+More: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md](docs/agent-guide.md#install-skills-ark-and-ecosystem) · enthusiast track: [docs/enthusiast/](docs/enthusiast/README.md)
 
 ---
 
@@ -194,8 +208,10 @@ 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) |
-| Prepared candidate (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |
+| Current release (4.3.0 on npm `latest`) | [docs/releases/4.3.0.md](docs/releases/4.3.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Next prepare (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) (prepared — not published until npm verify) |
+| Prior (4.2.1) | [docs/releases/4.2.1.md](docs/releases/4.2.1.md) |
+| Previous (4.2.0) | [docs/releases/4.2.0.md](docs/releases/4.2.0.md) |
 | Previous (4.1.1) | [docs/releases/4.1.1.md](docs/releases/4.1.1.md) |
 | Previous (4.1.0) | [docs/releases/4.1.0.md](docs/releases/4.1.0.md) |
 | Previous patch (4.0.1) | [docs/releases/4.0.1.md](docs/releases/4.0.1.md) |

package/bin/ark-check-runtime.mjs

@@ -1576,6 +1576,14 @@ async function main() {
       : readJsonSafe(path.join(reportsDir(root), 'origin.json'));
     // Pass the same baseline split as doctor so productHonesty dirty-freeze matches.
     const reportBaseline = readBaseline(root, args.baseline || '.ark-baseline.json');
+    // Doctor parity for improvement compass: stale keys = baseline keys not in current occurrence set.
+    // Only when analysis is complete — partial scans under-count current keys and inflate false stale residual
+    // (same gate as doctor-plan: baselineStale: analysisComplete ? staleBaseline : null).
+    const reportOccurrenceKeys = baselineOccurrenceKeys(violations);
+    const reportCurrentKeys = new Set(reportOccurrenceKeys);
+    const reportBaselineStale = reportBaseline.exists
+      ? [...reportBaseline.keys].filter((key) => !reportCurrentKeys.has(key)).length
+      : 0;
     const { adoption: adoptionForReport, designDepth } = buildReportDepthPayload(
       root,
       config,
@@ -1588,6 +1596,7 @@ async function main() {
         frozenKeys: reportBaseline.exists ? reportBaseline.keys.size : 0,
         activeCount: activeViolations.length,
         activeBlockingCount: blockingViolations.length,
+        baselineStale: analysisComplete ? reportBaselineStale : null,
       }
     );
     const reportPayload = {
@@ -1608,7 +1617,13 @@ async function main() {
       originJustCreated: !existingOrigin,
       adoption: adoptionForReport,
       designDepth,
-      advisories: computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+      advisories: {
+        ...computeDoctorAdvisories(root, config, coverage, rules, files, ts, parseHealth),
+        // Doctor parity: always emit improvement compass when doctor would (reportParity).
+        ...(designDepth?.improvementCompass
+          ? { improvementCompass: designDepth.improvementCompass }
+          : {}),
+      },
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)

package/bin/ark-mcp-runtime.mjs

@@ -36,6 +36,8 @@ import {
   createProjectId,
   createProjectIdentity,
 } from './lib/project-identity.mjs';
+import { buildProjectStatusManifest } from './lib/status-command.mjs';
+import { ARK_STATUS_MANIFEST_SCHEMA } from './lib/status-manifest.mjs';
 
 function arkRulesCatalogForManifest(snapshot) {
   if (snapshot?.errors?.length || !snapshot?.arkRules) return {};
@@ -2143,6 +2145,25 @@ export async function runArkMcp({ hookInput } = {}) {
         '— never a numeric score. Same plane as ark-check --rules-inventory.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'ark_status',
+      description:
+        'Unified session/project status manifest (ACS03): project identity binding, honest write-path ' +
+        'activation, last-check summary, ArkRules residual counts, and primary next action. Same ' +
+        'envelope as `ark status --json`. Never prompts; never a numeric score. Prefer after ' +
+        'ark_identity so project.expectedRoot is bound.',
+      inputSchema: { type: 'object', properties: {} },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          status: ARK_STATUS_MANIFEST_SCHEMA,
+          projectIdentity: projectIdentityOutputSchema,
+          binding: PROJECT_BINDING_SCHEMA,
+          authoritative: { type: 'boolean' },
+        },
+      },
+    },
   ];
 
   for (const tool of TOOLS) {
@@ -2664,6 +2685,48 @@ export async function runArkMcp({ hookInput } = {}) {
     }
   }
 
+  function runStatusTool(_params, binding) {
+    try {
+      const status = buildProjectStatusManifest({
+        root: args.root,
+        config: path.basename(configPath) === 'ark.config.json' ? 'ark.config.json' : configPath,
+        expectedRoot: binding?.expectedRoot ?? _params?.arguments?.project?.expectedRoot,
+        expectedProjectId:
+          binding?.expectedProjectId ?? _params?.arguments?.project?.expectedProjectId,
+        arkgateVersion: ark.version,
+      });
+      // Prefer MCP binding status when the tool framework already evaluated expectation.
+      if (binding && typeof binding.status === 'string') {
+        status.projectIdentity.binding = binding.status;
+        status.projectIdentity.authoritative = binding.authoritative === true;
+        if (binding.code) status.projectIdentity.code = binding.code;
+        if (binding.message) status.projectIdentity.message = binding.message;
+        if (binding.status === 'mismatch') {
+          status.nextAction = {
+            id: 'rebind-project-identity',
+            summary:
+              binding.message ||
+              'Project expectation does not match this MCP process — re-run ark_identity with the correct root.',
+          };
+        }
+      }
+      const payload = {
+        ok: binding?.status !== 'mismatch',
+        status,
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+        isError: binding?.status === 'mismatch',
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   function runRulesInventoryTool() {
     try {
       const governed = collectGovernedFiles(args.root, config);
@@ -2772,6 +2835,7 @@ export async function runArkMcp({ hookInput } = {}) {
     ark_recommend: runRecommendTool,
     ark_suggest_include: runSuggestIncludeTool,
     ark_rules_inventory: runRulesInventoryTool,
+    ark_status: runStatusTool,
   };
 
   const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);

package/bin/ark.mjs

@@ -33,6 +33,8 @@ import {
   readChangeSetFile,
   renderChangePreflight,
 } from './lib/prepare-change.mjs';
+import { runStatusCommand } from './lib/status-command.mjs';
+import { runAgentProjectionCommand } from './lib/agent-projection-command.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -81,6 +83,11 @@ function parseArgs(argv) {
     skipPackageManager: false,
     removeHost: undefined,
     requireWriteHook: undefined,
+    expectedRoot: undefined,
+    expectedProjectId: undefined,
+    write: false,
+    check: false,
+    stdout: false,
     help: false,
     version: false,
   };
@@ -127,6 +134,11 @@ function parseArgs(argv) {
     else if (arg === '--require-write-hook') {
       args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
     }
+    else if (arg === '--expected-root') args.expectedRoot = path.resolve(requireValue(arg, i++));
+    else if (arg === '--expected-project-id') args.expectedProjectId = requireValue(arg, i++);
+    else if (arg === '--write') args.write = true;
+    else if (arg === '--check') args.check = true;
+    else if (arg === '--stdout') args.stdout = true;
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
@@ -143,6 +155,10 @@ function usage() {
               [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
   ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--json] [--no-install] [--no-strict]
   ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
+  ark status  [--root <project>] [--config ark.config.json] [--json]
+              [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
+  ark agents-md [--root <project>] [--config ark.config.json] [--write] [--check] [--stdout] [--json]
+                [--tools <host>]
 
 Commands:
   start     New here? Analyze and preview the complete setup. Read-only unless --apply.
@@ -152,6 +168,13 @@ Commands:
             --apply --no-install applies those exact bytes and verifies them.
             (alias: ark update)
   preflight Validate one atomic create/update/delete set without writing project files.
+  status    Unified session/project manifest (identity, activation, last check, rules).
+            Never prompts. Prefer --json for agents; CI=1 forces JSON.
+  agents-md Version-matched agent contract projection (ACS04). Stamps package version +
+            contract summary into a managed AGENTS.md block. Non-authoritative — not a
+            gate input. Preview by default; --write merges without clobbering outside
+            regions; --check fails on version drift; --stdout prints the block only.
+            (aliases: agents-md, agent-projection)
 
 Options:
   --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
@@ -164,7 +187,12 @@ Options:
   --accept-conflicts
                 Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
   --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
-  --json        Emit the start/upgrade preview as deterministic machine-readable JSON.
+  --json        Emit the start/upgrade/status/agents-md preview as deterministic machine-readable JSON.
+  --write       For agents-md: merge the version-matched projection into AGENTS.md.
+  --check       For agents-md: exit 1 when projection stamp drifts from package version.
+  --stdout      For agents-md: print the projection block only (no file write).
+  --expected-root / --expected-project-id
+                Optional project expectation for status (MCP-compatible binding check).
   --preset     Start from a named architecture preset instead of detection.
   --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
                Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
@@ -900,6 +928,32 @@ async function main() {
     }
   }
 
+  if (args.command === 'status') {
+    return runStatusCommand({
+      root: args.root,
+      config: args.config,
+      json: args.json,
+      expectedRoot: args.expectedRoot,
+      expectedProjectId: args.expectedProjectId,
+      host: args.tools,
+      arkgateVersion: cliVersion(),
+    });
+  }
+
+  if (args.command === 'agents-md' || args.command === 'agent-projection') {
+    return runAgentProjectionCommand({
+      root: args.root,
+      config: args.config,
+      json: args.json,
+      write: args.write,
+      apply: args.apply,
+      check: args.check,
+      stdout: args.stdout,
+      host: args.tools,
+      arkgateVersion: cliVersion(),
+    });
+  }
+
   console.error(`Unknown command: ${args.command}`);
   console.error(usage());
   return 2;

package/bin/lib/adapter-contract.mjs

@@ -8,14 +8,72 @@
  * Pure CLI helper (bin/lib/adapter-contract.mjs). Zero Node I/O.
  */
 
-/** 1.4 adds optional evidence.arkruleId + evidence.arkruleSource (ADR 0012 / AR03). */
-export const ARK_ANALYSIS_RESULT_SCHEMA_VERSION = '1.4';
+/**
+ * 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';
 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) {
     if (ruleId === 'LAYER_IMPORT_VIOLATION') {
         if (evidence.typeOnly ||
@@ -51,7 +109,12 @@ function nextActionForDiagnostic(ruleId, evidence, violation) {
     }
     return `Resolve ${ruleId} without weakening ark.config.json, then run Ark again.`;
 }
-export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
+export function toAdapterDiagnostic(violation, fallbackSeverity = 'error', 
+/**
+ * Optional precomputed baseline-compatible targetKey (e.g. occurrence-aware from
+ * `adapterFindingOccurrenceTargetKeys`). When omitted, uses the first-occurrence key.
+ */
+targetKeyOverride) {
     const ruleId = text(violation.ruleId) ?? text(violation.code) ?? 'ARK_UNKNOWN';
     // Type-only placement debt (failsStrict:false / typeOnly non-peer) is warning severity.
     const severity = violation.severity === 'warning' ||
@@ -84,6 +147,8 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
         ...(text(violation.arkruleId) ? { arkruleId: text(violation.arkruleId) } : {}),
         ...(text(violation.arkruleSource) ? { arkruleSource: text(violation.arkruleSource) } : {}),
     };
+    const targetKey = targetKeyOverride ?? adapterFindingTargetKey(violation);
+    const findingRef = adapterFindingRefFromTargetKey(targetKey);
     return {
         ruleId,
         severity,
@@ -95,6 +160,9 @@ export function toAdapterDiagnostic(violation, fallbackSeverity = 'error') {
         },
         evidence,
         nextAction: text(violation.nextAction) ?? nextActionForDiagnostic(ruleId, evidence, violation),
+        findingRef,
+        targetKey,
+        docsCodePath: adapterDocsCodePath(ruleId),
     };
 }
 export function createAdapterResult(input) {
@@ -133,10 +201,16 @@ export function createAdapterResult(input) {
             }
         }
     }
+    // Occurrence-aware targetKeys (violations and warnings counted separately) so
+    // list identity matches baselineOccurrenceKeys on each stream — ACS06 freeze parity.
+    const violationList = input.violations ?? [];
+    const warningList = input.warnings ?? [];
+    const violationTargetKeys = adapterFindingOccurrenceTargetKeys(violationList);
+    const warningTargetKeys = adapterFindingOccurrenceTargetKeys(warningList);
     const diagnostics = [
         // toAdapterDiagnostic maps failsStrict:false / typeOnly non-peer → warning severity.
-        ...(input.violations ?? []).map((item) => toAdapterDiagnostic(item, 'error')),
-        ...(input.warnings ?? []).map((item) => toAdapterDiagnostic(item, 'warning')),
+        ...violationList.map((item, index) => toAdapterDiagnostic(item, 'error', violationTargetKeys[index])),
+        ...warningList.map((item, index) => toAdapterDiagnostic(item, 'warning', warningTargetKeys[index])),
     ];
     const base = {
         schemaVersion: ARK_ANALYSIS_RESULT_SCHEMA_VERSION,
@@ -286,6 +360,15 @@ export const ARK_ANALYSIS_RESULT_SCHEMA = {
                         },
                     },
                     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 },
                 },
             },
         },