arkgate 4.8.16 → 4.8.18

package/CHANGELOG.md

@@ -96,6 +96,87 @@ 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.18 — 2026-09-18
+
+**Patch** over **4.8.17**. Daily accumulate (2026-09-18 ART) of the six
+ships that landed after 4.8.17 published: monorepo DomainModel globs
+([#269](https://github.com/pedroknigge/arkgate/pull/269)), packed
+README latest-truth
+([#270](https://github.com/pedroknigge/arkgate/issues/270) /
+[#272](https://github.com/pedroknigge/arkgate/pull/272)), deep pstack
+audit ([#273](https://github.com/pedroknigge/arkgate/pull/273)), doctor
+#1 dual-match honesty
+([#275](https://github.com/pedroknigge/arkgate/pull/275)), compact-start
+size refuse ([#274](https://github.com/pedroknigge/arkgate/pull/274)),
+and stale-skill Guiar
+([#278](https://github.com/pedroknigge/arkgate/pull/278)).
+**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: published** (npm `latest` is **4.8.18**).
+
+### Added
+- Doctor and `ark-check` warn when installed `/ark-*` skills are behind
+  this package (canonical `.agents/skills` included, even with no host
+  marker dir). Primary next action is skills-only refresh
+  (`--install-agent-gates --skills-only --force`) — not a full re-adopt
+  ([#278](https://github.com/pedroknigge/arkgate/pull/278)).
+- Maintainer pstack audit report (core + add-ons) at
+  `docs/audit/2026-09-17-pstack-deep-product-audit.md`
+  ([#273](https://github.com/pedroknigge/arkgate/pull/273)). Report
+  only. No product code.
+
+### Fixed
+- Monorepo `arkgate start` no longer puts whole-app roots (`api/**`,
+  `client/**`) on DomainModel next to the finer globs. Domain stays
+  package-scoped (`packages/*/src/**`, `**/domain/**`). When dual-match
+  is huge, doctor #1 is “fix overlapping layer globs” with one example,
+  not only “make CI required”
+  ([#269](https://github.com/pedroknigge/arkgate/pull/269)).
+- Packed README / docs hub no longer pin npm `latest` to an older
+  version than this tarball. `check:package-files` and the
+  packed-artifact path refuse that waiting-room pin
+  ([#270](https://github.com/pedroknigge/arkgate/issues/270) /
+  [#272](https://github.com/pedroknigge/arkgate/pull/272)).
+- Doctor #1 no longer treats intentional Domain+Tooling file+glob
+  dual-lists as a glob leak, and overlapping-glob copy names the tree's
+  real roots instead of a canned `api/**` sermon
+  ([#275](https://github.com/pedroknigge/arkgate/pull/275)).
+- `doctorResidentWarm` CI ceiling is 800ms after docs-only main already
+  missed 680ms (p95 697–707ms). Same miss as #270 / the audit tip
+  ([#275](https://github.com/pedroknigge/arkgate/pull/275)).
+- Cold `arkgate start --apply` now refuses a plan that is too big for
+  compact start **before** any “writing…” copy, names the file/byte
+  numbers, and prints one next action (`arkgate-check --init`).
+  `--force` does not unlock the size lock
+  ([#274](https://github.com/pedroknigge/arkgate/pull/274)).
+
+## 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: published** (npm `latest` is **4.8.17**).
+
+### 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.18** is on npm `latest`.
 > 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.18](CHANGELOG.md) · [4.8.11](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)
 
 ---
 
@@ -76,9 +76,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`.
 
 That is the product. Stuck? Run status (`--doctor`) and do action **#1**.
 
@@ -344,8 +347,8 @@ 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) |
-| Current published (4.8.11 on npm `latest`) | [docs/releases/4.8.11.md](docs/releases/4.8.11.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.18 on npm `latest`) | [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.11) | [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) |
 | Prior published (4.8.7) | [docs/releases/4.8.7.md](docs/releases/4.8.7.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

@@ -1740,7 +1740,12 @@ export function buildArchitectureRecommendation(root, options = {}) {
     // a thin slice and can mis-flag framework internals, so steer these to the adoption flow.
     mature: signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD,
     initCommand: `${arkCommand(root, 'ark', `init --archetype ${result.archetype} --yes`)}`,
-    firstCommand: `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
+    // Greenfield: compact start. Mature: `--init` writes the rules file without the
+    // compact-start size lock that cold `start --apply` can hit on large trees.
+    firstCommand:
+      signals.sourceFileCount >= MATURE_REPO_FILE_THRESHOLD
+        ? arkCommand(root, 'ark-check', '--init')
+        : `${arkCommand(root, 'ark', `start --apply --archetype ${result.archetype}`)}`,
     adoptCommand: arkCommand(root, 'ark-check', '--recommend --write-plan'),
     recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
     checkCommand: arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config'),
@@ -1817,10 +1822,11 @@ export function resolveStartInitPreset(root, rec = {}, archetype = rec.archetype
   return preset ?? null;
 }
 
-/** One-minute / preview footer when the coverage·confidence gate may refuse apply. */
+/** One-minute / preview footer when apply may refuse (coverage·shape or compact size). */
 export const START_APPLY_REFUSE_FOOTER = [
-  'If apply refuses (coverage below 50% or weak shape), that lock is deliberate.',
-  'Lock the shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'If apply refuses (coverage below 50%, weak shape, or too big for compact start), that lock is deliberate.',
+  'Coverage/shape: --archetype <id>  ·  --preset <name>  ·  --force',
+  'Too big for compact start: --force does not unlock. Next: arkgate-check --init',
   'Inspect ranked shapes: arkgate-check --recommend',
 ].join('\n');
 

package/bin/ark.mjs

@@ -24,6 +24,8 @@ import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import {
   applyStartPreview,
+  emitStartSetupBudgetRefuse,
+  evaluateStartSetupBudgetGate,
   formatStartPackageInstallFailure,
   planStart,
   renderStartPreview,
@@ -470,6 +472,10 @@ async function start(args) {
         }
         return 2;
       }
+      if (!evaluateStartSetupBudgetGate(preview.setupBudget).ok) {
+        emitStartSetupBudgetRefuse(preview, args.json);
+        return 2;
+      }
     }
     if (args.json) console.log(JSON.stringify(preview, null, 2));
     else if (!args.apply) renderStartPreview(preview);

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;

package/bin/lib/agent-gates.mjs

@@ -106,6 +106,8 @@ export {
   assessSkillCatalogParity,
   detectSkillGaps,
   skillGapsForActiveHost,
+  skillGapToolLabel,
+  SKILL_CANONICAL_TOOL,
   agentsMdSkillRefs,
   verifyHostSkillCatalog,
   printSkillAndCodexGapHints,