arkgate 4.2.1 → 4.4.0

package/templates/agent-skills/ark-think/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: ark-think
+description: Host-side architectural reasoning — 2–3 enforceable options on layer and/or ArkRules planes for ONE decision. Not full recon (use /ark-explore). No gate bypass. No package LLM call.
+---
+
+# /ark-think — Architectural reasoning (host LLM only)
+
+You are the user's architecture thinking partner **inside** the project's Ark contract.
+This skill does **not** call any LLM API from the arkgate package. **You** (the host agent)
+reason; the write-gate and CI remain deterministic.
+
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).
+
+## When / not when
+
+| Use `/ark-think` when… | Do **not** use it when… |
+|------------------------|-------------------------|
+| One decision: new layer vs slice, port vs shared, peerIsolation choice | Full map / ranked residual / dual-plan seed → `/ark-explore` |
+| 2–3 options already bounded by a known surface | Apply remediation → `/ark-fix` / `/ark-loop` / `/ark-autopilot` |
+| Trade-offs before writing a **new** feature | Brownfield contract wrong / false-green → `/ark-adopt` then `/ark-contract` |
+| Explain *why* a rule exists in *this* tree | HTML tour → `/ark-explain`; fitness numbers → `/ark-coverage` |
+
+If you lack a product map and the tree is messy: run a **compressed** explore pass first
+(≥8 files) **or** **STOP** and invoke `/ark-explore` — do not invent options from diagrams alone.
+
+## Dual engine (mandatory)
+
+| Engine | Role |
+|--------|------|
+| **Deterministic** | What the contract and doctor *prove* today (layers, rules, governed%, gaps) |
+| **Exploratory** | What *this* decision surface wants — options grounded in files you open |
+
+Never reason only from abstract hexagons. Open real modules before recommending a shape.
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Think + ArkRules
+- For ONE decision, consider options on **both** planes when relevant: e.g. new layer wall **vs** structure sensor **vs** invariant catalog entry.
+- Every option must state enforceability: which plane holds it after the change.
+
+## Subagent fan-out (optional, host-dependent)
+
+When the user asks to go faster **or** the work naturally splits (multiple packages,
+feature dirs, plan clusters), you **may** dispatch **subagents**:
+
+| Host capability | Behavior |
+|-----------------|----------|
+| **Parallel subagents supported** (e.g. multi-agent / `spawn_subagent` / concurrent Agent tools) | Launch **2–N** agents in **one wave** with **disjoint path scopes**. Prefer **read-only** explore agents for mapping; at most **one writer** unless the host gives isolated worktrees. Parent merges findings, then runs `ark-check` once. |
+| **Not supported** (single agent only) | **Fall back to sequential** — same checklist, one cluster/step at a time. Never claim parallel work you did not run. |
+
+**Rules:**
+1. Give each subagent a **tight brief**: paths in scope, sensor commands allowed, deliverable shape (paths opened + findings JSON or bullets).
+2. **No shared mutable files** across parallel writers.
+3. STOP handoffs and dual-engine rules still apply in every agent.
+4. Parent owns the **### Completion** block (union of **Opened**, single **Handoff**).
+5. Do **not** use subagents to weaken the gate or invent `mechanical-safe` kinds.
+
+## Steps
+
+1. **Load the contract** — `ark.config.json`; when MCP is available, call `ark_identity` with
+   the exact project root followed by `ark_manifest` with the same root plus returned project
+   id. The `ark://manifest` resource is compatibility-only and always
+   unverified/non-authoritative. Use `ark-check --coverage --json` / `--doctor` for honesty
+   about governed% and false-green.
+2. **Touch the decision surface** — README skim + **≥5 source files** on the feature/package/boundary
+   under discussion. Name paths in the answer.
+3. **Name the active shape** — which preset/archetype fits (hexagonal, vertical-slice,
+   ddd-bounded-contexts, feature-sliced, monorepo, …). If none, run `--recommend --json`
+   **and** say whether detection matches the tree you opened.
+4. **Name concurrent patterns** on the decision surface (if ≥2): which is **golden** vs legacy.
+5. **Reason within bounds** — propose **2–3 options** that **stay enforceable** by the gate.
+   Prefer concrete paths and import rules over abstract diagrams.
+6. **Explore alternatives** — for each option: coupling, testability, **AI-agent safety**,
+   migration cost, **pilot + kill-switch** if the option adds a layer or wall.
+7. **Surface hard lines** — never suggest: weakening `ark.config.json` to pass, silent
+   judgment auto-apply, codemod engines, or skipping write-gate/CI.
+8. **Hand off** — placement `/ark-place`; config `/ark-contract`; bulk debt `/ark-loop` /
+   `/ark-autopilot`; map-only `/ark-explore`; violations `/ark-fix`.
+   When the user needs action not advice: **STOP — do not continue this skill as complete** — invoke the handoff skill.
+
+## Output format
+
+- **Context:** product + contract + what you opened (paths) + phase if known (Align/Stabilize/Shape)
+- **Options:** 2–3 alternatives with trade-offs (coupling, testability, agent safety, enforceability)
+- **Recommendation:** one option + why it is enforceable **today**
+- **Pilot / kill-switch:** if the choice changes shape or adds a layer
+- **Risks if we pick wrong:** one sentence user-visible impact
+- **Next command:** exact `ark-check` / skill to run next
+
+## Related
+
+- Greenfield shape: `/ark-architect`
+- Brownfield: `/ark-adopt`
+- Full recon / dual-plan seed: `/ark-explore`
+- Explain existing: `/ark-explain`
+
+## Completion contract (skill incomplete if missing)
+
+End with **exactly** these headings (markdown `###`):
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
+- **Result:** one-line outcome
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
+- **Handoff:** `/ark-…` / CLI / `none`
+- **Incomplete?** `no` | `yes — <what is missing>`
+
+If a **STOP** handoff applies and you continued as if done, set **Incomplete?** to `yes`.
+**Skill incomplete if missing** any of the bullets above.

