arkgate 3.6.1 → 3.8.0

package/docs/agent-guide.md

@@ -8,8 +8,10 @@ hard-CI split is a deliberate trade-off, not a gap: local hooks and MCP coach at
 while a required merge status is the one boundary a repository can make every write path share.
 
 CLI names: prefer **`arkgate` / `arkgate-check` / `arkgate-mcp`**; aliases `ark` / `ark-check` /
-`ark-mcp` still work for one major. TypeScript **5.x / 6.x / 7.x** as the project compiler:
-see [typescript-support.md](typescript-support.md).
+`ark-mcp` still work for one major. The current source candidate tests packed project TypeScript
+**5.9.3 / 6.0.3 / 7.0.2** and uses an exact, physically distinct TypeScript 6 analysis host when
+the project API is unusable. Published 3.7.0 predates that correction; see the distribution and
+completeness boundary in [typescript-support.md](typescript-support.md).
 
 ## Architecture playbook and `ark-check --recommend`
 
@@ -65,6 +67,7 @@ npx ark init --archetype crud-product --yes   # non-interactive: shape → prese
 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 --ratchet-cores                   # require populated core layers after raw graph is green
 npx ark-check --watch                           # debounced re-check when governed files change
 ```
 
@@ -73,6 +76,14 @@ docs or CI templates. Compact `ark start` previews first and keeps the applied s
 project files and 25 KB;
 run `ark-check --report ark-report.html` explicitly when you want to establish an origin/evolution
 baseline. Do not `--reset-origin` unless the user explicitly wants a new baseline.
+`ark-check --report --no-archive` still creates `origin.*` on the first report (or on an explicit
+reset) and refreshes `latest.*`; it skips only the timestamped JSON file under
+`.ark/reports/history/`.
+
+Once the **raw** graph has zero violations (the baseline is deliberately ignored) and governed
+coverage is at least 50%, `ark-check --ratchet-cores` changes `optional: true` to
+`optional: false` for populated core layers in `ark.config.json`. Empty cores remain optional.
+The command refuses active raw violations or low coverage; re-run `ark-check --doctor` after it.
 
 To remove a compact host integration, preview `ark start --remove-host <host>` and add `--apply`
 only after review. Ark removes only its exact compact artifacts, leaves customized files untouched
@@ -90,6 +101,7 @@ explore then apply A + propose/apply-with-ok B. `/ark-loop` = plan A only. Empty
 ```bash
 npx ark-check --doctor --json   # designFitness, designSmells[].outcome, postGreenPath, goldenPattern, pilotLoop
 npx ark-check --plan --json     # plan.goal.designWeak + plan.patternBets[] + plan.pilotLoop
+npx ark-check --doctor --fail-on-new-smells --base-ref origin/main --json # opt-in new/worsened design delta
 ```
 
 **Post-green path (Q01):** when design-weak, doctor sets `postGreenPath` / `primaryNextAction`
@@ -104,7 +116,8 @@ Never multi-pilot batch; never mechanical-safe; never claim healthy finished whi
 **AI-velocity evidence (Q05):** deterministic fixture bench (no live LLM) compares the same
 feature add on design-weak vs golden-path trees. Run `npm run eval:ai-velocity`; metric is
 `placementTurns` (agent-equivalent steps to the DomainModel home). Method is stored next to
-the number in `eval/ai-velocity-report.json`. See [eval/README.md](../eval/README.md).
+the number in `eval/ai-velocity-report.json`. See
+[the evaluation guide](https://github.com/pedroknigge/arkgate/blob/main/eval/README.md).
 
 Smell **ids** (stable JSON) plus **outcome** lines (plain language, Q02) on each
 `designSmells[]` object — prefer `outcome` for humans; keep `id` for automation:
@@ -112,7 +125,7 @@ Smell **ids** (stable JSON) plus **outcome** lines (plain language, Q02) on each
 | id | Outcome (what to do / why the AI struggles) |
 |----|-----------------------------------------------|
 | `io-under-application` | Business code reaches DB/APIs directly — put I/O behind a port/adapter |
-| `handler-in-persistence` | HTTP handlers under storage folders — move handlers to API/UI |
+| `handler-in-persistence` | Static framework HTTP imports (`next/server`), `defineRoute` calls, or handler bodies under Persistence-role storage folders — move transport to API/UI |
 | `god-module` | Huge multi-job files — split the pilot by concern |
 | `domain-logic-in-ui` | can*/calculate* in UI — move pure rules into Domain |
 | `facade-sql-in-routes` | Routes import ORM/SQL — keep queries in repository/adapter |
@@ -138,12 +151,14 @@ migration acks a date so they cannot fossilize. X05 — acks matching no detecte
 as `ackLifecycle.stale`: fix the edge string or delete the entry. X06 — the family-infra
 carve-out also matches mid-name families (`HoursPersistenceAdapters -> PersistenceInfrastructure`).
 
-**Effect capabilities (U03, evidence-only):** the analysis IR reports typed capability uses for
-seven closed ids (`network`, `filesystem`, `clock`, `randomness`, `environment`, `process`,
-`persistence`). `collectCapabilityUses(ts, sourceFile)` is the symbol-aware collector (ambient
-globals + imports, one scanner — shadowing/type-only/`globalThis` handled); `ir.capabilityUses`
-carries the import-based subset the pure engine can prove from content alone. Direct evidence
-only. **Walls (U04) are opt-in:** a layer with `capabilities: { deny: ["clock", …] }` or
+**Effect capabilities (U03, evidence-only):** the public analysis IR reports typed capability
+uses for seven closed ids (`network`, `filesystem`, `clock`, `randomness`, `environment`,
+`process`, `persistence`) through `analyzeProject(...).ir.capabilityUses`. The CLI/hook adapters
+add symbol-aware ambient evidence internally (shadowing/type-only/`globalThis` handled); the
+pure IR carries the import-based subset it can prove from content alone. `collectCapabilityUses`
+and `CAPABILITY_IDS` are internal implementation exports, not exports from `arkgate`; the related
+public low-level root helper is `collectForbiddenCapabilityUses`. Direct evidence only.
+**Walls (U04) are opt-in:** a layer with `capabilities: { deny: ["clock", …] }` or
 `pure: true` (deny all seven) turns matching evidence into judgment-class
 `CAPABILITY_VIOLATION` findings with a port-injection `nextAction`; absence changes no verdict.
 One violation, one voice: ambient uses covered by `forbiddenGlobals` stay `FORBIDDEN_GLOBAL`.
@@ -164,6 +179,29 @@ never move. `reshapePilot.nextPilot` is a **proposed** one-at-a-time card (`move
 write gate + atomic preflight; merges are `/ark-architect` judgment cards. `notAScore`, never a
 verdict/`designFitness` input; there is no apply path.
 
