[docs](adr): interim-ratify D4/D5 qaFit and preset calibration (closes OI-2, OI-4)

Establish the model-decision log (docs/adr/, per charter Section 14.4/14.5) and
record the interim ratification of the two open model-value items. No Domain
Advisor is appointed yet (charter D12), so the Owner ratifies using the
documented literature anchors — honestly framed as defensible expert defaults,
not empirically validated facts (empirical validation stays the v3.0 item; an
independent Domain Advisor may revise any value via a superseding ADR).

- docs/adr/README.md — the ADR log + process; distinguishes these model ADRs
  (0001…) from the design spec's inline app ADRs (ADR-001…007).
- ADR-0001 — ratify the D4/D5 qaFit baseline (Cockburn/Martin/Bogard/Jackson/
  Richards & Ford grounding); flags the weakest cells (SSR security, Hexagonal
  security/interop) for future scrutiny. Closes OI-4 / DI-1.
- ADR-0002 — ratify the preset calibration; accepts the four sub-2% margins as
  honest close calls with the standing "re-run verify-model on any change"
  rule. Closes OI-2.
- Status updates: Model Data Sheet v0.8 (§4 D4/D5 and §6 now ✅ Ratified
  (interim); new ✅ legend tier), SRS v0.7 (OI-2/OI-4 closed), design spec v0.5
  (DoR items + DI-1 closed), charter v1.6 (ADR-log path clarified to docs/adr/).
- Synced cross-document version pointers; fixed the ADR relative links; both
  guard scripts still pass (no numeric change).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: programmerShinobi

docs/01-discovery-and-planning/discovery-and-planning.md

@@ -5,7 +5,7 @@
 | Field | Detail |
 |---|---|
 | **Document type** | Project Charter / Product Vision |
-| **Version** | 1.5 |
+| **Version** | 1.6 |
 | **Date** | 2026-06-12 |
 | **Status** | Approved — execution baseline |
 | **Author / Owner** | Faqih Pratama Muhti, B.Sc. Computer Science |
@@ -22,6 +22,7 @@
 | 1.3 | 2026-06-11 | Editorial clarification (no scope change, no re-approval): designated the Section 22 solo-stage KPI table as the operative v1.0 target set (Section 4 = aspirational); aligned the sign-off date with the v1.2 baseline |
 | 1.4 | 2026-06-11 | Scope clarification: a basic custom-configuration import/export (JSON) is in the MVP (matching Build Spec v3); the richer organization-level config import/export remains deferred to v2.0. Resolves a charter↔Build Spec↔SRS mismatch |
 | 1.5 | 2026-06-12 | Reference hardening (editorial, no scope change): added peer-reviewed and SEI sources [16]–[24] (ADD technical report, SUS and its acceptability threshold, architectural design decisions, technical debt, GQM, Strangler Fig, MADR) and cited them inline where claims rely on them |
+| 1.6 | 2026-06-13 | Editorial: clarified the ADR decision-log path to `docs/adr/` (Section 14.5), where the model-decision records now live |
 
 ---
 
@@ -383,7 +384,7 @@ decisions documents its own.)
 
 **14.5 Onboarding new contributors.** Required files in the repo: `README.md`, `CONTRIBUTING.md`
 (how to set up and contribute), `EXTENDING.md` (how to add factors/QAs/dimensions/anti-patterns/
-translations), `CODE_OF_CONDUCT.md` (adopting the Contributor Covenant [13]), `ADR/` (decision
+translations), `CODE_OF_CONDUCT.md` (adopting the Contributor Covenant [13]), [`docs/adr/`](../adr/) (decision
 history), Issue & PR templates. Provide several `good first issue`s for newcomers.
 
 **14.6 Recognition.** Record contributors (e.g. an `all-contributors` file), mention them in

docs/02-requirement-analysis/README.md

@@ -7,7 +7,7 @@
 
 ## Deliverable
 
