arkgate 4.8.16 → 4.8.17

package/CHANGELOG.md

@@ -96,6 +96,32 @@ in the immutable pre-2.0 archive linked below.
   Existing configs keep whatever URL they already have. Editor completion
   matches the 4.x line you just installed.
 
+## 4.8.17 — 2026-09-17
+
+**Patch** over **4.8.16**. Daily accumulate of the two ships that landed
+after 4.8.16 published: ADR path on policy weaken / new layer edge
+([#264](https://github.com/pedroknigge/arkgate/pull/264)) and the
+policy-delta-ack-match confidence retarget
+([#265](https://github.com/pedroknigge/arkgate/pull/265)).
+**Write. Check. Ship.** **No required config migration.** No
+`schemaVersion` bump. Does not close `K01` / `Z09`. This mother
+`ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: prepared** (npm `latest` remains **4.8.16** until Actions `publish-npm`
+runs with `tag=v4.8.17` and `dry_run=false`).
+
+### Added
+- A weaken, new layer, or new allow edge must name a short ADR /
+  decision-note path on `--policy-ack` (`adrPath`). A free-floating
+  reason is not enough
+  ([#264](https://github.com/pedroknigge/arkgate/pull/264)).
+
+### Fixed
+- Retarget `policy-delta-ack-match` onto the current
+  `policyDeltaAcknowledgementMatches` body so the 90% confidence
+  floor still holds after #264
+  ([#265](https://github.com/pedroknigge/arkgate/pull/265)).
+
 ## 4.8.16 — 2026-09-16
 
 **Patch** over **4.8.15**. Daily accumulate of the five ships that landed

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.16** is prepared on this tree; npm `latest` remains **4.8.15** until `publish-npm` for `v4.8.16`.
+> **ArkGate 4.8.17** is prepared on this tree; npm `latest` remains **4.8.16** until `publish-npm` for `v4.8.17`.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
@@ -47,7 +47,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops rewriting a big product choice — like the billing plan —
 > as if it were a seat count. Change those choices through a valve, not a generic update.
 > `@arkgate/runtime` is deprecated.
-> [4.8.16 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.17 prepared](CHANGELOG.md) · [4.8.11 published](docs/releases/4.8.11.md) · [4.8.10](docs/releases/4.8.10.md) · [4.8.9](docs/releases/4.8.9.md) · [4.8.8](docs/releases/4.8.8.md) · [4.8.7](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -344,7 +344,7 @@ Compact starters leave the extra off. Details: [ArkOrder](docs/arkorder.md).
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Prepared (4.8.16; not published) | [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.17; not published) | [CHANGELOG](CHANGELOG.md) |
 | Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.10) | [docs/releases/4.8.10.md](docs/releases/4.8.10.md) · [CHANGELOG](CHANGELOG.md) |
 | Prior published (4.8.9) | [docs/releases/4.8.9.md](docs/releases/4.8.9.md) · [CHANGELOG](CHANGELOG.md) |

package/bin/ark-check-runtime.mjs

@@ -1959,9 +1959,13 @@ async function main() {
         );
         console.error(`  Next: ${finding.nextAction}`);
       }
+      if (policyDelta.adrNote?.missing) {
+        console.error(policyDelta.adrNote.ask);
+        console.error(`Next: ${policyDelta.adrNote.nextAction}`);
+      }
       console.error(
         `Policy transition blocked (${policyDelta.basePolicyHash} → ${policyDelta.candidatePolicyHash}). ` +
-          'Provide --policy-ack with the exact hashes, finding ids, and a non-empty reason.'
+          'Provide --policy-ack with the exact hashes, finding ids, a non-empty reason, and adrPath to a short note under docs/adr/.'
       );
     }
     if (designCheck.failureText()) console.error(designCheck.failureText());

package/bin/ark-mcp-runtime.mjs

@@ -107,6 +107,7 @@ import {
   evaluateWriteDesignDelta,
   formatDesignDeltaBlock,
 } from './lib/design-delta.mjs';
+import { attachPolicyAdrNote } from './lib/adr-path.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 const arkMcpLauncher = fileURLToPath(new URL('./ark-mcp.mjs', import.meta.url));
@@ -1995,7 +1996,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'judgment-required, or weakening. Pass the previous baseConfig and optional ' +
         'candidateConfig (defaults to this project contract). Weakening and judgment-required ' +
         'results set isError unless acknowledgement exactly matches both policy hashes and all ' +
-        'blocking finding ids. Read-only; never edits the contract.',
+        'blocking finding ids, and adrPath names a short note under docs/adr/ or docs/decisions/. ' +
+        'Read-only; never edits the contract.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -2010,7 +2012,8 @@ export async function runArkMcp({ hookInput } = {}) {
           acknowledgement: {
             type: 'object',
             description:
-              'Optional schemaVersion/basePolicyHash/candidatePolicyHash/findingIds/reason object.',
+              'Optional schemaVersion/basePolicyHash/candidatePolicyHash/findingIds/reason object. ' +
+              'When the transition needs an acknowledgement, adrPath must name a short note under docs/adr/ or docs/decisions/.',
           },
         },
         required: ['baseConfig'],
@@ -2468,11 +2471,15 @@ export async function runArkMcp({ hookInput } = {}) {
       };
     }
     try {
-      const result = ark.analyzePolicyDelta({
-        baseConfig,
-        candidateConfig: params?.arguments?.candidateConfig ?? config,
-        acknowledgement: params?.arguments?.acknowledgement,
-      });
+      const acknowledgement = params?.arguments?.acknowledgement;
+      const result = attachPolicyAdrNote(
+        ark.analyzePolicyDelta({
+          baseConfig,
+          candidateConfig: params?.arguments?.candidateConfig ?? config,
+          acknowledgement,
+        }),
+        { root: args.root, acknowledgement, failClosed: true }
+      );
       return {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
         structuredContent: result,

package/bin/lib/adr-path.mjs

@@ -0,0 +1,116 @@
+/**
+ * Policy-ack ADR path tooth (AP02). Tooling I/O on the existing
+ * --policy-ack / --strict-merge plane. Doctor does not import this file.
+ */
+
+import path from 'node:path';
+import { ADR_PRESENCE_HOMES, isNonEmptyMarkdownFile } from './adr-presence.mjs';
+
+export const ADR_PATH_ASK =
+  'This change loosens a rule or adds a layer edge, but the acknowledgement has no decision-note path.';
+
+export const ADR_PATH_NEXT =
+  'Add a short note under docs/adr/ (or docs/decisions/) and put that file path in --policy-ack as adrPath.';
+
+export const ADR_PATH_MISSING_FILE_ASK =
+  'The acknowledgement names a decision note that is missing or empty.';
+
+export const ADR_PATH_MISSING_FILE_NEXT =
+  'Write that note (or fix adrPath) under docs/adr/ or docs/decisions/, then run ArkGate again.';
+
+/**
+ * Relative path under a conventional decision-note home. No I/O.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function canonicalizeAdrPath(value) {
+  if (typeof value !== 'string') return null;
+  const rel = value.trim().replace(/\\/g, '/');
+  if (!rel || rel.startsWith('/') || /^[A-Za-z]:\//.test(rel) || rel.includes('\0')) return null;
+  const parts = [];
+  for (const segment of rel.split('/')) {
+    if (!segment || segment === '.') continue;
+    if (segment === '..') return null;
+    parts.push(segment);
+  }
+  return parts.join('/') || null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isConventionalAdrPath(value) {
+  const rel = canonicalizeAdrPath(value);
+  if (!rel) return false;
+  for (const home of ADR_PRESENCE_HOMES) {
+    if (home.endsWith('.md')) {
+      if (rel === home) return true;
+      continue;
+    }
+    if (rel.startsWith(`${home}/`) && rel.toLowerCase().endsWith('.md') && rel.length > home.length + 4) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Conventional path that already has a non-empty markdown file.
+ *
+ * @param {string} root
+ * @param {unknown} adrPath
+ * @returns {string | null}
+ */
+export function resolveAdrNotePath(root, adrPath) {
+  const rel = isConventionalAdrPath(adrPath) ? canonicalizeAdrPath(adrPath) : null;
+  if (!rel || typeof root !== 'string' || root.length === 0) return null;
+  return isNonEmptyMarkdownFile(path.join(root, rel)) ? rel : null;
+}
+
+/**
+ * Residual when a weaken / new-edge needs a tied note path.
+ * `needed` is policyDelta.requiresAcknowledgement. Off → null.
+ *
+ * @param {{ root?: string, needed?: boolean, adrPath?: unknown }} [input]
+ * @returns {{ missing: true, ask: string, nextAction: string, path?: string } | null}
+ */
+export function collectAdrPathResidual(input = {}) {
+  if (input.needed !== true) return null;
+  const rel = canonicalizeAdrPath(input.adrPath);
+  if (!rel) {
+    return { missing: true, ask: ADR_PATH_ASK, nextAction: ADR_PATH_NEXT };
+  }
+  if (resolveAdrNotePath(input.root ?? '', input.adrPath)) return null;
+  return {
+    missing: true,
+    path: rel,
+    ask: isConventionalAdrPath(input.adrPath) ? ADR_PATH_MISSING_FILE_ASK : ADR_PATH_ASK,
+    nextAction: isConventionalAdrPath(input.adrPath) ? ADR_PATH_MISSING_FILE_NEXT : ADR_PATH_NEXT,
+  };
+}
+
+/**
+ * Attach `adrNote` to a policy-delta result. Flips `valid` only when
+ * `failClosed` (existing policy-ack / --strict-merge plane) and the path
+ * is missing. Domain hash match stays I/O-free.
+ *
+ * @param {object | undefined} result
+ * @param {{ root?: string, acknowledgement?: { adrPath?: unknown }, failClosed?: boolean }} [input]
+ */
+export function attachPolicyAdrNote(result, input = {}) {
+  if (!result || result.requiresAcknowledgement !== true) return result;
+  const residual = collectAdrPathResidual({
+    root: input.root,
+    needed: true,
+    adrPath: input.acknowledgement?.adrPath,
+  });
+  const adrNote = residual
+    ? residual
+    : { missing: false, path: canonicalizeAdrPath(input.acknowledgement?.adrPath) };
+  if (!residual || input.failClosed !== true) {
+    return { ...result, adrNote };
+  }
+  return { ...result, adrNote, valid: false };
+}

package/bin/lib/adr-presence.mjs

@@ -1,7 +1,8 @@
 /**
  * Soft ADR / decision-note presence when gates are demanded.
  * Tooling I/O. Never a gate fail. Absence is silent unless require-gates
- * or adopted-strict (required-merge) is on.
+ * or adopted-strict (required-merge) is on. The policy-ack path tooth lives
+ * in adr-path.mjs so doctor does not parse it.
  */
 
 import fs from 'node:fs';
@@ -23,7 +24,7 @@ export const ADR_PRESENCE_ASK =
 export const ADR_PRESENCE_NEXT =
   'Add a short note under docs/adr/ (or docs/decisions/) when you loosen a rule or add a real gate. Not every change.';
 
-function isNonEmptyMarkdownFile(file) {
+export function isNonEmptyMarkdownFile(file) {
   if (!fs.existsSync(file) || !fs.statSync(file).isFile()) return false;
   try {
     return fs.readFileSync(file, 'utf8').trim().length > 0;