DongHyeonkaandClaude Opus 5
b2963105a8
The keycloak project ended with four open questions that design could not
settle. A two-VM lab was built to answer them by measurement, and this is
that material: 26 experiments, 125 raw command outputs, 22 browser captures.
Follows the import procedure in README.md.
source/ the originating repository verbatim — 78 documents, 28 SVGs,
8 manifests, plus .source-revision recording the commit
final/ the SSOT
document.md 729 lines written from the 29 experiment documents, not
concatenated: what was predicted, what was measured, and
where the measurement itself was wrong
evidence/raw 125 outputs, flattened to <experiment>__<file> because
the originals collided (01-baseline.txt appeared three
times) and the audit only globs the top level
evidence/meta one per raw file; command and exitCode are null and the
README says why rather than inventing them
evidence/browser 22 captures
assets/ three diagrams through techviz
.techviz/ their VizSpecs
A separate project rather than an addition to keycloak: the B-layer answers
that project's four questions, but the A, C and D layers are about cluster
failure, SSO and operations, and one document.md should hold one subject.
The four question records there can point here through 관계.
Recorded rather than papered over: only three of the 28 diagrams were
remade. The repository forbids hand-drawn SVG and forbids titles inside the
canvas; all 28 originals carry both, so converting them is redrawing, not
reformatting. They stay in source/ and the gap is written into the document.
verify-pipeline.py passes. audit-records.py reports no issues.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
97 lines
4.1 KiB
Markdown
97 lines
4.1 KiB
Markdown
# 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.
|