arkgate 4.5.7 → 4.6.1

package/docs/product-voice.md

@@ -16,11 +16,19 @@ 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.
+- **Five-door autonomy:** invoking `/ark-adopt`, `/ark-place`, `/ark-autopilot`, `/ark-explore`,
+  or `/ark-upgrade` **is** the approval. The agent writes or maps in that turn. CLI/MCP are
+  sensor + gate. Silent reshape from the compact router (unasked) stays forbidden.
+- **Team parliament:** the architecture file is a **constitution**. A product change must not
+  amend it. Stewards own loosen and baseline-grow. The ratchet is **new vs the branch you
+  merge to**, not only the file on this checkout. A small PR pays `--changed --base`, not
+  the whole tree. Humans who never hit the write hook are allowed to ignore Ark.
 - **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 +37,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 +55,66 @@ 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; invoke of an apply door is the approval — not silent compact-router reshape |
+| **five doors** | skill menu of 13 | adopt · place · autopilot · explore · upgrade — other names are shortcuts |
+| **law / constitution** | contract + baseline + ArkRules files | `ark.config.json`, `arkrules/*`, `.ark-baseline.json` — a different change type than product |
+| **steward** | contract owner | GitHub handle or email in `stewards`; only they may loosen the law or grow the baseline |
+| **several hands** | multi-author / CODEOWNERS | Doctor asks for stewards or shows list drift; adopt proposes handles or emails, never invents names |
+| **contract session** | `--contract-session` | Explicit “this diff is a law change”; still never mixed with product files |
+| **vs the base branch** | `--against` / `--changed --base` / `status --vs` | Ratchet and honesty against the ref you merge to |
+| **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 +175,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 +206,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 +250,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,38 +281,47 @@ 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: map (`/ark-explore` shape-focus) then apply one small refactor with `/ark-autopilot` (invoke = apply). |
 
 ### 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
 
 ```text
-[What failed in plain terms]. [Rule or evidence id]. Next: [one fix path — /ark-fix, prepare-write, or contract edit].
+[What failed in plain terms]. [Rule or evidence id]. Next: [one fix path — /ark-autopilot, /ark-place, or /ark-adopt].
 ```
 
 Never: mock the user, imply the gate is optional, or suggest disabling rules to “finish.”
+Never: tell an agent to edit `ark.config.json` to clear a product-PR red. That is a **contract
+session** for a steward — split the PR.
+
+```text
+This change mixes the constitution with product files. Next: split the PR, or run a steward
+--contract-session that touches only ark.config / arkrules / .ark-baseline.json.
+```
 
 ### 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.
 
 ---
 
 ## Compact router model
 
-Keep short. Three jobs only:
+Keep short. Five doors only:
 
 1. Point at **doctor** as status.
-2. Day-to-day place / validate / check.
-3. Point at **full skill pack install** as optional expert depth — not a skill catalog dump.
+2. Session 0: **`/ark-adopt`**. Day-to-day new files: **`/ark-place`**.
+3. Apply / leftover design: **`/ark-explore`** then **`/ark-autopilot`** (invoke = apply one refactor).
+4. Bump: **`/ark-upgrade`**.
+5. Full skill pack is optional expert depth — not a 13-name exam.
 
 ---
 
@@ -302,11 +329,27 @@ Keep short. Three jobs only:
 
 | Skill role | Frontmatter tone |
 |------------|------------------|
-| `/ark-autopilot` | Guided **end-to-end** path (explore → dual plan → apply A; B with OK) |
-| `/ark-explore` | Map / dual-plan **seed** only; primary post-green map half |
-| Others | Specialized escape; name when **not** to use them |
+| `/ark-adopt` | Session 0 — write the path (greenfield + brownfield) |
+| `/ark-place` | New feature — place **and write** |
+| `/ark-autopilot` | Apply A + one Shape refactor; invoke = approval |
+| `/ark-explore` | Map / dual-plan **seed** only |
+| `/ark-upgrade` | Preview then apply in-turn |
+| Others | Shortcut to a door above |
+
+Autonomy contract on every door. Never claim silent full-tree reshape from the compact router.
+
+---
+
+## Autonomy contract (skills)
+
+Invoking a five-door skill **is** the approval. Write or map in the same turn.
+
+**CLI budget:** identity only if using MCP; one doctor / recommend / upgrade preview; then work;
+then check. Forbidden as the deliverable: dumping `--plan` JSON, “approve?”, or
+`STOP — invoke /ark-X` for work that door absorbs.
 
-Keep dual-engine rules and **STOP** handoffs. Never claim silent full-tree reshape.
+**Still never:** weaken the architecture config; invent `mechanical-safe` kinds; claim finished
+while leftover design work remains; batch every Shape bet in one turn.
 
 ---
 
@@ -315,7 +358,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,21 @@ 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)  
-2. Guided map / dual plan (skill pack: `/ark-explore` then `/ark-autopilot` with your OK)  
-3. One pilot at a time · re-run doctor  
+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` applies one refactor)  
+3. One small refactor at a time · re-run doctor  
+
+**Teams:** do not amend `ark.config.json` in a product PR. Local gate:
+`npx arkgate-check --changed --base origin/dev`. Law-only PRs use
+`--contract-session` (stewards own loosen / baseline-grow). Checkout honesty:
+`npx arkgate status --vs origin/dev`.
 
 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,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.5.7",
+  "version": "4.6.1",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",

package/schemas/ark.config.schema.json

@@ -632,6 +632,15 @@
         "minLength": 1
       },
       "default": {}
+    },
+    "stewards": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "uniqueItems": true,
+      "default": []
     }
   },
   "$defs": {

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

@@ -292,6 +292,57 @@
           "minLength": 1
         }
       }
+    },
+    "vsBase": {
+      "type": "object",
+      "description": "Checkout vs a git base ref: pin, contract identity, baseline grow. Advisory honesty only — never a gate input.",
+      "additionalProperties": false,
+      "required": [
+        "baseRef",
+        "line",
+        "pinLocal",
+        "pinBase",
+        "contractEqual",
+        "baselineGrew"
+      ],
+      "properties": {
+        "baseRef": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pinLocal": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "pinBase": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "contractEqual": {
+          "type": "boolean"
+        },
+        "baselineGrew": {
+          "type": "boolean"
+        }
+      }
     }
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "4.5.7",
+  "version": "4.6.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.5.7",
+      "version": "4.6.1",
       "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.1**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (frozen catalog)