arkgate 4.8.15 → 4.8.17

package/CHANGELOG.md

@@ -96,6 +96,71 @@ 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
+after 4.8.15 published: invariant tests path
+([#255](https://github.com/pedroknigge/arkgate/pull/255)), doctor green
+cites ([#256](https://github.com/pedroknigge/arkgate/pull/256)),
+coverageRoots when enforced
+([#257](https://github.com/pedroknigge/arkgate/pull/257)),
+`start --apply` install honesty
+([#259](https://github.com/pedroknigge/arkgate/pull/259)), and prototype
+shortcuts ([#260](https://github.com/pedroknigge/arkgate/pull/260)).
+**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.15** until Actions `publish-npm`
+runs with `tag=v4.8.16` and `dry_run=false`).
+
+### Added
+- Adopted trees with domain invariants must name a real tests path, so
+  coverage cannot certify a test no runner runs
+  ([#255](https://github.com/pedroknigge/arkgate/pull/255)).
+- Doctor green / healthy lines now cite a file, config key, or test — an
+  uncited line cannot look healthy
+  ([#256](https://github.com/pedroknigge/arkgate/pull/256)).
+- When a domain invariant is enforced, `coverage.coverageRoots` is
+  required. Test globs alone are not enough
+  ([#257](https://github.com/pedroknigge/arkgate/pull/257)).
+- Soft residual when SQLite, a JSON-file store, or admin literals stand
+  in for Persistence or Domain
+  ([#260](https://github.com/pedroknigge/arkgate/pull/260)).
+
+### Changed
+- `start --apply` fails closed if the package install fails, and names
+  the exact command to recover
+  ([#259](https://github.com/pedroknigge/arkgate/pull/259)).
+- Pack ceilings remeasured on the IT01 CI pack (run 34848276803).
+  ≥10% headroom. No new product surface.
+
 ## 4.8.15 — 2026-09-13
 
 **Patch** over **4.8.14**. Pre-adoption ship bar: opt-in `--local` /

package/README.md

@@ -39,7 +39,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.15** is prepared on this tree; npm `latest` remains **4.8.14** until `publish-npm` for `v4.8.15`.
+> **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.15 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)
 
 ---
 
@@ -69,10 +69,12 @@ Full map: **[docs/README.md](docs/README.md)**
 npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
 npx arkgate start --apply         # compact config + host router + CI plan
-npx arkgate-check --doctor        # status — one next step
-npx arkgate-check --doctor --all  # full details
+npx --package=arkgate arkgate-check --doctor        # status — one next step
+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
@@ -342,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.15; 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/ark-shared.mjs

@@ -22,6 +22,7 @@ import {
   normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
+  arkPackageRecoveryCommand,
 } from './lib/package-manager.mjs';
 
 /**
@@ -674,6 +675,7 @@ export {
   normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
+  arkPackageRecoveryCommand,
 };
 
 // FX01–FX02: registry-aware skip lives in upgrade-package-decision (injectable probe).

package/bin/ark.mjs

@@ -22,7 +22,12 @@ import {
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
-import { applyStartPreview, planStart, renderStartPreview } from './lib/start-preview.mjs';
+import {
+  applyStartPreview,
+  formatStartPackageInstallFailure,
+  planStart,
+  renderStartPreview,
+} from './lib/start-preview.mjs';
 import { runUpgradeCommand } from './lib/upgrade-command.mjs';
 import { detectActiveAgentHost } from './lib/skill-install.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
@@ -489,7 +494,8 @@ async function start(args) {
       const skip = shouldSkipArkgateInstall(args.root, cliVersion());
       if (!skip.skip) {
         const [command, commandArgs] = packageInstallArgv(args.root, `^${cliVersion()}`);
-        if (!args.json) console.log(`Installing package: ${command} ${commandArgs.join(' ')}`);
+        const installCommand = `${command} ${commandArgs.join(' ')}`;
+        if (!args.json) console.log(`Installing package: ${installCommand}`);
         // Keep stdout clean for --json consumers (package managers are chatty on stdout).
         const status = args.json
           ? (spawnSync(command, commandArgs, {
@@ -498,10 +504,9 @@ async function start(args) {
               encoding: 'utf8',
             }).status ?? 1)
           : runCommand(command, commandArgs, args.root);
-        if (status !== 0 && !args.json) {
-          console.log(
-            `Package manager exited ${status}. package.json is pinned; run the install command when online.`
-          );
+        if (status !== 0) {
+          console.error(formatStartPackageInstallFailure({ exitStatus: status, installCommand }));
+          return status;
         }
       }
     }
@@ -568,8 +573,12 @@ async function start(args) {
       if (pinned.changed) {
         console.log(`  Pinned arkgate@${pinned.version} in package.json devDependencies.`);
         if (installStatus !== null && installStatus !== 0) {
-          console.log(
-            `  Package manager install exited ${installStatus} — package.json is still pinned; run install when online.`
+          const [command, commandArgs] = packageInstallArgv(root, pinned.version);
+          console.error(
+            formatStartPackageInstallFailure({
+              exitStatus: installStatus,
+              installCommand: `${command} ${commandArgs.join(' ')}`,
+            })
           );
         }
       } else if (pinned.reason === 'already-present') {

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;