+**Reshape decision memory (Y01):** when the team accepts, defers, or rejects that target, record
+the explicit verdict in `.ark/reshape-decisions.json` using the card's exact
+`decisionTarget` (`concept` + complete sorted `anchors`), a non-empty `reason`, and optional
+`reviewBy` (`YYYY-MM-DD`). Current rejected/deferred decisions hide only the repeated pilot card;
+the physical facts keep rendering. Accepted keeps the same `/ark-loop` path. Expired/malformed
+dates and decisions whose anchor set changed no longer apply; doctor/report list them. The golden
+pattern is never parsed to infer a decision — cite it in `reason` when it explains the layout.
+
+```json
+{
+  "schemaVersion": "1",
+  "decisions": [
+    {
+      "concept": "projects",
+      "anchors": ["src/app/api", "src/lib/api-handlers", "src/lib/repositories"],
+      "verdict": "rejected",
+      "reason": "These role directories are our thin-shell-handlers-data golden layout.",
+      "reviewBy": "2027-01-31"
+    }
+  ]
+}
+```
+
 **Governance weight (W02):** `contractHealth.governanceWeight` reports raw facts (layers, rules,
 governed files, files/layer, rules/layer) plus a fixed band (`heavy` / `typical` / `light` /
 `unknown`) with fixed wording. It is explicitly `notAScore` — never a gate input. Read `heavy` as
@@ -179,7 +217,8 @@ persisted as a short Shape plan under the repo; not a gate requirement.
 **Full-skill agent co-pilot:** after explicitly installing the `/ark-*` pack, use
 `/ark-autopilot` (explore-first, dual plan A remediation + B pattern bets). Recon without
 applying: `/ark-explore`. The default compact router uses MCP/CLI directly. Never treat empty
-`--plan` steps as “architecture healthy” when `designWeak` / non-empty `patternBets` remain.
+`--plan` steps as “architecture healthy” when `designWeak` / non-empty `patternBets` remain, or
+when `plan.completeness !== "complete"`. Partial and unavailable analysis force `goal.met: false`.
 
 `ark init --archetype <id>` maps playbook ids to named presets (`hexagonal`, `layered`,
 `feature-sliced`, `monorepo`). With `--yes` and no archetype, Ark auto-selects from
@@ -337,11 +376,18 @@ Prefer preparing the write before the host commits it to disk:
 | MCP **`ark_prepare_write`** | Place + constrain + validate + optional `autoPatch` + `judgmentBrief` + contentHash + optional `goldenPattern` in one call |
 | MCP **`ark_prepare_change`** | Validate one complete create/update/delete batch in memory; optional `changeMap` also returns structural convergence; never writes |
 | CLI **`ark preflight --changes <file> --json`** | Same atomic verdict and map convergence for hosts/scripts that do not call MCP |
-| Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch revalidation green or discarded |
+| Write-gate **`autoPatch`** | Mechanical-safe **import type** rewrites only; post-patch lexical validation must pass or the patch is discarded. It remains `partial`/non-green until complete-candidate preflight. |
 | PreToolUse **`--hook-repair`** | On deny: `ARK_REPAIR_JSON` / `ARK_AUTOPATCH_JSON` on stderr (still exit 2 — never silent write) |
