@aperant/framework 0.6.7 → 0.7.3

package/dist/plugin/skills/apt-discuss/SKILL.md

@@ -17,7 +17,7 @@ execution_modes:
   - step
   - research
 allowed-tools: "Bash, Read, Grep, Glob, Write"
-argument-hint: "apt:discuss [--brainstorm] [topic]"
+argument-hint: "apt:discuss [--brainstorm] [--grill] [topic]"
 gates: []
 ---
 <objective>
@@ -46,6 +46,31 @@ never by asking:
 These are two postures of the same skill, not two different skills. The
 intent-detection step below decides which one to enter — same file, same
 artifact layout, different section populated.
+
+**Decision-lock posture loader (Pocock adoption ID-02 + ID-04 — AC11).**
+When entering decision-lock posture, you MUST load
+`appendices/grill-discipline.md` into reasoning context. It carries the
+validated 100-token reframe sentence ("Your job is not to emit a plan;
+your job is to resolve the design tree until planning is mechanical.")
+and the autonomy-aware degradation table (Autonomy 1 grills everything;
+Autonomy 2 batches recommendations; Autonomy 3 auto-locks with three
+escalation triggers — conflict with prior locked decision, critical-path
+file touched, or no defensible default). This appendix is the canonical
+source for the autonomy-aware rule; downstream skills (`apt:improve`,
+`apt:triage`) reference it rather than re-stating the policy. Brainstorm
+posture does NOT load this appendix.
+
+**Brainstorm posture zoom-out helper (Pocock adoption AC6 + AC11).**
+When in brainstorm posture and the user's turn contains a zoom-out
+trigger phrase ("give me a broader picture", "I'm lost in this area",
+"explain how this fits", "what's the surrounding architecture", "zoom
+out from X"), load `appendices/zoom-out-helper.md` and follow its
+3-6-line compressed orientation pattern. The brainstorm posture stays
+active — this is an augmentation, not a pivot. The full router-invocable
+`/apt:zoom-out` skill is the right answer when the user invokes it
+explicitly; this helper is the right answer when the request surfaces
+inside an active brainstorm discussion. Decision-lock posture does NOT
+load this helper (orientation is descriptive, not normative).
 </objective>
 
 <your_environment>
@@ -158,10 +183,11 @@ If any file is missing, proceed with what's available. The framework works with
 Extract the task description from `$ARGUMENTS`:
 
 1. Strip mode flags (`--assumptions`, `--power`, `--auto`, `--review-auto`, `--continue`) from arguments
-2. The remaining text is the task description
-3. If task description is empty but `state.json` has an `active_task`, use that task's description
-4. If still empty, ask: "What are you working on?"
-5. Generate a `task-id` slug from the description: lowercase, hyphens, max 40 characters
+2. Strip the **`--grill`** overlay flag from arguments (orthogonal to the mode flags — see Section 6.5). `--grill` may combine with any mode; standalone `--grill` defaults to Interactive.
+3. The remaining text is the task description
+4. If task description is empty but `state.json` has an `active_task`, use that task's description
+5. If still empty, ask: "What are you working on?"
+6. Generate a `task-id` slug from the description: lowercase, hyphens, max 40 characters
    - Example: "Add OAuth login with Google" -> `add-oauth-login-with-google`
 
 ## 3.5. Brainstorm (skip if you picked decision-lock in Section 1)
@@ -539,6 +565,47 @@ Review-Auto is Auto Mode **plus one human checkpoint at the batch end**. It does
 
 Do NOT introduce per-decision staging ("show me D-01, wait, show me D-02, wait...") — that collapses review-auto into spaced interactive mode and defeats the point of joint reasoning up front. Do NOT skip the pause ("autonomy is high, let's just write it") — that collapses review-auto into auto. The one pause at the end is the whole identity of this mode.
 
+## 6.5. Grill Mode (`--grill` flag — Pocock `grill-with-docs` overlay)
+
+**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies Pocock's 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
+
+The discipline this overlay loads is already in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md) — re-read the reframe sentence and the autonomy degradation table before each grill turn. **Do NOT duplicate that content here.** What follows is only the moves + writer-call instructions specific to the overlay.
+
+### The 4 grill moves (apply during gray-area resolution)
+
+1. **Challenge against the glossary.** When the user uses a term that conflicts with an existing CONTEXT.md term-block, call it out immediately: *"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"* Read `CONTEXT.md` (or per-context CONTEXT files via `CONTEXT-MAP.md`) when the overlay activates; skip silently if absent.
+2. **Sharpen fuzzy language.** When the user uses vague or overloaded terms, propose a precise canonical term: *"You're saying 'account' — do you mean Customer or User? Those are different things."*
+3. **Stress-test with concrete scenarios.** When domain relationships are being discussed, invent specific scenarios that probe edge cases and force precision about the boundaries between concepts.
+4. **Cross-reference with code.** When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: *"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"*
+
+### Inline writer calls (NOT batched)
+
+When a term resolves with confidence during the grill, invoke `apt-tools context write` to upsert the term-block into CONTEXT.md **right there** — do NOT batch:
+
+```bash
+node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs context write . \
+  --term "Plan thread" \
+  --definition "<one-line definition>" \
+  --aliases-to-avoid "Plan session,plan chat" \
+  --cardinality "one-to-many"
+```
+
+**Lazy creation:** if no `CONTEXT.md` exists at the project root (or in the relevant per-context directory when `CONTEXT-MAP.md` is present), the first resolved term creates the file. Do NOT create CONTEXT.md upfront with placeholder content.
+
+**Glossary-only rule:** CONTEXT.md is a glossary of domain terms — NO implementation details, NO spec content, NO scratch-pad notes. Implementation lives in `spec.md` / `implementation_plan.json`; scratch lives in `.aperant/context/notes/{task-id}.md`. Term-blocks are user-facing concepts (e.g. "Plan thread", "Sparring round"), not code identifiers (e.g. "ChatSession", "useTaskStore").
+
+When a decision passes the **Nygard 3-gate**, offer to write an ADR via `apt-tools adr write .`. The 3-gate (ALL three must hold — miss one and skip the ADR):
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful.
+2. **Surprising without context** — a future reader will wonder *"why did they do it this way?"*.
+3. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons.
+
+If only one or two hold, the decision belongs in `.aperant/context/notes/{task-id}.md` (locked-decisions list), not in an ADR.
+
+### Autonomy interaction
+
+`--grill` does not change the autonomy degradation already specified in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md). Autonomy 1 grills every term/decision interactively; Autonomy 2 batches recommendations; Autonomy 3 auto-locks with the three escalation triggers (conflict-with-locked, critical-path file, no-defensible-default). The overlay simply ensures that whichever autonomy path runs, the writer CLIs fire as side-effects of the resolution work.
+
 ## 7. Advanced Elicitation (DEEP Tasks Only)
 
 After all decisions are locked, check the task track. If the track is DEEP (from state.json or router context), behavior depends on the resolved mode from Section 6's precedence chain (D-07):

package/dist/plugin/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/dist/plugin/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/dist/plugin/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 |
 |---|---|
@@ -340,11 +383,20 @@ executor commits introduce a new feature surface without registering it.
 
 ```bash
 node packages/framework/bin/apt-tools.mjs features-audit . \
+  --task-id "$TASK_ID" \
   --diff-files "$(git diff --name-only HEAD^ HEAD | tr '\n' ',')" \
   --apply-stubs
 ```
 
 Notes:
+- `--task-id $TASK_ID` (BUG-025b) is mandatory when the executor runs
+  from the main-repo cwd instead of inside the worktree (the
+  orchestrator's common path). features-audit resolves the worktree's
+  `.aperant/features/` from the active task record and writes there,
+  preventing generated `*.json` from leaking into main. When invoked
+  from the worktree cwd directly, `--task-id` is a no-op (layer 1
+  detection short-circuits). Pass `--no-worktree-redirect` only when
+  you intentionally want to write to the invoking cwd.
 - `--apply-stubs` only runs when the matched surface's policy is
   `auto-update` (the default for `.aperant/features/*.json`). Users who
   opted out via `/apt:setup` Batch 7 get a no-op — the command still

package/dist/plugin/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/dist/plugin/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.