# Refactoring From Analysis Design

## Goal

Use completed `/shared/document-detail/<project>` analysis as the planning context for bounded refactoring, while keeping current application source as the SSOT and retaining verifiable evidence for every change.

## Core pipeline

1. Only an analysis snapshot whose queue state is `COMPLETE`, whose recorded revision equals the current repository HEAD, and whose working tree is clean may feed refactoring.
2. Findings from `document-detail` become bounded WorkItems. Queue order is controlled by priority, while `type` and `scope` determine execution and verification strategy.
3. Each WorkItem is implemented in an isolated Git worktree/branch, never directly in the analysis source checkout.
4. Verification evidence is retained under `/shared/refactor-detail/<project>/<work-item>/`.
5. An item cannot reach `WAITING_APPROVAL` unless the evidence contract for its type is satisfied.
6. Approved merged refactors cause the analysis queue entry to become `REANALYZE`; human-authored repository changes remain an explicit reanalysis decision.

## Durable layout

```text
/shared/codebase/refactor-queue.yaml
/shared/refactor-detail/<project>/<work-item>/
├── work-item.json
├── plan.md
├── evidence/
│   ├── environment.md
│   ├── baseline/raw/
│   ├── after/raw/
│   └── comparison.md
├── verification/
└── diff/
```

The queue carries ordering/state summaries. `work-item.json` is the detail SSOT for the refactor item. `document-detail` is context; current code is source truth.

## WorkItem fields

Every item records: id, project, analysisRevision, priority, type, scope, target, status, problem, goal, acceptanceCriteria, and evidence references.

Allowed initial type taxonomy:

- `PERFORMANCE`
- `CODE_STRUCTURE`
- `MODULE_STRUCTURE`
- `ARCHITECTURE`
- `DATA_ACCESS`
- `RELIABILITY`
- `CONCURRENCY`
- `TRANSACTION`
- `SECURITY`
- `OPERABILITY`
- `CONFIGURATION`
- `DEPENDENCY`
- `BUILD`
- `TESTABILITY`
- `CLEANUP`

Allowed scopes: `LOCAL`, `MODULE`, `CROSS_MODULE`, `PROJECT`.

Priority determines order (`P0`..`P3`, then queue order). Type/scope never replace priority; they select the verification contract.

## Performance hard gate

A `PERFORMANCE` WorkItem must define its measurement contract before source modification:

- exact measurement command or reproducible procedure;
- environment evidence path;
- dataset/load fixture identifier;
- metrics to compare;
- acceptance criteria.

The baseline must be captured before the refactor. After the change, the same measurement contract must be used. Before `WAITING_APPROVAL`, retained evidence must include:

- raw baseline output;
- raw after output;
- environment record;
- `comparison.md` containing before/after values, delta, conditions, and acceptance result.

If equivalent conditions cannot be reproduced, the item is `BLOCKED`; no improvement claim is allowed.

## Type-directed verification

- `PERFORMANCE`: baseline + after measurement + comparison + functional regression checks.
- `BUILD`: baseline/after build measurement when improvement is claimed, plus build correctness.
- `ARCHITECTURE`, `MODULE_STRUCTURE`, `DEPENDENCY`: dependency graph/architecture rules/build/integration evidence as applicable.
- `DATA_ACCESS`, `TRANSACTION`, `CONCURRENCY`, `RELIABILITY`: representative integration/contract/failure-path evidence; concurrency or failure injection where the claim depends on it.
- `SECURITY`: security regression tests/configuration/negative-path evidence without storing secrets.
- `CODE_STRUCTURE`, `CLEANUP`, `TESTABILITY`, `CONFIGURATION`, `OPERABILITY`: behavior-preserving tests plus references/build/runtime checks appropriate to the item.

All types retain the commands and raw verification outputs used to justify completion.

## Safety

- Never refactor an analysis snapshot that is stale or dirty.
- Never fabricate benchmark output, runtime evidence, or before/after comparisons.
- Never weaken or delete a failing test merely to make a refactor pass.
- Never store secrets in evidence.
- Large goals must be decomposed into reviewable WorkItems; one scheduled execution works on at most one item.