oh-my-agent-commandcode 0.0.0-stage → 20.38.4

package/skills/oma-recap/resources/output-formats.md

@@ -0,0 +1,83 @@
+# Recap Output Format Templates
+
+Markdown templates for the recap files written to `.agents/results/recap/`.
+Response language follows the user's prompt language first, then the `language` setting in `.agents/oma-config.yaml`, then English.
+
+## Daily format (1d or specific date)
+
+```markdown
+## {date} Recap
+
+> **TL;DR**
+> - {Completed outcome, only with completion evidence}
+> - {In-progress or requested work, labelled with its status when completion is unproven}
+> - {Another supported outcome or status}
+
+### Overview
+2-3 sentence summary of the day. Written from "I did X" perspective.
+Distinguish requested, in-progress, and completed work. A prompt by itself is a request; an
+explicit result, receipt, or artifact supports completion. Focus on outcomes and progress, not
+tool ratios or technical details.
+
+### {Theme 1} (AM 09:36~11:30)
+- Core work performed
+- Key decisions
+- 2-4 bullets per theme
+
+### {Theme 2} (PM 13:33~15:21)
+- Core work performed
+- Key decisions
+
+### Miscellaneous
+- Brief summary of sub-15-minute tasks
+
+### Tool Usage Patterns
+- Tool usage ratios and primary purposes
+- Notable tool-switching patterns
+```
+
+## Multi-day format (3d, 7d, 2w, 30d)
+
+For any multi-day window, use a **project-driven structure** like a sprint report.
+Focus on what was accomplished per project, not day-by-day chronology.
+
+```markdown
+## {start} ~ {end} Recap
+
+> **TL;DR**
+> - {Completed outcome, only with completion evidence}
+> - {In-progress or requested work, labelled with its status when completion is unproven}
+> - {Another supported outcome or status}
+
+### Overview
+3-5 sentence narrative of the period. Major focus shifts across the window,
+key milestones achieved, and overall direction. Written from "I did X" perspective.
+
+### {Project A}
+What this project is, with requested, in-progress, and completed work distinguished by evidence.
+- Key milestone or deliverable 1
+- Key milestone or deliverable 2
+- Key decision made
+- Current status (shipped / in progress / blocked)
+
+### {Project B}
+- ...
+
+### Side Projects
+Projects with <30 prompts, summarized briefly.
+- {project}: one-line summary
+- {project}: one-line summary
+
+### Tool Usage Patterns
+- Tool usage ratios and how they evolved over the period
+- Notable shifts (e.g., "started using Codex midway through the period")
+```
+
+## Multi-day grouping rules
+
+- Group by **project**, not by date
+- Order projects by activity volume (most active first)
+- Each project section: what it is, supported outcomes, key decisions, and current status
+- Do NOT include prompt counts or date ranges in project headers (those are internal metrics)
+- Small projects (<30 prompts) go into "Side Projects" as one-liners
+- Overview should read like a sprint report narrative, not a log

