arkgate 3.7.0 → 3.8.0

package/docs/package-surface.md

@@ -17,46 +17,127 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
 | **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. |
+| **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Doctor design fitness (P02+)** | `ark-check --doctor --json` → `doctor.designFitness`, `doctor.designSmells[]` | Additive. Stable smell `id`s: `io-under-application`, `handler-in-persistence`, `god-module`, `domain-logic-in-ui`, `facade-sql-in-routes`, `mixed-pattern-cluster`, `soft-contract`. Y02 extends `handler-in-persistence` to static ES imports/re-exports of framework HTTP surfaces (`next/server`), `defineRoute` calls, and existing handler bodies inside Persistence-role layers or specific persistence paths; `require()` and dynamic `import()` are outside this narrow advisory, and a generic `Infrastructure` role alone is not Persistence. Persistence candidates are filtered and sorted before the bounded content scan so large application prefixes cannot hide the advisory. The detector inspects the first 800 sorted Persistence candidates; later candidates are uninspected, so absence of this advisory is not whole-tree proof above that envelope. Each smell has `evidence[]`, `fix`, technical `message`, and plain-language **`outcome`** (Q02). Does **not** fail the gate by itself. |
 | **Post-green path (Q01)** | `doctor.postGreenPath`, `doctor.primaryNextAction`, `doctor.healthyFinishedForbidden` | Additive when `designFitness.designWeak`. Single Shape door (`id: clarify-for-ai`): explore shape-focus → dual-plan B → autopilot only with OK. Never empty plan A = healthy finished. |
 | **Golden pattern (Q03)** | Optional `.ark/golden-pattern.json`; doctor JSON `doctor.goldenPattern`; MCP `ark_place` / `ark_prepare_write` → `goldenPattern` | Additive, **advisory for NEW code only**. Required fields: `name`, `norm`; optional `newCodeHome`, `examplePath`, `schemaVersion`. **Absent is normal** (no claim). Never ENFORCE; never clears design-weak. Malformed → `invalid: true`, not silent guidance. |
 | **Plan pattern B (P03+)** | `ark-check --plan --json` → `plan.patternBets[]`, `plan.goal.designWeak` | Additive. Each bet: `id`, `smellId`, `pilot`, `evidence`, `successSignal`, `killSwitch`, **`neverMechanicalSafe: true`**, `class: "judgment"`. **Never** auto-applied by loop/autoPatch; not a `remediationKind` mechanical-safe. `goal.met` remains edge honesty only. |
 | **Pilot loop (Q04)** | `plan.pilotLoop` / `doctor.pilotLoop` | Additive. When design-weak: `active`, `oneAtATime`, `neverMechanicalSafe`, **`nextPilot`** extraction-card fields (`pilotTarget`, `smellId`, `move`, `successSignal`, `killSwitch`, `doNot[]`). **One pilot → re-doctor**; never multi-pilot batch; never mechanical-safe. |
-| **AI-velocity eval (Q05)** | `npm run eval:ai-velocity` → `eval/ai-velocity-report.json` | Fixture-measured (no live LLM). Same feature scenario on design-weak vs golden-path arms; metric **`placementTurns`** (agent-equivalent). Golden must be strictly better. Method string lives next to the number. Does not weaken the gate. |
+| **AI-velocity eval (Q05)** | Repository-only evidence: `npm run eval:ai-velocity` → `eval/ai-velocity-report.json` | Fixture-measured (no live LLM). Same feature scenario on design-weak vs golden-path arms; metric **`placementTurns`** (agent-equivalent). Golden must be strictly better. Method string lives next to the number. Does not weaken the gate. |
 | **Contract health (W01)** | `ark-check --doctor --json` → `doctor.contractHealth`; optional `.ark/contract-smell-acks.json` | Additive, **advisory only** — meta-lint of the contract itself (layer-name heuristics; imprecision costs a warning line, never a verdict); never changes the verdict, `designFitness`, or `patternBets`. Stable smell ids: `contract-bidirectional-allow`, `contract-peripheral-depends-core`, `contract-lateral-adapter-allow`, `contract-dead-rule`; each smell has `severity`, `evidence[]` (sorted, honest `…(+N more)` truncation), `fix`, `message`, plain-language `outcome`, and `acknowledgedEdges` (acks applied to that id). **X03/X06**: the lateral smell does not fire on an adapter reaching its **own family's infra base** — the target reads `<Family><InfraWords…>` (**every** remaining target token an infra word: `Infra(structure)`/`Base`/`Core`/`Shared`/`Common`/`Kernel`/`Platform`/`Foundation`) and the source carries the family token **anywhere** in its name (X06, field: `HoursPersistenceAdapters -> PersistenceInfrastructure` — mid-name families). `PaymentsCoreAdapters` is still a sibling; cross-family edges, non-infra siblings, and the reverse (base → member) still fire. Acknowledgments live in the bounded sidecar (`{ acks: [{ id, edge, reason, reviewBy? }] }`, ≤64 KB / ≤200 entries; bidirectional edges order-insensitive, exact two segments); `contractHealth.acknowledged` counts **applied** acks only (stale acks count 0). **X02 ack lifecycle**: optional `reviewBy` (`YYYY-MM-DD`, strict round-trip validation — `2026-02-30` is malformed) — past the date the ack **stops applying** and the smell returns with `(ack expired …)` annotated evidence; among dated entries a fresh re-ack wins over a dead one, but once ANY dated ack exists for an edge the dated entries govern — a leftover undated duplicate cannot resurrect an expired exception. `detectContractSmells` defaults `today` to the real clock (pass `null` to disable expiry); `analyzeContractSmells` stays pure (clock injected). `contractHealth.ackLifecycle` reports `{ undated, malformed, expiredCount, expired[], staleCount, stale[] (lists capped at 12) }`; undated acks apply (backward compatible) but surface in doctor, report, and the fossilization note even when every smell is suppressed. **X05**: an ack matching **no detected edge** (orphaned by a fixed contract or quieted heuristic, unknown id, or typo'd edge) is `stale` — it suppresses nothing and doctor/report list the exact entries to fix or delete, even at zero visible smells. Malformed `reviewBy` never applies (fail-loud, like a sloppy edge); non-string `reviewBy` → whole file `invalid`. **Absent is normal**; malformed file or edge grammar → ignored + `ackFile.invalid` where applicable, never silent suppression. |
