@laitszkin/apollo-toolkit 4.1.3 → 5.0.0

package/scripts/rewrite-imports.mjs

@@ -88,7 +88,7 @@ for (const name of TOOL_NAMES) {
 /**
  * Map a @laitszkin/* specifier to a root-relative path.
  */
-function resolvePackage(specifier) {
+export function resolvePackage(specifier) {
   const name = specifier.replace('@laitszkin/', '');
   return PACKAGE_MAP[name] || null;
 }
@@ -96,7 +96,7 @@ function resolvePackage(specifier) {
 /**
  * Compute relative import path from sourceFile to pkgPath.
  */
-function relativePath(fromFile, pkgPath) {
+export function relativePath(fromFile, pkgPath) {
   const fromDir = dirname(fromFile);
   let rel = relative(fromDir, resolve(root, pkgPath));
   if (!rel.startsWith('.')) rel = './' + rel;

package/scripts/test.sh

@@ -3,15 +3,66 @@
 # a Node.js 24.x test runner IPC deserialization issue that can make
 # tests flaky when --experimental-test-module-mocks is active globally.
 # See: https://github.com/nodejs/node/issues (test_runner IPC clone)
+#
+# Coverage enforcement (COVERAGE=true):
+#   Per-group line/branch/function thresholds are checked immediately after
+#   each group.  Combined coverage = weighted average of Groups 1+2.  Group 3
+#   (codegraph mock.module tests) excluded due to Node.js incompatible flags.
+#   Combined weighted coverage (Groups 1 + 2) is enforced after all groups
+#   finish.
+#
+# Limitations:
+#   - Split-process: Each group runs in a separate node process, so there is
+#     no single coverage report.  The combined estimate is a file-weighted
+#     average of per-group results.
+#   - Group 3 (mock.module): Excluded from coverage enforcement due to
+#     --experimental-test-module-mocks incompatibility with v8 coverage.
+#   - Windows glob: The test/**/*.test.js glob uses forward slashes.
+#     In CI (shell: bash) this works correctly via Git Bash.
+#     For direct cmd.exe/PowerShell invocation, use backslash globs instead.
 
 EXIT=0
 
+# Coverage tracking globals (populated when COVERAGE=true)
+G1_PCT=0
+G1_FILES=0
+G2_PCT=0
+G2_FILES=0
+
+# Use TMPDIR, TEMP, or /tmp as fallback for platforms without mktemp
+RUN_TEST_LOG="${TMPDIR:-${TEMP:-/tmp}}/test-run-$$.log"
+
+# Extract a pipe-delimited column from the "all files" coverage summary line,
+# stripping whitespace and trailing '%'.
+# Columns: (1) file | (2) line % | (3) branch % | (4) funcs % | (5) uncovered lines
+_cov_col() {
+  local col="$1" text="$2"
+  echo "$text" | grep "all files" | awk -F'|' -v c="$col" '{
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", $c)
+    gsub(/%/, "", $c)
+    print $c
+  }'
+}
+
+# Count the number of individual file entries in a coverage table
+# (lines with numeric coverage data before "all files", excluding the header).
+_cov_file_count() {
+  echo "$1" | awk -F'|' '
+    /^ℹ all files/{exit}
+    /^ℹ file .* line %/{next}
+    $2 ~ /[0-9]/{c++}
+    END{print c}
+  '
+}
+
 run_test_group() {
   local label="$1"
   shift
   echo ""
   echo "==> $label"
-  if "$@"; then
+  "$@" 2>&1 | tee -a "$RUN_TEST_LOG"
+  local group_exit=${PIPESTATUS[0]}
+  if [ "$group_exit" -eq 0 ]; then
     echo "    PASS"
   else
     echo "    FAIL"
@@ -19,21 +70,106 @@ run_test_group() {
   fi
 }
 
-# Group 1: stable non-mock tests (test/)
-run_test_group "Stable tests (test/)" \
-  node --test 'test/**/*.test.js'
+# Like run_test_group but executes via "node --experimental-test-coverage"
+# and enforces per-group threshold checks.  Stores line percentage and file
+# count in the named global variables for later combined-weight computation.
+# Usage: run_coverage_group label line_thr branch_thr func_thr pct_var files_var node_args...
+# Note: do NOT include "node" in node_args; it is prepended automatically.
+run_coverage_group() {
+  local label="$1" line_thr="$2" branch_thr="$3" func_thr="$4" pct_var="$5" files_var="$6"
+  shift 6
+
+  echo ""
+  echo "==> $label"
+
+  local out
+  out=$(node --experimental-test-coverage "$@" 2>&1)
+  local exit_code=$?
+  echo "$out"
+
+  if [ $exit_code -ne 0 ]; then
+    echo "    FAIL (tests failed)"
+    EXIT=1
+    return 1
+  fi
+
+  local line_pct branch_pct func_pct file_count
+  line_pct=$(_cov_col 2 "$out")
+  branch_pct=$(_cov_col 3 "$out")
+  func_pct=$(_cov_col 4 "$out")
+  file_count=$(_cov_file_count "$out")
 
-# Group 2: package .test.js files that do NOT need mock.module
-EXCLUDE='(cmd-init|cmd-list-apis|cmd-survey)'
+  if [ -z "$line_pct" ]; then
+    echo "    FAIL (no coverage data)"
+    EXIT=1
+    return 1
+  fi
+
+  # Store for combined-weight computation (even when thresholds fail)
+  eval "$pct_var=\$line_pct"
+  eval "$files_var=\$file_count"
+
+  local fail=0
+  [ "$(echo "$line_pct < $line_thr" | bc -l 2>/dev/null)" = "1" ] && fail=1
+  [ "$(echo "$branch_pct < $branch_thr" | bc -l 2>/dev/null)" = "1" ] && fail=1
+  [ "$(echo "$func_pct < $func_thr" | bc -l 2>/dev/null)" = "1" ] && fail=1
+
+  if [ "$fail" = "1" ]; then
+    echo "    FAIL (lines=${line_pct}% branches=${branch_pct}% funcs=${func_pct}%)"
+    EXIT=1
+    return 1
+  fi
+
+  echo "    PASS (lines=${line_pct}% branches=${branch_pct}% funcs=${func_pct}%)"
+}
+
+
+# Group 2 test file list (shared between coverage and non-coverage paths)
+EXCLUDE='(cmd-init|cmd-list-apis|cmd-survey|eval)'
 PACKAGE_TEST_FILES=$(find packages -name '*.test.js' -not -path '*/node_modules/*' | grep -v -E "$EXCLUDE" | sort | tr '\n' ' ')
-run_test_group "Package tests (no mock.module)" \
-  node --test $PACKAGE_TEST_FILES
+
+if [ "$COVERAGE" = "true" ]; then
+  # Group 1: stable non-mock tests (test/) — coverage with thresholds
+  run_coverage_group "Stable tests (test/)" 75 60 65 G1_PCT G1_FILES \
+    --test 'test/**/*.test.js'
+
+  # Group 2: package tests (no mock.module) — coverage with thresholds
+  run_coverage_group "Package tests (no mock.module)" 65 60 65 G2_PCT G2_FILES \
+    --test $PACKAGE_TEST_FILES
+else
+  # Group 1: stable non-mock tests (test/)
+  run_test_group "Stable tests (test/)" \
+    node --test 'test/**/*.test.js'
+
+  # Group 2: package .test.js files that do NOT need mock.module
+  run_test_group "Package tests (no mock.module)" \
+    node --test $PACKAGE_TEST_FILES
+fi
 
 # Group 3: mock-dependent tests — isolated with --experimental-test-module-mocks
+# Always runs the same way (excluded from coverage enforcement).
 run_test_group "Package tests (mock.module)" \
   node --experimental-test-module-mocks --test \
     'packages/tools/codegraph/dist/lib/cmd-init.test.js' \
     'packages/tools/codegraph/dist/lib/cmd-list-apis.test.js' \
     'packages/tools/codegraph/dist/lib/cmd-survey.test.js'
 
+# Combined weighted coverage enforcement (Groups 1 + 2 only)
+if [ "$COVERAGE" = "true" ]; then
+  total_files=$((G1_FILES + G2_FILES))
+  if [ "$total_files" -gt 0 ]; then
+    combined_pct=$(echo "scale=2; ($G1_PCT * $G1_FILES + $G2_PCT * $G2_FILES) / $total_files" | bc -l)
+    echo ""
+    echo "==> Combined coverage (G1+G2, file-weighted): ${combined_pct}%"
+    if [ "$(echo "$combined_pct < 80" | bc -l)" = "1" ]; then
+      echo "    FAIL (combined coverage ${combined_pct}% < 80%)"
+      EXIT=1
+    else
+      echo "    PASS (combined coverage ${combined_pct}% >= 80%)"
+    fi
+  fi
+fi
+
+rm -f "$RUN_TEST_LOG"
+
 exit $EXIT

package/skills/design/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: design
-description: Reads SPEC.md, validates technical feasibility through web research, finds quality reference implementations, confirms tech stack compatibility, then produces DESIGN.md (architecture design, external dependencies), CHECKLIST.md (verification strategy), and Architecture Diff. Not for use without a SPEC.md.
+description: Reads SPEC.md, validates technical feasibility through web research, finds quality reference implementations, confirms tech stack compatibility, then produces DESIGN.md (architecture design, external dependencies), CHECKLIST.md (verification strategy), Architecture Diff, and design-time refactoring plan. Not for use without a SPEC.md.
 ---
 
 ## Goal
 
 Transform business specifications (SPEC.md) into technical design.
 Research first, design second — avoid reinventing wheels and ground every decision in evidence.
+During architecture survey, identify and classify refactoring opportunities by module boundary scope — include them as standard design output.
 
 ## Acceptance Criteria
 
 - Three web research passes completed and recorded
-- `docs/plans/<YYYY-MM-DD>/<spec_name>/DESIGN.md` produced, covering: architecture design, external dependencies (with API facts and limits), data persistence, invariants, technical trade-offs
+- `docs/plans/<YYYY-MM-DD>/<spec_name>/DESIGN.md` produced, covering: architecture design, external dependencies (with API facts and limits), data persistence, invariants, technical trade-offs, design-time refactoring
 - `docs/plans/<YYYY-MM-DD>/<spec_name>/CHECKLIST.md` produced, covering: behavior-to-test mapping, hardening requirements, test level choices
 - Architecture Diff produced using the C4 model hierarchy
+- Design-time refactoring classified by module boundary scope (T1–T3) and dispositioned (refactored / scheduled / deferred with rationale)
 
 ## Workflow
 
@@ -44,13 +46,13 @@ Output: Feasibility assessment + risk checklist
 
 **⚠️ Decision gate — STOP if blocking issues are found.**
 
-| Assessment | Meaning | Action |
-|---|---|---|
-| ✅ All feasible | Every requirement is achievable under the current or extendable tech stack | Continue to Step 3 |
-| ⚠️ Partial validation needed | Some areas are uncertain; the path is unclear but there is no confirmed blocker | Continue, but mark all uncertain items as Exploratory-level risks in DESIGN.md. Suggest a spike or prototype where warranted |
-| 🛑 **Blocking issues found** | At least one requirement cannot be implemented under any reasonable tech stack extension within the project's constraints | **STOP.** Do NOT proceed to architecture design. Document the specific infeasibility with supporting evidence (API limitations, licensing, missing platform capabilities, etc.). Report to the user and request SPEC.md revision |
+| Assessment | Action |
+|---|---|
+| ✅ All feasible | Continue to Step 3 |
+| ⚠️ Partial validation needed | Continue, mark uncertain items as Exploratory-level risks; suggest spike/prototype where warranted |
+| 🛑 **Blocking issues found** | **STOP.** Do not proceed. Document infeasibility with evidence (API limits, licensing, platform gaps). Request SPEC.md revision |
 
-**Why this gate exists**: The spec phase validates requirements against the repo's existing code only — it does not verify external technical feasibility. This is the first and only time in the pipeline that technical feasibility is checked against real-world constraints. Proceeding with architecture design on infeasible requirements produces wasted work. If you hit a blocking issue, escalate before designing.
+**Why this gate exists**: The spec phase validates against existing code only — it does not check external feasibility. This is the pipeline's only chance to catch real-world constraints before design. If blocking, escalate before designing.
 
 #### 2b. Existing Quality References
 
@@ -80,19 +82,21 @@ Cover the following sections:
 - **Research Summary**: Feasibility per requirement, existing references, tech stack compatibility (from Step 2)
 - **Architecture Overview**: Module list with responsibilities, entry points, trust boundary, target vs baseline comparison
 - **Interaction Design**: Module call relationships, coupling patterns (route / RPC / event / sync), failure propagation, ordering constraints
-- **External Dependencies**: API facts, limits and failure modes, security and keys (absorbs what was formerly in contract.md)
+- **External Dependencies**: API facts, limits and failure modes, security and keys
 - **Data Persistence**: Storage resources, consistency expectations
 - **System Invariants**: Architectural constraints that must not be violated, plus violation symptoms
 - **Technical Trade-offs**: Each decision with rejected alternatives and lock-in effects
+- **Design-Time Refactoring**: T1–T3 code health findings classified and dispositioned
 
 Use `Req 1`, `Req 2` numbering to reference SPEC.md requirements (matching the SPEC.md template's `Requirement 1`, `Requirement 2`).
 
 **Scale awareness** — Not every section applies at full depth. Adapt based on the change's scope:
 
-- **Interaction Design (Section 3)**: If the change is confined to a single module with no new cross-module coupling, mark this section as `None` (no new interaction anchors needed). Do not fabricate INT-### entries for the sake of filling the table.
-- **External Dependency deep-dives (Section 4.2)**: For simple utility libraries (e.g., date formatting, UUID generation) that have no API quotas, authentication, or failure modes, skip the sub-tables. A one-line entry in Section 4.1 overview suffices. Reserve the full 4-sub-table format for dependencies with real operational complexity (external APIs, databases, message queues).
-- **Target vs Baseline (Section 2.3)**: If the change touches multiple dimensions (new modules, removed modules, ownership shifts, deployment changes), expand the table to multiple rows — one row per dimension. If it is a single-dimension change, a single row is fine.
-- **System Invariants (Section 6)**: If the change does not modify any architectural constraint (e.g., purely additive within an existing module), explicitly write `None` with a brief justification. Do not fabricate invariants.
+- **Interaction Design (Section 3)**: If the change is confined to a single module with no new cross-module coupling, mark this section as `None`. Do not fabricate INT-### entries.
+- **External Dependency deep-dives (Section 4.2)**: For simple utility libraries (e.g., date formatting, UUID generation) with no API quotas, authentication, or failure modes, skip the sub-tables. A one-line entry in Section 4.1 overview suffices.
+- **Target vs Baseline (Section 2.3)**: If the change touches multiple dimensions (new modules, removed modules, ownership shifts, deployment changes), expand to multiple rows. A single-dimension change needs only one row.
+- **System Invariants (Section 6)**: If the change does not modify any architectural constraint, explicitly write `None` with brief justification.
+- **Design-Time Refactoring (Section 8)**: If no code health issues were identified during the architecture survey, write `None`. Do not fabricate findings.
 
 **Design self-challenge** — Before finalizing the design, step back and ask three questions:
 
@@ -100,6 +104,14 @@ Use `Req 1`, `Req 2` numbering to reference SPEC.md requirements (matching the S
 2. **Is this the simplest viable design?** Have I introduced abstractions, indirections, or intermediate layers that are not justified by the current requirements? Prefer the simplest structure that works.
 3. **Are there rejected alternatives?** For every major architectural decision (module split, dependency choice, communication pattern), if you have not considered and explicitly rejected at least one alternative, you may be settling on the first workable solution rather than the best one.
 
+**Design-time refactoring** — While designing the target architecture, also assess code health in the affected modules:
+
+- **T1 (Module-internal simplification)**: Simplify control flow, remove dead code, inline unnecessary wrappers within a single function or file. Existing unit tests validate behavior — refactor directly.
+- **T2 (Module-internal restructuring)**: Extract shared logic, consolidate state, reorganize files within the same module boundary. Existing integration tests validate behavior — include in the design's task decomposition.
+- **T3 (Module boundary adjustment)**: Changes affecting a module's public API, data contract, or cross-module coupling. Requires dedicated test coverage — define test strategy in CHECKLIST.md.
+
+See `references/code-smells.md` for patterns to identify, and the module-specific reference files for detailed guidance per tier.
+
 **Single spec**: Produce one DESIGN.md for one SPEC.md.
 **Batch spec**: Produce **one** unified DESIGN.md covering the scope of all SPEC.md files in the batch.
 
@@ -109,12 +121,12 @@ Use the `test-case-strategy` skill to design the verification strategy.
 Use `assets/templates/CHECKLIST.md`.
 
 The CHECKLIST.md defines the **test plan** — it maps SPEC.md requirements to tests, defines hardening requirements, and records test-level decisions.
-(Do not include execution tracking fields — those belong to the implementation phase.)
 
 Cover the following sections:
 - **Behavior-to-Test Checklist**: Each BDD requirement mapped to one or more tests
 - **Hardening Requirements**: Regression tests, drift checks, property-based tests, edge cases, authorization checks
 - **E2E / Integration Decisions**: Per flow, choose the appropriate test level with rationale
+- **Design-Time Refactoring (T3)**: If T3 refactoring is planned, define its test coverage requirements here
 
 **Mandatory test coverage** (applies when the SPEC.md describes changes other than pure documentation or pure test changes):
 
@@ -138,6 +150,12 @@ Do not read unrelated features or modules — maintain context economy.
 
 If no existing architecture exists, skip the baseline comparison and start defining the boundary from System Context level.
 
+**Code health assessment** — While reading code to measure the baseline, actively assess code quality:
+- Identify code smells, dead code, legacy patterns, and unnecessary complexity in the affected modules
+- Classify findings using the T1–T3 framework (see `references/code-smells.md` for patterns to recognize)
+- T1 items (module-internal simplification) are safe to refactor immediately — existing tests validate behavioral preservation
+- T2 and T3 items feed into the target architecture design in Step 3
+
 #### 5b. Measure Baseline Drift
 
 Compare the existing architecture diagram against the current code to assess its reliability:
@@ -151,13 +169,7 @@ Compare the existing architecture diagram against the current code to assess its
 3. **Component level** (submodules): Define functions, variables, dataflows, and error rows within each submodule
 4. **Code level** (selective): Only supplement function-level details for critical paths
 
-C4 level reference:
-| C4 Level | Maps to | Purpose |
-|----------|---------|---------|
-| System Context | Overall system + external actors | System boundary and external dependencies |
-| Container | Feature (functional module) | High-level functional boundary |
-| Component | Submodule (implementation unit) | Internal implementation units |
-| Code | Function level | Function-level details (selective) |
+C4 level mapping: System Context → system boundary, Container → feature, Component → submodule, Code → function (selective). See `references/definition.md` for full definitions.
 
 #### 5d. Evidence Tracing
 
@@ -170,46 +182,21 @@ Each component should link to:
 Two alternative workflows — use the **Classic flow** when `codegraph` is not installed, or the **CodeGraph-integrated flow** when it is available.
 
 **Classic flow** (manual):
+Generate and validate the architecture diff using `apltk architecture` commands. Confirm validation passes, then produce a visual comparison. See `references/architecture.md` for all CLI flags.
 
-```bash
-apltk architecture --spec <spec_dir> render
-apltk architecture --spec <spec_dir> validate
-```
+**New flow (CodeGraph-integrated):**
 
-Confirm validation passes, then use the diff command to produce a visual comparison:
+1. **Survey the existing API landscape** — Use `apltk codegraph list-apis` to review the full project API directory (function names, file paths, callers). Understand what existing modules and functions your new feature will interact with.
 
-```bash
-apltk architecture diff
-```
+2. **Fill the proposal skeleton** — Based on your design decisions from steps 5a–5d, fill in the `proposal.yaml` file generated by `apltk architecture template`. Define the feature, its submodules, their functions, and cross-feature edges.
 
-**New flow (CodeGraph-integrated):**
+3. **Apply and verify** — Apply the mutations and verify correctness:
+   - `apltk architecture apply` processes all mutations with undo protection
+   - `apltk codegraph verify` confirms every symbol and edge reference exists in actual code
+
+4. **Render diff** (optional) — `apltk architecture diff --spec <spec_dir>` for visual confirmation.
 
-1. **Survey the existing API landscape**:
-   ```bash
-   apltk codegraph list-apis --all
-   ```
-   This returns the full project API directory (function names, file paths, callers) as a reference for integration points. Use this data to understand what existing modules, services, and functions your new feature will interact with.
-
-2. **Fill the proposal skeleton**: Based on your design decisions from steps 5a-5d,
-   fill in the `proposal.yaml` file generated by `apltk architecture template`.
-   Define the feature, its submodules, their functions, and cross-feature edges.
-
-3. **Apply batch mutations**:
-   ```bash
-   apltk architecture apply <spec_dir>/architecture_diff/atlas/proposal.yaml --spec <spec_dir>
-   ```
-   This processes all mutations in one call with undo protection.
-
-4. **Verify correctness**:
-   ```bash
-   apltk codegraph verify --spec <spec_dir>
-   ```
-   This confirms every symbol and edge reference in the spec overlay exists in the actual code.
-
-5. **Render and validate** (optional, for visual confirmation):
-   ```bash
-   apltk architecture diff --spec <spec_dir>
-   ```
+See `references/architecture.md` for exact CLI flags and mutation commands.
 
 **Single spec**: Produce one Architecture Diff for one SPEC.md.
 **Batch spec**: Produce **one** unified Architecture Diff covering all SPEC.md files in the batch.
@@ -225,23 +212,29 @@ Before delivering, run two passes — completeness then quality.
 - External dependency API facts are traceable to official documentation
 - CHECKLIST.md completely covers all BDD requirements from SPEC.md
 - Architecture Diff covers the full change scope
+- Design-time refactoring is documented in DESIGN.md Section 8, with T1–T3 findings classified and dispositioned (refactored / scheduled / deferred with rationale)
 
 **Design quality checks** (architectural soundness):
 
-- **Requirement traceability**: Can every BDD behavior from SPEC.md be traced to a module, interaction, data flow, or invariant in this design? If a requirement has no home, the design is incomplete.
-- **Internal consistency**: Do the modules listed in Section 2 appear as callers or callees in Section 3? Do the dependencies in Section 4 correspond to module responsibilities in Section 2? Unreferenced modules or dependencies indicate dead structure.
-- **Design simplicity**: Have I applied the scale awareness guidance from Step 3? Is this the simplest design that satisfies all requirements? Could any module, abstraction, or dependency be removed without breaking functionality?
-- **Risk transparency**: Are all feasibility risks, compatibility concerns, or uncertain technical points from Step 2 either addressed in the design or explicitly documented as accepted risks? Undocumented risks will surface during implementation as surprises — document them now.
+- **Requirement traceability**: Can every BDD behavior from SPEC.md be traced to a module, interaction, data flow, or invariant in this design?
+- **Internal consistency**: Do the modules listed in Section 2 appear as callers or callees in Section 3? Do the dependencies in Section 4 correspond to module responsibilities in Section 2?
+- **Design simplicity**: Is this the simplest design that satisfies all requirements? Could any module, abstraction, or dependency be removed without breaking functionality?
+- **Risk transparency**: Are all feasibility risks, compatibility concerns, or uncertain technical points from Step 2 either addressed in the design or explicitly documented as accepted risks?
+- **Refactoring disposition**: Are all identified code health findings accounted for — either refactored, scheduled in the task plan, or explicitly deferred with rationale? Unaddressed T1/T2 findings represent missed opportunities to reduce technical debt at the cheapest possible time.
 
 ## Examples
 
-- "SPEC.md defines a real-time messaging feature" → Research WebSocket vs SSE vs Polling trade-offs → Confirm compatibility with existing repo dependencies → Choose SSE → Design architecture → Produce DESIGN.md + CHECKLIST.md + Architecture Diff
+- "SPEC.md defines a real-time messaging feature" → Research WebSocket vs SSE vs Polling → Confirm compatibility → Choose SSE → Design architecture → Produce DESIGN.md + CHECKLIST.md + Architecture Diff → During code survey, identify legacy socket wrapper (T2) → schedule extraction in task plan
 - "SPEC.md requires CSV export, repo has no CSV library" → Research Node.js CSV libraries (json2csv vs csv-writer vs papaparse) → Confirm compatibility → Choose the lightest option → Design export flow architecture
-- "Batch spec: docs/plans/2026-05-29/auth-redesign/ with 3 SPEC.md files (login, permissions, 2FA)" → Read all 3 SPEC.md files → Unified research across all requirements → Produce **one** DESIGN.md + CHECKLIST.md + Architecture Diff covering the entire auth system
+- "Batch spec: docs/plans/2026-05-29/auth-redesign/ with 3 SPEC.md files (login, permissions, 2FA)" → Read all 3 SPEC.md files → Unified research → Produce **one** DESIGN.md + CHECKLIST.md + Architecture Diff → Identify dead auth middleware during survey (T1) → remove and verify with existing tests
 
 ## References
 
 - `assets/templates/DESIGN.md` — DESIGN.md template
 - `assets/templates/CHECKLIST.md` — CHECKLIST.md template
-- `references/architecture.md` — `apltk architecture` CLI reference (all mutation commands, for when you need more than render/validate/diff)
-- `references/definition.md` — C4 model level definitions (if you need more detail than the summary in Step 5c)
+- `references/architecture.md` — `apltk architecture` CLI reference (all mutation commands)
+- `references/definition.md` — C4 model level definitions
+- `references/code-smells.md` — Common code smell patterns to spot during architecture survey
+- `references/module-internal-simplification.md` — T1: module-internal simplification patterns
+- `references/module-internal-restructuring.md` — T2: module-internal restructuring patterns
+- `references/module-boundary-adjustment.md` — T3: module boundary adjustment patterns

package/skills/design/assets/templates/DESIGN.md

@@ -139,3 +139,15 @@ If none, write **None** and note the scope (e.g., stdlib only / in-process calls
 | Decision | Rejected Alternatives | Lock-in Effect on Implementation |
 |---|---|---|
 | […] | […] | […] |
+
+---
+
+## 8. Design-Time Refactoring
+
+Code health findings identified during architecture survey, classified by module boundary scope.
+
+| Finding | Affected Module | Tier (T1/T2/T3) | Disposition (Refactored / Scheduled / Deferred) | Test Evidence |
+|---|---|---|---|---|
+| […] | […] | […] | […] | […] |
+
+If none, write **None**.

package/skills/design/references/code-smells.md

@@ -0,0 +1,94 @@
+# Code Smell Patterns — Architecture Survey Reference
+
+Common patterns to recognize while reading code during architecture survey.
+Use this catalog to identify refactoring opportunities; each entry notes the likely tier (T1/T2/T3) for dispositioning.
+
+## Control Flow
+
+### Deeply Nested Conditionals
+Multiple levels of `if`/`else`/`switch` exceeding 3 levels deep, or containing duplicated branch predicates.
+- **T1 fix**: Early returns, guard clauses, switch-to-map, predicate extraction
+- **Symptoms**: Methods with >3 indent levels, repeated `if (condition)` checks
+
+### Mutable Flag Variables
+Boolean or enum variables threaded through functions purely to control which branch runs later.
+- **T1 fix**: Split the function at the decision point; caller chooses which path
+- **Symptoms**: `let/var` flags declared at function start, set in multiple branches
+
+### Sequential Conditionals Hiding State Machine
+A chain of `if`/`else` blocks that implicitly represent state transitions.
+- **T2 fix**: Explicit state machine or table-driven dispatch
+- **Symptoms**: State variable mutated across a chain, each branch checks both old and new state
+
+## Data & State
+
+### Shotgun Duplication
+The same small expression or transformation repeated across multiple functions or files.
+- **T2 fix**: Extract to shared utility or helper; place in the lowest-level module that needs it
+- **Symptoms**: Copy-pasted 2-5 line blocks, grep reveals identical patterns across module
+
+### Temporary Field
+An object property or class field only set in some code paths and always `null`/`undefined` in others.
+- **T1 fix**: Extract a separate type or parameter object; remove the field from the base type
+- **Symptoms**: Fields with `?`/`| undefined` that are checked before every use
+
+### Overly Permissive Null Handling
+Parameters or return types that accept `null` when the semantics don't require it, propagating `?.` / `== null` checks through callers.
+- **T1 fix**: Tighten the contract — require defined values, push null handling to the boundary
+- **Symptoms**: Chains of `?.a?.b?.c`, unnecessary `== null` checks on always-present data
+
+## Structure
+
+### Dead Code
+Exported functions never called, branches unreachable due to constants, commented-out code blocks.
+- **T1 fix**: Remove the function or branch; let the compiler/test suite catch if something depended on it
+- **Symptoms**: grep shows zero callers, `if (false)`, files with only comments
+
+### Lazy Class / Middle Man
+A class or function that does nothing but delegate to another, with no added behavior or transformation.
+- **T1 fix**: Inline the delegation; remove the intermediate
+- **Symptoms**: 1:1 method mapping between wrapper and wrapped, no state or logic added
+
+### Divergent Change Pattern
+The same class or file is modified for multiple unrelated reasons across recent commits.
+- **T2 fix**: Split the file along axis-of-change lines; each responsibility gets its own home
+- **Symptoms**: git log shows the same file touched for feature work, bug fixes, and refactoring in the same period
+
+### Data Clump
+The same 2-4 parameters appear together across multiple function signatures.
+- **T2 fix**: Extract parameter object; group validation and formatting with the new type
+- **Symptoms**: `(start, end, limit)`, `(userId, role, tenantId)` repeated across 3+ functions
+
+## Coupling
+
+### Feature Envy
+A function accesses data or calls methods on another object more than on its own.
+- **T2 fix**: Move the function to the object that owns the data it depends on
+- **Symptoms**: `a.x`, `a.y`, `a.z` in a method of `B`; long chains of `getter().getter()`
+
+### Inappropriate Intimacy
+Two modules or classes reach into each other's internal state rather than using public interfaces.
+- **T3 fix**: Define a clear interface between them; extract shared state into a third module
+- **Symptoms**: `friend`/`internal` usage across module boundaries, circular imports
+
+### God Object / God Module
+A single file or class with disproportionate size and responsibility breadth.
+- **T3 fix**: Decompose by responsibility into separate modules; update callers
+- **Symptoms**: File exceeds 500 lines, contains >1 "section" comment block, 10+ imports
+
+## Legacy & Migration
+
+### Deprecated API Usage
+Import from deprecated packages, usage of `@deprecated`-marked symbols, or reliance on removed Node.js/TypeScript features.
+- **T1 fix**: Replace with the recommended alternative (often a find-and-replace across the module)
+- **Symptoms**: `@deprecated` JSDoc, runtime deprecation warnings, import from `/dist/` or `lib/`
+
+### No-Longer-Needed Workaround
+Code that exists to work around a bug or gap in a previous framework/library version, now resolved upstream.
+- **T1 fix**: Remove the workaround; test the happy path and edge case
+- **Symptoms**: Comments referencing old issue numbers or "temporary" workarounds, version-gated blocks for very old versions
+
+### Commented-Out Alternative
+A second version of a function/block left commented out "for reference."
+- **T1 fix**: Remove; if needed, git history preserves the alternative
+- **Symptoms**: Blocks commented out with explanations like "old version" or "alternative approach"