@aperant/framework 0.6.3 → 0.6.5

package/skills/apt-execute/SKILL.md

@@ -9,16 +9,20 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-executor"
+task_context: require-existing
 default_execution_mode: auto
 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.
@@ -78,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>
@@ -133,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
@@ -235,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.**
@@ -255,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*.

package/skills/apt-improve/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: apt:improve
+description: "Proactive refactor discovery — scan a named area through DEEPENING / INTERFACE-DESIGN / LANGUAGE lenses, present top candidates, deepen via grill loop."
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "The user feels code has rotted and wants a refactor surface (not a feature). Triggers: 'this part of the codebase needs work', 'I want to refactor X but don't know where to start', 'show me what's worth refactoring in Y'."
+user_invocable: true
+internal: false
+spawns_agent: true
+agent_name: "apt-improver"
+task_context: create-new
+default_track: DEEP
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Grep, Glob, Bash"
+argument-hint: "apt:improve [area-name]"
+gates: []
+---
+
+# Improve — Proactive Refactor Discovery
+
+Open question #2 in the Pocock adoption spec was answered concretely:
+`apt:review` Pass 4 (architecture) is strictly **reactive** — it audits
+the current diff for boundary violations. The work-intent "look at this
+codebase and tell me what to refactor proactively" has no home today
+(users retrofit it onto `apt:discuss --brainstorm` or `/apt:roundtable`,
+both scope-mismatched). This skill is that home.
+
+**Pocock adoption attribution.** 3-phase workflow + DEEPENING /
+INTERFACE-DESIGN / LANGUAGE lenses ported from Matt Pocock's MIT-licensed
+`improve-codebase-architecture` skill. Aperant-specific: spawns the
+`apt-improver` agent and references `apt-discuss/appendices/grill-discipline.md`
+as the canonical source for the autonomy-aware deepening loop rather than
+re-stating the policy here.
+
+## When to Use
+
+- Feeling that an area of the codebase has rotted but unsure where to
+  start (proactive discovery)
+- Before a multi-task refactor cycle, to surface the highest-leverage
+  candidates first
+- After a feature has bedded in and the user wants to consolidate
+
+## When NOT to Use
+
+- Auditing a current diff for boundary violations — that's `/apt:review`
+  Pass 4 (reactive)
+- Locking a specific refactor decision — use `/apt:discuss` instead
+- Renaming or restructuring without proactive discovery — use
+  `/apt:plan` directly
+
+## 3-Phase workflow
+
+### Phase 1 — Explore (scan a named area for candidate refactors)
+
+Sub-agent `apt-improver` reads:
+
+- The named area (a noun phrase like "sparring engine", "feature
+  registry", "auth flow")
+- `CONTEXT.md` term-blocks matching the area (if present)
+- Relevant files via Glob/Grep
+
+It applies three lenses, each described in its own sub-file:
+
+- **DEEPENING** (`DEEPENING.md`) — does this area model the domain at
+  the right depth? Are abstractions earning their keep, or are they
+  shallow wrappers hiding nothing?
+- **INTERFACE-DESIGN** (`INTERFACE-DESIGN.md`) — are the boundaries
+  between modules well-shaped? Are there feature-envy patterns? Hidden
+  coupling? Async leakage?
+- **LANGUAGE** (`LANGUAGE.md`) — 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?
+
+Output: a Phase-1 inventory of **candidate refactors** with one-line
+diagnoses per candidate.
+
+### Phase 2 — Present candidates (top 3-5 with deletion-test rationale)
+
+The skill body filters the Phase-1 inventory down to 3-5 candidates
+using the **deletion test**: for each candidate, ask "if I deleted this
+abstraction, what would break?" If the answer is "nothing important",
+the candidate is high-priority (the abstraction was paying no rent).
+
+Output to the user:
+
+```markdown
+## Refactor candidates for {area}
+
+1. **{Candidate title}** — {one-line diagnosis}.
+   Deletion test: {what breaks if removed} → {priority: high/med/low}.
+
+2. ...
+```
+
+### Phase 3 — Deepen via grill loop (autonomy-aware)
+
+The user picks one or more candidates. For each picked candidate, the
+skill enters a deepening loop. **This loop references
+`apt-discuss/appendices/grill-discipline.md` as the canonical source**
+for autonomy-aware degradation:
+
+- Autonomy 1: ask the user about every load-bearing design question
+- Autonomy 2: batch-recommend per decision, user reviews at end
+- Autonomy 3: auto-lock with the 3 escalation triggers (conflict with
+  prior locked decision; critical-path file touched; no defensible
+  default)
+
+The deepening loop produces a concrete refactor plan (which becomes
+`/apt:plan`'s input on a subsequent invocation).
+
+## Sub-files (MIT-attributed)
+
+- `DEEPENING.md` — domain-modeling depth lens
+- `INTERFACE-DESIGN.md` — boundary-shape lens
+- `LANGUAGE.md` — naming-consistency lens
+
+All three are ported from Matt Pocock's improve-codebase-architecture
+skill with MIT attribution per AC15.
+
+## Agent spawned
+
+`apt-improver` (definition at `packages/framework/agents/apt-improver.md`)
+runs Phase 1 — the codebase scan. Phases 2 and 3 run inline in the
+parent agent (no separate sub-agent) because they require user
+interaction for the candidate filter + the deepening loop.
+
+## Output contract
+
+- Phase 1 outputs a candidate inventory to stdout (not persisted).
+- Phase 2 outputs the top 3-5 to stdout for user selection.
+- Phase 3 (deepening loop) writes locked decisions to
+  `.aperant/context/notes/{task-id}.md` via `apt-tools context write`
+  and `apt-tools adr write` (the latter only when Nygard's 3-gate
+  filter passes — most refactor decisions are reversible and stay in
+  context-notes).
+- The skill does NOT emit an implementation plan — that's `/apt:plan`'s
+  job. apt:improve produces *what to refactor*; apt:plan produces *how*.

package/skills/apt-mockup/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: step
 execution_modes:
   - auto

package/skills/apt-pause/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-personas/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto