arkgate 3.0.4 → 3.1.0

package/docs/agent-guide.md

@@ -281,14 +281,21 @@ Prefer preparing the write before the host commits it to disk:
 | Surface | Role |
 |---------|------|
 | MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash + optional `goldenPattern` in one call |
+| MCP **`ark_prepare_change`** | Validate one complete create/update/delete batch in memory; optional `changeMap` also returns structural convergence; never writes |
+| CLI **`ark preflight --changes <file> --json`** | Same atomic verdict and map convergence for hosts/scripts that do not call MCP |
 | Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch revalidation green or discarded |
 | PreToolUse **`--hook-repair`** | On deny: `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` on stderr (still exit 2 — never silent write) |
-| Doctor **`writePath`** | Reports `repair` \| `reject-only` \| `mcp-only` \| `none` for installed gates |
+| Doctor **`writePath`** | Reports installed mode plus `enforcementLadder` (`supported` / `installed` / `active` / `bypassable`, evidence, operation coverage, required-status honesty) |
 | Doctor **`goldenPattern`** | Optional Q03 advisory summary (`present` / `invalid`); never clears design-weak |
 
 Port-proof inject binding is **judgment** for auto-apply (signature/arity change), not write-path autoPatch.
 Full reference: [ai-gates.md](ai-gates.md). Loop-cost harness: `npm run eval:loop-cost`.
 
+Blocking diagnostics carry one deterministic `nextAction` in both human and JSON output. Complete
+Codex `ApplyPatch` payloads use the same atomic batch engine as CLI/MCP before single-file safety
+checks; this improves early feedback without upgrading Codex's bypassable hook to a universal hard
+boundary. Removing `AGENTS.md`, skills, or session context never changes the contract verdict.
+
 Do not invent layers outside the 11-layer profile or named presets. Unrecognized
 directories (`utils/`, `lib/`) must be classified explicitly via `/ark-contract`.
 
@@ -307,7 +314,7 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 |------|-----------------|-------------|
 | 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/` |
-| OpenAI Codex | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`; doctor defers non-temp home gaps when session host ≠ Codex — see [ai-gates.md](ai-gates.md)) | `$CODEX_HOME/prompts` (`--codex-home`; fix when using Codex) |
+| OpenAI Codex | `$CODEX_HOME/config.toml` (global; absolute `--root`; multi-project → secondary `ark_<slug>` unless `--force`; doctor defers non-temp home gaps when session host ≠ Codex — 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` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:
@@ -672,6 +679,13 @@ The strongest place to constrain an AI agent is the moment it writes a file, not
 JS-API TypeScript — nested or project) so a host can gate
 the write path:
 
+For a complete multi-file candidate, use `ark preflight --changes changes.json --json` or MCP
+`ark_prepare_change`. Add `--change-map map.json` (or MCP `changeMap`) only for an explicit schema
+`1.0` structural plan. Ark binds its normalized `changeMapHash` and compares the full candidate
+against the current supplied base. `convergence.findings` separates satisfied, missing,
+contradictory, and unplanned paths/edges; any structural mismatch rejects the batch. No map is
+required, and `behavioralCompletion` remains `not-evaluated` even when structure converges.
+
 ```bash
 npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
 ```

package/docs/ai-gates.md

@@ -48,7 +48,11 @@ you pass `--force`, so review and commit only the templates that match your proj
 **Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
 (`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
 `autoPatch` flags), the supported profile for the active host, and the evidence actually found.
-Supported capability and installed guarantee are deliberately separate.
+`writePath.enforcementLadder` separates `supported`, `installed`, `active`, and `bypassable` for
+local hooks, advisory MCP, and CI. Doctor leaves hook trust and required-status policy
+`unverified`; an actual covered PreToolUse denial can report operation-scoped activity. Codex
+`apply_patch` can expose a complete patch to the shared atomic preflight, but the host remains
+bypassable/advisory because some Code Mode paths do not dispatch the project hook.
 
 **Design fitness (3.0.1+):** the same doctor JSON may include `doctor.designFitness` and
 `doctor.designSmells[]` (path evidence). Edge-clean `operatingMode: enforce` can still set
@@ -182,6 +186,9 @@ The MCP server exposes a resource and tools agents can use proactively (not an e
 - **`ark://manifest`** (resource) — the machine-readable architecture contract (layers + rules), so the agent can read the architecture before generating code.
 - **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate). May return additive **`autoPatch`** (W1) for mechanical-safe import-type rewrites.
 - **`ark_prepare_write`** (tool) — **W2:** place + constrain + validate + optional autoPatch + judgmentBrief + contentHash in one call (composes `ark_place` + write gate).
