arkgate 4.4.0 → 4.5.5

package/docs/README.md

@@ -53,15 +53,15 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · [CHANGELOG.md](../CHANGELOG.md) |
-| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. improvement compass for **4.4.0**, agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. deep-module coach post-4.5 **implemented, not published**; domain fitness & session truth for **4.5.0**; improvement compass for **4.4.0**; agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current published: [releases/4.3.0.md](releases/4.3.0.md) (`arkgate@4.3.0` on npm `latest`).  
-Next prepare: [releases/4.4.0.md](releases/4.4.0.md) (Status: prepared — not on npm until publish verify).  
-Prior: [releases/4.2.1.md](releases/4.2.1.md) (`arkgate@4.2.1`).  
-Previous: [releases/4.2.0.md](releases/4.2.0.md) (`arkgate@4.2.0`) · [releases/4.1.1.md](releases/4.1.1.md) (`arkgate@4.1.1`).  
+Current published: [releases/4.5.0.md](releases/4.5.0.md) (`arkgate@4.5.0` on npm `latest`).
+Prepared next: [releases/4.5.5.md](releases/4.5.5.md) (`arkgate@4.5.5` — not on `latest` until publish).  
+Prior: [releases/4.4.0.md](releases/4.4.0.md) (`arkgate@4.4.0`).  
+Previous: [releases/4.3.0.md](releases/4.3.0.md) · [releases/4.2.1.md](releases/4.2.1.md) · [releases/4.2.0.md](releases/4.2.0.md) · [releases/4.1.1.md](releases/4.1.1.md).  
 Previous major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0`).  
 Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-guide.md](agent-guide.md).
 

package/docs/agent-guide.md

@@ -59,7 +59,46 @@ path is authoritative only when that matching project id is also supplied. Only
 `binding.status: "matched"` with `authoritative: true` is authoritative; calls that omit the
 expectation remain compatible but are explicitly `unverified`.
 
-### Improvement compass (doctor)
+### Session recipe (agent turn)
+
+Default loop for each agent session (product language — no inventing residual):
+
+1. **Bind identity** — call `ark_identity` with `project.expectedRoot` = exact absolute project
+   root. Reuse root + returned `projectId` on later tools. Only `binding.status: "matched"` with
+   `authoritative: true` is authoritative.
+2. **Read status** — `ark status --json` / MCP `ark_status` for identity, write-path activation,
+   last-check summary, residual lens ids (`improvementCompass`), and primary next action.
+3. **Act** — address residual / next action / stable `findingRef` from diagnostics. Never invent
+   green residual lenses. Projection, skills, and AGENTS.md never enforce.
+4. **Doctor when compass mode is not full** — if `improvementCompass.mode` is `subset` or
+   `unavailable`, run `ark-check --doctor` (and `--json` for the full 15-lens map) before treating
+   residual as complete. When mode is `full`, status residual ids are a subset of doctor residual
+   for the same facts.
+
+```bash
+npx ark status --json --expected-root /abs/project/root
+# mode !== full → full residual map:
+npx ark-check --doctor --json
+```
+
+Product path: [use.md — Session recipe](use.md#session-recipe-agent-turn).
+
+### Two-axis done recipe
+
+Architecture residual and feature residual are **separate axes**. Never collapse them:
+
+| Axis | Where truth lives | Done means |
+|------|-------------------|------------|
+| **1. Architecture residual** | `ark status` / `ark-check --doctor` / improvement compass (scan) | Edges honest under the contract; residual lenses / design-weak addressed or deliberately deferred |
+| **2. Feature / ticket residual** | User brief, PR, tracker (process **outside** the package) | Requested behavior matches acceptance; product QA |
+
+**Enforce green ≠ feature done.** Green edges (or quiet residual lenses) only clear axis 1.
+Axis 2 is never a package LLM verdict or second scoreboard — agents and humans judge the ticket.
+
+Optional Completion bullet for skills: **Done axes** — architecture residual | feature residual.
+Compact router restates the same rule for day-zero installs.
+
+### Improvement compass (doctor + status)
 
 `ark-check --doctor` (human + `--json`) projects residual architecture work as a closed set of
 **lenses** (`doctor.improvementCompass`). Always `notAScore: true`. Never feeds `valid`,
@@ -67,17 +106,20 @@ strict-merge exit, or plan `goal.met`. Out-of-scope lenses (scalability, app sec
 full resilience) stay honest. Product path: [use.md — Improvement compass](use.md#improvement-compass-not-a-score).
 Package surface row: [package-surface.md](package-surface.md).
 
-**Status snapshot:** the status schema may carry a thin optional residual-id slice when Tooling
-passes it through, but **`ark status --json` does not compute the compass yet** — use doctor for
-residual lenses. Residual never changes status `nextAction` by itself.
+**Status snapshot:** `ark status --json` / MCP `ark_status` project a thin `improvementCompass`
+with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`).
+Incomplete facts → `subset` / `unavailable` + reason — **never invent green residual**. Residual
+never flips gate verdicts and never alone rewrites status `nextAction` as a score. When mode is
+not `full`, follow the [session recipe](#session-recipe-agent-turn) and run doctor.
 
 Compact router and skills read residual lenses in plain language; green edges alone are never
 “architecture finished” while residual remains.
 
-### Unified status snapshot (4.3)
+### Unified status snapshot (4.3+)
 
 For one machine-readable session/project manifest (identity binding, honest write-path activation,
-last-check summary, rules residual counts, primary next action) use:
+last-check summary, rules residual counts, primary next action, improvement-compass residual map)
+use:
 
 ```bash
 npx ark status --json
@@ -87,8 +129,8 @@ npx ark status --json --expected-root /abs/project/root
 
 MCP parity tool: **`ark_status`** (same envelope; pass `project.expectedRoot` after `ark_identity`).
 Schema: `arkgate/schema/status-manifest`. Never prompts; under `CI=1` JSON is forced. **Not a
-score** — counts and verdicts only. Write-path interpretation of activation vs merge teeth is under
-[Write-path honesty](#write-path-honesty).
+score** — counts, honesty modes, and residual ids only. Write-path interpretation of activation vs
+merge teeth is under [Write-path honesty](#write-path-honesty).
 
 **Stable finding refs (4.3):** every factory-emitted diagnostic on CLI JSON, MCP analysis
 envelopes, and opt-in hook repair payloads (`ARK_REPAIR_JSON`) carries:

package/docs/brownfield-adoption.md

@@ -9,6 +9,18 @@ The rule underneath all of it: **`ark.config.json` is authoritative.** A green c
 governs 40% of the tree, or a baseline full of false positives, is worse than no gate — it
 looks safe. Report the truth, then fix it.
 
+### Domain glossary (process only)
+
+If the repo already has a product/domain glossary, prefer those terms when naming layers,
+slices, intents, and Shape pilots. Common root names (detect; none required):
+
+- `CONTEXT.md`
+- `docs/glossary.md` · `docs/domain.md` · `docs/ubiquitous-language.md` · `docs/CONTEXT.md`
+
+Call out glossary language vs lived code when they disagree. **Missing glossary is normal** —
+do not spam warnings and do not invent a glossary file. Glossary content never enforces; the
+gate remains the contract + scan. Skills: `/ark-adopt`, `/ark-explore`.
+
 ## 1. Config — reflect what exists, propose the rest
 
 ```bash

