Report untouched concepts as gaps, and give breadth a docs home

[sarthakagrawal927]

Closes #79.

The /sweep surface was already ~90% built, and the OpenSpec change the issue body was generated from already existed. The bug itself was never fixed — roi.ts had worked around it with its own local isUnknown, which is why it went unnoticed.

The blind spot

weakConcepts() filtered on mastery[c.id] && (…confidence ?? 1) < 0.6, so a concept the learner had never touched could never be reported as a gap. The app could say you were shaky on something you had studied, but never that you had not covered something at all — which directly defeats a product whose stated goal is breadth.

Replaced by conceptGaps(mastery, limit) returning { concept, kind: 'shaky' | 'uncovered', confidence }:

• shaky — has a mastery row, confidence < 0.6, sorted ascending
• uncovered — no row at all, sorted by sweepOrder imported from sweep.ts (foundations → editorial priority, DRY with triage order)

Shaky is listed first: it decays, whereas uncovered has been at zero all along.

Gaps are deliberately not filtered by prerequisite reachability. Prereq gating reads mastery, so for a learner who has touched nothing, every gap would be filtered straight back out — reintroducing the same blind spot under a new name.

Downstream surfaces, all updated

• src/pages/Progress.tsx — "Weakest concepts" → "Biggest gaps"; uncovered rows read Next: cover X … never opened rather than 0% confident
• src/pages/LearnAll.tsx — WeakAreasPanel → GapsPanel; uncovered cards show new / never opened, a zero-width bar, and a Read CTA to /concepts/:id instead of Review (there is nothing to review); empty state rewritten, since it is now only reachable when the catalogue is fully covered
• src/lib/roi.ts and roi.test.ts — both carried a present-tense comment asserting the recommender cannot see untouched concepts. True when written, false after this change; corrected and pointed at conceptGaps

Verified BuildLab / FeynmanGate use pickNextConcept, not this function, and no e2e test references the changed strings.

The regression test was proven, not assumed

A throwaway probe ran the old implementation against the new assertion and failed with expected 5, received 0 (toHaveLength(5) on weakConceptsOld({}, 5)). Probe deleted after confirming.

Verification

• pnpm test → 486 passed (481 before, 5 new)
• pnpm typecheck → exit 0
• pnpm lint → 401 files, no fixes applied
• pnpm docs:validate → OK (74 markdown files, 10 ADRs, 26 required files)
• pnpm test:coverage → thresholds met; recommend.ts at 73.07%
• pnpm quality:cycles → zero import cycles
• pnpm exec vite build → clean

Not run: pnpm test:e2e (needs a server/browsers) and pnpm build / pnpm ready, which stop at the env gate because .env.local holds empty placeholders — a pre-existing, documented condition.

Doc

docs/product/breadth-sweep.md, 179 lines. Covers why breadth, what was built, rating semantics, the coverage-gap fix and its consuming surfaces, ranking and "no hub" honesty, storage/privacy, the deferred sync, and the spec-after-code process note. Links out to content-pipelines.md#source-hubs, ADR 0004, surfaces.md, and the OpenSpec design.md rather than re-explaining. Registered in docs/index.md, docs/product/overview.md, and the /sweep row in surfaces.md.

Explicitly not done

Cross-device sync is untouched — no schema, handler, or registry change. It needs a schema change and owner review first, per its own design doc.

Open questions

• Should "Known" self-assessments be spot-checked? A wrong self-rating currently never resurfaces, which quietly undermines the breadth model. Open in tasks.md.
• Does /sweep earn a SITE_NAV_ITEMS entry? Costs a ~294-file curriculum regeneration.
• Taste calls made that you may want to overridden: the "Biggest gaps" heading on both surfaces, shaky-before-uncovered ordering, and the uncovered Read CTA targeting /concepts/:id rather than /sweep?domain=<tag>.
• PROJECT_STATUS.md still does not mention Sweep at all; left alone as owner-maintained.

🤖 Generated with Claude Code