package/skills/oma-refactor/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: oma-refactor
+description: Restructure existing code while preserving observable behavior. Use
+  for targeted technical debt or hotspot work with characterization tests.
+---
+
+# Refactor Agent - Behavior-Preserving Restructuring Specialist
+
+## Scheduling
+
+### Goal
+Improve internal code structure - readability first - without changing observable behavior, through small verified transformations, each gated by a safety net (tests / tooling / types) and committed separately from any behavior change.
+
+### Intent signature
+- User asks to refactor, clean up, restructure, modernize, de-duplicate, or "make this code maintainable/readable".
+- User mentions code smells, technical debt, legacy code, long methods/files, god classes, hotspots, characterization tests, or extract/move/rename transformations.
+- User asks "where should we refactor first?" or wants a refactoring plan/priority for a codebase.
+
+### When to use
+- Executing a refactoring on specific files/modules (extract, move, rename, decompose, pattern/idiom alignment)
+- Preparatory refactoring before a feature ("make the change easy, then make the easy change")
+- Legacy (brownfield) rescue: seam discovery + characterization tests, then restructuring
+- Refactoring target selection and prioritization (smells + SATD + hotspot = churn x complexity)
+- Auditing whether code is safe to refactor now (coverage breadth x mutation strength x flakiness)
+
+### When NOT to use
+- Adding or completing behavior already requested by the user -> use the appropriate existing implementation skill; classify the scope under Entry first.
+- Fixing a reported bug or failing behavior -> use `oma-debug` (refactoring must not change behavior)
+- Security/performance/accessibility review or quality audit -> use `oma-qa`
+- System design, module boundary decisions, ADRs, convention changes -> use `oma-architecture` (a convention/pattern change is an architecture decision, not a local refactoring)
+- DB schema design or migration mechanics -> use `oma-db` (this skill only plans the expand-contract sequence)
+- Commit splitting / staging mechanics -> use `oma-scm`
+- Performance optimization as a goal -> out of scope by definition (tuning is a side effect, never the objective)
+
+### Expected inputs
+- `target`: file/module/path, smell report, SATD marker, or the feature request motivating preparatory refactoring
+- `verification`: existing project test command(s); coverage/mutation tooling if already available
+- `constraints`: coding guide / conventions, regulated-environment flags, merge-window concerns
+- Optional: prior metric reports, hotspot data, ADRs touching the target area
+
+### Expected outputs
+- Refactored code as a sequence of atomic, refactor-only commits (no test changes mixed in)
+- Safety-net additions when missing (characterization / golden-master tests) as separate commits
+- Before/after report: metric delta (cyclomatic/cognitive complexity, size, coupling) + readability verdict
+
+```yaml
+outputs:
+  - name: report
+    description: refactoring plan or before/after report
+    artifact: ".agents/results/refactor/*.md"
+    required: false
+```
+
+Standalone runs write plan / before-after reports under `.agents/results/refactor/`; orchestrated runs (via the `refactor-engineer` agent) write `.agents/results/result-refactor[-{sessionId}].md` per the agent execution protocol.
+
+### Dependencies
+- `resources/definition.md` (invariant definition: 5 properties, boundaries, destination principle, naming roles, inline evidence)
+- `resources/measurement.md` (4-layer measurement + git forensics commands)
+- `resources/governance.md` (optional organization conventions and existing verification tools)
+- Configured code-intelligence symbol/reference tools; existing project test runners for the target language
+- Git history for churn/ownership/hotspot analysis
+
+### Control-flow features
+- Branches by safety-net state (greenfield vs brownfield), statefulness (code-only vs expand-contract), and verification outcome (pass vs Mikado revert)
+- Reads code/history/metrics; writes code, tests (in separate commits), and reports
+- Stops and routes to `oma-architecture` when the change requires a convention/boundary decision
+
+## Structural Flow
+
+### Entry
+1. Classify the requested outcome against the actual target code, not the word "refactor" alone. Behavior-preserving restructuring stays here. Implementation or bug fixing already included in the request continues under the appropriate existing implementation skill or `oma-debug`, within existing authorization and without renewed approval. For mixed requests, separate behavior changes from restructuring and apply this skill only to the latter.
+2. For the refactoring scope, establish its motivation and diagnose the safety net: coverage of changed lines, test determinism (flakiness), mutation strength if measurable.
+3. Identify the destination form: the language idiom and codebase convention the result must match.
+
+Missing or stub code does not itself authorize new behavior. A pure refactor with
+no implementation to restructure reports the missing target rather than inventing
+one. If a contract fact needed for correctness remains unknown after checking
+available task and project evidence, ask for that specific fact under the shared
+execution policy and clarification protocol. Distinguish missing
+information from missing authorization: retain existing permission, pause only
+dependent work, and continue independent authorized work.
+
+### Scenes
+1. **PREPARE**: Within the refactoring scope, classify greenfield (safety net exists) vs brownfield (build net first); check size gates and hotspot rank; confirm two-hats scope (no feature/bug work mixed in).
+2. **ACQUIRE**: Read target code via symbol tools; collect metrics (complexity, size, coupling) and git signals (churn, ownership); read the coding guide for conventions.
+3. **REASON**: Decompose the goal into a sequence of named atomic transformations; for stateful targets plan expand-contract; verify each step is independently verifiable and revertible.
+4. **ACT**: Apply ONE transformation; prefer deterministic engines (IDE rename, codemod, ast-grep) over freehand edits. When one feature spans several files after a split, consider G-5's optional header map if it helps navigation.
+5. **VERIFY**: Re-run existing tests unchanged. Pass -> commit (refactor-only) -> next transformation. Repeated failure -> Mikado: record the broken prerequisite, undo only this transformation's edits, recurse on the prerequisite first. Preserve pre-existing edits and other contributors' work.
+6. **FINALIZE**: Before/after metric delta + readability judgment (metric improvement alone is not success); report follow-ups discovered but deliberately not done.
+
+### Transitions
+- If the safety net is missing or weak (low diff coverage, flaky, no assertions), write characterization / golden-master tests FIRST, committed separately, before touching production code.
+- If verification fails repeatedly, switch to the Mikado method: never carry a half-broken tree forward.
+- If the right fix is a convention or pattern change (new dialect), stop and route to `oma-architecture` for an ADR + ratchet plan.
+- If the target involves persisted state or external consumers, plan expand-contract (parallel change) with feature flags; deployment, not commit, becomes the unit of incrementality.
+- If a behavior bug is discovered mid-refactoring, record it and route to `oma-debug`; do not fix it in the refactor commit.
+- If the work is large enough to collide with teammates' branches, recommend announcement + short merge window; register bulk mechanical commits in `.git-blame-ignore-revs`.
+
+### Failure and recovery
+| Failure | Recovery |
+|---------|----------|
+| Tests fail after a transformation | Mikado: record prerequisite, undo only this transformation's edits, preserve unrelated work, attack prerequisite first |
+| No tests and code is untestable | Find a seam; apply only minimal mechanical changes to inject test access, then characterize |
+| Tests are flaky | Fix or quarantine flaky tests before refactoring - an unreliable net is no net |
+| Metric improves but readability worsens | Reject the transformation; readability is the success criterion, metrics are proxies |
+| Scope keeps growing | Stop; report the boundary issue and split into a Mikado graph or route to architecture |
+| Refactoring engine/codemod produces wrong output | Engines are not infallible - tests re-run is mandatory; fall back to manual atomic edits |
+
+### Exit
+- Success: behavior verified unchanged, structure measurably improved, readability confirmed, refactor-only commits, follow-ups reported.
+- Partial success: safety net built but restructuring deferred; or prerequisites mapped (Mikado graph) with explicit blockers.
+- Handoff: already-requested implementation or bug fixing continues under its owning skill's completion criteria; changing skills is not a task failure.
+- Blocked or failed: report the exact missing contract, verification path, or required decision and the dependent work it prevents, plus independent work completed. A pure refactor with no target reports that limit without inventing behavior.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Diagnose safety net | `VALIDATE` | Coverage/flakiness/mutation state of target scope |
+| Collect signals | `READ` | Metrics, git churn/ownership, smells, SATD |
+| Rank targets | `COMPARE` | Hotspot = complexity x churn |
+| Plan atomic sequence | `INFER` | Named transformations, Mikado graph |
+| Write characterization tests | `WRITE` | Golden-master/snapshot tests (separate commit) |
+| Apply transformation | `WRITE` / `CALL_TOOL` | One atomic refactor, engine-first |
+| Verify preservation | `VALIDATE` | Existing tests re-run unchanged |
+| Commit separately | `UPDATE_STATE` | `refactor:`-typed commits only |
+| Report delta | `NOTIFY` | Metric + readability before/after |
+
+### Tools and instruments
+- Configured code intelligence for symbol/reference/pattern impact analysis; an available semantic rename engine for renames. Native inspection remains valid, but do not replace a semantic rename with blind text replacement
+- Deterministic transformers: IDE refactoring actions, codemods (jscodeshift / OpenRewrite / ast-grep / comby)
+- Metrics: use already installed complexity tools such as lizard / radon and existing project lint limits; installing or downloading additional tools requires authorization
+- Test stack: preserve the project runner and configuration; use mutation tooling only when available and appropriate (see `resources/governance.md`)
+- Git forensics one-liners (see `resources/measurement.md`)
+
+### Canonical workflow path
+1. Apply Entry's scope routing first. For the remaining refactoring scope, run coverage and check test determinism; classify green/brownfield.
+2. If brownfield: find a seam, write characterization (golden-master) tests for CURRENT behavior, commit.
+3. Select targets by hotspot rank (complexity x churn), not by smell aesthetics alone.
+4. Plan a sequence of named atomic transformations toward the language-idiomatic, convention-conforming form.
+5. Loop per transformation: apply (engine-first) -> re-run tests UNCHANGED -> commit `refactor:` only.
+   On repeated failure: record prerequisite, undo only this transformation's edits,
+   preserve pre-existing and concurrent work, recurse (Mikado).
+6. Finish: metric delta + readability verdict; list discovered-but-deferred work; never mix in behavior changes.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `CODEBASE` | Target source, tests, coding guide, lint configs |
+| `LOCAL_FS` | Reports under `.agents/results/refactor/`, `.git-blame-ignore-revs` |
+| `PROCESS` | Test runners, coverage/mutation tools, codemod engines, git log analysis |
+| `MEMORY` | Mikado prerequisite graph, deferred follow-ups, metric baselines |
+
+### Preconditions
+- A verification path exists or can be built (tests/types/tooling); otherwise the first deliverable is the safety net, not restructuring.
+- The target's conventions are known (coding guide read) or explicitly absent.
+
+### Effects and side effects
+- Mutates production code (structure only) and adds tests in separate commits.
+- Runs test/coverage/mutation commands; reads git history.
+- May write reports under `.agents/results/refactor/` and entries to `.git-blame-ignore-revs`.
+- Never alters observable behavior, public contracts, or persisted data without an expand-contract plan.
+
+### Guardrails
+1. **Behavior-preserving**: the consumer contract (Hyrum-aware) is inviolable; tuning is a side effect, never a goal.
+2. **Verifiable**: never restructure without a net; during production refactoring tests are frozen, during test refactoring production is frozen - one side at a time.
+3. **Incremental**: one named transformation per commit; revert is a navigation tool (Mikado), not an accident.
+4. **Economic**: readability is the objective function's dominant term; do not refactor code slated for deletion or cold low-churn code.
+5. **Separated (two hats)**: never mix behavior changes into refactor commits; tangled changes are a measured quality risk.
+6. Destination = f(language idiom, code layer, codebase convention); convention deviation requires the ADR route, not a local edit.
+7. Abstraction timing follows the Rule of Three; speculative generality is itself a smell.
+8. All metrics are proxies (Goodhart): a 499-line mechanical split, assertion-free coverage, or pattern-count gains are failures, not wins.
+
+## References
+- Local code tools: `../_shared/core/code-intelligence.md` (code search/navigation)
+- Authorization and contract ambiguity: `../_shared/core/execution-policy.md` and `../_shared/core/clarification-protocol.md` (when clarification or authorization is needed)
+
+- Invariant definition (5 properties, boundaries, destination, naming roles, contexts, D&C, inline evidence): `resources/definition.md`
+- Measurement: 4 layers + git forensics commands: `resources/measurement.md`
+- Optional organization conventions and existing verification tools: `resources/governance.md`
+- Context loading: `../_shared/core/context-loading.md`
+- Quality principles: `../_shared/core/quality-principles.md`
+- Adjacent skills: `oma-debug` (bugs), `oma-qa` (audits), `oma-architecture` (boundaries/ADR), `oma-db` (schema), `oma-scm` (commits)

