@zigrivers/scaffold 2.38.1 → 2.44.3

package/knowledge/core/eval-craft.md

@@ -1006,3 +1006,47 @@ Style observations, minor inconsistencies, documentation improvements. Not actio
 - "3 documentation files have no cross-references from other docs (possibly orphaned)"
 - "Coverage eval matched 'user profile' by file name only, not by test content — confidence is low"
 - "Makefile has 2 targets not listed in CLAUDE.md Key Commands, but they start with `_` (internal targets)"
+
+### Per-Category Implementation Guidance
+
+Concrete checks to implement for each eval category. For each category, these are the highest-value grep/scan targets.
+
+#### Adherence
+
+- **Naming conventions**: Grep source files for patterns that violate documented naming (e.g., `camelCase` in a `snake_case` project, uppercase constants that should be enums)
+- **Error handling patterns**: Scan for bare `catch {}`, swallowed errors (`catch (e) { /* ignore */ }`), and missing error propagation per `docs/coding-standards.md`
+- **Import rules**: Check for barrel import violations, circular imports, and forbidden cross-layer imports (e.g., UI importing directly from DB layer)
+- **TODO hygiene**: Grep for `TODO|FIXME|HACK` without a task ID tag like `[BD-xxx]` — untagged TODOs are tracking gaps
+
+#### Consistency
+
+- **Cross-doc refs match**: Extract all file path references from markdown docs (`docs/*.md`) and verify each referenced path exists on disk
+- **Format standardization**: Verify commit messages follow the documented pattern in `docs/coding-standards.md` by regex-matching `git log --oneline`
+- **Command table sync**: Parse the Key Commands table in `CLAUDE.md`, extract each backtick-quoted command, and verify a matching Makefile target or package.json script exists
+- **Config value consistency**: Check that port numbers, env var names, and feature flags in config files match what documentation describes
+
+#### Structure
+
+- **File placement rules**: For each source file, verify its directory matches the module placement rules in `docs/project-structure.md` (e.g., no feature code in `shared/`, no stray files in root)
+- **Test co-location**: For each source file with logic, verify a corresponding `.test.*` file exists per the documented convention (co-located or mirror directory)
+- **Shared code 2+ consumers**: Scan every file in `shared/`, `common/`, or `lib/` directories and count distinct importers — flag any with fewer than 2 consumers
+- **No orphan files**: Verify every source file is either imported by another file or is a documented entry point (main, index, CLI handler)
+
+#### Coverage
+
+- **Feature-to-code mapping**: Extract Must-have features from `docs/plan.md`, derive domain keywords, and grep source tree for 2+ keyword matches per feature
+- **AC-to-test mapping**: Extract acceptance criteria from `docs/user-stories.md`, extract keywords, and search test files for keyword co-occurrence (high confidence: exact AC ID reference; medium: 2+ domain keywords)
+- **API endpoint coverage**: Parse documented endpoints from `docs/api-contracts.md`, verify each has a route definition in code and at least one test file asserting its status codes
+
+#### Cross-doc
+
+- **Terminology consistency**: Extract key domain terms from the PRD and verify the same terms (not synonyms) appear in architecture, user stories, and coding standards docs
+- **Tech stack references**: Verify that technology names referenced across docs match the canonical list in `docs/tech-stack.md` (e.g., no doc says "Postgres" when the canonical name is "PostgreSQL")
+- **Path consistency**: Collect all file path references across all docs and verify they use the same path format (no mix of `src/features/` and `features/src/`)
+
+#### Security
+
+- **Auth middleware usage**: Parse the security review for protected routes, then verify each route definition includes auth middleware (`requireAuth`, `@authenticated`, or equivalent)
+- **Secret patterns**: Grep for hardcoded API keys, tokens, and passwords using known patterns (`AKIA...`, `sk_live_...`, `ghp_...`, and generic `password\s*=\s*['"][^'"]+`)
+- **Input validation**: For each API endpoint accepting user input, verify a validation step exists (Zod `.parse()`, Joi `.validate()`, express-validator chain, or equivalent)
+- **No secrets in git**: Run `git log --diff-filter=A --name-only` and check that no `.env`, credentials, or key files were ever committed

