arkgate 2.9.2 → 2.11.0

package/CHANGELOG.md

@@ -4,6 +4,93 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 2.11.0 — 2026-07-10
+
+Fail-closed enforcement hardening: `--strict` now combines contract coverage, installed-gate
+checks, write-hook presence, and bypass diagnostics in one CI profile. The GitHub Action runs
+the exact checked-out revision by default, and runtime workflows cancel timed-out work
+cooperatively.
+
+### Added
+
+- **Strict CI profile:** `arkgate-check --strict` enables strict config validation, requires
+  generated gates plus a PreToolUse write hook, and fails on configured safety diagnostics.
+- **Bypass diagnostics:** new `dynamicImportAllowlist` and `safety` config fields detect
+  non-literal dynamic imports, TypeScript suppression directives, explicit `any` casts,
+  production InMemory defaults, and disabled or omitted peer isolation. `--doctor --json`
+  exposes the same evidence under `doctor.safety`.
+- **Release-quality CI:** JavaScript syntax validation, enforced coverage thresholds, and a
+  Node 18/20/22/24 compatibility matrix now run before merge.
+
+### Changed
+
+- **Pinned GitHub Action execution:** `uses: pedroknigge/arkgate@<tag-or-SHA>` now runs that
+  checked-out ArkGate source. The `version` input remains available only as an explicit exact
+  npm compatibility override.
+- **Complete MCP contract:** `ark://manifest` exposes every configured file layer separately
+  from runtime intent layers, plus reviewed dynamic-import and safety policy.
+- **Workflow cancellation contract:** workflow steps receive an `AbortSignal` as their third
+  argument. `timeoutMs` aborts that signal, clears the active step, and rejects duplicate step
+  names before execution can corrupt compensation order.
+- **Filesystem confinement:** source scans follow internal symlinks once and reject symlinks
+  that escape the project root.
+
+### Fixed
+
+- **Baseline duplicate honesty:** repeated violations now receive stable per-occurrence keys,
+  so adding a second identical violation is new debt instead of being hidden by one baseline
+  entry.
+- **Write-hook duplicate honesty:** proposed writes compare violation counts, preventing a new
+  duplicate from being mistaken for an already-existing violation.
+- **CLI argument safety:** unknown flags and missing flag values fail with usage guidance
+  instead of silently weakening enforcement or throwing an internal error.
+- **Action gate detection:** repositories using the ArkGate composite Action satisfy the CI
+  gate check without needing a separate literal `ark-check` command.
+
+## 2.10.0 — 2026-07-10
+
+Track W — **Constrained write → verified repair**: write-boundary autoPatch, prepare_write,
+loop-cost measurement, opt-in hook repair payloads, doctor write-path awareness, and a
+proof-gated port-inject transform (judgment for auto-apply).
+
+### Added
+
+- **W1 write-boundary autoPatch:** `validate_code` and PreToolUse `--hook` may return
+  additive `autoPatch: { source, remediationKind, confidence, valid }` for mechanical-safe
+  **import type** rewrites (`import-type-from-pure-type-module`, `import-type-of-type-exports`).
+  Post-patch revalidation must be green or the patch is discarded (never silent write).
+  Implementation: `bin/lib/auto-patch.mjs`.
+- **W2 `ark_prepare_write` MCP tool:** place + constrain + validate + optional autoPatch +
+  judgmentBrief + contentHash in one call (`bin/lib/prepare-write.mjs`). Composes
+  `ark_place` + write gate — not a second contract.
+- **W3 loop-cost eval harness:** `eval/loop-cost-run.mjs` / `npm run eval:loop-cost`
+  records turns-to-green, optional tokens, CHEATED (fixture-measured). Baseline
+  `eval/loop-cost-baseline.json` (medianTurnsTypeOnly=1, cheatedRate=0).
+- **W4 opt-in hook repair payload:** `--hook-repair` / `ARK_HOOK_REPAIR=1` on deny emits
+  `ARK_REPAIR_JSON` + `ARK_AUTOPATCH_JSON` (stderr) and optional Grok `autoPatch` (stdout).
+  Default `--hook` remains hard-block prose only. Install templates (Claude/Grok) include
+  `--hook-repair`. Never silent write.
+- **W5 doctor write-path awareness:** `ark-check --doctor` (JSON + human) surfaces
+  `writePath.mode` (`repair` | `reject-only` | `mcp-only` | `none`) and
+  `prepareWrite` / `autoPatch` flags from installed hooks/MCP. Reject-only gap is
+  additive (info) with install fix.
+- **W6 port-proof inject binding (eval-gated):** prove+transform for
+  `port-proof-inject-binding` — single named value import used only as
+  `binding.method(...)` inside function declarations. Removes the import, emits a
+  port type, injects the binding as a parameter (call sites preserved). **Judgment for
+  auto-apply** (call arity changes; not write-path autoPatch). Fail-closed static proof;
+  rest params refuse apply. Labeled eval case. Implementation: `bin/lib/port-proof.mjs` +
+  scan flag `portProofEligible`.
+
+### Changed
+
+- **Write gate type-only edges:** `import type` / `export type` no longer hard-block
+  LAYER_IMPORT / infra heuristics on the write path (erased at runtime). Value imports
+  and peerIsolation still deny. ark-check plan continues to surface type placement debt.
+- **`ark_prepare_write` isError:** always `isError` when proposed source is invalid
+  (autoPatch is additive recovery, not soft-success).
+- **`resolveImportFileAbs`:** confines disk reads under project root (no path escape).
+
 ## 2.9.2 — 2026-07-09
 
 Skill surface hardening: dual-engine, explore, STOP handoffs, AGENTS routing, subagent fan-out.

