* 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>
- Added explicit audience callouts (👤 humans, 🤖 AI agents)
- Human setup section: prerequisites, step-by-step template creation, testing
- AI execution workflow: complete loop with API calls, error handling, telemetry
- Agent execution examples with bash/curl commands at every step
- Configuration tips: enforcement gates, progress files, retry policies
- Troubleshooting section for common issues
- API reference summary table for quick lookup
- Expanded from 17KB to 28KB with actionable procedures for both audiences
- Created dedicated guide at docs/features/prd-driven-development.md (17KB)
- Added concise summary in FEATURES.md with link to full guide
- Reduced FEATURES.md by 506 lines while preserving all content
- Matches existing features/ directory structure and formatting
- Includes workflow steps, OAuth2 example, configuration tips, when to use/not use
