# 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`.