-➡️ **[Software Requirements Specification (SRS)](software-requirements-specification.md)** — draft v0.6.
+➡️ **[Software Requirements Specification (SRS)](software-requirements-specification.md)** — draft v0.7.
 
 It translates the charter and [Build Spec v3](../specs/build-spec-v3.md) into discrete, testable,
 traceable requirements (ISO/IEC/IEEE 29148 structure), covering:

docs/02-requirement-analysis/software-requirements-specification.md

@@ -5,12 +5,12 @@
 | Field | Detail |
 |---|---|
 | **Document type** | Software Requirements Specification (SRS) |
-| **Version** | 0.6 |
+| **Version** | 0.7 |
 | **Date** | 2026-06-13 |
 | **Status** | Draft — review-ready |
 | **Author / Owner** | Faqih Pratama Muhti, B.Sc. Computer Science |
 | **Audience** | Engineers, architects, analysts, reviewers |
-| **Derived from** | [Discovery & Planning charter](../01-discovery-and-planning/discovery-and-planning.md) v1.5 · [Build Spec v3](../specs/build-spec-v3.md) |
+| **Derived from** | [Discovery & Planning charter](../01-discovery-and-planning/discovery-and-planning.md) v1.6 · [Build Spec v3](../specs/build-spec-v3.md) |
 | **License** | [CC BY 4.0](../../LICENSE-docs.md) |
 
 **Document history**
@@ -23,6 +23,7 @@
 | 0.4 | 2026-06-12 | Computation precision: linked the [Scoring Algorithm Specification](../03-blueprint/scoring-algorithm.md); pinned defaults exactly (budget = 2, the no-signal level of the inverted factor) in FR-FACT-5/AC-2; AC-2/AC-3 now state exact expected composites and the expected close-call flag; Section 5.3 presets machine-verified, IoT D5 target widened to SPA / SSR |
 | 0.5 | 2026-06-12 | Reference hardening: added peer-reviewed and standard sources (SUS and its acceptability threshold, MADR, Strangler Fig, additive multi-attribute value model, ADD technical report) and cited them inline at NFR-USE-1, FR-OUT-1, FR-REC-12/13, and Section 5.1 |
 | 0.6 | 2026-06-13 | Calibration-stability review: widened the e-commerce and IoT D4 targets to Hexagonal / Clean (the pair differs only on interoperability and ties exactly whenever that weight is 0); margins for every preset target are now machine-measured (Scoring Algorithm Section 9.4) |
+| 0.7 | 2026-06-13 | Closed OI-2 and OI-4: the preset calibration and the D4/D5 `qaFit` vectors are interim-ratified ([ADR-0002](../adr/0002-ratify-preset-calibration.md), [ADR-0001](../adr/0001-ratify-d4-d5-qafit.md)) |
 
 ---
 
@@ -91,7 +92,7 @@ decision records. The authoritative scope (in/deferred/non-goals) is the charter
 
 ### 1.4 References
 
-1. [Discovery & Planning charter](../01-discovery-and-planning/discovery-and-planning.md) (v1.5) — problem, scope, KPIs, risks, governance.
+1. [Discovery & Planning charter](../01-discovery-and-planning/discovery-and-planning.md) (v1.6) — problem, scope, KPIs, risks, governance.
 2. [Build Spec v3](../specs/build-spec-v3.md) — technical specification and model definitions.
 3. [UI/UX Execution Playbook](../guides/uiux-execution-playbook.md) — usability requirements for technical users.
 4. ISO/IEC/IEEE 29148:2018 — Requirements engineering.
@@ -481,9 +482,9 @@ all UX-quality criteria met; KPIs K3 and K5 met at beta; no critical defects.
 | # | Open issue | Owner | Target | Notes |
 |---|---|---|---|---|
 | OI-1 | ~~Final factor count~~ — **Resolved: fixed at 14** (Build Spec Section 4 / [Model Data Sheet](../03-blueprint/model-data-sheet.md) Section 2) | Owner | Closed (2026-06-12) | Grouping also fixed in the Model Data Sheet |
