feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs

Navigation:
- New order: Overview · Todo · Domains · Repos · Workstreams (collapsible,
  open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends,
  Dependencies) · Contributions · SBOM · Progress · Reference (collapsible)
- Reference section gains path:/reference landing page; all 18 doc pages
  listed in nav (alphabetical) and in reference.md table

New pages:
- todo.md — Internal / Ecosystem / Third-party todo classification
- dependencies.md — dependency edge table derived from state/summary
- reference.md — Reference landing page with full doc index

New reference doc pages (11):
  contributions, debt, dependencies, domains, extensions, overview,
  repos, tasks, todo + reference (meta) already added previously

doc-overlay.js — lazy bubblehelp tooltip:
- _titleCache Map + _fetchDocTitle(docPath): on first hover of any ?
  button, fetches the target doc page, parses <h1>, sets btn.title
- Native browser tooltip appears exactly on the ? circle on subsequent hover

Context-help wired on all 14 dashboard pages:
- h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept,
  extensions, dependencies (contributions/workstreams/decisions/sbom/
  progress/reference were already wired)
- domains.md + repos.md: added missing withDocHelp import and live-data link
- tasks/techdept/extensions: removed duplicate _h1 const that caused
  SyntaxError: Identifier '_h1' has already been declared

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-03-01 23:46:26 +01:00
parent 894c8b3934
commit 235355eb58
22 changed files with 1468 additions and 25 deletions

View File

@@ -0,0 +1,91 @@
---
title: Technical Debt — Reference
---
# Technical Debt — Reference
The Technical Debt page tracks known quality compromises across all six project
domains — intentional shortcuts, design weaknesses, missing tests, and similar
issues that reduce codebase health but have been consciously deferred.
---
## Debt types
| Type | Examples |
|------|---------|
| **design** | Architectural decisions that should be revisited |
| **implementation** | Hacky or fragile code that works but shouldn't stay |
| **test** | Missing or incomplete test coverage |
| **docs** | Missing or outdated documentation |
| **dependencies** | Pinned old versions, unused packages, missing lockfiles |
| **performance** | Known bottlenecks not yet worth addressing |
| **security** | Hardcoded values, missing input validation, weak auth |
| **other** | Anything that doesn't fit the above |
---
## Severity levels
| Severity | Meaning |
|----------|---------|
| **critical** | Blocks release or poses an active risk |
| **high** | Should be resolved before the next major milestone |
| **medium** | Normal triage priority |
| **low** | Nice-to-fix; acceptable to defer indefinitely |
---
## Statuses
| Status | Meaning |
|--------|---------|
| **open** | Known and unaddressed |
| **in_progress** | Being actively worked on |
| **deferred** | Acknowledged but intentionally postponed |
| **resolved** | Fixed |
| **wont_fix** | Accepted as permanent — documented for future reference |
Items are sorted by status (open → in_progress → deferred → resolved → wont_fix)
then by severity (critical → high → medium → low) within each group.
---
## Filters
| Filter | Effect |
|--------|--------|
| **Status** | Multi-select |
| **Severity** | Multi-select |
| **Domain** | Multi-select |
| **Type** | Multi-select |
---
## Registering debt
Via MCP:
```
register_technical_debt(
domain = "custodian",
title = "Hard-coded API URL in data loaders",
debt_type = "implementation",
severity = "high",
description = "All data loaders use http://127.0.0.1:8000 directly. Should read from an env var or config.",
location = "state-hub/dashboard/src/data/*.json.py",
workstream_id = "<uuid>" # optional
)
```
```
update_td_status(td_uuid="<uuid>", status="resolved")
```
---
## Human-readable IDs
Each debt item carries a human-readable ID in the form `TD-<DOMAIN>-NNN`
(e.g. `TD-CUST-001`). IDs are optional at creation and auto-assigned if omitted.
They appear in the table for easy reference in commit messages and comments.