package/skills/oma-refactor/resources/definition.md

@@ -0,0 +1,108 @@
+# Refactoring - Invariant Definition
+
+Use `governance.md` for organization-specific parameters.
+
+## Core definition
+
+Refactoring is the act of improving a system's internal structure toward its codebase's conventional form - without changing externally observable behavior (the contract its consumers depend on) - through small, revertible, named transformations whose behavior preservation is mechanically verifiable, in order to lower the future cost of change, whose dominant term is human comprehension cost.
+
+## The five mandatory properties
+
+If any property is missing, the activity is not refactoring.
+
+| # | Property | Meaning | Without it |
+|---|----------|---------|------------|
+| 1 | Behavior-preserving | Consumer contract unchanged | Feature change / redesign |
+| 2 | Verifiable | Preservation guaranteed by tests/tools/types | Risky edit |
+| 3 | Incremental | Composition of small named transformations | Rewrite |
+| 4 | Economically motivated | Lowers future change cost (~= comprehension cost) | Vanity polishing |
+| 5 | Separated | Never mixed with behavior changes in a commit | Unreviewable tangle |
+
+### 1. Behavior preservation - the boundary is contractual, not technical
+- Preserved: input/output equivalence, public interface semantics, the *meaning* of side effects (records written, events emitted).
+- Not preserved: internal call order, private structure, stack-trace shape.
+- Gray zone (performance, log format, serialization): judged by **Hyrum's Law** - if someone actually depends on it, it is part of the contract.
+- Performance (tuning) is allowed only as a side effect, never as the goal. If performance is contractual (SLA, real-time), preserve it too.
+- Preservation is necessary but not sufficient: behavior can be preserved while readability worsens - that is a failed refactoring. (Empirical: LLM refactorings preserved behavior ~84% yet worsened readability in ~71% of cases while static metrics improved.)
+
+### 2. Verifiability - the precondition
+Guarantee mechanisms: (a) test suite - tests are FROZEN during refactoring; a failing test means behavior changed; (b) deterministic tool transformations - engines have bugs too (refactoring-engine bug studies exist), so re-run tests anyway; (c) type system / compiler; (d) differential testing and semantic equivalence checking (e.g., execution-driven differential testers, equivalence checkers).
+- Symmetry rule: refactor production with tests frozen; refactor tests with production frozen. One side at a time.
+- "Test failed = behavior changed" holds only for deterministic tests. Flaky tests destroy the signal itself.
+- When no net exists: write **characterization tests** (pin CURRENT behavior, bugs included - Hyrum). Practical form: golden-master / approval / snapshot tests.
+
+### 3. Incrementality - an open catalog
+Composition of named transformations (Extract Function, Move Method, Rename, ...). Small enough to verify instantly, revert instantly, and review confidently. The standard catalog names only a fraction of real-world behavior-preserving changes (detector studies explain ~20% of real changesets with the standard catalog alone) - the test is the five properties, not catalog membership. Compound refactorings are where automated agents fail most; decompose to atomic steps.
+
+### 4. Economics - readability is the dominant term
+`change cost = comprehension cost + ripple cost + verification cost`. Most developer time goes to comprehension, so readability (analysability) is the primary objective; coupling-driven ripple radius (modifiability) is the second, independent lever.
+- Cognitive grounding: refactoring removes extraneous cognitive load; working-memory limits (chunking) justify small units; naming is the largest readability lever no metric measures.
+- Debt vocabulary: Cunningham's debt metaphor is a communication device for non-engineers (interest = ongoing cost, principal = structural flaw). Fowler's quadrants (deliberate x prudent) split the prescription: prudent-deliberate debt is a repayment-planning problem; reckless-inadvertent debt is an education problem.
+
+### 5. Separation - two hats
+Never wear the feature hat and the refactoring hat simultaneously; mixed (tangled) commits make preservation unreviewable and are a measured quality risk (tangled refactorings in agent patches significantly reduce compilability). This is why `refactor` is a distinct commit type. Separation governs commits, not budgets - preparatory refactoring embedded in feature work is part of that feature's cost.
+
+## What refactoring is NOT
+Bug fixing (intentional behavior change) / performance optimization (different goal, often anti-readability) / feature addition / rewrite (wholesale replacement without stepwise verification) / API-breaking change (= redesign/migration). Lifecycle home: ISO/IEC/IEEE 14764 perfective/preventive maintenance. Edge case: cross-language migration can satisfy all five properties but is conventionally named "migration".
+
+## When NOT to refactor
+- Code about to be deleted or replaced (zero economics)
+- Cold, low-churn stable code (touching it is pure risk)
+- Right before a release (risk asymmetry: gains are future, risk is now)
+- Without a safety net (build the net first)
+- Know the risk: a fraction of refactorings induce defects and security regressions (both empirically documented); the five properties reduce risk, they do not zero it.
+- Rewrite is right only when incremental-migration total cost exceeds rewrite + full re-verification cost (include feature-freeze cost and second-system risk in the comparison).
+
+## Triggers
+- Code smells (qualitative heuristics: duplication, Long Method - long *body*, god class, Feature Envy, Shotgun Surgery, Speculative Generality): signals that change cost is rising, not defects.
+- SATD (self-admitted technical debt): TODO/HACK/FIXME in comments/issues - a third signal independent of structure and history. Do not let the *tone* of the admission drive priority (negativity measurably skews developer prioritization even though most consider it wrong).
+
+## Destination - one principle, three axes
+**Reusability = context independence.** Every pattern is a named technique for severing one kind of context dependency (Strategy: host vs algorithm; Facade: consumer vs subsystem internals; Adapter: new context vs existing interface; DI: unit vs dependency construction). Pure functions reduce implicit context dependencies.
+
+**Pattern choice = f(language expressiveness, code layer, codebase convention):**
+- Language axis: patterns compensate for what the language cannot express (Norvig: most GoF patterns evaporate into idioms). The destination is the language's idiom, not a GoF diagram.
+- Layer axis: functional core vs imperative shell call for different forms and different test economics.
+- Convention axis: in brownfield, the coding guide and framework conventions beat "theoretically better" patterns - consistency is a component of analysability. Changing a convention is an architecture decision (ADR + lint ratchet for new code + module-wise migration), never a boy-scout edit.
+- Timing: Rule of Three - abstract after reuse evidence accumulates; speculative generality is a smell.
+
+## Naming - operationalizing the unmeasured lever
+
+Rename is the only core transformation with no metric gate; its gate is qualitative: does the new name reveal the entity's **role** and **domain meaning** to the next reader? For variables, Sajaniemi's role taxonomy makes that question checkable (11 roles cover ~99% of variables in procedural/OO code): first identify the role, then verify the name exposes it.
+
+| Role | Behavior | Naming cue |
+|------|----------|-----------|
+| Fixed value | Set once, read thereafter | `maxRetries`, `basePath` |
+| Stepper | Walks a predictable succession | `attempt`, `pageIndex` |
+| Flag | Two-state signal controlling flow | `isStale`, `hasOverflow` |
+| Walker | Traverses a data structure | `cursor`, `currentNode` |
+| Most-recent holder | Latest value seen so far | `lastError`, `currentLine` |
+| Most-wanted holder | Best value found so far | `closestMatch`, `maxSoFar` |
+| Gatherer | Accumulates across values | `total`, `mergedDiff` |
+| Container | Elements enter and leave | `pendingJobs`, `seenIds` |
+| Follower | Previous value of another variable | `prevNode` |
+| Organizer | Holds data being rearranged | `sortedCopy` |
+| Temporary | Held briefly (swap/reuse) | `tmp` - acceptable ONLY in this role |
+
+Rename discipline:
+- Generic names (`data`, `result`, `temp`, `value`) outside the temporary role fail the role check; lying names (name promises X, body does Y) outrank them as targets.
+- One variable, one role: a variable that switches roles mid-scope is a **Split Variable** trigger, not a rename target.
+- Functions are named for intent (what), not mechanism (how); command = verb, query = noun/predicate.
+- Renames are engine-executed (LSP/IDE rename or a configured provider’s semantic rename tool), never find-replace; tests re-run regardless.
+- Goodhart applies here too: role vocabulary diagnoses; the terminal check is still "does the next reader understand this cheaper".
+
+## Execution contexts
+- **Greenfield**: refactoring is the third beat of TDD (Red -> Green -> Refactor) - minute-scale hygiene, net already exists.
+- **Brownfield**: order inverts - find a seam (minimal mechanical change to enable testing) -> characterization tests -> restructure. Large scale: Strangler Fig, Branch by Abstraction, Sprout Method - the system stays working at every point. The classification is per code fragment (coverage map), not per project.
+- **Stateful (data/API)**: git revert does not restore data. Mechanism: **Expand-Contract (parallel change)** - expand (old+new coexist) -> dual-write + backfill -> switch reads -> contract (remove old); feature flags are the standard switch. External consumers: semver + deprecation cycles as a staged contract-transfer protocol; the pattern vocabulary for that staging (Version Identifier, Two in Production, Aggressive Obsolescence, Limited Lifetime Guarantee - MAP evolution patterns, Zimmermann et al.) lives with `oma-architecture` (`resources/api-evolution.md`) - a published-contract change is an architecture decision, route there for the ADR.
+- **Team concurrency**: big renames collide with every open branch - another reason for "small and frequent". Announce large refactorings + short merge windows; register bulk mechanical commits in `.git-blame-ignore-revs`; LSC (monorepo-wide atomic change + owner-split review) is incrementality at org scale.
+- **Regulated environments**: even behavior-preserving changes trigger re-verification/re-certification - economics invert; batch-per-release refactoring is the one legitimate exception to "continuous flow".
+
+## Architectural principle - refactoring enables divide and conquer
+Functional core / imperative shell: pure-core unit tests cost ~0 and assert maximally -> "every step gets a unit test" is the rational default there; the shell gets few integration/contract tests. The test pyramid is D&C's verification form (unit = conquer, contract/integration = combine, E2E = divide). "All units pass therefore the system works" is the composition fallacy. Expensive, mock-heavy unit tests diagnose a failed decomposition - i.e., a refactoring target. Reusability and testability are the same coin: a test is the code's second consumption context.
+
+## Goodhart - every metric is a proxy
+Complexity targets -> mechanical splits; coverage KPIs -> assertion-free tests; size gates -> boundary-dodging splits; pattern counts -> speculative generality; git metrics -> commit-habit gaming; SATD tone -> priority distortion. Metrics diagnose; they do not replace qualitative judgment on what they cannot see (bad names, wrong abstraction level, missing domain concepts). The only terminal criterion: **can the next person understand and change this code more cheaply?**
+
+## Standards anchors
+ISO/IEC 25010 (maintainability - analysability is the standard vocabulary for the readability thesis) | ISO/IEC/IEEE 14764 (perfective/preventive) | ISO/IEC 25023, 5055 (automated measures) | ISO/IEC/IEEE 29119-4 (test design techniques, coverage criteria incl. MC/DC) | ISO 26262 / DO-178C (risk-tiered coverage; re-certification implications) | ISO/IEC 25051 (successor of withdrawn 12119). Standards are anchors for the doctrine, not its content.