-| OI-2 | Preset factor-level values that hit the Section 5.3 outcome targets | Owner + Domain Advisor | M1–M2 | **Baseline levels now recorded** in [Model Data Sheet](../03-blueprint/model-data-sheet.md) Section 6; calibrate against [Section 5.3](#5-data--decision-model-requirements) & ADR-log |
+| OI-2 | ~~Preset factor-level values~~ — **Resolved: interim-ratified** ([ADR-0002](../adr/0002-ratify-preset-calibration.md)) | Owner | Closed (2026-06-13) | Levels in [Model Data Sheet](../03-blueprint/model-data-sheet.md) Section 6; all 25 targets machine-verified; independent Domain Advisor may revise |
 | OI-3 | Whether the C4 Mermaid stub (FR-OUT-5) is in v1.0 or deferred | Owner | M1 | Currently **Could**-priority |
-| OI-4 | D4/D5 `qaFit` values (documented as defensible defaults) | Domain Advisor | M1–M3 | **Baseline values now recorded** in [Model Data Sheet](../03-blueprint/model-data-sheet.md) Section 4; ratify & ADR-log per Charter Section 14.4 |
+| OI-4 | ~~D4/D5 `qaFit` values~~ — **Resolved: interim-ratified** ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md)) | Owner | Closed (2026-06-13) | Values in [Model Data Sheet](../03-blueprint/model-data-sheet.md) Section 4; independent Domain Advisor / empirical study (v3.0) may revise |
 | OI-5 | Confirm/ratify the quantitative performance budgets in NFR-PERF-3 (bundle size, FCP, p95 interaction) | Engineer | M2 (Phase 3 design) | Interim targets already set in NFR-PERF-3; ratify against the real bundle |
 | OI-6 | Empirical-validation study design (deferred per Charter Section 5) | Owner | v3.0 | Out of MVP scope; tracked for v3.0 |
 

docs/03-blueprint/README.md

@@ -7,7 +7,7 @@
 
 ## Deliverables
 
-➡️ **[Design Specification (Blueprint)](design-specification.md)** — draft v0.4: architecture
+➡️ **[Design Specification (Blueprint)](design-specification.md)** — draft v0.5: architecture
 overview, module & code structure, the decision-model data schema, state & persistence (with a
 resilience & edge-case design), the design system & tokens, UX patterns, the key design decisions
 (ADRs), and a Definition-of-Ready gate for development.

docs/03-blueprint/design-specification.md

@@ -5,12 +5,12 @@
 | Field | Detail |
 |---|---|
 | **Document type** | Design Specification / Software Design Document (SDD) |
-| **Version** | 0.4 |
+| **Version** | 0.5 |
 | **Date** | 2026-06-12 |
 | **Status** | Draft |
 | **Author / Owner** | Faqih Pratama Muhti, B.Sc. Computer Science |
 | **Audience** | Engineers, architects, designers |
-| **Derived from** | [SRS](../02-requirement-analysis/software-requirements-specification.md) v0.6 · [Build Spec v3](../specs/build-spec-v3.md) · [Charter](../01-discovery-and-planning/discovery-and-planning.md) v1.5 · [UI prototype](prototype/index.html) |
+| **Derived from** | [SRS](../02-requirement-analysis/software-requirements-specification.md) v0.7 · [Build Spec v3](../specs/build-spec-v3.md) · [Charter](../01-discovery-and-planning/discovery-and-planning.md) v1.6 · [UI prototype](prototype/index.html) |
 | **License** | [CC BY 4.0](../../LICENSE-docs.md) |
 
 **Document history**
@@ -21,6 +21,7 @@
 | 0.2 | 2026-06-12 | Realigned to SRS v0.2 / Charter v1.4: added a resilience & edge-case design (Section 5.1) covering FR-EDGE-*, browser-baseline and performance-budget coverage, corrected the design-token source reference, and extended traceability |
 | 0.3 | 2026-06-12 | Build-readiness: linked the new [Model Data Sheet](model-data-sheet.md) (frozen numeric model values), added a Definition-of-Ready gate (Section 11), and updated DI-1 to the recorded baseline |
 | 0.4 | 2026-06-12 | Computation precision: linked the [Scoring Algorithm Specification](scoring-algorithm.md) as the exact contract for `lib/scoring.ts`/`lib/sensitivity.ts`; Definition of Ready updated — scoring computation pinned and preset calibration machine-verified |
