arkgate 2.3.0 → 2.5.0

package/templates/skills/ark-fix.md

@@ -47,18 +47,22 @@ paste output you can generate yourself.
   with the impure implementation outside the domain, and pass it in.
 - **Intent prefix mismatch**: rename the intent to the layer's declared prefix,
   or move the handler to the layer that owns that prefix.
-- **Type-only inversion** (a lower layer `import type`s something from an upper layer,
-  e.g. a domain module importing a type that happens to live in a UI hook): move the
-  TYPE down to the layer that owns it (e.g. `src/lib/<domain>/types.ts`), and re-export
-  it from the original module for back-compat (`export type { X } from "@/lib/<domain>/types"`)
-  so no consumer breaks. This is the highest-volume, safest adoption fix — verify with
-  `tsc --noEmit`. It often also breaks a circular dependency that ran through the hook.
-  Two cases where the move is NOT mechanical — stop and flag instead of forcing it:
-  (a) the type extends a persistence/ORM row (e.g. a Drizzle schema type) — moving it to a
-  domain layer would couple domain→Persistence (the write gate will block it), so it needs a
-  domain-owned type or port, not a move; (b) the source file mixes the type with runtime
-  logic (stubs, helpers, mock builders) — split the types into their own module first, then
-  move.
+- **Type-only inversion** (`typeOnly: true` on a `LAYER_IMPORT_VIOLATION` — plan class
+  `mechanical-safe`, `remediationKind: type-only-import-move`): a lower layer `import type`s
+  something from an upper layer (e.g. domain importing a type that lives in a UI hook). Move the
+  TYPE down to the layer that owns it and re-export for back-compat
+  (`export type { X } from "@/lib/<domain>/types"`). Highest-volume safe fix — verify with the
+  gate (and `tsc --noEmit` if present). Not mechanical if: (a) the type extends a persistence/ORM
+  row — needs a domain-owned type/port; (b) the source mixes types with runtime logic — split
+  first, then move (or use pure-type file relocate when the *whole file* is type-only).
+- **Pure-type file relocate** (`sourcePureTypeModule` + type-only edge —
+  `remediationKind: pure-type-file-relocate`): the entire source file is type-surface only (no
+  runtime statements). Relocate the **file** to the owning layer (or extract the type module
+  there). Behavior-preserving; do not invent runtime ports.
+- **Value-syntax import of a pure type-only module** (`targetTypeOnlyExports` —
+  `remediationKind: import-type-from-pure-type-module`): convert static `import { T } from …`
+  to `import type { T } from …`. Never auto-apply for `require()` / dynamic `import()` (those stay
+  judgment — they still execute the module).
 - **Raw infrastructure access in an orchestration/UI layer** (a route/handler or component
   that runs SQL or imports the DB client directly — e.g. `sqlClient\`SELECT …\`` or
   `import { db } from "@/lib/db"` inside `src/app/**`): this is the value-import counterpart

package/templates/skills/ark-loop.md

@@ -21,15 +21,25 @@ If Ark isn't set up yet, run `ark start` (or `ark-check --recommend` then `ark i
 1. **Read the plan.** Run `ark-check --plan --json` (add `--baseline .ark-baseline.json` if the
    repo uses a baseline). It returns `goal` (with `met`, `activeViolations`, `autoApplicable`,
    `needsDecision`, `deferred`) and `steps[]`, each tagged `class` (`mechanical-safe` /
-   `judgment` / `deferred`) with a `confidence` and a plain-language `rationale`. If
-   `goal.met` is already true, report "nothing to do" and stop.
+   `judgment` / `deferred`) with a `confidence`, plain-language `rationale`, and often
+   `remediationKind`. If `goal.met` is already true, report "nothing to do" and stop.
+
+   **`mechanical-safe` kinds you may auto-apply** (zero false-safe — never invent others):
+
+   | `remediationKind` | What to do |
+   |-------------------|------------|
+   | `type-only-import-move` | Edge is already `import type` / type-only: move the **type** to the owning layer + re-export for back-compat |
+   | `pure-type-file-relocate` | Whole **source file** is pure type-surface (`sourcePureTypeModule`) + type-only edge: relocate the file (or extract types) to the owning layer |
+   | `import-type-from-pure-type-module` | Static value-syntax import of a pure type-only **target** module (`targetTypeOnlyExports`): convert to `import type` (and place type if needed) |
+
+   Still **judgment** (never auto): value imports, `require()` / dynamic `import()`, mixed modules with side effects, forbidden globals, cycles, verbatim infra relocation.
 
 2. **Work in a discardable git worktree.** Create one (`git worktree add`) so the entire run is
    reversible and never disturbs the user's working tree. Do all edits there. Nothing is
    permanent until the user reviews the final diff.
 
