arkgate 4.4.0 → 4.5.5

package/templates/skills/ark-explore.md

@@ -34,6 +34,26 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Map residual lenses → dual-plan B seeds.** Plain Align / Stabilize / Shape from compass + design-weak — not a scorecard.
 
+## Deep modules (process)
+
+- Prefer **deep modules**: small **interface**, complexity hidden behind it (not a depth score).
+- When proposing a port/adapter or Shape pilot, **name the seam** (callers stay stable; behavior swaps behind it). One adapter → seam still hypothetical; two real adapters → seam justified.
+- Apply the **deletion test** before extracting “just for tests”: if deleting the module makes complexity *vanish*, it was pass-through; if complexity *reappears* across callers, it earned its keep.
+- Prefer verification **at the public interface** of the seam (locality/leverage), not private pass-through layers.
+- When doctor surfaces **hot paths** or **deepening candidates**, treat them as advisory residual only — never as a gate fail; bias dual-plan B pilots toward recent churn when listed.
+
+## Domain glossary (process)
+
+If the consumer tree has a **domain glossary**, prefer its terms for layer/slice folders, pilot names, and next-action prose:
+
+| Common root names (detect, do not require) |
+|--------------------------------------------|
+| `CONTEXT.md`, `docs/glossary.md`, `docs/domain.md`, `docs/ubiquitous-language.md`, `docs/CONTEXT.md` |
+
+- Call out **glossary vs code** conflicts when names disagree with lived folders.
+- **Missing glossary is normal** — do not warn-spam or invent a glossary file.
+- Glossary content never enforces; the gate remains `ark.config.json` + scan.
+
 ## When / not when
 
 | Use `/ark-explore` when… | Do **not** use it when… |
@@ -390,6 +410,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-fix.md

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Name residual lenses** on each cluster (SoC, DIP, coupling, …). Still no weaken-gate to clear a lens.
 
+## Deep modules (process)
+
+- Prefer fixes that leave a **deep module** at a named **seam** (port in the owning layer; adapter outside).
+- Apply the **deletion test** before extracting a layer “just so tests can mock it.”
+- After a port/inject fix, **test at the public interface** of the seam (match remediation `nextAction` language), not only private internals.
+
 ## When / not when
 
 | Use `/ark-fix` when… | Do **not** use it when… |
@@ -198,6 +204,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-loop.md

@@ -31,6 +31,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Lens language on each cluster** while looping edges; residual shape lenses hand off to explore/autopilot.
 
+## Deep modules (process)
+
+- Judgment remediations that introduce ports: **name the seam**, prefer deep modules, **test at the public interface**.
+- Do not invent pass-through files that fail the **deletion test** just to clear a plan step.
+- Empty plan A is edge residual only — Shape residual still needs explore/autopilot; green edges ≠ feature done.
+
 ## When / not when
 
 | Use `/ark-loop` when… | Do **not** use it when… |
@@ -193,6 +199,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-place.md

@@ -24,6 +24,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **Where so the AI doesn’t mess up next time** — golden pattern + layer home before the write.
 
+## Deep modules (process)
+
+- Place so new code stays **deep**: one small public surface per concern; hide implementation details.
+- If the artifact is a port or adapter, **name the seam** and put the interface where callers should depend (usually Domain/Application), implementation on the outer side.
+- Do not scaffold empty pass-through modules that fail the **deletion test** (complexity would vanish if deleted).
+
 ## When / not when
 
 | Use `/ark-place` when… | Do **not** use it when… |
@@ -175,6 +181,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-think.md

@@ -28,6 +28,12 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **2–3 options labeled by lens impact** (what residual improves / what stays out-of-scope).
 
+## Deep modules (process)
+
+- Prefer **deep modules** (small interface, hidden complexity). Never invent a depth score.
+- Label the **seam** on each option that introduces a port/adapter; apply the **deletion test** before pass-through extracts “for testability.”
+- Recommend tests **at the public interface** of the chosen seam.
+
 ## When / not when
 
 | Use `/ark-think` when… | Do **not** use it when… |
@@ -146,6 +152,7 @@ End with **exactly** these headings (markdown `###`):
 - **Result:** one-line outcome
 - **Planes:** one-line split of residual **[Layer]** vs **[ArkRules]** (or `n/a` if unused)
 - **Compass:** top residual lenses | `n/a`
+- **Done axes:** architecture residual (status/doctor/compass) | feature/ticket residual (outside package). Enforce green ≠ feature done
 - **Handoff:** `/ark-…` / CLI / `none`
 - **Incomplete?** `no` | `yes — <what is missing>`
 

package/templates/skills/ark-upgrade.md

@@ -32,6 +32,20 @@ patterns are **out-of-scope** lenses — say so; do not invent Ark enforcement f
 
 **After upgrade:** refresh projection; re-doctor; compass residual still drives process, not scores.
 
+## Suggested improvements (what to try next)
+
+After `ark upgrade` (preview or apply), read JSON **`whatsNew`** or the human **Suggested improvements**
+block. It lists concrete try/inspect actions for this package line (advisory only — not a score):
+
+1. **Deep-module coach** — `ark-check --doctor` → `doctor.deepModuleCoach` (hot paths + deepening)
+2. **Improvement compass** — residual lenses on doctor/HTML (not a score)
+3. **Session recipe** — `ark status --json` honesty modes; doctor when mode is not full
+4. **Two-axis done** — architecture residual vs feature/ticket residual (Enforce green ≠ feature done)
+5. **Self-service honesty** — upgrade `selfService` write-path labels + customized preserve
+
+Never invent gate verdicts from these suggestions. Missing residual is honest empty, not green.
+
+
 ## Dual engine (mandatory)
 
 Use the semantic sensor (`ark-check --doctor --json` plus the strict contract