arkgate 4.8.16 → 4.8.18

package/docs/README.md

@@ -73,8 +73,8 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Prepared: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.16`; not published until `publish-npm` for `v4.8.16`).
-Current published: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11` on npm `latest`; does not close `K01`).
+Current published: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.18` on npm `latest`; does not close `K01`).
+Prior published: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11`).
 Prior published: [releases/4.8.10.md](releases/4.8.10.md) (`arkgate@4.8.10`).
 Prior published: [releases/4.8.9.md](releases/4.8.9.md) (`arkgate@4.8.9`).
 Prior: [releases/4.8.6.md](releases/4.8.6.md) · [releases/4.8.5.md](releases/4.8.5.md) · [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).

package/docs/agent-guide.md

@@ -55,6 +55,11 @@ feature work. Full `/ark-*` skills are **expert depth** and label residual **`[L
 npx ark-check --install-agent-gates --skills-only --force
 ```
 
+After the pin moves, a teammate who already has `arkgate` installed can keep a
+**stale** `.agents/skills` catalog (version stamp or content hash behind the
+package). Doctor and a plain `ark-check` warn. Primary next action is that
+same skills-only refresh — not `/ark-adopt` and not a full gate rewrite.
+
 ### Write-path honesty
 
 Claude/Grok/Antigravity/Cursor can hard-block listed PreToolUse / preToolUse ops when installed
@@ -282,7 +287,8 @@ npx ark-check --recommend --json
 `--recommend` does not require `ark.config.json`. It exits `0` and prints a progressive
 adoption plan: archetype id, preset, `confidence`, `runnerUp`, `why` (shape signals),
 structured positive/negative `evidence`, discovered `signals.packageUnits`,
-`adoptInOrder.phase1`, `firstCommand` (`ark start --apply --archetype …`), and `checkCommand`.
+`adoptInOrder.phase1`, `firstCommand` (`ark start --apply --archetype …` on a
+thin tree; `ark-check --init` on a mature tree), and `checkCommand`.
 When the top two shapes are close or projected governed coverage is below 90%, JSON sets
 `requiresConfirmation: true` and explains why in `confirmationReasons`.
 
@@ -891,6 +897,7 @@ Filter: **Contener · Guiar · Ordenar** — contain the write, guide the next s
 
 ```bash
 # Ark — expert skill pack (preferred when you also want gates)
+# Same command refreshes a stale catalog after the package moved (doctor warns).
 npx ark-check --install-agent-gates --skills-only --force
 
 # Ecosystem — from installed package or a git checkout
@@ -1347,7 +1354,7 @@ The server exposes these thirteen tools. Every tool accepts the additive
 | `ark_manifest` | No non-project args: return the machine-readable architecture contract with an authoritative binding after the identity handshake. |
 | `validate_code` | `{ source, layer?, filePath? }`: validate one snippet; infer the layer from `filePath` when possible; return an error result when invalid. |
 | `ark_check` | `{ strict?, baseline? }`: run the full project architecture check. `verdict` separates `identity`, `completeness`, `graph`, `coverage`, `gates`, and `overallOk`; no individual green fact substitutes for the combined verdict. |
-| `ark_policy_delta` | `{ baseConfig, candidateConfig?, acknowledgement? }`: classify a complete contract transition; never edits the contract. |
+| `ark_policy_delta` | `{ baseConfig, candidateConfig?, acknowledgement? }`: classify a complete contract transition; never edits the contract. Weakening / new layer / new allow edge needs `adrPath` on the acknowledgement. |
 | `ark_coverage` | No args: report per-layer counts, every unclassified file, unmatched layers, and missing rule edges. |
 | `ark_place` | `{ filePath?, description? }`: resolve or propose a governed home and return its import/global constraints. |
 | `ark_prepare_write` | `{ source, filePath?, description?, layer? }`: compose placement and snippet validation, with hashes and a mechanical-safe patch when available. |

package/docs/ai-gates.md

@@ -512,6 +512,10 @@ lag the installed package. Temp/upgrade `--root` never mutates default user home
 sessions treat a stale Claude home as urgent because Cursor loads `~/.claude/skills`.
 Antigravity sessions treat a stale `~/.gemini/config/skills` catalog as urgent.
 
+Project `.agents/skills` can also lag after a teammate `npm install`s a new pin without
+`ark upgrade`. Doctor and `ark-check` warn (content identity + `arkVersion`). Next action
+is skills-only refresh — not a full re-adopt.
+
 ```bash
 npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
 ```

package/docs/configuration.md

@@ -457,12 +457,15 @@ JSON artifact passed with `--policy-ack`:
   "basePolicyHash": "fnv1a-...",
   "candidatePolicyHash": "fnv1a-...",
   "findingIds": ["weakening:$.dynamicImportAllowlist:added"],
-  "reason": "Temporary loader while the static registry is migrated."
+  "reason": "Temporary loader while the static registry is migrated.",
+  "adrPath": "docs/adr/0001-temporary-loader.md"
 }
 ```
 