-| **Effect capabilities (U03/Y08)** | Analysis API `collectCapabilityUses(ts, sourceFile)` + Domain vocabulary (`CAPABILITY_IDS`, `capabilityForModuleSpecifier`, `capabilityForAmbientName`, `forbiddenGlobalForModuleSpecifier`, `lowerForbiddenGlobal`); pure-engine `ir.capabilityUses` | Additive within IR `1.0`. Seven **closed** ids: `network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence` (ADR 0009). Direct evidence only — transitive inference never detects. The symbol-aware collector covers ambient globals (shadowing/type-only/globalThis-alias precision from the S05/C04 machinery) plus imports; the compiler-free IR engine carries **import-based** uses only (exact module or subpath match, never substring; textual `import type`/`export type` erasure — ANY braced named-binding list stays a value import there; template-literal bodies are skipped entirely (specifiers inside `${…}` are the symbol path's job); `require(…)` counts as capability evidence but never creates a graph edge on the pure path). **U04 walls are opt-in:** per-layer `capabilities: { deny: [...] }` or the dual-depth sugar `pure: true` (denies all seven); absence changes no verdict. `CAPABILITY_VIOLATION` is judgment-class (never mechanical-safe) with a port-injection `nextAction`; D7 dedup — evidence already owned by the layer's `forbiddenGlobals` reports only `FORBIDDEN_GLOBAL`. Y08 adds one deliberately narrow import dual: `forbiddenGlobals: ["process"]` owns exact value imports of `process` and `node:process`, but not subpaths or `child_process`; statement-level `import type` / `export type` remains erased on every path (the existing pure-IR all-named limitation above is unchanged). Atomic preflight blocks denied capabilities and that exact dual across a complete multi-file candidate (import-based on the pure path; other ambient evidence adds on the symbol-aware CLI/hook path). T01 policy-delta classifies the surface on **coverage atoms** (`ambient:<entry>` prefix-expanded, narrow `import-exact:<specifier>` duals, and `import:<capability>` for a complete wall): any lost atom is weakening (`fetch`→`XMLHttpRequest`, `Date`→`Date.now`, wall→fg all weaken; finding path `$.layers[name].capabilities`); fg → equivalent-or-stronger wall never needs an acknowledgment; unlowerable custom globals keep raw key comparison. |
+| **Effect capabilities (U03/Y08)** | Public root API: `analyzeProject(...).ir.capabilityUses`; the CLI/hook adapters add symbol-aware ambient evidence internally | Additive within IR `1.0`. Seven **closed** ids: `network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence` (ADR 0009). `collectCapabilityUses` and the Domain vocabulary are internal implementation exports, **not** exports from `arkgate`; the related public low-level helper is `collectForbiddenCapabilityUses`. Direct evidence only — transitive inference never detects. The symbol-aware adapter path covers ambient globals (shadowing/type-only/globalThis-alias precision from the S05/C04 machinery) plus imports; the compiler-free IR engine carries **import-based** uses only (exact module or subpath match, never substring; textual `import type`/`export type` erasure — ANY braced named-binding list stays a value import there; template-literal bodies are skipped entirely (specifiers inside `${…}` are the symbol path's job); `require(…)` counts as capability evidence but never creates a graph edge on the pure path). **U04 walls are opt-in:** per-layer `capabilities: { deny: [...] }` or the dual-depth sugar `pure: true` (denies all seven); absence changes no verdict. `CAPABILITY_VIOLATION` is judgment-class (never mechanical-safe) with a port-injection `nextAction`; D7 dedup — evidence already owned by the layer's `forbiddenGlobals` reports only `FORBIDDEN_GLOBAL`. Y08 adds one deliberately narrow import dual: `forbiddenGlobals: ["process"]` owns exact value imports of `process` and `node:process`, but not subpaths or `child_process`; statement-level `import type` / `export type` remains erased on every path (the existing pure-IR all-named limitation above is unchanged). Atomic preflight blocks denied capabilities and that exact dual across a complete multi-file candidate (import-based on the pure path; other ambient evidence adds on the symbol-aware CLI/hook path). T01 policy-delta classifies the surface on **coverage atoms** (`ambient:<entry>` prefix-expanded, narrow `import-exact:<specifier>` duals, and `import:<capability>` for a complete wall): any lost atom is weakening (`fetch`→`XMLHttpRequest`, `Date`→`Date.now`, wall→fg all weaken; finding path `$.layers[name].capabilities`); fg → equivalent-or-stronger wall never needs an acknowledgment; unlowerable custom globals keep raw key comparison. |
 | **Ambient state (U05)** | `ark-check --doctor --json` → `doctor.ambientState`; optional `.ark/ambient-state-acks.json` | Additive, **advisory only and opt-in**: only layers declared `pure: true` are scanned; the MVP shape is module-scope `let`/`var`. Findings carry `file`/`line`/`name`/`kind` (sorted, capped with honest `truncated` count). Acknowledgments live in the bounded sidecar (`{ acks: [{ file, name, reason }] }`, ≤64 KB / ≤200 entries); `acknowledged` counts applied acks; malformed file suppresses nothing. When TypeScript is unavailable the sensor reports `available: false` instead of guessing. **No strict mode exists** — A5: strictness requires a completed corpus and an explicit later decision. |
-| **Parse health (Y03)** | `ark-check --doctor --json` → `doctor.parseHealth`; report section `data-advisory="parseHealth"` | Additive, **advisory only**. The existing architecture AST contributes only `parseDiagnosticCount` per governed file (cache schema v9, bound to the TypeScript parser version; no raw diagnostics, second parse, or `tsc`). JSON reports `scannedFiles`, `affectedFiles`, `diagnosticCount`, deterministic top-12 `{ file, diagnosticCount }` entries, and honest `truncated`/`overflow`; missing/unsafe counts or unavailable scan evidence produce `available: false`, never a clean claim or a non-JSON-safe number. Parse health never changes the verdict, `ok`, violations, `designFitness`, or `patternBets`. |
+| **Parse health + analysis completeness (Y03/Z02)** | `ark-check --doctor --json` → `doctor.parseHealth` + `doctor.completeness`; check JSON → `completeness`; report section `data-advisory="parseHealth"` | The resolved candidate facts contribute only `parseDiagnosticCount` per governed file (no raw diagnostics, second parser pass, or `tsc`). Z04's correctness path ignores legacy v9 caches and parses the complete candidate on every invocation; Z07 owns any future identity-keyed warm snapshot. Doctor remains diagnostic: parse health adds no architecture violation and does not change `designFitness` or `patternBets`. Verdict surfaces consume the evidence fail-closed: affected governed files mean `partial`, plan `goal.met: false`, normal JSON `valid:false`/`ok:false`, and strict merge exit `1`; the non-strict process exit remains advisory for compatibility. No usable host means `unavailable`, plan false, and CLI exit `2`. JSON reports `scannedFiles`, `affectedFiles`, `diagnosticCount`, deterministic top-12 `{ file, diagnosticCount }` entries, and honest `truncated`/`overflow`; missing/unsafe evidence never becomes a clean claim. |
 | **Physical cohesion + reshape pilot (X04/Y01)** | `ark-check --doctor --json` → `doctor.physicalCohesion` (`reshapePilot`, `reshapeDecisions`); optional `.ark/reshape-decisions.json`; report section `data-advisory="physicalCohesion"` | Additive, **advisory only** — `notAScore`; never feeds the verdict, `designFitness`, or `patternBets`. Signal is **concentration, not volume**: concept clusters per anchor directory (deterministic path/name tokenization; framework filenames like `route.ts` take the topmost meaningful path segment — ADR 0010 D2). Fixed corpus-calibrated thresholds (`maxCluster ≥ 40` OR ≥2 anchors ≥ 20, ADR 0010 D3); findings ranked and capped (top 5, honest `truncated`). Anchors under `app/`/`pages/` are `fixedByConvention` and never move (D7). `reshapePilot` is **proposed, never applied** (`neverMechanicalSafe`): one Q04-style pilot card at a time targeting the smallest convention-free anchor, with `moveSample`/`movesTotal`, `successSignal`, `killSwitch`, `doNot[]`; real moves run only through the write gate + atomic preflight via `/ark-loop`; merges are `/ark-architect` judgment cards, never a codemod (D6). **Y01 verdict memory:** bounded sidecar `{ schemaVersion?: "1", decisions: [{ concept, anchors, verdict: "accepted"|"deferred"|"rejected", reason, reviewBy? }] }` (≤64 KiB / ≤200 unique targets). Identity is concept + complete sorted anchor set, never counts/change-map evidence. Current rejected/deferred records suppress pilot pressure only; accepted keeps the existing path. Expired/malformed/stale/invalid records suppress nothing; lifecycle and decisions render in doctor/report. Explicit only — golden-pattern prose never infers a verdict. |
 | **Capability walls, every adapter (U04+U06)** | CLI scan, pure IR engine, atomic preflight, `ark-mcp --hook` / MCP gate (`capabilityWalls`), ESLint `ark/no-denied-capabilities` | The same opt-in deny set enforces across every surface: hook/MCP and CLI cover ambient + import evidence (symbol-aware); the pure engine, preflight, and ESLint cover the import dimension (documented envelope). Dual depth everywhere: plain port hint (`FIX_HINTS`/`suggestion`) + stable JSON (`ruleId`, `capability`, `fixClass: inject-port`, deterministic `nextAction`). |
-| **Hook-path budgets (U06)** | `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
+| **Hook-path budgets (U06)** | Repository-only evidence: `npm run bench:hook-path`; `eval/performance/hook-budgets.v1.json`; CI job "Hook-path end-to-end budgets" | Measures the COMPLETE pre-tool paths as fresh child processes (hook cold/warm, doctor cold) at 1k/10k. D5 method locked: ceilings are Linux-baseline p95 + fixed headroom, set once per cycle, never ratcheted; scenarios without a recorded baseline stay in RECORDING mode and cannot fail CI. |
 | **Governance weight (W02)** | `ark-check --doctor --json` → `doctor.contractHealth.governanceWeight` | Additive, **advisory only** — raw facts (`declaredLayers`, `populatedLayers`, `governedFiles`, `rules`, `deniedEdges`, `allowedEdges`, `filesPerLayer`, `rulesPerLayer`) plus a fixed comparative band `weight: heavy | typical | light | unknown` and its fixed `note`. Fixed deterministic thresholds: **heavy** = fewer than 25 governed files per declared layer AND (6+ layers OR 4+ well-formed rules per layer); **light** = at most 2 layers over 150+ governed files; **unknown** = no layers or no governed files; everything else is **typical** (banding uses raw ratios; the reported ratios are rounded for display). `notAScore: true` is explicit: never a composite score, ranking, or gate input; the heavy note asks to justify NEW layers/rules and never suggests deleting working ones. Human doctor prints a line only for `heavy`/`light`. |
 | **Report parity (X01)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth"`, nested `governanceWeight`) + layer wall badges | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. |
 | **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, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. |
 | **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
 | **Atomic change preflight (T02, 3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
-| **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
+| **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
 | **Structural convergence (T04, 3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
 | **Enforcement ladder + fixed journey (T05, 3.1.0)** | `doctor.writePath.enforcementLadder`; hook repair `enforcement`; `npm run eval:change-integrity` | Additive schema `1.0` separates supported/installed/active/bypassable state and evidence. Hard is operation-scoped only for a supported covered hook; MCP is advisory; required CI status stays unverified locally. Fixed no-context fixture proves CLI/MCP/hook/final parity, one casual denial, acceptance behavior, and strict Ark. |
-| **`arkgate/schema/analysis-result`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `valid`, `diagnostics`) | Schema `1.1` adds optional `nextAction`; the `1.0` fixture and consumer-owned TypeScript diagnostics remain valid. |
+| **Enforcement state (Z06/Z10)** | `doctor.writePath.enforcementState`; schema/type | Schema `1.1`: runtime observation, operation coverage, and operation-scoped `hard`. Only fresh covered active-host evidence permits `hard:true`; unverified assets and MCP remain non-hard. |
+| **Design delta (Z10)** | `--fail-on-new-smells --base-ref <ref>`; hook/MCP; schema/types | Schema `1.0`: identities, touched paths, stable evidence/verdict. Missing base fails closed; only new/worsened `domain-logic-in-ui` blocks; global doctor smells stay advisory. |
+| **`arkgate/schema/analysis-result`** or **`arkgate/schema/ark.analysis-result.schema.json`** | Public CLI/MCP/hook diagnostic envelope (`schemaVersion`, `mode`, `valid`, `completeness`, `completenessReasons`, `diagnostics`, resolved identities) | Schema `1.3` distinguishes `resolved-candidate-facts` from `lexical-compatibility`; partial/unavailable analysis is always non-green, and resolved complete/partial results require policy/resolver/facts/tree identities. `1.2` added completeness and remains accepted alongside consumer-owned 1.0/1.1 values. |
+| **`arkgate/schema/resolved-candidate-facts`** or **`arkgate/schema/ark.resolved-candidate-facts.schema.json`** | Versioned parity-capable input for `analyzeResolvedProject` / `preflightResolvedChange` | Schema `1.0` is serializable and deterministic. Tooling owns filesystem/compiler resolution; Domain/Kernel validate and evaluate supplied facts without importing those effects. Facts name resolver/compiler inputs, governed files, dependency evidence, completeness reasons, and candidate tree/facts hashes. |
 | **Config JSON Schema** | `arkgate/schema` or `arkgate/schema/ark.config.schema.json` | Stable package resource subpaths for editor completion and contract tooling. |
 | **Agent skills** | `/ark-*` templates installed by `--install-agent-gates` | Skill *names* and “default flow” are stable; internal skill prose may evolve (e.g. When/not when, explore Shape dual-plan seed, extraction cards, 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`) | The `uses:` tag/SHA selects the checker source; `version` remains an optional exact npm compatibility override. |
+| **Package metadata** | `arkgate/package.json` | Stable resource subpath for tooling that needs the installed manifest. |
+
+### Corrective distribution status and strict boundary
+
+`arkgate@3.8.0` includes the non-deduplicable TS6 host, completeness schema, and resolved
+candidate-facts parity path above. It installs `typescript-ark-host` at
+exact `npm:typescript@6.0.3`, prefers a usable project compiler API, and fails closed on `partial`
+or `unavailable` analysis. Its packed compatibility gate is scoped to Node 18/20/22/24,
+npm/pnpm/Yarn, and project TypeScript 5.9.3/6.0.3/7.0.2. All 36 packed cells passed on source
+`228dd893` in CI run `29655190747`. Yarn uses strict PnP for the JS compilers and its
+`node-modules` linker for native TS7; the report names that mode.
+
+Z04 closes the separate current-source parity claim under the supplied-facts boundary selected in
+[ADR 0011](adr/0011-resolved-candidate-facts-boundary.md). Complete candidates—including aliases,
+workspace/project packages, symlinks, creates, updates, and deletes—are resolved once into
+versioned facts and evaluated by one pure Kernel/generated-bundle verdict. CLI, MCP, complete-patch
+hook, programmatic resolved APIs, and final check preserve the same evidence identities; ESLint
+claims parity only for its documented on-disk static-relative envelope. Retained lexical APIs and
+single-snippet adapters report `lexical-compatibility`, `partial`, and non-green instead of
+borrowing the resolved claim.
+
+Strict CI remains the final authority because it is the merge boundary, not because another
+semantic engine is expected there. No early adapter result is permission to suppress that gate.
 
 Gates need **no application code imports**. Most projects only use the CLI + MCP + config.
 
+## Programmatic root API
+
+`src/gate.ts` is the canonical source for `import ... from 'arkgate'`. Its public runtime values
+are grouped below.
+
+| Group | Exported runtime values |
+|-------|-------------------------|
+| Metadata and adapter diagnostics | `version`, `ARK_ANALYSIS_RESULT_SCHEMA_VERSION`, `ARK_ANALYSIS_RESULT_SCHEMA`, `createAdapterResult`, `toAdapterDiagnostic` |
+| AI snippet gate | `createAICodeGate` |
+| Profiles and config factories | `createArchitectureProfile`, `createArchitectureProfileFromArkConfig`, `createElevenLayerArkConfig`, `elevenLayerProfile` |
+| Analysis and preflight | `loadContract`, `analyzeResolvedProject`, `preflightResolvedChange`, lexical-compatibility `analyzeProject` / `analyzeChange` / `preflightChange`, `analyzePolicyDelta`, `analyzeArchitectureConvergence`, `explainViolation`, `evaluateArchitectureGraph`, `collectAnalysisConfigWarnings`, `detectArchitectureCycles`, `collectForbiddenCapabilityUses`, `extractSemanticDependencies` |
+| Policy delta | `POLICY_DELTA_SCHEMA_VERSION`, `classifyArkPolicyDelta`, `policyDeltaAcknowledgementMatches` |
+| Design delta contract | `ARK_DESIGN_DELTA_SCHEMA_VERSION` |
+| Analysis IR + resolved facts | `ANALYSIS_IR_SCHEMA_VERSION`, `RESOLVED_CANDIDATE_FACTS_SCHEMA_VERSION`, `RESOLVED_CANDIDATE_FACTS_SCHEMA`, `createResolvedCandidateFacts`, `loadResolvedCandidateFacts`, `resolvedFactsEvidenceRequirementsHash`, `deterministicHash`, `stableSerialize` |
+| Config contract | `ARK_CONFIG_SCHEMA`, `ARK_CONFIG_SCHEMA_VERSION`, `loadArkConfigContract`, `parseArkConfigJson` |
+
+The type-only root exports are also semver-supported:
+
+- Adapter diagnostics: `AdapterDiagnostic`, `AdapterResult`, `AdapterSeverity`,
+  `AdapterViolationInput`, `AdapterCompletenessReason`, `AnalysisCompleteness`, `AnalysisMode`.
+- Resolved facts: `ResolvedCandidateFacts`, `ResolvedCandidateFactsInput`, and their
+  dependency/file/evidence component types.
+- AI snippet gate: `AICodeGate`, `AICodeGateResult`, `AICodeGateViolation`,
+  `AICodeGateContext`, `AICodeGateOptions`, `AIGateExtension`.
+- Profiles and config factories: `ArchitectureLayer`, `ArchitectureLayerConfig`,
+  `ArchitectureProfile`, `ArchitectureRule`, `ArkCheckConfig`,
+  `CreateArchitectureProfileFromArkConfigOptions`, `CreateArchitectureProfileOptions`,
+  `CreateElevenLayerArkConfigOptions`.
+- Analysis and preflight: `AnalysisContract`, `ArchitectureChangeMap`,
+  `ArchitectureChangeMapContract`, `ArchitectureChangeMapDependency`,
+  `ArchitectureChangeMapFile`, `ArchitectureChangeOperation`,
+  `AnalyzeArchitectureConvergenceInput`, `ArchitectureActualChange`,
+  `ArchitectureConvergenceClassification`, `ArchitectureConvergenceFinding`,
+  `ArchitectureConvergenceResult`, `ArchitectureDependency`, `AnalyzeProjectInput`,
+  `AnalyzeResolvedProjectInput`, `PreflightResolvedChangeInput`, `AnalyzeChangeInput`,
+  `AnalysisResult`, `ResolvedAnalysisFile`, `ResolvedAnalysisIr`, `ResolvedAnalysisResult`,
+  `ResolvedChangePreflightResult`, `ResolvedSafetyReport`, `PreparedChangeFile`, `ChangePreflightResult`,
+  `AnalyzePolicyDeltaInput`, `PolicyDeltaAnalysis`, `ArchitectureEngineViolation`,
+  `ArchitectureEngineEdge`, `EvaluateArchitectureGraphInput`, `ArchitectureEngineResult`,
+  `CollectAnalysisConfigWarningsInput`, `ForbiddenCapabilityUse`, `SemanticDependency`,
+  `SemanticDependencyKind`.
+- Policy delta: `PolicyDelta`, `PolicyDeltaAcknowledgement`, `PolicyDeltaClassification`,
+  `PolicyDeltaFinding`.
+- Design delta: `ArkDesignDeltaResult`, `ArkDesignDeltaIdentity`, `ArkDesignDeltaChange`,
+  `ArkDesignDeltaEvidence`, `ArkDesignSmellId`, `ArkDesignDeltaVerdict`.
+- Analysis IR: `AnalysisFileInput`, `AnalysisFileChange`, `AnalysisCompilerOptions`,
+  `AnalysisFile`, `AnalysisImportEdge`, `AnalysisCapabilityUse`, `AnalysisEvidence`,
+  `AnalysisViolation`, `AnalysisIr`.
+- Config contract: `ArkConfig`, `ArkConfigLoadResult`.
+
+Runtime-kernel factories, `CAPABILITY_IDS`, `collectCapabilityUses`, and Domain capability mapping
+helpers are deliberately absent from this root. Use `@arkgate/runtime` for the experimental
+runtime, and `analyzeProject(...).ir.capabilityUses` for public capability evidence.
+
 ---
 
 ## Experimental opt-in surfaces
 
-These APIs are shipped for evaluation and compatibility, but they are **not production-ready
+These APIs are implemented for evaluation and compatibility, but they are **not production-ready
 product claims**. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **Runtime kernel** | **`@arkgate/runtime`** | Separate 0.x package, published under the `experimental` tag. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Built-in stores are **InMemory reference only**. |
+| **Runtime kernel** | **`@arkgate/runtime`** | Separate 0.x source package configured for the `experimental` tag. It is not currently present in the npm registry, and the root `publish-npm.yml` workflow does not publish it automatically. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Built-in stores are **InMemory reference only**. |
 | **Runtime migration shim** | `arkgate/runtime` | Deprecated forwarder to `@arkgate/runtime`; contains no implementation and is removed in ArkGate 4. |
 | **NestJS adapter** | `@arkgate/runtime/nestjs` | Experimental optional peer `@nestjs/common`; the deprecated `arkgate/nestjs` path forwards here. |
 
@@ -72,7 +153,12 @@ import { createStrictArkKernel, createStrictArkKernelFromConfig } from '@arkgate
 import { ArkModule, InjectArk } from '@arkgate/runtime/nestjs';
 ```
 
-See [production-hardening.md](./production-hardening.md) for requirements an eventual
+These imports describe the intended package boundary. Before an npm evaluation, verify that a
+separate publication exists with `npm view @arkgate/runtime dist-tags --json`. Until it does,
+build `packages/runtime` in an ArkGate source checkout and install that local folder; do not treat
+the deprecated root forwarding shims as an embedded runtime.
+
+See [production-hardening.md](https://github.com/pedroknigge/arkgate/blob/main/docs/production-hardening.md) for requirements an eventual
 production deployment would need to satisfy; it is not a readiness certification.
 
 ---
@@ -100,6 +186,6 @@ production deployment would need to satisfy; it is not a readiness certification
 
 ## Release notes (maintainers)
 
-Ship notes for a version live under [releases/](./releases/) (latest:
-[3.7.0.md](./releases/3.7.0.md)).
-Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases) (latest:
+[3.8.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/3.8.0.md)).
+Publish path: signed annotated tag → GitHub Release → `publish-npm.yml` (see [CONTRIBUTING.md](https://github.com/pedroknigge/arkgate/blob/main/CONTRIBUTING.md)).

package/docs/typescript-support.md

@@ -1,4 +1,4 @@
-# TypeScript support (5.x · 6.x · 7.x)
+# TypeScript support (5.x / 6.x / 7.x)
 
 ArkGate’s architecture gate (`arkgate-check` / `ark-mcp`) needs a **JavaScript API**
 TypeScript package that exposes:
@@ -6,6 +6,7 @@ TypeScript package that exposes:
 - `ts.sys` (at least `fileExists`)
 - `createSourceFile` (AST)
 - `resolveModuleName` (module graph)
+- `isInTypeQuery` (runtime-reference classification)
 
 It does **not** require the Go-native `tsc` binary for the gate. Type-checking
 semantics of your app still come from **your** project `typescript` + `tsconfig`.
@@ -14,11 +15,22 @@ semantics of your app still come from **your** project `typescript` + `tsconfig`
 
 | Range | Status |
 |-------|--------|
-| **TypeScript 5.x** | Fully supported (primary CI) |
-| **TypeScript 6.x** | Supported (bridge release before 7) |
-| **TypeScript 7.x** | Supported as **project** compiler; gate loads project TS when API-compatible, otherwise **falls back** to a JS-API TypeScript |
+| **TypeScript 5.x** | Supported; packed compatibility cell uses **5.9.3** |
+| **TypeScript 6.x** | Supported; packed compatibility cell uses **6.0.3** |
+| **TypeScript 7.x** | Supported through the project's own compiler plus ArkGate's physically distinct TypeScript 6 analysis host; packed compatibility cell uses **7.0.2** |
 
-Optional peer (documentational):
+These current-source claims passed the complete 36-cell packed matrix on source `228dd893` in
+[CI run 29655190747](https://github.com/pedroknigge/arkgate/actions/runs/29655190747).
+Published 3.7.0 remains outside this corrected support claim.
+
+> **Distribution boundary:** published `arkgate@3.7.0` predates this correction. Its compatible
+> analysis dependency can deduplicate to a TS7 version-only export, and its unavailable
+> `--plan --json` result can incorrectly report `goal.met: true`. The current source candidate for
+> the next corrective release fixes both defects with a non-deduplicable host and explicit analysis
+> completeness. Do not attribute that fix to 3.7.0; upgrade once the corrective version is
+> published.
+
+Supported consumer range (also declared as an optional peer for compatibility):
 
 ```json
 "peerDependencies": {
@@ -26,24 +38,63 @@ Optional peer (documentational):
 }
 ```
 
-ArkGate does not hard-require `typescript` as a runtime dependency of the package
-itself; the CLI resolves it from the **project** first, then from the environment.
+The current source line installs one exact production fallback under a different package identity:
+
+```json
+"dependencies": {
+  "typescript-ark-host": "npm:typescript@6.0.3"
+}
+```
+
+The CLI still resolves the consumer project's **own** `typescript` first so a usable project API
+and its module-resolution semantics win. If that export is missing or version-only, ArkGate loads
+`typescript-ark-host`. Because the dependency key is distinct from `typescript`, npm, pnpm, and
+Yarn cannot satisfy it by reusing the project's TS7 package. It also does not replace the project's
+`tsc`; builds and type checks continue to run the compiler selected by the consumer lockfile.
 
 ## How loading works
 
-1. Prefer `require('typescript')` from the **project** root (when it has `sys` + AST + resolve).  
-2. If missing or **not API-compatible** (TS 7.0 version-only export, or incomplete host), fall back to **ArkGate’s own** `typescript` dependency (JS-API 5.x nested under the package), then bare `import('typescript')`.
-3. If nothing usable is found:  
-   - `--plan` still prints **coverage honesty** (no import graph)  
-   - full check exits non-zero with an install hint  
+1. Prefer `require('typescript')` from the **project** root when it has `sys` + AST + resolve.
+2. If the project export is missing or **not API-compatible** (for example, the TS 7.0
+   version-only export), load `typescript-ark-host` at exact `npm:typescript@6.0.3` from ArkGate's
+   install tree.
+3. If neither host is usable, analysis is `unavailable`: plan has `goal.met: false`, normal JSON
+   has `valid: false` and `ok: false` with `ANALYSIS_HOST_UNAVAILABLE`, and the CLI exits `2`.
+4. If the selected host reports parse diagnostics in governed files, analysis is `partial`:
+   `--plan --json` has `goal.met: false`, normal JSON has `valid: false` / `ok: false`, and
+   `--strict-merge` exits `1`. The non-strict command preserves its legacy advisory exit code;
+   doctor also remains diagnostic while exposing the same completeness and parse-health evidence.
 
 Debug which TypeScript was used:
 
 ```bash
 ARK_DEBUG_TS=1 npx arkgate-check --plan
-# → [ark-check] TypeScript 5.9.x via arkgate (fallback)
+# project TS 5/6 → [ark-check] TypeScript 5.9.3 via project
+# project TS 7   → [ark-check] TypeScript 6.0.3 via arkgate-fallback (fallback)
 ```
 
+## Analysis identity and completeness (schema 1.3)
+
+Every current CLI/MCP/hook diagnostic envelope carries required `mode`, `completeness`, and
+structured `completenessReasons`:
+
+| Value | Meaning | Can plan/check be green? |
+|-------|---------|--------------------------|
+| `complete` | Every governed file was analyzed with a usable host and no parse diagnostics | Yes, if the normal contract verdict is also clean |
+| `partial` | A host ran, but governed syntax could not be fully parsed | No in JSON/plan; strict merge fails. The non-strict process exit remains advisory for compatibility |
+| `unavailable` | No API-compatible host could produce architecture evidence | No; CLI exits `2` |
+
+Schema 1.3 also distinguishes `resolved-candidate-facts` from `lexical-compatibility`.
+Resolved complete/partial results carry `policyHash`, `resolverIdentity`, `factsHash`, and
+`candidateTreeHash`, so adapters can prove they evaluated the same input. Single-file lexical
+surfaces cannot prove module resolution and therefore report `partial`, `valid:false`, plus
+`lexicalValid` where useful. Both the exported union and JSON Schema prohibit `valid:true` for
+partial/unavailable analysis. The public TypeScript `AdapterResult` union still accepts
+consumer-owned 1.0/1.1/1.2 values. For source compatibility, the low-level
+`createAdapterResult({ valid, ... })` factory still treats omitted completeness as complete; that
+legacy construction is not evidence of resolved adapter parity, and shipped adapters pass mode,
+completeness, reasons, and identities explicitly.
+
 ## TypeScript 7 notes
 
 TypeScript 7 is the **native (Go) compiler** generation. Important for tools like ArkGate:
@@ -51,7 +102,10 @@ TypeScript 7 is the **native (Go) compiler** generation. Important for tools lik
 - **`require('typescript')` on 7.0.x** exports only `{ version, versionMajorMinor }` — not `sys`, `createSourceFile`, or `resolveModuleName`.  
 - Unstable programmatic surfaces live under `typescript/unstable/*` (sync/async API, AST). They are **not** the classic TS 5/6 host ArkGate uses today.
 - Stable **programmatic JS API** maturity continues over the 7.x line (Microsoft: full story into **7.1+**).  
-- When the project’s TypeScript is not API-compatible, ArkGate loads its **bundled JS-API dependency** (`typescript@^5.9`, nested under the package) so the host write path and CI check keep working while you try TS 7 as the project compiler.
+- When the project’s TypeScript is not API-compatible, the current source line loads the exact,
+  separately named `typescript-ark-host` dependency. Published 3.7.0 does not yet have that fix.
+- TypeScript 7 syntax that TypeScript 6.0.3 cannot parse is reported as `partial`, never clean.
+  ArkGate fails closed until its analysis host can parse every governed file.
 - Your **tsconfig** must follow TS 6/7 defaults (see below) or `tsc` / resolve can fail independently of ArkGate.
 
 ### tsconfig defaults that surprise teams (TS 6 → 7)
@@ -87,47 +141,62 @@ Example consumer-friendly skeleton (also used in `tests/fixtures/ts-consumer`):
 }
 ```
 
-## Side-by-side TypeScript 6 + 7 (tooling)
+## Project compiler remains project-owned
 
-If you need **tsc 7** for builds and a **JS API 6** for tools that still expect classic exports:
+Do not downgrade, alias, or replace the project's `typescript` dependency for ArkGate. A TS7
+project keeps TS7 for `tsc`, editor semantics, and its lockfile; `typescript-ark-host` is an
+internal analysis dependency. If a repository intentionally runs multiple `tsc` versions for its
+own migration, keep that setup separate from ArkGate's host resolution.
 
-```json
-{
-  "devDependencies": {
-    "typescript": "npm:@typescript/typescript6@^6.0.0",
-    "typescript-7": "npm:typescript@^7.0.0"
-  }
-}
-```
+Declare the project compiler directly whenever you invoke `tsc`. If a consumer has no direct
+`typescript` dependency, a package manager may expose the fallback alias's binary because it is the
+only compiler in the install; that binary is not ArkGate's promise for project type checking. A
+direct project `typescript` dependency wins in the packed npm, pnpm, and Yarn cells.
 
-- `npx tsc6` — TypeScript 6 CLI (from the alias package)  
-- `npx typescript-7` / install path — TypeScript 7 CLI as needed  
+## Yarn PnP and the native TS7 compiler
 
-ArkGate will prefer the project’s `typescript` package; keep that entry **API-compatible** (5/6, or 7 once `sys` is present). See Microsoft’s TS 7 RC blog for dual-install details.
+The supported Yarn 4.17.1 matrix names its linker mode explicitly:
+
+- TypeScript 5.9/6.0 cells use **strict PnP** with no root `node_modules`.
+- TypeScript 7.0 cells use Yarn's **`node-modules` linker**, so the native compiler resolves normal
+  package imports without an internal-path or unplugged-package bridge.
+
+Yarn supports PnP for JS TypeScript releases by applying a compatibility patch to TypeScript's
+resolver. The native TS7 compiler does not execute that JavaScript patch. ArkGate therefore does
+not claim strict-PnP type-checking support for the TS7 cell; use Yarn's `node-modules` linker or
+remain on the JS compiler for that workflow. ArkGate's CLI/MCP analysis-host fallback is a separate
+concern and never changes the compiler selected by the project. See Yarn's
+[PnP explanation](https://yarnpkg.com/getting-started/qa#why-is-typescript-patched-even-if-i-dont-use-plugnplay)
+and Microsoft's [TS7 native release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/).
 
 ## CI matrix (this repo)
 
-GitHub Actions job `ts-compat` installs TypeScript **5.9.x**, **6.0.x**, and **7.0.x** into a temp copy of `tests/fixtures/ts-consumer` and runs:
+The release compatibility workflow packs the candidate first, then tests clean consumers across:
 
-```bash
-node bin/ark-check.mjs --root <fixture> --plan --json --no-cache
-```
+- Node **18 / 20 / 22 / 24**;
+- **npm / pnpm / Yarn**;
+- project TypeScript **5.9.3 / 6.0.3 / 7.0.2**.
 
-Locally:
+That is 36 installed-artifact cells. Each cell verifies that the project's `tsc` stays on the
+requested project compiler and that ArkGate resolves its fallback as exact 6.0.3 when the project
+API is unusable. Reports record `installMode` so the Yarn TS7 linker boundary cannot disappear
+behind a green job. All 36 cells passed on source `228dd893` in CI run `29655190747`. Locally, the
+repository entry point is:
 
 ```bash
-node scripts/ts-compat-matrix.mjs 5.9.3
-node scripts/ts-compat-matrix.mjs 6.0.3
-node scripts/ts-compat-matrix.mjs 7.0.2
+npm run test:ts-compat
 ```
 
 ## What “compatible” means for ArkGate
 
 | Goal | Status |
 |------|--------|
-| Gate does not crash on project TS 7 | Yes (fallback if API incomplete) |
+| Packed gate runs beside project TS 7 | Yes in current source; verified across the complete packed matrix. Published 3.7.0 predates the distinct host |
 | Plan/check work with project TS 5/6 | Yes |
 | Plan/check work when project has TS 7 + usable `sys` | Yes (uses project) |
+| Project `tsc` remains the selected project version | Yes; the analysis alias does not replace it |
+| TS7-only syntax outside the TS6 parser envelope reports clean | No; completeness becomes `partial` and strict merge fails |
+| Missing analysis host can satisfy a plan | No; completeness is `unavailable`, goal is false, exit is `2` |
 | Gate uses native Go typechecker API exclusively | Not required; future if 7.1+ exposes a stable Node API we adopt |
 | User tsconfigs with removed options still “just work” | User must migrate tsconfig (TS6/7); Ark reports resolve/parse failures clearly |
 
@@ -175,4 +244,7 @@ When Microsoft ships a stable Node API for native TypeScript 7.1+:
 2. Keep the multi-version matrix green.  
 3. Optionally prefer project TS 7 for resolution without fallback.
 
-Until then, **fallback + matrix** is the compatibility story so teams can try TS 7 today without breaking the architecture gate.
+Until then, the exact TypeScript 6 analysis alias is the compatibility bridge. Any `partial` or
+`unavailable` result is a hard stop for accepting the analysis, not permission to trust a
+clean-looking subset. Automation must read `valid`/`ok` or use `--strict-merge`; the legacy
+non-strict process exit is not the completeness authority.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -28,6 +28,12 @@
     "./schema/ark.analysis-result.schema.json": "./schemas/ark.analysis-result.schema.json",
     "./schema/change-map": "./schemas/ark.change-map.schema.json",
     "./schema/ark.change-map.schema.json": "./schemas/ark.change-map.schema.json",
+    "./schema/resolved-candidate-facts": "./schemas/ark.resolved-candidate-facts.schema.json",
+    "./schema/ark.resolved-candidate-facts.schema.json": "./schemas/ark.resolved-candidate-facts.schema.json",
+    "./schema/enforcement-state": "./schemas/ark.enforcement-state.schema.json",
+    "./schema/ark.enforcement-state.schema.json": "./schemas/ark.enforcement-state.schema.json",
+    "./schema/design-delta": "./schemas/ark.design-delta.schema.json",
+    "./schema/ark.design-delta.schema.json": "./schemas/ark.design-delta.schema.json",
     "./nestjs": {
       "types": "./compat/nestjs.d.ts",
       "import": "./compat/nestjs.js",
@@ -47,9 +53,18 @@
   "files": [
     "bin",
     "bin/lib",
+    "!bin/lib/design-delta.source.mjs",
+    "!bin/lib/enforcement-state.source.mjs",
+    "!bin/lib/hook-templates.source.mjs",
+    "!bin/lib/ai-velocity.mjs",
+    "!bin/lib/graph-cycles.mjs",
+    "!bin/lib/safety-diagnostics.mjs",
+    "!bin/lib/ts-resolve.mjs",
     "compat",
     "dist",
+    "!dist/**/*.d.cts",
     "schemas",
+    "!schemas/*.source.json",
     "docs/agent-guide.md",
     "docs/enthusiast",
     "docs/demos/01-write-gate-self-correction.md",
@@ -82,7 +97,7 @@
     "test:fuzz": "npm run build && ARK_FUZZ_CAMPAIGN=pr vitest run tests/fuzz",
     "test:fuzz:extended": "npm run build && ARK_FUZZ_CAMPAIGN=extended vitest run tests/fuzz",
     "test:confidence": "npm run test:coverage && npm run test:mutation",
-    "test:adapter-parity": "vitest run tests/unit/adapters/adapterParity.test.ts tests/unit/eslint/parity.test.ts",
+    "test:adapter-parity": "vitest run tests/unit/adapters/adapterParity.test.ts tests/unit/adapters/z04ResolvedAdapterParity.test.ts tests/unit/eslint/parity.test.ts",
     "test:onboarding-matrix": "for shard in library/small library/medium library/large api/small api/medium api/large frontend/small frontend/medium frontend/large monorepo/small monorepo/medium monorepo/large; do O04_SHARD=$shard npm run test:onboarding-matrix:shard; done",
     "test:onboarding-matrix:shard": "vitest run tests/unit/static-check/o04OnboardingMatrix.test.ts",
     "test:gate-only": "vitest run tests/unit/static-check/arkCheck.test.ts tests/unit/mcp/arkMcp.test.ts tests/unit/eslint",
@@ -95,11 +110,20 @@
     "check:layer-match": "node scripts/generate-layer-match.mjs --check",
     "generate:cli-pure": "node scripts/generate-cli-pure.mjs",
     "check:cli-pure": "node scripts/generate-cli-pure.mjs --check",
+    "generate:packaged-tooling": "node scripts/generate-packaged-tooling.mjs",
+    "check:packaged-tooling": "node scripts/generate-packaged-tooling.mjs --check",
     "generate:analysis-engine": "node scripts/generate-analysis-engine.mjs",
     "check:analysis-engine": "node scripts/generate-analysis-engine.mjs --check",
+    "generate:z08-prompts": "node scripts/generate-z08-task-prompts.mjs",
+    "check:z08-prompts": "node scripts/generate-z08-task-prompts.mjs --check",
+    "prepare:z08-sources": "node eval/causal/prepare-sources.mjs",
+    "generate:z08-manifest": "node eval/causal/generate-manifest.mjs",
+    "attest:z08-mutation": "node eval/causal/attest-mutation.mjs",
+    "eval:z08-causal": "node eval/causal/run.mjs",
+    "test:z08:harness": "vitest run tests/unit/eval/causalContract.test.ts tests/unit/eval/causalAnalysis.test.ts tests/unit/eval/causalRunner.test.ts tests/unit/eval/causalGrader.test.ts tests/unit/eval/z08TaskMaterialize.test.ts",
     "check:gallery-starters": "node scripts/check-gallery-starters.mjs",
     "generate:gallery-starters": "node scripts/check-gallery-starters.mjs --write",
-    "test:ts-compat": "node scripts/ts-compat-matrix.mjs 5.9.3 && node scripts/ts-compat-matrix.mjs 6.0.3 && node scripts/ts-compat-matrix.mjs 7.0.2",
+    "test:ts-compat": "node scripts/ts-compat-matrix.mjs",
     "eval:agent": "node eval/run.mjs",
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
@@ -111,6 +135,8 @@
     "test:adoption-harness": "vitest run tests/unit/eval/adoptionHarness.test.ts",
     "bench:scale": "node scripts/ark-scale-bench.mjs",
     "test:scale-bench": "npm run build && vitest run tests/unit/scripts/arkScaleBench.test.ts",
+    "test:z07:pr": "node scripts/z07-feedback-run.mjs --mode pr",
+    "test:z07:nonmutation": "node scripts/z07-feedback-run.mjs --mode full",
     "check:module-budgets": "node scripts/check-module-budgets.mjs",
     "check:package-files": "node scripts/verify-package-files.mjs",
     "check:release-artifacts": "node scripts/verify-release-artifacts.mjs",
@@ -122,7 +148,7 @@
     "bench:hook-path": "node scripts/hook-path-bench.mjs"
   },
   "dependencies": {
-    "typescript": ">=5.0.0 <8"
+    "typescript-ark-host": "npm:typescript@6.0.3"
   },
   "peerDependencies": {
     "@arkgate/runtime": ">=0.1.0-experimental.0 <1",
@@ -152,10 +178,12 @@
     "@stryker-mutator/vitest-runner": "^9.6.1",
     "@types/node": "^20.14.0",
     "@vitest/coverage-v8": "^3.2.6",
+    "esbuild": "0.28.1",
     "fast-check": "^4.9.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "tsup": "^8.1.0",
+    "typescript": "5.9.3",
     "vitest": "^3.2.6"
   },
   "engines": {