arkgate 3.6.1 → 3.8.0

package/README.md

@@ -16,9 +16,14 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 3.6.1** is current stable: Codex MCP configuration is project-scoped, doctor
-> recognizes the effective project binding, and stale agent worktrees no longer become
-> permanent global MCP owners. [Release notes](docs/releases/3.6.1.md).
+> **ArkGate 3.8.0** is current stable: complete analysis fails closed, complete candidates share
+> one resolved architecture verdict, managed upgrades are digest-bound, and an opt-in design-delta
+> ratchet blocks new or worsened UI domain logic. [Release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.0.md).
+
+> **TypeScript 7 distribution note:** ArkGate prefers a usable project compiler API, then its
+> exact, physically distinct TypeScript 6 analysis host. Analysis reports required
+> `complete | partial | unavailable` status; incomplete results cannot look green. See the
+> [exact boundary](docs/typescript-support.md).
 
 ---
 
@@ -42,7 +47,7 @@ If you remember nothing else:
 | **Messy / spaghetti code** (even if the gate is green) | **`/ark-explore`** then **`/ark-autopilot`** — [below](#less-spaghetti-after-the-gate-is-green) |
 | New ArkGate version | `/ark-upgrade` |
 
-**Everything else is optional.** You do not need to learn “modes”, 11 skills, or the runtime
+**Everything else is optional.** You do not need to learn “modes”, the full skill pack, or the runtime
 kernel to get value. The compact router is enough for normal work; install `/ark-autopilot` only
 when you want the full guided workflow.
 
@@ -207,6 +212,11 @@ project file is written. With `--change-map map.json` (or MCP `changeMap`), the
 classifies planned structure as satisfied, missing, contradictory, or unplanned. This is structural
 convergence only: behavioral completion is always reported as not evaluated.
 
+ArkGate 3.8.0 closes the former compiler-free atomic-path divergence with versioned
+resolved-candidate facts and a differential adapter corpus, including `tsconfig` aliases and
+workspace edges. Strict CI remains the final merge boundary; lexical/single-snippet feedback is
+explicitly partial and non-green.
+
 Every blocking diagnostic carries stable rule/location/evidence fields plus one deterministic
 `nextAction`; human CLI/hook text prints that same action. A complete Codex `ApplyPatch` payload is
 reconstructed and sent through the same atomic engine before per-file safety checks. Codex remains
@@ -244,6 +254,8 @@ Brownfield phases: **Align** (honest contract) → **Stabilize** (real baseline)
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair payloads never write code silently: the host must re-inject the candidate and ArkGate revalidates it. Run `arkgate-check --doctor` for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
 
+Assets stay non-hard without fresh covered-operation evidence; MCP stays advisory.
+
 #### Why the hard guarantee lives at the merge gate
 
 The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
@@ -285,17 +297,34 @@ ark.config.json
   writes those exact bytes. Full skills remain explicit via `--install-agent-gates --skills-only`;
   reports remain opt-in via `ark-check --report`.
 - **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.
-- **Enforcement ladder (Phase T):** doctor JSON exposes `writePath.enforcementLadder` with separate
-  `supported`, `installed`, `active`, `bypassable`, evidence, operation coverage, and required-status
-  honesty. Hook repair JSON carries the operation-scoped ladder; MCP alone remains advisory.
+- **Enforcement state:** doctor JSON exposes schema-backed `writePath.enforcementState` with
+  separate analyzed, configured, installed, runtime-observed, operation-coverage, active,
+  bypassable, required, and hard evidence for local write, advisory MCP, and CI merge boundaries.
+  Provider-unavailable required status remains `unverified`; local workflow text never proves
+  branch protection. The older
+  `enforcementLadder` projection remains for compatibility.
+- **Opt-in design delta (Z10):**
+  `--doctor --fail-on-new-smells --base-ref <ref>` blocks only new/worsened semantic
+  `domain-logic-in-ui`; historical/unrelated work stays green and missing bases fail closed.
 - **Fail-closed CI (2.11):** `--strict-merge` combines config coverage, shared gate-file
   presence, and bypass diagnostics for dynamic imports, TypeScript suppressions, explicit `any`
   casts, InMemory runtime defaults, and disabled peer isolation. `--strict` is a compatibility
   alias. Neither requires an editor hook; use `--require-write-hook claude|grok` when that local
   guarantee is part of the check.
+- **Resolved analysis + completeness (3.8.0):** schema 1.3 identifies
+  `resolved-candidate-facts` versus `lexical-compatibility`, requires structured incompleteness
+  reasons, and exposes policy/resolver/facts/tree identities for resolved results. Single-file
+  lexical checks are explicitly `partial`/non-green; governed parse diagnostics also make plan
+  `goal.met: false` and normal JSON `valid:false`/`ok:false`. Strict merge exits `1`; a missing
+  host is `unavailable` and exits `2`.
 - **Release evidence:** independent 3.0 audit baseline plus signed-tag, GitHub Release, and
-  provenance-backed npm publication; see the [3.1.0 release notes](docs/releases/3.1.0.md).
-- **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)).
+  provenance-backed npm publication; see the [3.1.0 release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.1.0.md).
+- **TypeScript:** 3.8.0 passed all 36 packed compatibility cells for project
+  compilers 5.9.3 / 6.0.3 / 7.0.2 across npm, pnpm, and Yarn. ArkGate prefers a usable project
+  API, then its exact `typescript-ark-host@6.0.3`; the project `tsc` remains project-owned.
+  Yarn uses strict PnP for TS5/6 and the `node-modules` linker for native TS7; that mode is explicit
+  in the report. See the exact boundary in
+  [docs/typescript-support.md](docs/typescript-support.md).
 
 ### Why not only ESLint / dependency-cruiser / Nx?
 
