arkgate 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
+## 2.12.0 — 2026-07-10
+
+### Fixed
+
+- **Install agent gates on temp roots:** skip rewriting the developer's real
+  `~/.codex/config.toml` when the project root is a temp/upgrade scratch and
+  `CODEX_HOME` is unset. Home MCP wire failures no longer fail an otherwise
+  successful repo gate install (sandbox/EPERM). Explicit `CODEX_HOME` and
+  `--codex-home` still wire as before.
+- **Q1 coverage floors (broad include, 80/85/95):** Vitest thresholds statements/lines **≥80%**,
+  branches/functions **≥85%** on the **full product unit surface** (`src/**` + `bin/lib/**` +
+  `bin/ark-shared.mjs`; only process-entry shells excluded — no cherry-picked enforcement-core
+  include). Per-path critical floors: write-path-detect / auto-patch / prepare-write /
+  safety-diagnostics / baseline-key / graph-cycles at **≥95%** branch. Real branch-driving tests
+  under `tests/unit/static-check/` (critical + surface/topup/seam suites). Two consecutive
+  green `npm run test:coverage` captures (stmts/lines **92.71%**, branches **85%**, functions
+  **94.76%**; critical modules all **≥95%** branch).
+- **agent-gates modularization:** thin facade (`bin/lib/agent-gates.mjs` ~100 LOC) re-exports
+  `gate-files`, `skill-install`, `ci-and-commands`, `mcp-adoption`, `install-migrate`,
+  `typescript-host`, `hook-templates`, `write-path-detect`, plus field/codex helpers.
+  `detectDeployPathQuality` extracted to `bin/lib/deploy-path.mjs` so `mcp-adoption.mjs` stays
+  under the 600 LOC module budget. Import hygiene on extract modules; `loadTypeScript` uses
+  `__arkCheckCli` for the nested arkgate TypeScript fallback.
+- **Deny→repair CI proof:** `tests/unit/static-check/writePathDetect.test.ts` drives
+  shipped `bin/ark-mcp.mjs --hook --hook-repair` and asserts `ARK_REPAIR_JSON` /
+  `ARK_AUTOPATCH_JSON` on deny (exit 2); reject-only without repair flag still supported.
+- **Dogfood write path repair:** local Claude/Grok hooks use `--hook-repair`; doctor
+  reports `writePath.mode = repair` on this tree.
+- **Self-hosted AGENTS.md:** `--install-agent-gates --force` no longer overwrites library
+  mother-repo Identity (`skipped-self-hosted`).
+- **hexagonal-order-api:** `safety.allowInMemory` for ephemeral demo kernel; prefer
+  `arkgate/runtime` imports; `npm run check` green under `--strict-config`.
+- **multi-app / monorepo rules:** deny App→Persistence, Presentation→Domain, and
+  Persistence→Presentation (parity with crud-product starter).
+- **Generated CI Node default lags local npm (again):** when a project had no
+  `.nvmrc` / `engines.node`, the Ark architecture gate workflow defaulted to
+  Node 22. Lockfiles written on Node 24/26 then failed `npm ci` with
+  "Missing: … from lock file" before `ark-check` ran — CI green, Ark red.
+  Detection order is now `.nvmrc` / `.node-version` → `engines.node` → **highest
+  `node-version` from sibling workflows** (excludes `ark-check.yml` so a stale
+  gate cannot re-pin itself) → default **24**. Refresh existing gates with
+  `ark-check --install-agent-gates --force` (or edit `node-version` in
+  `.github/workflows/ark-check.yml`).
+
+### Changed
+
+- **Hook templates extracted** to `bin/lib/hook-templates.mjs` (agent-gates seam).
+- **Write-path detect extracted** to `bin/lib/write-path-detect.mjs` (doctor W5; re-exported
+  from agent-gates).
+- **Coverage thresholds** raised to Q1 floors on the broad include set: statements/lines **≥80**,
+  branches/functions **≥85**, critical write/safety modules **≥95%** branch (see Fixed above).
+- **`/ark-explore` skill:** decision-grade recon — field path (run starters/checks),
+  installed hooks vs install templates, coupling via fan-in/exports (not LOC alone),
+  ranked “así te lo re-soluciono” rows only when residual changes action; ENFORCE /
+  empty plan treated as baseline, not the story. **v2.1:** output modes (recon vs
+  dual-plan seed, no multi-week roadmaps by default); path-correct vs design-correct
+  + semantic false-green; success signals and kill-switches on bets (anti-vanity).
+- **`/ark-autopilot` skill:** explore-first (decision-grade), **dual plan** —
+  A remediation from `--plan` + B pattern/evolution bets (never auto-apply B as
+  mechanical-safe); empty plan no longer means “healthy” without explore/B.
+- **Day-zero origin first:** `ark start` / `ark init` freeze `.ark/reports/origin.*`
+  immediately after `ark.config.json` exists and **before** agent docs, skills, and CI
+  templates. Later `--report` still shows evolution vs that snapshot.
+
 ## 2.11.0 — 2026-07-10
 
 Fail-closed enforcement hardening: `--strict` now combines contract coverage, installed-gate

