arkgate 4.8.16 → 4.8.17

package/docs/README.md

@@ -73,7 +73,7 @@ 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`).
+Prepared: [CHANGELOG](../CHANGELOG.md) (`arkgate@4.8.17`; not published until `publish-npm` for `v4.8.17`).
 Current published: [releases/4.8.11.md](releases/4.8.11.md) (`arkgate@4.8.11` on npm `latest`; does not close `K01`).
 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`).

package/docs/agent-guide.md

@@ -1347,7 +1347,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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.8.16",
+  "version": "4.8.17",
   "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.17",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "4.8.16",
+      "version": "4.8.17",
       "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.17**
 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)
 

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/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)
 

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