diff --git a/.claude/skills/audit-code-quality/SKILL.md b/.claude/skills/audit-code-quality/SKILL.md index 47a82741d8..3bbd33867f 100644 --- a/.claude/skills/audit-code-quality/SKILL.md +++ b/.claude/skills/audit-code-quality/SKILL.md @@ -96,6 +96,29 @@ finding, a completeness pass — same findings shape. --- +## Phase 2.5 — React Doctor pass (ui / frontend / both scope) + +For any scope that includes the frontend, also run the deterministic **React-correctness +scanner** — it catches state/effects, hydration, perf, and a11y bugs the rubric's LLM finders +miss, and it is a **required CI check** (`.github/workflows/react-doctor.yml`): + +```bash +npx -y react-doctor@0.7.6 --project apps/web,apps/mobile,packages/shared \ + --json --json-out "${TMPDIR:-/tmp}/rd-audit.json" \ + --no-supply-chain --no-score --no-dead-code --yes --max-duration 360 --no-color +``` + +Scope to the three workspaces via `--project` — this **excludes `design/handoff/**`**, whose +vendored `*.jsx` design mockups emit ~1054 false `jsx-no-undef` errors that are not app code. +The flags match the CI gate's hermetic/no-knip stance; the CI gate is `--scope changed`, so it +never sees the standing backlog this full scan surfaces. Fold every diagnostic into the report +(the JSON's paths are workspace-relative — prefix with the project): react-doctor **errors** → +**High** (real React bugs), **warnings** → **Low/Info**, each tagged `[react-doctor · {rule}]` +with file:line + the rule's fix; group warnings by rule with a count. `api` scope skips this +(React-only). Report-only — surface findings, do not fix here. + +--- + ## Phase 3 — Apply the rubric (what a repo-wide audit recalibrates) The rubric was written for a diff; the workflow's finders already recalibrate two rules — diff --git a/.claude/skills/prod-readiness/SKILL.md b/.claude/skills/prod-readiness/SKILL.md index 8e4cb416c1..36ed066c42 100644 --- a/.claude/skills/prod-readiness/SKILL.md +++ b/.claude/skills/prod-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: prod-readiness -description: Pre-launch orchestrator — runs the four repo-wide audits (security, tests, performance, code-quality) in parallel via the audit workflow and adds an ops-layer audit (observability, multi-instance readiness, background durability, backups, staging), then consolidates everything into ONE tier-tagged, verification-protocol-backed report with an honest launch verdict. Use before a release to know what's safe to ship. Orchestrates + consolidates; it does not re-derive the child audits' findings. +description: Pre-launch orchestrator — runs the four repo-wide audits (security, tests, performance, code-quality) in parallel via the audit workflow, adds an ops-layer audit (observability, multi-instance readiness, background durability, backups, staging) AND a full-repo React-correctness scan (React Doctor) over orbit-ui-mobile, then consolidates everything into ONE tier-tagged, verification-protocol-backed report with an honest launch verdict. Use before a release to know what's safe to ship. Orchestrates + consolidates; it does not re-derive the child audits' findings. argument-hint: --- @@ -44,7 +44,7 @@ The workflow runs its own coverage contract over the ops inventory + the §2 cha its ops findings, and **inherits** each child audit's verify and loop; you merge every child ledger into the consolidated report. -**The binding inventory (§1) — nine items:** +**The binding inventory (§1) — ten items:** | # | Inventory item | Kind | Owner of the analysis | |---|---|---|---| @@ -57,6 +57,7 @@ ledger into the consolidated report. | 7 | Background durability | ops check | the workflow (own §2 challenge) | | 8 | Backups | ops check | the workflow (returns as Deferred — un-verifiable from a repo read) | | 9 | Staging | ops check | the workflow (own §2 challenge) | +| 10 | React correctness (React Doctor) | scanner | the workflow (full-repo react-doctor scan of apps/web + apps/mobile + packages/shared; ui/both scope only) | This list is **binding**: by the end every item is either **(a) covered with a verdict** or **(b) in the Deferred ledger with a one-line reason**. There is no silently-skipped bucket. @@ -100,6 +101,7 @@ durability · staging — as Haiku finders, runs a Haiku skeptic per Blocker/Hig { scope, audits: [ { kind, findings, counts, coverage, deferred, rounds }, … ×4 ], opsFindings: [ { severity, check, title, location, risk, evidence, fix } ], + reactDoctor: { ran, errorCount, warningCount, findings: [ { severity, rule, category, location, message, fix } ], note }, opsChecksRun, opsDeferred, failedAudits } ``` @@ -107,6 +109,14 @@ durability · staging — as Haiku finders, runs a Haiku skeptic per Blocker/Hig restore path"). `failedAudits` names any audit workflow that errored — each forces **≤ CONDITIONAL** and is named as a blocker. +**React Doctor (item 10)** runs only for `ui`/`both` scope (it is React-only — `api` scope +returns `ran:false`, a legitimate skip, not a gap). It is the deterministic React-correctness +gate that also runs in CI as a **required** check (`.github/workflows/react-doctor.yml`, but +there `--scope changed` — only NEW issues). Here it scans the **full** app backlog across the +three workspaces (design/handoff mockups excluded — their vendored `*.jsx` throw ~1054 false +`jsx-no-undef`). A `reactDoctor.ran:false` for a ui/both scope is a **Deferred coverage gap** +(react-doctor couldn't run), not "clean". + --- ## Phase 3 — Consolidate & write reports (Opus) @@ -129,11 +139,14 @@ audit + native label** so nothing is silently relabeled: | Consolidated tier | Maps from | |---|---| | **Blocker** | security Tier 1 · tests Critical · performance Critical · code-quality Critical · ops Blocker | -| **High** | security Tier 2 · tests High · performance High · code-quality High · ops High | +| **High** | security Tier 2 · tests High · performance High · code-quality High · ops High · **react-doctor error** (real React bug: effect cleanup, hydration/browser-global in render, impure updater, prop-callback-in-render, server-auth-actions) | | **Medium** | tests Medium · performance Medium · code-quality Medium · ops Medium | -| **Low / Info** | performance Low/Info · code-quality Low/Info | +| **Low / Info** | performance Low/Info · code-quality Low/Info · **react-doctor warning** (perf/a11y/maintainability nits) | | **Out-of-scope / acknowledged** | security Tier 3 · enterprise-only ops | +Tag each react-doctor finding `[react-doctor · {rule} · {error/warning}]` with its `location` +and `fix`. Group the (typically many) warnings by rule with a count rather than listing each. + ### Report skeleton ```markdown @@ -173,6 +186,7 @@ audit + native label** so nothing is silently relabeled: | 7 | Background durability | … | … | | 8 | Backups | deferred | verify in the DB console | | 9 | Staging | … | … | +| 10 | React correctness (React Doctor) | yes/skipped(api)/deferred | {errorCount errors / warningCount warnings, or "skipped — api scope" / "did not run — deferred"} | ## Deferred ledger (verification-protocol §4) @@ -188,10 +202,13 @@ above — silence reads as coverage.} ### Launch verdict (§5 honesty) — computed, never hardcoded -- **GO** only if **zero Blockers** AND all **9** inventory items produced a verdict (every - audit ran; every ops check resolved or is a legitimately Deferred un-verifiable like backups). +- **GO** only if **zero Blockers** AND all **10** inventory items produced a verdict (every + audit ran; every ops check resolved or is a legitimately Deferred un-verifiable like backups) + AND **react-doctor reports zero errors** (a react-doctor error is a real React bug and the + required CI gate's currency — GO requires the app-code error backlog at zero). - **CONDITIONAL** if no Blockers but some items are Deferred in a way that gates launch (e.g. - backups unverified, staging gate absent) — name the conditions. + backups unverified, staging gate absent, react-doctor errors outstanding, or react-doctor + did not run for a ui/both scope) — name the conditions. - **NO-GO** if any Blocker stands. - **A `failedAudit` forces at most CONDITIONAL and names itself as the blocker** — a partial sweep can never read green. The coverage table makes any non-running audit visible. @@ -213,7 +230,7 @@ above — silence reads as coverage.} | Medium | {N} | | Low / Info | {N} | -**Inventory (9)**: security {ran/deferred} · tests {…} · performance {…} · code-quality {…} · observability {…} · multi-instance {…} · background durability {…} · backups {deferred} · staging {…} +**Inventory (10)**: security {ran/deferred} · tests {…} · performance {…} · code-quality {…} · observability {…} · multi-instance {…} · background durability {…} · backups {deferred} · staging {…} · react-doctor {N errors / M warnings, or skipped-api} **Report**: `.claude/audits/prod-readiness-{scope}.md` **Top blocker**: {the single highest-priority thing standing between here and launch, or "none"} ``` diff --git a/.claude/workflows/prod-readiness.mjs b/.claude/workflows/prod-readiness.mjs index feeeb2bcd1..58808bb163 100644 --- a/.claude/workflows/prod-readiness.mjs +++ b/.claude/workflows/prod-readiness.mjs @@ -4,6 +4,7 @@ export const meta = { phases: [ { title: 'Audits', detail: 'the four /audit workflows in parallel' }, { title: 'Ops', detail: 'observability · multi-instance · background durability · staging' }, + { title: 'React', detail: 'react-doctor full-repo scan of orbit-ui-mobile (ui/both scope)' }, { title: 'Verify', detail: 'skeptic per Blocker/High ops finding — default refuted' }, ], } @@ -49,6 +50,49 @@ const OPS_VERDICT = { const OPS_LADDER = 'Blocker (a whole runtime is dark, or it corrupts user data on scale-out) / High (a single observability gap, a scheduler that double-fires, work lost on restart) / Medium (calibrated — e.g. a missing pre-prod gate)' +// React Doctor — the deterministic React-correctness gate (also a REQUIRED CI check, +// .github/workflows/react-doctor.yml). The CI gate is --scope changed (only NEW issues); +// prod-readiness runs the FULL-repo scan so the whole backlog is surfaced and fixed. +const REACT_DOCTOR_SCHEMA = { + type: 'object', + additionalProperties: false, + properties: { + ran: { type: 'boolean' }, + findings: { + type: 'array', + items: { + type: 'object', + additionalProperties: false, + properties: { + severity: { type: 'string' }, + rule: { type: 'string' }, + category: { type: 'string' }, + location: { type: 'string' }, + message: { type: 'string' }, + fix: { type: 'string' }, + }, + required: ['severity', 'rule', 'location', 'message'], + }, + }, + note: { type: 'string' }, + }, + required: ['ran', 'findings'], +} + +function reactDoctorPrompt() { + return [ + `Run React Doctor over the WHOLE orbit-ui-mobile repo (apps/web + apps/mobile + packages/shared) and report EVERY diagnostic — this is the full backlog, NOT the PR-scoped CI gate.`, + `Steps: cd to ${UI}. Ensure deps are present (node_modules exists; if not, run \`npm ci\`). Then run EXACTLY:`, + ` npx -y react-doctor@0.7.6 --project apps/web,apps/mobile,packages/shared --json --json-out "${REACT_DOCTOR_JSON_OUT}" --no-supply-chain --no-score --no-dead-code --yes --max-duration 360 --no-color`, + `(SCOPE the scan to the three real app workspaces via --project — this EXCLUDES design/handoff/**, whose vendored *.jsx design mockups emit ~1054 false jsx-no-undef "errors" that are NOT app code. --no-dead-code + --no-supply-chain + --no-score match the CI gate's hermetic/no-knip stance; do NOT drop them. Default scope is "full" and --warnings is on, so BOTH error- and warning-severity diagnostics are reported. Paths in the JSON are workspace-relative — prefix each with its project when reporting location.)`, + `Read the JSON report file (${REACT_DOCTOR_JSON_OUT}). For EVERY diagnostic emit a finding: severity ("error" or "warning"), rule (the rule id), category (e.g. Correctness/Performance/Accessibility/Security), location ("apps/…/file.tsx:line"), message (what's wrong), fix (the concrete change — from the rule's guidance; run \`npx react-doctor@0.7.6 why \` if you need the rationale).`, + `Return ran=true with the full findings array — the report derives the error/warning counts from it, so do NOT report an aggregate of your own. This is READ-ONLY analysis — do NOT modify any source file. If react-doctor genuinely cannot run (offline, deps unresolved after npm ci), return ran=false, findings=[], and a one-line note.`, + ].join('\n') +} + +const { tmpdir } = await import('node:os') +const REACT_DOCTOR_JSON_OUT = `${tmpdir().replaceAll('\\', '/')}/rd-prodreadiness.json` + const OPS_CHECKS = [ { check: 'observability', @@ -94,6 +138,14 @@ const rank = (s) => { return 3 } const isSeriousOps = (f) => /blocker|high/i.test(f.severity || '') +const countBy = (findings) => { + const out = {} + for (const f of findings) { + const s = (f.severity || 'unknown').trim() + out[s] = (out[s] || 0) + 1 + } + return out +} const parsedArgs = typeof args === 'string' ? JSON.parse(args) : args || {} const scope = parsedArgs.scope || 'both' @@ -114,6 +166,22 @@ const opsRaw = ( ) ).filter(Boolean).flatMap((r) => r.findings || []) +phase('React') +let reactDoctor = { ran: false, findings: [], note: 'skipped — react-doctor is orbit-ui-mobile-only (scope=api)' } +if (scope !== 'api') { + reactDoctor = + (await agent(reactDoctorPrompt(), { + label: 'react-doctor', + phase: 'React', + agentType: 'general-purpose', + effort: 'low', + schema: REACT_DOCTOR_SCHEMA, + })) || { ran: false, findings: [], note: 'react-doctor agent returned null (died/skipped) — treat as a Deferred coverage gap' } +} +const reactDoctorSeverities = countBy(reactDoctor.findings || []) +reactDoctor.errorCount = reactDoctorSeverities.error || 0 +reactDoctor.warningCount = reactDoctorSeverities.warning || 0 + phase('Verify') const seriousOps = opsRaw.filter(isSeriousOps).sort((a, b) => rank(a.severity) - rank(b.severity)) const opsVerdicts = ( @@ -145,6 +213,7 @@ return { scope, audits: auditResults, opsFindings, + reactDoctor, opsChecksRun: OPS_CHECKS.map((c) => c.check), opsDeferred: [ { check: 'backups', reason: 'un-verifiable from a repo read — verify in the DB console: automated backups / PITR enabled AND a tested restore path' },