arkgate 3.8.2 → 3.9.0

package/CHANGELOG.md

@@ -5,6 +5,97 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 3.9.0 — 2026-07-23
+
+**Beautiful Path** minor: one primary flow, doctor as control plane, progressive disclosure, and
+senior-grade product voice — plus residual beauty, write-path honesty, Shape coach depth, and
+field-claim scaffolding. **No required config migration.** Does not weaken write gate or CI.
+Z09 / residual `RB-11` remain open (longitudinal claim gate; field kit is scaffolding only).
+Not a rewrite of the analysis engine. No plan-B silent codemod. No fake hard write on Cursor/Codex.
+
+### Added
+
+- **Product voice canon:** `docs/product-voice.md` — lexicon (including **design-weak** / **residual**
+  / hard vs advisory write), **Do** table, doctor/deny microcopy models, progressive-disclosure rule.
+  Linked from README and Agents knowledge map.
+- **Field program kit (not closed):** `docs/field/` — Z09 preregistration template, cohort D30/D90
+  checklist, independent-reviewer manifesto + open signed-identity decision. Explicit **status: not
+  closed**; does not invent adopter counts or close `RB-11` / C-028 residual.
+- **Release notes:** `docs/releases/3.9.0.md`.
+- **Docs information architecture:** three public lanes — [docs/use.md](docs/use.md) (anyone),
+  [docs/develop.md](docs/develop.md) (integrate), [CONTRIBUTING.md](CONTRIBUTING.md) (library);
+  hub [docs/README.md](docs/README.md); history under [docs/archive/](docs/archive/README.md).
+  Historical release notes and epic plans remain in-repo but are not the product front door.
+- **Maintainer workflow:** `.grok/workflows/product-beauty-audit.rhai` — read-only parallel audit of
+  product surfaces against product-voice criteria (report-only by default).
+- **Host enforcement expansion (prepared, not npm-published as a separate release):**
+  - **Google Antigravity** (`antigravity` / alias `agy`): `.agents/hooks.json` PreToolUse install,
+    `ark-mcp --hook` adapter for `toolCall` + write tools (`write_to_file`,
+    `replace_file_content`, `multi_replace_file_content`), doctor inventory, hard-write when
+    installed + trusted (same ladder as Claude/Grok).
+  - **OpenCode** (`opencode`): merge/write `opencode.json` MCP (`type: local`), advisory-only
+    write path, optional experimental plugin template
+    `templates/hooks/opencode-ark-write-gate.mjs` (never claimed hard).
+  - Canonical host matrix + README/`docs/ai-gates.md` honesty rows updated.
+
+### Changed
+
+- **README first-run narrative:** one door (`start` → doctor → optional `/ark-autopilot`); skills
+  section reframed as expert escapes, not a second curriculum; status lights language tightened;
+  host matrix states **required CI status** as the merge hard boundary and labels
+  Cursor/Codex/OpenCode advisory at write (Antigravity hard when covered).
+- **Compact router** (`compactAgentInstructions`): primary path = doctor + place/validate/check;
+  full `/ark-*` pack documented as optional expert depth with install command.
+- **Doctor human surface:** status-light copy matches product voice; top block is **Primary next
+  action** (#1) plus optional **Also** list; design-weak mode uses warn `!` (not green `✓`);
+  edge-clean under design-weak no longer claims absolute “matches the contract”; New-here primary
+  is finish `start` → doctor (not a competing recommend/architect curriculum); Cursor/Codex write
+  path lines state advisory + required CI. JSON ids (`postGreenPath`, `primaryNextAction`,
+  `clarify-for-ai`) unchanged.
+- **Post-green primary action string:** senior-grade Shape residual wording; same skill chain.
+- **Agent install messaging:** install-agent-gates prints compact vs expert-skill-pack profile hints.
+- **Skill frontmatter / mode tables:** `/ark-autopilot` = guided end-to-end; ranks **Enforce ·
+  design-weak** Shape door; `/ark-explore` = specialized map / post-green door with status-light
+  table and smell-envelope honesty (absence ≠ full-tree proof).
+- **Agent guide / AI gates / package surface:** default path and host write honesty aligned; design
+  smell envelope documented; no “default = full skill pack.”
+
+### Tests
+
+- `q01PostGreenPath` — primary-action wording, design-weak mode mark `!`, no absolute contract-match
+  under residual.
+- `skillsSurface` — autopilot/explore Shape door ranking; compact router progressive disclosure.
+- `q06ReleaseSurfaces` — 3.9.0 notes, product-voice Do/lexicon, field kit not-closed.
+- Compact-start / adoption-gaps / codex residual honesty expectations updated for voice.
+
+## 3.8.3 — 2026-07-22
+
+Corrective **patch** over 3.8.2 from multi-repo field evidence (PROPIA pnpm workspace upgrade;
+Amarilla greenfield `start`). **No required config migration.** Z09 / residual `RB-11` remain open.
+
+### Fixed
+
+- **pnpm workspace upgrade install:** `packageInstallArgv` emits `pnpm add -D arkgate@… -w` on
+  workspace roots (`pnpm-workspace.yaml`). Yarn workspaces get `-W`. npm single-package path
+  unchanged.
+- **Upgrade re-install when already current:** skip package-manager install when
+  `node_modules/arkgate` already matches this CLI version; go straight to managed preview.
+- **Install failure recovery copy:** prints the exact failed install command and a
+  `--no-install` re-run path.
+- **`start` package pin by default:** `start --apply` pins `arkgate` in `devDependencies`
+  unless `--no-install` (was: only with explicit `--install`).
+- **Compact start always writes `.mcp.json`:** every host gets project MCP registration;
+  setup budget raised to 8 files / 32 KB so MCP fits with host hooks.
+- **Unbound upgrade apply when content matches:** `--apply` without `--plan-digest` is a
+  successful no-op when `wouldWrite` is 0 (optional stamp refresh still needs the digest).
+- **Upgrade applied copy:** distinguishes content writes vs stamp/metadata refresh instead of
+  a single “Applied N changes” when only stamps moved.
+
+### Tests
+
+- `tests/unit/static-check/fieldJourney383.test.ts` — workspace argv, skip-when-current, start pin.
+- Z06 / O03 / installFieldFixes expectations updated for default pin and MCP-in-compact.
+
 ## 3.8.2 — 2026-07-22
 
 Corrective **patch** over 3.8.1 from PREDIAL WEB field evidence. Aligns doctor skill freshness with