package/docs/develop.md

@@ -69,7 +69,9 @@ can show `runtimeObserved: true` even when branch-protection policy is plan-unav
 | Rules inventory (brownfield) | `arkgate-check --rules-inventory` · MCP `ark_rules_inventory` |
 | Stable package API | [package-surface.md](package-surface.md) |
 | Diagnostic codes (`ruleId` why/fix) | [diagnostics.md](diagnostics.md) · root `DIAGNOSTIC_CATALOG` |
-| Session / project status snapshot | `ark status --json` · MCP `ark_status` · [agent-guide](agent-guide.md) · schema `arkgate/schema/status-manifest` |
+| Session / project status snapshot | `ark status --json` · MCP `ark_status` · [session recipe](agent-guide.md#session-recipe-agent-turn) · schema `arkgate/schema/status-manifest` |
+| Status compass honesty | `improvementCompass.mode`: `full` \| `subset` \| `unavailable` · residual ⊆ doctor when `full` · [package-surface](package-surface.md) |
+| Managed upgrade self-service | `ark upgrade --json` → `selfService` (activation labels + customized preserve) · [package-surface](package-surface.md) |
 | Version-matched AGENTS projection | `ark agents-md` · [agent-guide](agent-guide.md) · **non-authoritative** (never enforces) |
 | Stable finding refs (`findingRef` / `targetKey`) | analysis-result schema **1.5** · [agent-guide](agent-guide.md) · [package-surface](package-surface.md) |
 | Agent Skills layout (same 13 names) | `templates/agent-skills/` · [agent-guide](agent-guide.md#install-skills-ark-and-ecosystem) · `npx skills add …` |

package/docs/package-surface.md

@@ -18,7 +18,9 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 |---------|----------------|-----------------|
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
-| **Improvement compass (4.4)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. Status schema accepts an optional thin `improvementCompass` residual-id slice for Tooling pass-through — **`ark status` does not compute lenses yet**; agents should read doctor for residual. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input (`valid` / strict-merge / `goal.met` unchanged). Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`. |
+| **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
+| **Deep-module coach (post-4.5 advisory)** | `ark-check --doctor --json` → `doctor.deepModuleCoach`; human doctor section **Deep-module coach (advisory — not a score)** always when doctor runs (empty candidates / hot-path `unavailable` are honesty, not omission); HTML `data-advisory="deepModuleCoach"`. | Additive schema `1.0`. Always **`notAScore: true`**. **`hotPaths`**: recent-churn heuristic from bounded git log; `available` + `status` `ok` \| `unavailable`; empty `paths` when history missing/incomplete — **never invent**. **`deepeningCandidates`**: cards projected only from existing design smells / physical cohesion / reshape pilot / pilotLoop / residual compass lenses — **empty when no evidence** (no fake candidates). Never flips `valid`, strict-merge, completeness green, or `goal.met`. Prefer deep modules / named seams / test-at-public-interface process language in skills. Domain pure + CLI gen mirror (`deepeningCoach.ts` / `bin/lib/deepening-coach.mjs`); **not** a root package export — consume via `doctor.deepModuleCoach` (or the gen mirror in Tooling). |
+| **Upgrade what’s new (4.5.5)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty. Never invents residual or flips gates. |
 | **Doctor design fitness** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. `handler-in-persistence` covers static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so **absence of a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). **4.2 feedback hardening:** mode labels preserve the observed SUGGEST/ADAPT/ENFORCE state; a local permission/UI-state `canEdit` name alone is not a domain smell; real UI business rules route Domain → Application → UI; seed/fixture/demo/migration/generated files are not god-module pilots. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`**. Does **not** fail the gate by itself. |
 | **Post-green Shape door** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
 | **Golden pattern (new code)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
@@ -40,6 +42,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
+| **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
@@ -51,7 +54,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema **`1.5`** adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
 | **Stable finding refs (4.3)** | Root API `adapterFindingTargetKey` / `adapterFindingRefFromTargetKey` / `toAdapterDiagnostic` / `createAdapterResult`; CLI/MCP/repair envelopes via analysis-result diagnostics | Multi-turn re-address without fuzzy message match. `targetKey` **is** the baseline (occurrence) key so freeze identity is never orphaned; `findingRef` is a compact FNV-1a of that key. Line/message drift does not change the ref. Multi-turn fixture: `tests/fixtures/finding-refs/multi-turn-stability.json`. |
 | **Diagnostic code catalog** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. Docs ship in the npm tarball. |
-| **Status manifest** | CLI `ark status [--json]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action. Optional thin `improvementCompass` residual ids when Tooling supplies them. **Not a score.** Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
+| **Status manifest** | CLI `ark status [--json]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` / `projectStatusImprovementCompass` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action, and **`improvementCompass`** with honesty **`mode`** `full`\|`subset`\|`unavailable` (residual ids only; always `notAScore: true`; optional `reasonCode`/`reason`/`factsSource`/`contractHash`). **Not a score.** Residual never changes gate verdicts. Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
 | **Agent contract projection** | CLI `ark agents-md [--write] [--check] [--stdout] [--json]`; install/upgrade AGENTS templates; root API `buildAgentProjectionBlock` / `mergeAgentProjectionDocument` | Schema `1.0` (projection markers). Version-stamped managed block (`arkgateVersion` + contract summary + diagnostic short list). **Non-authoritative** — not a gate input; enforcement is ark-check / hooks / CI. Content-identity merge preserves customized regions outside markers. Drift: `--check` vs package version. |
 | **Agent Skills packaging** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `validateAgentSkillsPackage`; `npm run check:agent-skills` | Schema `1.0` (package contract). Same **13** skill names as flat templates; Agent Skills–compatible layout for `npx skills add`. No new skill names. Layout is generated 1:1 from `templates/skills/*.md`. |
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
@@ -204,10 +207,9 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md);
- next prepare: [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md);
-
-prior published: [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
+(current published: [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md); prepared: [4.5.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.5.md);
+ prior published: [4.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md), [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md),
+[4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
 previous: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md),
 [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md),
 [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md),

package/docs/product-voice.md

@@ -97,12 +97,28 @@ Examples:
 | **diagnostic code** / **ruleId** | Stable public violation id (e.g. `LAYER_IMPORT_VIOLATION`) with shared why/fix anchors — catalog-linked, not prose-only ([diagnostics.md](diagnostics.md)) |
 | **agent projection** | Version-matched AGENTS/CLAUDE (or equivalent) block generated from package + contract; **non-authoritative** — enforcement is ark-check / hooks / CI |
 | **finding ref** | Stable id for a finding across turns (ruleId + target key), so agents re-address without fuzzy message match |
-| **status snapshot** | One machine-readable project/session manifest (`ark status --json` shape): identity, activation honesty, last check, residual counts — not a numeric score |
+| **status snapshot** | One machine-readable project/session manifest (`ark status --json` shape): identity, activation honesty, last check, residual counts, thin compass residual map — not a numeric score |
+| **session recipe** | Agent loop: bind identity → read status → act on residual / findingRef; run doctor when status compass mode is not `full` |
+| **compass mode** | Status honesty label for the projected residual map: `full` \| `subset` \| `unavailable` — never invent green residual |
 | **improvement compass** | Closed projection of residual architecture work across fixed **lenses** (aligned to 15 common principles). Always `notAScore`. Never a gate input. |
 | **lens** | One named principle dimension (`soc`, `dip`, `domain`, …) with status `ok` / `residual` / `not-instrumented` / `out-of-scope` and evidence refs from existing sensors |
 | **topResidual** | Deterministic short list of residual lens ids — what to improve next, not a ranking score |
 | **out-of-scope lens** | Principle Ark does not instrument (e.g. scalability APM, SAST) — say so; do not invent residual |
 | **AI-easy architecture** | Small, pure, placeable modules and a golden pattern so the next agent turn stays ordered under the contract |
+| **self-service upgrade honesty** | After managed upgrade, consumers can see write-path activation labels and customized-content preserve without asking a maintainer |
+| **module** | Anything with a surface callers depend on and an implementation behind it (function, package, slice) — not only a TypeScript `module` keyword |
+| **interface** (product sense) | Everything a caller must know: types, invariants, errors, ordering, config — not only a TypeScript `interface` keyword |
+| **depth** / **deep module** | Much behavior behind a **small interface** (deep) vs interface almost as complex as the body (shallow). Prefer deep modules. **Never** a 0–10 depth score |
+| **seam** | Place where behavior can be swapped or tested without editing callers (port boundary). Name seams when proposing ports/adapters or Shape pilots |
+| **adapter** | Concrete thing that satisfies an interface at a seam |
+| **leverage** | Capability callers get per unit of interface they must learn |
+| **locality** | Change, bugs, and verification concentrate in one place |
+| **deletion test** | Process heuristic before extracting “just for tests”: if you delete the module and complexity *vanishes*, it was mostly pass-through; if complexity *reappears* across many callers, it was earning its keep. One adapter → seam still hypothetical; two real adapters → seam justified |
+| **test at the public interface** | Prefer verifying behavior through the seam’s public surface, not through private pass-through layers or extraction-for-test-only modules |
+| **hot path** (advisory) | Repo-relative path with elevated **recent change volume** (heuristic from git history when available). Advisory residual only — never a gate input; omit or mark unavailable when history is missing |
+| **deepening candidate** (advisory) | Shape residual card projected only from **existing** smells / cohesion / compass evidence — locality/leverage intent; never invents candidates without evidence; never flips the verdict |
+| **domain glossary** | Optional consumer file of product terms (common roots: `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`). Prefer terms for layer/slice/pilot naming when present. Missing glossary is normal — no warning spam; never enforces |
+| **two-axis done** | (1) architecture residual via status/doctor/compass (scan); (2) feature/ticket residual outside the package (process). **Enforce green ≠ feature done** |
 
 ## Public docs are product-only (from 4.4.0)
 
@@ -158,6 +174,10 @@ gate  →  same binary verdict on every parity-capable adapter
 | Name scan before process | “Scan: two layer import violations. Process: fix the Application→Domain edge first.” |
 | Label projection non-enforcing | “Regenerated agent contract for this package version. Enforcement remains ark-check / hooks / required CI.” |
 | Keep status counts honest | “Inventory and residual counts are evidence — not a health score.” |
+| Prefer deep modules | “Small interface, hide the complexity. Name the seam; test at the public interface.” |
+| Apply the deletion test | “If deleting this extract would vanish the complexity, skip the pass-through; if callers re-absorb it, keep the module.” |
+| Two-axis done | “Edges green and residual lenses quiet is architecture residual; ticket acceptance is a separate axis — Enforce green ≠ feature done.” |
+| Glossary when present | “Prefer `CONTEXT.md` / product glossary terms for pilot and layer names; missing glossary is fine.” |
 
 ## Avoid
 
@@ -187,6 +207,10 @@ gate  →  same binary verdict on every parity-capable adapter
 | Treating AGENTS.md / projection / skills as the write gate | Advisory surface; hard path is hooks / MCP prepare / required CI |
 | Free-generated sensor or rule ids outside the catalog | Guardrail catalog is closed; unknown codes are a bug, not creativity |
 | Numeric “architecture health” or trust score in status JSON | Counts and residuals yes; scored trust no |
+| Depth score / “deepness rank” / Excellent module bands | Depth is vocabulary for process judgment, not a score surface |
+| Extract “just for tests” without a deletion test | Pass-through modules add interface without locality or leverage |
+| Treat hot paths or deepening candidates as gate failures | Advisory residual only; missing git never invents hot paths |
+| Claim feature done solely because Enforce is green | Two-axis done: architecture residual and ticket residual are separate |
 
 ---
 

package/docs/use.md

@@ -87,6 +87,9 @@ list: [configuration.md](configuration.md).
 
 **Green edges ≠ elegant design.** Empty remediation plan is not “architecture finished” if design residual remains.
 
+**Two-axis done:** (1) architecture residual via status/doctor/compass; (2) feature/ticket residual
+outside the package. **Enforce green ≠ feature done.**
+
 ---
 
 ## When the gate is green but the code is still messy
@@ -105,6 +108,34 @@ npx arkgate-check --install-agent-gates --skills-only --force
 
 ---
 
+## Session recipe (agent turn)
+
+Short loop so agents do not invent residual or re-run doctor every message:
+
+1. **Bind identity** — MCP: call `ark_identity` with `project.expectedRoot` set to the project’s
+   exact absolute root; reuse that root plus the returned `projectId` on later Ark tools. CLI:
+   pass `--expected-root /abs/project/root` on `ark status` when you need matched vs stale binding.
+2. **Read status** — `npx ark status --json` (or MCP `ark_status`) for identity, write-path
+   activation honesty, last-check summary, residual lens ids, and primary next action.
+3. **Act** — work the residual / next action / stable `findingRef` from check diagnostics. Do not
+   invent green residual lenses. Green edges alone are never “architecture finished.”
+4. **Doctor when status is incomplete** — if status `improvementCompass.mode` is **`subset`** or
+   **`unavailable`** (or compass facts are missing), run `npx ark-check --doctor` (add `--json` for
+   the full 15-lens map) before treating residual as complete. When mode is **`full`**, status
+   residual ids are a safe subset of doctor residual for the same facts.
+
+```bash
+npx ark status --json --expected-root /abs/project/root
+# when mode is not full:
+npx ark-check --doctor
+npx ark-check --doctor --json   # doctor.improvementCompass
+```
+
+Details: [agent-guide — Session recipe](agent-guide.md#session-recipe-agent-turn) ·
+[package surface — status / compass](package-surface.md).
+
+---
+
 ## Improvement compass (not a score)
 
 Doctor shows an **improvement compass**: a closed set of architecture **lenses** (separation of
@@ -125,6 +156,8 @@ Improvement compass (not a score)
 | Never a gate input | Residual alone does **not** fail CI or flip `valid` |
 
 JSON: `ark-check --doctor --json` → `doctor.improvementCompass` (full lenses + `topResidual`).  
+Status also projects a thin residual map with honesty **`mode`**: `full` \| `subset` \| `unavailable`
+(always `notAScore`) — see [Session recipe](#session-recipe-agent-turn).  
 Human doctor prints the short section above.
 
 ### Align → Stabilize → Shape

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.4.0",
+  "version": "4.5.5",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",

package/schemas/ark.status-manifest.schema.json

@@ -242,11 +242,12 @@
     },
     "improvementCompass": {
       "type": "object",
-      "description": "Optional thin improvement-compass residual ids (notAScore). Never a gate input; full lenses on doctor JSON.",
+      "description": "Thin improvement-compass residual ids with honesty mode (notAScore). full | subset | unavailable. Never a gate input; full lenses on doctor JSON. When full, residual ids ⊆ doctor residual for the same facts. unavailable never invents green residual.",
       "additionalProperties": false,
       "required": [
         "schemaVersion",
         "notAScore",
+        "mode",
         "topResidual"
       ],
       "properties": {
@@ -256,6 +257,13 @@
         "notAScore": {
           "const": true
         },
+        "mode": {
+          "enum": [
+            "full",
+            "subset",
+            "unavailable"
+          ]
+        },
         "topResidual": {
           "type": "array",
           "items": {
@@ -263,6 +271,25 @@
             "minLength": 1
           },
           "maxItems": 15
+        },
+        "reasonCode": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "factsSource": {
+          "enum": [
+            "doctor-facts",
+            "report-snapshot",
+            "none"
+          ]
+        },
+        "contractHash": {
+          "type": "string",
+          "minLength": 1
         }
       }
     }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.4.0",
+  "version": "4.5.5",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.4.0",
+      "version": "4.5.5",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -1,13 +1,13 @@
 # ArkGate Agent Skills package
 
-> **Generated layout (Agent Skills packaging).** Do not edit SKILL.md files here by hand.
+> **Generated layout (ACS05).** Do not edit SKILL.md files here by hand.
 > Author skill bodies in `templates/skills/<name>.md`, then run
 > `npm run generate:agent-skills`. Drift: `npm run check:agent-skills`.
 
 This directory is the **Agent Skills–compatible** packaging of the same **13**
 `/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
 
-Package version when last generated context: **arkgate@4.3.0**
+Package version when last generated context: **arkgate@4.5.0**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

package/templates/agent-skills/ark-adopt/SKILL.md

@@ -31,6 +31,18 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
 
+## Domain glossary (process)
+
+When present, prefer the consumer **domain glossary** for layer names, slice folders, intent names, and pilot wording:
+
+| Detect (no requirement) |
+|-------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Prefer glossary terms over inventing parallel vocabulary.
+- Call out conflicts between glossary language and code reality (process judgment).
+- **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -184,6 +196,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-explore/SKILL.md

@@ -34,6 +34,26 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.
 
+## Deep modules (process)
+
+- Prefer **deep modules**: small **interface**, complexity hidden behind it (not a depth score).
+- When proposing a port/adapter or Shape pilot, **name the seam** (callers stay stable; behavior swaps behind it). One adapter → seam still hypothetical; two real adapters → seam justified.
+- Apply the **deletion test** before extracting “just for tests”: if deleting the module makes complexity *vanish*, it was pass-through; if complexity *reappears* across callers, it earned its keep.
+- Prefer verification **at the public interface** of the seam (locality/leverage), not private pass-through layers.
+- When doctor surfaces **hot paths** or **deepening candidates**, treat them as advisory residual only — never as a gate fail; bias dual-plan B pilots toward recent churn when listed.
+
+## Domain glossary (process)
+
+If the consumer tree has a **domain glossary**, prefer its terms for layer/slice folders, pilot names, and next-action prose:
+
+| Common root names (detect, do not require) |
+|--------------------------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Call out **glossary vs code** conflicts when names disagree with lived folders.
+- **Missing glossary is normal** — do not warn-spam or invent a glossary file.
+- Glossary content never enforces; the gate remains `ark.config.json` + scan.
+
 ## When / not when
 
 | Use `/ark-explore` when… | Do **not** use it when… |
@@ -390,6 +410,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-fix/SKILL.md

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Name residual lenses** on each cluster (SoC, DIP, coupling, …). Still no weaken-gate to clear a lens.
 
+## Deep modules (process)
+
+- Prefer fixes that leave a **deep module** at a named **seam** (port in the owning layer; adapter outside).
+- Apply the **deletion test** before extracting a layer “just so tests can mock it.”
+- After a port/inject fix, **test at the public interface** of the seam (match remediation `nextAction` language), not only private internals.
+
 ## When / not when
 
 | Use `/ark-fix` when… | Do **not** use it when… |
@@ -198,6 +204,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-loop/SKILL.md

@@ -31,6 +31,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Lens language on each cluster** while looping edges; residual shape lenses hand off to explore/autopilot.
 
+## Deep modules (process)
+
+- Judgment remediations that introduce ports: **name the seam**, prefer deep modules, **test at the public interface**.
+- Do not invent pass-through files that fail the **deletion test** just to clear a plan step.
+- Empty plan A is edge residual only — Shape residual still needs explore/autopilot; green edges ≠ feature done.
+
 ## When / not when
 
 | Use `/ark-loop` when… | Do **not** use it when… |
@@ -193,6 +199,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-place/SKILL.md

@@ -24,6 +24,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Deep modules (process)
+
+- Place so new code stays **deep**: one small public surface per concern; hide implementation details.
+- If the artifact is a port or adapter, **name the seam** and put the interface where callers should depend (usually Domain/Application), implementation on the outer side.
+- Do not scaffold empty pass-through modules that fail the **deletion test** (complexity would vanish if deleted).
+
 ## When / not when
 
 | Use `/ark-place` when… | Do **not** use it when… |
@@ -175,6 +181,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-think/SKILL.md

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).
 
+## Deep modules (process)
+
+- Prefer **deep modules** (small interface, hidden complexity). Never invent a depth score.
+- Label the **seam** on each option that introduces a port/adapter; apply the **deletion test** before pass-through extracts “for testability.”
+- Recommend tests **at the public interface** of the chosen seam.
+
 ## When / not when
 
 | Use `/ark-think` when… | Do **not** use it when… |
@@ -146,6 +152,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -32,6 +32,20 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **After upgrade:** refresh projection; re-doctor; compass residual still drives process, not scores.
 
+## Suggested improvements (what to try next)
+
+After `ark upgrade` (preview or apply), read JSON **`whatsNew`** or the human **Suggested improvements**
+block. It lists concrete try/inspect actions for this package line (advisory only — not a score):
+
+1. **Deep-module coach** — `ark-check --doctor` → `doctor.deepModuleCoach` (hot paths + deepening)
+2. **Improvement compass** — residual lenses on doctor/HTML (not a score)
+3. **Session recipe** — `ark status --json` honesty modes; doctor when mode is not full
+4. **Two-axis done** — architecture residual vs feature/ticket residual (Enforce green ≠ feature done)
+5. **Self-service honesty** — upgrade `selfService` write-path labels + customized preserve
+
+Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.
+
+
 ## Dual engine (mandatory)
 
 Use the semantic sensor (`ark-check --doctor --json` plus the strict contract

package/templates/skills/ark-adopt.md

@@ -31,6 +31,18 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
 
+## Domain glossary (process)
+
+When present, prefer the consumer **domain glossary** for layer names, slice folders, intent names, and pilot wording:
+
+| Detect (no requirement) |
+|-------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Prefer glossary terms over inventing parallel vocabulary.
+- Call out conflicts between glossary language and code reality (process judgment).
+- **Missing glossary is normal** — continue without warning spam. Never treat glossary prose as enforcement.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -184,6 +196,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`