From ecbe3362207821212eecf7803b41422e83dea7f1 Mon Sep 17 00:00:00 2001 From: Jason Lee <56489493+jason931225@users.noreply.github.com> Date: Mon, 17 Aug 2026 21:19:47 -0400 Subject: [PATCH] docs: align hyperscaler standard authority pointers --- DESIGN.md | 5 ++- HANDOFF.md | 14 ++++-- README.md | 12 ++++- SPEC.md | 5 ++- docs/CI-GATES.md | 2 + docs/DESIGN-DOCTRINE.md | 94 ++++------------------------------------ docs/PLATFORM-ROADMAP.md | 4 +- docs/current/DELIVERY.md | 16 +++---- 8 files changed, 47 insertions(+), 105 deletions(-) diff --git a/DESIGN.md b/DESIGN.md index 81d2f28a2..797e2b233 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -1,5 +1,6 @@ -# DESIGN — one-release redirect +# DESIGN — tombstoned historical pointer Current product and architecture authority lives in [`docs/current/PRODUCT.md`](docs/current/PRODUCT.md). -This path remains for one release so existing links resolve. It is not current authority and cannot dispatch work; use the replacement above. +This path is intentionally retained for one-release link stability only. It is **not** +current authority and cannot dispatch work. Use the replacement above. diff --git a/HANDOFF.md b/HANDOFF.md index 5d807899f..a0fa3468b 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,9 +1,15 @@ # HANDOFF — volatile restart pointer -Start at [`README.md`](README.md), then read [`PRODUCT`](docs/current/PRODUCT.md), [`ROADMAP`](docs/current/ROADMAP.md), and [`DELIVERY`](docs/current/DELIVERY.md). This file is a short restart pointer, not product, roadmap, or delivery authority. +Start with current, live authority: -The latest preserved recovery context is [`docs/handoffs/2026-08-03-disk-wipe-consolidation.md`](docs/handoffs/2026-08-03-disk-wipe-consolidation.md). Product code does not depend on an old worktree or local branch. Custody, recovery, restricted-input, and secret-handling obligations remain recorded in that historical handoff and must not be discarded. +- [`README.md`](README.md) +- [`docs/current/PRODUCT.md`](docs/current/PRODUCT.md) +- [`docs/current/ROADMAP.md`](docs/current/ROADMAP.md) +- [`docs/current/DELIVERY.md`](docs/current/DELIVERY.md) -In a fresh clone of the latest `origin/main`, follow the root README and then read the tracked [execution handoff](.omx/plans/reasoning-lens-contract-execution-handoff.json). The four tracked OMX continuity artifacts are Git-custodied even though new `.omx/` runtime output is ignored; retired ignored runtime bytes must not be restored as authority. +This is a restart pointer only. Preserve historical custody evidence in +[`docs/handoffs/2026-08-03-disk-wipe-consolidation.md`](docs/handoffs/2026-08-03-disk-wipe-consolidation.md) +and `.omx/` artifacts, but do not use them as live authority. -`main` remains the integration branch. Product and delivery HOLDs are recorded in the three current authorities. The linked handoff supplies custody evidence and itemized disposition state only; it cannot clear or weaken a current HOLD. +`main` remains the integration branch. Product and delivery HOLDs are recorded in +the three current authorities above. diff --git a/README.md b/README.md index 7fdc5272f..cf1a19cda 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,17 @@ npm ci npm run verify ``` -`npm ci` installs the pinned repository tooling; `npm run verify` is the one supported local repository verification entrypoint. Run narrower tests while developing and any additional checks required by the touched surface, then record the exact candidate SHA, commands, environment, discovered/executed counts, failures, and remaining HOLDs as described in [`docs/current/DELIVERY.md`](docs/current/DELIVERY.md). +`npm ci` installs the pinned repository tooling; `npm run verify` is the supported local repository verification entrypoint. + +For a local full CI-path parity run, install the pinned DotSlash runtime first: + +```sh +tools/buck/install_dotslash.sh +export PATH="${CONSOLE_DOTSLASH_BIN_DIR:-${RUNNER_TEMP:-${TMPDIR:-/tmp}/console-dotslash}/bin}:$PATH" +npm run verify +``` + +Run narrower tests while developing and any additional checks required by the touched surface, then record the exact candidate SHA, commands, environment, discovered/executed counts, failures, and remaining HOLDs as described in [`docs/current/DELIVERY.md`](docs/current/DELIVERY.md). ## Reasoning lens manifest diff --git a/SPEC.md b/SPEC.md index efa8c9e78..ddf719672 100644 --- a/SPEC.md +++ b/SPEC.md @@ -1,5 +1,6 @@ -# SPEC — one-release redirect +# SPEC — tombstoned historical pointer Current product scope, invariants, architecture, and holds live in [`docs/current/PRODUCT.md`](docs/current/PRODUCT.md). -This path remains for one release so existing links resolve. It is not current authority and cannot dispatch work; use the replacement above. +This path is intentionally retained for one-release link stability only. It is **not** +current authority and cannot dispatch work. Use the replacement above. diff --git a/docs/CI-GATES.md b/docs/CI-GATES.md index 0bb8f7017..840a3cbc0 100644 --- a/docs/CI-GATES.md +++ b/docs/CI-GATES.md @@ -2,6 +2,8 @@ # CI Gates +Refreshed: 2026-08-17 from the live `.github/workflows/ci.yml` and `.github/workflows/security.yml` workflows on this branch. + The GitHub Actions workflow in `.github/workflows/ci.yml` is the **executable inventory** of CI enforcement (this doc is a non-authority mirror). This document mirrors the current gate inventory and splits the checks into two groups: core local gates that a fresh development session can diff --git a/docs/DESIGN-DOCTRINE.md b/docs/DESIGN-DOCTRINE.md index a98f46496..a9e2a1400 100644 --- a/docs/DESIGN-DOCTRINE.md +++ b/docs/DESIGN-DOCTRINE.md @@ -1,90 +1,12 @@ -> **SUPERSEDED PRE-PIVOT RECORD — NOT CURRENT AUTHORITY.** -> Public web, legacy application, and React Console visual authorities were deleted or superseded. -> **Do not govern new work from this file.** -> **Current authority:** [`docs/current/PRODUCT.md`](current/PRODUCT.md); frontend HOLD + ADR-0030. -> Pivot history only: [`PIVOT-2026-07-28.md`](PIVOT-2026-07-28.md). +# KNL design doctrine — retired historical doctrine -# KNL design doctrine +This doctrine described a deleted storefront/legacy surface under `web/` and is +not live authority for the current repository. -**One company, coherent product principles, explicit visual authorities. Best practice only.** +Use the current authorities for active work: -The public web, legacy application, and target Console are one product and share universal -principles: Korean-first copy, WCAG AA, reduced-motion support, honest content, no stubs, canonical -object identity, and audited/policy-gated actions. They do **not** share one visual component system. +- [`docs/current/PRODUCT.md`](current/PRODUCT.md) +- [`docs/design/oyatie-console`](./design/oyatie-console/) -This document's palette, typography, layout, and `web/src/components/ui/**` rules govern the public -web and legacy application. Accepted ADR-0025 governs the isolated target under -`web/src/console/**`; its visual authority is `docs/design/oyatie-console/**`, and it does not inherit -legacy shell/UI/page visuals. The two surfaces share the nonvisual platform spine—auth, contracts, -policy, audit, realtime, i18n, telemetry, and E2E—during measured convergence. - -## 1. Storefront and legacy tokens (`web/src/styles.css` @theme) - -`ink #101820` · `signal #f6b521` (amber) · `signal-dark #c88800` · `brand-teal #0f766e` -· `steel #51606c` · `line #d7dee5` · `muted-panel #eef2f5`. Within the storefront/legacy scope, -**no raw hex** in components -(`#050d14`, `#f6f8fa`, `#14120c` are forbidden — use `ink` / `muted-panel`). Semantic use: -ink = dark surfaces/headings; signal = primary CTA + dark-surface accents; brand-teal = -light-surface accents; steel = body; line = borders; muted-panel = alt section bg. - -## 2. Storefront and legacy typography - -- Hero H1 `clamp(40px,6vw,72px)` leading-[1.05] tracking-[-0.02em] `font-extrabold`, max-w-[820px]. -- Section H2 `clamp(28px,3.4vw,44px)` leading-[1.12] `font-extrabold`. -- Body `text-steel` 17–18px leading-[1.7]. Reserve `font-extrabold`/`font-black` for H1–H3 + CTAs. -- **One eyebrow rule:** 12–13px `font-black uppercase tracking-[0.14em]`, **brand-teal on light / - signal on dark**. Never brand-teal on ink (fails AA, 3.27:1). - -## 3. Storefront and legacy spacing and layout - -Content bands `py-[clamp(72px,9vw,120px)]`; accent bands `py-[clamp(40px,5vw,64px)]`. One inner -width `max-w-[1240px]`, one padding rhythm `px-5 sm:px-8 lg:px-12`. 8pt rhythm inside components. - -## 4. Storefront and legacy components — KNL primitives (no slate) - -The shared `web/src/components/ui/*` (Button/Card/Badge/Input/Select/Textarea) are KNL-tokened for -the storefront and legacy application, -not slate. Buttons: **primary** `bg-signal text-ink`; **secondary-dark** `border-white/35 bg-white/10 -text-white`; **secondary-light** `border-ink text-ink`. `min-h-[52px]` (44px in headers/dense -console). `rounded`. Cards: 12px radius, 1px `line` border, contained image `object-cover` with -`motion-safe:group-hover:scale-105` + ink→transparent gradient. - -## 5. Accessibility — WCAG AA, non-negotiable - -Every interactive element has a visible **focus-visible** ring (`outline-2 outline-offset-2`, -signal/ink/white as the surface demands). Every `
` is `aria-labelledby` an id'd heading. -Decorative/background images are `aria-hidden`; meaningful images keep real alt text. Tap targets -**≥44px**. Full keyboard operability; no icon-only controls without an aria-label. Contrast ≥4.5:1 -normal / 3:1 large — verify on dark (`white/70` ok, brand-teal-on-ink not) and amber (ink text). - -## 6. Motion — restraint - -Only small hover translate (≤2–3px) + card image-zoom (≤1.04) + static hero scale-1.03. **All** -transforms gated under `motion-safe:`. No parallax, no autoplay, no position jumps for reduced-motion. - -## 7. Content & voice - -Korean-first; **all** visible copy lives in `web/src/i18n/ko.ts` (the check-ui-strings gate forbids -inline Hangul). **Online-centric — phone is a last resort.** No fabricated metrics/testimonials, -no stubs, no lorem, no filler, no dead-end screens. Real content only. No orphaned i18n keys. - -## 8. Surface doctrine — coherent product, distinct visual systems - -- **Public web and legacy application** — this doctrine's KNL brand system, with marketing - spaciousness or legacy operational density as appropriate. -- **Target carbon-copy Console** — the denser ontology/window/object grammar in - `docs/design/oyatie-console/**`, isolated under `web/src/console/**` per ADR-0025. - -Coherence comes from product vocabulary, accessibility, canonical objects, policy/audit behavior, -and the shared platform spine—not from forcing the homepage palette or legacy components into the -carbon-copy surface. The legacy visual system is removed only after ADR-0025's rollout and deletion -gates pass. - -## 9. Enforcement - -Universal gates: `eslint --max-warnings 0`, `check-ui-strings`, `tsc -b`, `vite build`, the vitest -suite, and real-backend browser E2E. Storefront/legacy visual changes cite this doctrine and match the -homepage reference. Carbon-copy changes cite ADR-0025 plus the nearest -`docs/design/oyatie-console/**` authority and pass its fidelity, accessibility, performance, -full-stack, and persona gates. Reviewers reject cross-boundary visual imports as well as unsupported -one-off deviations within either authority. +This file remains for historical context only and is not suitable for dispatching +new work. diff --git a/docs/PLATFORM-ROADMAP.md b/docs/PLATFORM-ROADMAP.md index 4fc0ca82c..b1648552f 100644 --- a/docs/PLATFORM-ROADMAP.md +++ b/docs/PLATFORM-ROADMAP.md @@ -1,7 +1,7 @@ -# KNL one-stop platform — historical vision notes (non-authority) +# KNL one-stop platform — archived historical roadmap (non-authority) > **HISTORICAL / NON-AUTHORITY.** -> **Current ordered roadmap:** [`current/ROADMAP.md`](current/ROADMAP.md), constrained by [`current/PRODUCT.md`](current/PRODUCT.md). +> **Current ordered roadmap:** [`docs/current/ROADMAP.md`](docs/current/ROADMAP.md), constrained by [`docs/current/PRODUCT.md`](docs/current/PRODUCT.md). > This file is a **frozen pre-pivot plan**. It is not a living plan, does not dispatch work, and cannot clear HOLDs. > Phrases below such as “Living plan”, “Already built”, or live hostnames are **historical claims**, not present-tense product truth. diff --git a/docs/current/DELIVERY.md b/docs/current/DELIVERY.md index 5b44cb5ab..133a4747b 100644 --- a/docs/current/DELIVERY.md +++ b/docs/current/DELIVERY.md @@ -19,19 +19,19 @@ Merge only the reviewed candidate through the repository's protected integration Run the smallest targeted regression first, then the applicable format, lint/type, contract, security, and domain gates. The supported repository entrypoint is: ```sh -# one-time: install the pinned DotSlash runtime that tools/buck2 shells out to, -# then put it on PATH -- the installer only appends to $GITHUB_PATH, which does -# not exist outside GitHub Actions, and it cannot modify its parent shell. +npm ci +npm run verify +``` + +The Buck2-backed steps require the pinned DotSlash runtime on PATH for full CI-path parity. Candidate-local heavy-path workflows without it may fail with environment failures that are not product regressions. + +```sh +# For local CI-path parity tools/buck/install_dotslash.sh export PATH="${CONSOLE_DOTSLASH_BIN_DIR:-${RUNNER_TEMP:-${TMPDIR:-/tmp}/console-dotslash}/bin}:$PATH" - npm run verify ``` -The Buck2-backed steps require the pinned DotSlash runtime on PATH. Without the -`export` above, `npm run verify` exits 1 with six failures that are -environment, not regressions. - For documentation-authority changes, also run the doc-link tests and gate, ADR tests and gate, citation checks, foundation tests and gate, CI-preflight tests and gate, verifier tests, `npm run verify`, and `git diff --check`. Inspect the exact changed-path allowlist and ignored/untracked state before signing a candidate. Record exact commands, revision, toolchain/environment, discovered and executed counts, failures, artifact hashes where relevant, and validation gaps. A ran-nothing result, stale SHA, superseded candidate, or omitted required surface is not green evidence.