package/README.md

@@ -151,6 +151,11 @@ critical handoffs say **STOP** and name the next skill (hosts must follow — ma
 When the host allows it, skills may **fan out parallel subagents** (disjoint scopes);
 otherwise they **fall back to sequential**.
 
+**Write path (Track W):** Prefer MCP **`ark_prepare_write`** when you have a snippet (place +
+constrain + validate + optional `autoPatch` + `judgmentBrief`). PreToolUse hooks with
+`--hook-repair` emit machine-readable repair payloads on deny (still hard block; never silent
+write). See [docs/ai-gates.md](docs/ai-gates.md).
+
 | Need | Skill |
 |------|--------|
 | Only the apply loop (plan already exists) | `/ark-loop` |
@@ -184,6 +189,10 @@ ark.config.json
 - **Frameworks:** Nest / Next / express / library layouts get sensible globs on init so day-one coverage is real.
 - **Brownfield:** baseline ratchet, refuse to freeze a wrong contract, `/ark-adopt` for mature trees.
 - **Agents:** skills install into Claude / Cursor / Codex / Grok; `ark start` freezes an origin report under `.ark/reports/`.
+- **Write protocol (2.10 / Track W):** mechanical-safe **autoPatch** on the write gate (`import type`); MCP **`ark_prepare_write`** (place + validate + patch + judgmentBrief); opt-in hook **`--hook-repair`** (`ARK_REPAIR_JSON`); doctor **`writePath`** (repair vs reject-only); loop-cost eval (`npm run eval:loop-cost`). Port-proof inject is **judgment** (arity change), not silent auto-apply.
+- **Fail-closed CI (2.11):** `--strict` combines config coverage, required CI/MCP/write gates,
+  PreToolUse hook presence, and bypass diagnostics for dynamic imports, TypeScript suppressions,
+  explicit `any` casts, InMemory runtime defaults, and disabled peer isolation.
 - **TypeScript:** project compilers 5.x / 6.x / 7.x — gate falls back to a nested JS-API TypeScript when TS 7’s main export is version-only ([docs/typescript-support.md](docs/typescript-support.md)).
 
 ### Why not only ESLint / dependency-cruiser / Nx?
@@ -208,6 +217,7 @@ ark.config.json
 npx arkgate start                         # guided setup + plan + origin report
 npx arkgate-check --doctor                # health + Adoption gaps (not just fitness)
 npx arkgate-check --doctor --json         # machine-readable doctor.adoption
+npx arkgate-check --strict                # fail-closed CI + installed-gate/safety checks
 npx arkgate-check --plan                  # safe-to-auto-fix vs your call
 npx arkgate-check --coverage              # Governed: N%
 npx arkgate-check --report ark-report.html  # showcase HTML + Adoption card + origin/latest
@@ -218,8 +228,8 @@ npx arkgate upgrade                       # package + gates/skills + MCP/Codex n
 CI (example):
 
 ```yaml
-- run: npx arkgate-check --root . --config ark.config.json --strict-config
-# or: uses: pedroknigge/arkgate@main
+- run: npx arkgate-check --root . --config ark.config.json --strict
+# or: uses: pedroknigge/arkgate@<tag-or-SHA>  # runs that checked-out revision
 ```
 
 ---

package/SECURITY.md

@@ -28,10 +28,9 @@ a private security contact without including exploit details.
 ArkGate releases are GitHub-first:
 
 1. Changes land on GitHub and must pass CI plus the dedicated security workflow.
-2. A GitHub Release is created from an annotated `vX.Y.Z` tag. Tag verification is
-   **fail-closed** by default for unsigned tags unless
-   `ARK_ALLOW_UNSIGNED_RELEASE_TAG=true` is set (CI publish sets this until GPG signing is
-   wired). Signed tags can later require `ARK_REQUIRE_SIGNED_RELEASE_TAG=true`.
+2. A GitHub Release is created from a signed `vX.Y.Z` tag (`git tag -s`). The publish
+   workflow verifies the signature and fails closed for unsigned tags. The local override
+   exists only for explicit emergency use and is not enabled in CI.
 3. The manual `Publish npm` workflow verifies the tag, requires the GitHub Release to
    exist, reruns release checks, publishes npm with provenance, and uploads a SHA-256
    checksum for the npm tarball to the GitHub Release.

package/bin/ark-check.mjs

@@ -43,6 +43,7 @@ import {
   arkPackageVersion,
   REQUIRED_GATE_FILES,
   codexPromptsDir,
+  detectWritePathCapabilities,
 } from './lib/agent-gates.mjs';
 import { syncBaselineIntoCheckSurfaces } from './lib/field-install.mjs';
 import {
@@ -64,6 +65,7 @@ import {
 import { runRatchetCores } from './lib/core-ratchet.mjs';
 import {
   baselineKey,
+  baselineOccurrenceKeys,
   readBaseline,
   summarizeViolations,
   writeBaseline,
@@ -99,6 +101,7 @@ function parseArgs(argv) {
     printConfig: undefined,
     tsconfig: undefined,
     json: false,
+    strict: false,
     strictConfig: false,
     requireGates: false,
     init: false,
@@ -122,13 +125,25 @@ function parseArgs(argv) {
     version: false,
     help: false,
   };
+  const requireValue = (flag, index) => {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('-')) {
+      throw new Error(`Missing value for ${flag}. Run ark-check --help for usage.`);
+    }
+    return value;
+  };
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
+    else if (arg === '--strict') {
+      args.strict = true;
+      args.strictConfig = true;
+      args.requireGates = true;
+    }
     else if (arg === '--strict-config') args.strictConfig = true;
     else if (arg === '--require-gates') args.requireGates = true;
     else if (arg === '--init') args.init = true;
-    else if (arg === '--preset') args.preset = argv[++i];
+    else if (arg === '--preset') args.preset = requireValue(arg, i++);
     else if (arg === '--install-agent-gates') args.installAgentGates = true;
     else if (arg === '--tools') {
       // Consume the next arg only when it isn't another flag (same rule as --baseline),
@@ -152,7 +167,7 @@ function parseArgs(argv) {
     else if (arg === '--recommend') args.recommend = true;
     else if (arg === '--write-plan') args.writePlan = true;
     else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
-    else if (arg === '--apply-policy-pack') args.applyPolicyPack = argv[++i];
+    else if (arg === '--apply-policy-pack') args.applyPolicyPack = requireValue(arg, i++);
     else if (arg === '--suggest-include') args.suggestInclude = true;
     else if (arg === '--adopt-contract') args.adoptContract = true;
     else if (arg === '--ratchet-cores') args.ratchetCores = true;
@@ -174,13 +189,14 @@ function parseArgs(argv) {
       const next = argv[i + 1];
       args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
     }
-    else if (arg === '--root') args.root = path.resolve(argv[++i]);
-    else if (arg === '--config') args.config = argv[++i];
-    else if (arg === '--manifest') args.manifest = argv[++i];
-    else if (arg === '--print-config') args.printConfig = argv[++i];
-    else if (arg === '--tsconfig') args.tsconfig = argv[++i];
+    else if (arg === '--root') args.root = path.resolve(requireValue(arg, i++));
+    else if (arg === '--config') args.config = requireValue(arg, i++);
+    else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
+    else if (arg === '--print-config') args.printConfig = requireValue(arg, i++);
+    else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
     else if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
+    else throw new Error(`Unknown argument: ${arg}. Run ark-check --help for usage.`);
   }
   return args;
 }
@@ -198,7 +214,7 @@ function usage() {
   return [
     'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
     '       ark-check --version',
-    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict | --strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
@@ -251,6 +267,8 @@ function usage() {
     '',
     'Config warnings are advisory by default and are included in JSON output.',
     'Use --strict-config to make config warnings fail the check.',
+    'Use --strict for the fail-closed CI profile: --strict-config + --require-gates',
+    'plus the security diagnostics surfaced by doctor.',
     '',
     '--require-gates fails the check when AGENTS.md, .mcp.json, or the generated CI',
     'workflow is missing, so "installed but never configured" is a red CI. Combine it',
@@ -301,6 +319,10 @@ function readConfig(root, configPath) {
     ...(raw.exclude ? { exclude: raw.exclude } : {}),
     ...(raw.excludeGenerated !== undefined ? { excludeGenerated: raw.excludeGenerated } : {}),
     ...(raw.cyclePolicy ? { cyclePolicy: raw.cyclePolicy } : {}),
+    ...(raw.dynamicImportAllowlist
+      ? { dynamicImportAllowlist: raw.dynamicImportAllowlist }
+      : {}),
+    ...(raw.safety ? { safety: raw.safety } : {}),
   };
 }
 
@@ -316,7 +338,7 @@ function detectConfig(root) {
 
   for (const entry of DEFAULT_INTENT_PREFIXES) {
     const directories = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? []).filter(
-      (directory) => walk(path.join(root, srcDir, directory)).length > 0
+      (directory) => walk(path.join(root, srcDir, directory), [], { root }).length > 0
     );
     if (directories.length === 0) continue;
     layers.push({
@@ -784,7 +806,7 @@ function runInit(args) {
     }
     // The starter profile only governs src/. Existing source elsewhere would make the
     // gate silently green, so surface it instead of pretending the project is covered.
-    const outside = walk(args.root)
+    const outside = walk(args.root, [], { root: args.root })
       .map((file) => normalize(path.relative(args.root, file)))
       .filter((rel) => !rel.startsWith('src/') && !rel.split('/').some((s) => s.startsWith('.')));
     if (outside.length > 0) {
@@ -956,6 +978,9 @@ async function main() {
 
   if (args.requireGates) {
     const missing = missingGates(args.root);
+    if (args.strict && !detectWritePathCapabilities(args.root).hookPresent) {
+      missing.push('PreToolUse write hook');
+    }
     if (missing.length > 0) {
       const payload = {
         ok: false,
@@ -1032,7 +1057,7 @@ async function main() {
     );
   }
 
-  const { violations, warnings } = runArchitectureScan({
+  const { violations, warnings, safety } = runArchitectureScan({
     root,
     config,
     manifest,
@@ -1046,6 +1071,7 @@ async function main() {
     runDoctor(root, config, files, rules, violations, args.json, {
       configPath: path.isAbsolute(args.config) ? args.config : path.join(root, args.config),
       configMissing: !fs.existsSync(path.isAbsolute(args.config) ? args.config : path.join(root, args.config)),
+      safety,
     });
     return;
   }
@@ -1118,11 +1144,10 @@ async function main() {
   if (args.baseline) {
     const baseline = readBaseline(root, args.baseline);
     if (baseline.exists) {
-      suppressed = violations.filter((violation) => baseline.keys.has(baselineKey(violation)));
-      activeViolations = violations.filter(
-        (violation) => !baseline.keys.has(baselineKey(violation))
-      );
-      const currentKeys = new Set(violations.map(baselineKey));
+      const occurrenceKeys = baselineOccurrenceKeys(violations);
+      suppressed = violations.filter((_, index) => baseline.keys.has(occurrenceKeys[index]));
+      activeViolations = violations.filter((_, index) => !baseline.keys.has(occurrenceKeys[index]));
+      const currentKeys = new Set(occurrenceKeys);
       staleBaselineKeys = [...baseline.keys].filter((key) => !currentKeys.has(key)).length;
     } else {
       warnings.push(