arkgate 4.7.1 → 4.7.3

package/CHANGELOG.md

@@ -5,13 +5,50 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.7.3 — 2026-08-25
+
+**Patch** over **4.7.2**. Remaining first-contact copy: README H1, below-fold headings,
+product-voice lexicon, live site pages, and doctor HTML strings. Same deny.
+**No required config migration.** Does not close Z09 / K01.
+
+**Status: prepared** (not on npm `latest` until publish; see `docs/releases/4.7.3.md`).
+
+### Changed
+
+- **README H1** is the deny, not “Architecture Co-pilot”. Below the fold: two kinds of
+  rules (not “two planes”); required CI is the hard line (not “merge gate”).
+- **Product voice** North star and lexicon prefer rules file / the write is rejected /
+  doctor. Allowlist wins.
+- **npm keywords** drop `co-pilot` / `write-gate`.
+- **Doctor HTML** strings drop co-pilot. ADR 0001 product title unchanged. Historical
+  4.6.2 three-beat line stays in that release note.
+
+## 4.7.2 — 2026-08-25
+
+**Patch** over **4.7.1**. Public copy uses ordinary software words: if the AI writes an
+illegal import, the write is rejected; the same check fails the pull request. Not an API Gateway.
+Not a folder linter. If the check is not required on the PR, the rules file is
+just documentation. **No required config migration.** Does not close Z09 / K01.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.7.2.md`).
+
+### Changed
+
+- **First-contact wording (common language):** README, use/develop/docs hub/enthusiast,
+  agent-guide, ai-gates, package-surface openings, compact agent router, skill picker
+  `description` frontmatter, first-run CLI help, compact doctor strings, Action and MCP
+  descriptions, npm `description`, and the live product site lead with the deny. How:
+  one rules file, one check, one next step. Authority:
+  [product voice](docs/product-voice.md). ADR 0001 product title unchanged. Historical
+  4.6.2 three-beat line stays in that release note.
+
 ## 4.7.1 — 2026-08-25
 
 **Patch** over **4.7.0**. One project skill catalog, visible package version in the
 skill picker, no home duplicates, ArkRun routed through existing skill names.
 **No required config migration.** Does not close Z09 / K01.
 
-**Status: unpublished** (implementation on `main`; npm `latest` remains **4.7.0** until publish).
+**Status: published** (on npm `latest`; see `docs/releases/4.7.1.md`).
 
 ### Added
 

package/README.md

@@ -1,11 +1,13 @@
 <div align="center">
 
-# ArkGate — Architecture Co-pilot for AI TypeScript
+# ArkGate — illegal imports rejected at write and at merge
 
-**One architecture config. One check. One coach.**
+**If the AI writes an illegal import, the write is rejected. The same check fails the pull request.**
 
-Your AI writes most of the code. ArkGate keeps that work inside an architecture you can trust —
-and makes sure a “green” check means something real.
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the rules
+file is just documentation.
+
+**One rules file. One check. One next step.**
 
 [![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
 [![CI](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroknigge/arkgate/actions/workflows/ci.yml)
@@ -16,11 +18,12 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.7.0** is on npm `latest`. Optional **ArkRun** extra on schema `1.2`.
+> **ArkGate 4.7.3** (tree). npm `latest` remains **4.7.2** until this patch publishes.
+> If the AI writes an illegal import, the write is rejected. Optional **ArkRun** extra on schema `1.2`.
 > A tree is **adopted** only with a required GitHub status running `arkgate-check --strict-merge`,
 > or `.ark/adoption-stance.json` `stance: "advisory-only"`. Doctor is compact (`--doctor --all`
-> for Details). [4.7.0 notes](docs/releases/4.7.0.md) · [4.6.7](docs/releases/4.6.7.md) ·
-> [4.6.6](docs/releases/4.6.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> for Details). [4.7.3 notes](docs/releases/4.7.3.md) · [4.7.2](docs/releases/4.7.2.md) ·
+> [4.7.1](docs/releases/4.7.1.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -41,21 +44,20 @@ Full map: **[docs/README.md](docs/README.md)**
 ```bash
 npm install -D arkgate typescript
 npx arkgate start                 # preview files + commands
