arkgate 4.1.0 → 4.1.1

package/docs/develop.md

@@ -14,14 +14,18 @@ npx arkgate start --apply
 npx arkgate-check --doctor
 ```
 
-Make the architecture check a **required** merge status (GitHub/GitLab/etc.):
+Make the architecture check a **required** merge **status context** (GitHub/GitLab/etc.). The CLI
+command is `arkgate-check --strict-merge` / `ark-check --strict-merge` — the hard boundary is
+requiring that job’s status, not merely adding a workflow file:
 
 ```yaml
 - run: npx arkgate-check --root . --config ark.config.json --strict-merge
 # or: uses: pedroknigge/arkgate@<tag-or-SHA>
 ```
 
-`--strict-merge` (or compatibility `--strict`) is the repository-wide hard boundary for every agent host.
+Generated workflows also gate `--fail-on-new-smells --base-ref` so a first push with an all-zero
+`github.event.before` still runs the full merge gate without a broken delta (see
+[ai-gates.md](ai-gates.md#ci-backstop)).
 
 ---
 
@@ -31,9 +35,9 @@ Local write hardness **differs by host**. CI required status is the shared hard
 
 | Host | Local write | MCP | Merge |
 |------|-------------|-----|-------|
-| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status |
-| Codex · OpenCode | Best-effort / advisory | Advisory | Required status |
-| Cursor | Advisory only | Advisory | Required status |
+| Claude · Grok · Antigravity | Hard PreToolUse when installed + trusted | Advisory | Required status context |
+| Codex · OpenCode | Best-effort / advisory | Advisory | Required status context |
+| Cursor | Advisory only | Advisory | Required status context |
 
 Full matrix and install commands: [ai-gates.md](ai-gates.md) · canonical table in [README](../README.md#host-enforcement-support).
 
@@ -46,7 +50,13 @@ npx arkgate-check --install-agent-gates --tools opencode
 npx arkgate-check --install-agent-gates --skills-only --force
 ```
 
-Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed files alone do not imply `hard:true` without runtime evidence where the product requires it.
+Doctor reports what is actually installed and observed (`writePath` / enforcement state). Installed
+files alone do not imply `hard:true` without runtime evidence where the product requires it.
+
+**Evidence split (Phase EH):** soft-write hosts keep `soft-write-host` in evidence without forcing
+global **Not finished** when the contract is ready. With `ARK_DOCTOR_GITHUB=1`, successful CI runs
+can show `runtimeObserved: true` even when branch-protection policy is plan-unavailable
+(`unavailable-plan` on GitHub Free private); `hard: false` until the status is required.
 
 ---
 

package/docs/package-surface.md

@@ -37,6 +37,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **`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)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
+| **Product honesty readiness split (4.1.1 EH)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (T01, 3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
 | **Atomic change preflight (T02, 3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (T03, 3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
@@ -189,7 +190,8 @@ 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)
-(current published: [4.0.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.1.md);
-next prepared: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md);
-previous: [4.0.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.0.0.md)).
+(current published: [4.1.0.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.0.md);
+prepared next: [4.1.1.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.1.1.md);
+previous: [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

@@ -73,7 +73,9 @@ Examples:
 | **compact router** | Default onboarding agent instructions (not the full skill pack) |
 | **hard write** | Non-bypassable PreToolUse block for listed ops (Claude/Grok when installed + trusted) |
 | **advisory write** | MCP/rules coach only (Cursor/Codex at write time) — not a hard block |
-| **required CI** | Merge hard boundary when the repository makes `arkgate-check` a required status |
+| **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** |
 
 ## Do (product copy)
 
@@ -82,11 +84,13 @@ Examples:
 | Name the status light + plain fact + term + next action | “Enforce · design-weak. Checked edges are honest; design smells remain. Next: one Shape door — explore → dual-plan B → autopilot with OK.” |
 | Rank one primary door under residual | Doctor **Primary next action** #1; **Also** only for secondary |
 | Label expert skills as escapes | “Install skill pack only when doctor or a STOP handoff names a skill.” |
-| State host write honesty | “Cursor/Codex: advisory write. Required CI is the hard merge boundary.” |
+| State host write honesty | “Cursor/Codex: advisory write. Required GitHub status context is the hard merge boundary.” |
+| Soft-write ≠ unfinished project | “Architecture contract ready; Codex local writes are advisory.” Keep `soft-write-host` in evidence; reserve **Not finished** for contract/project debt. |
 | Keep Suggest on start → doctor | New-here primary is finish `start`, not a competing recommend/architect curriculum |
 | Qualify edge-clean under design-weak | “None on checked edges … design residual remains. Not healthy finished.” |
 | Prefer fail-closed over fake hard | Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green |
-| Honesty clear ≠ architecture healthy | `productHonesty.finished` means residual 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`. |
+| 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.” |
 
 ## Avoid
 
@@ -100,6 +104,8 @@ Examples:
 | Skill-shopping lists as the default curriculum | Progressive disclosure: one door first |
 | “Healthy / done” while design-weak | False done |
 | “Honesty clear” as “architecture finished” | Honesty clear only means residual honesty sensors are quiet; graph/mode debt is separate |
+| “Not finished” solely because host is Codex/Cursor | Soft-write is environment residual; do not paint a green whole-tree project as unfinished architecture |
+| Conflating CLI name with required status | `ark-check` is the command; the hard boundary is the GitHub required **status context** |
 | “ArkRules prove business correctness” | They enforce *declared* structure/coverage evidence, not arbitrary logic or full semantic proof |
 | “Structure enforced = Domain extraction done” | Structure sensors are **heuristics**; extraction is judgment (`/ark-fix` / pilot) |
 | “Covered invariant = E2E business tests” | Coverage = symbol/test evidence for a named policy, not a runtime test runner |

package/docs/use.md

@@ -33,9 +33,11 @@ Full skill pack is **optional** (expert depth). Day-to-day: compact router + doc
 | When | What happens |
 |------|----------------|
 | While the AI writes | Host write gate or advisory MCP (depends on host) |
-| Before merge | `arkgate-check` — make it a **required** CI status |
+| Before merge | Make the Ark job a **required GitHub status context** running `arkgate-check --strict-merge` (alias `ark-check`) |
 | Anytime | Doctor: Suggest / Adapt / Enforce (+ design-weak if residual) |
 
+**Codex / Cursor / OpenCode:** local write stays advisory forever — that is not unfinished architecture. Doctor may say **contract ready** while still reminding you that local writes are advisory; **Not finished** is reserved for real project/contract debt.
+
 ArkGate is **not** a web framework, ORM, or app runtime. It is architecture enforcement + co-pilot for AI TypeScript.
 
 ### Two planes (you choose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop; optional ArkRules)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

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