arkgate 4.2.0 → 4.3.0

package/docs/package-surface.md

@@ -16,7 +16,7 @@ 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. In 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. In 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the ACS03 unified status snapshot. `ark agents-md` is the ACS04 version-matched agent projection (non-authoritative). |
 | **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 a smell is not full-tree proof** above that envelope (incomplete/`partial` analysis also never proves “no smells”). **4.2 feedback hardening:** mode labels preserve the observed SUGGEST/ADAPT/ENFORCE state; a local permission/UI-state `canEdit` name alone is not a domain smell; real UI business rules route Domain → Application → UI; seed/fixture/demo/migration/generated files are not god-module pilots. 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. |
@@ -34,7 +34,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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 and snapshot evidence (X01/4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | 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. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
-| **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
+| **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the ACS03 status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
 | **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`arkRules`** map (schema `1.1+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `arkRules` is byte-for-byte silent on inter-layer verdicts. |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
@@ -47,11 +47,16 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **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. |
 | **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.4` adds optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `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/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.5`** (ACS06) adds optional stable finding refs on diagnostics: `findingRef` (`fnv1a-` + hex), `targetKey` (baseline-compatible freeze identity), `docsCodePath` (`docs/diagnostics.md#RULE_ID`). Factory-emitted diagnostics always include them; consumer-owned 1.0–1.4 values remain valid without them. `1.4` added optional `evidence.arkruleId` / `evidence.arkruleSource` for ArkRules; `1.3` distinguished `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. |
+| **Stable finding refs (ACS06 / 4.3)** | Root API `adapterFindingTargetKey` / `adapterFindingRefFromTargetKey` / `toAdapterDiagnostic` / `createAdapterResult`; CLI/MCP/repair envelopes via analysis-result diagnostics | Multi-turn re-address without fuzzy message match. `targetKey` **is** the baseline (occurrence) key so freeze identity is never orphaned; `findingRef` is a compact FNV-1a of that key. Line/message drift does not change the ref. Multi-turn fixture: `tests/fixtures/finding-refs/multi-turn-stability.json`. |
+| **Diagnostic code catalog (ACS02)** | Root API `DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`; docs [diagnostics.md](diagnostics.md) (`#RULE_ID` anchors) | Closed vocabulary of public `ruleId`s with why/fix anchors. Cataloguing only — no new rule semantics. Remediation parity is test-guarded. Docs ship in the npm tarball. |
+| **Status manifest (ACS03)** | CLI `ark status [--json]`; MCP `ark_status`; `arkgate/schema/status-manifest`; root API `buildStatusManifest` / `ARK_STATUS_MANIFEST_SCHEMA` | Schema `1.0`. One session/project snapshot: identity binding, honest write-path activation (`hard`\|`advisory`\|`unavailable`), last-check summary, rules residual counts, primary next action. **Not a score.** Never prompts (`CI=1` forces JSON). Optional `--expected-root` / `--expected-project-id` (MCP `project`) for matched vs stale identity. |
+| **Agent contract projection (ACS04)** | CLI `ark agents-md [--write] [--check] [--stdout] [--json]`; install/upgrade AGENTS templates; root API `buildAgentProjectionBlock` / `mergeAgentProjectionDocument` | Schema `1.0` (projection markers). Version-stamped managed block (`arkgateVersion` + contract summary + diagnostic short list). **Non-authoritative** — not a gate input; enforcement is ark-check / hooks / CI. Content-identity merge preserves customized regions outside markers. Drift: `--check` vs package version. |
+| **Agent Skills packaging (ACS05)** | `templates/agent-skills/<name>/SKILL.md` (+ package README); root API `ARK_SKILL_NAMES` / `validateAgentSkillsPackage`; `npm run check:agent-skills` | Schema `1.0` (package contract). Same **13** skill names as flat templates; Agent Skills–compatible layout for `npx skills add`. No new skill names. Layout is generated 1:1 from `templates/skills/*.md`. |
 | **`arkgate/schema/arkrules`** or **`arkgate/schema/ark.arkrules.schema.json`** | Per-layer structure sensors + invariant catalog (ADR 0012) | Schema `1.0`. Opt-in via root `arkRules` map (`ark.config` schema `1.1`). |
 | **`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; install via `--install-agent-gates` (often `--skills-only` on top of compact) | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. |
+| **Agent skills** | `/ark-*` templates; install via `--install-agent-gates` (often `--skills-only` on top of compact) **or** Agent Skills ecosystem path | **Day zero** is the compact router from `ark start` / `start --apply` + doctor control plane — not the full skill pack. Skill *names* (frozen **13**) and the guided expert path (`/ark-autopilot` after pack install) are stable; internal skill prose may evolve. **4.0:** all skills except experimental `/ark-runtime` integrate **layers + ArkRules** and must label residual `[Layer]` vs `[ArkRules]`. **4.2:** repo catalogs are content-idempotent; the optional shared Codex home catalog is monotonic across 4.2.0+ installers. Pre-4.2 writers are outside that protocol and must be upgraded first. A durable pending-catalog journal preserves the floor across an interrupted install and is cleared only by its owning same/newer recovery. **4.3 / ACS05:** Agent Skills–compatible layout at `templates/agent-skills/<name>/SKILL.md` (1:1 with flat `templates/skills/*.md`); install via `npx skills add ./node_modules/arkgate/templates/agent-skills` (or the GitHub tree). Domain `ARK_SKILL_NAMES` + `validateAgentSkillsPackage`; drift `npm run check:agent-skills`. Skills never enforce. |
 | **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. |
@@ -87,7 +92,10 @@ are grouped below.
 
 | Group | Exported runtime values |
 |-------|-------------------------|
-| Metadata and adapter diagnostics | `version`, `ARK_ANALYSIS_RESULT_SCHEMA_VERSION`, `ARK_ANALYSIS_RESULT_SCHEMA`, `createAdapterResult`, `toAdapterDiagnostic` |
+| Metadata and adapter diagnostics | `version`, `ARK_ANALYSIS_RESULT_SCHEMA_VERSION`, `ARK_ANALYSIS_RESULT_SCHEMA`, `ADAPTER_DIAGNOSTIC_DOCS_RELATIVE_PATH`, `createAdapterResult`, `toAdapterDiagnostic`, `adapterFindingTargetKey`, `adapterFindingOccurrenceTargetKeys`, `adapterFindingRefFromTargetKey`, `adapterDocsCodePath` |
+| Diagnostic code catalog (ACS02 / 4.3) | `DIAGNOSTIC_CATALOG`, `DIAGNOSTIC_RULE_IDS`, `DIAGNOSTIC_CATALOG_SCHEMA_VERSION`, `DIAGNOSTIC_DOCS_RELATIVE_PATH`, `getDiagnosticCatalogEntry`, `isKnownDiagnosticCode`, `isCataloguedOrArkRuleFamily`, `diagnosticDocsPath`, `diagnosticDocsFragment`, `catalogWhyForRuleId`, `catalogFixForRuleId`, `serializeDiagnosticCatalog` |
+| Status manifest (ACS03 / 4.3) | `ARK_STATUS_MANIFEST_SCHEMA_VERSION`, `ARK_STATUS_MANIFEST_SCHEMA_URL`, `ARK_STATUS_MANIFEST_SCHEMA`, `buildStatusManifest`, `evaluateStatusBinding`, `classifyStatusWritePath`, `resolveStatusNextAction`, `defaultHonestLabel` |
+| Agent contract projection (ACS04 / 4.3) | `ARK_AGENT_PROJECTION_SCHEMA_VERSION`, `DEFAULT_AGENT_PROJECTION_RULE_IDS`, `AGENT_PROJECTION_NON_ENFORCEMENT_LABEL`, `buildAgentProjectionBlock`, `buildAgentProjectionBody`, `buildAgentProjectionMeta`, `mergeAgentProjectionDocument`, `extractAgentProjectionBlock`, `projectionMatchesPackageVersion`, `agentProjectionContentIdentity` |
 | MCP project identity | `ARK_PROJECT_IDENTITY_SCHEMA_VERSION`, `ARK_PROJECT_IDENTITY_SCHEMA_URL`, `ARK_PROJECT_IDENTITY_SCHEMA`, `PROJECT_EXPECTATION_SCHEMA`, `PROJECT_BINDING_SCHEMA`, `createProjectId`, `createProjectIdentity` |
 | AI snippet gate | `createAICodeGate` |
 | Profiles and config factories | `createArchitectureProfile`, `createArchitectureProfileFromArkConfig`, `createElevenLayerArkConfig`, `elevenLayerProfile` |
@@ -101,6 +109,7 @@ The type-only root exports are also semver-supported:
 
 - Adapter diagnostics: `AdapterDiagnostic`, `AdapterResult`, `AdapterSeverity`,
   `AdapterViolationInput`, `AdapterCompletenessReason`, `AnalysisCompleteness`, `AnalysisMode`.
+- Diagnostic catalog: `DiagnosticCatalogEntry`, `DiagnosticCategory`.
 - MCP project identity: `ProjectIdentity`, `ProjectExpectation`, `ProjectBinding`.
 - Resolved facts: `ResolvedCandidateFacts`, `ResolvedCandidateFactsInput`, and their
   dependency/file/evidence component types.
@@ -194,9 +203,11 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(prepared: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md);
-current published: [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md);
-previous: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md),
+(prepared candidate: [4.3.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.3.0.md);
+current published: [4.2.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.1.md);
+previous: [4.2.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.2.0.md),
+[4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md),
+[4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md),
 [4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md),
 [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.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/product-voice.md

@@ -21,6 +21,9 @@ because the design space is small and honest.
   opt-in.
 - **Co-pilot side:** where code belongs, who talks to whom, how; dual plan **A** (edges) +
   **B** (shape); one pilot at a time; never silent judgment codemod; never weaken the contract.
+- **Agent contract surface (4.3.0):** agents read **guardrail catalogs** and **scan** evidence;
+  they **process** (judge / coach) outside the package. Projection and skills never become the
+  pass/fail gate.
 - **False done is forbidden:** Enforce ≠ elegant design. `design-weak` / residual must not
   read as “healthy finished.” Empty ArkRules inventory is not a score. MCP configuration on
   disk is not proof that the current process belongs to this project.
@@ -83,6 +86,31 @@ Examples:
 | **required CI / status context** | Merge hard boundary when the repository makes the Ark job a **required GitHub status context** (CLI: `arkgate-check --strict-merge` / `ark-check --strict-merge`) |
 | **contract ready** | Project/layers/ArkRules honesty residual clear — not the same as “hard local write” |
 | **environment residual** | Permanent host/provider posture (e.g. soft-write Codex) kept in evidence without forcing global **Not finished** |
+| **guardrail catalog** | Closed vocabulary of allowed sensors, capabilities, diagnostic `ruleId`s, and skill roles — agents and copy choose from the catalog; they do not invent free-form enforcement claims |
+| **scan** | Deterministic engine / CLI / MCP evidence pass (layers, ArkRules sensors, status facts, prepare-write). Same inputs → same verdict. No LLM. |
+| **process** (agent judgment) | Skill- or agent-side coaching: placement, dual-plan, pilot choice, remediation order. Improves prevention; **never** package pass/fail |
+| **diagnostic code** / **ruleId** | Stable public violation id (e.g. `LAYER_IMPORT_VIOLATION`) with shared why/fix anchors — catalog-linked, not prose-only ([diagnostics.md](diagnostics.md)) |
+| **agent projection** | Version-matched AGENTS/CLAUDE (or equivalent) block generated from package + contract; **non-authoritative** — enforcement is ark-check / hooks / CI |
+| **finding ref** | Stable id for a finding across turns (ruleId + target key), so agents re-address without fuzzy message match |
+| **status snapshot** | One machine-readable project/session manifest (`ark status --json` shape): identity, activation honesty, last check, residual counts — not a numeric score |
+
+## Scan vs process (dual depth)
+
+Borrow the harness *shape* (scan facts, then process with judgment) without shipping an LLM
+verdict in core:
+
+```text
+scan  →  deterministic contract graph + host activation evidence
+process → skills / human / host agent choose pilots and wording
+gate  →  same binary verdict on every parity-capable adapter
+```
+
+| Surface | Language to use | Language to avoid |
+|---------|-----------------|-------------------|
+| CLI / MCP / CI | “Scan found…”, “Checked edges…”, “Verdict: pass/fail/incomplete” | “The model decided…”, “AI validated architecture” |
+| Skills / doctor coach | “Process next: one pilot…”, “Judgment: Shape door…” | “Process mode enforces…”, “Skill pass/fail” |
+| Catalog / codes | “ruleId from the diagnostic catalog”, “closed capability set” | Open-ended “any rule string”, free-generated sensors |
+| Projection / AGENTS.md | “Agent-facing summary; not the gate” | “Follow AGENTS.md to pass CI” |
 
 ## Do (product copy)
 
@@ -100,6 +128,10 @@ Examples:
 | Keep inventory claims evidence-bound | “Possible rule candidate in the configured Application layer.” A filename or technical constant alone is not Domain evidence. |
 | Honesty clear ≠ architecture healthy | `productHonesty.finished` means residual **architecture** honesty sensors are clear — not a green graph score. Open blocking violations, ADAPT/SUGGEST with debt, dual-truth pin, or design residual keep `unfinished: true`. Permanent soft-write alone does **not**. |
 | Separate CI runtime from provider policy | Successful CI run ≠ required status; GitHub Free plan 403 → `unavailable-plan`, not “CI never ran.” |
+| Prefer catalog language for agent DX | “Stable `ruleId` with why/fix anchors.” Not a free-form list of “things that might be wrong.” |
+| Name scan before process | “Scan: two layer import violations. Process: fix the Application→Domain edge first.” |
+| Label projection non-enforcing | “Regenerated agent contract for this package version. Enforcement remains ark-check / hooks / required CI.” |
+| Keep status counts honest | “Inventory and residual counts are evidence — not a health score.” |
 
 ## Avoid
 
@@ -124,6 +156,11 @@ Examples:
 | “Max arkRules packs = merge fails structure” | **Advisory ArkRules ≠ merge teeth.** Only `mode: "enforced"` can add teeth, and only after honest classification (FG-ARKRULES-ADVISORY-ONLY) |
 | “Type-only volume means the gate is broken” | High type-only count is placement debt (behavior OK); group under plan A type-only, offer SharedTypes starter |
 | Blurring import edges with invariants | Always label **`[Layer]`** vs **`[ArkRules]`** |
+| “Ark uses AI to decide pass/fail” / package “process verdict” | Package is zero-LLM; process is agent-side judgment only |
+| Inventing new skill **names** or preset packs as product copy filler | 4.3.0 freeze: deepen + package the 13; no new names/presets without ROADMAP promotion |
+| Treating AGENTS.md / projection / skills as the write gate | Advisory surface; hard path is hooks / MCP prepare / required CI |
+| Free-generated sensor or rule ids outside the catalog | Guardrail catalog is closed; unknown codes are a bug, not creativity |
+| Numeric “architecture health” or trust score in status JSON | Counts and residuals yes; scored trust no |
 
 ---
 
@@ -153,6 +190,9 @@ Skills table in docs = **escapes / expert**, not a second onboarding track.
 - Empty plan A is not “architecture healthy” when design residual remains.
 - One pilot at a time. Pattern bets are never mechanical-safe.
 - Doctor is the control plane: status light + next action.
+- Scan is deterministic. Process is judgment. Only the gate decides pass/fail.
+- Guardrails are a catalog, not free generation.
+- Agent docs project the contract; they never replace the gate.
 
 ## Hero phrases (forbidden)
 
@@ -160,6 +200,8 @@ Skills table in docs = **escapes / expert**, not a second onboarding track.
 - You don’t need to understand architecture.
 - We auto-fix everything safely.
 - Ship it 🚀 / crush the spaghetti with vibes.
+- The AI validated your architecture / model pass/fail.
+- Follow AGENTS.md to pass the architecture gate.
 
 ---
 
@@ -225,4 +267,7 @@ Keep dual-engine rules and **STOP** handoffs. Never claim silent full-tree resha
 - [ ] No false done under design-weak / incomplete analysis.
 - [ ] Technical terms present (contract, gate, edges, pilot) without slang.
 - [ ] Expert skills are labeled expert — not the default curriculum.
+- [ ] Scan vs process is not blurred with package LLM pass/fail.
+- [ ] Codes, sensors, and capabilities stay inside the guardrail catalog.
+- [ ] Projection / AGENTS.md never claimed as enforcement.
 - [ ] Seniors would not be embarrassed to paste the line into a PR.

package/docs/use.md

@@ -28,6 +28,19 @@ Full skill pack is **optional** (expert depth). Day-to-day: compact router + doc
 
 ---
 
+## When not to adopt
+
+Skip ArkGate (or treat it as overkill) when:
+
+- The project has **no AI coding agents** and **no multi-layer integration boundaries** worth pinning.
+- It is a **single-developer hobby CRUD** with no pressure to keep layers honest over time.
+- The team will **not** maintain `ark.config.json` layers or make `arkgate-check --strict-merge` a
+  **required** GitHub status context — without that, local advisory write stays avoidable.
+
+In those cases a boundary linter or editor rules may be enough; see [README — Why not only ESLint / Nx / cruiser?](../README.md#why-not-only-eslint--nx--cruiser). When you *do* adopt, day-to-day honesty is still: advisory write on soft hosts → required merge status. Surface that with `npx arkgate-check --doctor` or `npx arkgate status --json` ([agent guide — Write-path honesty](agent-guide.md#write-path-honesty)).
+
+---
+
 ## What you get
 
 | When | What happens |
@@ -51,6 +64,16 @@ Start always gives you **layers**. ArkRules templates may ship with start/init;
 
 **Do not confuse:** green Layers ≠ perfect design (Shape residual can remain). Covered invariants ≠ “the business always does the right thing” — they mean the named policy is declared and has symbol/test evidence.
 
+### New modules vs config edits
+
+**Happy path:** put a new module under an existing layer directory/glob (`layers[].patterns`). Usually
+**no** `ark.config.json` edit — the file classifies and the existing rules apply.
+
+**Touch the contract only when** you invent a new boundary (new layer or allow/deny edge), leave an
+ungoverned path under `include`, or need a capability / forbidden-global exception. Optional ArkRules
+`appliesTo` globs narrow invariants inside a layer; empty `appliesTo: []` fails closed. Full field
+list: [configuration.md](configuration.md).
+
 ---
 
 ## Status lights (not settings)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -33,6 +33,8 @@
     "./schema/ark.design-delta.schema.json": "./schemas/ark.design-delta.schema.json",
     "./schema/arkrules": "./schemas/ark.arkrules.schema.json",
     "./schema/ark.arkrules.schema.json": "./schemas/ark.arkrules.schema.json",
+    "./schema/status-manifest": "./schemas/ark.status-manifest.schema.json",
+    "./schema/ark.status-manifest.schema.json": "./schemas/ark.status-manifest.schema.json",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -72,6 +74,7 @@
     "docs/brownfield-adoption.md",
     "docs/configuration.md",
     "docs/package-surface.md",
+    "docs/diagnostics.md",
     "docs/threat-model.md",
     "tests/fixtures/ts-consumer",
     "templates",
@@ -107,6 +110,8 @@
     "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:agent-skills": "node scripts/generate-agent-skills.mjs",
+    "check:agent-skills": "node scripts/generate-agent-skills.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",
@@ -124,6 +129,7 @@
     "eval:agent": "node eval/run.mjs",
     "eval:corpus": "node eval/validate-corpus.mjs",
     "eval:comparative": "node eval/comparative-run.mjs",
+    "eval:placement-ab": "node eval/placement-ab-run.mjs --dry",
     "eval:loop-cost": "node eval/loop-cost-run.mjs",
     "eval:ai-velocity": "node eval/ai-velocity-run.mjs",
     "eval:change-integrity": "node eval/change-integrity-run.mjs",
@@ -160,6 +166,10 @@
     "qs": "6.15.3",
     "vite": "6.4.3",
     "postcss": "8.5.23",
+    "fast-uri": "3.1.5",
+    "nanoid": "3.3.18",
+    "brace-expansion@2": "2.1.4",
+    "brace-expansion@5": "5.0.9",
     "tsup": {
       "esbuild": "0.28.1"
     },

package/schemas/ark.analysis-result.schema.json

@@ -91,7 +91,7 @@
   ],
   "properties": {
     "schemaVersion": {
-      "const": "1.4"
+      "const": "1.5"
     },
     "mode": {
       "enum": [
@@ -252,6 +252,19 @@
           "nextAction": {
             "type": "string",
             "minLength": 1
+          },
+          "findingRef": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^fnv1a-[0-9a-f]{8}$"
+          },
+          "targetKey": {
+            "type": "string",
+            "minLength": 1
+          },
+          "docsCodePath": {
+            "type": "string",
+            "minLength": 1
           }
         }
       }

package/schemas/ark.status-manifest.schema.json

@@ -0,0 +1,244 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/arkgate@4/schemas/ark.status-manifest.schema.json",
+  "title": "ArkGate status manifest",
+  "description": "Unified session/project status snapshot for agents (identity, activation honesty, last check, rules counts, next action). Not a score.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "arkgateVersion",
+    "projectIdentity",
+    "activation",
+    "lastCheck",
+    "rules",
+    "nextAction"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "1.0"
+    },
+    "arkgateVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "projectIdentity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "projectId",
+        "resolvedRoot",
+        "resolvedConfigPath",
+        "binding",
+        "authoritative"
+      ],
+      "properties": {
+        "projectId": {
+          "anyOf": [
+            {
+              "type": "string",
+              "pattern": "^sha256:[a-f0-9]{64}$"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "resolvedRoot": {
+          "type": "string",
+          "minLength": 1
+        },
+        "resolvedConfigPath": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "binding": {
+          "enum": [
+            "matched",
+            "unverified",
+            "mismatch"
+          ]
+        },
+        "authoritative": {
+          "type": "boolean"
+        },
+        "code": {
+          "enum": [
+            "PROJECT_ROOT_MISMATCH",
+            "PROJECT_ID_MISMATCH",
+            "INVALID_PROJECT_EXPECTATION"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "activation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "writePath",
+        "host",
+        "honestLabel"
+      ],
+      "properties": {
+        "writePath": {
+          "enum": [
+            "hard",
+            "advisory",
+            "unavailable"
+          ]
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "honestLabel": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "lastCheck": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "at",
+        "verdict",
+        "activeViolations",
+        "frozenResidual"
+      ],
+      "properties": {
+        "at": {
+          "anyOf": [
+            {
+              "type": "string",
+              "minLength": 1
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "verdict": {
+          "anyOf": [
+            {
+              "enum": [
+                "pass",
+                "fail",
+                "incomplete"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "activeViolations": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "frozenResidual": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "rules": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "arkRulesLoaded",
+        "inventoried",
+        "underContract",
+        "frozenResidual"
+      ],
+      "properties": {
+        "arkRulesLoaded": {
+          "type": "boolean"
+        },
+        "inventoried": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "underContract": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "frozenResidual": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "minimum": 0
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "nextAction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "summary"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/server.json

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

package/templates/agent-skills/README.md

@@ -0,0 +1,59 @@
+# ArkGate Agent Skills package
+
+> **Generated layout (ACS05).** Do not edit SKILL.md files here by hand.
+> Author skill bodies in `templates/skills/<name>.md`, then run
+> `npm run generate:agent-skills`. Drift: `npm run check:agent-skills`.
+
+This directory is the **Agent Skills–compatible** packaging of the same **13**
+`/ark-*` skills shipped as flat templates for Ark install. **No new skill names.**
+
+Package version when last generated context: **arkgate@4.2.1**
+Schema: agent-skills package contract `1.0`
+
+## Skills (frozen catalog)
+
+- `ark-adopt`
+- `ark-architect`
+- `ark-autopilot`
+- `ark-contract`
+- `ark-coverage`
+- `ark-explain`
+- `ark-explore`
+- `ark-fix`
+- `ark-loop`
+- `ark-place`
+- `ark-runtime`
+- `ark-think`
+- `ark-upgrade`
+
+## Install — Ark (host write path + skill catalogs)
+
+Preferred when you also want hooks/MCP/CI wiring:
+
+```bash
+npx ark-check --install-agent-gates --skills-only --force
+# or full host install (hooks + MCP + skills):
+npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigravity,opencode
+```
+
+## Install — skills ecosystem (`npx skills`)
+
+From this package directory (checkout or `node_modules/arkgate`):
+
+```bash
+# Local path (after npm install arkgate, or from a git checkout)
+npx skills add ./templates/agent-skills
+# or:
+npx skills add ./node_modules/arkgate/templates/agent-skills
+
+# GitHub tree (Agent Skills package root)
+npx skills add https://github.com/pedroknigge/arkgate/tree/main/templates/agent-skills
+
+# List without installing
+npx skills add ./templates/agent-skills --list
+```
+
+Skills are **process** depth (host judgment + routing). They are **not** enforcement.
+Enforcement is `ark-check` / host write hooks / required CI (`--strict-merge`).
+
+See [docs/agent-guide.md](../../docs/agent-guide.md#install-skills-ark-and-ecosystem).