@@ -307,9 +336,10 @@ ark.config.json
 | Placement tools (`ark_place`, …) | ✅ | ❌ |
 | Honest governed % + adoption path | ✅ | ❌ |
 | Classified plan (`mechanical-safe` / judgment) | ✅ | ❌ |
-| TypeScript 5 / 6 / 7 project compilers | ✅ | varies |
+| TypeScript 5.9 / 6.0 / 7.0 packed consumers | ✅ (3.8.0; 36/36 packed CI cells) | varies |
+| Incomplete analysis can satisfy plan/result/strict merge | ❌ (`partial` / `unavailable` fail closed) | varies |
 | Adoption scorecard (hosts / MCP / origin) | ✅ | ❌ |
-| **Editor ESLint same layer contract as CI** | ✅ (`arkgate/eslint`) | varies |
+| **Editor ESLint on-disk relative-import parity; resolved CI backstop** | ✅ (`arkgate/eslint`) | varies |
 
 ---
 
@@ -322,7 +352,8 @@ npx arkgate start --tools codex --apply   # select the host explicitly
 npx arkgate start --install --apply       # also add arkgate to package.json (explicit only)
 npx arkgate start --remove-host codex     # preview compact-host removal; add --apply to confirm
 npx arkgate-check --doctor                # health + Adoption gaps (not just fitness)
-npx arkgate-check --doctor --json         # adoption + explicit writePath.enforcementLadder
+npx arkgate-check --doctor --json         # adoption + schema-backed writePath.enforcementState
+npx arkgate-check --doctor --fail-on-new-smells --base-ref origin/main  # opt-in design ratchet
 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%
@@ -330,9 +361,15 @@ npx arkgate-check --report ark-report.html  # showcase HTML (opens in browser on
 npx arkgate-check --baseline              # only NEW violations fail
 npx arkgate preflight --changes changes.json --json  # atomic read-only batch verdict
 npx arkgate preflight --changes changes.json --change-map map.json --json  # intent hash + structural convergence
-npx arkgate upgrade                       # package + gates/skills + MCP/Codex normalize
+npx arkgate upgrade --json                # read-only managed-content preview + planDigest
+npx arkgate upgrade --apply               # update package, then re-preview with the new CLI
+# run the emitted nextCommand to apply only that preview, including --plan-digest
 ```
 
+Managed upgrade records content identities in `ark.managed.json`, preserves customized and
+unrelated files, and requires explicit consent for recorded deletions or conflicts. It never
+rewrites a Codex home or another global directory implicitly.
+
 CI (example):
 
 ```yaml
@@ -355,6 +392,9 @@ import { createStrictArkKernelFromConfig } from '@arkgate/runtime';
 
 The stable `arkgate` package does not bundle runtime implementation. The deprecated
 `arkgate/runtime` forwarding shim requires `@arkgate/runtime` and is removed in ArkGate 4.
+The companion is not currently present in the npm registry and the root release workflow does
+not publish it; the import above documents the intended boundary. Source-checkout evaluation
+requires `npm run build:runtime` followed by installing the local `packages/runtime` folder.
 
 NestJS: `@arkgate/runtime/nestjs` (optional peer `@nestjs/common`).
 
@@ -374,16 +414,16 @@ for real systems. Details: [production-hardening.md](https://github.com/pedrokni
 |----------|------|
 | New builders (plain language) | [docs/enthusiast/](docs/enthusiast/README.md) |
 | **Package surface and configuration** | [package policy](docs/package-surface.md) · [contract](docs/configuration.md) |
-| Wire agents + **ESLint (CI-parity)** | [docs/ai-gates.md](docs/ai-gates.md) · [threat model](docs/threat-model.md) |
-| **TypeScript 5 / 6 / 7 support** | [docs/typescript-support.md](docs/typescript-support.md) |
+| Wire agents + **ESLint (bounded parity)** | [docs/ai-gates.md](docs/ai-gates.md) · [threat model](docs/threat-model.md) |
+| **TypeScript 5 / 6 / 7 support + analysis completeness** | [docs/typescript-support.md](docs/typescript-support.md) |
 | Migrate from `ark-runtime-kernel` | [docs/migrate-from-ark-runtime-kernel.md](https://github.com/pedroknigge/arkgate/blob/main/docs/migrate-from-ark-runtime-kernel.md) |
 | Messy existing repo | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Agent / MCP tools | [docs/agent-guide.md](docs/agent-guide.md) |
 | Security reporting | [SECURITY.md](SECURITY.md) |
-| Demos | [docs/demos/](docs/demos/) |
-| Examples | [examples/](examples/README.md) |
-| Latest release (3.6.1) | [release notes](docs/releases/3.6.1.md) · [3.0.0 baseline](docs/releases/3.0.0.md) |
-| Roadmap and decisions | [ROADMAP.md](ROADMAP.md) · [ADRs](docs/adr/) · [Changelog](CHANGELOG.md) |
+| Demos | [docs/demos/](https://github.com/pedroknigge/arkgate/tree/main/docs/demos) |
+| Examples | [examples/](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md) |
+| Latest release (3.8.0) | [release notes](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.0.md) · [3.0.0 baseline](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.0.0.md) |
+| Roadmap and decisions | [ROADMAP.md](https://github.com/pedroknigge/arkgate/blob/main/ROADMAP.md) · [ADRs](https://github.com/pedroknigge/arkgate/tree/main/docs/adr) · [Changelog](CHANGELOG.md) |
 
 ---