Lyra step 2.5 architecture deepening

lyra-step-2.5-architecture-deepening

Thin lyra-step wrapper. Delegates the actual analysis to the improve-codebase-architecture skill. This wrapper only places that work in the Sigma/lyra-step sequence and records it in the workspace state.

Doctrine: Pocock "deep modules" (Matt Pocock — "Your codebase isn't ready for AI", YouTube 2026). A tangled shallow-module codebase makes interface contracts (11.5) impossible to write cleanly — deepen first.

Where it sits

Step 2 Architecture ─┬─> 2.5 deepening (new project: optional polish)
/lyra-step-retrofit ─┘                  (existing project: REQUIRED before 11.5/15)
                          │
                          ▼
                    11 PRD → 11.5 contracts → 15 build
Step 19 Maintenance ──> 2.5 deepening (recurring refactor pass)

When the user invokes this

• "/lyra-step-2.5-architecture-deepening [<workspace-path>]"
• "architektur vertiefen", "deep modules", "vor dem bauen aufräumen"
• automatically recommended by /lyra-step-retrofit (part of the commercial lyra-step framework — not required) for existing projects with shallow-module sprawl

Workspace resolution

Arg 1 → workspace path, else pwd. Verify <workspace>/sigma/.state.json exists (warn if not — the underlying skill still runs against the code repo). Reads CONTEXT.md + docs/adr/ if present (the underlying skill uses domain language from there).

Process

1. Run the improve-codebase-architecture skill against the code repo.
2. Capture the report yourself (the wrapper's job, not the engine's): as soon as the engine has presented its numbered candidate list, write it to <workspace>/sigma/step-2.5-architecture-deepening/output.md — even if the user explores no candidate further. If the user does enter the grilling loop, append the crystallized decisions to the same file.
3. Surface any proposal that changes a public interface as a **Decision:** marker (it affects the contracts 11.5 will write).
4. Recommend: apply high-confidence deepenings BEFORE running 11.5, so contracts lock the new (deep) interfaces, not the old shallow ones.

Outputs

• <workspace>/sigma/step-2.5-architecture-deepening/output.md — the deepening report (proposals, target interfaces, before/after module map).
• Decisions appended to STATUS.md "Open Decisions" (if a Sigma workspace is present; standalone runs just keep the report).

STATUS.md / .state.json update

Sigma workspaces only — skip both files in standalone runs. Contract: in .state.json, set steps["2.5"].status to "done" (report written, no open decisions) or "partial" (report written, decisions open). In STATUS.md, append one line per open decision under the existing ## Open Decisions heading, formatted - [step-2.5] <decision>; never rewrite other sections. No emoji. Audit trail stays in the planning workspace; the refactors themselves land in the code repo.