-| Doctor **`writePath`** | Reports installed mode plus `enforcementLadder` (`supported` / `installed` / `active` / `bypassable`, evidence, operation coverage, required-status honesty) |
+| Opt-in design delta | `--fail-on-new-smells --base-ref <ref>` blocks only new/worsened supported smells; missing base fails closed; schema: `arkgate/schema/design-delta` |
+| Doctor **`writePath`** | Schema-backed support/assets/runtime/operation/bypass/required/`hard` evidence; only fresh covered-operation proof permits `hard:true` |
 | Doctor **`goldenPattern`** | Optional Q03 advisory summary (`present` / `invalid`); never clears design-weak |
 
+**Published 3.7.0 limitation:** its compiler-free atomic graph can miss aliases/workspace edges.
+The current source candidate closes that divergence through versioned resolved-candidate facts;
+API, bundle, CLI, MCP, complete-patch hook, and final strict check share the same candidate evidence.
+Lexical/single-snippet feedback remains explicitly partial and non-green. The normal strict gate is
+still the required final merge boundary.
+
 Port-proof inject binding is **judgment** for auto-apply (signature/arity change), not write-path autoPatch.
 Full reference: [ai-gates.md](ai-gates.md). Loop-cost harness: `npm run eval:loop-cost`.
 
@@ -372,7 +418,18 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok
 | **Grok Build** | `.grok/hooks/ark-write-gate.json` + `.grok/config.toml` / `.mcp.json` | `.grok/skills/<name>/SKILL.md` |
 
 This is a path reference, not a guarantee table. Full copy-paste setups:
