arkgate 4.5.6 → 4.6.0

package/docs/README.md

@@ -53,12 +53,13 @@ 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. [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **in progress → 4.5.6 prepared**; deep-module coach **shipped in 4.5.5**; 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. |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. [understandable-ark-4.6](plans/understandable-ark-4.6/README.md) **4.6.0**; [field-upgrade-mcp-truth](plans/field-upgrade-mcp-truth/README.md) **shipped in 4.5.6**; deep-module coach **shipped in 4.5.5**; 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.5.5.md](releases/4.5.5.md) (`arkgate@4.5.5` on npm `latest`).  
+Current published: [releases/4.5.7.md](releases/4.5.7.md) (`arkgate@4.5.7` on npm `latest`).  
+Prepared: [releases/4.6.0.md](releases/4.6.0.md) (`arkgate@4.6.0`).  
 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`).  

package/docs/agent-guide.md

@@ -40,12 +40,14 @@ npx ark-check --install-agent-gates --skills-only --force
 
 ### Write-path honesty
 
-Claude/Grok/Antigravity can hard-block listed PreToolUse ops when installed and trusted.
-Cursor/Codex/OpenCode remain **advisory at write**. For every host, the repository-wide hard
-boundary is a **required GitHub status context** that runs `arkgate-check --strict-merge` (alias
-`ark-check --strict-merge`) — the CLI name is not the status context name. Never claim
-Cursor/Codex/OpenCode hard write. Soft-write alone does not mean the project is unfinished; doctor
-keeps it as an environment residual. See [ai-gates.md](ai-gates.md) and the README host matrix.
+Claude/Grok/Antigravity/Cursor can hard-block listed PreToolUse / preToolUse ops when installed
+and trusted (Cursor: `Write` / `StrReplace` via `.cursor/hooks.json`). Codex/OpenCode remain
+**advisory at write**. For every host, the repository-wide hard boundary is a **required GitHub
+status context** that runs `arkgate-check --strict-merge` (alias `ark-check --strict-merge`) —
+the CLI name is not the status context name. Never claim Codex/OpenCode hard write; never claim
+Cursor hard write without the trusted hooks file covering Write|StrReplace. Soft-write alone does
+not mean the project is unfinished; doctor keeps it as an environment residual. See
+[ai-gates.md](ai-gates.md) and the README host matrix.
 
 Surface the same plane from the CLI: pair **`ark status --json`** (activation facts) with
 **`ark-check --doctor`** (`doctor.writePath`) — advisory local write on soft hosts → **required**
@@ -605,10 +607,10 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 
 | Host | Installed paths | Skills path |
 |------|-----------------|-------------|
-| Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | `.claude/skills/<name>/SKILL.md` |
-| Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` |
+| Claude Code | `.claude/settings.json` hook + `.mcp.json` / `claude mcp add` | **Repo:** `.claude/skills/<name>/SKILL.md`; **home:** `$CLAUDE_HOME/skills` (default `~/.claude/skills`, `--claude-home`) |
+| Cursor | `.cursor/mcp.json` + `.cursor/rules/ark.mdc` | `.cursor/commands/` (Cursor also loads Claude **home** skills from `~/.claude/skills`) |
 | OpenAI Codex | `.codex/config.toml` (project primary, relative `--root .`; configured on disk is not runtime-active until restart + `ark_identity` match); optional legacy `$CODEX_HOME/config.toml` fallback uses absolute roots and scoped secondaries — see [ai-gates.md](ai-gates.md) | **Repo:** `.agents/skills/<name>/SKILL.md`; **home:** `$CODEX_HOME/skills/<name>/SKILL.md` (`--codex-home`) |
-| **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
+| **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | **Repo:** `.grok/skills/<name>/SKILL.md`; **home:** `$GROK_HOME/skills` (default `~/.grok/skills`, `--grok-home`) |
 | Google Antigravity | `.agents/hooks.json` (+ `GEMINI.md` for shared Gemini consumers) | `.agents/skills/<name>/SKILL.md` |
 | OpenCode | `opencode.json` MCP (`type: local`; advisory) | `.opencode/skills/<name>/SKILL.md` |
 
