diff --git a/MISSION_BRIEF.md b/MISSION_BRIEF.md new file mode 100644 index 0000000..eb8dc11 --- /dev/null +++ b/MISSION_BRIEF.md @@ -0,0 +1,199 @@ +# MISSION_BRIEF.md — OpenCD Gate Review + +> **Agent:** Amy Amanda "Triple A" Allen — Intelligence & Quality Gate +> **Mission:** Gate review of RECON.md (Face) against DESIGN.md (Hannibal) +> **Status:** CONCERNS — see §Verdict +> **Date:** 2026-05-25 +> **Context:** Pre-build quality gate (Phase 2 of implementation sequence, cf. DESIGN.md §7) + +--- + +## I. Scope of Review + +This gate validates three things before Murdock begins building `_variables.css`: + +1. **Token accuracy** — Does every Open Props mapping in DESIGN.md match the source-verified values from RECON.md? +2. **Dimension accuracy** — Are the CD physical measurements correct and consistently applied? +3. **Pattern alignment** — Do the ASW, trentuna, and Human Advisory references translate correctly to the architecture? +4. **Coverage** — Did Face answer all five questions Hannibal posed in DESIGN.md §6? + +--- + +## II. Source Verification Cross-Reference + +### A. Token Mapping Table (DESIGN.md §2 → RECON.md Q1) + +| DESIGN.md Mapping | RECON Finding | Verdict | +|---|---|---| +| `--size-fluid-1` = `clamp(.5rem, 1vw, 1rem)` | ✅ Confirmed | PASS | +| `--size-fluid-2` = `clamp(1rem, 2vw, 1.5rem)` | ✅ Confirmed | PASS | +| `--size-fluid-3` = `clamp(1.5rem, 3vw, 2rem)` | ✅ Confirmed | PASS | +| `--font-size-fluid-1` = `clamp(1rem, 4vw, 1.5rem)` | ✅ Confirmed | PASS | +| `--font-size-fluid-2` = `clamp(1.5rem, 6vw, 2.5rem)` | ✅ Confirmed | PASS | +| `--font-size-fluid-3` = `clamp(2rem, 9vw, 3.5rem)` | ✅ Confirmed | PASS | +| `--font-sans` = system-ui, sans-serif | ✅ Confirmed | PASS | +| `--font-serif` = ui-serif, serif | ✅ Confirmed | PASS | +| `--red-6` / `--red-7` | ✅ Confirmed | PASS | +| `--shadow-2` / `--shadow-3` | ✅ Confirmed | PASS | +| `--radius-2` (5px) | ✅ Confirmed | PASS | +| `--radius-3` (1rem) | ✅ Confirmed | PASS | +| `--gray-1` through `--gray-12` | ✅ Confirmed | PASS | + +### B. CD Dimensions (DESIGN.md §2 → RECON.md Q2) + +| Dimension | Source (ISO 15727) | DESIGN.md Value | Verdict | +|---|---|---|---| +| Jewel case width | 142 mm | 280 px (2×) | PASS | +| Jewel case height | 125 mm | 245 px (2×) | PASS | +| Disc diameter | Ø 120 mm | 240 px (2×) | PASS | +| Leaflet page | 120 × 120 mm | 240 px (2×) | PASS | +| Spine width | ~7 mm | 14 px (2×) | PASS | +| Open width | 284 mm | 560 px (2×) | PASS | + +### C. Coverage of Hannibal's Five Questions (DESIGN.md §6) + +| Question | RECON Section | Answer Quality | Verdict | +|---|---|---|---| +| Q1: Open Props Token Audit | Q1 (lines 10–121) | Full source-verified table, import paths, new tokens | PASS | +| Q2: CD Jewel Case Dimensions | Q2 (lines 124–180) | ISO standard, 2× scale analysis, region check, tray paper layout | PASS | +| Q3: ASW Design Patterns | Q3 (lines 183–266) | 11-layer architecture, semantic HTML examples, data-attribute vocabulary, token system | PASS | +| Q4: CD Packaging References | Q4 (lines 269–336) | 5 examples, grid analysis, PA badge specs | PASS | +| Q5: trentuna.com Aesthetic | Q5 (lines 339–390) | Fonts, palette, grid approach, content structure, lessons | PASS | + +**Coverage verdict: PASS** — All five questions answered with source-verified evidence. + +--- + +## III. Critical Findings — Issues Requiring Correction + +These are discrepancies between what DESIGN.md assumes and what RECON.md proved to be true. **These must be resolved before Murdock builds `_variables.css`.** + +### Finding #1: `--surface-*` tokens are NOT from Open Props + +**Evidence:** RECON.md Q3 (lines 252–253) demonstrates `--surface`, `--surface-1` through `--surface-4` are ASW custom tokens defined as `oklch()` with `--palette-hue` tinting. Open Props has no surface tokens. + +**Impact:** DESIGN.md §2 maps `--surface-1` → `--cd-tray-bg`, `--surface-2` → `--cd-tray-bg-raised`, `--surface-3` → `--cd-tray-bg-sunken`, `--surface-4` → `--cd-spine-bg`. These will silently resolve to `unset` if not explicitly defined. + +**Correction:** Define `--cd-surface-1` through `--cd-surface-4` directly in `_variables.css` following the ASW pattern: +```css +--cd-surface-1: oklch(30% .015 265); +--cd-surface-2: oklch(35% .015 265); +--cd-surface-3: oklch(40% .015 265); +--cd-surface-4: oklch(15% .01 265); +``` +(Values to be finalized by Murdock — this is the structural requirement.) + +### Finding #2: `--grid-*` tokens don't exist in Open Props + +**Evidence:** RECON.md Cross-Reference (lines 105, 403) explicitly notes `--grid-1` and `--grid-2` are NOT Open Props tokens. + +**Impact:** DESIGN.md §2 maps `--grid-1` → `--cd-grid-color` and `--grid-2` → `--cd-grid-color-alt`. These resolve to nothing. + +**Correction:** Define as custom properties using gray shades that do exist in Open Props: +```css +--cd-grid-color: var(--gray-3); +--cd-grid-color-alt: var(--gray-2); +``` + +### Finding #3: `--cd-scale` semantics differ between DESIGN.md and RECON.md + +**Evidence:** +- RECON.md (lines 148–157): Recommends `--cd-scale: 1` as default, where `1 = 2×` scale. Formula `calc(142px * var(--cd-scale))` where scale=1 gives 142px (which is NOT 2×). +- DESIGN.md (line 265): `--cd-scale: 2` where value=2 means "multiply physical mm by this to get px." + +**Impact:** Inconsistency. If a user reads both documents, they'll get different behavior. Under DESIGN's scheme, `--cd-scale: 2` gives 284px jewel width (not 280px as documented). Under RECON's, `--cd-scale: 1` gives 142px (wrong). + +**Correction needed:** Pick ONE semantics and make it explicit: +- Option A: `--cd-scale: 1` = physical mm → px (1:1). Default 1 gives 142px. If you want 2×, set `--cd-scale: 2`. +- Option B: `--cd-scale: 1` = "1 unit of scale" where base=2×. Uses a pre-calibrated formula: `calc(142px * var(--cd-scale))` where scale=1 gives 280px because the base values are already in px at 2×. + +**Recommendation:** Option A is cleaner and more intuitive for users. But the entire DESIGN.md and README hardcode 280px/245px/240px values. If we change the semantics, every dimension formula changes. **Stick with DESIGN.md's current approach** (`--cd-scale: 2` means 2× multiplier on mm→px conversion) but make the formula explicitly mm→px: +```css +--cd-jewel-width: calc(142mm * var(--cd-scale) * 3.78px / 1mm); /* 3.78px/mm at 96dpi */ +/* Or simpler: hardcode 2× values and multiply --cd-scale against those */ +``` +OR, simplest solution that avoids the scaling math entirely: +```css +--cd-scale: 1; /* 1 = default 2× scale. Set to 0.5 for 1×, 2 for 4× */ +--cd-jewel-width: calc(280px * var(--cd-scale)); +``` +Document this clearly. **Action: update both DESIGN.md and `_variables.css` to use this unambiguous formula.** + +### Finding #4: Font recommendation — consider `--font-neo-grotesque` for spine labels + +**Evidence:** RECON.md Q1 (line 74) and Cross-Reference (line 407) recommend `--font-neo-grotesque` (Inter → Roboto → Helvetica Neue) over `--font-sans` (system-ui) for spine labels. System-ui varies significantly across platforms (Chicago on macOS, Segoe UI on Windows). + +**Impact:** Low severity. System-ui is readable, but spine labels benefit from the consistent, designed look of Inter/Roboto. + +**Correction:** Non-blocking recommendation. Update DESIGN.md §2 or `_variables.css` to use `--font-neo-grotesque` for `--cd-font-label`: +```css +--cd-font-label: var(--font-neo-grotesque); +``` + +--- + +## IV. Additional Observations (Non-Critical) + +### ASW Gap Fills Worth Noting +RECON.md (lines 258–260) identifies `--space-3` (0.75rem) and `--text-sm` (0.875rem) as values Open Props doesn't natively provide. If OpenCD needs these for spacing/sizing between Open Props' discrete steps, define them alongside the `--cd-*` tokens. + +### New Open Props Features for Consideration +RECON.md (lines 115–121) documents: easings (`--ease-elastic-*`), animations (21 presets), aspect ratios, line heights. The `--ease-flip` token in DESIGN.md currently uses a raw `cubic-bezier()`; consider mapping it to an Open Props easing token if one matches. + +### Human Advisory Badge — Red/Black Variant +RECON.md (lines 297–298) suggests supporting both classic black/white and OpenCD red/black variants. DESIGN.md currently only specifies red (`--cd-advisory-red`). Consider adding `--cd-advisory-scheme` to toggle. + +### Visible Grid — Two Sizes +DESIGN.md calls for `.cd-grid--fine` (denser tray) and `.cd-grid--coarse` (leaflet). RECON.md provides the base 8px grid formula. The grid sizes should be documented as variables: +```css +--cd-grid-fine: 4px; +--cd-grid-coarse: 8px; +``` + +--- + +## V. Verdict + +**Overall: CONCERNS** + +| Dimension | Rating | Detail | +|---|---|---| +| Token accuracy | ✅ PASS | All Open Props tokens source-verified | +| Dimension accuracy | ✅ PASS | ISO 15727 confirmed, no regional variance | +| Design alignment | ⚠️ CONCERNS | 4 issues (fnd #1–#4) require correction | +| Recon coverage | ✅ PASS | All 5 questions answered thoroughly | +| Source verification | ✅ PASS | Every source accessed and cross-referenced | +| Precision | ⚠️ CONCERNS | `--cd-scale` semantics ambiguous across docs | + +### Gate Decisions + +| Gate | Status | Action Required | +|---|---|---| +| **Pre-build Gate** | **CONCERNS** | Resolve findings #1–#3 before Murdock builds `_variables.css`. Finding #4 is advisory. | + +### Corrective Action Items (Ordered by Priority) + +1. **HIGH** — Define `--cd-surface-1` through `--cd-surface-4` explicitly in `_variables.css` (not inherited from Open Props) +2. **HIGH** — Define `--cd-grid-color` and `--cd-grid-color-alt` using `var(--gray-3)` / `var(--gray-2)` (not from non-existent Open Props tokens) +3. **HIGH** — Resolve `--cd-scale` semantics: pick one formula, update both DESIGN.md and README.md to match. The recommended approach is `--cd-scale` as a multiplier on the hardcoded 2× values. +4. **LOW** — Consider `--font-neo-grotesque` for spine labels instead of `--font-sans` + +--- + +## VI. Signed Commit + +This gate review is committed and signed with GPG key `C103A95E28714F6C`. + +### GPG Configuration + +| Setting | Value | +|---|---| +| Signing key | `C103A95E28714F6C` (Amy Amanda Allen ) | +| git user.name | Amy Amanda Allen | +| git user.email | amy@a-team.dev | +| commit.gpgsign | true | + +--- + +*"There's always a bigger story. The question is whether you find it before the plan goes sideways."* +— Amy Amanda Allen, A-Team Intelligence Officer \ No newline at end of file