12 KiB
12 KiB
33 — Requirements traceability
Purpose
Every functional requirement must map to an implementation milestone, automated evidence and final acceptance. A requirement is not complete because a UI exists; its domain, authorization, error and persistence behavior must be tested.
Functional traceability
| Requirement | Outcome | Milestone | Primary evidence |
|---|---|---|---|
FR-LIB-001 |
Index all valid built-in and private playbook versions. | 2 | browser/library + api/search |
FR-LIB-002 |
Search title, summary, tags, category, problem statement and supported stacks. | 2 | browser/library + api/search |
FR-LIB-003 |
Filter by category, lifecycle, risk tier, autonomy support, playbook type, stack and quality status. | 2 | browser/library + api/search |
FR-LIB-004 |
Sort by relevance, recently updated, title and quality status. | 2 | browser/library + api/search |
FR-LIB-005 |
Persist search and filter state in the URL. | 2 | browser/library + api/search |
FR-LIB-006 |
Allow personal favorites and collections. | 2 | browser/library + api/search |
FR-LIB-007 |
Show why a playbook matches a repository or query. | 2 | browser/library + api/search |
FR-LIB-008 |
Prevent deprecated playbooks from appearing as default recommendations. | 2 | browser/library + api/search |
FR-DET-001 |
Show purpose, expected outcome and explicit non-goals. | 2 | browser/detail + api/playbook |
FR-DET-002 |
Show required and optional inputs. | 2 | browser/detail + api/playbook |
FR-DET-003 |
Show supported modes and autonomy levels. | 2 | browser/detail + api/playbook |
FR-DET-004 |
Show risk tier, guardrails, validation and completion contract. | 2 | browser/detail + api/playbook |
FR-DET-005 |
Show compatible stacks and known limitations. | 2 | browser/detail + api/playbook |
FR-DET-006 |
Show version, lifecycle, changelog and quality evidence. | 2 | browser/detail + api/playbook |
FR-DET-007 |
Allow a user to start composition with or without a repository profile. | 2 | browser/detail + api/playbook |
FR-REP-001 |
Create profiles manually without connecting a forge. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-002 |
Store languages, frameworks, package managers, services, databases and deployment types. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-003 |
Store setup, lint, typecheck, test, build and smoke-test commands. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-004 |
Store protected paths, excluded paths and policy constraints. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-005 |
Store source metadata and evidence timestamp. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-006 |
Version profile snapshots for generated runs. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-007 |
Import and export a schema-validated profile. | 3 | domain/profile + api/repository + browser/profile |
FR-REP-008 |
Allow manual overrides without destroying source observations. | 3 | domain/profile + api/repository + browser/profile |
FR-COM-001 |
Resolve playbook inputs through a guided form. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-002 |
Select a repository profile or operate profile-free. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-003 |
Select work mode and autonomy level. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-004 |
Select or confirm scope and protected paths. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-005 |
Preview generated output continuously. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-006 |
Explain the provenance of each generated block. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-007 |
Validate required inputs and compatibility before export. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-008 |
Run prompt lint and distinguish errors from warnings. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-009 |
Autosave a draft locally or server-side. | 4 | composer/unit + composer/property + browser/composer |
FR-COM-010 |
Produce deterministic output from normalized inputs. | 4 | composer/unit + composer/property + browser/composer |
FR-OUT-001 |
Copy plain prompt text. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-002 |
Download Markdown. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-003 |
Generate a ZIP Run Pack with manifest and digests. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-004 |
Optionally generate AGENTS.md recommendations without overwriting an existing file. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-005 |
Store an immutable run snapshot. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-006 |
Re-render a historical run without silently using a newer playbook version. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-007 |
Re-import a Run Pack and verify its manifest. | 5 | artifact/integration + archive/security + browser/export |
FR-OUT-008 |
Ensure safe filenames and prevent archive traversal. | 5 | artifact/integration + archive/security + browser/export |
FR-AUT-001 |
Import a Playbook Package from a directory or ZIP. | 7 | content-import + browser-prompt-lab |
FR-AUT-002 |
Validate structural and semantic rules. | 7 | content-import + browser-prompt-lab |
FR-AUT-003 |
Edit private drafts in a schema-aware editor. | 7 | content-import + browser-prompt-lab |
FR-AUT-004 |
Render examples with test input sets. | 7 | content-import + browser-prompt-lab |
FR-AUT-005 |
Publish by creating an immutable semantic version. | 7 | content-import + browser-prompt-lab |
FR-AUT-006 |
Compare versions and require a changelog. | 7 | content-import + browser-prompt-lab |
FR-AUT-007 |
Deprecate without deleting historical versions. | 7 | content-import + browser-prompt-lab |
FR-AUT-008 |
Export a complete package for Git review. | 7 | content-import + browser-prompt-lab |
FR-GIT-001 |
Configure a Gitea base URL and token. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-002 |
Test connectivity and discover server version/capabilities. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-003 |
List accessible repositories with pagination. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-004 |
Import repository metadata and selected governance evidence. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-005 |
Read relevant files through a bounded allowlist and size limits. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-006 |
Create a timestamped repository snapshot. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-007 |
Recommend playbooks based on observable gaps. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-GIT-008 |
Remain strictly read-only in the first implementation. | 6 | gitea/contract + ssrf/security + browser/integration |
FR-QUA-001 |
Lint playbooks and rendered prompts. | 7 | lint/unit + evaluation/integration |
FR-QUA-002 |
Store evaluation cases tied to exact versions. | 7 | lint/unit + evaluation/integration |
FR-QUA-003 |
Show quality dimensions separately rather than one unexplained percentage. | 7 | lint/unit + evaluation/integration |
FR-QUA-004 |
Distinguish authored claims from executed evidence. | 7 | lint/unit + evaluation/integration |
FR-QUA-005 |
Mark stale evidence when its environment or fixture changes. | 7 | lint/unit + evaluation/integration |
FR-QUA-006 |
Block “Validated” status without required evidence. | 7 | lint/unit + evaluation/integration |
FR-ADM-001 |
Show integration health and background-job failures. | 8 | authorization/integration + operations/browser |
FR-ADM-002 |
Record security-relevant audit events. | 8 | authorization/integration + operations/browser |
FR-ADM-003 |
Allow export and deletion of user-owned data. | 8 | authorization/integration + operations/browser |
FR-ADM-004 |
Configure retention for generated artifacts and logs. | 8 | authorization/integration + operations/browser |
FR-ADM-005 |
Expose backup and restore guidance. | 8 | authorization/integration + operations/browser |
Non-functional traceability
| Area | Primary implementation evidence | Release evidence |
|---|---|---|
| Reliability | idempotency, transaction, lease and immutable-snapshot integration tests | restart and partial-failure drills |
| Performance | indexed search, composition and artifact benchmarks with recorded hardware/data | P95 report against stated targets |
| Security | authorization, archive, XSS, CSRF, SSRF, redaction and secret-envelope tests | dependency/secret scans and threat-model review |
| Privacy | data inventory, retention and export/delete integration tests | operator privacy and backup review |
| Accessibility | component checks plus keyboard and screen-reader-oriented browser flows | WCAG 2.2 AA evidence for core screens |
| Maintainability | dependency-boundary checks, strict typecheck and migration tests | architecture review and clean-room build |
| Deterministic composition | 28 golden prompt conformance tests plus digest checks | cross-platform fixture verification and historical run replay |
Milestone 1 enabling-contract evidence
Milestone 1 intentionally completes domain and persistence prerequisites rather than prematurely closing later end-user requirements. The following requirements remain assigned to their authoritative milestones, but now have these proven foundations:
| Requirement area | Milestone 1 foundation | Durable evidence |
|---|---|---|
| Library indexing, search and deprecation | Immutable indexed versions, lifecycle-aware current recommendation, typed search and combined filters. | packages/db/src/playbooks/playbook-catalog.test.ts, PostgreSQL integration and docs/44-milestone-one-package-ingestion.md |
| Playbook detail and version evidence | Current manifest/template/quality plus full version history and exact-version API reads. | catalog unit tests, live detail/exact-version API and browser detail evidence |
| Package structural and semantic validation | Canonical schema and semantic validator with actionable structured issues. | packages/content/src/index.test.ts, pack validator and seed-catalog cross-check |
These are partial trace links, not completed requirement statuses. Milestone 2 must still prove the Library and detail user experience; Milestone 7 must still prove private package import and Prompt Lab validation flows.
Milestone 2 end-user evidence
Milestone 2 completes the library search, filter, sort, URL-state, match-reason
and deprecation requirements plus the first six detail requirements for the
authenticated runtime catalog. Durable evidence is recorded in
docs/45-milestone-two-library-explorer.md, the catalog/API unit suites and the
23-pass production Playwright matrix at commit 3397226.
The first library requirement remains partial until private package authoring/import is proven. The sixth library requirement remains partial: persisted personal favorites are complete, named collections are not. The seventh detail requirement remains partial because the exact version/digest handoff is complete while guided composition belongs to Milestone 4. These open portions are not accepted exceptions and remain in the final acceptance matrix.
Milestone exit rule
At the end of each milestone, CURRENT_STATE.md must list the requirement IDs completed and the exact test or browser evidence. A requirement with only partial implementation remains open. Accepted exceptions need an owner, rationale, expiry/review date and impact.
Final release matrix
The release report must use the schema and pre-populated template defined in document 41. It must export a machine-readable matrix with fields: requirementId, status, commit, testEvidence, browserEvidence, exceptionId, notes. Valid statuses are passed, failed, blocked, not-applicable and accepted-exception.