arkgate 4.4.0 → 4.5.0

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. domain fitness & session truth for **4.5.0** with honesty modes / mandatory domain split / self-service residual, 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.4.0.md](releases/4.4.0.md) (`arkgate@4.4.0` on npm `latest`).  
+Next prepare: [releases/4.5.0.md](releases/4.5.0.md) (Status: prepared — not on npm until publish verify).  
+Prior: [releases/4.3.0.md](releases/4.3.0.md) (`arkgate@4.3.0`).  
+Previous: [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,31 @@ 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).
+
+### 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 +91,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 +114,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/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,7 @@ 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`. |
 | **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 +40,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 +52,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 +205,10 @@ 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.4.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.4.0.md);
+ next prepare: [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md);
+ prior published: [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,15 @@ 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 |
 
 ## Public docs are product-only (from 4.4.0)
 

package/docs/use.md

@@ -105,6 +105,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 +153,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.0",
   "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.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.4.0",
+      "version": "4.5.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"