package/skills/oma-refactor/resources/governance.md

@@ -0,0 +1,33 @@
+# Refactor Governance
+
+Use the target project's documented conventions. These examples do not create
+organization policy or change the authority of repository instructions.
+
+## G-1. Budget
+Use an agreed refactoring budget when the organization has one. A small scoped
+refactor does not require introducing a capacity floor or measurement platform.
+
+## G-2. Budget usage
+Distinguish preparatory work required by a feature from separately planned debt
+repayment when the project tracks those costs.
+
+## G-3. Outcomes
+Use measured delivery, reliability and maintenance outcomes to adjust an adopted
+budget in either direction. Do not infer fixed cost percentages without evidence.
+
+## G-4. Metrics
+Select work by observed change difficulty and defects. Metrics support decisions;
+they do not require splitting code or spending a fixed quota.
+
+## G-5. File size
+Follow an existing size gate if present. File length is a review signal; split by
+responsibility when that improves navigation and coupling. Do not add a 500-line
+CI gate or demand an ADR for an unrelated scoped edit. For a useful split map,
+keep a short entry-file comment listing related paths and roles current.
+
+## G-6. Test tools
+Use the repository's existing test runner and coverage commands, including Jest,
+Vitest, unittest, pytest, XCTest, Swift Testing, cargo test, or go test as applicable.
+An unlisted language does not block refactoring or require an ADR. Add coverage or
+mutation instrumentation only when relevant to the task and available in the
+project; a runner migration is separate work.