+- **`ark_prepare_change`** (tool) — **T02–T05:** read-only atomic create/update/delete preflight with cross-file edge/cycle findings and candidate fingerprints. Optional `changeMap` accepts strict schema `1.0` intent and returns its hash plus satisfied/missing/contradictory/unplanned structural convergence; behavioral completion is not evaluated. Omission is supported. MCP registration remains advisory unless the host makes invocation non-bypassable.
+- Blocking CLI/MCP/hook diagnostics include the same deterministic `nextAction`. `AGENTS.md`, skill
+  catalogs, session prose, and live LLM calls are not inputs to the enforcement verdict.
 - **`ark_place`** (tool) — given a target file path, returns its layer, forbidden globals, and which layers it may / must not import. Call it *before* writing a new file so generated code lands in a governed location.
 - **`ark_check`** (tool) — runs the full architecture check and returns structured violations (applies the baseline automatically when one exists).
 - **`ark_coverage`** (tool) — per-layer file counts, the full unclassified-file list, and layers whose patterns match nothing.
@@ -268,7 +275,7 @@ Hand-editing with relative `--root .` is wrong: Codex does not use the project a
 
 ```bash
 npx ark-check --install-agent-gates --tools codex
-# optional: install /ark-* slash prompts into $CODEX_HOME/prompts
+# optional: install /ark-* skills into $CODEX_HOME/skills/<name>/SKILL.md
 npx ark-check --install-agent-gates --codex-home
 ```
 
@@ -309,11 +316,36 @@ primary A. It writes a **scoped secondary** table:
 
 `ark-check --doctor` surfaces the multi-project state so you are not left thinking B owns
 `ark://manifest` when only a secondary table exists. **Deferred (fix when using Codex):**
