arkgate 4.2.1 → 4.4.0

package/docs/README.md

@@ -19,17 +19,18 @@ Product site: [arkgate.online](https://www.arkgate.online/) · npm: [`arkgate`](
 ### Use (product)
 | Doc | What it is |
 |-----|------------|
-| [use.md](use.md) | One flow: install → doctor → day-to-day |
+| [use.md](use.md) | One flow: install → doctor (+ improvement compass) → day-to-day |
 | [enthusiast/](enthusiast/README.md) | Tutorials and plain-language track |
 | [demos/](demos/) | Short end-to-end demos |
-| [product-voice.md](product-voice.md) | How ArkGate should sound in English UI |
+| [product-voice.md](product-voice.md) | How ArkGate should sound in English UI (compass = lenses, not scores) |
 
 ### Develop (integrate)
 | Doc | What it is |
 |-----|------------|
 | [develop.md](develop.md) | Gates, hosts, config, brownfield, power tools |
 | [ai-gates.md](ai-gates.md) | Install hooks / MCP / CI per host |
-| [agent-guide.md](agent-guide.md) | Agent, CLI, and MCP reference |
+| [agent-guide.md](agent-guide.md) | Agent, CLI, and MCP reference (incl. `ark status --json` / MCP `ark_status`) |
+| [diagnostics.md](diagnostics.md) | Public diagnostic `ruleId` catalog (why / fix anchors) |
 | [configuration.md](configuration.md) | `ark.config.json` contract |
 | [brownfield-adoption.md](brownfield-adoption.md) | Existing messy repos |
 | [package-surface.md](package-surface.md) | Stable vs experimental package surface |
@@ -52,15 +53,15 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · [CHANGELOG.md](../CHANGELOG.md) |
-| Epic plans (seeded + shipped) | [plans/](plans/) · latest shipped: [workspace identity and activation truth](plans/workspace-identity-activation-truth/README.md) (Phase WI; **4.2.0 published**) |
+| Epic plans (seeded + shipped) | [plans/](plans/) — maintainer seeds (e.g. improvement compass for **4.4.0**, agent contract surface for **4.3.0**). Product how-to stays in use/develop/agent-guide; plans are not required reading to use the package. |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Prepared candidate: [releases/4.2.1.md](releases/4.2.1.md) (`arkgate@4.2.1`, not published).
-
-Current published: [releases/4.2.0.md](releases/4.2.0.md) (`arkgate@4.2.0` on npm `latest`).  
-Previous: [releases/4.1.1.md](releases/4.1.1.md) (`arkgate@4.1.1`) · [releases/4.1.0.md](releases/4.1.0.md) (`arkgate@4.1.0`).  
+Current published: [releases/4.3.0.md](releases/4.3.0.md) (`arkgate@4.3.0` on npm `latest`).  
+Next prepare: [releases/4.4.0.md](releases/4.4.0.md) (Status: prepared — not on npm until publish verify).  
+Prior: [releases/4.2.1.md](releases/4.2.1.md) (`arkgate@4.2.1`).  
+Previous: [releases/4.2.0.md](releases/4.2.0.md) (`arkgate@4.2.0`) · [releases/4.1.1.md](releases/4.1.1.md) (`arkgate@4.1.1`).  
 Previous major: [releases/4.0.0.md](releases/4.0.0.md) (`arkgate@4.0.0`).  
 Config: [configuration.md](configuration.md) · Agent skills dual-plane: [agent-guide.md](agent-guide.md).
 

package/docs/agent-guide.md

@@ -38,13 +38,19 @@ feature work. Full `/ark-*` skills are **expert depth** and label residual **`[L
 npx ark-check --install-agent-gates --skills-only --force
 ```
 
-**Write-path honesty:** Claude/Grok/Antigravity can hard-block listed PreToolUse ops when
-installed and trusted. Cursor/Codex/OpenCode remain **advisory at write**. For every host, the
-repository-wide hard boundary is a **required GitHub status context** that runs
-`arkgate-check --strict-merge` (alias `ark-check --strict-merge`) — the CLI name is not the
-status context name. Never claim Cursor/Codex/OpenCode hard write. Soft-write alone does not mean
-the project is unfinished; doctor keeps it as an environment residual. See [ai-gates.md](ai-gates.md)
-and the README host matrix.
+### Write-path honesty
+
+Claude/Grok/Antigravity can hard-block listed PreToolUse ops when installed and trusted.
+Cursor/Codex/OpenCode remain **advisory at write**. For every host, the repository-wide hard
+boundary is a **required GitHub status context** that runs `arkgate-check --strict-merge` (alias
+`ark-check --strict-merge`) — the CLI name is not the status context name. Never claim
+Cursor/Codex/OpenCode hard write. Soft-write alone does not mean the project is unfinished; doctor
+keeps it as an environment residual. See [ai-gates.md](ai-gates.md) and the README host matrix.
+
+Surface the same plane from the CLI: pair **`ark status --json`** (activation facts) with
+**`ark-check --doctor`** (`doctor.writePath`) — advisory local write on soft hosts → **required**
+merge status as the hard boundary. Product path: [use.md — What you get](use.md#what-you-get) ·
+[README host matrix](../README.md#host-enforcement-support).
 
 **MCP project identity (4.2.0):** before trusting project-specific MCP evidence, call
 `ark_identity` with `project.expectedRoot` set to the exact project's absolute root. Reuse that
@@ -53,6 +59,72 @@ path is authoritative only when that matching project id is also supplied. Only
 `binding.status: "matched"` with `authoritative: true` is authoritative; calls that omit the
 expectation remain compatible but are explicitly `unverified`.
 
+### Improvement compass (doctor)
+
+`ark-check --doctor` (human + `--json`) projects residual architecture work as a closed set of
+**lenses** (`doctor.improvementCompass`). Always `notAScore: true`. Never feeds `valid`,
+strict-merge exit, or plan `goal.met`. Out-of-scope lenses (scalability, app security tooling,
+full resilience) stay honest. Product path: [use.md — Improvement compass](use.md#improvement-compass-not-a-score).
+Package surface row: [package-surface.md](package-surface.md).
+
+**Status snapshot:** the status schema may carry a thin optional residual-id slice when Tooling
+passes it through, but **`ark status --json` does not compute the compass yet** — use doctor for
+residual lenses. Residual never changes status `nextAction` by itself.
+
+Compact router and skills read residual lenses in plain language; green edges alone are never
+“architecture finished” while residual remains.
+
+### Unified status snapshot (4.3)
+
+For one machine-readable session/project manifest (identity binding, honest write-path activation,
+last-check summary, rules residual counts, primary next action) use:
+
+```bash
+npx ark status --json
+# optional identity check (matched vs stale):
+npx ark status --json --expected-root /abs/project/root
+```
+
+MCP parity tool: **`ark_status`** (same envelope; pass `project.expectedRoot` after `ark_identity`).
+Schema: `arkgate/schema/status-manifest`. Never prompts; under `CI=1` JSON is forced. **Not a
+score** — counts and verdicts only. Write-path interpretation of activation vs merge teeth is under
+[Write-path honesty](#write-path-honesty).
+
+**Stable finding refs (4.3):** every factory-emitted diagnostic on CLI JSON, MCP analysis
+envelopes, and opt-in hook repair payloads (`ARK_REPAIR_JSON`) carries:
+
+| Field | Meaning |
+|-------|---------|
+| `findingRef` | Compact multi-turn id (`fnv1a-` + 8 hex). Re-address the same finding without fuzzy text match. |
+| `targetKey` | Baseline-compatible freeze identity (`ruleId\|file\|from\|to\|target`, with `#N` for duplicates). **Same plane as `--baseline`** — refs never orphan freezes. |
+| `docsCodePath` | Package-relative catalog anchor (`docs/diagnostics.md#RULE_ID`). |
+
+Line/message drift across agent turns does not change `findingRef` / `targetKey`. Schema:
+`arkgate/schema/analysis-result` **`1.5`**. Multi-turn fixture:
+`tests/fixtures/finding-refs/multi-turn-stability.json`.
+
+**Version-matched agent projection (4.3):** install/upgrade embeds a managed AGENTS.md
+block stamped with the installed `arkgate` version plus a compact contract summary (layers +
+diagnostic short list). Regenerate after package upgrade without clobbering customized regions
+outside the markers:
+
+```bash
+npx ark agents-md              # preview
+npx ark agents-md --write      # merge managed block only
+npx ark agents-md --check      # exit 1 on version/stamp drift
+npx ark agents-md --stdout     # print block only
+```
+
+The projection is **non-authoritative**. Enforcement is `ark-check` / host write hooks / required
+CI (`--strict-merge`) — never AGENTS.md, skills, or this projection. Root API:
+`buildAgentProjectionBlock` / `mergeAgentProjectionDocument`.
+
+**Agent Skills packaging (4.3):** the same frozen **13** skill names are also shipped as
+an Agent Skills–compatible package under `templates/agent-skills/<name>/SKILL.md` for hosts that
+install via `npx skills` (in addition to Ark `--install-agent-gates`). See
+[Install skills — Ark and ecosystem](#install-skills-ark-and-ecosystem). No new skill names.
+Skill bodies coach residual lenses and anti false-done; they never enforce.
+
 ## Architecture playbook and `ark-check --recommend`
 
 Before generating project structure, agents should read the **tool-agnostic application
@@ -486,6 +558,40 @@ monotonic across ArkGate 4.2.0+ installers. Pre-4.2 binaries ignore its metadata
 upgrade legacy repos before they write the optional home catalog. See
 [AI gates — Codex skill catalog](ai-gates.md#codex-skill-catalog-skillmd-not-flat-prompts).
 
+### Install skills — Ark and ecosystem {#install-skills-ark-and-ecosystem}
+
+The same **13** skill names ship two ways. **No new skill names** (4.3 freeze): packaging and
+routing only.
+
+| Channel | What it installs | When to use |
+|---------|------------------|-------------|
+| **Ark install** | Host skill catalogs + optional hooks/MCP/CI wiring via `--install-agent-gates` | Default for projects that want write-path gates and version-stamped managed catalogs |
+| **Agent Skills ecosystem** (`npx skills`) | The Agent Skills layout only (`<name>/SKILL.md`) into host skill dirs | Hosts already on the open skills channel; discovery without running Ark install |
+
+**Canonical authoring source:** flat `templates/skills/<name>.md` (Ark install reads these).
+
+**Agent Skills package root** (generated, 1:1 content): `templates/agent-skills/<name>/SKILL.md`
+— ships in the npm tarball under `templates/`. Drift guard: `npm run check:agent-skills`.
+
+```bash
+# Ark — expert skill pack (preferred when you also want gates)
+npx ark-check --install-agent-gates --skills-only --force
+
+# Ecosystem — from installed package or a git checkout
+npx skills add ./node_modules/arkgate/templates/agent-skills
+npx skills add ./templates/agent-skills
+# GitHub tree:
+npx skills add https://github.com/pedroknigge/arkgate/tree/main/templates/agent-skills
+# List without installing:
+npx skills add ./node_modules/arkgate/templates/agent-skills --list
+```
+
+Frozen names: `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`. Root API: `ARK_SKILL_NAMES` / `validateAgentSkillsPackage` (Domain
+`agentSkillsPackage`). Skills are **process** depth — they never decide pass/fail; enforcement
+remains `ark-check` / hooks / CI.
+
 For an optional executable adoption check, copy the shipped template into a Vitest/Jest suite
 after installing ArkGate:
 
@@ -646,6 +752,11 @@ Relevant violation codes include `LAYER_IMPORT_VIOLATION`, `FORBIDDEN_GLOBAL`,
 `FORBIDDEN_SUBSTRING`, `FORBIDDEN_IMPORT`, `POLICY_VIOLATION`, `UNKNOWN_INTENT`,
 `LAYER_REFERENCE_VIOLATION`, `EXTENSION_ERROR`, and `AST_ANALYZER_ERROR`.
 
+**Full catalog (ACS02):** every public `ruleId` with why/fix anchors lives in
+[diagnostics.md](diagnostics.md) (stable fragment `#RULE_ID`) and the root API
+`DIAGNOSTIC_CATALOG` / `getDiagnosticCatalogEntry` / `diagnosticDocsPath`. Agents must not
+invent free-form rule ids outside that closed vocabulary.
+
 Use `ark-check` in CI for repository-level checks that need real file paths:
 
 ```bash
@@ -893,7 +1004,7 @@ npx ark-mcp --root . --config ark.config.json [--manifest ark.manifest.json]
   this resource `unverified` and non-authoritative. It never substitutes for `ark_manifest` in
   a project verdict.
 
-The server exposes these twelve tools. Every tool accepts the additive
+The server exposes these thirteen tools. Every tool accepts the additive
 `project: { expectedRoot, expectedProjectId? }` input:
 
 | Tool | Primary input and purpose |
@@ -910,6 +1021,7 @@ The server exposes these twelve tools. Every tool accepts the additive
 | `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. |
 | `ark_rules_inventory` | No args: inventory possible intra-layer rules using configured layer evidence when available; test/fixture/seed/migration surfaces and narrow technical constants are excluded from extraction pilots. Counts are not a score. |
+| `ark_status` | No non-project args: return the unified status-manifest envelope (identity binding, honest write-path activation, last-check summary, rules residual counts, primary next action). Same shape as `ark status --json`. Prefer after `ark_identity`. Never a score. |
 
 Every project-bound tool success, tool error, and JSON-RPC error data carries:
 
@@ -957,13 +1069,15 @@ when the binding is matched, analysis is complete, the graph is valid, coverage
 are active. The underlying CLI fields remain present for diagnosis, but are not an authoritative
 whole-project green on their own.
 
-Current diagnostic envelopes use schema `1.4` and require `mode`,
+Current diagnostic envelopes use schema `1.5` 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.
+`completenessReasons`. Factory-emitted diagnostics carry stable `findingRef`, baseline-compatible
+`targetKey`, and `docsCodePath` (ACS06). 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.4 `AdapterResult` values remain accepted by the
+public union (refs optional on those older envelopes).
 
 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

package/docs/configuration.md

@@ -94,6 +94,13 @@ Layer fields:
   (`network`, `filesystem`, `clock`, `randomness`, `environment`, `process`, `persistence`);
   `pure: true` is the shorthand that denies all seven. Absence changes no verdict.
 
+**Day-to-day maintenance:** new modules that land under an existing layer `patterns` glob need **no**
+config edit. Edit `ark.config.json` when you add a layer, change who may import whom, cover an
+ungoverned path under `include`, or adjust capabilities / forbidden globals. Optional ArkRules
+`invariants[].appliesTo` globs only narrow *which files* a named invariant considers inside that
+layer — they do not replace Layers placement. Empty `appliesTo: []` fails closed; zero-match globs
+warn or fail by mode (`ARKRULE_SCOPE_EMPTY`). Product path: [use.md — New modules vs config edits](use.md#new-modules-vs-config-edits).
+
 `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` /

package/docs/develop.md

@@ -68,6 +68,11 @@ can show `runtimeObserved: true` even when branch-protection policy is plan-unav
 | ArkRules (structure + invariants) | [configuration.md](configuration.md#arkrules-intra-layer-opt-in) · `arkRules` / `arkrules/*` · skill `/ark-contract` |
 | Rules inventory (brownfield) | `arkgate-check --rules-inventory` · MCP `ark_rules_inventory` |
 | Stable package API | [package-surface.md](package-surface.md) |
+| Diagnostic codes (`ruleId` why/fix) | [diagnostics.md](diagnostics.md) · root `DIAGNOSTIC_CATALOG` |
+| Session / project status snapshot | `ark status --json` · MCP `ark_status` · [agent-guide](agent-guide.md) · schema `arkgate/schema/status-manifest` |
+| Version-matched AGENTS projection | `ark agents-md` · [agent-guide](agent-guide.md) · **non-authoritative** (never enforces) |
+| Stable finding refs (`findingRef` / `targetKey`) | analysis-result schema **1.5** · [agent-guide](agent-guide.md) · [package-surface](package-surface.md) |
+| Agent Skills layout (same 13 names) | `templates/agent-skills/` · [agent-guide](agent-guide.md#install-skills-ark-and-ecosystem) · `npx skills add …` |
 | Where new code goes | MCP `ark_place` · skill `/ark-place` (respects layer **and** structure sensors) |
 | Preflight multi-file change | MCP `ark_prepare_change` · `ark preflight --changes …` |
 | Write snippet preflight | MCP `ark_prepare_write` |
@@ -95,9 +100,12 @@ Sensors:
 ```bash
 npx arkgate-check --plan
 npx arkgate-check --coverage
-npx arkgate-check --doctor --json
+npx arkgate-check --doctor --json   # improvementCompass (notAScore lenses) + status light
 ```
 
+Doctor residual lenses never flip `valid` / strict-merge alone. Product path:
+[use.md — Improvement compass](use.md#improvement-compass-not-a-score).
+
 Agent reference (tools, skills, dual path): [agent-guide.md](agent-guide.md).
 
 ---
@@ -117,6 +125,9 @@ npx arkgate-check --doctor --json
 npx arkgate-check --plan --json
 npx arkgate-check --coverage
 npx arkgate-check --baseline
+npx arkgate status --json           # session/project snapshot (not a score)
+npx arkgate agents-md               # preview managed AGENTS block
+npx arkgate agents-md --write       # embed/refresh projection markers
 npx arkgate preflight --changes changes.json --json
 npx arkgate upgrade --json          # managed content preview
 npx arkgate upgrade --apply