package/skills/oma-refactor/resources/hotspots.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Join Git churn and installed lizard output without interpreting file names."""
+import argparse
+from collections import Counter
+from pathlib import Path
+import shutil
+import subprocess
+
+def churn(repo, since="1 year ago"):
+    prefix = ["git", "-C", str(repo)]
+    commits = subprocess.run(prefix + ["log", "--format=%H", f"--since={since}"],
+                             check=True, capture_output=True, text=True).stdout.splitlines()
+    counts = Counter()
+    for commit in commits:
+        result = subprocess.run(prefix + ["diff-tree", "--root", "--no-commit-id",
+                                          "--name-only", "--no-renames", "-r", "-z", commit],
+                                check=True, capture_output=True)
+        counts.update(p.decode("utf-8", "surrogateescape")
+                      for p in result.stdout.split(b"\0") if p)
+    return counts
+
+def measure(repo, relative_path, tool):
+    path = (repo / relative_path).resolve()
+    if not path.is_relative_to(repo.resolve()) or not path.is_file():
+        return None
+    # An absolute path is one argv entry, including spaces/newlines/$()/leading '-'.
+    return subprocess.run([tool, "-C", "999", str(path)],
+                          check=True, capture_output=True, text=True).stdout
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    parser.add_argument("--limit", type=int, default=30)
+    args = parser.parse_args()
+    tool = shutil.which("lizard")
+    if not tool:
+        parser.error("lizard is not installed; report that measurement is unavailable")
+    for path, count in churn(args.repo).most_common(args.limit):
+        output = measure(args.repo, path, tool)
+        if output is not None:
+            print(f"changes={count} path={path!r}\n{output}")
+
+if __name__ == "__main__":
+    main()

package/skills/oma-refactor/resources/measurement.md

@@ -0,0 +1,93 @@
+# Measurement - Four Layers + Commands
+
+> Operationalizes target selection and effect verification. All values are diagnostic proxies (Goodhart) - never evaluation KPIs.
+
+## Layer 1 - Static structure: "where change is hard"
+
+| Metric | Reading | Thresholds |
+|--------|---------|-----------|
+| McCabe V(G) = E - N + 2P (~ branch points + 1) | Number of independent paths; not a branch-coverage minimum | <=10 ok / 11-20 caution / 21-50 high risk / 50+ investigate risk |
+| Cognitive Complexity | Human reading difficulty (nesting-weighted) | Primary indicator for the readability objective |
+| CK suite (CBO, LCOM, WMC) | Coupling/cohesion at class/module boundary | Triggers for Move/Extract Class |
+| Duplication % | Token/AST clone ratio | Duplicate Code smell, quantified |
+
+```bash
+# Use installed project tools; uvx can download packages and is not install-free.
+# Python
+radon cc -s -a <path>      # cyclomatic
+lizard <path>              # multi-language CC + NLOC + params
+# Any language with lizard support
+uvx lizard -l <lang> --CCN 10 <path>
+```
+
+## Layer 2 - Git forensics: "where change actually happens"
+
+```bash
+# High-churn files (exclude lock/generated noise)
+git log --format=format: --name-only --since="1 year ago" \
+  | grep -vE '(^$|lock|generated|\.snap|\.min\.)' | sort | uniq -c | sort -nr | head -20
+
+# Bug hotspots (message-quality dependent; approximate is still useful)
+git log -i -E --grep="fix|bug|broken" --name-only --format='' \
+  | grep -v '^$' | sort | uniq -c | sort -nr | head -20
+
+# Ownership / bus factor (squash merges distort this)
+git shortlog -sn --no-merges
+
+# Velocity trend (interpret as trend only, never absolute)
+git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c
+
+# Firefighting signal (safety-net trust diagnosis)
+git log --oneline --since="1 year ago" | grep -icE 'revert|hotfix|emergency|rollback'
+```
+
+Corrections: use `--follow` for single-file rename history; register bulk mechanical commits in `.git-blame-ignore-revs`; squash merges flatten authorship.
+
+**+ SATD signal** (admitted debt, independent of structure and history):
+
+Use the configured code provider's content search for `TODO|FIXME|HACK|XXX`
+within source files. Count findings per file without bypassing the project's code
+search policy. Treat self-admitted debt as a signal, not a required refactor.
+
+## Layer 3 - Hotspot: "what to fix first"
+
+`hotspot = complexity (L1) x change frequency (L2)` - the quantified form of the economic property and the budget's spending rank.
+
+Use [hotspots.py](hotspots.py) from the repository root with an already-installed
+`lizard`. The helper preserves Git paths using NUL delimiters and passes each path
+as a subprocess argument. It never interpolates a filename into shell code or
+installs a measurement tool.
+
+```bash
+python3 <skill-directory>/resources/hotspots.py --repo . --limit 30
+```
+
+If lizard is unavailable, report that measurement gap rather than downloading it
+as part of a scoped refactor.
+
+## Layer 4 - Safety-net instrumentation: "where refactoring is safe NOW"
+
+`net = breadth x strength x reliability` - if any factor is zero, there is no net.
+
+| Dimension | Metric | Notes |
+|-----------|--------|-------|
+| Breadth | Coverage (statement < branch < condition < MC/DC) | Coverage measures *executed*, not *verified*. Prefer diff coverage gates over global targets |
+| Strength | Mutation score (PIT / StrykerJS / mutmut) | The true measure of "will the net catch a behavior change" |
+| Reliability | Flakiness rate | Non-deterministic tests destroy the "failure = behavior changed" signal; fix or quarantine first |
+
+```bash
+# Per-registry commands (see governance.md for the registry)
+vitest run --coverage              # TS/JS breadth
+stryker run                        # TS/JS strength
+pytest --cov=<pkg> --cov-report=term-missing
+mutmut run                         # Python strength
+flutter test --coverage           # Dart breadth (strength gap: compensate with assertion review)
+```
+
+Tier by layer: dense unit tests on the pure core, few integration/contract tests on the shell, MC/DC only for safety-critical modules.
+
+When the net is missing, LLM-assisted test generation is viable for seeding characterization suites - prefer approaches guided by coverage or mutation feedback, and review generated assertions manually (generation quality is bounded by the feedback signal).
+
+## Outcome accounting (org level)
+
+Budget effectiveness closes with DORA: deployment frequency, change lead time, change failure rate, MTTR. Investment hypothesis: structural improvement -> lead time down + change failure rate down. Review budget consumption alongside DORA trends quarterly; Layer-2 signals are proxies, DORA is the outcome.