-non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/prompts`) are
+non-temp Codex-home gaps (`codex-home-multi-project`, stale `$CODEX_HOME/skills`) are
 severity **info**, marked `deferred: true`, and omitted from Top actions when the session
 host is known and not Codex — `/ark-upgrade` on Grok/Claude is not Incomplete because of
 them. **Temp/upgrade primary roots** stay fail-closed urgent (rewritten, not multi-project).
 
+### Codex skill catalog (SKILL.md, not flat prompts)
+
+Codex discovers skills as directories containing `SKILL.md` (Agent Skills standard):
+
+| Scope | Path |
+|-------|------|
+| **Repo** (written by `--tools codex`) | `.agents/skills/<name>/SKILL.md` |
+| **Home** (optional `--codex-home`) | `$CODEX_HOME/skills/<name>/SKILL.md` |
+
+Flat `.codex/prompts/*.md` files are **not** the invocable skill catalog. Install writes the
+repo catalog above so AGENTS.md `/ark-*` references match what Codex can load. After install,
+Ark verifies those references against each selected host catalog.
+
+**Parity & honesty (doctor / install):**
+
+- Doctor distinguishes **missing / stale / legacy-prompts-only** for repo (`.agents/skills`) and
+  home (`$CODEX_HOME/skills`). Home debt is **deferred** when the session host is not Codex.
+- Legacy flat prompts alone are reported as non-loadable skill debt with a
+  `--skills-only --tools codex --force` (repo) or `--codex-home --force` (home) fix.
+- Codex **write path is advisory**: MCP + best-effort `.codex/hooks.json` is **not** a hard
+  write boundary and is **not** equivalent to Claude/Grok PreToolUse hard-write + repair.
+  The hard merge backstop is CI `--strict-merge` (or `--strict`) plus a required status check.
+- CI workflows that run ark-check without the fail-closed profile (or with only
+  `--strict-config`) surface gap `enforcement-ci-not-fail-closed`.
+
 ## Grok Build (xAI)
 
 Grok reads project rules from **`AGENTS.md`**, project MCP from **`.grok/config.toml`**

package/docs/configuration.md

@@ -95,3 +95,47 @@ Safety fields:
 
 The packaged JSON Schema is authoritative for types, constraints, defaults, and the unknown-key
 policy.
+
+## Contract transitions
+
+`ark-check --strict-merge` protects the transition into a new contract, not only the resulting
+file. In a Git checkout it compares the candidate `ark.config.json` with the merge base when that
+base is available. CI can bind the comparison explicitly:
+
+```bash
+ARK_POLICY_BASE_REF="$BASE_SHA" npx ark-check --strict-merge
+```
+
+For local or non-Git automation, supply a committed config file or Git ref:
+
+```bash
+npx ark-check --strict-config --policy-base ./before.ark.config.json --json
+npx ark-check --strict-merge --policy-base-ref origin/main
+```
+
+The additive JSON result includes `policyDelta`: both policy hashes, the overall classification,
+stable findings, and `blockingFindingIds`. Supported comparisons cover governed include/exclude
+roots, layer patterns/exclusions/forbidden globals, deny rules, same-layer peer isolation,
+cycle policy, dynamic-import allowlists, and safety thresholds. Ambiguous ownership changes are
+`judgment-required` rather than guessed.
+
+Weakening and judgment-required transitions fail closed. An intentional exception is an explicit
+JSON artifact passed with `--policy-ack`:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "basePolicyHash": "fnv1a-...",
+  "candidatePolicyHash": "fnv1a-...",
+  "findingIds": ["weakening:$.dynamicImportAllowlist:added"],
+  "reason": "Temporary loader while the static registry is migrated."
+}
+```
+
+The acknowledgement must list every blocking finding exactly. It is not a permanent allowlist:
+changing either contract changes its hash and invalidates the acknowledgement.
+
+MCP clients can call `ark_policy_delta` with the previous `baseConfig`, an optional candidate
+contract (the current project contract is the default), and the same optional acknowledgement.
+It invokes the public classifier directly, is read-only, and marks a blocking result as an MCP
+error without maintaining separate adapter policy.

package/docs/package-surface.md

@@ -7,6 +7,8 @@
 In-repo `docs/` remains the package/agent reference. Source: GitHub; distribution: npm.
 
 This document is the consumer contract for **what is stable** vs **what is experimental**.
+It ships as the consumer contract linked from the npm README. The separate experimental-runtime
+hardening guide remains repository-hosted rather than duplicated in the gate tarball.
 
 ---
 
@@ -23,7 +25,12 @@ This document is the consumer contract for **what is stable** vs **what is exper
 | **AI-velocity eval (Q05)** | `npm run eval:ai-velocity` → `eval/ai-velocity-report.json` | Fixture-measured (no live LLM). Same feature scenario on design-weak vs golden-path arms; metric **`placementTurns`** (agent-equivalent). Golden must be strictly better. Method string lives next to the number. Does not weaken the gate. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
-| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Versioned JSON Schema; committed v1 compatibility fixture protects rule, severity, location, and evidence fields. |
+| **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
+| **Atomic change preflight (T02, 3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
+| **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
+| **Structural convergence (T04, 3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
+| **Enforcement ladder + fixed journey (T05, 3.1.0)** | `doctor.writePath.enforcementLadder`; hook repair `enforcement`; `npm run eval:change-integrity` | Additive schema `1.0` separates supported/installed/active/bypassable state and evidence. Hard is operation-scoped only for a supported covered hook; MCP is advisory; required CI status stays unverified locally. Fixed no-context fixture proves CLI/MCP/hook/final parity, one casual denial, acceptance behavior, and strict Ark. |
+| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Schema `1.1` adds optional `nextAction`; the `1.0` fixture and consumer-owned TypeScript diagnostics remain valid. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. When/not when, explore Shape dual-plan seed, extraction cards, day-zero origin order). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |

package/docs/threat-model.md

@@ -27,21 +27,24 @@ infrastructure beyond how this package is published.
 
 | ID | Threat | Impact | Mitigations (shipped) |
 |----|--------|--------|------------------------|
-| T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor writePath honesty |
+| T1 | Agent bypasses hook (direct `fs` / alternate tool) | Ungoverned code lands | CI gate; optional pre-commit (Q3); doctor ladder never upgrades installed files to active/hard proof |
 | T2 | Human commits without agent path | Same as T1 | `templates/hooks/pre-commit-ark`; branch protection + required check (Q3 external) |
-| T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge` profile |
-| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | safety diagnostics; false-green adoption detector |
+| T3 | CI job missing / not required | Merge green without architecture | doctor `enforcement-ci-*` gaps; `--strict-merge`; required-status remains locally `unverified` |
+| T4 | Config weakened (`peerIsolation: false`, empty rules) | False green | semantic policy-delta guard in strict merge; hash-bound explicit acknowledgement; present-state safety diagnostics |
 | T5 | Baseline ratcheted open | Debt reintroduced | baseline unused/stale signals; occurrence keys |
 | T6 | Dual MCP bin / wrong root | Gate points at wrong tree | migrate-commands; Codex fail-closed temp roots |
 | T7 | Malicious dependency in publish | Compromised gate | signed tags, npm provenance, dependency-review, CodeQL, Semgrep, `verify-package-files` |
 | T8 | Path traversal in hooks/check | Read/write outside project | root resolution + under-root import resolve |
 | T9 | Runtime InMemory mistaken for durable | Data loss | durability stance docs + safety InMemory production detector |
 | T10 | Repair payload silently applied | Unexpected rewrites | repair never writes; host must re-inject; exit 2 on deny |
+| T11 | Prompt context is mistaken for enforcement | Verdict changes after compaction or missing skills | contract/tree inputs only; no-context eval compares hashes and adapter evidence |
+| T12 | Partial multi-file hook validation misses a cross-file edge | Invalid batch reaches disk | complete `apply_patch` events use atomic preflight; incomplete/bypassable paths rely on CI |
 
 ## Trust boundaries
 
 ```
-Claude/Grok host --PreToolUse--> arkgate-mcp (hard matched-write boundary)
+Claude/Grok host --PreToolUse--> arkgate-mcp (hard only for observed covered operation)
+Codex ApplyPatch  --PreToolUse--> arkgate-mcp (atomic feedback; bypassable/non-hard host profile)
 Any MCP host     --tool call----> arkgate-mcp (advisory validation)
 Human IDE        --disk/git-----> working tree
 working tree     --PR-----------> CI ark-check --strict-merge

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -26,6 +26,8 @@
     "./schema/ark.config.schema.json": "./schemas/ark.config.schema.json",
     "./schema/analysis-result": "./schemas/ark.analysis-result.schema.json",
     "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
+    "./schema/change-map": "./schemas/ark.change-map.schema.json",
+    "./schema/ark.change-map.schema.json": "./schemas/ark.change-map.schema.json",
     "./nestjs": {
       "types": "./compat/nestjs.d.ts",
       "import": "./compat/nestjs.js",
@@ -50,16 +52,14 @@
     "schemas",
     "docs/agent-guide.md",
     "docs/enthusiast",
-    "docs/demos",
+    "docs/demos/01-write-gate-self-correction.md",
+    "docs/demos/02-brownfield-baseline-adoption.md",
     "docs/ai-gates.md",
-    "docs/migrate-from-ark-runtime-kernel.md",
     "docs/typescript-support.md",
-    "docs/ark-check-example.json",
     "docs/assets",
     "docs/brownfield-adoption.md",
     "docs/configuration.md",
     "docs/package-surface.md",
-    "docs/production-hardening.md",
     "docs/threat-model.md",
     "tests/fixtures/ts-consumer",
     "templates",
@@ -105,6 +105,7 @@
     "eval:comparative": "node eval/comparative-run.mjs",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
     "eval:ai-velocity": "node eval/ai-velocity-run.mjs",
+    "eval:change-integrity": "node eval/change-integrity-run.mjs",
     "eval:adoption": "node eval/adoption-run.mjs",
     "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
     "bench:scale": "node scripts/ark-scale-bench.mjs",

package/schemas/ark.analysis-result.schema.json

@@ -11,7 +11,7 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": "1.0"
+      "const": "1.1"
     },
     "valid": {
       "type": "boolean"
@@ -83,6 +83,10 @@
                 "type": "boolean"
               }
             }
+          },
+          "nextAction": {
+            "type": "string",
+            "minLength": 1
           }
         }
       }

package/schemas/ark.change-map.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@3/schemas/ark.change-map.schema.json",
+  "title": "ArkGate architecture change map",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "files"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "minLength": 1,
+      "default": "https://unpkg.com/arkgate@3/schemas/ark.change-map.schema.json"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0",
+      "default": "1.0"
+    },
+    "files": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "operation",
+          "layer"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "operation": {
+            "type": "string",
+            "enum": [
+              "create",
+              "update",
+              "delete"
+            ]
+          },
+          "layer": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "default": [],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "from",
+          "to"
+        ],
+        "properties": {
+          "from": {
+            "type": "string",
+            "minLength": 1
+          },
+          "to": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  }
+}

package/server.json

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

package/templates/skills/ark-upgrade.md

@@ -123,11 +123,15 @@ npx arkgate-check --install-agent-gates --skills-only --force
    **Active host first.** Refresh skills for the host running this skill (e.g.
    `.grok/skills/`, `.claude/skills/`, `.cursor/commands/`). Repo-local copies for
    other detected hosts are fine to refresh in the same pass when cheap.
-   **Codex is deferred when you are not on Codex.** Prompts live in
-   `$CODEX_HOME/prompts` (`~/.codex/prompts`), not the repo. `ark upgrade` may
-   best-effort refresh that home when it exists; still list Codex under
-   **Deferred hosts** and do **not** chase MCP multi-project / stale home skills
-   until the user is on Codex (or asks). Fix command when needed:
+   **Codex is deferred when you are not on Codex.** Repo skills live in
+   `.agents/skills/<name>/SKILL.md`; optional home skills in
+   `$CODEX_HOME/skills/<name>/SKILL.md` (not legacy flat `$CODEX_HOME/prompts`).
+   When **on Codex**, refresh **both** repo catalog and home if doctor reports
+   missing/stale/legacy-prompts-only parity gaps. `ark upgrade` may best-effort
+   refresh home when it exists; still list Codex under **Deferred hosts** when
+   not on Codex and do **not** chase MCP multi-project / stale home skills until
+   the user is on Codex (or asks). Fix when needed:
+   `ark-check --install-agent-gates --skills-only --tools codex --force` and/or
    `ark-check --install-agent-gates --skills-only --codex-home --force`
    (and `--tools codex` / `--force` for primary MCP rebind). Exception: temp or
    `ark-upgrade` MCP `--root` paths — leave fail-closed rewrite to the CLI; do not

package/docs/ark-check-example.json

@@ -1,87 +0,0 @@
-{
-  "include": ["src"],
-  "layers": [
-    {
-      "name": "DomainModel",
-      "patterns": ["src/domain/**"],
-      "intentPrefixes": ["Domain."]
-    },
-    {
-      "name": "ApplicationOrchestration",
-      "patterns": ["src/application/**"],
-      "intentPrefixes": ["Application."]
-    },
-    {
-      "name": "PersistenceAdapters",
-      "patterns": ["src/adapters/persistence/**"],
-      "intentPrefixes": ["Adapter.Persistence."]
-    },
-    {
-      "name": "IntegrationAdapters",
-      "patterns": ["src/adapters/integration/**"],
-      "intentPrefixes": ["Adapter.Integration."]
-    },
-    {
-      "name": "WorkflowSagaEngine",
-      "patterns": ["src/workflows/**"],
-      "intentPrefixes": ["Workflow."]
-    },
-    {
-      "name": "BackgroundJobsScheduling",
-      "patterns": ["src/jobs/**"],
-      "intentPrefixes": ["Job."]
-    },
-    {
-      "name": "PresentationAdapters",
-      "patterns": ["src/presentation/**"],
-      "intentPrefixes": ["Presentation."]
-    },
-    {
-      "name": "ReportingReadModels",
-      "patterns": ["src/reporting/**"],
-      "intentPrefixes": ["Reporting."]
-    },
-    {
-      "name": "ExtensibilityMetadata",
-      "patterns": ["src/metadata/**"],
-      "intentPrefixes": ["Metadata."]
-    },
-    {
-      "name": "SecurityAuditObservability",
-      "patterns": ["src/security/**", "src/audit/**", "src/observability/**"],
-      "intentPrefixes": ["Security.", "Audit.", "Observability."]
-    },
-    {
-      "name": "Kernel",
-      "patterns": ["src/kernel/**"],
-      "intentPrefixes": ["Kernel."]
-    }
-  ],
-  "rules": [
-    {
-      "from": "DomainModel",
-      "to": "PersistenceAdapters",
-      "allowed": false
-    },
-    {
-      "from": "DomainModel",
-      "to": "IntegrationAdapters",
-      "allowed": false
-    },
-    {
-      "from": "DomainModel",
-      "to": "PresentationAdapters",
-      "allowed": false
-    },
-    {
-      "from": "PresentationAdapters",
-      "to": "PersistenceAdapters",
-      "allowed": false
-    },
-    {
-      "from": "ReportingReadModels",
-      "to": "PersistenceAdapters",
-      "allowed": false
-    }
-  ]
-}

package/docs/demos/03-copilot-autopilot.md

@@ -1,93 +0,0 @@
-# Demo: the co-pilot autopilot, end to end
-
-Take a project from "no guardrails" to "governed, cleaned up, and enforced" — the way a
-non-developer would, driving an agent. This is the Phase F→G→H→I flow (plan · guided setup ·
-loop · autopilot) in one sitting.
-
-## In one line
-
-`npx ark start` sets it up and shows a plan; **`/ark-autopilot`** (in your agent) carries the
-plan out — applying the safe fixes and proposing the rest, always validated by `ark-check`.
-
-## Prerequisites
-
-- Ark built or installed from this repository
-- An agent CLI (Claude, Cursor, Codex, Grok, …) for the `/ark-autopilot` and `/ark-loop` steps
-
-## Steps
-
-### 1. Guided setup (no architecture knowledge needed)
-
-```bash
-TMP=$(mktemp -d); cd "$TMP"
-git init -q                        # the loop works in a discardable worktree
-npm init -y >/dev/null
-npx ark start --yes
-```
-
-Ark describes the project's shape in plain language, writes `ark.config.json` + agent/CI gates,
-and prints the **plan** — how many fixes are _safe to auto-apply_ vs _need your decision_ —
-plus which **operating mode** applies: **suggest**, **adapt**, or **enforce**.
-
-On Nest/Next/express/library projects, init also merges framework filename conventions into
-the layer globs so day-one **governed%** is real (not a false-green empty contract).
-
-### 2. See the plan yourself (optional)
-
-```bash
-npx ark-check --plan            # human view (includes Governed: N%; pattern bets when design-weak)
-npx ark-check --plan --json     # { ok, plan: { goal, counts, steps, patternBets?, designSmells? } }
-npx ark-check --doctor --json   # designFitness / designSmells when residual is design-weak
-```
-
-Each **A** step is tagged `mechanical-safe` / `judgment` / `deferred` with a `confidence`,
-`rationale`, and often `remediationKind`. Auto-safe kinds: type-only type move, pure-type **file**
-relocate, `import type` of pure-type modules, and named type-export imports from mixed modules
-(`import-type-of-type-exports`). `goal.met` is true only when
-there are no active violations **and** governed coverage is meaningful — so a clean plan that
-checks almost nothing is not "done."
-
-When edges are clean but design residual remains, JSON also sets `goal.designWeak` and
-`patternBets[]` (each with `neverMechanicalSafe: true`). Those are **B** (Shape) bets — not
-auto-applied. Extraction cards: [brownfield-adoption.md](../brownfield-adoption.md) §6.
-
-### 3. Carry the plan out — the autopilot
-
-In your agent, run:
-
-```
-/ark-autopilot
-```
-
-It runs the whole flow (newbie tier): **explore first** (map + dual plan), hands off to
-`/ark-loop` for plan **A** `mechanical-safe` steps one at a time — **validating each with
-`ark-check` and rolling back any regression** — proposes each A `judgment` and each B
-pattern/Shape bet for a yes/no, and reports what was auto-applied vs proposed vs deferred.
-Nothing lands until you review the diff. Empty A with open B is **not** “architecture healthy
-finished.”
-
-Expert entry: skip the autopilot and use the pieces — `ark init` / `/ark-contract` to shape the
-contract, `ark-check --plan` for the work, `/ark-fix` for targeted fixes, `ark-check
---strict-config` as the gate. Same contract, same gates; same suggest/adapt/enforce modes.
-
-### 4. It stays clean
-
-The gates installed in step 1 keep enforcing the architecture from now on — in CI, and at write
-time if the MCP hook is wired. Verify:
-
-```bash
-npx ark-check --root . --config ark.config.json --strict-config
-```
-
-## What this proves
-
-- **plan + goal** (Phase F): `ark-check --plan` classifies the work and defines "done" (with
-  governed% honesty).
-- **guided setup** (Phase G): `ark start` — no preset or skill name required; modes
-  suggest / adapt / enforce.
-- **loop** (Phase H): `/ark-loop` — safe, reversible, validated apply.
-- **autopilot** (Phase I): `/ark-autopilot` — the whole thing, with newbie/expert entry styles.
-- **field honesty** (2.0): framework overlays + no false-green at 0% governed.
-
-The classifier's precision (only provably-safe changes are ever `mechanical-safe`) is guarded
-by the classifier corpus test in `tests/unit/static-check/arkCheck.test.ts`.