+| 0.5 | 2026-06-13 | Definition of Ready: D4/D5 `qaFit` and preset calibration interim-ratified ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md), [ADR-0002](../adr/0002-ratify-preset-calibration.md)); DI-1 closed |
 
 ---
 
@@ -307,7 +308,7 @@ These app-level decisions are recorded here; model-value changes follow the ADR
 
 | # | Open issue | Notes |
 |---|---|---|
-| DI-1 | Ratify D4/D5 `qaFit` values | Baseline now recorded in the [Model Data Sheet](model-data-sheet.md) Section 4; Domain Advisor ratifies & ADR-logs (SRS OI-4) |
+| DI-1 | ~~Ratify D4/D5 `qaFit` values~~ — **Done (interim)** | [ADR-0001](../adr/0001-ratify-d4-d5-qafit.md) accepts the [Model Data Sheet](model-data-sheet.md) Section 4 baseline; closes SRS OI-4 |
 | DI-2 | Whether URL-hash state needs a compression library | Decide against a size budget (DI-4) |
 | DI-3 | Final design-token values vs the prototype | Promote the prototype `:root` blocks to the token source of truth |
 | DI-4 | Ratify the performance budgets against the real bundle | Interim targets already set in SRS NFR-PERF-3 (≤ 300 KB gzip, FCP ≤ 2 s, p95 ≤ 100 ms); inherits SRS OI-5 |
@@ -325,8 +326,8 @@ free of guesswork — each line is either fixed or has a usable baseline.
 - [x] **Design tokens** fixed against the prototype (Section 6).
 - [x] **Acceptance criteria** enumerated and ready to wire as tests (SRS Section 7, AC-1…12).
 - [x] **Scoring computation pinned**: formulas, tie-breaking, close-call, sensitivity, rounding, and float-precision rules in the [Scoring Algorithm Specification](scoring-algorithm.md), with machine-verified fixtures (`node scripts/verify-model.mjs`).
-- [x] **Preset levels pass the calibration test** against SRS 5.3 — all 25 targets machine-verified (SRS OI-2; Domain-Advisor ratification still pending).
-- [ ] **D4/D5 `qaFit` ratified** by a Domain Advisor (SRS OI-4) — *baseline usable now*.
+- [x] **Preset levels pass the calibration test** against SRS 5.3 — all 25 targets machine-verified, **interim-ratified** ([ADR-0002](../adr/0002-ratify-preset-calibration.md), closes SRS OI-2).
+- [x] **D4/D5 `qaFit` interim-ratified** by the Owner ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md), closes SRS OI-4); an independent Domain Advisor / the v3.0 study may still revise the values.
 - [x] **Factor content authored (EN/ID)**: labels, level labels, and help for all 14 factors — [Model Data Sheet Section 2.1](model-data-sheet.md) (Translator review pending).
 - [x] **Option & message content authored (EN/ID)**: educational metadata for all 21 options, the 7 anti-pattern messages, and the 12 fitness-function templates — [Option Content Sheet](option-content-sheet.md) (Translator & Domain-Advisor review pending).
 - [ ] **C4 stub** scoped in or out of v1.0 (SRS OI-3).

docs/03-blueprint/model-data-sheet.md

@@ -5,12 +5,12 @@
 | Field | Detail |
 |---|---|
 | **Document type** | Model Data Sheet (the single source of truth for every model value) |
-| **Version** | 0.7 |
+| **Version** | 0.8 |
 | **Date** | 2026-06-13 |