package/README.md

@@ -23,8 +23,8 @@ and makes sure a “green” check means something real.
 If you remember nothing else:
 
 ```text
-1.  npx arkgate start          ← install shape + gates + origin report
-2.  /ark-autopilot             ← in your agent: adopt, fix, leave gates on
+1.  npx arkgate start          ← walk tree → contract → **day-zero origin** → gates
+2.  /ark-autopilot             ← explore first, dual plan, safe fixes, leave gates on
 3.  npx arkgate-check --doctor ← “where am I?” anytime (one status screen)
 ```
 
@@ -106,7 +106,7 @@ Full checklist (CI, MCP, Codex, imports): **[docs/migrate-from-ark-runtime-kerne
 
 ```bash
 npm install -D arkgate typescript
-npx arkgate start                 # setup + origin report
+npx arkgate start                 # contract → day-zero origin → gates + plan
 # in agent:
 #   /ark-autopilot
 npx arkgate-check --doctor        # status light + next action
@@ -117,11 +117,13 @@ Aliases `ark` / `ark-check` / `ark-mcp` still work. **npm / pnpm / yarn**. No in
 <details>
 <summary>What <code>/ark-autopilot</code> does under the hood (optional detail)</summary>
 
-1. Setup if needed (`ark start`).
-2. Origin architecture report (before picture in `.ark/reports/`).
-3. Adoption: match contract to real folders, raise governed %.
-4. Plan + safe auto-fixes; judgment when you ask for full apply.
-5. Gates on + after report (evolution vs origin).
+1. Setup if needed (`ark start` — contract, then **day-zero origin**, then gates).
+2. **Explore pass** (decision-grade map of *this* product; field path when demos exist).
+3. **Dual plan:** **A** remediation from `--plan` (mechanical-safe only by default); **B** pattern/evolution bets (never auto-applied as mechanical-safe). Empty plan ≠ “healthy” without explore/B.
+4. Apply A → re-check; judgment only when you ask for full apply.
+5. Gates on + latest report (evolution vs frozen origin).
+
+Standalone recon without applying: `/ark-explore`.
 
 </details>
 
@@ -188,11 +190,14 @@ ark.config.json
 - **Presets:** hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts (+ aliases clean-architecture / onion-architecture). Layers start optional; doctor suggests tightening populated cores. Cross-slice / cross-context bans use optional `peerIsolation` rules.
 - **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/`.
+- **Agents:** skills install into Claude / Cursor / Codex / Grok; `ark start` freezes **day-zero origin** under `.ark/reports/` **before** agent docs/CI templates.
 - **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.
+- **Trust / coverage (2.12):** package unit-test floors on the broad product surface
+  (statements/lines **≥80%**, branches/functions **≥85%**; enforcement-critical modules **≥95%**
+  branch). Explore dual-plan + day-zero origin first (see above). Roadmap next: Q2 repair dogfood matrix.
 - **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?
@@ -214,7 +219,7 @@ ark.config.json
 ## Common commands
 
 ```bash
-npx arkgate start                         # guided setup + plan + origin report
+npx arkgate start                         # guided setup: contract → origin → gates → plan
 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

package/bin/ark.mjs

@@ -23,6 +23,32 @@ import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
 
+/**
+ * Day-zero architecture picture: freeze origin under `.ark/reports/` as soon as
+ * `ark.config.json` exists — **before** agent docs, skills, CI templates, or cleanups.
+ * Idempotent: origin is written only once (`--report` archive semantics).
+ */
+function freezeDayZeroOrigin(root) {
+  const configPath = path.join(root, 'ark.config.json');
+  if (!fs.existsSync(configPath)) {
+    console.log(
+      `  Skip origin freeze — no ark.config.json yet. After init: ${arkCommand(root, 'ark-check', '--report ark-report.html')}`
+    );
+    return;
+  }
+  const originJson = path.join(root, '.ark', 'reports', 'origin.json');
+  const already = fs.existsSync(originJson);
+  console.log(
+    already
+      ? 'Architecture origin already frozen (.ark/reports/origin.*) — leaving it untouched.'
+      : 'Freezing day-zero architecture picture (origin) before agent docs / gates…'
+  );
+  runArkCheck(
+    ['--root', root, '--config', 'ark.config.json', '--report', 'ark-report.html'],
+    { cwd: root }
+  );
+}
+
 function parseArgs(argv) {
   const args = {
     command: undefined,
@@ -330,6 +356,10 @@ async function init(args) {
       console.log('Skipped ark.config.json generation.');
     }
 
+    // Origin first: contract-on-tree picture before AGENTS.md / skills / CI templates.
+    console.log('');
+    freezeDayZeroOrigin(root);
+
     const installGates =
       nonInteractive || (await askYesNo(rl, 'Configure agent and CI gate templates?', true));
     if (installGates) {
@@ -357,7 +387,7 @@ async function init(args) {
       console.log(`Shape: ${archetype}. Plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
     }
     console.log(
-      `Freeze day-one architecture snapshot: ${arkCommand(root, 'ark-check', '--report ark-report.html')} (writes .ark/reports/origin.* once).`
+      `Day-zero origin: .ark/reports/origin.* (frozen once; later --report shows evolution vs origin).`
     );
     console.log(`Adoption health: ${arkCommand(root, 'ark-check', '--doctor')}`);
     return 0;