-npx arkgate start --apply         # compact contract + host router + CI plan
-npx arkgate-check --doctor        # control plane: status light + primary next action
-npx arkgate-check --doctor --all  # encyclopedia (Details)
+npx arkgate start --apply         # compact config + host router + CI plan
+npx arkgate-check --doctor        # what's wrong, what to do first
+npx arkgate-check --doctor --all  # full details
 ```
 
-That is the product. Doctor is the control plane — when stuck, do **primary next action #1**.
-JSON still carries improvement compass and coach (**not a score**). Compact human output does not.
+That is the product. Stuck? Run `--doctor` and do action **#1**.
 
 ```text
-start → doctor (+ compass) → /ark-adopt (session 0) → day-to-day /ark-place
-                         ↘ /ark-explore then /ark-autopilot when leftover design remains
+start → doctor → new files in the right folder
+              ↘ leftover mess: map, then one small refactor
 ```
 
-Teams: keep the constitution out of product PRs. Local gate
-`ark-check --changed --base origin/dev`. Steward law PRs use `--contract-session`.
+Keep the rules file out of product PRs. Local check:
+`ark-check --changed --base origin/dev`. Changing the rules themselves uses `--contract-session`.
 
 Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No install lifecycle scripts.
 
@@ -65,17 +67,19 @@ Aliases `ark` / `ark-check` / `ark-mcp` still work. npm / pnpm / yarn. No instal
 
 ## What it is
 
-A machine-readable architecture file (`ark.config.json`) plus enforcement:
+Import rules for TypeScript, enforced twice: the editor hook rejects the write, and a
+**required** CI check rejects the pull request. `ark.config.json` is the rules file those
+checks read.
 
 | When | Tool |
 |------|------|
-| **While the AI writes** | Pre-write block on supported hosts; warning only elsewhere |
+| **While the AI writes** | The write is rejected on supported hosts; warning only elsewhere |
 | **Before merge** | `arkgate-check` as a **required** CI status |
 
-### Two planes (4.0)
+### Two kinds of rules (4.0)
 
-| Plane | What it guards | Config |
-|-------|----------------|--------|
+| Kind | What it guards | Config |
+|------|----------------|--------|
 | **Layers** (always) | Who may import whom — imports, placement, purity, isolation | `ark.config.json` layers + rules |
 | **ArkRules** (opt-in; structure rules inside a layer) | Habits *inside* a layer — structure sensors + domain invariants as data | `arkRules` → `arkrules/<Layer>.json` |
 | **ArkRun** (opt-in extra) | Kernel usage + complete declarations | `arkRun` on schema `1.2` |
@@ -83,7 +87,9 @@ A machine-readable architecture file (`ark.config.json`) plus enforcement:
 Absence of ArkRules or ArkRun changes no inter-layer verdict. Label residual **`[Layer]`** vs **`[ArkRules]`**.  
 Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
-**Not** a web framework, ORM, or job runner. Optional **ArkRun** extra and companion kernel (`@arkgate/runtime`) are separate and not required for the gate. In-memory stores are not production durability.
+**Not** an API Gateway, a folder linter, a web framework, ORM, or job runner. Optional
+**ArkRules** and **ArkRun** extras are off unless you turn them on. In-memory stores are
+not production durability.
 
 **Name note:** npm package `arkgate` — not affiliated with the separate Archgate CLI project.
 
@@ -91,8 +97,9 @@ Details: [configuration](docs/configuration.md) · [use path](docs/use.md).
 
 ArkGate is overkill for small trees with **no AI agents** and **no multi-layer boundaries**, for
 single-developer hobby CRUDs under no integration pressure, and for teams that will not maintain
-`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. In those
-cases stay with a boundary linter alone (see [Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
+`ark.config.json` or a **required** CI status running `arkgate-check --strict-merge`. Without that
+status the rules file is just documentation — stay with a boundary linter alone (see
+[Why not only ESLint / Nx / cruiser?](#why-not-only-eslint--nx--cruiser)).
 Anyone path: [docs/use.md — When not to adopt](docs/use.md#when-not-to-adopt). Limits of a green
 check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-is--isnt).
 
@@ -105,7 +112,7 @@ check: [4.3.0 — What ArkGate is / isn't](docs/releases/4.3.0.md#what-arkgate-i
 | **Suggest** | Thin / new tree | Finish `start` → doctor |
 | **Adapt** | Not fully protected | Doctor action #1 |
 | **Enforce** | Honest import edges, and no new UI business-rule files vs merge-base | Keep write path + CI |
-| **Enforce · design-weak** | Edges clean; design residual remains | Shape residual — not “done” |
+| **Enforce · leftover design work** | Edges clean; leftover design work remains | Shape residual — not “done” |
 
 Details: [docs/use.md](docs/use.md).
 
@@ -132,22 +139,22 @@ filesystem writes, hosted or specialized opt-out paths, and human edits still re
 This table describes the supported profile **after its files are installed and the host loads/trusts them**. A hard local boundary covers only the listed hook operations; alternate tools, direct filesystem writes, and human edits still rely on CI. MCP validation is advisory because the agent must call it. The CI check blocks a merge only when the repository makes that status required. Repair **envelopes** may be emitted without reinjection being guaranteed; silent auto-apply never happens. Run `arkgate-check --doctor` (or `ark-check --doctor`) for the evidence actually detected in the current repository.
 <!-- arkgate-host-support:end -->
 
-#### Why the hard guarantee lives at the merge gate
+#### Why required CI is the hard line
 
 The split above is a deliberate trade-off, not a gap. ArkGate validates at the earliest boundary
 each host offers and enforces at the earliest boundary a repository can make non-bypassable: the
 required merge status. Hard hooks (Claude Code, Grok Build, Google Antigravity, Cursor, and
 Codex’s complete local `apply_patch`) deny their listed write operations at write time; advisory
-surfaces (MCP, rules, OpenCode plugins) coach the agent while it works. But any local boundary can
+surfaces (MCP, rules, OpenCode plugins) warn the agent while it works. But any local boundary can
 be routed around — another tool, a hosted/specialized path, a direct filesystem write, or a human
 edit — so the only guarantee ArkGate claims for every path is the
 `arkgate-check --strict-merge` check, and only when the repository makes that status required.
-Local checks optimize feedback speed; the merge gate owns correctness.
+Local checks optimize feedback speed; required CI owns correctness.
 
-A useful consequence: the contract doubles as a pressure sensor. Recurring violations or baseline
+A useful consequence: the rules file doubles as a pressure sensor. Recurring violations or baseline
 exceptions concentrated on one layer edge are evidence that the current design stopped fitting the
-code — a reason to reshape the contract deliberately (start with `/ark-explore`), never to weaken
-the gate.
+code — a reason to reshape the rules deliberately (start with `/ark-explore`), never to weaken
+the check.
 
 Setup per host: [docs/ai-gates.md](docs/ai-gates.md) · Develop path: [docs/develop.md](docs/develop.md)
 
@@ -165,7 +172,7 @@ expectation.
 |--|:---:|:---:|
 | CI import rules | ✅ | ✅ |
 | Hard-block AI writes on supported hosts | ✅ | ❌ |
-| Project-bound contract agents can read (`ark_manifest`) | ✅ | ❌ |
+| Project-bound rules agents can read (`ark_manifest`) | ✅ | ❌ |
 | Placement + preflight for multi-file changes | ✅ | ❌ |
 | Honest governed % + dual plan (edges vs shape) | ✅ | ❌ |
 | Opt-in intra-layer ArkRules (structure + invariants) | ✅ | ❌ |
@@ -227,7 +234,9 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current published (4.7.0 on npm `latest`) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current tree (4.7.3) | [docs/releases/4.7.3.md](docs/releases/4.7.3.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.7.2 on npm `latest`) | [docs/releases/4.7.2.md](docs/releases/4.7.2.md) |
+| Prior published (4.7.0) | [docs/releases/4.7.0.md](docs/releases/4.7.0.md) |
 | Prior published (4.6.7) | [docs/releases/4.6.7.md](docs/releases/4.6.7.md) |
 | Prior published (4.6.6) | [docs/releases/4.6.6.md](docs/releases/4.6.6.md) |
 | Prior published (4.6.5) | [docs/releases/4.6.5.md](docs/releases/4.6.5.md) |
@@ -266,4 +275,4 @@ Full guide: [CONTRIBUTING.md](CONTRIBUTING.md) · queue: [ROADMAP.md](ROADMAP.md
 **MCP:** [`io.github.pedroknigge/arkgate`](https://registry.modelcontextprotocol.io/)  
 Node ≥ 18 · **MIT**
 
-**Ark doesn’t invent your product. It keeps AI-generated TypeScript inside an architecture you can trust — and tells you when it isn’t really enforcing anything yet.**
+**Ark doesn’t invent your product. It rejects the illegal write — and tells you when it isn’t really enforcing anything yet.**

package/bin/lib/agent-projection.mjs

@@ -148,7 +148,7 @@ export function buildAgentProjectionBody(facts) {
         '',
     ];
     if (profile === 'compact') {
-        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — status light + primary next action. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Read the improvement compass (not a score). Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read architecture config with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix architecture, do not weaken the gate.', '6. Single door: import-rule debt → fix; leftover design work / residual shape lenses → map then guided apply with user OK.', '', '### Contract layers (summary)', '', formatAgentProjectionLayers(layers), '');
+        lines.push('### Primary path', '', '1. Run doctor (`ark-check --doctor`) — what is wrong and what to do first. Prefer the project-local CLI; do not wait on MCP “still connecting”.', '2. Name leftover work in plain language; never “done” on green imports alone while leftover design work remains.', '3. Identity handshake is optional when the CLI already resolved the project root. Call `ark_identity` only when using MCP evidence.', '4. Read the rules file with `ark_manifest` (same expectation) or the local `ark.config.json`. `ark://manifest` is compatibility-only / unverified.', '5. Place files inside configured layers; validate; run the check command above on violations — fix the import, do not weaken the rules file.', '6. Single door: illegal imports → fix; leftover design work → map then one small refactor with user OK.', '', '### Layers (summary)', '', formatAgentProjectionLayers(layers), '');
     }
     else {
         lines.push('### Contract layers', '', formatAgentProjectionLayers(layers), '', 'When creating a **new** kind of code that no layer covers, update `ark.config.json` first (`/ark-adopt`), then place the file.', '', '### Diagnostic codes (short list)', '', formatAgentProjectionCatalogShortList(catalog, docsPath), '', '### Session truth', '', '- Machine snapshot: `ark status --json` (or MCP `ark_status`) — identity, activation honesty, last check, residual counts. **Not a score.**', '- Authoritative contract: local `ark.config.json` / CLI, or `ark_manifest` after a matched `ark_identity` handshake. Identity is optional when CLI already resolved the root.', '- Host docs: the same projection schema is merged into `AGENTS.md` and `CLAUDE.md` (`ark agents-md --write`).', '');

package/bin/lib/ci-and-commands.mjs

@@ -314,7 +314,7 @@ ${placementTable}`;
 ${projectionBlock}
 ## Default agent flow (if unsure, do only this)
 
-1. Status anytime: \`${doctorCmd}\` — **control plane** (one status light, one next action; not a mode picker).
+1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first (not a mode picker).
 2. If \`ark.config.json\` is missing: run \`${startCmd}\` once (preview), then \`${startCmd} --apply\`.
 3. Guided end-to-end work (“make architecture sound”): **\`/ark-autopilot\`** — explore → dual plan A (edges) + B (shape) → write mechanical-safe and judgment; one Shape refactor. Day-zero origin is frozen by \`ark start\`/\`ark init\` (or adopt if missing) **before** agent docs.
 4. After ordinary feature edits: run \`${checkCmd}\` (teams: \`ark-check --changed --base origin/dev\`). On violations → **\`/ark-autopilot\`** (or \`/ark-place\` for new files). **Do not edit** \`ark.config.json\` / \`.ark-baseline.json\` in a product PR — that is a steward \`--contract-session\`. If doctor shows **Stewards (advisory)**, ask who owns the law — do not invent \`stewards[]\`. Leftover names \`/ark-fix\` / \`/ark-loop\` / \`/ark-contract\` are shortcuts to those doors.
@@ -405,10 +405,10 @@ ${projectionBlock}
 
 **Primary path (do this):**
 
-1. Status anytime: \`${doctorCmd}\` — one status light, one primary next action (control plane).
+1. Status anytime: \`${doctorCmd}\` — what's wrong and what to do first.
 2. Read the **Improvement compass** section (not a score). Name residual lenses in plain language when present (SoC, DIP, domain, …). Out-of-scope lenses (performance, app security tooling, full resilience) stay honest — do not invent Ark enforcement for them.
 3. CLI-first: if the local CLI already resolved this project root, do not wait on MCP “still connecting”. Identity handshake is optional in that case. When you do trust MCP evidence: call \`ark_identity\` with \`project.expectedRoot\` set to this project's exact absolute root, then reuse that root plus the returned \`projectIdentity.projectId\` on every Ark MCP call. A descendant path is authoritative only with that matching id. Missing tool, non-\`matched\` binding, or wrong root means this is not proven to be the right project: restart the host and use the local CLI meanwhile.
-4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a gate deny, fix the architecture — do not weaken \`ark.config.json\`.
+4. Day to day: call \`ark_manifest\` with the same project expectation (or skip if CLI already bound the root); place new files with \`ark_place\` (filePath required — fail-closed); validate after edits; run \`${checkCmd}\`. The \`ark://manifest\` resource is compatibility-only and always unverified. On a deny, fix the illegal import — do not weaken \`ark.config.json\`.
 5. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`. The host-readable projection is AGENTS.md and CLAUDE.md (same schema).
 
 **Single door when residual remains:**

package/bin/lib/enforcement-honesty.mjs

@@ -432,7 +432,7 @@ export function buildProductHonesty(input = {}) {
         message:
           operatingMode === 'adapt'
             ? 'Operating mode is ADAPT — not finished until whole-tree green, zero blocking, and zero design smells (contract and tree still disagree).'
-            : 'Operating mode is SUGGEST — not finished until whole-tree green, zero blocking, and zero design smells (contract is not yet the control plane).',
+            : 'Operating mode is SUGGEST — not finished until whole-tree green, zero blocking, and zero design smells (the rules file is not yet binding).',
       });
     }
   }

package/bin/lib/first-run-help.mjs

@@ -3,11 +3,11 @@
  */
 
 export function setupUsage() {
-  return `arkgate (alias ark) — One architecture config. One check. One coach.
+  return `arkgate (alias ark) — Illegal import: write rejected. Same check fails the PR.
 
   arkgate start              preview (no writes)
   arkgate start --apply      write host + CI setup
-  arkgate-check --doctor     where you are + one next action
+  arkgate-check --doctor     what's wrong, what to do first
 
 Stuck? Run doctor. Do #1.
 `;
@@ -27,7 +27,7 @@ Every flag: arkgate --help --all
 }
 
 export function setupUsageAll() {
-  return `arkgate (alias ark) — One architecture config. One check. One coach.
+  return `arkgate (alias ark) — Illegal import: write rejected. Same check fails the PR.
 
 Usage:
   arkgate start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]

package/bin/lib/html-report-depth.mjs

@@ -228,7 +228,7 @@ export function buildReportDepthPayload(
 export function writePathModeHint(mode) {
   switch (String(mode || '')) {
     case 'repair':
-      return 'Hard write hook with repair payload — best co-pilot path for the active host.';
+      return 'Hard write hook with repair payload — best write path for the active host.';
     case 'reject-only':
       return 'Hard write boundary without repair payload; edits can be blocked without guided re-entry.';
     case 'mcp-only':

package/bin/lib/html-report.mjs

@@ -119,7 +119,7 @@ export function modeBadgeHint(mode) {
     case 'suggest':
       return 'Starter shape — expand layers and raise governed coverage as the codebase grows.';
     default:
-      return 'Operating mode for co-pilot surfaces (suggest · adapt · enforce).';
+      return 'Operating mode for doctor surfaces (suggest · adapt · enforce).';
   }
 }
 
@@ -1165,15 +1165,15 @@ export function renderHtmlReport({
   <div class="section card" id="adoption">
     <h2>Adoption</h2>
     <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-      Co-pilot completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
+      Host completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
     </p>
     <div class="kpis" style="margin-bottom:.75rem">
       ${metricKpi(
         adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length,
         adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)',
         adoptionView.gaps.length === 0
-          ? 'Hosts, MCP argv, origin snapshot, and core optionality look complete for co-pilot use.'
-          : 'Install or fix the listed gaps so agents get write gates, MCP, and honest cores.'
+          ? 'Hosts, MCP argv, origin snapshot, and core optionality look complete for agent use.'
+          : 'Install or fix the listed gaps so agents get write hooks, MCP, and honest cores.'
       )}
       ${metricKpi(
         adoptionView.originReport.present ? 'yes' : 'no',