@aperant/framework 0.6.4 → 0.6.5

package/skills/apt-discuss/appendices/grill-discipline.md

@@ -0,0 +1,104 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/grill-with-docs
+Licensed under MIT. Modifications: ported as an apt:discuss posture loader,
+extended with the validated 100-token reframe sentence and the
+autonomy-aware degradation table from the Pocock adoption brainstorm
+(Architectural principles to lock §2).
+-->
+
+# Grill Discipline — apt:discuss posture loader
+
+This appendix loads into `apt:discuss`'s reasoning context whenever the
+skill is invoked in decision-lock posture (or as a sub-step inside
+`apt:improve` / `apt:triage`'s grill loop). It carries two load-bearing
+artifacts:
+
+1. The 100-token **reframe sentence** validated by the V2 grill-comparison
+   experiment (43/44 vs 38/44 blind-judge score against Pocock's verbatim
+   `grill-with-docs`).
+2. The **autonomy-aware degradation table** that prevents full-auto runs
+   from grinding to a halt grilling every gray area.
+
+## The reframe sentence (validated, 43/44 vs 38/44)
+
+> **Your job is not to emit a plan; your job is to resolve the design
+> tree until planning is mechanical.**
+
+This sentence is the *first thing* you load into your reasoning context
+when entering decision-lock posture. It does two things at once:
+
+- It refuses the "I'll just emit a plan and let the executor figure
+  out the gaps" anti-pattern. Plans with unresolved gray areas push the
+  cost into execution where rollbacks are 10× more expensive.
+- It frames the goal as *resolving a design tree*, not *answering a
+  questionnaire*. The interview-style "ask the user 47 clarifying
+  questions" is the failure mode this reframe blocks.
+
+The empirical V1 + V2 evidence is in
+`.aperant/experiments/grill-comparison-20260513/SUMMARY-FOR-AGENT-REVIEW.md`.
+
+## Autonomy-aware degradation table (load-bearing)
+
+The grill discipline runs at every autonomy level — the *interaction
+shape* degrades, not the discipline itself. This is the canonical
+source for this rule; new skills (apt:improve, apt:triage) reference
+THIS table rather than re-stating the policy.
+
+| Autonomy | Mode | Behavior |
+|---|---|---|
+| **1 (Supervised)** | Grill everything | Ask the user for every load-bearing decision. The user reviews each Q&A turn before the next one fires. |
+| **2 (Balanced / Semi)** | Batch-recommend | Auto-recommend per decision; collect all recommendations into a single batch the user reviews at the end. This is the existing `--review-auto` pattern. |
+| **3 (Full auto / YOLO)** | Auto-lock with escalation triggers | Auto-recommend and lock decisions silently. Escalate to the user only when one of THREE triggers fires (below). |
+
+## The three escalation triggers (Autonomy 3 only)
+
+At Autonomy 3, the agent locks recommendations silently — **EXCEPT** when:
+
+1. **Conflict with a prior locked decision.** The new recommendation
+   contradicts a decision already written to
+   `.aperant/context/notes/{task-id}.md` (or any other notes file under
+   `.aperant/context/notes/`). Re-litigating a locked decision needs
+   human sign-off.
+2. **Critical-path file touched.** The decision's downstream effect
+   modifies a file matching a glob in
+   `.aperant/config.json.risk_map.critical_paths` (e.g., auth, billing,
+   migration paths). Critical-path changes always escalate at every
+   autonomy level — this trigger is the autonomy-3 surface for the same
+   policy.
+3. **No defensible default exists.** Neither AGENTS.md nor an existing
+   codebase pattern provides a defensible answer. "Just pick one" is
+   not a defensible default; the agent must say "I see two viable
+   paths and no precedent — which do you want?"
+
+These three triggers cover the cases where a silent auto-lock would
+cause real harm. Everything else gets locked, logged, and surfaced in
+the final report only — not as a blocking prompt.
+
+## Practical consequence for new skills
+
+When `apt:improve`'s deepening loop, `apt:triage`'s priority resolution,
+or any other agent reaches a gray area:
+
+- It loads THIS appendix into reasoning context.
+- It reads the current autonomy from `.aperant/config.json` (or the
+  per-task autonomy from `apt-tools task get`).
+- It enters the matching row of the degradation table.
+- At Autonomy 3, it walks the three triggers before deciding to lock or
+  escalate.
+
+The "ask first vs lock first" decision is NOT a per-skill policy.
+Reasoning lives here; every grill-loop-bearing skill references it.
+
+## When NOT to load this appendix
+
+This appendix is for **decision-lock** posture (convergent discussion
+where the user has a concrete task with implicit gray areas). The
+**brainstorm** posture (divergent — user has a rough vision, exploring
+options) does NOT load this appendix; brainstorm has its own posture
+encoded in apt:discuss's `<objective>` block.
+
+`apt:zoom-out` (a sibling skill, also Pocock-adopted) does NOT load
+this appendix. Zoom-out is descriptive ("show me the broader picture"),
+not normative ("lock this decision"). Loading grill-discipline there
+would mis-fire the reframe sentence on a read-only operation.

package/skills/apt-discuss/appendices/zoom-out-helper.md

@@ -0,0 +1,79 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/zoom-out
+Licensed under MIT. Modifications: ported as a loaded-helper for apt:discuss
+brainstorm mode so the discipline activates without spawning the full
+apt:zoom-out skill (the latter is a router-invocable verb on its own).
+-->
+
+# Zoom-Out Helper — apt:discuss brainstorm mode loaded helper
+
+This appendix loads into `apt:discuss` brainstorm mode when the user's
+turn contains a zoom-out trigger phrase. The full
+`/apt:zoom-out` skill (router-invocable) is the right answer when the
+user invokes it explicitly; this helper is the right answer when the
+zoom-out request surfaces *inside* a brainstorm discussion.
+
+## When to load this appendix
+
+Inside an active `apt:discuss --brainstorm` session, if the user's turn
+contains any of these phrases (or their natural-language variants):
+
+- "give me a broader picture"
+- "I'm lost in this area"
+- "explain how this fits"
+- "what's the surrounding architecture"
+- "zoom out from {topic}"
+
+…load this appendix into reasoning context and follow the helper
+process below. The brainstorm posture stays active — you don't pivot
+out of `apt:discuss`; you augment its reasoning with the orientation
+discipline.
+
+## Process (helper mode, not full skill)
+
+1. **Identify the area.** Pull the noun phrase from the user's message
+   (e.g., "the sparring engine"). If ambiguous, ask a single targeted
+   clarifying question — do NOT enter a 20-question interview.
+
+2. **Load CONTEXT.md term-blocks if matching.** Same as the full
+   `apt:zoom-out` skill: if the area name matches a term or alias in
+   `CONTEXT.md`, pre-load that term-block's definition + flagged
+   ambiguities into the orientation.
+
+3. **Emit a compressed orientation INLINE in the discussion.** Format:
+
+   > **Purpose:** {one sentence}
+   > **Entry points:** `{file1}`, `{file2}`
+   > **State owners:** `{file3}` ({what state})
+   > **External boundaries:** `{file4}` ({what external})
+   > **Watch out for:** {one-line fragile area}
+
+   Three to six lines. The full one-page `apt:zoom-out` report is
+   overkill when the user is mid-discussion — they want enough context
+   to keep brainstorming, not a separate artifact.
+
+4. **Resume brainstorm posture.** After the orientation block, ask:
+   "Want me to keep zooming, lock a decision, or stay in brainstorm?"
+   so the user explicitly drives whether to deepen.
+
+## When NOT to load this appendix
+
+- In decision-lock posture (the user wants to *resolve* a decision, not
+  *orient* themselves) — load `grill-discipline.md` instead.
+- When the user explicitly types `/apt:zoom-out` — they invoked the
+  full skill; let that skill run unmodified.
+- In `apt:plan` — the planner's Phase-0 codebase investigation already
+  covers orientation. Loading this helper there would duplicate work.
+
+## Relationship to the full apt:zoom-out skill
+
+| | `apt:discuss + zoom-out-helper` | `/apt:zoom-out` (full skill) |
+|---|---|---|
+| Invocation | Detected mid-brainstorm | User-explicit verb |
+| Output | 3-6 line inline orientation | One-page report |
+| Side effects | None | None (read-only) |
+| Posture after | Brainstorm continues | Skill exits — no continuation |
+
+Same underlying discipline; different surface shapes for different
+work contexts.

package/skills/apt-execute/SKILL.md

@@ -15,11 +15,14 @@ execution_modes:
   - auto
   - step
 allowed-tools: "Read, Write, Edit, Bash, Grep, Glob"
-argument-hint: "apt:execute [--continue]"
+argument-hint: "apt:execute [--continue] [--subtask <id>] [--parallel] [--wave <N>] [--tdd] [--no-tdd]"
 gates: 
   - constitution-read
   - constitution-coverage
   - plan-exists
+config_keys:
+  - coding.tdd_default
+  - tdd.iron_law
 ---
 <objective>
 Read an implementation plan, iterate through subtasks, implement each one with atomic commits, and track progress. Supports both sequential (default) and wave-parallel execution modes.
@@ -79,6 +82,8 @@ When `/apt:execute` spawns ANY subagent (executor, wave workers, post-subtask re
 | `--subtask <id>` | Jump to a specific subtask (skip dependency check — user override) |
 | `--parallel` | Force wave-parallel mode even if `parallelization.enabled` is false in config |
 | `--wave <N>` | Execute only wave N (implies wave mode). Useful for pacing or quota management |
+| `--tdd` | Activate the vertical-tracer-bullet TDD discipline for this run (gates `<tdd_iron_law>`). Inverse of `--no-tdd`. Hard-exempt on QUICK tasks per Fast Path Guarantee (ID-05). |
+| `--no-tdd` | Deactivate TDD even if `coding.tdd_default: true` is set in config. |
 </arguments>
 
 <process>
@@ -134,6 +139,44 @@ Before loading context, determine execution mode:
 
 4. **If Sequential Mode:** proceed to Section 1 below (existing behavior, unchanged).
 
+### 0a.1. TDD Discipline Detection (Pocock adoption AC3)
+
+Compute whether the vertical-tracer-bullet TDD discipline is active for
+this run. The `<tdd_iron_law>` block in Section 3c is gated on this
+boolean. Three inputs combine; QUICK is hard-exempt regardless.
+
+1. **Read config:** `coding.tdd_default` from `.aperant/config.json`
+   (default `false` when absent).
+2. **Read flags:** `--tdd` (force-enable) and `--no-tdd` (force-disable)
+   on the command line.
+3. **Read task track** from `apt-tools task get . --id {task-id}` →
+   `task.track`. (If unset, fall back to `complexity` field on
+   `implementation_plan.json`: `simple` → QUICK, otherwise STANDARD.)
+
+Compute `tdd_active` as:
+
+```
+if track === "QUICK":
+  tdd_active = false   # Fast Path Guarantee — ID-05, hard-exempt
+elif --no-tdd flag:
+  tdd_active = false   # explicit user override
+elif --tdd flag:
+  tdd_active = true    # explicit user opt-in
+else:
+  tdd_active = coding.tdd_default || legacy config.tdd.iron_law === true
+```
+
+Carry `tdd_active` forward to Section 3c. When `tdd_active === false`,
+the iron-law block is skipped entirely and execute behaves identically
+to the pre-Pocock single-commit flow. When `tdd_active === true`, the
+red-green-refactor sequence is mandatory and audited by gate G9.
+
+**The QUICK exemption is a constraint, not a toggle.** A user who passes
+`--tdd` on a QUICK-routed task gets `tdd_active = false` and a one-line
+note in the run report: "TDD requested but skipped — QUICK Fast Path
+Guarantee (ID-05)". The Pocock appendix
+`appendices/tdd-mode.md` carries the rationale.
+
 ## 1. Load Context
 
 1. Read `AGENTS.md` if it exists — extract coding conventions, test requirements, style rules
@@ -236,11 +279,11 @@ Follow `subtask.description` to implement the changes. Rules:
 - Add/update tests if the subtask modifies testable behavior
 - Reference `prompts/coder.md` for coding methodology and environment awareness
 
-<tdd_iron_law enabled_when="config.tdd.iron_law === true">
+<tdd_iron_law enabled_when="tdd_active === true">
 
-**TDD Iron Law — conditional flow.** This block activates ONLY when `.aperant/config.json` has `tdd.iron_law: true` (read in Section 0a). When the flag is absent or `false`, skip this block entirely and use the single-commit flow above — behavior is unchanged.
+**TDD Iron Law — conditional flow.** This block activates ONLY when `tdd_active === true` (computed in Section 0a.1 from `coding.tdd_default` config, the `--tdd` / `--no-tdd` flags, and the task track). When `tdd_active === false` — including all QUICK-routed tasks regardless of flag or config (Fast Path Guarantee, ID-05) — skip this block entirely and use the single-commit flow above. The legacy `config.tdd.iron_law` config key continues to work and is rolled into `tdd_active` as a backward-compat alias.
 
-When `tdd.iron_law` is on, 3c/3d/3e collapses into a strict red-green-refactor sequence with **two commits per subtask**:
+When the iron law is on, 3c/3d/3e collapses into a strict red-green-refactor sequence with **two commits per subtask**:
 
 1. **Write the failing test first.** Identify or create the test file in `subtask.files` (look for `*.test.*` / `*.spec.*`). Add the test that describes the behavior you are about to implement. Do NOT touch implementation files yet.
 2. **Commit the red test.**
@@ -256,7 +299,7 @@ When `tdd.iron_law` is on, 3c/3d/3e collapses into a strict red-green-refactor s
    ```
    The audit gate `tdd-iron-law` (G9) fires during `/apt:verify` and asserts this commit order per subtask — a `feat(...)` commit that precedes the matching `test(...)` commit on the same file set is a blocking failure.
 
-**Rationalizations to reject** (do NOT take any of these shortcuts when `tdd.iron_law` is on):
+**Rationalizations to reject** (do NOT take any of these shortcuts when `tdd_active` is on):
 
 | Rationalization | Counter-rule |
 |---|---|

package/skills/apt-execute/appendices/tdd-mode.md

@@ -0,0 +1,107 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/tdd
+Licensed under MIT. Modifications: ported as an apt:execute appendix
+gated by `tdd_active` (config.coding.tdd_default || --tdd flag) and
+made QUICK-exempt per Aperant's Fast Path Guarantee (ID-05).
+-->
+
+# TDD Mode — Vertical Tracer-Bullet Discipline (apt:execute appendix)
+
+This appendix loads into `apt:execute`'s context when `tdd_active === true`
+(see SKILL.md §0a.1). It carries the vertical-tracer-bullet discipline
+Pocock's `tdd` skill captured. The audit gate G9 (`tdd-iron-law`) enforces
+the commit order; this prose explains the **why**.
+
+## Why vertical tracer bullets, not horizontal layers
+
+A "vertical slice" of TDD means: for each subtask, write one failing
+test that describes the **smallest end-to-end behavior change the user
+will care about**, then implement only enough to make it green.
+Horizontal TDD ("write all the data-layer tests first, then all the
+service tests, then all the UI tests") accumulates dead inventory and
+hides whether the slice actually delivers user value.
+
+Concretely:
+
+- A vertical-slice subtask titled "Solo dogfooder gets a PRD-shaped
+  spec on STANDARD" should commit one `test(plan): STANDARD emits PRD
+  shape` red test first — exercising the user-visible behavior — then
+  one `feat(plan): branch spec.md on track` green commit. Two commits.
+  Done.
+- A horizontal-slice subtask titled "edit apt-plan SKILL.md" gets you a
+  test that pins prose, not a test that pins user value. The G9 audit
+  will pass technically but the discipline failed.
+
+The vertical-slice subtask schema (`user_value` field, mandatory on
+STANDARD/DEEP per AC2) is **upstream** of this discipline — TDD bites
+hardest when the subtask was already framed as user value, not file
+scope.
+
+## The five rules of vertical tracer bullets
+
+These five rules are the load-bearing discipline; ignoring any one of
+them collapses TDD back into ceremony.
+
+1. **Write the failing test from the spec, not from the implementation
+   you're about to write.** If you write the test after you mentally
+   draft the implementation, the test only pins what you wrote —
+   not what the spec required. Read the relevant `acceptance_criteria`
+   id-ref, then write a test that fails because that AC isn't met yet.
+
+2. **Verify the test fails for the *right reason*.** A `ReferenceError`
+   because the function doesn't exist yet is not the same as the
+   assertion failing on a value mismatch. The G9 audit treats any
+   non-zero exit as RED, but the discipline demands you check the
+   failure mode is "behavior wrong", not "code shape wrong".
+
+3. **Implement the minimum to turn the test green.** No speculative
+   abstractions. No "while I'm here, I'll refactor X." The vertical
+   slice is one test + one minimum impl. Refactor lives in a follow-up
+   subtask with its own test.
+
+4. **Commit the test before the implementation.** This is the iron-law
+   commit order audit gate G9 enforces. A `feat(...)` commit that
+   precedes the matching `test(...)` commit on the same file set is a
+   blocking failure at `/apt:verify`.
+
+5. **Don't grow the test surface to cover edge cases the spec didn't
+   list.** Edge cases are subtasks of their own (with their own AC
+   id-refs). The vertical-slice rule applies recursively: each edge
+   case is a new tracer bullet through the whole stack, not a wider
+   suite of tests for the same slice.
+
+## Fast Path Guarantee — QUICK is hard-exempt
+
+`tdd_active` is forced `false` when the task's track is `"QUICK"`,
+regardless of flag or config. The rationale: QUICK is the one-shot
+fast path for trivial fixes (typo, copy change, single-line config
+update). Forcing TDD ceremony on those tasks violates the Fast Path
+Guarantee (ID-05) — the user opted into speed, not discipline. If a
+QUICK-routed task genuinely needs TDD, the right move is to re-route
+it as STANDARD via `/apt:plan` (which the router will do for any task
+with >1 file or >30 words of description).
+
+The skill body emits a one-line note in the run report when `--tdd`
+was passed on a QUICK task: "TDD requested but skipped — QUICK Fast
+Path Guarantee (ID-05)". This is intentional surface — the user sees
+that their flag was overridden by the constraint.
+
+## Backward-compat alias
+
+The legacy `config.tdd.iron_law` key continues to enable TDD for
+projects that adopted Aperant before the Pocock content-format
+upgrade. The new computation rolls it into `tdd_active`:
+
+```
+tdd_active = (
+               (--tdd flag) ||
+               (coding.tdd_default === true) ||
+               (config.tdd.iron_law === true)
+             )
+           && (track !== "QUICK")
+           && !(--no-tdd flag)
+```
+
+The two config keys (`coding.tdd_default` and `tdd.iron_law`) coexist
+without conflict; either set to `true` enables TDD by default.

package/skills/apt-improve/DEEPENING.md

@@ -0,0 +1,84 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/DEEPENING.md
+Licensed under MIT. Modifications: scoped to Aperant's apt:improve
+Phase-1 explore step and aligned with the deletion-test priority
+rubric in Phase 2.
+-->
+
+# DEEPENING — Domain-modeling depth lens
+
+This lens asks: **does this area model the domain at the right depth?**
+Are the abstractions earning their keep, or are they shallow wrappers
+hiding nothing?
+
+The discipline is to **find abstractions that have failed to deepen** —
+classes, modules, or types that started as a single-use convenience and
+never grew into something that captures domain meaning.
+
+## What "deep" means
+
+A deep abstraction:
+
+- Has a name that maps to a domain concept the user / business cares
+  about
+- Encapsulates more behavior than its interface suggests (you can call
+  one method and trust it to handle multiple internal concerns)
+- Reads naturally in client code without the reader needing to know
+  the abstraction's internals
+
+A shallow abstraction:
+
+- Has a name that mirrors implementation detail rather than domain
+  concept (e.g., `DataManager`, `Helper`, `Utils`)
+- Encapsulates almost no behavior — the interface is wider than the
+  internals (mostly pass-through)
+- Reads as noise in client code; the reader has to look inside the
+  abstraction to know what it does
+
+## Red flags this lens surfaces
+
+- **Anemic types** — types that are bags of fields with no methods, OR
+  classes with methods that just return fields.
+- **Pass-through wrappers** — `class FooService { constructor(api) { this.api = api } create(x) { return this.api.create(x) } }` adds nothing.
+- **Single-call-site abstractions** — extracted "for reuse" but only
+  called from one place. Inline them.
+- **God objects** — abstractions that grew too deep AND too wide,
+  collecting unrelated responsibilities. Different problem, same lens.
+
+## Apply in Phase 1
+
+When the explore step scans the named area:
+
+1. For each module / class / type, ask: "what domain concept does this
+   model?"
+2. If the answer is "none — it's an implementation detail dressed up as
+   a concept", flag it as a candidate.
+3. Note in the inventory: `{File}:{Symbol} — shallow ({reason})`. The
+   deletion test in Phase 2 will rank these.
+
+## What this lens does NOT cover
+
+- Boundary shape between modules → see `INTERFACE-DESIGN.md`
+- Naming consistency within / across modules → see `LANGUAGE.md`
+
+DEEPENING is about whether each abstraction is the right size. The
+sibling lenses are about whether the gaps between them are well-shaped
+and whether the language is consistent.
+
+## Deletion test (Phase 2 prep)
+
+For each candidate this lens flags, the Phase-2 deletion test asks:
+
+> If I deleted `{Symbol}` and inlined its body at every call site, what
+> domain meaning would be lost?
+
+If the answer is "nothing — it was just a name on a syntactic shape",
+the deletion test passes and the candidate is high-priority for refactor
+(remove the abstraction; the area gets shallower in surface area but
+deeper in meaning per remaining concept).
+
+If the answer is "we'd lose the {domain concept} as a first-class
+thing in the code", the deletion test fails — the abstraction was
+earning its keep, just maybe at the wrong depth. Re-scope to a sibling
+lens.

package/skills/apt-improve/INTERFACE-DESIGN.md

@@ -0,0 +1,97 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md
+Licensed under MIT. Modifications: scoped to Aperant's apt:improve
+Phase-1 explore step and aligned with apt:review Pass 4's boundary
+audit semantics (this lens is proactive; Pass 4 is reactive).
+-->
+
+# INTERFACE-DESIGN — Boundary-shape lens
+
+This lens asks: **are the boundaries between modules well-shaped?** Are
+there feature-envy patterns? Hidden coupling? Async leakage? Boundary
+violations the reactive `apt:review` Pass 4 audit would catch if a diff
+crossed them, but which currently exist statically and nobody is
+auditing?
+
+## Red flags this lens surfaces
+
+### Feature envy
+A method in module A spends most of its time reading fields from
+module B's types. The behavior wants to live in B but the import
+direction made it land in A. Symptom: lots of `b.x`, `b.y`, `b.z`
+accesses in A's methods.
+
+### Hidden coupling
+Module A imports module B by accident — not because B's exported
+surface is being used, but because B re-exports something A actually
+wanted from a third place. Symptom: `import { foo } from './b'` where
+`foo` is defined in C and B is just a passthrough.
+
+### Async leakage
+A function in A returns a Promise, but the work it kicks off settles
+asynchronously somewhere else (timer, event handler, background job).
+The caller can `await` the Promise and think they're done, but the
+real work is still in flight. Symptom: tests pass synchronously but
+real-world behavior is racy.
+
+### Wide-then-narrow interfaces
+Module A exports 30 functions, but only 3 are called externally. The
+other 27 are accidental surface. Symptom: `index.ts` exports `*`.
+
+### Pass-through importers
+Module A exports `foo` which it imports from B and re-exports
+unchanged. Adds a hop with no value. Symptom: A's body contains
+`export { foo } from './b'` and nothing else for that symbol.
+
+### Dependency direction violations
+Per Aperant's import-direction convention (`packages/` never imports
+from `cloud/`), this lens flags any backward import. The static lint
+catches some of these; this lens catches the rest (e.g., implicit type
+re-exports that leak `cloud/` types into `packages/`).
+
+## Apply in Phase 1
+
+When the explore step scans the named area:
+
+1. For each module boundary (file-level or directory-level), identify
+   the explicit imports + exports.
+2. Look for the 6 red flags above.
+3. Note in the inventory: `{Module A} ↔ {Module B} — {red-flag name}
+   ({one-line evidence})`.
+
+## Distinguishing this from DEEPENING and LANGUAGE
+
+| Lens | Question |
+|---|---|
+| **DEEPENING** | Does each abstraction earn its keep at its current depth? |
+| **INTERFACE-DESIGN** | Are the gaps between abstractions well-shaped? |
+| **LANGUAGE** | Does the codebase use the same word for the same thing? |
+
+A red flag in one lens often surfaces in another, but the lens is the
+diagnostic angle. A god-object problem is DEEPENING (the abstraction
+is too deep AND too wide); a feature-envy problem is INTERFACE-DESIGN
+(the boundary is in the wrong place).
+
+## Deletion test (Phase 2 prep)
+
+For each candidate this lens flags, the Phase-2 deletion test asks:
+
+> If I moved this code across the boundary it currently sits behind
+> (or removed the boundary entirely), what would break?
+
+If the answer is "nothing important — the boundary was an accident",
+the deletion test passes and the candidate is high-priority for
+refactor (move the code; the boundary disappears).
+
+If the answer is "we'd lose the ability to test / mock / version this
+slice independently", the deletion test fails — the boundary was
+earning its keep, even if the shape is awkward. Re-scope to "reshape"
+rather than "remove".
+
+## What this lens does NOT cover
+
+- Whether the abstractions on either side of the boundary are deep
+  enough → see `DEEPENING.md`
+- Whether the boundary's types and method names use the codebase's
+  domain language → see `LANGUAGE.md`

package/skills/apt-improve/LANGUAGE.md

@@ -0,0 +1,104 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/improve-codebase-architecture/LANGUAGE.md
+Licensed under MIT. Modifications: scoped to Aperant's apt:improve
+Phase-1 explore step and aligned with CONTEXT.md's aliases-to-avoid
+field — this lens reads that field to catch term conflations.
+-->
+
+# LANGUAGE — Naming-consistency lens
+
+This lens asks: **does the codebase use the same word for the same
+thing?** Do field names match domain language? Is CONTEXT.md's
+"aliases to avoid" list violated anywhere?
+
+Naming inconsistency is invisible until you trip over it. A reader who
+hits `userId` in one file and `user_id` in another, or `account` in
+the UI and `customer` in the backend, has to mentally translate
+between vocabularies — and that translation cost accumulates across
+every code review and every onboarding.
+
+## Red flags this lens surfaces
+
+### Same concept, two names
+The codebase has `user`, `account`, and `customer` referring to the
+same entity in different layers. Pick one and rename. CONTEXT.md's
+"aliases to avoid" field is the canonical place to record which name
+won.
+
+### Same name, two concepts
+The codebase has two distinct `Session` types — one for an auth
+session and one for a chat session. Disambiguate with a domain prefix
+(`AuthSession`, `ChatSession`) so a reader doesn't have to import the
+right one based on file location.
+
+### Field-name drift across layers
+The backend stores `created_at`, the API returns `createdAt`, the UI
+displays `Date created`. The serialization layer becomes a translation
+graveyard. Standardize across all three layers.
+
+### Implementation-detail names
+Field or symbol names that describe *how* something is stored or
+computed rather than *what* it represents. `is_processed_boolean` vs
+`is_processed`. `temp_holder_arr` vs `pending_items`.
+
+### CONTEXT.md violations
+If `CONTEXT.md` declares "Plan thread" with aliases-to-avoid: "Plan
+session, plan chat", any code in the area that calls it a "plan
+session" or "plan chat" is a violation. Grep CONTEXT.md aliases as
+part of this lens.
+
+## Apply in Phase 1
+
+When the explore step scans the named area:
+
+1. Read `CONTEXT.md` (if present) — every term-block's `Aliases to
+   avoid` field becomes a grep target.
+2. Grep the area for each alias. Each hit is a candidate.
+3. Look for the 4 other red flags above by inspection.
+4. Note in the inventory: `{File}:{Line} — uses {wrong-term} for
+   {canonical-term} ({CONTEXT.md reference if applicable})`.
+
+## Apply in Phase 3 (deepening loop)
+
+When the user picks a LANGUAGE candidate, the deepening loop should
+write the canonical decision into CONTEXT.md via `apt-tools context
+write`:
+
+```
+apt-tools context write . \
+  --term "{canonical}" \
+  --definition "{one-line}" \
+  --aliases-to-avoid "{loser1}, {loser2}"
+```
+
+This is the cycle: LANGUAGE lens surfaces conflations → user picks the
+canonical term → CONTEXT.md upserts the term-block → future LANGUAGE
+passes use CONTEXT.md as the grep source.
+
+## Distinguishing this from DEEPENING and INTERFACE-DESIGN
+
+A symbol can have a perfectly good name and still be the wrong depth
+(DEEPENING) or sit behind the wrong boundary (INTERFACE-DESIGN).
+LANGUAGE is orthogonal — it asks "regardless of where this lives or
+how big it is, does its name match the codebase's vocabulary?"
+
+## Deletion test (Phase 2 prep)
+
+The deletion test for LANGUAGE candidates is unusual: deleting the
+*wrong* name doesn't help unless you replace it with the right one. So
+the Phase-2 priority rubric for LANGUAGE candidates is:
+
+> Number of call sites that read with friction × cost of rename
+> divided by ergonomic gain.
+
+High-call-site, cheap-rename, real-confusion candidates are
+high-priority. One-off conflations that aren't blocking anyone are
+low-priority — record them in CONTEXT.md and move on.
+
+## What this lens does NOT cover
+
+- Abstraction depth → `DEEPENING.md`
+- Boundary shape → `INTERFACE-DESIGN.md`
+
+LANGUAGE is read-only of the symbol's *name*, not its *shape*.