@@ -381,9 +411,11 @@ async function start(args) {
   try {
     console.log("Let's set up Ark for your project.");
     console.log(
-      "I'll look at your code, suggest a shape, set up the guardrails, and show you a plan."
+      "I'll walk the tree, freeze a day-zero architecture picture, then set up guardrails and show a plan."
+    );
+    console.log(
+      'Nothing in your product code is changed — only Ark config, then origin snapshot, then agent/CI templates.'
     );
-    console.log('Nothing in your code is changed — this only adds Ark configuration.');
     if (nonInteractive && !args.yes) {
       console.log(
         'Non-interactive session (no TTY) — using guided defaults (same as --yes). Pass flags to override.'
@@ -440,10 +472,10 @@ async function start(args) {
       console.log('  Skipping arkgate package pin (--no-install).');
     }
 
-    // 3) Set up config + gates. Greenfield → the shape's preset; an established repo → detection,
-    // so the contract anchors to the directories you already have instead of aspirational globs.
+    // 3) Contract first (config only). Greenfield → shape preset; established repo → detection,
+    // so the contract anchors to directories you already have instead of aspirational globs.
     console.log('');
-    console.log('Setting up Ark…');
+    console.log('Setting up Ark contract…');
     const configPath = path.join(root, 'ark.config.json');
     if (!fs.existsSync(configPath)) {
       const initArgs = ['--root', root, '--init'];
@@ -482,6 +514,15 @@ async function start(args) {
     } else {
       console.log('  Found an existing ark.config.json — keeping it.');
     }
+
+    // 4) Day-zero origin — freeze the architecture picture *before* agent docs / CI / skills.
+    // Later --report runs show evolution vs this snapshot. Idempotent (origin once).
+    console.log('');
+    freezeDayZeroOrigin(root);
+
+    // 5) Agent + CI gate templates (docs, hooks, skills) — after origin is frozen.
+    console.log('');
+    console.log('Installing agent and CI gate templates…');
     {
       const gateArgs = ['--root', root, '--install-agent-gates'];
       if (args.tools) gateArgs.push('--tools', args.tools);
@@ -489,7 +530,7 @@ async function start(args) {
       runArkCheck(gateArgs, { cwd: root });
     }
 
-    // 4) Show the plan: what's safe to auto-fix vs what needs a decision.
+    // 6) Show the plan: what's safe to auto-fix vs what needs a decision.
     console.log('');
     console.log('Your architecture plan:');
     runArkCheck(['--root', root, '--config', 'ark.config.json', '--plan'], { cwd: root });
@@ -571,7 +612,7 @@ async function start(args) {
       planOk = false;
     }
 
-    // 5) Plain-language wrap-up — one next step, status light only.
+    // 7) Plain-language wrap-up — one next step, status light only.
     // Modes are detected (Suggest/Adapt/Enforce), not user-picked settings.
     // Soft-block false-green using the same doctor adoption gap (no second detector).
     let falseGreenGap = null;
@@ -620,7 +661,7 @@ async function start(args) {
       console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
     } else {
       console.log('  1. In your agent:  /ark-autopilot');
-      console.log('     → origin report, adoption, plan, safe fixes, leave gates on.');
+      console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
     }
     console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
     console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-config')}`);
@@ -630,16 +671,8 @@ async function start(args) {
       );
     }
     console.log('');
-    console.log('Optional later: --plan · --coverage · /ark-fix · /ark-place · ark upgrade');
-
-    // 6) First architecture report — freezes an origin snapshot under .ark/reports/
-    // so later --report runs can show evolution. Idempotent: origin is written only once.
-    console.log('');
-    console.log('Capturing architecture report (origin snapshot on first run)…');
-    runArkCheck(
-      ['--root', root, '--config', 'ark.config.json', '--report', 'ark-report.html'],
-      { cwd: root }
-    );
+    console.log('Day-zero origin is under .ark/reports/origin.* — re-run --report later for evolution.');
+    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-fix · /ark-place · ark upgrade');
     return 0;
   } finally {
     rl?.close();