package/templates/agent-skills/ark-upgrade/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: ark-upgrade
+description: Upgrade ArkGate through a content-identity preview, preserve customized files, and verify the active host and architecture contract.
+---
+
+# /ark-upgrade — managed ArkGate upgrade
+
+Upgrade the published `arkgate` package and its managed gates without treating a
+filename, package version, or similar-looking file as proof of ownership. The
+preview is the source of truth: inspect it before applying anything.
+
+For greenfield onboarding, start with `/ark-architect` (or
+`ark-check --recommend`); for a brownfield repository, use `/ark-adopt` before
+this upgrade flow.
+
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**After upgrade:** refresh projection; re-doctor; compass residual still drives process, not scores.
+
+## Dual engine (mandatory)
+
+Use the semantic sensor (`ark-check --doctor --json` plus the strict contract
+check) and direct inspection of every managed file the preview will change.
+Neither signal replaces the other.
+
+
+## MCP workspace binding (mandatory)
+
+Before any `ark_*` MCP tool, call `ark_identity` with `project.expectedRoot` set to the exact
+workspace root. Continue only when `binding.status === "matched"` and `authoritative === true`;
+retain `projectIdentity.projectId`, then pass both `expectedRoot` and `expectedProjectId` under
+`project` on every later MCP call. If identity is missing, mismatched, unverified, or the root is
+uncertain, do not consume MCP analysis: use the workspace-local CLI and report that MCP
+restart/retargeting is required. `ark://manifest` never satisfies this preflight.
+
+## Dual plane — layers + ArkRules (mandatory, except /ark-runtime)
+
+ArkGate has **two opt-in planes**. The user chooses which to use; you **always label** findings so they never blur.
+
+| Plane | What it protects | Where it lives | Sensors / tools |
+|-------|------------------|----------------|-----------------|
+| **Layers** (inter-layer) | Who may import whom, capabilities, pure/forbiddenGlobals, peerIsolation | `ark.config.json` → `layers[]`, `rules[]` | graph check, baseline edges, doctor coverage % |
+| **ArkRules** (intra-layer) | Structure inside a layer + domain invariants as data | `arkRules` map + `arkrules/<ExactLayerName>.json` | structure sensors, invariant coverage, `--rules-inventory`, doctor `rulesUnderContract` |
+
+**Rules for every report / answer:**
+1. Prefix each finding or next step with **`[Layer]`** or **`[ArkRules]`** (or a two-column table with those headers).
+2. Never call an import-edge violation an “invariant” or an aggregate sensor a “layer deny.”
+3. Absence of `arkRules` is **valid** — do not force ArkRules unless the user wants them or residual inventory clearly wants a pilot.
+4. Editing `arkrules/*` or promoting modes is **`/ark-contract`**; fixing code under a structure sensor is **`/ark-fix`** / **`/ark-loop`** (judgment, never invent mechanical-safe).
+5. CLI helpers: `ark-check --rules-inventory --json`, doctor JSON `rulesUnderContract`, sensors emit `ARKRULE_*` / `INVARIANT_UNCOVERED` with `evidence.arkruleId`.
+
+
+### Upgrade + ArkRules
+- Refresh skills + note if templates gained ArkRules deepen; do not force consumers to adopt `arkRules`.
+- After upgrade: doctor `rulesUnderContract` if map exists; dual-truth note if `--no-install` left package pin old.
+
+## Safety contract
+
+- Always invoke the **project-local** CLI (`npx arkgate` /
+  `node node_modules/arkgate/bin/ark.mjs`). Bare PATH `ark` / `arkgate` is unsafe
+  when a global 2.x install shadows the project (mutative legacy upgrade).
+- `ark upgrade` (managed era) is read-only. It reports the selected profile and hosts, every
+  managed asset, its content state, and the exact next command.
+- The first `ark upgrade --apply` updates the dependency and lockfile, then runs
+  the newly installed CLI to produce another read-only preview. It does **not**
+  apply that preview's gate or skill changes.
+- The post-update/no-install preview's `nextCommand` includes
+  `--plan-digest <sha256:…>` and applies only that exact candidate. A changed file
+  or selection invalidates the digest instead of being overwritten.
+- Missing or conflicted assets previously recorded as managed require explicit
+  `--accept-conflicts`. Stop and obtain user consent before using it.
+- Customized files are preserved. Unrelated source files and similar filenames
+  are never adopted. The command never writes a Codex home or another global
+  directory implicitly.
+- Do not combine this flow with legacy `--force`, `--migrate-commands`, or
+  `--codex-home` repair commands. Diagnose any older adoption debt separately.
+
+## Read the states
+
+| State | Meaning | Action |
+|---|---|---|
+| `current` | Content identity matches the candidate. | Record/adopt safely; metadata-only stamps may refresh. |
+| `stale` | Recorded managed content still matches its old identity. | Safe candidate replacement. |
+| `missing` | Candidate is absent. | Create if new; require consent if a recorded asset was deleted. |
+| `customized` | User content diverged without a competing managed base. | Preserve it. |
+| `conflicted` | Both managed base and user content diverged. | Preserve and require explicit consent. |
+| `retired` | A recorded asset is no longer selected by the candidate. | Preserve its file and manifest identity; take no action. |
+
+## Procedure
+
+1. **Resolve the project CLI (mandatory before any upgrade command).** Prefer the
+   **project-local** binary — never bare `ark` / `arkgate` from PATH unless you
+   prove it is this project's install.
+
+   Resolution order:
+
+   1. `node node_modules/arkgate/bin/ark.mjs` from the repository root (both `arkgate`
+      and `ark` package bins map to this file).
+   2. Package-manager exec from the project: `npx arkgate`, `pnpm exec arkgate`,
+      `yarn arkgate`, etc.
+
+   **Do not** use bare `ark` / `arkgate` from PATH unless `which ark` (or the
+   resolved realpath) is under this project's `node_modules/arkgate`, or the
+   binary reports the **same** version as `node_modules/arkgate/package.json` and
+   supports managed upgrade.
+
+   **Capability probe (abort if missing):** run
+   `node node_modules/arkgate/bin/ark.mjs upgrade --help` (or the resolved local
+   equivalent) and require a **managed upgrade** surface — help text must mention
+   `--plan-digest` (and read-only `upgrade --json` preview). If the only available
+   CLI is old (global Homebrew / npm global 2.x, or any binary whose help lacks
+   `--plan-digest`), **stop**: skill incomplete; do **not** preview or apply.
+   Global 2.x `ark upgrade` is mutative and can rewrite managed skills, forcing a
+   later `--accept-conflicts` recovery.
+
+   **Recovery (preferred → optional):**
+
+   - Preferred: package-manager runner from project / `--root`
+     (`npx arkgate upgrade …` / `pnpm exec arkgate upgrade …` / `yarn arkgate upgrade …`).
+     This works when arkgate is **hoisted** and a nested package has no shallow
+     `node_modules/arkgate`.
+   - Secondary: `node node_modules/arkgate/bin/ark.mjs upgrade …` from the
+     **workspace install root** (not a nested package lacking a local install).
+   - Optional: refresh a global install with `npm i -g arkgate@latest` only if the
+     user wants a global binary; still prefer project-local for this procedure.
+
+   Record the resolved CLI path/version, read
+   `node_modules/arkgate/package.json`, query `npm view arkgate version`, identify
+   the repository package manager, and open the intervening entries in the
+   shipped `CHANGELOG.md` (fall back to registry or release notes and name that
+   source). Do not infer “latest” from `node_modules` alone.
+
+2. **Preview managed content.** Using the **project-local** CLI from step 1
+   (never a bare PATH `ark` that failed the probe), run:
+
+   ```bash
+   npx arkgate upgrade --json
+   # or: node node_modules/arkgate/bin/ark.mjs upgrade --json
+   ```
+
+   Pass `--root <path>` and `--tools <active-host>` when selection would otherwise
+   be ambiguous. Open the reported files that matter to this repository. Confirm
+   that customized files remain non-applying and that any deletion/conflict is
+   blocked.
+
+3. **Update and re-preview.** If the registry is newer, run (project-local CLI):
+
+   ```bash
+   npx arkgate upgrade --apply
+   ```
+
+   This updates through the detected package manager and hands control to the new
+   package for a fresh preview. Review that new preview; do not assume the old
+   candidate and new candidate are identical. If already on the latest package,
+   retain the current read-only preview.
+
+   For pnpm repositories with `minimumReleaseAge`, use the repository's existing
+   trusted first-party exception mechanism when the new release is still cooling
+   off, and prove `pnpm install --frozen-lockfile` succeeds.
+
+4. **Apply only the reviewed candidate.** When there are no blocked assets, run
+   the preview's **exact** `nextCommand` as emitted (JSON field / human “Apply the
+   exact preview with: …”). That command is already **project-local**
+   (`npx arkgate` / `pnpm exec arkgate` / `yarn arkgate` — never bare PATH `ark`).
+   Do **not** rewrite it to bare `ark upgrade`; pasting through a global 2.x PATH
+   reintroduces the mutative footgun. Shape:
+
+   ```bash
+   npx arkgate upgrade --apply --no-install --plan-digest <preview-digest>
+   ```
+
+   If recorded deletion/conflict recovery is desired, ask first and then add
+   `--accept-conflicts`. Never add it merely to make the run green. Run a second
+   preview and require `summary.changed: 0`.
+
+5. **Verify enforcement and architecture.** Run
+   `npx arkgate-check --doctor --json` (or the project-local `ark-check`) and
+   the same fail-closed architecture command used by managed apply (normally
+   `npx arkgate-check --root . --config ark.config.json --strict-merge --json`).
+   Require `completeness: "complete"` and `ok: true`. Treat provider-unavailable CI
+   required-check evidence as `unverified`, never as proof that merges are
+   blocked. If new violations appear, hand off to `/ark-fix` for a small set or
+   `/ark-loop` / `/ark-autopilot` for residual debt; do not regenerate a baseline
+   without explicit approval.
+
+## Active host vs deferred hosts
+
+**Active host:** its repo-local gate, skills, MCP/advisory surface, doctor evidence,
+and strict check must be coherent before completion.
+
+**Deferred hosts:** inactive hosts may remain untouched and must be named with a
+future repair command when relevant. Deferred hosts never make Incomplete? `yes`
+once the active host and shared repository surfaces are verified. A temporary
+upgrade path or an actively selected host is not deferred.
+
+The managed manifest retains the selected host set, so a later preview does not
+silently switch to a different host. Home-level Codex setup is separate and is
+never an implicit side effect of this skill.
+
+## Subagent fan-out (optional, host-dependent)
+
+Parallelize independent preview, changelog, and enforcement checks when the
+host supports isolated subagents; otherwise fall back to sequential execution.
+
+## Completion contract (skill incomplete if missing)
+
+Skill incomplete if missing any required verification or any field below.
+
+End with exactly this structure:
+
+### Completion
+- **Sensor:** commands/tools run
+- **Opened:** real project and changelog paths read
+- **Active host:** host and verified status
+- **Deferred hosts:** `none` or host plus future action
+- **Result:** old → new version and managed-upgrade outcome
+- **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
+- **Handoff:** `/ark-…`, CLI action, or `none`
+- **Incomplete?** `no` or `yes — <missing work>`
+
+If a required verification did not run or a conflict remains blocked, report the
+task incomplete. Deferred hosts (including Codex when inactive) never make Incomplete? yes.

