opencd/MISSION_BRIEF.md

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:

--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:

--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:

--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:

--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:

--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:

--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 amy@a-team.dev)
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