-The acknowledgement must list every blocking finding exactly. It is not a permanent allowlist:
-changing either contract changes its hash and invalidates the acknowledgement.
+The acknowledgement must list every blocking finding exactly and name a short
+decision note as `adrPath` (under `docs/adr/` or `docs/decisions/`). A reason
+alone is not enough. It is not a permanent allowlist: changing either contract
+changes its hash and invalidates the acknowledgement.
 
 ## Team parliament (law vs feature)
 

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

@@ -52,7 +52,9 @@ unclassified source files therefore remain red.
 If gates are required and the tree has no short decision note yet (`docs/adr/` or
 `docs/decisions/`), `--require-gates` and doctor point at that path. Soft hint —
 not a fail, and silent when `--require-gates` is off. Not every change needs a
-note; use one when you loosen a rule or add a real gate.
+note; use one when you loosen a rule or add a real gate. When `--policy-ack`
+is required (weaken, new layer, or new allow edge), put that note's path on
+the acknowledgement as `adrPath`.
 
 Doctor JSON includes `writePath.mode` plus `enforcementLadder`: support, installation, observed
 evidence, covered operations, bypassability, and CI honesty. MCP registration stays advisory.

package/docs/enthusiast/how-to-pick-shape.md

@@ -26,7 +26,7 @@ Run **`/ark-adopt`** on a greenfield or early-adoption repo (leftover `/ark-arch
 | `adoptInOrder.phase1` | Folders to create first |
 | `analogy` | Plain-language mental model |
 | `antiPatterns` | What Ark will block later |
-| `firstCommand` | Usually `ark start --apply --archetype <id>` |
+| `firstCommand` | Thin tree: `ark start --apply --archetype <id>`. Mature: `ark-check --init` |
 
 Framework names appear only as secondary `toolHints` in JSON — never as the archetype label.
 

package/docs/package-surface.md

@@ -75,7 +75,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
-| **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
+| **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. A new layer or new allow edge is `judgment-required`. On the CLI/MCP policy-ack plane, `adrPath` must name a short note under `docs/adr/` or `docs/decisions/` (`policyDelta.adrNote`). Domain hash match stays I/O-free. |
 | **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--local` / `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources plus their import closure. `--local` (or `ARK_CHECK_LOCAL=1`) is the same cheap path and stays per `--root`; it cannot combine with `--strict-merge`. Check JSON may add `local`, `scope: "changed"`, `analysisRoot`. `stewards`, `layers[].description`, `layers[].trustBoundary`, and `layers[].owners` are excluded from policy hash. `requireLayerOwners` stays in the hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; 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. |

package/docs/use.md

@@ -34,9 +34,12 @@ npx --package=arkgate arkgate-check --doctor --all  # full details
 `arkgate-check` is a command in the `arkgate` package, not its own npm package. After a local install, `npx arkgate-check --doctor` also works.
 
 `start --apply` refuses when projected governed coverage is below 50% or
-shape confidence is weak (below 0.6 with coverage under 80%). That lock is
-deliberate. Lock the shape with `--archetype <id>`, `--preset <name>`, or
-`--force`, or inspect ranked shapes with `npx arkgate-check --recommend`.
+shape confidence is weak (below 0.6 with coverage under 80%), or when the
+planned write is too big for compact start (more than 8 gate files or 32 KB).
+That lock is deliberate. Coverage/shape: lock with `--archetype <id>`,
+`--preset <name>`, or `--force`. Size: `--force` does not unlock. Next:
+`npx arkgate-check --init`. Or inspect ranked shapes with
+`npx arkgate-check --recommend`.
 
 Then keep working with your agent. Stuck? Run `--doctor` and do action **#1**. Compact first; `--all` for details.
 
@@ -151,7 +154,9 @@ That is **Shape** work (plan B) — suggested, never auto-applied as silent magi
 `--contract-session` (stewards own loosen / baseline-grow). Checkout honesty:
 `npx arkgate status --vs origin/dev`.
 
-Install skills only when you want that guided path:
+Install skills only when you want that guided path. After a package bump, a
+teammate who already has Ark installed can keep **old skills**. Doctor warns;
+refresh the catalog only — do not re-adopt or rewrite `ark.config.json`:
 
 ```bash
 npx arkgate-check --install-agent-gates --skills-only --force

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.16",
+  "version": "4.8.18",
   "description": "When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

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

package/templates/agent-skills/README.md

@@ -9,7 +9,7 @@ closed `/ark-*` catalog shipped as flat templates for Ark install.
 **Closed catalog** (`ARK_SKILL_NAMES`) — first-class doors plus one-release
 redirect stubs. Add a name only with a live ROADMAP item.
 
-Package version when last generated context: **arkgate@4.8.16**
+Package version when last generated context: **arkgate@4.8.18**
 Schema: agent-skills package contract `1.0`
 
 ## Skills (closed catalog)

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

@@ -168,8 +168,10 @@ When gates are required (`--require-gates` / `--strict-merge` / required merge
 status) and there is no short decision-note home yet, doctor may ask for one
 under `docs/adr/` or `docs/decisions/`. Write a note when you loosen a rule or
 add a real gate — not on every file. Absence is silent unless that demand is
-on. The hint does not fail the check. Do **not** invent `/ark-adr`. Policy
-weaken still uses `--policy-ack`; this is only a place to write the why.
+on. The home hint does not fail the check. Do **not** invent `/ark-adr`.
+When `--policy-ack` is required (weaken, new layer, or new allow edge), put
+that note's path on the acknowledgement as `adrPath`. A free-floating reason
+is not enough on the policy-ack plane.
 
 ## States and transitions (process)
 
@@ -300,9 +302,10 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 - **Brownfield:** this skill — match config to reality; do not force a starter preset.
 - **Deep map only:** `/ark-explore`.
 - **Default path:** `ark start` → **`/ark-adopt`** → `/ark-place` / `/ark-autopilot`.
-  `start --apply` may refuse (coverage below 50% or weak shape) — that lock is
-  deliberate. Lock the shape with `--archetype`, `--preset`, or `--force`, or
-  inspect ranked shapes with `ark-check --recommend`.
+  `start --apply` may refuse (coverage below 50%, weak shape, or too big for
+  compact start) — that lock is deliberate. Coverage/shape: `--archetype`,
+  `--preset`, or `--force`. Size: `--force` does not unlock; next
+  `arkgate-check --init`. Or inspect ranked shapes with `ark-check --recommend`.
 
 ## Anti-wrapper rule (mandatory)
 

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

@@ -198,6 +198,9 @@ when residual signals remain.
    unverified/non-authoritative.
 2. **If asked generally** ("explain the architecture"), produce a guided tour:
    - Operating mode + governed% (honest: low coverage means green checks almost nothing).
+   - Dual-match: exact Domain file listings under another layer glob are
+     intentional. Trust doctor #1. Glob-repair #1 names this tree's overlapping
+     roots, not a canned `api/**`.
    - Each major layer: name, purpose, one real file from this repo, file count if known.
    - Dependency direction in one short diagram (ASCII is fine).
    - Enforcement points that are actually on: write gate, CI, ESLint, baseline.

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

@@ -24,7 +24,9 @@ one bounded decision needs 2–3 enforceable options.
 - Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
 - When `--require-gates` / adopted-strict is on and doctor JSON has `adrPresence`,
   the next step is a short note under `docs/adr/` (or `docs/decisions/`). Soft.
-  Not every change. Off when require-gates is off. No `/ark-adr`.
+  Not every change. Off when require-gates is off. No `/ark-adr`. When
+  `policyDelta` needs `--policy-ack` (weaken, new layer, or new allow edge),
+  the ack must name that note as `adrPath` — a reason alone is not enough.
 - When doctor JSON has `statesTransitions` or `statusTransitionCatalog`, the
   next step is a short states → transitions table (or one link) on the domain
   doc already in play. Use catalog names when present. Soft. Silent when that

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

@@ -98,6 +98,7 @@ Never invent gate verdicts from these suggestions. Missing residual is honest em
 | 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`, `~/.grok/skills`, or `~/.gemini/config/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. Antigravity’s global catalog still refreshes when the project `.agents/skills` already exists. |
+| Package moved; teammate still has old `/ark-*` skills | Doctor and `ark-check` warn. Refresh **skills only** (no re-adopt, no layers rewrite): `--install-agent-gates --skills-only --force`. |
 | 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-adopt.md

@@ -168,8 +168,10 @@ When gates are required (`--require-gates` / `--strict-merge` / required merge
 status) and there is no short decision-note home yet, doctor may ask for one
 under `docs/adr/` or `docs/decisions/`. Write a note when you loosen a rule or
 add a real gate — not on every file. Absence is silent unless that demand is
-on. The hint does not fail the check. Do **not** invent `/ark-adr`. Policy
-weaken still uses `--policy-ack`; this is only a place to write the why.
+on. The home hint does not fail the check. Do **not** invent `/ark-adr`.
+When `--policy-ack` is required (weaken, new layer, or new allow edge), put
+that note's path on the acknowledgement as `adrPath`. A free-floating reason
+is not enough on the policy-ack plane.
 
 ## States and transitions (process)
 
@@ -300,9 +302,10 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 - **Brownfield:** this skill — match config to reality; do not force a starter preset.
 - **Deep map only:** `/ark-explore`.
 - **Default path:** `ark start` → **`/ark-adopt`** → `/ark-place` / `/ark-autopilot`.
-  `start --apply` may refuse (coverage below 50% or weak shape) — that lock is
-  deliberate. Lock the shape with `--archetype`, `--preset`, or `--force`, or
-  inspect ranked shapes with `ark-check --recommend`.
+  `start --apply` may refuse (coverage below 50%, weak shape, or too big for
+  compact start) — that lock is deliberate. Coverage/shape: `--archetype`,
+  `--preset`, or `--force`. Size: `--force` does not unlock; next
+  `arkgate-check --init`. Or inspect ranked shapes with `ark-check --recommend`.
 
 ## Anti-wrapper rule (mandatory)
 

package/templates/skills/ark-explain.md

@@ -198,6 +198,9 @@ when residual signals remain.
    unverified/non-authoritative.
 2. **If asked generally** ("explain the architecture"), produce a guided tour:
    - Operating mode + governed% (honest: low coverage means green checks almost nothing).
+   - Dual-match: exact Domain file listings under another layer glob are
+     intentional. Trust doctor #1. Glob-repair #1 names this tree's overlapping
+     roots, not a canned `api/**`.
    - Each major layer: name, purpose, one real file from this repo, file count if known.
    - Dependency direction in one short diagram (ASCII is fine).
    - Enforcement points that are actually on: write gate, CI, ESLint, baseline.

package/templates/skills/ark-explore.md

@@ -24,7 +24,9 @@ one bounded decision needs 2–3 enforceable options.
 - Doctor #1: if ENFORCE + empty plan A and gates are already installed → **Shape** (`/ark-explore` then `/ark-autopilot`). Do not say install-agent-gates.
 - When `--require-gates` / adopted-strict is on and doctor JSON has `adrPresence`,
   the next step is a short note under `docs/adr/` (or `docs/decisions/`). Soft.
-  Not every change. Off when require-gates is off. No `/ark-adr`.
+  Not every change. Off when require-gates is off. No `/ark-adr`. When
+  `policyDelta` needs `--policy-ack` (weaken, new layer, or new allow edge),
+  the ack must name that note as `adrPath` — a reason alone is not enough.
 - When doctor JSON has `statesTransitions` or `statusTransitionCatalog`, the
   next step is a short states → transitions table (or one link) on the domain
   doc already in play. Use catalog names when present. Soft. Silent when that

package/templates/skills/ark-upgrade.md

@@ -98,6 +98,7 @@ Never invent gate verdicts from these suggestions. Missing residual is honest em
 | 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`, `~/.grok/skills`, or `~/.gemini/config/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. Antigravity’s global catalog still refreshes when the project `.agents/skills` already exists. |
+| Package moved; teammate still has old `/ark-*` skills | Doctor and `ark-check` warn. Refresh **skills only** (no re-adopt, no layers rewrite): `--install-agent-gates --skills-only --force`. |
 | 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),