arkgate 4.5.7 → 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) **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. |
+| 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.6.md](releases/4.5.6.md) (`arkgate@4.5.6` 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

@@ -607,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` |
 
@@ -618,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

@@ -446,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/package-surface.md

@@ -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.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.5.6.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.7",
-  "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.7",
+  "version": "4.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.5.7",
+      "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”.

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

@@ -1,6 +1,6 @@
 ---
 name: ark-explore
-description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
+description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when leftover design work remains. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
 ---
 
 # /ark-explore — Recon the real project (map only)
@@ -23,7 +23,7 @@ Name 1–3 **residual** lenses in plain language before skill-shopping. Always `
 
 **What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
 
-**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+**Anti false-done:** empty plan A + leftover design work → **Incomplete? yes**. Green imports alone
 are not “architecture finished.”
 
 **AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
@@ -59,12 +59,12 @@ If the consumer tree has a **domain glossary**, prefer its terms for layer/slice
 | Use `/ark-explore` when… | Do **not** use it when… |
 |--------------------------|-------------------------|
 | Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` or `/ark-fix` |
-| **Primary post-green door:** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
+| **Primary post-green door:** messy / leftover design work / “clarify for AI” | Skill-shopping coverage or think for the same leftover work |
 | Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
 | Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
 | Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |
 
-**Post-green single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
+**Post-green single path:** when doctor `postGreenPath` / ENFORCE · leftover design work is active, **this skill
 (shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot` only
 to apply B with user OK. Do not send the user to coverage or think as equal first choices.
 
@@ -75,7 +75,7 @@ to apply B with user OK. Do not send the user to coverage or think as equal firs
 | **Suggest** | Point at `ark start` → doctor; map only if user insists on recon before setup |
 | **Adapt** | Map false-green / ungoverned / concentrated edge; hand off adopt/contract before Shape vanity |
 | **Enforce** | Confirm edges; if residual smells/patterns appear, auto-upgrade to dual-plan seed / shape-focus |
-| **Enforce · design-weak** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
+| **Enforce · leftover design work** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
 
 `/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
 **You** are the full recon + pattern-planning skill.

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

@@ -21,7 +21,7 @@ Name 1–3 **residual** lenses in plain language before skill-shopping. Always `
 
 **What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
 
-**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+**Anti false-done:** empty plan A + leftover design work → **Incomplete? yes**. Green imports alone
 are not “architecture finished.”
 
 **AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
@@ -58,6 +58,7 @@ Never invent gate verdicts from these suggestions. Missing residual is honest em
 | Skills customized after install | Preserved by default. Preview `skillDrift` shows counts. **`--refresh-skills`** rewrites customized *skills* only with consent. |
 | Conflicted managed assets | Still need `--accept-conflicts`. Never silent overwrite of true edits. |
 | Multiple checkouts / monorepo packages | One `expectedRoot` per project; upgrade **each** pin; restart MCP after bump; prefer project-local CLI until identity matched **and** process version aligns. |
+| Stale `~/.claude/skills` or `~/.grok/skills` | Shared homes should be the newest ArkGate on the machine (additive; never downgrade). Refresh: `--install-agent-gates --skills-only --agent-homes --force`. Project skills may lag with the pin. |
 | Active host not in `--tools` / manifest | Preview `hostSelection` notes it and suggests `--tools` expansion. |
 
 **Post-apply:** read `postUpgradeChecks` (advisory). Confirm pin↔CLI, run doctor (compass + deepModuleCoach),

package/templates/skills/ark-autopilot.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”.

package/templates/skills/ark-explore.md

@@ -1,6 +1,6 @@
 ---
 name: ark-explore
-description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when design-weak. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
+description: Specialized map skill — decision-grade recon of layers + ArkRules opportunities + dual-plan seed (no apply). Primary post-green door when leftover design work remains. Not the default day-to-day path (use doctor + place/gate; guided apply is /ark-autopilot). CLI is a sensor; you read the tree. No gate bypass.
 ---
 
 # /ark-explore — Recon the real project (map only)
@@ -23,7 +23,7 @@ Name 1–3 **residual** lenses in plain language before skill-shopping. Always `
 
 **What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
 
-**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+**Anti false-done:** empty plan A + leftover design work → **Incomplete? yes**. Green imports alone
 are not “architecture finished.”
 
 **AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
@@ -59,12 +59,12 @@ If the consumer tree has a **domain glossary**, prefer its terms for layer/slice
 | Use `/ark-explore` when… | Do **not** use it when… |
 |--------------------------|-------------------------|
 | Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` or `/ark-fix` |
-| **Primary post-green door:** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
+| **Primary post-green door:** messy / leftover design work / “clarify for AI” | Skill-shopping coverage or think for the same leftover work |
 | Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
 | Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
 | Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |
 
-**Post-green single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
+**Post-green single path:** when doctor `postGreenPath` / ENFORCE · leftover design work is active, **this skill
 (shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot` only
 to apply B with user OK. Do not send the user to coverage or think as equal first choices.
 
@@ -75,7 +75,7 @@ to apply B with user OK. Do not send the user to coverage or think as equal firs
 | **Suggest** | Point at `ark start` → doctor; map only if user insists on recon before setup |
 | **Adapt** | Map false-green / ungoverned / concentrated edge; hand off adopt/contract before Shape vanity |
 | **Enforce** | Confirm edges; if residual smells/patterns appear, auto-upgrade to dual-plan seed / shape-focus |
-| **Enforce · design-weak** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
+| **Enforce · leftover design work** | **Primary post-green map door** — shape-focus + dual-plan B + extraction cards. False-done forbidden. Never claim healthy because plan A is empty. |
 
 `/ark-autopilot`, `/ark-adopt`, and `/ark-coverage` embed a **lighter** version of this pass.
 **You** are the full recon + pattern-planning skill.