-[ai-gates.md](ai-gates.md). Skill inventory: main [README](../README.md#agent-skills-ark-).
+[ai-gates.md](ai-gates.md). Skill inventory: main
+[README](../README.md#other-skills-only-when-you-need-them).
+
+For an optional executable adoption check, copy the shipped template into a Vitest/Jest suite
+after installing ArkGate:
+
+```bash
+mkdir -p tests
+cp node_modules/arkgate/templates/tests/ark-adoption-gaps.test.ts tests/ark-adoption-gaps.test.ts
+```
+
+It checks real on-disk contract, MCP, skill, and report artifacts; it does not mock the gate.
 
 ## Experimental runtime: contract discovery
 
@@ -396,7 +453,11 @@ const contract = ark.manifest().toJSON();
 ```
 
 Use `@arkgate/runtime` only when evaluating the experimental kernel. The stable `arkgate` gate
-package contains no runtime implementation. Package surface policy: [package-surface.md](package-surface.md).
+package contains no runtime implementation. The companion is not currently present in the npm
+registry and is not published by the root release workflow. Verify availability with
+`npm view @arkgate/runtime dist-tags --json`; until a separate experimental publication exists,
+evaluate it only from a source checkout after `npm run build:runtime` and install the local
+`packages/runtime` folder. Package surface policy: [package-surface.md](package-surface.md).
 
 Agents should read `contract` and `ark.observability.report()` before generating or modifying code.
 
@@ -480,7 +541,8 @@ contract, Ark records `interceptor.error` and keeps delivering the original even
 
 ## Code Generation Validation
 
-Use `createAICodeGate()` before merging agent-generated source snippets:
+Use `createAICodeGate()` for early lexical feedback on agent-generated source snippets, then run
+complete-candidate preflight before merging:
 
 ```ts
 import * as ts from 'typescript';
@@ -498,11 +560,13 @@ const result = gate.validate(generatedSource, {
   agentId: 'agent-1',
   layer: 'DomainModel',
 });
-if (!result.valid) {
+if (!result.lexicalValid) {
   for (const v of result.violations) {
     console.log(v.code, v.message, v.suggestion);
   }
 }
+// result.valid remains false: call ark_prepare_change / preflightResolvedChange,
+// then run the final strict repository check.
 ```
 
 Passing the `typescript` module enables built-in AST/symbol checks for dependencies, forbidden
@@ -617,25 +681,17 @@ Example config:
 }
 ```
 
-`ark-check` resolves imports through the TypeScript module resolver against your
-`tsconfig.json` — relative, path-alias (e.g. `@infra/db`), package/workspace imports,
-TypeScript `import = require()`, dynamic `import()`, and `require()` — plus string intent
-references. It also flags raw
-`publish()` calls, publish calls without `metadata.source`, and source intent literals
-whose resolved layer differs from the publishing file layer. Pass `--tsconfig <path>` to force one config
-for every file; otherwise each source file uses the nearest `tsconfig.json` above it (like
-`tsc`), so monorepos with per-package alias maps work under a single `--root`. It resolves
-modules the way your build does, but is intentionally not yet a full type-graph analyzer
-(cross-layer type-only references beyond the import specifier are out of scope).
-
-Repeat runs are cached in `node_modules/.cache/ark-check.json` — unchanged files skip the
-parse, while import edges always re-resolve against the live filesystem so the cache can
-never hide a new violation. `--no-cache` disables it.
-
-`ark-check --json` also reports `warnings` for incomplete governance coverage: missing
-layers, unclassified included files, unmatched layer patterns, duplicate layers, and rules
-that reference unknown layers. These are advisory by default. Use `--strict-config` once a
-project is ready to fail CI on coverage gaps.
+`ark-check` resolves relative, alias, package/workspace, `import =`, `import()` and `require()` edges
+plus intent/publish evidence. It uses the nearest `tsconfig.json` unless `--tsconfig` is set;
+importless type references are out.
+
+Each run parses the full candidate and ignores retired `.cache/ark-check.json`; `--no-cache` is a
+no-op. Z07 owns the identity-keyed snapshot after exact cold/warm parity.
+
+Doctor JSON gives parse totals, deterministic top 12 and overflow. `partial` forces
+`goal.met`/`valid`/`ok` false and strict exit `1`; unavailable exits `2`. Non-strict is advisory.
+
+Config warnings stay advisory unless CI opts into `--strict-config`.
 
 Use the optional ESLint plugin for fast local feedback aligned with CI:
 
@@ -647,9 +703,11 @@ export default [
 ];
 ```
 
-Rules: `ark/no-domain-infra-imports` (layer edges from `ark.config.json`, same semantics as
-`arkgate-check`), `ark/no-forbidden-globals` (per-layer `forbiddenGlobals`),
-`ark/no-raw-event-publish`, and `ark/require-publish-source`. See [ai-gates.md](ai-gates.md).
+Rules: `ark/no-domain-infra-imports` (exact parity for on-disk, in-scope static relative
+imports/exports; resolved CLI/preflight is authoritative outside that envelope),
+`ark/no-forbidden-globals` (per-layer `forbiddenGlobals`),
+`ark/no-denied-capabilities` (per-layer capability deny sets), `ark/no-raw-event-publish`, and
+`ark/require-publish-source`. See [ai-gates.md](ai-gates.md).
 
 ## Runtime Observability
 
@@ -729,8 +787,8 @@ not replace your web framework, HTTP clients, or job scheduler.
 ## Write-Path Gate (MCP)
 
 The strongest place to constrain an AI agent is the moment it writes a file, not after.
-`arkgate-mcp` / `ark-mcp` exposes ArkGate over MCP (JSON-RPC over stdio; gate host needs a
-JS-API TypeScript — nested or project) so a host can gate
+`arkgate-mcp` / `ark-mcp` exposes ArkGate over MCP (JSON-RPC over stdio; it prefers a usable
+project TypeScript API, then exact `typescript-ark-host@6.0.3`) so a host can gate
 the write path:
 
 For a complete multi-file candidate, use `ark preflight --changes changes.json --json` or MCP
@@ -744,15 +802,32 @@ required, and `behavioralCompletion` remains `not-evaluated` even when structure
 npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
 ```
 
-- **Resource `ark://manifest`** — contract discovery. Serve your exported
-  `ark.manifest().toJSON()` via `--manifest`, or omit it to get the 11-layer profile
-  (layers + rules) as the default contract.
-- **Tool `ark_recommend`** — no args. Returns the deterministic application-shape plan
-  (archetype, preset, phased adoption, analogy). Same as `ark-check --recommend --json`.
-- **Tool `validate_code`** — args `{ source, layer?, filePath? }`. Runs `createAICodeGate`
-  against the profile and (when a manifest is provided) the registered intent allowlist.
-  Returns `{ valid, violations, layer }`; `isError` is `true` when invalid. If `layer` is
-  omitted it is inferred from `filePath` via the config's layer patterns.
+- **Resource `ark://manifest`** — contract discovery. Serve an exported
+  `ark.manifest().toJSON()` via `--manifest`. Without that flag, the resource uses every active
+  layer and the effective rules from `ark.config.json`; the strict 11-layer profile is the
+  fallback only when the project config declares no layers.
+
+The server exposes these nine tools:
+
+| Tool | Primary input and purpose |
+|------|---------------------------|
+| `validate_code` | `{ source, layer?, filePath? }`: validate one snippet; infer the layer from `filePath` when possible; return an error result when invalid. |
+| `ark_check` | `{ strict?, baseline? }`: run the full project architecture check with structured diagnostics. |
+| `ark_policy_delta` | `{ baseConfig, candidateConfig?, acknowledgement? }`: classify a complete contract transition; never edits the contract. |
+| `ark_coverage` | No args: report per-layer counts, every unclassified file, unmatched layers, and missing rule edges. |
+| `ark_place` | `{ filePath?, description? }`: resolve or propose a governed home and return its import/global constraints. |
+| `ark_prepare_write` | `{ source, filePath?, description?, layer? }`: compose placement and snippet validation, with hashes and a mechanical-safe patch when available. |
+| `ark_prepare_change` | `{ changes, changeMap? }`: preflight one complete create/update/delete batch in memory; never writes files. |
+| `ark_recommend` | No args: return the deterministic application-shape plan used by `ark-check --recommend --json`. |
+| `ark_suggest_include` | No args: propose TypeScript/JavaScript include roots from workspaces and nested packages. |
+
+Current diagnostic envelopes use schema `1.3` and require `mode`,
+`completeness: "complete" | "partial" | "unavailable"`, and structured
+`completenessReasons`. Resolved results expose `policyHash`, `resolverIdentity`, `factsHash`, and
+`candidateTreeHash`; MCP `ark_check` mirrors CLI `ok`. Single-file `validate_code`,
+`ark_prepare_write`, and `createAICodeGate().validate()` are named lexical compatibility surfaces:
+they may expose `lexicalValid`, but remain partial and `valid:false` until complete-candidate
+preflight. Consumer-owned 1.0/1.1/1.2 `AdapterResult` values remain accepted by the public union.
 
 For hook-based enforcement, `ark-mcp --hook` runs one-shot: it reads a PreToolUse payload
 from stdin, validates the post-edit file content, and exits `2` with violations on stderr
@@ -795,8 +870,8 @@ registration by itself remains advisory on every host because the agent must cal
 
 1. **Read** manifest via `ark.manifest().toJSON()`
 2. **Generate** code using registered intents, profiles, metadata, projections, and workflow definitions
-3. **Validate snippets** with `createAICodeGate().validate(source, { layer })`
-4. **Validate repository** with `ark-check --root . --config ark.config.json`
+3. **Inspect snippets** with `createAICodeGate().validate(source, { layer })` (lexical, partial)
+4. **Validate the complete candidate** with `ark_prepare_change` or `ark-check --root . --config ark.config.json`
 5. **Lint** with `arkgate/eslint` recommended rules
 6. **Wire** relationships via `registry.define(..., { dependsOn, produces })`
 7. **Register** event contracts before publishing in strict mode

package/docs/ai-gates.md

@@ -43,16 +43,21 @@ you pass `--force`, so review and commit only the templates that match your proj
 **Doctor (W5):** `ark-check --doctor --json` includes `doctor.writePath`
 (`mode`: `repair` | `reject-only` | `mcp-only` | `none`, plus `prepareWrite` /
 `autoPatch` flags), the supported profile for the active host, and the evidence actually found.
-`writePath.enforcementLadder` separates `supported`, `installed`, `active`, and `bypassable` for
-local hooks, advisory MCP, and CI. Doctor leaves hook trust and required-status policy
-`unverified`; an actual covered PreToolUse denial can report operation-scoped activity. Codex
+`writePath.enforcementState` separately reports `supported`, `analyzed`, `configured`, `installed`,
+`runtimeObserved`, `operation`, `operationCoverage`, `active`, `bypassable`, `required`, and `hard`
+with structured evidence for local hooks, advisory MCP, and CI. Its public schema is
+`arkgate/schema/enforcement-state`; `enforcementLadder` remains a compatibility projection. Doctor
+leaves hook trust and required-status policy `unverified` without runtime/provider evidence and
+prints an explicit red flag for installed-but-unverified local hooks. Only a fresh covered
+PreToolUse/provider observation can set operation-scoped `hard:true`. Codex
 `apply_patch` can expose a complete patch to the shared atomic preflight, but the host remains
 bypassable/advisory because some Code Mode paths do not dispatch the project hook.
 
 **Design fitness (3.0.1+):** the same doctor JSON may include `doctor.designFitness` and
 `doctor.designSmells[]` (path evidence). Edge-clean `operatingMode: enforce` can still set
-`designFitness.designWeak: true` (**ENFORCE · design-weak**). That is Shape residual, not a
-write-path failure. Companion plan JSON: `plan.patternBets[]` with `neverMechanicalSafe: true`
+`designFitness.designWeak: true` (**ENFORCE · design-weak**). That global inventory remains Shape
+residual, not a write-path failure. Separately, Z10's opt-in design delta blocks only new/worsened
+supported smells on touched paths. Companion plan JSON: `plan.patternBets[]` with `neverMechanicalSafe: true`
 — never treat as write-boundary `autoPatch` / mechanical-safe. See
 [package-surface.md](package-surface.md) and [brownfield-adoption.md](brownfield-adoption.md) §6.
 
@@ -70,6 +75,14 @@ violations relative to the file's current on-disk state, so files with pre-exist
 (baselined) violations stay editable — they just can't get worse. New files block on
 every violation.
 
+### Opt-in resident hook pilot (Z07)
+
+Set `ARK_RESIDENT_HOOK=1` on both `ark-mcp` and its hook command. The pilot reuses the
+authoritative evaluator without caching decisions; stale inputs fall back one-shot.
+It is off by default, and `ApplyPatch` always uses the atomic one-shot preflight.
+With that MCP resident, `ark-check --doctor --json --resident` reuses canonical facts but
+recomputes live doctor surfaces; an absent or invalid snapshot falls back to the cold CLI.
+
 ### Opt-in repair payload (W4)
 
 Default is **hard block with prose** on stderr. Hosts that can re-inject a fixed write
@@ -84,7 +97,12 @@ can enable a **machine-readable repair payload** (still exit `2` — **never** s
 
 ```json
 {
-  "mode": "repair",
+  "schemaVersion": "1.3",
+  "mode": "lexical-compatibility",
+  "valid": false,
+  "completeness": "partial",
+  "completenessReasons": [{ "code": "LEXICAL_EVIDENCE_INCOMPLETE", "message": "…" }],
+  "repair": true,
   "decision": "deny",
   "filePath": "src/domain/use.ts",
   "layer": "DomainModel",
@@ -92,7 +110,9 @@ can enable a **machine-readable repair payload** (still exit `2` — **never** s
     "source": "import type { Row } from '../infra/types-only';\n…",
     "remediationKind": "import-type-from-pure-type-module",
     "confidence": 0.85,
-    "valid": true
+    "valid": false,
+    "lexicalValid": true,
+    "completeness": "partial"
   }
 }
 ```
@@ -182,6 +202,10 @@ The MCP server exposes a resource and tools agents can use proactively (not an e
 - **`validate_code`** (tool) — validates a snippet against the architecture on demand (the write-path gate). May return additive **`autoPatch`** (W1) for mechanical-safe import-type rewrites.
 - **`ark_prepare_write`** (tool) — **W2:** place + constrain + validate + optional autoPatch + judgmentBrief + contentHash in one call (composes `ark_place` + write gate).
 - **`ark_prepare_change`** (tool) — **T02–T05:** read-only atomic create/update/delete preflight with cross-file edge/cycle findings and candidate fingerprints. Optional `changeMap` accepts strict schema `1.0` intent and returns its hash plus satisfied/missing/contradictory/unplanned structural convergence; behavioral completion is not evaluated. Omission is supported. MCP registration remains advisory unless the host makes invocation non-bypassable.
+- **3.7.0 corrective boundary:** the compiler-free candidate graph can miss aliases/workspace
+  edges that final TypeScript-backed CI resolves. Keep the strict CI backstop mandatory while
+  [Phase Z](https://github.com/pedroknigge/arkgate/blob/main/docs/plans/enforcement-truth-at-speed/README.md)
+  restores differential parity.
 - Blocking CLI/MCP/hook diagnostics include the same deterministic `nextAction`. `AGENTS.md`, skill
   catalogs, session prose, and live LLM calls are not inputs to the enforcement verdict.
 - **`ark_place`** (tool) — given a target file path, returns its layer, forbidden globals, and which layers it may / must not import. Call it *before* writing a new file so generated code lands in a governed location.
@@ -424,11 +448,11 @@ If your runtime can run a shell command before file writes and pass the tool pay
 - Grok payloads also get `{ "decision": "deny", "reason": "…" }` on stdout when blocked
 - plumbing problems (no stdin, non-source files, files outside `--root`) never block
 
-## ESLint (editor feedback) — same contract as CI
+## ESLint (editor feedback) — bounded parity envelope
 
-For in-editor red squiggles that match **`arkgate-check`**, add the ESLint plugin.
+For fast in-editor red squiggles, add the ESLint plugin.
 Layer imports and purity globals are driven by **`ark.config.json`** (walk-up from the
-linted file): same layer globs, specificity, `exclude`, and `rules[]` edges as the CI gate.
+linted file).
 
 ```js
 // eslint.config.js  (flat config)
@@ -438,28 +462,80 @@ export default [
   ark.configs.recommended,
   // no-domain-infra-imports  → config-driven layer edges (type-only + value)
   // no-forbidden-globals     → layer.forbiddenGlobals from ark.config.json
+  // ark/no-denied-capabilities → layer.capabilities.deny / layer.pure
   // no-raw-event-publish + require-publish-source → runtime event hygiene
 ];
 ```
 
-**Parity notes (2.5+):**
+**Exact layer-edge parity envelope:** the linted production source is on disk, inside
+`include`, outside configured/generated exclusions, parse-clean, and uses a static
+`import`/`export` with a relative literal whose target is also on disk. Inside that envelope,
+ESLint uses the same layer glob specificity, rule decision, rule id, severity, and evidence as
+the resolved CLI. It reloads `ark.config.json` when its content changes and never invents a
+not-yet-created target.
+
+Outside that envelope—path aliases, packages/workspaces, symlinks, CommonJS,
+`import = require`, dynamic imports, virtual creates/deletes, unresolved targets, or complete
+cross-file candidates—ESLint emits no layer-parity verdict. Use `ark preflight`,
+`ark_prepare_change`, the complete ApplyPatch hook, or final strict CI; those paths consume the
+canonical resolved facts.
+
+Additional rule notes:
 
-- Relative imports are resolved to on-disk TS/JS targets; package bare imports are left to CI/TS.
+- Relative imports are resolved only to existing on-disk TS/JS targets; package bare imports are left to CI/TS.
 - Type-only and value forbidden edges both error (same pass/fail as `arkgate-check`).
-- `no-forbidden-globals` only applies when the file’s layer declares `forbiddenGlobals` (or you pass a `globals` option). Layers without a purity list are not inventively restricted.
-- Without `ark.config.json`, `no-domain-infra-imports` falls back to a domain→infra path heuristic.
+- `no-forbidden-globals` applies from the file layer’s `forbiddenGlobals`; the `globals` option is only a standalone fallback when no project config applies, never an override that weakens the project contract. Layers without either surface are not inventively restricted. `process` also owns exact value imports of `process` / `node:process`; type-only forms, subpaths, and `child_process` stay excluded. If the same layer also denies the `process` capability, this rule is the single `FORBIDDEN_GLOBAL` voice.
+- Without `ark.config.json`, `no-domain-infra-imports` emits no contract verdict.
 
 Rule ids are `ark/<kebab-name>`. Individual rules are also on `ark.rules` if you wire them by hand.
-Prefer keeping editor + CI on the same `ark.config.json` — do not maintain a parallel globals list unless you intentionally override.
+Prefer keeping editor + CI on the same `ark.config.json`. Use the rule-local `globals` list only
+for standalone linting where no project contract applies.
 
 ## CI backstop
 
 Whatever the agent side does, run the merge profile in CI:
 
 ```yaml
-- run: npx ark-check --root . --config ark.config.json --strict-merge
+- run: npx ark-check --root . --config ark.config.json --strict-merge --fail-on-new-smells --base-ref "${{ github.event.pull_request.base.sha || github.event.before }}"
+```
+
+This explicit brownfield ratchet records schema `1.0` identities, touched paths, and stable
+evidence; missing base exits `2`. Its first semantic smell is `domain-logic-in-ui`; residual,
+path-only moves, and unrelated work stay green. Generated Claude/Grok hooks share the delta and
+golden-pattern repair hint. MCP exposes the result but stays advisory.
+
+Or use the repository's composite Action at a pinned release or commit:
+
+```yaml
+- uses: pedroknigge/arkgate@v3.7.0
+  with:
+    root: .
+    config: ark.config.json
+    strict-config: 'true'
+    baseline: ''
+    version: ''
+    github-token: ${{ github.token }}
+```
+
+| Action input | Default | Meaning |
+|--------------|---------|---------|
+| `root` | `.` | Project root to check. |
+| `config` | `ark.config.json` | Config path relative to `root`. |
+| `strict-config` | `true` | On the current Action revision, run the fail-closed `--strict` profile; an explicit older `version` uses its compatibility `--strict-config` path. |
+| `baseline` | empty | Optional frozen-violation baseline; empty disables baseline mode. |
+| `version` | empty | Optional exact npm version override; empty runs the code from the pinned Action revision. |
+| `github-token` | empty | Token for a pull-request failure comment; empty skips the comment. |
+
+For an additional local human-commit check, copy the shipped hook template:
+
+```bash
+cp node_modules/arkgate/templates/hooks/pre-commit-ark .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
 ```
 
+The template runs the project's architecture check before a commit. It is optional and local;
+it does not replace the CI job or repository policy that makes the CI status required for merges.
+
 `--strict-merge` requires strict config plus the shared gate files (`AGENTS.md`, MCP config,
 and CI workflow) and fails on safety diagnostics. `--strict` is a compatibility alias. Neither
 profile requires an editor hook; add `--require-write-hook claude|grok` only when CI must verify
@@ -482,8 +558,8 @@ reported as lost static assurance; it does not imply that a runtime schema was b
 
 ### Scanner soundness envelope
 
-ArkGate uses the TypeScript compiler API for the governed source files. The repository scanner
-and `createAICodeGate({ typescript })` recognize these dependency forms:
+ArkGate uses the TypeScript compiler API for the governed source files. The resolved candidate
+scanner used by CLI/preflight/MCP/complete-patch hooks recognizes these dependency forms:
 
 - `import ... from 'literal'`, side-effect imports, and `export ... from 'literal'`;
 - TypeScript `import x = require('literal')` external-module references;
@@ -491,6 +567,12 @@ and `createAICodeGate({ typescript })` recognize these dependency forms:
 - relative, tsconfig path-alias, package, and installed workspace-package targets that resolve
   to source inside the project root. Third-party or escaped targets are deliberately not governed.
 
+`createAICodeGate({ typescript })` recognizes the same syntax lexically, but it does not discover a
+project resolver by itself. Its result is explicitly `mode: "lexical-compatibility"`,
+`completeness: "partial"`, and `valid:false`; `lexicalValid` records whether those bounded checks
+passed. A caller-supplied target resolver can improve feedback but does not turn the snippet into a
+parity-capable complete-candidate verdict.
+
 Direct `import(expr)` emits `DYNAMIC_IMPORT_NOT_ALLOWLISTED`; direct `require(expr)` emits
 `DYNAMIC_REQUIRE_NOT_ALLOWLISTED`. They are warnings in the default reporting profile and fail
 `--strict-config` / `--strict-merge`. The existing `dynamicImportAllowlist` name is retained for

package/docs/configuration.md

@@ -87,6 +87,12 @@ Layer fields:
   (`network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence`);
   `pure: true` is the shorthand that denies all seven. Absence changes no verdict.
 
+`forbiddenGlobals: ["process"]` covers the ambient binding plus exact runtime imports from
+`process` and `node:process`. It does not imply the broader `process` capability wall: subpaths
+and `child_process` remain outside this narrow dual, and statement-level `import type` /
+`export type` declarations are excluded. Declare `capabilities.deny: ["process"]` when the whole
+process module-capability family must be denied.
+
 Rule fields:
 
 - `from`, `to`, `allowed`, `message`, `peerIsolation`, `sliceFolders`

package/docs/demos/01-write-gate-self-correction.md

@@ -6,7 +6,7 @@ corrects the architecture instead of weakening the contract.
 ## Prerequisites
 
 - Ark installed in the repo (`ark-check`, agent gates optional for this demo)
-- [examples/hexagonal-order-api](../../examples/hexagonal-order-api/) cloned with dependencies
+- [examples/hexagonal-order-api](https://github.com/pedroknigge/arkgate/tree/main/examples/hexagonal-order-api) cloned with dependencies
 
 ## Steps
 
@@ -70,5 +70,5 @@ Expected:
 - The error message points at the **layer edge**, not a generic lint rule.
 - The fix is a file move or port inversion — not editing `ark.config.json`.
 
-See also: [Break it on purpose](../../examples/hexagonal-order-api/README.md#break-it-on-purpose)
+See also: [Break it on purpose](https://github.com/pedroknigge/arkgate/blob/main/examples/hexagonal-order-api/README.md#break-it-on-purpose)
 for two more exercises.

package/docs/enthusiast/README.md

@@ -38,20 +38,20 @@ Reproducible scripts — no video required:
 
 - [Write-gate self-correction](../demos/01-write-gate-self-correction.md)
 - [Brownfield baseline adoption](../demos/02-brownfield-baseline-adoption.md)
-- [Co-pilot autopilot, end to end](../demos/03-copilot-autopilot.md)
+- [Co-pilot autopilot, end to end](https://github.com/pedroknigge/arkgate/blob/main/docs/demos/03-copilot-autopilot.md)
 
 ## Gallery starters
 
 | Archetype | Directory |
 |-----------|-----------|
-| `crud-product` | [examples/crud-product-starter](../../examples/crud-product-starter/) |
-| `api-backend` | [examples/api-backend-starter](../../examples/api-backend-starter/) |
-| `worker-pipeline` | [examples/worker-pipeline-starter](../../examples/worker-pipeline-starter/) |
-| `multi-app-workspace` | [examples/multi-app-workspace-starter](../../examples/multi-app-workspace-starter/) |
-| `vertical-slice-product` | [examples/vertical-slice-starter](../../examples/vertical-slice-starter/) |
-| `ddd-bounded-contexts` | [examples/ddd-context-starter](../../examples/ddd-context-starter/) |
+| `crud-product` | [examples/crud-product-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/crud-product-starter) |
+| `api-backend` | [examples/api-backend-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/api-backend-starter) |
+| `worker-pipeline` | [examples/worker-pipeline-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/worker-pipeline-starter) |
+| `multi-app-workspace` | [examples/multi-app-workspace-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/multi-app-workspace-starter) |
+| `vertical-slice-product` | [examples/vertical-slice-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/vertical-slice-starter) |
+| `ddd-bounded-contexts` | [examples/ddd-context-starter](https://github.com/pedroknigge/arkgate/tree/main/examples/ddd-context-starter) |
 
-Deep teaching example (runnable API + break exercises): [hexagonal-order-api](../../examples/hexagonal-order-api/).
+Deep teaching example (runnable API + break exercises): [hexagonal-order-api](https://github.com/pedroknigge/arkgate/tree/main/examples/hexagonal-order-api).
 
 ## Brownfield vs greenfield
 
@@ -63,5 +63,5 @@ Deep teaching example (runnable API + break exercises): [hexagonal-order-api](..
 ## Related
 
 - [Agent integration guide](../agent-guide.md)
-- [Public demos](../demos/)
-- [Examples index](../../examples/README.md)
+- [Public demos](https://github.com/pedroknigge/arkgate/tree/main/docs/demos)
+- [Examples index](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md)

package/docs/enthusiast/how-to-gallery-starter.md

@@ -10,7 +10,7 @@ npm install
 npm run check
 ```
 
-Pick by archetype — see [examples/README.md](../../examples/README.md).
+Pick by archetype — see [examples/README.md](https://github.com/pedroknigge/arkgate/blob/main/examples/README.md).
 
 ## When to use a starter vs hexagonal-order-api
 
@@ -24,4 +24,4 @@ Pick by archetype — see [examples/README.md](../../examples/README.md).
 1. Run `ark-check --doctor`
 2. Install gates: `ark-check --install-agent-gates`
 3. Use `/ark-place` for new files
-4. Optionally commit `ark-adoption-plan.json` from `--write-plan` alongside `ark.config.json`
+4. Optionally commit `ark-adoption-plan.json` from `--write-plan` alongside `ark.config.json`