package/templates/skills/ark-adopt.md

@@ -12,6 +12,25 @@ with a burn-down. A green check over a wrong contract is a **false green**.
 spaghetti “ENFORCE · design-weak”. Always end with dual-plan **B** seeds (or handoff explore)
 when design smells remain after the contract is honest.
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Spaghetti → honest contract.** SoC/DIP false-green STOP paths in plain language; residual lenses stay Incomplete until mapped.
+
 ## When / not when
 
 | Use `/ark-adopt` when… | Do **not** use it when… |
@@ -164,6 +183,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-architect.md

@@ -5,6 +5,25 @@ description: Choose the application shape, adopt phase-1 layers, scaffold direct
 
 # /ark-architect — Choose your application shape and adopt Ark
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Greenfield that is AI-easy day one:** golden norm + thin layers so the next agent turn stays ordered.
+
 ## When / not when
 
 | Use `/ark-architect` when… | Do **not** use it when… |
@@ -144,7 +163,7 @@ the same files or weaken the gate.
 - Default to smallest viable phase 1; unlock phase 2 only when the user describes need.
 - All user-facing copy is **English**.
 
-## Merge cards (X04 reshape — judgment only)
+## Merge cards (physical cohesion reshape — judgment only)
 
 When `doctor.physicalCohesion` reports a mirrored concept and the user asks whether files
 should be **merged**, treat it as domain modeling, never deduplication (field fact: zero
@@ -168,6 +187,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-autopilot.md

@@ -16,6 +16,25 @@ fixes you design from reading source (still validate with ark-check, never weake
 **Not a plan grinder.** Empty `--plan` does **not** mean “architecture is healthy” without
 the explore pass and dual-plan section B (pattern / Shape bets).
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Guided vibe path:** phase 0 = doctor + compass residual. Shape only with user OK. Never script “done” while residual lenses remain.
+
 ## When / not when
 
 | Use `/ark-autopilot` when… | Do **not** use it when… |
@@ -23,10 +42,10 @@ the explore pass and dual-plan section B (pattern / Shape bets).
 | “Make architecture sound” end-to-end | Map only, no apply → `/ark-explore` |
 | Brownfield or greenfield with apply | Only fitness numbers → `/ark-coverage` |
 | User wants A + B planned and A executed | Single edge fix → `/ark-fix`; plan A only → `/ark-loop` |
-| **Apply half of Q01 post-green path** (after explore map / when user wants full apply) | Skipping explore when doctor primary is Shape map-first |
+| **Apply half of post-green Shape path** (after explore map / when user wants full apply) | Skipping explore when doctor primary is Shape map-first |
 | Spaghetti under ENFORCE: Shape work with user ok on B | Contract false-green first → `/ark-adopt` / `/ark-contract` STOP paths |
 
-**Q01:** doctor’s single door is `/ark-explore` shape-focus → dual-plan B, **then** this skill only
+**Post-green door:** doctor’s single door is `/ark-explore` shape-focus → dual-plan B, **then** this skill only
 to apply B with OK. Prefer that order when `postGreenPath` / design-weak is the primary residual.
 
 ## Related onboarding
@@ -54,10 +73,10 @@ decision-grade explore pass **and** without opening violating files.
 4. **Open every file** in plan A `steps[]` (and `target` if present) before classifying a fix.
 5. **“Así te lo re-soluciono”** for each A cluster and each B pattern bet.
 6. Apply A → re-run ark-check → rollback on regression. **Never auto-apply B** as mechanical-safe.
-7. **Q04 pilot loop for B:** when design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
+7. **One-pilot loop for B:** when design-weak, take **`pilotLoop.nextPilot`** (one extraction card)
    → apply **only** that pilot with user OK → **re-doctor**. Never multi-pilot batch B; residual
    outside the pilot may remain and must not be called “healthy finished.”
-8. **Y01 reshape verdicts:** read `doctor.physicalCohesion.reshapeDecisions` before acting on
+8. **Reshape decision memory:** read `doctor.physicalCohesion.reshapeDecisions` before acting on
    mirror facts. Outcome first: a current rejected/deferred verdict means “intentional/deferred
    layout — no pilot”; never reconstruct that dead card from `findings`. When the user accepts,
    defers, or rejects a live card, persist its exact `decisionTarget` with a non-empty reason and
@@ -199,7 +218,7 @@ Status lights from doctor — not settings you choose. Rank residual honestly:
     populated cores are `optional: true`, run `ark-check --ratchet-cores` then `--doctor`.
     Never ratchet while active violations remain or false-green gap is open.
 
-## Mechanical-edit hygiene (Y04 — outcome gate)
+## Mechanical-edit hygiene (outcome gate)
 
 - Header injection must **merge into the existing doc comment**; the kept result has one `/**`, not stacked headers.
 - Route completion or movement must **preserve the original typed `defineRoute<…>(opts, handler)` call**; reconstruct that call instead of extracting untyped opts/handler constants that drop generics or contextual typing.
@@ -235,6 +254,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-contract.md

@@ -5,6 +5,25 @@ description: Safely edit ark.config.json layers/rules and arkrules/* (structure
 
 # /ark-contract — Change the architecture contract (safely)
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Contract edits are last resort.** Policy-delta honesty; do not weaken rules to clear compass residual.
+
 ## When / not when
 
 | Use `/ark-contract` when… | Do **not** use it when… |
@@ -129,6 +148,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-coverage.md

@@ -11,6 +11,25 @@ what adoption gaps remain. Work autonomously. End with a ranked fitness report.
 **This is not `/ark-explore`.** You do **not** produce a multi-pattern dual-plan or spaghetti
 Shape ladder by default. If the tree is design-weak under ENFORCE, **handoff** to explore.
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Fitness numbers + handoff** when residual lenses are non-empty — never call coverage “done architecture.”
+
 ## When / not when
 
 | Use `/ark-coverage` when… | Do **not** use it when… |
@@ -160,6 +179,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-explain.md

@@ -7,6 +7,25 @@ description: Explain this project's architecture in plain language and generate
 
 The user wants to understand the architecture, a specific rule, or why the gate blocked them.
 
+## Improvement compass (process preflight)
+
+When doctor is available, read `doctor.improvementCompass` (or the human **Improvement compass** section).
+Name 1–3 **residual** lenses in plain language before skill-shopping. Always `notAScore` — never invent
+0–10 scores or Excellent/Good ranks.
+
+**What the user should feel next:** fewer blocked AI writes, clearer folders, safer domain — then jargon.
+
+**Anti false-done:** empty plan A + residual lenses / design-weak → **Incomplete? yes**. Green edges alone
+are not “architecture finished.”
+
+**AI-easy architecture:** ports over concrete I/O in domain; one concern per module; golden pattern for
+new files; place before write (`/ark-place` / prepare-write).
+
+**Out of scope (honest):** scalability/performance, full app-security tooling (SAST), and full resilience
+patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement for them.
+
+**Tour by lenses** (teach, not score). Prefer showcase HTML + doctor compass section when explaining residual.
+
 ## When / not when
 
 | Use `/ark-explain` when… | Do **not** use it when… |
@@ -200,6 +219,7 @@ End with **exactly** these headings (markdown `###`):
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome (include `ark-report.html` path; note if browser open was attempted)
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
+- **Compass:** top residual lenses | `n/a`
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`