@@ -616,10 +618,13 @@ This is a path reference, not a guarantee table. Full copy-paste setups:
 [ai-gates.md](ai-gates.md). Skill inventory: main
 [README](../README.md#other-skills-only-when-you-need-them).
 When several repositories share one machine, repo catalogs stay pinned and isolated; unchanged
-skill bodies are not rewritten for a version stamp. The optional `$CODEX_HOME/skills` catalog is
-monotonic across ArkGate 4.2.0+ installers. Pre-4.2 binaries ignore its metadata and lock, so
-upgrade legacy repos before they write the optional home catalog. See
-[AI gates — Codex skill catalog](ai-gates.md#codex-skill-catalog-skillmd-not-flat-prompts).
+skill bodies are not rewritten for a version stamp. Shared **home** catalogs (Codex since 4.2;
+Claude/Grok since 4.6) are the machine floor: always latest additive, never downgrade. Refresh
+with `--agent-homes` (or `--claude-home` / `--grok-home` / `--codex-home`). Absent home trees
+are normal — doctor stays quiet until `ark-*` skills exist there. Pre-4.2 binaries ignore Codex
+home metadata and lock, so upgrade legacy repos before they write the optional Codex home
+catalog. See [AI gates — Codex skill catalog](ai-gates.md#codex-skill-catalog-skillmd-not-flat-prompts)
+and [shared Claude/Grok homes](ai-gates.md#shared-claude--grok-home-skills).
 
 ### Install skills — Ark and ecosystem {#install-skills-ark-and-ecosystem}
 

package/docs/ai-gates.md

@@ -286,20 +286,30 @@ Use both: the MCP server for discovery, the hook for enforcement.
 
 ## Cursor
 
-Cursor supports MCP servers (`.cursor/mcp.json`):
+Cursor supports MCP servers (`.cursor/mcp.json`) and project hooks (`.cursor/hooks.json`):
 
 ```json
 {
-  "mcpServers": {
-    "ark": {
-      "command": "npx",
-      "args": ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
-    }
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "npx arkgate-mcp --hook --hook-repair --fail-on-new-smells --root . --root-env CURSOR_PROJECT_DIR --config ark.config.json",
+        "matcher": "Write|StrReplace",
+        "failClosed": true,
+        "timeout": 30
+      }
+    ]
   }
 }
 ```
 
-Cursor has no pre-write hook, so the gate is advisory at write time — pair it with a rules file so the agent actually calls it. `.cursor/rules/ark.mdc`:
+When that hook is installed and trusted, Cursor **hard-blocks** agent `Write` / `StrReplace`
+for governed TypeScript sources (exit 2 or `permission: "deny"`). Repair envelopes may emit;
+Cursor does **not** guarantee Write `updated_input` reinjection — the agent must fix and retry
+from `agent_message`. Shell, Tab, and human edits still rely on CI.
+
+Pair with MCP + a rules file so the agent also calls advisory tools. `.cursor/rules/ark.mdc`:
 
 ```markdown
 ---
@@ -307,15 +317,15 @@ description: Ark architecture contract
 alwaysApply: true
 ---
 
-Before writing or editing any TypeScript source file, call the `validate_code`
-tool from the `ark` MCP server with the full post-edit file content and its
-path. If it reports violations, fix them before writing. The architecture
-contract is available authoritatively from `ark_manifest` after `ark_identity`
-matches. `ark://manifest` is compatibility-only and always unverified.
+Before trusting Ark MCP evidence, call `ark_identity` with `project.expectedRoot`
+set to the exact project root. Then call `ark_manifest`. Before writing TypeScript,
+prefer MCP `ark_prepare_write` / `validate_code` when available; the project
+`.cursor/hooks.json` hard gate still blocks invalid Write/StrReplace.
 ```
 
-Your repository backstop in Cursor is CI: `ark-check` fails its check on anything that slips
-through. It blocks the merge only when that status is required by repository policy.
+Your repository backstop remains CI: `ark-check` fails its check on anything that slips
+through (Shell bypass, Tab, incomplete coverage). It blocks the merge only when that status
+is required by repository policy.
 
 ## OpenAI Codex CLI
 
@@ -436,6 +446,25 @@ severity **info**, marked `deferred: true`, and omitted from doctor **Primary ne
 `/ark-upgrade` on Grok/Claude is not Incomplete because of them. **Temp/upgrade primary roots**
 stay fail-closed urgent (rewritten, not multi-project).
 
+### Shared Claude / Grok home skills {#shared-claude--grok-home-skills}
+
+Project catalogs follow that checkout’s ArkGate pin (they may lag). Shared user-home catalogs
+are the **machine floor**:
+
+| Scope | Path | Flag |
+|-------|------|------|
+| Claude home | `$CLAUDE_HOME/skills` (default `~/.claude/skills`) | `--claude-home` |
+| Grok home | `$GROK_HOME/skills` (default `~/.grok/skills`) | `--grok-home` |
+| All three + Codex | same monotonic protocol | `--agent-homes` |
+
+Doctor reports `agentHomeGaps` only when those catalogs already contain `ark-*` skills and
+lag the installed package. Temp/upgrade `--root` never mutates default user homes. Cursor
+sessions treat a stale Claude home as urgent because Cursor loads `~/.claude/skills`.
+
+```bash
+npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
+```
+
 ### Codex skill catalog (SKILL.md, not flat prompts)
 
 Codex discovers skills as directories containing `SKILL.md` (Agent Skills standard):

package/docs/develop.md

@@ -35,9 +35,9 @@ Local write hardness **differs by host**. CI required status is the shared hard
 
 | Host | Local write | MCP | Merge |
 |------|-------------|-----|-------|
-| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status context |
-| Codex · OpenCode | Best-effort / advisory | Advisory | Required status context |
-| Cursor | Advisory only | Advisory | Required status context |
+| Claude · Grok · Antigravity | Pre-write block when installed + trusted | Advisory | Required status context |
+| Codex · OpenCode | Warning only (not blocked) | Advisory | Required status context |
+| Cursor | Pre-write block for Write/StrReplace when `.cursor/hooks.json` is trusted | Advisory | Required status context |
 
 Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
 

package/docs/enthusiast/how-to-agent-gates.md

@@ -8,8 +8,9 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 
 Installs:
 
-- Write-path configuration (Claude/Grok hard PreToolUse; Cursor/Codex advisory MCP)
-  — PreToolUse uses **`--hook-repair`** (W4): on deny, stderr may include
+- Write-path configuration (Claude/Grok/Antigravity/Cursor hard PreToolUse when covered;
+  Codex advisory MCP)
+  — PreToolUse / Cursor `preToolUse` uses **`--hook-repair`** (W4): on deny, stderr may include
   `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` for hosts that re-inject a patch.
   Still exit 2 / hard block; never silent write. Drop `--hook-repair` for
   reject-only prose, or set `ARK_HOOK_REPAIR=0` and omit the flag.
@@ -20,7 +21,7 @@ Installs:
 | Host | Extra paths |
 |------|-------------|
 | Claude Code | `.claude/settings.json`, `.claude/skills/` |
-| Cursor | `.cursor/mcp.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
+| Cursor | `.cursor/mcp.json`, `.cursor/hooks.json`, `.cursor/rules/ark.mdc`, `.cursor/commands/` |
 | Codex | `.codex/hooks.json`, `.codex/config.toml`, `.agents/skills/` |
 | **Grok Build** | `.grok/config.toml`, `.grok/hooks/`, `.grok/skills/` |
 

package/docs/package-surface.md

@@ -20,7 +20,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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; 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; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP. Never invents residual or flips gates. |
+| **Upgrade what’s new (4.5.6+)** | `ark upgrade --json` → `whatsNew` (+ human **Suggested improvements** block; also on preview). | Always **`notAScore: true`**, **`neverGateInput: true`**. Closed try/inspect list: deep-module coach, improvement compass, session/status honesty, two-axis done, self-service honesty, registry-aware upgrade, skill drift/refresh, multi-project MCP. Never invents residual or flips gates. |
 | **Field upgrade truth (4.5.6)** | `ark upgrade` registry-aware install; JSON `reasonCode` / `suggestedInstallCmd`; `skillDrift`; `--refresh-skills`; `postUpgradeChecks`; `hostSelection`. | No false-skip when registry ahead; offline honesty; customized skills preserved unless opt-in refresh; checks are advisory only. |
 | **MCP process package honesty (4.5.6)** | Every MCP tool context → `processPackage` (`processPackageMismatch` / `processStale`, versions, `nextAction`). | Multi-checkout users: restart MCP after pin bump; prefer project-local CLI until identity matched and versions align. Fail-closed identity (WI01) unchanged. |
 | **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. |
@@ -209,8 +209,8 @@ 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.5.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.5.md);
- prior published: [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [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),
+(current published: [4.5.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.7.md);
+ prior published: [4.5.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.md), [4.5.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.0.md), [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),

package/docs/product-voice.md

@@ -16,11 +16,12 @@ deliberately in the same change). Voice is product surface, not marketing decora
 A track so simple a newcomer enters, so strict a senior trusts — and the AI ships faster
 because the design space is small and honest.
 
-- **Gate side:** machine-readable contract + write gate + CI. Deterministic. Fail-closed.
-  Green must mean something real. Two planes: **Layers** (inter) always; **ArkRules** (intra)
-  opt-in.
-- **Co-pilot side:** where code belongs, who talks to whom, how; dual plan **A** (edges) +
-  **B** (shape); one pilot at a time; never silent judgment codemod; never weaken the contract.
+- **Gate side:** architecture config (`ark.config.json`) + pre-write block where the host
+  supports it + required CI. Deterministic. Don’t show green if we could not verify.
+  Two planes: **import rules** (who may import whom) always; **ArkRules** (structure rules
+  inside a layer) opt-in.
+- **Coach side:** where code belongs, who talks to whom, how; fix imports first, then leftover
+  design work; one small refactor at a time; never silent auto-reshape; never weaken the config.
 - **Agent contract surface (4.3.0):** agents read **guardrail catalogs** and **scan** evidence;
   they **process** (judge / coach) outside the package. Projection and skills never become the
   pass/fail gate.
@@ -29,7 +30,7 @@ because the design space is small and honest.
   rank. Out-of-scope lenses (perf, app security tooling, full resilience) stay honest.
 - **Vibe-coder dual depth:** human doctor and skills lead with plain outcomes and one next move;
   experts keep full JSON. Full-AI workflows get the same single door — not a skill menu exam.
-- **False done is forbidden:** Enforce ≠ elegant design. `design-weak` / residual must not
+- **False done is forbidden:** “Rules on” ≠ elegant design. Leftover design work must not
   read as “healthy finished.” Empty ArkRules inventory is not a score. MCP configuration on
   disk is not proof that the current process belongs to this project.
 
@@ -47,57 +48,60 @@ Examples:
 
 | Bad | Good |
 |-----|------|
-| Ship it 🚀 your architecture is crushed! | Checked edges are clean. Residual design smells mean the tree is still design-weak. Next: `/ark-explore` shape-focus. |
+| Ship it 🚀 your architecture is crushed! | Import rules check out. Leftover design smells mean the tree is still messy. Next: `/ark-explore` shape-focus. |
 | You don’t need to understand anything. | Doctor reports one status light and one primary next action. Run `ark-check --doctor`. |
-| Become an architect in 60 seconds. | Install pins the contract and compact router. Full guided cleanup is `/ark-autopilot` after skills install. |
+| Become an architect in 60 seconds. | Install pins `ark.config.json` and a short agent router. Full guided cleanup is `/ark-autopilot` after skills install. |
 
 ---
 
-## Lexicon (prefer)
-
-| Term | Use for |
-|------|---------|
-| **contract** | `ark.config.json` layers, rules, include — the machine-readable architecture file |
-| **Layers plane** | Inter-layer edges: imports, placement, purity, isolation |
-| **ArkRules** (opt-in) | Intra-layer structure sensors + domain invariant catalogs as data (`arkrules/*`) |
-| **advisory ArkRules** | Default sensor mode — **not** merge teeth; does not fail CI/merge alone (FG-ARKRULES-ADVISORY-ONLY) |
-| **extraMergeTeeth** | Only when enforced structure/invariant rules exist **and** classification is honest (≥50% governed, ≥1 populated layer) |
-| **dual-plane residual** | Label findings **`[Layer]`** vs **`[ArkRules]`** — never blur them |
-| **rulesUnderContract** | Doctor/inventory counts for ArkRules — **never a score** |
-| **type-only placement debt** | `import type` edges on the violations list with `failsStrict:false` — prefer SharedTypes / owning layer; not runtime coupling |
-| **gate** / **write gate** | Host boundary that blocks or advises on invalid writes |
-| **edges** | Allowed import graph (plan **A** / remediation) |
-| **baseline** | Frozen known debt; does not make a wrong contract honest |
-| **remediation** | Fixing violations against the contract |
-| **pilot** | One extraction / reshape cluster at a time |
-| **shape** | Design residual after edges are clean (plan **B**) |
-| **design-weak** | Edges clean under Enforce, but design smells / pattern residual remain — not “done” |
-| **residual** | Work still open after a green edge check (usually Shape / plan **B**) |
-| **co-pilot** | Guidance that proposes order and pilots without silent codemod |
-| **fail-closed** | Incomplete analysis or unproven enforcement never looks green |
-| **honest coverage** | Governed % and empty scope that cannot false-green |
-| **mechanical-safe** | Deterministic auto-apply class only |
-| **judgment** | Human/agent design work; never silent auto-apply as mechanical-safe |
-| **doctor** | Control plane: status light + next action |
-| **compact router** | Default onboarding agent instructions (not the full skill pack) |
-| **hard write** | Non-bypassable PreToolUse block for listed ops (Claude/Grok when installed + trusted) |
-| **advisory write** | MCP/rules coach only (Cursor/Codex at write time) — not a hard block |
-| **project identity** | Stable canonical root + config identity returned by `ark_identity`; separate from contract and process identity |
-| **matched binding** | Live MCP answered for the exact project root, or for a contained descendant together with the matching project id; only this binding is authoritative |
-| **authoritative manifest** | Contract returned by `ark_manifest` after a matched identity handshake |
-| **compatibility manifest resource** | `ark://manifest` through standard `resources/read`; always unverified/non-authoritative because the request cannot portably carry a project expectation |
-| **configured on disk** | Host files name an Ark MCP command; says nothing about which process is currently running |
-| **runtime observed** | A live `ark_identity` response matched this workspace; never infer it from `.codex/config.toml` or hook files |
-| **required CI / status context** | Merge hard boundary when the repository makes the Ark job a **required GitHub status context** (CLI: `arkgate-check --strict-merge` / `ark-check --strict-merge`) |
-| **contract ready** | Project/layers/ArkRules honesty residual clear — not the same as “hard local write” |
-| **environment residual** | Permanent host/provider posture (e.g. soft-write Codex) kept in evidence without forcing global **Not finished** |
-| **guardrail catalog** | Closed vocabulary of allowed sensors, capabilities, diagnostic `ruleId`s, and skill roles — agents and copy choose from the catalog; they do not invent free-form enforcement claims |
-| **scan** | Deterministic engine / CLI / MCP evidence pass (layers, ArkRules sensors, status facts, prepare-write). Same inputs → same verdict. No LLM. |
-| **process** (agent judgment) | Skill- or agent-side coaching: placement, dual-plan, pilot choice, remediation order. Improves prevention; **never** package pass/fail |
-| **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, thin compass residual map — not a numeric score |
+## Lexicon (prefer) — 4.6 common words
+
+**Brands (keep):** **ArkGate** (product / npm `arkgate`) and **ArkRules** (opt-in structure rules
+inside a layer). Gloss on first mention; do not rebrand.
+
+Human copy prefers the **common** column. JSON field names (`designWeak`, `ruleId`, MCP tools)
+stay stable unless a change explicitly adds an alias.
+
+| Prefer (human) | Was / JSON | Use for |
+|----------------|------------|---------|
+| **architecture config** | contract | `ark.config.json` layers, rules, include |
+| **import rules** / **allowed dependencies** | Layers plane / edges | Who may import whom; placement, purity, isolation |
+| **ArkRules** (opt-in; gloss: structure rules inside a layer) | ArkRules | Intra-layer sensors + domain invariant catalogs (`arkrules/*`) |
+| **advisory ArkRules** | advisory ArkRules | Default sensor mode — **not** merge teeth; does not fail CI/merge alone |
+| **extra merge checks** | extraMergeTeeth | Only when enforced structure/invariant rules exist **and** classification is honest |
+| **label `[Layer]` vs `[ArkRules]`** | dual-plane residual | Never blur import-rule findings with ArkRules findings |
+| **ArkRules counts** | rulesUnderContract | Doctor/inventory counts — **never a score** |
+| **type-only import debt** | type-only placement debt | `import type` on the violations list with `failsStrict:false` |
+| **pre-write block** | hard write | Host actually blocks listed edit ops (installed + trusted) |
+| **warning only (not blocked)** | advisory write | MCP/rules coach; not a hard block |
+| **import graph** | edges | Allowed imports (fix these first) |
+| **baseline** | baseline | Frozen known debt; does not make a wrong config honest |
+| **fix** | remediation | Fixing violations against the config |
+| **one small refactor** | pilot | One extraction / reshape cluster at a time |
+| **shape / leftover design work** | **design-weak** / residual | Imports clean under Enforce, but design smells remain — not “done” |
+| **coach** | co-pilot | Guidance that proposes order without silent auto-reshape |
+| **don’t show green if unverified** | fail-closed | Incomplete analysis or unproven enforcement never looks green |
+| **honest coverage** | honest coverage | Governed % and empty scope that cannot false-green |
+| **safe to auto-apply** | mechanical-safe | Deterministic auto-apply class only |
+| **your judgment** | judgment | Human/agent design work; never silent auto-apply |
+| **doctor** | doctor | Status light + next action |
+| **short agent router** | compact router | Default onboarding agent instructions (not the full skill pack) |
+| **right project?** | matched binding / project identity | Live MCP answered for this exact project root (+ id). `ark_identity` |
+| **authoritative config read** | authoritative manifest | `ark_manifest` after a matched identity handshake |
+| **compatibility manifest** | `ark://manifest` | Always unverified — request cannot carry a project expectation |
+| **configured on disk** | configured on disk | Host files name an Ark MCP command; not proof of the live process |
+| **runtime observed** | runtime observed | A live `ark_identity` matched this workspace |
+| **required CI status** | required CI / status context | Merge hard boundary: required GitHub status running `arkgate-check --strict-merge` |
+| **config ready** | contract ready | Project/import-rules/ArkRules honesty clear — not the same as a local pre-write block |
+| **host limitation** | environment residual | Permanent soft-write host (e.g. Codex) — do not paint the whole project unfinished |
+| **allowed rule ids** | guardrail catalog | Closed vocabulary of sensors, capabilities, `ruleId`s, skill roles |
+| **check (tool)** | scan | Deterministic engine / CLI / MCP. Same inputs → same verdict. No LLM. |
+| **coaching / your judgment** | process | Skill- or agent-side. **Never** package pass/fail |
+| **diagnostic code** / **ruleId** | ruleId | Stable public violation id — catalog-linked ([diagnostics.md](diagnostics.md)) |
+| **agent summary** | agent projection | Version-matched AGENTS/CLAUDE block; **non-authoritative** |
+| **finding id** | finding ref | Stable id (ruleId + target key) across turns |
+| **status snapshot** | status snapshot | `ark status --json`: identity, activation, last check, leftover counts — not a score |
+| **shared agent skills (home)** | Codex/Claude/Grok home catalog | Machine floor: always latest additive; never downgrade |
 | **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. |
@@ -158,20 +162,20 @@ gate  →  same binary verdict on every parity-capable adapter
 
 | Do | Example |
 |----|---------|
-| Name the status light + plain fact + term + next action | “Enforce · design-weak. Checked edges are honest; design smells remain. Next: one Shape door — explore → dual-plan B → autopilot with OK.” |
+| Name the status light + plain fact + next action | “Enforce · leftover design work. Import rules check out; design smells remain. Next: one Shape door — explore → plan B → autopilot with OK.” |
 | Rank one primary door under residual | Doctor **Primary next action** #1; **Also** only for secondary |
 | Label expert skills as escapes | “Install skill pack only when doctor or a STOP handoff names a skill.” |
-| State host write honesty | “Cursor/Codex: advisory write. Required GitHub status context is the hard merge boundary.” |
+| State host write honesty | “Cursor: pre-write block for Write/StrReplace when hooks are trusted. Codex: warning only (not blocked). Required GitHub status is the merge boundary.” |
 | Soft-write ≠ unfinished project | “Architecture contract ready; Codex local writes are advisory.” Keep `soft-write-host` in evidence; reserve **Not finished** for contract/project debt. |
 | Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
-| Qualify edge-clean under design-weak | “None on checked edges … design residual remains. Not healthy finished.” |
-| Prefer fail-closed over fake hard | Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green |
-| State project binding before verdict | “Ark MCP matched this workspace; `ark_manifest` evidence is authoritative.” Otherwise: “Ark MCP is configured, but runtime identity is unverified. Restart and call `ark_identity` with the exact project root.” |
+| Qualify import-clean under leftover design | “None on checked imports … leftover design work remains. Not healthy finished.” |
+| Prefer unverified-as-not-green | Incomplete analysis, unobserved hooks, and soft MCP never paint as a hard green pre-write block |
+| State project binding before verdict | “Ark MCP matched this workspace; `ark_manifest` evidence is for this project.” Otherwise: “Ark MCP is configured, but we have not proven this is the right project. Restart and call `ark_identity` with the exact project root.” |
 | Keep inventory claims evidence-bound | “Possible rule candidate in the configured Application layer.” A filename or technical constant alone is not Domain evidence. |
 | Honesty clear ≠ architecture healthy | `productHonesty.finished` means residual **architecture** honesty sensors are clear — not a green graph score. Open blocking violations, ADAPT/SUGGEST with debt, dual-truth pin, or design residual keep `unfinished: true`. Permanent soft-write alone does **not**. |
 | Separate CI runtime from provider policy | Successful CI run ≠ required status; GitHub Free plan 403 → `unavailable-plan`, not “CI never ran.” |
 | Prefer catalog language for agent DX | “Stable `ruleId` with why/fix anchors.” Not a free-form list of “things that might be wrong.” |
-| Name scan before process | “Scan: two layer import violations. Process: fix the Application→Domain edge first.” |
+| Name the check before coaching | “Check: two layer import violations. Next: fix the Application→Domain import 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.” |
@@ -189,7 +193,7 @@ gate  →  same binary verdict on every parity-capable adapter
 | “auto-refactor your whole app” / magic codemod claims | We never silent-apply plan B |
 | “modes you pick” for Suggest/Adapt/Enforce | Those are **status lights**, not settings |
 | Skill-shopping lists as the default curriculum | Progressive disclosure: one door first |
-| “Healthy / done” while design-weak | False done |
+| “Healthy / done” while leftover design work remains | False done |
 | “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
 | “Not finished” solely because host is Codex/Cursor | Soft-write is environment residual; do not paint a green whole-tree project as unfinished architecture |
 | “MCP installed / active” because a config file exists | Say **configured on disk · runtime unverified** until `ark_identity` matches the expected root |
@@ -233,16 +237,17 @@ Skills table in docs = **escapes / expert**, not a second onboarding track.
 
 ## Hero phrases (approved)
 
-- One contract. One gate. One co-pilot.
+- One architecture config. One check. One coach.
 - Green must mean something real.
 - You arrive at Enforce; you never turn it on.
-- Enforce does not mean the design is elegant — only that checked edges are honest.
-- Empty plan A is not “architecture healthy” when design residual remains.
-- One pilot at a time. Pattern bets are never mechanical-safe.
+- Enforce does not mean the design is elegant — only that checked imports are honest.
+- A clean import check is not “architecture healthy” when leftover design work remains.
+- One small refactor at a time. Pattern bets are never auto-applied.
 - Doctor is the control plane: status light + next action.
-- Scan is deterministic. Process is judgment. Only the gate decides pass/fail.
+- The check is deterministic. Coaching is judgment. Only the gate decides pass/fail.
 - Guardrails are a catalog, not free generation.
-- Agent docs project the contract; they never replace the gate.
+- Agent docs summarize the config; they never replace the gate.
+- **ArkGate** and **ArkRules** are product names — gloss them; don’t invent a second brand.
 
 ## Hero phrases (forbidden)
 
@@ -263,15 +268,15 @@ Each model line follows the sentence template: **plain fact · term · next acti
 
 | Light | Model line |
 |-------|------------|
-| **Suggest** | Thin or new tree. Contract is not yet the control plane. Next: `ark start` preview, then `--apply`; re-run doctor. |
-| **Adapt** | Contract and tree still disagree, or debt is open. Write path does not fully protect you yet. Next: doctor top action #1. |
-| **Enforce** | Honest coverage and clean checked edges. Keep host write path + required CI. |
-| **Enforce · design-weak** | Checked edges are honest; design smells remain. Green is not elegant design. Next: one Shape door — map (`/ark-explore` shape-focus) → dual-plan B → apply B only with `/ark-autopilot` and OK. |
+| **Suggest** | Thin or new tree. Architecture config is not yet in charge. Next: `ark start` preview, then `--apply`; re-run doctor. |
+| **Adapt** | Config and tree still disagree, or debt is open. The write path does not fully protect you yet. Next: doctor top action #1. |
+| **Enforce** | Honest coverage and clean checked imports. Keep the host write path + required CI. |
+| **Enforce · leftover design work** | Import rules check out; design smells remain. Green is not elegant design. Next: one Shape door — map (`/ark-explore` shape-focus) → plan B → apply B only with `/ark-autopilot` and OK. |
 
 ### Primary next action
 
 - Lead with the **outcome**, then the **skill or command**, then the **constraint** (never mechanical-safe / never skill-shop).
-- When design-weak, rank the single Shape path first; do not list explore / coverage / think as equal first choices.
+- When leftover design work remains, rank the single Shape path first; do not list explore / coverage / think as equal first choices.
 
 ### Deny / gate failure
 
@@ -283,8 +288,8 @@ Never: mock the user, imply the gate is optional, or suggest disabling rules to
 
 ### Healthy finished
 
-Print “Healthy — nothing to do” **only** when there is no design-weak residual and no open top actions.
-Otherwise name the residual.
+Print “Healthy — nothing to do” **only** when there is no leftover design work and no open top actions.
+Otherwise name the leftover work.
 
 ---
 
@@ -315,7 +320,8 @@ Keep dual-engine rules and **STOP** handoffs. Never claim silent full-tree resha
 - [ ] One next action is obvious.
 - [ ] Status light is not a mode picker.
 - [ ] No false done under design-weak / incomplete analysis.
-- [ ] Technical terms present (contract, gate, edges, pilot) without slang.
+- [ ] Technical terms present (architecture config, import rules, ArkGate, ArkRules) without slang.
+- [ ] Leftover design work is never called “done”.
 - [ ] Expert skills are labeled expert — not the default curriculum.
 - [ ] Scan vs process is not blurred with package LLM pass/fail.
 - [ ] Codes, sensors, and capabilities stay inside the guardrail catalog.

package/docs/use.md

@@ -2,7 +2,7 @@
 
 For **anyone** shipping TypeScript with an AI coding agent. You do not need to study clean architecture first.
 
-**One contract. One gate. One co-pilot.**
+**One architecture config. One check. One coach.**
 
 ---
 
@@ -21,7 +21,7 @@ Then keep working with your agent. The doctor is the **control plane**: when stu
 |-----------|---------|
 | Unsure | `npx arkgate-check --doctor` |
 | Agent broke architecture | Fix the edge doctor names (or re-run check) |
-| Code is green but still a mess | Shape residual — see below |
+| Code is green but still a mess | Leftover design work — see below |
 | New ArkGate version | Follow doctor / upgrade guidance |
 
 Full skill pack is **optional** (expert depth). Day-to-day: compact router + doctor is enough.
@@ -47,7 +47,7 @@ In those cases a boundary linter or editor rules may be enough; see [README —
 |------|----------------|
 | While the AI writes | Host write gate or advisory MCP (depends on host) |
 | Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
-| Anytime | Doctor: Suggest / Adapt / Enforce (+ design-weak if residual) |
+| Anytime | Doctor: Suggest / Adapt / Enforce (+ leftover design work if the design is still messy) |
 
 **Codex / Cursor / OpenCode:** local write stays advisory forever — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that local writes are advisory; **Not finished** is reserved for real project/contract debt.
 
@@ -96,14 +96,16 @@ outside the package. **Enforce green ≠ feature done.**
 
 That is **Shape** work (plan B) — suggested, never auto-applied as silent magic.
 
-1. Doctor confirms design-weak (and residual lenses on the improvement compass)  
+1. Doctor confirms leftover design work (and residual lenses on the improvement compass)  
 2. Guided map / dual plan (skill pack: `/ark-explore` then `/ark-autopilot` with your OK)  
-3. One pilot at a time · re-run doctor  
+3. One small refactor at a time · re-run doctor  
 
 Install skills only when you want that guided path:
 
 ```bash
 npx arkgate-check --install-agent-gates --skills-only --force
+# optional: refresh shared Claude/Grok/Codex home skills (never downgrades)
+# npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
 ```
 
 ---

package/package.json

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

package/server.json

@@ -1,17 +1,17 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.pedroknigge/arkgate",
-  "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
+  "description": "ArkGate \u2014 architecture co-pilot for AI TypeScript (write gate, CI, plan/loop)",
   "repository": {
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.5.6",
+  "version": "4.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.5.6",
+      "version": "4.6.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/agent-skills/README.md

@@ -7,7 +7,7 @@
 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.5.6**
+Package version when last generated context: **arkgate@4.6.0**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)

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

@@ -190,7 +190,7 @@ Status lights from doctor — not settings you choose. Rank residual honestly:
 | **Suggest** | Thin/new tree; contract not control plane | Finish `ark start` → re-doctor; do not skill-shop |
 | **Adapt** | Contract/tree disagree or debt open | Explore + adopt/loop/contract; do not claim guarded |
 | **Enforce** | Honest coverage + clean checked **edges** | Confirm gates + CI; emit dual-plan B only if residual found |
-| **Enforce · design-weak** | Edges clean; design smells remain | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** pilot with user OK. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
+| **Enforce · leftover design work** | Imports clean; design still messy | **Primary Shape door:** explore shape-focus → dual-plan **B** → apply **one** small refactor with user OK. Empty plan A ≠ done. Never mechanical-safe B. False-done forbidden. |
 
 - **Setup (Suggest):** no config → `ark start` (start freezes origin after config, before gates).
 - **Align (Adapt):** open debt, low honesty, or false-green → explore + adopt/loop; do not claim “guarded”.