Files

T

DongHyeonkaandClaude Opus 5 b2963105a8 docs(keycloak-session-store): import the session-storage lab as a new project

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>

2026-09-04 22:51:59 +09:00

4.1 KiB

Raw Blame History

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

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.
Findings from document-detail become bounded WorkItems. Queue order is controlled by priority, while type and scope determine execution and verification strategy.
Each WorkItem is implemented in an isolated Git worktree/branch, never directly in the analysis source checkout.
Verification evidence is retained under /shared/refactor-detail/<project>/<work-item>/.
An item cannot reach WAITING_APPROVAL unless the evidence contract for its type is satisfied.
Approved merged refactors cause the analysis queue entry to become REANALYZE; human-authored repository changes remain an explicit reanalysis decision.

Durable layout

/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.

4.1 KiB Raw Blame History