-3. **Apply the `mechanical-safe` steps, one at a time, validated.** For each such step
-   (e.g. a type-only import moved to the layer that owns it + a re-export for back-compat):
+3. **Apply the `mechanical-safe` steps, one at a time, validated.** Match the step's
+   `remediationKind` (table above) — do not expand the edit into a broader refactor:
    - Record the current active-violation count from the plan.
    - Make the edit at the SOURCE (fix the placement; don't add an `ark-*-disable` or edit the
      baseline/config to hide it).

package/templates/skills/ark-upgrade.md

@@ -18,6 +18,26 @@ npx arkgate-check --install-agent-gates --force
 
 Guide: `docs/migrate-from-ark-runtime-kernel.md` in the package (or on GitHub).
 
+**TypeScript 7 projects:** ArkGate falls back to a nested JS-API TypeScript when the
+project's `typescript` main export is version-only (TS 7.0). After upgrade, point users at
+`docs/typescript-support.md` if the gate or `ARK_DEBUG_TS=1` mentions fallback. Dual install
+(TS6 JS API + TS7 CLI) is optional for tooling that still needs classic `tsc` APIs.
+
+**MCP double-bin check (identity cutover):** after upgrade, open `.mcp.json` and
+`.cursor/mcp.json`. `args` must contain **exactly one** of `arkgate-mcp` / `ark-mcp`
+(prefer `arkgate-mcp`), never both. If both appear, run:
+
+```
+npx arkgate-check --install-agent-gates --migrate-commands
+```
+
+`ark upgrade` already runs migrate-commands; re-run it if an older 2.x left dual names.
+
+**Adoption completeness:** run `npx arkgate-check --doctor` (or `--doctor --json`) and
+read the **Adoption** section — host gaps, Codex home temp paths, optional-but-populated
+core layers, missing origin snapshot, baseline policy. Fix commands are printed per gap.
+HTML reports include the same Adoption card (separate from the 0–100 fitness score).
+
 ## Fast path
 
 One command does the whole flow — update the package, refresh gates + `/ark-*` skills
@@ -30,7 +50,12 @@ arkgate upgrade
 
 Use it when the user just wants the update done. Run the detailed steps below instead when
 you need to inspect the changelog first, handle a pnpm cooling-off window, or the one-liner
-reports a problem to triage.
+reports a problem to triage. Always refresh skills so agents pick up new `mechanical-safe`
+kinds and TS guidance:
+
+```
+npx arkgate-check --install-agent-gates --skills-only --force
+```
 
 ## Steps
 

