* docs: add PRD traceability and work-item hierarchy design (#773)
Design document for first-class traceability layer connecting tasks to
PRD requirements, risks, decisions, and verification evidence.
Key design decisions addressed:
- WorkItemLevel uses 'child-task' not 'subtask' to avoid collision with
existing task.subtasks[] checklist model
- next_safe query evaluates depends_on ∪ blockedBy (covers both modern
dependency graph and legacy blockedBy semantics)
- next_safe forces status=todo; returns 400 on conflicting status filter
- stopConditions includes stopConditionResolved map for machine-queryable
state rather than free-form strings only
- Coverage endpoints introduce optional project requirement/risk catalogs
(POST /api/projects/:id/catalog/{requirements,risks}) to enable true
uncovered-row semantics; without a catalog, total = observed IDs only
- Verification semantics: 'verified' requires done task + checked
verificationSteps or verificationIds (presence alone is insufficient)
- Archive/hierarchy: ON DELETE SET NULL is physical-delete-only; service
layer warns on archiving parents with active children
- Cross-scope parent links rejected at the project level (400)
- SQLite JSON columns for ID arrays with json_each() query model; forward
path to normalized junction tables documented
Changes:
- docs/features/prd-traceability.md — new design doc (958 lines)
- docs/FEATURES.md — add design-draft entry with link to doc
GPT cross-model review addressed before commit.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* docs: fix gated/blocked next-safe exclusion and archive wording consistency
Two semantic contradictions flagged in PR #800 review:
1. next_safe gated exclusion — RiskDisposition.gated is documented as
'this task may not proceed until the gate is cleared' and coverage
treats gated as an open risk, but the algorithm only excluded blocked
and unknown. Fix: exclude blocked and gated always (no override),
exclude unknown unless allow_unknown_risks=true. Updated in:
- next-safe algorithm criterion 6+7
- acceptance criterion #5 and #7
- rollout step 10
- B-5 backlog row
2. Archive wording mismatch — SQLite schema section said 'issues a
warning and requires reparent or cascade archive', but AC #14 said
'warning only'. Resolved as warning-only throughout: archive proceeds
regardless, children retain parentId, response includes
archiveWarning field. Updated in:
- SQLite schema archive semantics prose
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Fix audit follow-up gates
- remove gray-matter and use local YAML frontmatter handling
- upgrade DOMPurify and clear production advisories
- make CLI/MCP smoke skip cleanly without VK_API_KEY
- reduce initial JS below the Mantine QA budget
Closes#753Closes#754Closes#755