package/knowledge/core/multi-model-review-dispatch.md

@@ -176,6 +176,14 @@ When models actively disagree (one flags an issue, another says the same thing i
 3. **Default to the stricter interpretation.** If genuinely ambiguous, the finding stands at reduced severity (P1 → P2).
 4. **Document the disagreement.** The reconciliation report should note: "Models disagreed on [topic]. Resolution: [decision and rationale]."
 
+### Consensus Classification
+
+When synthesizing multi-model findings, classify each finding:
+- **Consensus**: All participating models flagged the same issue at similar severity → report at the agreed severity
+- **Majority**: 2+ models agree, 1 dissents → report at the lower of the agreeing severities; note the dissent
+- **Divergent**: Models disagree on severity or one model found an issue others missed → present to user for decision, minimum P2 severity
+- **Unique**: Only one model raised the finding → include with attribution, flag as "single-model finding" for user review
+
 ### Output Format
 
 #### Review Summary (review-summary.md)

package/knowledge/core/system-architecture.md

@@ -85,6 +85,45 @@ For most scaffold pipeline projects:
 
 ## Deep Guidance
 
+## Reading ADRs to Derive Architectural Constraints
+
+The `system-architecture` pipeline step consumes ADR decision records as direct inputs. Each accepted ADR represents a binding constraint on the architecture — not a suggestion, but a committed decision that component choices must honor.
+
+### How to Extract Constraints from ADRs
+
+For each ADR, read the **Decision** and **Consequences** sections:
+
+1. **Identify the affected component scope.** An ADR about the database engine constrains the data access layer and all repository implementations. An ADR about the messaging system constrains all async communication patterns.
+2. **Extract the affirmative constraint.** "We will use PostgreSQL" → every database component must use the `pg` driver (Node.js) or `psycopg2` (Python), not a generic ORM that could target SQLite.
+3. **Extract the prohibitive constraint.** "We will not use a microservice architecture" → no service discovery, no inter-service REST calls, no per-service databases.
+4. **Note the rationale.** If an ADR says "because of GDPR data residency requirements," this rationale extends to related decisions not explicitly stated in the ADR (e.g., no third-party analytics SDKs that exfiltrate data).
+
+### Mapping ADR Outcomes to Component Decisions
+
+Document constraints inline with component definitions:
+
+```
+Component: UserRepository
+Constraint source: ADR-003 (PostgreSQL as the database)
+Implementation requirement: Must use pg driver. ORM must target PostgreSQL dialect.
+  Cannot use SQLite, MySQL, or a generic query builder that doesn't validate SQL dialect.
+
+Component: NotificationService
+Constraint source: ADR-007 (async via Redis pub/sub, not a message broker)
+Implementation requirement: Must use ioredis for pub/sub.
+  Cannot use RabbitMQ, Kafka, or in-process EventEmitter for cross-service notifications.
+```
+
+### Cross-Referencing ADR Status
+
+ADR status affects how strictly to apply constraints:
+
+- **Accepted**: Binding. The architecture must comply. Any component that would violate this decision requires a new ADR to supersede it.
+- **Proposed**: Treat as intended but not yet locked. Note the dependency — if the ADR is rejected, the architecture may need revision.
+- **Deprecated** or **Superseded**: The old constraint no longer applies; the superseding ADR's constraint applies instead. Remove any component requirements derived from the deprecated ADR.
+
+When a component's implementation would conflict with an accepted ADR, that conflict must be surfaced explicitly — either by revising the component design or by drafting a new ADR before proceeding.
+
 ## Component Design
 
 ### Identifying Components from Domain Models

package/knowledge/core/task-decomposition.md

@@ -508,3 +508,56 @@ If a task genuinely can't be split further without creating tasks that have no i
 **Premature shared utilities.** Creating "shared utility library" tasks before any feature needs them. This produces speculative abstractions that don't fit actual use cases. Fix: shared code emerges from feature work. Only create shared utility tasks after two or more features demonstrate the need.
 
 **Ignoring the critical path.** Assigning agents to low-priority tasks while critical-path tasks wait for resources. Fix: always prioritize critical-path tasks. Non-critical tasks are parallelized around the critical path, not instead of it.
+
+### Critical Path and Wave Planning
+
+#### Identifying the Critical Path
+
+The critical path is the longest chain of sequentially dependent tasks from project start to finish. To find it:
+
+1. **Build the full DAG** — list every task and its dependencies (logical, file contention, infrastructure)
+2. **Assign effort estimates** — use story points or hours per task
+3. **Trace all paths** — walk from every root node (no dependencies) to every leaf node (no dependents)
+4. **Sum each path** — the path with the highest total effort is the critical path
+5. **Mark float** — non-critical tasks have float equal to (critical path length - their path length); they can slip by that amount without delaying the project
+
+Critical path tasks get top priority for agent assignment. Delays on these tasks delay the entire project; delays on non-critical tasks do not (up to their float).
+
+#### Wave Planning
+
+Waves group independent tasks for parallel execution. Each wave starts only after its dependency wave completes.
+
+```
+Wave 0: Project infrastructure (DB setup, CI pipeline, auth scaffold)
+Wave 1: Core data models, base API framework, design tokens
+Wave 2: Feature endpoints, UI components, middleware (per-feature)
+Wave 3: Integration flows, cross-feature wiring, E2E test scaffolds
+Wave 4: Polish, performance, E2E tests, documentation finalization
+```
+
+**Rules for wave construction:**
+- A task belongs to the earliest wave where all its dependencies are satisfied
+- Tasks within a wave have zero dependencies on each other
+- The number of useful parallel agents equals the task count of the widest wave
+- If one wave has 8 tasks and the next has 2, consider whether splitting wave-2 tasks could improve parallelism
+
+#### Agent Allocation by Wave
+
+Assign agents based on task type to maximize context reuse within an agent session:
+
+- **Backend agents** — API endpoints, database migrations, service logic. Context: architecture doc, API contracts, coding standards
+- **Frontend agents** — UI components, pages, client-side state. Context: UX spec, design system, component patterns
+- **Infrastructure agents** — CI/CD, deployment, config, monitoring. Context: dev setup, operations runbook
+- **Cross-cutting agents** — Auth, error handling, shared utilities. Context: security review, coding standards
+
+An agent working consecutive tasks of the same type retains relevant context and produces more consistent output.
+
+#### Parallelization Signals
+
+Tasks are safe to run in parallel when they share no file dependencies. Quick checklist:
+
+- **Different feature directories** — `src/features/auth/` vs `src/features/billing/` can always parallelize
+- **Different layers of different features** — backend auth + frontend billing have no file overlap
+- **Same feature, different layers** — only if the interface contract is agreed upfront (API shape, component props)
+- **Same file touched** — must be sequenced, no exceptions (merge conflicts are expensive)
+- **Shared utility creation** — block until the utility task merges, then dependents can parallelize

package/knowledge/core/testing-strategy.md

@@ -397,6 +397,166 @@ Initial data loaded into the test database for integration tests. Rules:
 
 **No test naming convention.** Test descriptions like "test 1," "works correctly," or "handles the thing." Uninformative when tests fail. Fix: test names should describe the scenario and expected outcome: "returns 404 when user does not exist," "applies 10% discount for premium members."
 
+### From Acceptance Criteria to Test Cases
+
+Acceptance criteria are the bridge between user stories and automated tests. Every AC should produce one or more test cases with clear traceability.
+
+#### Given/When/Then to Arrange/Act/Assert
+
+The mapping is direct:
+
+- **Given** (precondition) becomes **Arrange** — set up test data, mock dependencies, configure state
+- **When** (action) becomes **Act** — call the function, hit the endpoint, trigger the event
+- **Then** (expected outcome) becomes **Assert** — verify return value, check database state, assert response body
+
+```typescript
+// AC: Given a user with 5 failed login attempts,
+//     When they attempt a 6th login,
+//     Then the account is locked and they see "Account locked"
+it('locks account after 5 failed attempts', async () => {
+  // Arrange: create user with 5 failed attempts
+  const user = await createUser({ failedAttempts: 5 });
+  // Act: attempt login
+  const res = await request(app).post('/login').send({ email: user.email, password: 'wrong' });
+  // Assert: locked
+  expect(res.status).toBe(423);
+  expect(res.body.error.message).toContain('Account locked');
+});
+```
+
+#### One AC, Multiple Test Cases
+
+Each AC produces at minimum one happy-path test. Then derive edge cases:
+
+- **Boundary values**: If the AC says "max 50 characters," test 49, 50, and 51
+- **Empty/null inputs**: If the AC assumes input exists, test what happens when it does not
+- **Concurrency**: If the AC describes a state change, test what happens with simultaneous requests
+
+#### Negative Case Derivation
+
+For every "Given X" in an AC, systematically test "Given NOT X":
+
+- AC says "Given user is authenticated" — test unauthenticated access (expect 401)
+- AC says "Given the order exists" — test with nonexistent order ID (expect 404)
+- AC says "Given valid payment details" — test with expired card, insufficient funds, invalid CVV
+
+#### Parameterized Tests for Similar ACs
+
+When multiple ACs follow the same pattern with different inputs, use data-driven tests:
+
+```typescript
+it.each([
+  ['empty email', { email: '', password: 'valid' }, 'Email is required'],
+  ['invalid email', { email: 'notanemail', password: 'valid' }, 'Invalid email format'],
+  ['short password', { email: 'a@b.com', password: '123' }, 'Password too short'],
+])('rejects registration with %s', async (_, input, expectedError) => {
+  const res = await request(app).post('/register').send(input);
+  expect(res.status).toBe(400);
+  expect(res.body.error.message).toContain(expectedError);
+});
+```
+
+#### Test Naming for Traceability
+
+Test names should mirror the AC wording so that when a test fails, the team can trace it back to the requirement without reading the test body:
+
+- AC: "User sees error when email is already taken" — Test: `'returns 409 when email is already taken'`
+- AC: "Profile updates immediately after save" — Test: `'updates profile and reflects changes on next fetch'`
+- Include the story or AC ID in the describe block when practical: `describe('US-002: Edit profile', () => { ... })`
+
+### Pending Test Syntax and Skeleton-to-TDD Workflow
+
+#### Pending Test Syntax
+
+A pending test (also called a test skeleton or todo test) marks a test case that is known to be needed but not yet implemented. It fails intentionally, serving as a reminder and a contract — CI will report it, nobody can accidentally claim the work is done.
+
+**TypeScript / Jest:**
+```typescript
+// it.todo() — built-in pending marker; no callback needed
+it.todo('returns 404 when user does not exist');
+it.todo('rejects payment with expired card');
+
+// xit() / xdescribe() — skipped test with a body (useful to sketch logic first)
+xit('locks account after 5 failed login attempts', async () => {
+  // stub: arrange/act/assert goes here
+});
+```
+
+**Python / pytest:**
+```python
+import pytest
+
+@pytest.mark.skip(reason="not yet implemented — US-014 payment failure handling")
+def test_rejects_expired_card():
+    pass  # implementation stub
+
+# Or with pytest-todo plugin:
+@pytest.mark.todo
+def test_sends_confirmation_email_on_order():
+    pass
+```
+
+**Go / testing:**
+```go
+func TestRejectsExpiredCard(t *testing.T) {
+    t.Skip("not yet implemented — US-014")
+}
+```
+
+**Bats (shell):**
+```bash
+@test "rejects request without auth token" {
+  skip "not yet implemented — US-007"
+}
+```
+
+The key property of a pending test: it must be **visible in CI output** (not silently ignored) and **clearly labeled** with the story or AC it corresponds to.
+
+#### Skeleton-to-TDD Workflow
+
+The skeleton-to-TDD workflow takes user stories all the way to passing tests through four explicit stages:
+
+1. **Story → Acceptance Criteria.** Extract the Given/When/Then conditions from the user story. Each condition becomes a candidate test.
+2. **Acceptance Criteria → Pending Tests.** Write one `it.todo()` (or language equivalent) per AC. Name each test after the AC's expected outcome. Commit. CI now shows red for all pending tests — this is the intended state.
+3. **Pending Test → Failing Test.** For one pending test at a time: fill in the Arrange/Act/Assert body. Remove `.todo`. Run tests — the test must fail (because the implementation doesn't exist yet). If it passes immediately, the test is not testing anything real.
+4. **Failing Test → Passing Test.** Write the minimum implementation to make the failing test pass. No speculative code. Run tests — green. Commit.
+
+Repeat steps 3-4 for each pending test. When all pending tests for a story are passing, the story is done.
+
+**Example progression for US-014: "User sees error when paying with expired card":**
+
+```
+Stage 1: AC derived → "given expired card, POST /checkout returns 402 with error.code CARD_EXPIRED"
+Stage 2: it.todo('returns 402 CARD_EXPIRED for expired card')    ← CI: pending
+Stage 3: it('returns 402 CARD_EXPIRED for expired card', ...) { ... } ← CI: failing
+Stage 4: PaymentService.charge() → check expiry → throw CardExpiredError   ← CI: passing
+```
+
+#### story-tests-map.md Format
+
+The `story-tests-map.md` file provides a traceability matrix linking user stories to the test files and test names that verify them. It lives in the project root or `docs/` directory.
+
+**Minimal format (Markdown table):**
+
+```markdown
+# Story-to-Tests Map
+
+| Story ID | Story Title                | Test File                              | Test Name(s)                                              | Status   |
+|----------|----------------------------|----------------------------------------|-----------------------------------------------------------|----------|
+| US-001   | User registers account     | tests/auth/register.test.ts            | creates user and returns 201                              | passing  |
+| US-001   | User registers account     | tests/auth/register.test.ts            | returns 409 when email already exists                     | passing  |
+| US-002   | User logs in               | tests/auth/login.test.ts               | returns JWT on valid credentials                          | passing  |
+| US-002   | User logs in               | tests/auth/login.test.ts               | returns 401 on invalid password                           | passing  |
+| US-014   | Payment with expired card  | tests/checkout/payment.test.ts         | returns 402 CARD_EXPIRED for expired card                 | pending  |
+| US-014   | Payment with expired card  | tests/checkout/payment.test.ts         | returns 402 INSUFFICIENT_FUNDS for declined card          | pending  |
+```
+
+**Rules for maintaining the map:**
+- Every user story must have at least one row (even if all tests are pending)
+- The `Status` column reflects the current CI state: `passing`, `failing`, or `pending`
+- When a test is renamed or moved, update the map in the same commit
+- The map is machine-readable — keep it parseable (consistent column counts, no merged cells)
+
 ## See Also
 
 - [api-design](../core/api-design.md) — Contract testing patterns

package/knowledge/finalization/implementation-playbook.md

@@ -69,14 +69,19 @@ If a task does not have a context brief, the agent should create one from the sp
 
 When a per-task context block is incomplete, agents should consult this taxonomy to ensure they have sufficient context:
 
+**Before starting any task**, check `docs/story-tests-map.md` to find test skeletons for your task's user stories. If test skeletons exist, begin TDD with those pending tests rather than writing new ones.
+
 | Task Type | Required Docs | Additional Context |
 |-----------|--------------|-------------------|
-| Backend API | `docs/api-contracts.md`, `docs/database-schema.md`, `docs/domain-models/`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Relevant ADR for API style choices |
-| Frontend UI | `docs/ux-spec.md`, `docs/design-system.md`, `docs/api-contracts.md`, `docs/coding-standards.md`, `docs/tdd-standards.md` | Component patterns from design system |
-| Database migration | `docs/database-schema.md`, `docs/domain-models/`, `docs/operations-runbook.md` | Rollback strategy from ops runbook |
-| Infrastructure/CI | `docs/dev-setup.md`, `docs/git-workflow.md`, `docs/operations-runbook.md` | Deployment pipeline stages |
-| Bug fix | Relevant source code, `docs/tdd-standards.md`, `docs/coding-standards.md` | Related test files, reproduction steps |
-| Security hardening | `docs/security-review.md`, `docs/api-contracts.md`, `docs/coding-standards.md` | OWASP checklist items from security review |
+| Backend API | `docs/api-contracts.md`, `docs/database-schema.md`, `docs/domain-models/`, `docs/coding-standards.md`, `docs/tdd-standards.md`, `docs/story-tests-map.md` | Relevant ADR for API style choices, `tests/acceptance/` skeletons |
+| Frontend UI | `docs/ux-spec.md`, `docs/design-system.md`, `docs/api-contracts.md`, `docs/coding-standards.md`, `docs/tdd-standards.md`, `docs/story-tests-map.md` | Component patterns from design system, `tests/acceptance/` skeletons |
+| Database migration | `docs/database-schema.md`, `docs/domain-models/`, `docs/operations-runbook.md`, `docs/story-tests-map.md` | Rollback strategy from ops runbook, `tests/acceptance/` skeletons |
+| Infrastructure/CI | `docs/dev-setup.md`, `docs/git-workflow.md`, `docs/operations-runbook.md`, `docs/story-tests-map.md` | Deployment pipeline stages |
+| Bug fix | Relevant source code, `docs/tdd-standards.md`, `docs/coding-standards.md`, `docs/story-tests-map.md` | Related test files, reproduction steps, `tests/acceptance/` skeletons |
+| Security hardening | `docs/security-review.md`, `docs/api-contracts.md`, `docs/coding-standards.md`, `docs/story-tests-map.md` | OWASP checklist items from security review, `tests/acceptance/` skeletons |
+| Refactoring | `docs/coding-standards.md`, `docs/system-architecture.md` (if available), `docs/domain-models/` (if available), `docs/story-tests-map.md` | All existing tests pass; no behavior change verified |
+| Performance | `docs/system-architecture.md`, `docs/operations-runbook.md` (if available), `docs/story-tests-map.md` | Benchmark comparison before/after; make check passes |
+| E2E / Integration | `docs/tdd-standards.md`, `tests/acceptance/` (if available), `docs/api-contracts.md` (if available), `docs/story-tests-map.md` | E2E tests pass; make check passes |
 
 ## Deep Guidance
 
@@ -460,6 +465,16 @@ When `make eval` fails during implementation:
    - **Security evals**: Missing input validation or auth check. Fix: add the missing security control per security-review.md.
 4. **If eval seems wrong**: Check if the eval itself is outdated. Flag for upstream review rather than working around it.
 
+**Eval Failure → Root Cause Reference**:
+
+| Eval Category | Root Cause Doc | What to Check |
+|---------------|---------------|---------------|
+| Adherence | `docs/coding-standards.md` | The specific pattern or convention that was violated |
+| Consistency | Cross-doc references | Naming, paths, and commands match across all documents |
+| Structure | `docs/project-structure.md` | File placement rules, directory conventions |
+| Coverage | `docs/story-tests-map.md` | Missing acceptance-criteria-to-test mapping |
+| Security | `docs/security-review.md` | The specific security control that was violated |
+
 **Spec gap discovered during implementation:**
 1. Document the gap with specific details (what's missing, what's needed)
 2. Check if an ADR or architecture decision covers the case
@@ -476,7 +491,9 @@ When `make eval` fails during implementation:
 
 When a task's upstream dependency hasn't merged or has failed:
 
-1. **Check the dependency task status** in docs/implementation-plan.md
+1. **Check the dependency task status** — Look at git branch status (`git log --oneline origin/main..origin/<branch>`), PR state (`gh pr view <branch>`), or the task tracking system (Beads `bd show <task-id>` / `docs/implementation-plan.md` status column) to determine whether the dependency is in-progress, merged, failed, or blocked.
 2. **If in-progress**: Wait for it to merge. Do not start work that depends on uncommitted changes.
 3. **If failed/blocked**: Flag for human review. The task may need to be reworked, reordered, or its dependency removed.
 4. **If the dependency is in a different agent's worktree**: Coordinate via AGENTS.md or the task tracking system. Never duplicate work.
+5. **Max wait**: If blocked for more than 30 minutes, find an unblocked task from the implementation plan and work on that instead. Do not idle.
+6. **Escalation**: If no unblocked tasks remain, document the blocker in a PR comment (or Beads note) and notify via AGENTS.md or the project's communication channel so the blocker is visible to all agents and the project owner.

package/knowledge/product/prd-craft.md

@@ -343,3 +343,44 @@ Before considering a PRD complete:
 - [ ] Competitive context is provided
 - [ ] The PRD says WHAT, not HOW
 - [ ] Every stakeholder group has been considered (end users, admins, support, integrators)
+
+### Non-Functional Requirements — Specification and Quantification
+
+Every NFR must have three components: a **measurable target**, a **measurement method**, and an **acceptable threshold**. Without all three, an NFR is aspirational, not actionable.
+
+#### Performance
+
+- **Response time**: Specify percentile targets — e.g., "API p95 < 200ms, p99 < 500ms for read operations; p95 < 500ms for writes"
+- **Throughput**: Define sustained request rate — e.g., "System handles 500 requests/second under normal load"
+- **Concurrent users**: State peak capacity — e.g., "10,000 simultaneous authenticated sessions without degradation"
+- **Measurement**: Name the tool and method — "Measured via k6 load test against staging, run nightly in CI"
+
+#### Security
+
+- **Compliance standards**: Name the specific standards — OWASP Top 10, SOC2 Type II, PCI DSS Level 1, HIPAA
+- **Authentication requirements**: Specify method and strength — "OAuth 2.0 + PKCE, session timeout 30 min, MFA for admin roles"
+- **Data classification**: Label data tiers — "PII (encrypted at rest AES-256, in transit TLS 1.3), public (CDN-cacheable)"
+- **Audit logging**: Define what is logged — "All auth events, all data mutations, all admin actions; retained 90 days"
+
+#### Scalability
+
+- **Growth targets**: Quantify the horizon — "Support 10x current load within 12 months without architecture changes"
+- **Scaling strategy**: State horizontal vs vertical — "Stateless API servers behind load balancer; horizontal auto-scale at 70% CPU"
+- **Data volume**: Project storage growth — "100GB Year 1, 1TB Year 3; archive records older than 2 years to cold storage"
+
+#### Availability
+
+- **Uptime SLA**: State the target and what it means — "99.9% monthly (43 min downtime/month allowed)"
+- **RTO/RPO**: Recovery time objective and recovery point objective — "RTO: 15 min, RPO: 5 min (continuous replication)"
+- **Graceful degradation**: Define fallback behavior — "If payment provider is down, queue orders and retry; show user 'processing' status"
+- **Maintenance windows**: Specify schedule — "Zero-downtime deploys via rolling update; no scheduled maintenance windows"
+
+#### Accessibility
+
+- **WCAG level**: State the target — "WCAG 2.1 AA compliance for all public-facing pages"
+- **Screen reader support**: Name tested readers — "VoiceOver (macOS/iOS), NVDA (Windows); tested quarterly"
+- **Keyboard navigation**: Full keyboard operability for all interactive elements; visible focus indicators
+
+#### The Three-Part Rule
+
+Every NFR entry in the PRD must answer: *What is the target?* (p95 < 200ms), *How is it measured?* (k6 load test in CI), *What is acceptable?* (p95 between 200-300ms triggers warning; above 300ms blocks deploy). If any of the three is missing, the NFR is incomplete.

package/knowledge/review/review-adr.md

@@ -1,7 +1,7 @@
 ---
 name: review-adr
 description: Failure modes and review passes specific to Architecture Decision Records
-topics: [review, adr, decisions]
+topics: [adr, decisions, review]
 ---
 
 # Review: Architecture Decision Records

package/knowledge/review/review-api-design.md

@@ -1,7 +1,7 @@
 ---
 name: review-api-design
 description: Failure modes and review passes specific to API contract specifications
-topics: [review, api, contracts, rest, graphql]
+topics: [api, contracts, rest, graphql, review]
 ---
 
 # Review: API Contracts

package/knowledge/review/review-database-design.md

@@ -1,7 +1,7 @@
 ---
 name: review-database-design
 description: Failure modes and review passes specific to database schema design artifacts
-topics: [review, database, schema, data-modeling]
+topics: [database, schema, data-modeling, review]
 ---
 
 # Review: Database Schema

package/knowledge/review/review-domain-modeling.md

@@ -1,7 +1,7 @@
 ---
 name: review-domain-modeling
 description: Failure modes and review passes specific to domain modeling artifacts
-topics: [review, domain-modeling, ddd, bounded-contexts]
+topics: [domain-modeling, ddd, bounded-contexts, review]
 ---
 
 # Review: Domain Modeling

package/knowledge/review/review-implementation-tasks.md

@@ -1,7 +1,7 @@
 ---
 name: review-implementation-tasks
 description: Failure modes and review passes specific to implementation tasks artifacts
-topics: [review, tasks, planning, decomposition, agents]
+topics: [tasks, planning, decomposition, agents, review]
 ---
 
 # Review: Implementation Tasks

package/knowledge/review/review-methodology.md

@@ -1,7 +1,7 @@
 ---
 name: review-methodology
 description: Shared process for conducting multi-pass reviews of documentation artifacts
-topics: [review, methodology, quality-assurance, multi-pass]
+topics: [methodology, quality-assurance, multi-pass, review]
 ---
 
 # Review Methodology

package/knowledge/review/review-operations.md

@@ -1,7 +1,7 @@
 ---
 name: review-operations
 description: Failure modes and review passes specific to operations and deployment runbook artifacts
-topics: [review, operations, deployment, monitoring, runbooks]
+topics: [operations, deployment, monitoring, runbooks, review]
 ---
 
 # Review: Operations & Deployment

package/knowledge/review/review-prd.md

@@ -1,7 +1,7 @@
 ---
 name: review-prd
 description: Failure modes and review passes specific to product requirements document artifacts
-topics: [review, prd, requirements, completeness, clarity, nfr, constraints]
+topics: [prd, requirements, completeness, clarity, nfr, constraints, review]
 ---
 
 # Review: Product Requirements Document

package/knowledge/review/review-security.md

@@ -1,7 +1,7 @@
 ---
 name: review-security
 description: Failure modes and review passes specific to security review and documentation artifacts
-topics: [review, security, owasp, auth, threat-modeling]
+topics: [security, owasp, auth, threat-modeling, review]
 ---
 
 # Review: Security

package/knowledge/review/review-system-architecture.md

@@ -1,7 +1,7 @@
 ---
 name: review-system-architecture
 description: Failure modes and review passes specific to system architecture documents
-topics: [review, architecture, components, data-flow, modules]
+topics: [architecture, components, data-flow, modules, review]
 ---
 
 # Review: System Architecture

package/knowledge/review/review-testing-strategy.md

@@ -1,7 +1,7 @@
 ---
 name: review-testing-strategy
 description: Failure modes and review passes specific to testing and quality strategy artifacts
-topics: [review, testing, quality, coverage, test-pyramid]
+topics: [testing, quality, coverage, test-pyramid, review]
 ---
 
 # Review: Testing Strategy

package/knowledge/review/review-user-stories.md

@@ -1,7 +1,7 @@
 ---
 name: review-user-stories
 description: Failure modes and review passes specific to user story artifacts
-topics: [review, user-stories, coverage, acceptance-criteria, INVEST, testability]
+topics: [user-stories, coverage, acceptance-criteria, INVEST, testability, review]
 ---
 
 # Review: User Stories

package/knowledge/review/review-ux-specification.md

@@ -1,7 +1,7 @@
 ---
 name: review-ux-specification
 description: Failure modes and review passes specific to UI/UX specification artifacts
-topics: [review, ux, design, accessibility, responsive-design]
+topics: [ux, design, accessibility, responsive-design, review]
 ---
 
 # Review: UX Specification

package/knowledge/review/review-vision.md

@@ -1,7 +1,7 @@
 ---
 name: review-vision
 description: Vision-specific review passes, failure modes, and quality criteria for product vision documents
-topics: [review, vision, product-strategy, validation]
+topics: [vision, product-strategy, validation, review]
 ---
 
 # Review: Product Vision