package/templates/tests/ark-adoption-gaps.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Structural adoption-gap tests — copy into your project (e.g. tests/ark-adoption-gaps.test.ts)
+ * and run with Vitest/Jest. Asserts real on-disk gate artifacts (no mocks).
+ *
+ * Install reminder after copy:
+ *   npx arkgate-check --install-agent-gates
+ *   npx arkgate-check --doctor
+ */
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const root = process.cwd();
+
+function exists(rel: string) {
+  return fs.existsSync(path.join(root, rel));
+}
+
+describe('ArkGate adoption gaps (structural)', () => {
+  it('has architecture contract + primary gate files', () => {
+    expect(exists('ark.config.json')).toBe(true);
+    expect(exists('AGENTS.md')).toBe(true);
+    expect(exists('.mcp.json')).toBe(true);
+  });
+
+  it('MCP argv uses a single preferred bin (no dual ark-mcp + arkgate-mcp)', () => {
+    const raw = fs.readFileSync(path.join(root, '.mcp.json'), 'utf8');
+    const json = JSON.parse(raw);
+    const args: string[] = json?.mcpServers?.ark?.args ?? [];
+    const bins = args.filter((a) => a === 'ark-mcp' || a === 'arkgate-mcp');
+    expect(bins.length).toBe(1);
+    expect(bins[0]).toBe('arkgate-mcp');
+  });
+
+  it('has /ark-* skills for at least one agent host when that host dir exists', () => {
+    const hosts: Array<{ dir: string; skill: (n: string) => string }> = [
+      { dir: '.grok', skill: (n) => path.join('.grok', 'skills', n, 'SKILL.md') },
+      { dir: '.claude', skill: (n) => path.join('.claude', 'skills', n, 'SKILL.md') },
+      { dir: '.cursor', skill: (n) => path.join('.cursor', 'commands', `${n}.md`) },
+    ];
+    const required = [
+      'ark-autopilot',
+      'ark-loop',
+      'ark-fix',
+      'ark-adopt',
+      'ark-architect',
+      'ark-upgrade',
+    ];
+    for (const h of hosts) {
+      if (!exists(h.dir)) continue;
+      for (const name of required) {
+        expect(exists(h.skill(name)), `missing skill ${name} under ${h.dir}`).toBe(true);
+      }
+    }
+  });
+
+  it('origin report exists after first --report (or documents the command)', () => {
+    // Prefer real origin; if missing, the suite still documents the one-liner.
+    if (exists(path.join('.ark', 'reports', 'origin.json'))) {
+      expect(exists(path.join('.ark', 'reports', 'origin.json'))).toBe(true);
+      return;
+    }
+    // Soft path: ensure doctor/report is still the sanctioned fix.
+    expect(
+      'npx arkgate-check --report ark-report.html'.includes('--report')
+    ).toBe(true);
+  });
+});

package/tests/fixtures/ts-consumer/ark.config.json

@@ -0,0 +1,11 @@
+{
+  "include": ["src"],
+  "layers": [
+    { "name": "DomainModel", "patterns": ["src/domain/**"], "forbiddenGlobals": ["fetch"] },
+    { "name": "ApplicationOrchestration", "patterns": ["src/app/**"] }
+  ],
+  "rules": [
+    { "from": "DomainModel", "to": "ApplicationOrchestration", "allowed": false },
+    { "from": "ApplicationOrchestration", "to": "DomainModel", "allowed": true }
+  ]
+}

package/tests/fixtures/ts-consumer/src/app/types.ts

@@ -0,0 +1 @@
+import type { User } from '../domain/user'; export type U = User;

package/tests/fixtures/ts-consumer/src/domain/bad.ts

@@ -0,0 +1 @@
+import type { U } from '../app/types'; export type X = U;

package/tests/fixtures/ts-consumer/src/domain/ok.ts

@@ -0,0 +1 @@
+export const ok = 1;

package/tests/fixtures/ts-consumer/src/domain/user.ts

@@ -0,0 +1 @@
+export type UserId = string; export interface User { id: UserId }

package/tests/fixtures/ts-consumer/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "rootDir": "./src",
+    "types": ["node"],
+    "skipLibCheck": true,
+    "noEmit": true,
+    "paths": {
+      "@domain/*": ["./src/domain/*"]
+    }
+  },
+  "include": ["src/**/*.ts"]
+}