-| **Status** | Baseline — build against this; model heuristics pending Domain-Advisor ratification |
+| **Status** | Baseline — build against this; D4/D5 fit & presets interim-ratified ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md)/[0002](../adr/0002-ratify-preset-calibration.md)), pending independent review |
 | **Author / Owner** | Faqih Pratama Muhti, B.Sc. Computer Science |
 | **Audience** | Engineers building the scoring engine and `config/` |
-| **Derived from** | [Build Spec v3](../specs/build-spec-v3.md) Sections 3–12 · [SRS](../02-requirement-analysis/software-requirements-specification.md) v0.6 Section 5 · [UI prototype](prototype/index.html) |
+| **Derived from** | [Build Spec v3](../specs/build-spec-v3.md) Sections 3–12 · [SRS](../02-requirement-analysis/software-requirements-specification.md) v0.7 Section 5 · [UI prototype](prototype/index.html) |
 | **License** | [CC BY 4.0](../../LICENSE-docs.md) |
 
 **Document history**
@@ -24,6 +24,7 @@
 | 0.5 | 2026-06-13 | Linked the new [Option Content Sheet](option-content-sheet.md): the bilingual educational metadata for all 21 options, anti-pattern messages, and fitness-function templates are now authored |
 | 0.6 | 2026-06-13 | Calibration-stability review: widened the e-commerce and IoT D4 targets to Hexagonal / Clean (exact tie whenever the interoperability weight is 0); target margins are now measured by the verification script, with the four sensitive targets documented in the [Scoring Algorithm Specification](scoring-algorithm.md) Section 9.4 |
 | 0.7 | 2026-06-13 | Factor-content consistency (Section 2.1): made the Indonesian QA names uniform across all help texts (no more mixed EN/ID tokens) and established the baseline ID QA vocabulary; fixed two English level labels so they are truly verbatim from Build Spec Section 4 (lifespan "prototype", dataVolume "big data") |
+| 0.8 | 2026-06-13 | Interim ratification: D4/D5 `qaFit` ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md)) and preset calibration ([ADR-0002](../adr/0002-ratify-preset-calibration.md)) accepted as v1.0 defaults by the Owner (interim Domain-Advisor role, charter D12); values remain editable, pending independent review and the v3.0 empirical study |
 
 ---
 
