arkgate 4.2.1 → 4.4.0

package/templates/skills/ark-explore.md

@@ -15,17 +15,36 @@ install hooks, examples/starters, and coupling evidence. Output is **decision-gr
 ranked residual that changes the next command — **not** a celebration of ENFORCE and
 **not** a paraphrase of README/ROADMAP.
 
+## 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.
+
+**Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.
+
 ## When / not when
 
 | Use `/ark-explore` when… | Do **not** use it when… |
 |--------------------------|-------------------------|
 | Map / “what next?” / residual after ENFORCE | User wants edits applied → `/ark-autopilot` or `/ark-fix` |
-| **Primary post-green door (Q01):** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
+| **Primary post-green door:** messy / spaghetti / design-weak / “clarify for AI” | Skill-shopping coverage or think for the same residual |
 | Spaghetti brownfield: patterns concurrent, design-weak under green check | Only “governed% + gates installed?” numbers → `/ark-coverage` |
 | Dual-plan **seed** (A remediation + B pattern bets) without applying | One design trade-off between 2–3 options already mapped → `/ark-think` |
 | Path-correct vs design-correct honesty | Plain-language tour / HTML report → `/ark-explain` |
 
-**Q01 single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
+**Post-green single path:** when doctor `postGreenPath` / ENFORCE · design-weak is active, **this skill
 (shape-focus / dual-plan seed) is the map half of the one door** — then `/ark-autopilot` only
 to apply B with user OK. Do not send the user to coverage or think as equal first choices.
 
@@ -278,7 +297,7 @@ ENFORCE without Shape progress is **`ENFORCE · design-weak`** — say that out
 **Extraction card** (for each I/O / god-module B bet — judgment, never mechanical-safe).
 Canonical productized template also in `docs/brownfield-adoption.md` §6.
 
-**Q04 pilot loop:** when doctor/plan JSON is available, use **`pilotLoop.nextPilot`** as the
+**One-pilot loop:** when doctor/plan JSON is available, use **`pilotLoop.nextPilot`** as the
 **single** next extraction card (one pilot at a time → re-doctor). Do not open five B bets
 in parallel. When `pilotLoop.queuedBets > 0`, those bets stay **queued**, not concurrent.
 `multiPilotBatchForbidden` / `autoApplyForbidden` (alias `autoApplyPlanBForbidden`) are hard
@@ -370,6 +389,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-fix.md

@@ -9,6 +9,25 @@ You fix violations Ark reports. Prefer structural fixes over silencing the gate.
 **Read the surrounding product code** (callers, package role, feature ownership) — not only
 the two files on the violation edge.
 
+## 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.
+
+**Name residual lenses** on each cluster (SoC, DIP, coupling, …). Still no weaken-gate to clear a lens.
+
 ## When / not when
 
 | Use `/ark-fix` when… | Do **not** use it when… |
@@ -147,14 +166,14 @@ If the “fix” is really a missing business intent or Domain home for a rule:
 - Prefer mechanical-safe kinds when the plan tags them; otherwise design judgment carefully.
 - Code only — no DB migrations unless user asked.
 
-## 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.
 - A convention-only `*-data.ts` stub is not a fix: move the real code or **leave the placeholder file uncreated**; never write `import "server-only"; export {}` as an empty naming token.
 - Keep the edit only when the **previously clean file stays typecheck-clean**. Otherwise roll it back and treat the change as judgment.
 
-## Reshape findings (X04 — never mechanical)
+## Reshape findings (physical cohesion — never mechanical)
 
 If `doctor.physicalCohesion` fires while you fix: do **not** fold reshape moves into your fix
 batch. Physical moves run only through `/ark-loop`'s one-pilot loop; merge decisions only as
@@ -178,6 +197,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-loop.md

@@ -12,6 +12,25 @@ Deterministic kinds stay **tight**. Your job is still **exploratory on the files
 importers/targets, see if the plan step is a symptom of wrong shape / false Domain / I/O
 under Application — escalate to `/ark-contract` or `/ark-explore` when the wall is structural.
 
+## 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.
+
+**Lens language on each cluster** while looping edges; residual shape lenses hand off to explore/autopilot.
+
 ## When / not when
 
 | Use `/ark-loop` when… | Do **not** use it when… |
@@ -113,14 +132,14 @@ feature dirs, plan clusters), you **may** dispatch **subagents**:
 
 Never auto: free value uses of imports, multi-import files, dynamic import/require, forbidden globals, cycles, port-proof inject, multi-file adapter scaffolding without proof.
 
-## 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.
 - A convention-only `*-data.ts` stub is not a fix: move the real code or **leave the placeholder file uncreated**; never write `import "server-only"; export {}` as an empty naming token.
 - Keep the edit only when the **previously clean file stays typecheck-clean**. Otherwise roll it back and treat the change as judgment.
 
-## Reshape pilots (X04 — physical cohesion, advisory)
+## Reshape pilots (physical cohesion — physical cohesion, advisory)
 
 When `ark-check --doctor --json` carries `doctor.physicalCohesion.reshapePilot.nextPilot`,
 you may run **that one pilot** — never more:
@@ -173,6 +192,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-place.md

@@ -5,6 +5,25 @@ description: "Where does new code go? Names the layer, directory, and naming for
 
 # /ark-place — Where does this code go?
 
+## 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.
+
+**Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
+
 ## When / not when
 
 | Use `/ark-place` when… | Do **not** use it when… |
@@ -155,6 +174,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-runtime.md

@@ -15,6 +15,12 @@ and NestJS adapters. The stable `arkgate` package is the architecture gate; it d
 the runtime implementation. This skill migrates hand-rolled versions of those to the kernel,
 one feature at a time.
 
+## Improvement compass note
+
+This skill is **experimental runtime** only. Do **not** treat runtime adoption as residual on the
+resilience lens unless the user explicitly opts into the experimental kernel. Prefer doctor compass
+for static architecture residual; hand static residual to `/ark-explore` / `/ark-fix`.
+
 ## Dual engine (mandatory)
 
 | Engine | Role |
@@ -113,6 +119,7 @@ End with **exactly** these headings (markdown `###`):
 - **Sensor:** commands/tools run
 - **Opened:** real paths read (or `n/a` only if pure install/upgrade with no source analysis)
 - **Result:** one-line outcome
+- **Compass:** `n/a` (runtime skill; static residual → explore/fix) | top residual if doctor was run
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-think.md

@@ -9,6 +9,25 @@ You are the user's architecture thinking partner **inside** the project's Ark co
 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… |
@@ -126,6 +145,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-upgrade.md

@@ -13,6 +13,25 @@ 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
@@ -211,6 +230,7 @@ End with exactly this structure:
 - **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>`