arkgate 2.10.0 → 2.12.0

package/dist/{types-D6Q8WHes.d.cts → types-BZ17b9i5.d.cts}

@@ -941,7 +941,11 @@ interface WorkflowStep<P extends SagaContext = SagaContext> {
     onEvent?: IntentName;
     retry?: RetryPolicy;
     timeoutMs?: number;
-    execute: (payload: P, bus: EventBus) => MaybePromise<Partial<P> | void>;
+    /**
+     * Execute one step. The signal is aborted when `timeoutMs` elapses; implementations
+     * performing I/O must pass it to the underlying client for cooperative cancellation.
+     */
+    execute: (payload: P, bus: EventBus, signal: AbortSignal) => MaybePromise<Partial<P> | void>;
     compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
 }
 interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {

package/dist/{types-D6Q8WHes.d.ts → types-BZ17b9i5.d.ts}

@@ -941,7 +941,11 @@ interface WorkflowStep<P extends SagaContext = SagaContext> {
     onEvent?: IntentName;
     retry?: RetryPolicy;
     timeoutMs?: number;
-    execute: (payload: P, bus: EventBus) => MaybePromise<Partial<P> | void>;
+    /**
+     * Execute one step. The signal is aborted when `timeoutMs` elapses; implementations
+     * performing I/O must pass it to the underlying client for cooperative cancellation.
+     */
+    execute: (payload: P, bus: EventBus, signal: AbortSignal) => MaybePromise<Partial<P> | void>;
     compensate?: (payload: P, bus: EventBus, error?: unknown) => MaybePromise<void>;
 }
 interface WorkflowStartTrigger<P extends SagaContext = SagaContext> {

package/docs/agent-guide.md

@@ -49,13 +49,23 @@ MCP `ark_recommend` and the `/ark-architect` skill.
 ### Terminal onboarding (Phase B)
 
 ```bash
-npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → gates → strict check
+npx ark start --yes                             # preferred: shape → contract → **day-zero origin** → gates → plan
+npx ark init --archetype crud-product --yes   # non-interactive: shape → preset → origin → gates
 npx ark init                                    # TTY wizard: pick application shape (1–8), not a framework
 npx ark-check --doctor                          # includes "New here?" when coverage is low or config is fresh
 npx ark-check --report beginner.html --beginner # simplified HTML for enthusiasts
 npx ark-check --watch                           # debounced re-check when governed files change
 ```
 
+**Day-zero origin (2.12+):** as soon as `ark.config.json` exists, `ark start` / `ark init`
+freeze `.ark/reports/origin.*` **before** writing agent docs, skills, or CI templates.
+Later `--report` shows evolution vs that snapshot. Do not `--reset-origin` unless the user
+explicitly wants a new baseline.
+
+**Default agent co-pilot:** `/ark-autopilot` (explore-first, dual plan A remediation + B
+pattern bets). Recon without applying: `/ark-explore`. Never treat empty `--plan` as
+“architecture healthy” without the explore pass.
+
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from
 `--recommend` scoring.
@@ -176,7 +186,7 @@ reference, and explanation for the full path (recommend → init → gallery →
 3. Run `ark init --archetype <id> --yes`, `--apply-policy-pack enthusiast-<preset>`, or `ark init --preset <preset> --yes` when no `ark.config.json` exists.
 4. Optional: `--write-plan` for `ark-adoption-plan.json`; copy a gallery starter from `examples/README.md`.
 5. Use `/ark-place` or `ark_place` for individual files after the contract exists.
-6. Verify with `ark-check --root . --config ark.config.json --strict-config`.
+6. Verify with `ark-check --root . --config ark.config.json --strict`.
 
 ### Write protocol (2.10+ / Track W)
 

package/docs/ai-gates.md

@@ -153,7 +153,7 @@ Layers:
   - PersistenceAdapters: src/adapters/persistence/**
 Rules: 10 denied layer edge(s). Full contract: ark://manifest MCP resource.
 Baseline: 3 frozen violation(s) — only NEW violations fail; do not add to them.
-After edits run: npx ark-check --root . --config ark.config.json --strict-config
+After edits run: npx ark-check --root . --config ark.config.json --strict
 ```
 
 The hook belongs in the **project's** `.claude/settings.json` (that's what
@@ -390,9 +390,27 @@ Prefer keeping editor + CI on the same `ark.config.json` — do not maintain a p
 Whatever the agent side does, gate the merge:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict-config
+- run: npx ark-check --root . --config ark.config.json --strict
 ```
 
+The `--strict` profile also requires the generated CI/write gates and fails on safety
+diagnostics. Configure reviewed exceptions explicitly:
+
+```json
+{
+  "dynamicImportAllowlist": ["src/plugins/loader.ts"],
+  "safety": {
+    "maxTsSuppressions": 0,
+    "maxAnyCasts": 0,
+    "allowInMemory": false,
+    "allowDisabledPeerIsolation": false
+  }
+}
+```
+
+`ark-check --doctor --json` reports counts under `doctor.safety`. An `any` cast is
+reported as lost static assurance; it does not imply that a runtime schema was bypassed.
+
 Adopting Ark on an existing codebase with violations? Freeze them once and ratchet down:
 
 ```bash

package/docs/package-surface.md

@@ -16,10 +16,10 @@ This document is the consumer contract for **what is stable** vs **what is opt-i
 |---------|----------------|-----------------|
 | **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend) are stable within a major. Additive fields OK; removals/renames are major. |
 | **MCP tools** | `arkgate-mcp` / `ark://…` resources | Tool names and primary argument shapes are stable within a major. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
-| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve. |
+| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Schema fields documented in playbooks/examples are stable; new optional fields may appear. |
+| **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. explore dual-plan seed, day-zero origin order). |
 | **ESLint subpath** | `arkgate/eslint` | Config-driven layer/import rules; loads consumer `ark.config.json`. |
-| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | Inputs for running the check stay stable within a major. |
+| **GitHub Action** | `pedroknigge/arkgate` (see `action.yml`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
 
 Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
 
@@ -73,3 +73,10 @@ See [production-hardening.md](./production-hardening.md) for runtime operational
 | Bugfix with no contract change | **patch** |
 | Prefer `arkgate/runtime` over root (docs only; root still exports) | **patch/minor** |
 | Remove root kernel re-exports | **major** (with migration notes) |
+
+---
+
+## Release notes (maintainers)
+
+Ship notes for a version live under [releases/](./releases/) (e.g. [2.12.0.md](./releases/2.12.0.md)).
+Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](../CONTRIBUTING.md)).

package/docs/production-hardening.md

@@ -37,6 +37,11 @@ When implementing Ark store interfaces in production, cover these guarantees exp
 - Observability: failed writes and dispatches are visible to operators.
 - Migration: schema changes for stored records are versioned.
 
+Workflow `timeoutMs` uses cooperative cancellation: ArkGate aborts the `AbortSignal`
+passed as the third `execute` argument, but JavaScript cannot stop an operation that
+ignores that signal. Production steps must pass it to network/database clients and keep
+external effects idempotent; otherwise work may finish after the workflow was marked failed.
+
 ## Interface Targets
 
 | Concern | Interface |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -66,9 +66,11 @@
     "dev": "tsup --watch",
     "test": "vitest",
     "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary",
     "typecheck": "tsc --noEmit",
     "security:audit": "npm audit --omit=dev --audit-level=high",
-    "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict-config",
+    "check:architecture": "node bin/ark-check.mjs --root . --config ark.config.json --strict",
+    "check:js": "node scripts/check-js-syntax.mjs",
     "generate:layer-match": "node scripts/generate-layer-match.mjs",
     "check:layer-match": "node scripts/generate-layer-match.mjs --check",
     "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
@@ -111,6 +113,7 @@
   "devDependencies": {
     "@nestjs/common": "^11.1.27",
     "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^3.2.6",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "2.10.0",
+  "version": "2.12.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "2.10.0",
+      "version": "2.12.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/templates/skills/ark-autopilot.md

@@ -1,38 +1,44 @@
 ---
 name: ark-autopilot
-description: End-to-end architecture co-pilot — exploratory map of the real project, then setup, deep plan from source, mechanical-safe fixes, and judgment design. CLI is a sensor; you read and remediate files.
+description: End-to-end architecture co-pilot — decision-grade explore first, dual plan (remediation + pattern improvements), mechanical-safe fixes, judgment design. CLI is a sensor; you read and remediate files.
 ---
 
 # /ark-autopilot — Get to a sound architecture, end to end
 
-Composes **explore + setup + plan + loop**. Safe default: auto-apply only `mechanical-safe`;
-when the user says full apply / “al mango” / apply everything, also execute
-**judgment** fixes you design from reading source (still validate with ark-check,
+Composes **explore → sensors → dual plan → loop**. Safe default: auto-apply only
+`mechanical-safe`; when the user says full apply / “al mango” / apply everything, also
+execute **judgment** fixes you design from reading source (still validate with ark-check,
 never weaken the gate).
 
+**Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
+the explore pass and dual-plan section B (pattern bets).
+
 
 ## Related onboarding
 
 - **Greenfield:** `/ark-architect` or `ark-check --recommend` / `ark start`.
 - **Brownfield:** `/ark-adopt` — match contract to reality; do not force a starter preset.
-- **Deep map only:** `/ark-explore` — reconnaissance without applying fixes.
+- **Deep map only:** `/ark-explore` — full recon report without applying fixes.
+- **Adoption metrics only:** `/ark-coverage` — governed% + capability gaps (feeds dual plan B).
 - **Default path:** `ark start` → `/ark-autopilot` → `ark-check --doctor`.
 
 ## Dual engine (mandatory)
 
 | Engine | Role |
 |--------|------|
-| **Deterministic** | `ark-check` plan/coverage/doctor, mechanical-safe kinds, write/CI gates, exit codes |
-| **Exploratory** | You map **this** product’s real tree: entry points, packages, coupling, false greens, opportunities |
+| **Deterministic** | `ark-check` plan/coverage/doctor, mechanical-safe kinds, write/CI gates, exit codes, origin snapshot |
+| **Exploratory** | You map **this** product’s real tree: entry points, coupling, false greens, field path, pattern debt |
 
-**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without reading the violating files **and** without a short product map.
+**Forbidden:** only printing `--plan` JSON or “4 safe / 4 judgment — approve?” without a
+decision-grade explore pass **and** without opening violating files.
 
 **Required:**
-1. **Explore pass** (below) before claiming a loop strategy.
-2. CLI sensor: `ark-check --plan --json`, coverage/doctor as needed.
-3. **Open every file** in the plan’s `steps[]` (and its `target` if present) before classifying a fix.
-4. **“Así te lo re-soluciono”** for each cluster: exact moves (extract type, relocate file, invert dependency).
-5. Apply → re-run ark-check → rollback on regression.
+1. **Explore pass** (below) **before** claiming a loop strategy — same bar as `/ark-explore`, budgeted.
+2. CLI sensors: `--plan --json`, `--coverage --json` / `--doctor` as needed.
+3. **Dual plan** always emitted (sections A and B).
+4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
+5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
+6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
 
 
 ## Subagent fan-out (optional, host-dependent)
@@ -52,64 +58,90 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
 5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
 
-## Explore pass (before grinding the plan)
+Useful first wave: **core product tree** | **field path** (examples/starters) | **agent install surfaces** (hooks vs templates).
+
+## Explore pass (phase 0 — mandatory, first)
 
-Do this even if the plan is non-empty — plan lists *violations*, not *product reality*.
+Do this **before** grinding plan A — plan lists *violations*, not *product reality*.  
+Use the **`/ark-explore` decision-grade bar** (compressed into the autopilot report, not optional fluff).
 
-1. **Product one-liner** — README + main package(s) + what the user gets.
-2. **Entry points** — apps, APIs, CLIs, workers (min paths named).
-3. **Lived layout** — which dirs are really Domain / Application / I/O / UI vs what globs claim.
-4. **False-green soft block** — doctor / coverage: empty Domain/Persistence while Application
-   globs still cover I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …).
-   Doctor gap id: `contract-false-green-io-under-application`. If so:
+1. **Headline** — product one-liner + honesty (mode, governed%, false-green / false-promise risk).
+2. **Map** — entry points, lived layout vs globs (one screen).
+3. **Field path** — if `examples/` / gallery / starter docs exist: open ≥2, **run** their check when cheap; flag soft-green or broken demos. Else `Field path: n/a`.
+4. **Agent/gate reality** — installed hooks vs install templates (e.g. `--hook` vs `--hook-repair`); MCP; CI gate present.
+5. **Coupling** — fan-in / exports / importers for hotspots (LOC alone is a hint).
+6. **False-green soft block** — doctor/coverage: empty Domain/Persistence while Application owns I/O (`airtable`, `supabase`, `prisma`, `drizzle`, `repositories`, …). Doctor gap id: `contract-false-green-io-under-application`. If so:
    **STOP — do not continue this skill as complete.** **STOP — false-green: invoke /ark-adopt or /ark-contract before claiming ENFORCE.** Do not claim goal.met / ENFORCE from type-only cleanup while doctor reports `contract-false-green-io-under-application`.
-5. **Suggestive top bets** — 2–5 opportunities ranked (shape, extract, manifiesto, gates/DX),
-   separate from mechanical-safe steps. User may defer; still list them.
+7. **Seed dual plan B** — 2–5 pattern / evolution bets ranked (impact × effort × enforceability).
+
+Min bar: **≥12 source files** across **≥4 meaningful directories** (not only files in `steps[]`).  
+Standalone long report: `/ark-explore`. Adoption numbers deep-dive: `/ark-coverage`.
+
+## Dual plan (always emit)
+
+| Section | Source | Question | Auto-apply? |
+|---------|--------|----------|-------------|
+| **A. Remediation** | `--plan --json` + opened step files | What must change so the gate is honest? | Only `mechanical-safe` by default |
+| **B. Pattern / evolution** | Explore + coverage/doctor | What existing patterns should improve even if A is empty? | **Never** as mechanical-safe |
+
+**Section A** — group by edge; treat `peerIsolation` / cross-slice as **judgment**.  
+**Section B** examples: peerIsolation, move rules out of UI, strengthen starter/preset rules, write-path repair, split god orchestration modules, Domain placement / intents, import surface (`/runtime` vs root). Cap **3–5** B rows. Each row: evidence path + **así te lo re-soluciono** + next skill/command + success signal.
+
+B does **not** count as “architecture healthy finished.” Report B as `proposed | deferred | applied-with-user-ok`.
 
-Min bar: **≥8 source files** across **≥3 meaningful directories** (not only files in `steps[]`).
+## Origin snapshot (day-zero picture)
 
-For a full reconnaissance report, run or fold in `/ark-explore`.
+- **When:** as soon as `ark.config.json` exists and `.ark/reports/origin.json` is missing — **before** applying fixes and **before** treating “done”. Prefer that `ark start` / `ark init` already froze origin **before** agent docs; if missing, freeze now.
+- **How:** `ark-check --report ark-report.html` (writes origin once under `.ark/reports/`).
+- **Never** `--reset-origin` unless the user explicitly wants a new baseline.
+- **Do not** wait until the end of the loop to create origin the first time — later reports need a frozen “before” picture.
+- End of run: re-`--report` for **latest** + evolution vs origin (origin stays frozen).
 
 ## Operating modes (detected, not picked)
 
-- **Setup (Suggest):** no config → `ark start` / recommend shape.
+- **Setup (Suggest):** no config → `ark start` / recommend shape (start freezes origin after config, before gates).
 - **Align (Adapt):** open debt, low honesty, or false-green → explore + adopt/loop; do not claim “guarded”.
-- **Guard (Enforce):** `goal.met`, solid governed%, no false-green → install/confirm gates and stop.
+- **Guard (Enforce):** `goal.met`, solid governed%, no false-green → confirm gates; still emit dual plan B if explore found residual.
 
 ## Flow
 
-0. **Explore pass** — product map + false-green check + suggestive bets (see above).
+0. **Explore pass** — decision-grade recon (see above); seed plan B.
 1. **Setup if needed** — `ark start` if no `ark.config.json`. Trust `--recommend` / playbook:
    `vertical-slice-product` and `ddd-bounded-contexts` are first-class shapes (not hexagonal by default).
-2. **Origin report** — `ark-check --report ark-report.html` (do not `--reset-origin` unless asked).
-3. **Plan + code read** — `--plan --json`; read each step’s source/target; group by edge.
-   Treat `peerIsolation` / cross-slice steps as **judgment** (never mechanical-safe).
-4. **Concentrated edge?** — if one edge dominates:
+2. **Origin if missing** — freeze day-zero (`--report`) immediately after contract exists.
+3. **Sensors** — `--plan --json`, doctor/coverage as needed.
+4. **Emit dual plan** — A from plan steps (files opened); B from explore (3–5 bets).
+5. **Concentrated edge?** — if one edge dominates A:
    **STOP — do not continue this skill as complete.** **STOP — concentrated edge: invoke /ark-contract with source evidence** (do not freeze a wrong contract or grind N freezes).
-5. **Worktree preferred** — discardable git worktree when possible.
-6. **Mechanical-safe** — only kinds from `/ark-loop` table; one step, validate, rollback.
-7. **Judgment** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement the designed fix, validate, rollback on fail.
-8. **Manifiesto** — if loose business rules surface (domain logic in UI/core), propose Domain placement + `intentPrefixes` / intents; apply config only via `/ark-contract` discipline (strict check after).
-9. **Final report** — re-`--report`; evolution vs origin; **explore bets** still open vs auto vs judgment applied vs deferred.
-10. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
-11. **Core ratchet (when green)** — if plan `goal.met` and doctor still **ADAPT** only because
+6. **Worktree preferred** — discardable git worktree when possible.
+7. **Mechanical-safe (A only)** — kinds from `/ark-loop` table; one step, validate, rollback.
+8. **Judgment (A)** — default: propose with full “así te lo re-soluciono”. If user authorized full apply: implement, validate, rollback on fail.
+9. **Pattern bets (B)** — propose; apply only with explicit user go + correct skill (`/ark-contract`, refactor, install gates, etc.). Never weaken the gate to clear B.
+10. **Manifiesto** — loose business rules → Domain placement + `intentPrefixes` / intents via `/ark-contract` discipline.
+11. **Final report** — re-`--report`; evolution vs origin; A applied vs open; B proposed/deferred; gates on.
+12. **Strict check** — `ark-check --strict-config` (dead preset globs are advisory; real violations still fail).
+13. **Core ratchet (when green)** — if plan `goal.met` and doctor still **ADAPT** only because
     populated cores are `optional: true`, run `ark-check --ratchet-cores` then `--doctor`.
     Never ratchet while active violations remain or false-green gap is open.
 
 ## Never
 
 - Disable rules, broaden allows, or baseline **new** debt to “finish”.
-- Claim clean while judgment steps were skipped without user decision.
+- Claim clean while judgment A steps were skipped without user decision.
 - Claim ENFORCE / “done” when doctor reports `contract-false-green-io-under-application` (adopt first).
+- Claim “done” solely because plan A is empty while explore/B residual remains unlisted.
 - Replace host Nest/DI with the runtime kernel unasked.
-- Treat “plan empty” as “architecture is healthy” without the explore pass.
+- Auto-apply pattern (B) bets as if they were mechanical-safe.
+- Create origin only after a long cleanup (freezes a polished “before” that never was).
 
 ## Done criteria
 
-- Explore pass completed (product map + paths read + bets listed).
-- Every applied step validated by real `ark-check`.
-- Final plan `goal.met` true **or** remaining steps listed with file-level proposals and why blocked.
-- Report cites paths you changed, open **opportunities**, and report HTML paths.
+- Explore pass completed (decision-grade map + paths + field path or n/a + B seeds).
+- Dual plan emitted (A and/or B; if both empty, one-line justification).
+- Origin present under `.ark/reports/origin.*` (frozen this run or earlier).
+- Every applied A step validated by real `ark-check`.
+- Final plan `goal.met` true **or** remaining A steps listed with file-level proposals.
+- Open **B opportunities** listed; report HTML paths cited.
 
 ## Completion contract (skill incomplete if missing)
 

package/templates/skills/ark-explain.md

@@ -37,7 +37,8 @@ the same files or weaken the gate.
    (`pnpm … exec ark-check` / `yarn` / `npx`).
 
    This also maintains snapshots under **`.ark/reports/`**:
-   - `origin.json` / `origin.html` — frozen **first** report (start of the journey)
+   - `origin.json` / `origin.html` — frozen **day-zero** report (`ark start`/`ark init`
+     freezes this **right after** `ark.config.json`, before agent docs/CI templates)
    - `latest.json` / `latest.html` — every run
    - `history/*.json` — last ~20 machine-readable points for later tooling