@@ -38,10 +39,12 @@ every value the scoring engine needs, in one place,** so Phase 4 development has
 
 - 🔒 **Fixed** — taken verbatim from Build Spec v3; change only via the model-change ADR process
   ([Charter Section 14.4](../01-discovery-and-planning/discovery-and-planning.md#14-governance--contribution)).
-- 🧪 **Baseline** — a defensible default (promoted from the prototype or derived to hit the SRS
-  outcome targets); **valid to build against now**, to be ratified by a Domain Advisor
-  (SRS [OI-2](../02-requirement-analysis/software-requirements-specification.md#9-open-issues--to-be-determined), OI-4).
-  Ratification adjusts numbers **in this sheet**, not the requirements.
+- ✅ **Ratified (interim)** — accepted as the v1.0 default by the Owner via an ADR
+  ([ADR-0001](../adr/0001-ratify-d4-d5-qafit.md), [ADR-0002](../adr/0002-ratify-preset-calibration.md));
+  still editable — an independent Domain Advisor or the v3.0 empirical study may revise it.
+- 🧪 **Baseline copy** — authored content pending review (Translator for the Indonesian copy,
+  Charter Section 14.2); **valid to build against now**. Review adjusts wording **in this sheet**,
+  not the requirements.
 
 > All values live in `config/` at build time (NFR-MAINT-1); this sheet is the human-readable
 > master that those files must mirror. **How** these values are computed (formulas, tie-breaking,
@@ -192,7 +195,7 @@ Values are integers 1–5; any unlisted entry defaults to **3**.
 | `event-sourcing` | Event Sourcing | `3,4,3,3,2,3,3,5,4,3,2,2` |
 | `polyglot` | Polyglot persistence | `4,4,3,3,3,3,3,3,3,4,2,3` |
 
-### D4 — Code Structure (4 options) — 🧪 Baseline (promoted from prototype; ratify per OI-4)
+### D4 — Code Structure (4 options) — ✅ Ratified (interim, [ADR-0001](../adr/0001-ratify-d4-d5-qafit.md); promoted from prototype)
 
 Build Spec Section 6 left D4 `qaFit` "to be assigned & documented." These are the values the
 prototype already encodes and displays; they follow the Build Spec principle (Hexagonal/Clean
@@ -205,7 +208,7 @@ favor maintainability/testability at a time-to-market cost; simpler structures f
 | `vertical-slice` | Vertical Slice | `3,3,3,3,4,3,4,3,3,3,3,4` |
 | `layered` | Layered | `3,3,3,3,3,3,3,3,3,3,4,5` |
 
-### D5 — Frontend Architecture (3 options) — 🧪 Baseline (promoted from prototype; ratify per OI-4)
+### D5 — Frontend Architecture (3 options) — ✅ Ratified (interim, [ADR-0001](../adr/0001-ratify-d4-d5-qafit.md); promoted from prototype)
 
 Build Spec Section 6 left D5 `qaFit` "to be assigned & documented." Micro-frontends favor
 deployability/scalability at a maintainability/`ttm` cost.
@@ -234,7 +237,7 @@ Each rule is a boolean over factors + chosen options, with a severity and an EN/
 
 ---
 
-## 6. Scenario presets — factor levels — 🧪 Calibrated baseline (ratify per OI-2)
+## 6. Scenario presets — factor levels — ✅ Ratified (interim, [ADR-0002](../adr/0002-ratify-preset-calibration.md); calibrated & machine-verified)
 
 Each preset sets all 14 factor levels (column order = Section 2). These levels are **calibrated
 and machine-verified**: running [`scripts/verify-model.mjs`](../../scripts/verify-model.mjs)
@@ -315,8 +318,8 @@ value theory, sensitivity analysis, apportionment).
 
 | Item | Status | Closes |
 |---|---|---|
-| D4 / D5 `qaFit` vectors (Section 4) | 🧪 Baseline recorded | Domain Advisor ratifies → SRS OI-4 |
-| Preset factor levels (Section 6) | 🧪 **Calibrated & machine-verified** (all 25 targets hold) | Domain Advisor ratifies → SRS OI-2 |
+| D4 / D5 `qaFit` vectors (Section 4) | ✅ **Ratified (interim)** — [ADR-0001](../adr/0001-ratify-d4-d5-qafit.md) | Independent Domain Advisor / empirical study (v3.0) may revise |
+| Preset factor levels (Section 6) | ✅ **Ratified (interim)** — [ADR-0002](../adr/0002-ratify-preset-calibration.md); all 25 targets hold | Independent Domain Advisor may revise |
 | Factor content EN/ID (labels, level labels, help) | 🧪 **Authored** (Section 2.1) | Translator review → Charter Section 14.2 |
 | Option educational metadata; fitness & anti-pattern messages (EN/ID) | 🧪 **Authored** ([Option Content Sheet](option-content-sheet.md)) | Translator & Domain-Advisor review → Charter Section 14.2 |
 | C4 Mermaid stub in v1.0? | ❔ Scope | SRS OI-3 |

docs/README.md

@@ -35,6 +35,7 @@ spanning **multiple** phases live here:
 | [`specs/`](specs/) | [Build Spec v3](specs/build-spec-v3.md) | The complete technical specification the app is built from (feeds phases 2–5) |
 | [`guides/`](guides/) | [UI/UX Execution Playbook](guides/uiux-execution-playbook.md) | 9 usability factors for technical users as executable tasks (phases 3–4) |
 | [`guides/`](guides/) | [Feature-Maturity Playbook](guides/feature-maturity-playbook.md) | UX/technical/analyst factors as concrete, verifiable tasks (phases 4–7) |
+| [`adr/`](adr/) | [Architecture Decision Records](adr/) | The model-decision log (e.g. the D4/D5 fit & preset ratifications), per charter governance |
 
 ## Reading paths