@ghostbyte/agent-docs-kit 4.0.2 → 5.0.0

package/content/engineering/09-message-queues.md

@@ -1,48 +1,38 @@
 # Message Queues
 
-# Engineering Topic 9: Message Queue Concepts
+## Engineering Topic 9: Message Queue Concepts
 
 **When to run this:** When designing or reviewing a system that uses a message queue/event stream (Kafka, RabbitMQ, SQS, etc.) for async communication between services.
 
 **Goal of this pass:** Confirm the delivery, ordering, and failure-handling guarantees the system actually needs match what the queue setup actually provides.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | The reference list of concepts for this topic — what each one is, why it matters, and the self-check question to ask. Doesn't get filled in; copy `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same list, with a Status column and notes. Copy this file per pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full source list lives in `../ENGINEERING_REFERENCE.md`. Unlike
-`../../security-gate/phases/`, this is knowledge/practice review, not pass/fail security
-testing — there's no severity rating, and "Fail" isn't the right framing.
-Use the Status options in `RESULTS_TEMPLATE.md` instead: Applied, Partial,
-Should adopt, or Not applicable.
+Use each stable practice ID in a generated engineering worksheet. Record concrete evidence and choose Applied, Partial, Recommended, Unverified, or N/A. Preserve each dated worksheet as review history.
 
 ## Wrap-up
 
 - This isn't a gate — nothing here blocks a release the way
-  Critical/High security items in `../../security-gate/phases/` do.
+  Critical/High security items in security phase reviews do.
 - Total concepts in this topic: 10
 - Useful as an onboarding read-through, a periodic self-audit, or context
   to hand an agent before it reviews related code.
 
 ---
 
-# Concepts — Topic 9: Message Queue Concepts
+## Concepts — Topic 9: Message Queue Concepts
 
-Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a pass.
+Use the applicable practices below to populate the worksheet findings table.
 
-| # | Concept | Why it matters | Self-check |
+| Practice ID | Practice | Why it matters | Evidence question |
 |---|---|---|---|
-| 1 | Producer / consumer | The basic decoupling pattern — getting the boundary wrong (e.g. producer waiting on consumer) defeats the purpose of using a queue at all. | Are producers and consumers actually decoupled, with the producer not blocked waiting on consumer processing? |
-| 2 | Topic + partition | Partitioning enables parallel consumption, but choosing the wrong partition key can cause hot partitions or lost ordering guarantees. | Is the partition key chosen deliberately (e.g. by entity ID) rather than defaulted, and does it avoid hot-partitioning? |
-| 3 | Consumer group | Lets multiple consumer instances share the work of one topic without processing the same message redundantly (within the group). | If there are multiple consumer instances, are they correctly grouped so work is distributed, not duplicated? |
-| 4 | At-least-once delivery | The common default guarantee — means consumers WILL sometimes see the same message twice and must handle that. | Does every consumer assume at-least-once delivery and handle duplicate messages correctly? |
-| 5 | Dead letter queue | Without one, a message that repeatedly fails processing either blocks the queue or is silently dropped. | Do failed messages, after retry limits, go to a dead letter queue instead of blocking or vanishing? |
-| 6 | Backpressure | If consumers can't keep up, the system needs a defined behavior (slow producers, buffer, drop) rather than unbounded queue growth. | Is there a defined response when consumer lag grows unbounded, rather than assuming it will always catch up? |
-| 7 | Fan-out | Delivering one message to multiple independent consumers (e.g. via separate subscriptions) needs the right topology — a single queue with one consumer group won't do it. | If multiple independent services need the same message, is the topology (e.g. separate subscriptions/topics) actually set up for fan-out? |
-| 8 | Message ordering | Most queues only guarantee order within a partition/shard, not globally — code that assumes global order will break. | Does any consumer logic assume strict global ordering, and if so, does the actual queue setup guarantee that? |
-| 9 | Idempotent consumer | Given at-least-once delivery, consumers must be able to safely process the same message twice without double-effecting (e.g. double-charging). | Is consumer processing logic idempotent (e.g. keyed on a unique message/operation ID) so redelivery is safe? |
-| 10 | Offset commit | Committing the offset too early risks losing a message if processing then fails; committing too late risks reprocessing more than necessary. | Is the offset committed only after successful processing (not before), matching the delivery guarantee the system actually needs? |
+| ENG-09-01 | Producer / consumer | The basic decoupling pattern — getting the boundary wrong (e.g. producer waiting on consumer) defeats the purpose of using a queue at all. | Are producers and consumers actually decoupled, with the producer not blocked waiting on consumer processing? |
+| ENG-09-02 | Topic + partition | Partitioning enables parallel consumption, but choosing the wrong partition key can cause hot partitions or lost ordering guarantees. | Is the partition key chosen deliberately (e.g. by entity ID) rather than defaulted, and does it avoid hot-partitioning? |
+| ENG-09-03 | Consumer group | Lets multiple consumer instances share the work of one topic without processing the same message redundantly (within the group). | If there are multiple consumer instances, are they correctly grouped so work is distributed, not duplicated? |
+| ENG-09-04 | At-least-once delivery | The common default guarantee — means consumers WILL sometimes see the same message twice and must handle that. | Does every consumer assume at-least-once delivery and handle duplicate messages correctly? |
+| ENG-09-05 | Dead letter queue | Without one, a message that repeatedly fails processing either blocks the queue or is silently dropped. | Do failed messages, after retry limits, go to a dead letter queue instead of blocking or vanishing? |
+| ENG-09-06 | Backpressure | If consumers can't keep up, the system needs a defined behavior (slow producers, buffer, drop) rather than unbounded queue growth. | Is there a defined response when consumer lag grows unbounded, rather than assuming it will always catch up? |
+| ENG-09-07 | Fan-out | Delivering one message to multiple independent consumers (e.g. via separate subscriptions) needs the right topology — a single queue with one consumer group won't do it. | If multiple independent services need the same message, is the topology (e.g. separate subscriptions/topics) actually set up for fan-out? |
+| ENG-09-08 | Message ordering | Most queues only guarantee order within a partition/shard, not globally — code that assumes global order will break. | Does any consumer logic assume strict global ordering, and if so, does the actual queue setup guarantee that? |
+| ENG-09-09 | Idempotent consumer | Given at-least-once delivery, consumers must be able to safely process the same message twice without double-effecting (e.g. double-charging). | Is consumer processing logic idempotent (e.g. keyed on a unique message/operation ID) so redelivery is safe? |
+| ENG-09-10 | Offset commit | Committing the offset too early risks losing a message if processing then fails; committing too late risks reprocessing more than necessary. | Is the offset committed only after successful processing (not before), matching the delivery guarantee the system actually needs? |

package/content/engineering/10-api-design-compatibility.md

@@ -0,0 +1,14 @@
+# API Design and Compatibility
+
+Use this review before introducing or changing a public, partner, or service-to-service API.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-10-01 | Explicit contracts | Machine-readable contracts reduce client/server drift. | Is the current request, response, and error contract versioned with the implementation? |
+| ENG-10-02 | Backward compatibility | Uncoordinated breaking changes create outages. | Are removals and semantic changes gated by a documented migration window? |
+| ENG-10-03 | Consistent errors | Predictable errors make clients safer and observable. | Do errors use stable codes, safe messages, and correlation identifiers? |
+| ENG-10-04 | Idempotency | Retries must not duplicate important side effects. | Do retryable writes use an idempotency strategy with a defined lifetime? |
+| ENG-10-05 | Pagination and limits | Unbounded reads create latency and cost failures. | Are page size, ordering, cursors, and maximum limits explicit? |
+| ENG-10-06 | Deprecation telemetry | Owners need evidence before retiring a version. | Can maintainers identify remaining callers of deprecated behavior? |
+| ENG-10-07 | Contract tests | Integration assumptions should fail before deployment. | Do provider and consumer tests cover critical compatibility promises? |
+| ENG-10-08 | Safe defaults | Optional fields and defaults affect long-lived clients. | Can old clients ignore additions without changing behavior unexpectedly? |

package/content/engineering/11-reliability-slos.md

@@ -0,0 +1,14 @@
+# Reliability, SLOs, and Error Budgets
+
+Use this review when defining service reliability or deciding whether delivery speed is outrunning operational health.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-11-01 | User-centered SLI | Reliability should represent user experience. | Does each indicator measure a user-visible success or latency outcome? |
+| ENG-11-02 | Achievable SLO | A target should guide decisions, not promise perfection. | Is the objective based on business need and measured historical behavior? |
+| ENG-11-03 | Error budget | Teams need a shared release-versus-reliability signal. | Is remaining error budget visible and tied to an agreed response? |
+| ENG-11-04 | Multi-window alerts | Fast and slow burns require different detection windows. | Do alerts identify material budget consumption without paging on noise? |
+| ENG-11-05 | Dependency objectives | Upstream limits constrain the service objective. | Are critical dependency availability and latency assumptions recorded? |
+| ENG-11-06 | Graceful degradation | Partial service can preserve essential workflows. | Are noncritical features shed safely when dependencies or capacity fail? |
+| ENG-11-07 | Recovery objectives | Recovery needs measurable targets. | Are RTO and RPO defined and tested for important data and workflows? |
+| ENG-11-08 | Reliability review | Objectives must evolve with product behavior. | Are SLOs reviewed after incidents and material architecture changes? |

package/content/engineering/12-observability-telemetry.md

@@ -0,0 +1,14 @@
+# Observability and Telemetry
+
+Use this review when adding telemetry or when production behavior cannot be explained quickly.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-12-01 | Structured logs | Searchable fields beat unstructured narratives. | Do logs contain stable event names, severity, and correlation context? |
+| ENG-12-02 | Useful metrics | Metrics should describe demand, errors, latency, and saturation. | Can dashboards explain whether users and resources are healthy? |
+| ENG-12-03 | Distributed traces | Cross-service latency needs causal context. | Are trace identifiers propagated across supported boundaries? |
+| ENG-12-04 | Cardinality control | Unbounded labels can disable or overprice monitoring. | Are user-generated and high-cardinality values excluded from metric labels? |
+| ENG-12-05 | Sensitive-data controls | Telemetry is another data store. | Are secrets and personal data redacted before collection? |
+| ENG-12-06 | Actionable alerts | Alerts should lead to a known response. | Does every page identify impact, owner, runbook, and escalation path? |
+| ENG-12-07 | Retention and sampling | Cost controls must preserve investigation value. | Are retention and sampling choices documented by telemetry class? |
+| ENG-12-08 | Instrumentation tests | Broken telemetry can hide production failures. | Do tests verify critical events and trace propagation without asserting noise? |

package/content/engineering/13-deployment-change-safety.md

@@ -0,0 +1,14 @@
+# Deployment and Change Safety
+
+Use this review for release pipelines, migrations, feature rollouts, and rollback design.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-13-01 | Small reversible changes | Small batches limit diagnosis and rollback cost. | Can the change be disabled or reverted without unrelated work? |
+| ENG-13-02 | Progressive delivery | Early signals reduce blast radius. | Is rollout staged by environment, cohort, region, or percentage? |
+| ENG-13-03 | Automated verification | Human-only checks miss repeatable regressions. | Are build, test, policy, and artifact checks required before promotion? |
+| ENG-13-04 | Migration compatibility | Code and data often deploy at different times. | Do schema changes support old and new application versions during rollout? |
+| ENG-13-05 | Health-based rollback | Rollback decisions should use defined signals. | Are stop and rollback thresholds tied to service and business health? |
+| ENG-13-06 | Artifact promotion | Rebuilding can change what was tested. | Is the verified immutable artifact promoted between environments? |
+| ENG-13-07 | Change traceability | Operators need to connect behavior to releases. | Can a running version be traced to source, build, approvals, and configuration? |
+| ENG-13-08 | Post-deployment observation | Success requires evidence after deployment. | Is there an owned observation window with a clear completion decision? |

package/content/engineering/14-capacity-concurrency.md

@@ -0,0 +1,14 @@
+# Capacity, Concurrency, and Resource Management
+
+Use this review for load-sensitive services, shared resources, and systems with concurrent state changes.
+
+| Practice ID | Practice | Why it matters | Evidence question |
+|---|---|---|---|
+| ENG-14-01 | Capacity model | Demand and limits should be explicit. | Are peak throughput, latency, storage, and headroom assumptions measured? |
+| ENG-14-02 | Bounded concurrency | Unlimited work can exhaust every dependency. | Are worker, connection, and request counts bounded at each layer? |
+| ENG-14-03 | Backpressure | Overload should be controlled rather than amplified. | Does the system reject, queue, or slow work using documented thresholds? |
+| ENG-14-04 | Timeouts and cancellation | Abandoned work should release resources. | Are timeouts budgeted end-to-end and cancellation signals propagated? |
+| ENG-14-05 | Contention testing | Shared locks and hot keys appear under load. | Do tests exercise realistic contention and skew rather than uniform traffic only? |
+| ENG-14-06 | Autoscaling signals | Scaling on the wrong signal can worsen overload. | Do scaling signals lead demand and respect dependency capacity? |
+| ENG-14-07 | Resource cleanup | Leaks turn normal operation into delayed failure. | Are connections, files, memory, and temporary objects bounded and observable? |
+| ENG-14-08 | Degradation plan | Capacity exhaustion must preserve critical work. | Are admission control and priority rules defined for overload conditions? |

package/content/engineering/full-reference.md

@@ -1,144 +1,24 @@
-# Engineering Reference
-
-A companion to `../security-gate/SECURITY_CHECKLIST.md`. That file is pass/fail **security
-tests**; this file is **"what should I know"** — quick-recall concept lists
-for performance, infra, and engineering practice. Nothing here has a
-severity rating or a test step; use it for onboarding, self-study, or as
-context for an agent before it reviews related code.
-
-## Table of contents
-
-- [A. Speeding Up a Slow Query](#a-speeding-up-a-slow-query)
-- [B. Networking Concepts Every Dev Should Know](#b-networking-concepts-every-dev-should-know)
-- [C. Rate Limiting Algorithms](#c-rate-limiting-algorithms)
-- [D. Debugging Production Issues](#d-debugging-production-issues)
-- [E. Code Review Practices](#e-code-review-practices)
-- [F. Data Modeling Concepts](#f-data-modeling-concepts)
-- [G. Cloud Cost-Saving Techniques](#g-cloud-cost-saving-techniques)
-- [H. Types of Testing](#h-types-of-testing)
-- [I. Message Queue Concepts](#i-message-queue-concepts)
-
-> **Note:** the original "Web security vulnerabilities" list is not
-> duplicated here — it's already covered item-for-item in
-> `../security-gate/SECURITY_CHECKLIST.md` → `02_Web_Vulnerabilities`. Rate limiting
-> algorithms (below) are a companion to, not a replacement for,
-> `01_API_Security/01_rate_limiting.md`.
-
----
-
-## A. Speeding Up a Slow Query
-
-1. Start with the explain plan
-2. Add the missing index
-3. Stop selecting *
-4. Fix N+1 queries
-5. Use a covering index
-6. Cache repeated queries
-7. Prune partitions
-8. Denormalize for reads
-9. Batch your writes
-10. Update table statistics
-
-## B. Networking Concepts Every Dev Should Know
-
-1. DNS resolution
-2. TCP handshake
-3. TLS handshake
-4. NAT
-5. Load balancer types
-6. CDN edge caching
-7. Packet loss & retransmit
-8. MTU / fragmentation
-9. Keep-alive
-10. BGP routing
-
-## C. Rate Limiting Algorithms
-
-1. Fixed window
-2. Sliding window log
-3. Sliding window counter
-4. Token bucket
-5. Leaky bucket
-6. Distributed rate limiting
-7. Client-side throttling
-8. Adaptive rate limiting
-9. Concurrency limiting
-10. Back pressure
-
-## D. Debugging Production Issues
-
-1. Correlation IDs
-2. Distributed tracing
-3. Feature flag rollback
-4. Canary analysis
-5. Replay traffic
-6. Heap dumps
-7. Chaos testing
-8. Synthetic monitoring
-9. Error budgets
-10. Postmortems
-
-## E. Code Review Practices
-
-1. Small PRs
-2. Clear description
-3. Constructive feedback
-4. Nitpick vs. blocker
-5. Fast turnaround
-6. Automated checks first
-7. Context before code
-8. Approve vs. request changes
-9. Self-review first
-10. Learning from reviews
-
-## F. Data Modeling Concepts
-
-1. Primary vs. foreign keys
-2. One-to-many
-3. Many-to-many
-4. Composite keys
-5. Soft deletes
-6. Polymorphic associations
-7. Enum vs. lookup table
-8. Audit columns
-9. Schema migrations
-10. Precision & data types
-
-## G. Cloud Cost-Saving Techniques
-
-1. Spot instances
-2. Autoscaling
-3. Reserved capacity
-4. Right-sizing
-5. Storage tiering
-6. CDN offloading
-7. Serverless for spiky loads
-8. Idle resource cleanup
-9. Compression
-10. Multi-region arbitrage
-
-## H. Types of Testing
-
-1. Unit test
-2. Integration test
-3. End-to-end test
-4. Snapshot test
-5. Contract test
-6. Load test
-7. Chaos test
-8. Mutation test
-9. Smoke test
-10. Regression test
-
-## I. Message Queue Concepts
-
-1. Producer / consumer
-2. Topic + partition
-3. Consumer group
-4. At-least-once delivery
-5. Dead letter queue
-6. Backpressure
-7. Fan-out
-8. Message ordering
-9. Idempotent consumer
-10. Offset commit
+# Engineering Quality Reference
+
+This index routes reviewers to focused, evidence-based practice reviews. Engineering findings are advisory unless they reveal a separate correctness, reliability, or security defect.
+
+Use `Applied`, `Partial`, `Recommended`, `Unverified`, or `N/A`. For each recommendation, record observable evidence, impact, an owner, and a verification step.
+
+## Topic index
+
+1. Query performance and slow-query diagnosis
+2. Networking fundamentals
+3. Rate-limiting algorithms
+4. Production debugging
+5. Code-review practices
+6. Data modeling
+7. Cloud cost saving
+8. Testing types and strategy
+9. Message queues
+10. API design and compatibility
+11. Reliability, SLOs, and error budgets
+12. Observability and telemetry
+13. Deployment and change safety
+14. Capacity, concurrency, and resource management
+
+Run `agent-docs list engineering`, then create only the needed worksheet with `agent-docs engineering worksheet <topic>`.

package/content/security/01-design-architecture.md

@@ -1,21 +1,14 @@
 # Design & Architecture
 
-# Phase 1: Design & Architecture (Pre-Code)
+## Phase 1: Design & Architecture (Pre-Code)
 
 **When to run this:** Before writing code — during system/feature design, RFCs, or architecture review.
 
 **Goal of this pass:** Catch design-level flaws (missing trust boundaries, over-broad data collection, no threat model) that are cheap to fix now and expensive to fix after code exists.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full background, "why it matters," and references for every item live in
-`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
-checklist below).
+Use each stable control ID in a generated security worksheet. Record observed evidence before assigning a status; leave a control Unverified when evidence is unavailable. Preserve each dated worksheet as audit history.
 
 ## Sign-off criteria
 
@@ -25,15 +18,14 @@ checklist below).
 
 ---
 
-# What to Check — Phase 1: Design & Architecture (Pre-Code)
+## What to Check — Phase 1: Design & Architecture (Pre-Code)
 
-Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a test pass.
+Use the applicable controls below to populate the worksheet findings table.
 
-| # | Source file | Item | Severity | Example test |
+| Control ID | Source | Control | Severity | Evidence question |
 |---|---|---|---|---|
-| 1 | `15_Architecture_Compliance/01_privacy_by_design.md` | Privacy by Design | Medium | Review the most recent feature's design doc and confirm data collection was scoped to only what the feature actually needs. |
-| 2 | `15_Architecture_Compliance/02_threat_modeling.md` | Threat Modeling | High | Pull the data-flow diagram for the highest-risk service and confirm a STRIDE (or equivalent) pass was actually performed and mitigations tracked to closure. |
-| 3 | `15_Architecture_Compliance/04_defense_in_depth.md` | Defense in Depth | Medium | Pick one critical asset and map every independent control protecting it; confirm there isn't a single point whose failure alone exposes it. |
-| 4 | `15_Architecture_Compliance/06_zero_trust_network.md` | Zero Trust Network Architecture | High | From inside the internal network, attempt to reach a service without presenting valid per-request authentication and confirm it's still denied. |
-| 5 | `15_Architecture_Compliance/08_secure_sdlc.md` | Secure SDLC (added) | Medium | Confirm the most recent feature had security requirements defined at design time, not bolted on after code review. |
+| SEC-01-01 | `15_Architecture_Compliance/01_privacy_by_design.md` | Privacy by Design | Medium | Review the most recent feature's design doc and confirm data collection was scoped to only what the feature actually needs. |
+| SEC-01-02 | `15_Architecture_Compliance/02_threat_modeling.md` | Threat Modeling | High | Pull the data-flow diagram for the highest-risk service and confirm a STRIDE (or equivalent) pass was actually performed and mitigations tracked to closure. |
+| SEC-01-03 | `15_Architecture_Compliance/04_defense_in_depth.md` | Defense in Depth | Medium | Pick one critical asset and map every independent control protecting it; confirm there isn't a single point whose failure alone exposes it. |
+| SEC-01-04 | `15_Architecture_Compliance/06_zero_trust_network.md` | Zero Trust Network Architecture | High | From inside the internal network, attempt to reach a service without presenting valid per-request authentication and confirm it's still denied. |
+| SEC-01-05 | `15_Architecture_Compliance/08_secure_sdlc.md` | Secure SDLC (added) | Medium | Confirm the most recent feature had security requirements defined at design time, not bolted on after code review. |

package/content/security/02-local-development.md

@@ -1,21 +1,14 @@
 # Local Development
 
-# Phase 2: Local Development
+## Phase 2: Local Development
 
 **When to run this:** During day-to-day coding, before opening a pull request.
 
 **Goal of this pass:** Prevent secrets, unpinned/unvetted dependencies, and known-bad coding patterns from ever reaching a shared branch.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full background, "why it matters," and references for every item live in
-`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
-checklist below).
+Use each stable control ID in a generated security worksheet. Record observed evidence before assigning a status; leave a control Unverified when evidence is unavailable. Preserve each dated worksheet as audit history.
 
 ## Sign-off criteria
 
@@ -25,17 +18,16 @@ checklist below).
 
 ---
 
-# What to Check — Phase 2: Local Development
+## What to Check — Phase 2: Local Development
 
-Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a test pass.
+Use the applicable controls below to populate the worksheet findings table.
 
-| # | Source file | Item | Severity | Example test |
+| Control ID | Source | Control | Severity | Evidence question |
 |---|---|---|---|---|
-| 1 | `08_Release_Engineering_Version_Control/01_secure_coding_guidelines.md` | Secure Coding Guidelines | Low | Confirm the team's secure-coding cheat sheet is linked from the PR template/onboarding docs, not just filed away unused. |
-| 2 | `08_Release_Engineering_Version_Control/02_semantic_versioning.md` | Semantic Versioning | Low | Check the last 3 releases and confirm any breaking change actually bumped the MAJOR version. |
-| 3 | `10_Dependency_Supply_Chain/01_backend_dependency_scanning.md` | Dependency & SCA Scanning | High | Run the SCA scanner manually against the current backend dependency tree and confirm it matches what CI reports, with no critical CVEs unpatched past SLA. |
-| 4 | `10_Dependency_Supply_Chain/02_dependency_version_pinning.md` | Dependency Version Pinning | Medium | Delete the lockfile locally and reinstall; confirm CI fails the build if the regenerated lockfile differs from the committed one. |
-| 5 | `10_Dependency_Supply_Chain/03_frontend_dependency_scanning.md` | Frontend Dependency Scanning | Medium | Run npm audit / yarn audit and manually review any newly added package for typosquatting risk or suspicious post-install scripts. |
-| 6 | `06_Data_Protection_Secrets/06_secrets_management.md` | Secrets Management (added) | Critical | Run a secret-scanning tool (e.g. gitleaks/truffleHog) across the full git history, not just HEAD, and confirm zero committed credentials. |
-| 7 | `09_Release_Pipeline_Stages/01_local_dev_testing.md` | Stage 1: Local / Developer Testing | Low | Confirm a fresh local dev environment setup never requires copying real production credentials or data. |
+| SEC-02-01 | `08_Release_Engineering_Version_Control/01_secure_coding_guidelines.md` | Secure Coding Guidelines | Low | Confirm the team's secure-coding cheat sheet is linked from the PR template/onboarding docs, not just filed away unused. |
+| SEC-02-02 | `08_Release_Engineering_Version_Control/02_semantic_versioning.md` | Semantic Versioning | Low | Check the last 3 releases and confirm any breaking change actually bumped the MAJOR version. |
+| SEC-02-03 | `10_Dependency_Supply_Chain/01_backend_dependency_scanning.md` | Dependency & SCA Scanning | High | Run the SCA scanner manually against the current backend dependency tree and confirm it matches what CI reports, with no critical CVEs unpatched past SLA. |
+| SEC-02-04 | `10_Dependency_Supply_Chain/02_dependency_version_pinning.md` | Dependency Version Pinning | Medium | Delete the lockfile locally and reinstall; confirm CI fails the build if the regenerated lockfile differs from the committed one. |
+| SEC-02-05 | `10_Dependency_Supply_Chain/03_frontend_dependency_scanning.md` | Frontend Dependency Scanning | Medium | Run npm audit / yarn audit and manually review any newly added package for typosquatting risk or suspicious post-install scripts. |
+| SEC-02-06 | `06_Data_Protection_Secrets/06_secrets_management.md` | Secrets Management (added) | Critical | Run a secret-scanning tool (e.g. gitleaks/truffleHog) across the full git history, not just HEAD, and confirm zero committed credentials. |
+| SEC-02-07 | `09_Release_Pipeline_Stages/01_local_dev_testing.md` | Stage 1: Local / Developer Testing | Low | Confirm a fresh local dev environment setup never requires copying real production credentials or data. |

package/content/security/03-database-backend.md

@@ -1,21 +1,14 @@
 # Database & Backend
 
-# Phase 3: Database & Backend Layer
+## Phase 3: Database & Backend Layer
 
 **When to run this:** While building/reviewing server-side business logic and the data access layer.
 
 **Goal of this pass:** Confirm the backend enforces authorization and business rules itself, and that the data layer doesn't quietly reintroduce injection or over-fetching risk.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full background, "why it matters," and references for every item live in
-`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
-checklist below).
+Use each stable control ID in a generated security worksheet. Record observed evidence before assigning a status; leave a control Unverified when evidence is unavailable. Preserve each dated worksheet as audit history.
 
 ## Sign-off criteria
 
@@ -25,22 +18,21 @@ checklist below).
 
 ---
 
-# What to Check — Phase 3: Database & Backend Layer
+## What to Check — Phase 3: Database & Backend Layer
 
-Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a test pass.
+Use the applicable controls below to populate the worksheet findings table.
 
-| # | Source file | Item | Severity | Example test |
+| Control ID | Source | Control | Severity | Evidence question |
 |---|---|---|---|---|
-| 1 | `05_Backend_Handling/01_business_logic_validation.md` | Business Logic Validation | High | Attempt to call the 'ship order' step of a checkout flow while skipping the 'payment' step and confirm the server rejects the out-of-order transition. |
-| 2 | `05_Backend_Handling/02_file_upload_handling.md` | File Upload Handling | Critical | Upload a file with a .jpg extension but executable/script magic bytes inside, and confirm the server validates content type by inspecting bytes, not just the extension. |
-| 3 | `05_Backend_Handling/03_orm_database_security.md` | ORM & Database Layer Security | High | Search the codebase for any raw-query escape hatches in the ORM and confirm every one uses parameter binding, not string concatenation. |
-| 4 | `05_Backend_Handling/04_background_job_queue_security.md` | Background Job & Queue Security | Medium | Submit a queued job payload with malformed/malicious data directly (bypassing the API layer) and confirm the worker validates it the same way the API would. |
-| 5 | `05_Backend_Handling/05_error_handling_stack_traces.md` | Error Handling & Stack Trace Exposure | Medium | Send a malformed request (bad JSON, wrong content-type) to a production endpoint and confirm the response is a generic error, not a stack trace or file path. |
-| 6 | `03_Access_Control_Session_Auth/02_backend_access_control.md` | Backend Access Control | Critical | Using User A's valid session, request User B's resource ID directly and confirm a 403, not the data. |
-| 7 | `03_Access_Control_Session_Auth/05_rbac_abac.md` | RBAC / ABAC Models (added) | Medium | Pick a long-lived test account and diff its current granted permissions against what its role should have today, looking for accumulated excess access. |
-| 8 | `06_Data_Protection_Secrets/01_encryption_at_rest.md` | Encryption at Rest | High | Confirm via cloud console/CLI that the database volume, backups, and object storage all show encryption-at-rest enabled, not just the primary disk. |
-| 9 | `06_Data_Protection_Secrets/02_encryption_in_transit.md` | Encryption in Transit | High | Attempt to connect to the database and any internal service-to-service endpoint over plaintext and confirm the connection is refused, TLS-only. |
-| 10 | `06_Data_Protection_Secrets/03_pii_data_classification.md` | PII & Data Classification | Medium | Pull a sample data export/report and check whether it exposes any field classified as higher-sensitivity than the export's intended audience. |
-| 11 | `06_Data_Protection_Secrets/04_key_management.md` | Key Management (KMS) | Critical | Confirm encryption keys live in a KMS/HSM (not a config file or env var) and walk through the documented key-revocation procedure end to end. |
-| 12 | `06_Data_Protection_Secrets/05_tls_certificate_management.md` | TLS Certificate Management | High | Run an SSL/TLS scan (e.g. against the Mozilla Observatory or testssl.sh) on each public endpoint and confirm TLS 1.2+ only, no weak ciphers, valid expiry. |
+| SEC-03-01 | `05_Backend_Handling/01_business_logic_validation.md` | Business Logic Validation | High | Attempt to call the 'ship order' step of a checkout flow while skipping the 'payment' step and confirm the server rejects the out-of-order transition. |
+| SEC-03-02 | `05_Backend_Handling/02_file_upload_handling.md` | File Upload Handling | Critical | Upload a file with a .jpg extension but executable/script magic bytes inside, and confirm the server validates content type by inspecting bytes, not just the extension. |
+| SEC-03-03 | `05_Backend_Handling/03_orm_database_security.md` | ORM & Database Layer Security | High | Search the codebase for any raw-query escape hatches in the ORM and confirm every one uses parameter binding, not string concatenation. |
+| SEC-03-04 | `05_Backend_Handling/04_background_job_queue_security.md` | Background Job & Queue Security | Medium | Submit a queued job payload with malformed/malicious data directly (bypassing the API layer) and confirm the worker validates it the same way the API would. |
+| SEC-03-05 | `05_Backend_Handling/05_error_handling_stack_traces.md` | Error Handling & Stack Trace Exposure | Medium | Send a malformed request (bad JSON, wrong content-type) to a production endpoint and confirm the response is a generic error, not a stack trace or file path. |
+| SEC-03-06 | `03_Access_Control_Session_Auth/02_backend_access_control.md` | Backend Access Control | Critical | Using User A's valid session, request User B's resource ID directly and confirm a 403, not the data. |
+| SEC-03-07 | `03_Access_Control_Session_Auth/05_rbac_abac.md` | RBAC / ABAC Models (added) | Medium | Pick a long-lived test account and diff its current granted permissions against what its role should have today, looking for accumulated excess access. |
+| SEC-03-08 | `06_Data_Protection_Secrets/01_encryption_at_rest.md` | Encryption at Rest | High | Confirm via cloud console/CLI that the database volume, backups, and object storage all show encryption-at-rest enabled, not just the primary disk. |
+| SEC-03-09 | `06_Data_Protection_Secrets/02_encryption_in_transit.md` | Encryption in Transit | High | Attempt to connect to the database and any internal service-to-service endpoint over plaintext and confirm the connection is refused, TLS-only. |
+| SEC-03-10 | `06_Data_Protection_Secrets/03_pii_data_classification.md` | PII & Data Classification | Medium | Pull a sample data export/report and check whether it exposes any field classified as higher-sensitivity than the export's intended audience. |
+| SEC-03-11 | `06_Data_Protection_Secrets/04_key_management.md` | Key Management (KMS) | Critical | Confirm encryption keys live in a KMS/HSM (not a config file or env var) and walk through the documented key-revocation procedure end to end. |
+| SEC-03-12 | `06_Data_Protection_Secrets/05_tls_certificate_management.md` | TLS Certificate Management | High | Run an SSL/TLS scan (e.g. against the Mozilla Observatory or testssl.sh) on each public endpoint and confirm TLS 1.2+ only, no weak ciphers, valid expiry. |

package/content/security/04-api-layer.md

@@ -1,21 +1,14 @@
 # API Layer
 
-# Phase 4: API Layer
+## Phase 4: API Layer
 
 **When to run this:** While building/reviewing any endpoint that's called over the network — internal or external.
 
 **Goal of this pass:** Confirm authentication, authorization, and abuse controls are enforced on every endpoint, not assumed from the caller.
 
-## Files in this folder
+## How to use this reference
 
-| File | Purpose |
-|---|---|
-| `CHECKLIST.md` | What to check — the reference list of items, severity, and example test steps for this phase. Doesn't get filled in; copy it or use `RESULTS_TEMPLATE.md` to record a real pass. |
-| `RESULTS_TEMPLATE.md` | Fillable version of the same checklist, with Result/Notes columns and a sign-off block. Copy this file per test pass (e.g. `RESULTS_2026-08-29.md`) so history isn't overwritten. |
-
-Full background, "why it matters," and references for every item live in
-`../../SECURITY_CHECKLIST.md` (search for the source file path shown in the
-checklist below).
+Use each stable control ID in a generated security worksheet. Record observed evidence before assigning a status; leave a control Unverified when evidence is unavailable. Preserve each dated worksheet as audit history.
 
 ## Sign-off criteria
 
@@ -25,27 +18,26 @@ checklist below).
 
 ---
 
-# What to Check — Phase 4: API Layer
+## What to Check — Phase 4: API Layer
 
-Reference checklist only — no result columns. Use `RESULTS_TEMPLATE.md` in
-this same folder to actually record a test pass.
+Use the applicable controls below to populate the worksheet findings table.
 
-| # | Source file | Item | Severity | Example test |
+| Control ID | Source | Control | Severity | Evidence question |
 |---|---|---|---|---|
-| 1 | `01_API_Security/01_rate_limiting.md` | Rate Limiting | High | Fire 200 requests/sec at a login endpoint from one IP and confirm 429s with Retry-After start well before account lockout thresholds are reachable. |
-| 2 | `01_API_Security/02_api_keys.md` | API Keys | High | Grep the built client bundle and mobile binary for hardcoded key patterns, then rotate one key and confirm the old value is rejected within minutes. |
-| 3 | `01_API_Security/03_oauth2.md` | OAuth 2.0 | Critical | Attempt the authorization flow with a modified redirect_uri (e.g. attacker.com) and confirm the server rejects it rather than redirecting. |
-| 4 | `01_API_Security/04_jwt_validation.md` | JWT Validation | Critical | Submit a token with 'alg' changed to 'none' and an empty signature; confirm the API rejects it instead of trusting the claims. |
-| 5 | `01_API_Security/05_input_sanitation.md` | Input Sanitation | High | Submit oversized, wrong-type, and boundary values (e.g. negative quantity, 10k-char string) on every field and confirm consistent server-side rejection. |
-| 6 | `01_API_Security/06_cors_policy.md` | CORS Policy | High | Send a fetch with Origin: https://evil.com and credentials:'include'; confirm the Access-Control-Allow-Origin response does not reflect evil.com. |
-| 7 | `01_API_Security/07_mtls.md` | Mutual TLS (mTLS) | Medium | Present an expired or self-signed client certificate to the mTLS endpoint and confirm the connection is rejected, not silently accepted. |
-| 8 | `01_API_Security/08_request_signing.md` | Request Signing | Medium | Replay a previously captured signed request unmodified after its timestamp window; confirm it is rejected as a replay. |
-| 9 | `01_API_Security/09_ip_allowlisting.md` | IP Allowlisting | Medium | Send a request from a disallowed IP with a spoofed X-Forwarded-For header set to an allowlisted IP and confirm it is still blocked. |
-| 10 | `01_API_Security/10_security_headers.md` | Security Headers (added) | Medium | Run curl -I against each public endpoint and confirm CSP, HSTS, X-Content-Type-Options, and frame-ancestors are all present. |
-| 11 | `03_Access_Control_Session_Auth/07_session_management.md` | Session Management (added) | High | Capture the session cookie before and after login and confirm the session ID value actually changes (regenerates) rather than persisting. |
-| 12 | `03_Access_Control_Session_Auth/08_mfa.md` | Multi-Factor Authentication (added) | Critical | Attempt the password-reset flow and confirm it cannot be used to fully log in while skipping the MFA step. |
-| 13 | `03_Access_Control_Session_Auth/09_session_store_caching.md` | Session Store Security (Redis/Memcached) | High | Attempt to connect directly to the Redis/Memcached session store from outside the app network and confirm authentication is required and it isn't publicly reachable. |
-| 14 | `03_Access_Control_Session_Auth/10_remember_me_persistent_login.md` | "Remember Me" & Persistent Login Tokens | High | Use a captured remember-me token once, then reuse the same (now-rotated-out) token value again and confirm it triggers revocation/alerting rather than silent success. |
-| 15 | `03_Access_Control_Session_Auth/06_forced_reauth_sensitive_actions.md` | Forced Re-Authentication for Sensitive Actions | High | From an already-logged-in session, attempt to change the account email/password without re-entering credentials and confirm it's blocked. |
-| 16 | `03_Access_Control_Session_Auth/03_cache_invalidation_on_auth_change.md` | Cache Invalidation on Auth/Privilege Change | High | Downgrade a test user's role, then immediately retry a privileged action with their still-active session and confirm it's now denied. |
-| 17 | `03_Access_Control_Session_Auth/04_device_trust_fingerprinting.md` | Device Trust & Fingerprinting | Medium | Replay a captured device-trust identifier from a different browser/device and confirm it does not skip MFA. |
+| SEC-04-01 | `01_API_Security/01_rate_limiting.md` | Rate Limiting | High | Fire 200 requests/sec at a login endpoint from one IP and confirm 429s with Retry-After start well before account lockout thresholds are reachable. |
+| SEC-04-02 | `01_API_Security/02_api_keys.md` | API Keys | High | Grep the built client bundle and mobile binary for hardcoded key patterns, then rotate one key and confirm the old value is rejected within minutes. |
+| SEC-04-03 | `01_API_Security/03_oauth2.md` | OAuth 2.0 | Critical | Attempt the authorization flow with a modified redirect_uri (e.g. attacker.com) and confirm the server rejects it rather than redirecting. |
+| SEC-04-04 | `01_API_Security/04_jwt_validation.md` | JWT Validation | Critical | Submit a token with 'alg' changed to 'none' and an empty signature; confirm the API rejects it instead of trusting the claims. |
+| SEC-04-05 | `01_API_Security/05_input_sanitation.md` | Input Sanitation | High | Submit oversized, wrong-type, and boundary values (e.g. negative quantity, 10k-char string) on every field and confirm consistent server-side rejection. |
+| SEC-04-06 | `01_API_Security/06_cors_policy.md` | CORS Policy | High | Send a fetch with Origin: https://evil.com and credentials:'include'; confirm the Access-Control-Allow-Origin response does not reflect evil.com. |
+| SEC-04-07 | `01_API_Security/07_mtls.md` | Mutual TLS (mTLS) | Medium | Present an expired or self-signed client certificate to the mTLS endpoint and confirm the connection is rejected, not silently accepted. |
+| SEC-04-08 | `01_API_Security/08_request_signing.md` | Request Signing | Medium | Replay a previously captured signed request unmodified after its timestamp window; confirm it is rejected as a replay. |
+| SEC-04-09 | `01_API_Security/09_ip_allowlisting.md` | IP Allowlisting | Medium | Send a request from a disallowed IP with a spoofed X-Forwarded-For header set to an allowlisted IP and confirm it is still blocked. |
+| SEC-04-10 | `01_API_Security/10_security_headers.md` | Security Headers (added) | Medium | Run curl -I against each public endpoint and confirm CSP, HSTS, X-Content-Type-Options, and frame-ancestors are all present. |
+| SEC-04-11 | `03_Access_Control_Session_Auth/07_session_management.md` | Session Management (added) | High | Capture the session cookie before and after login and confirm the session ID value actually changes (regenerates) rather than persisting. |
+| SEC-04-12 | `03_Access_Control_Session_Auth/08_mfa.md` | Multi-Factor Authentication (added) | Critical | Attempt the password-reset flow and confirm it cannot be used to fully log in while skipping the MFA step. |
+| SEC-04-13 | `03_Access_Control_Session_Auth/09_session_store_caching.md` | Session Store Security (Redis/Memcached) | High | Attempt to connect directly to the Redis/Memcached session store from outside the app network and confirm authentication is required and it isn't publicly reachable. |
+| SEC-04-14 | `03_Access_Control_Session_Auth/10_remember_me_persistent_login.md` | "Remember Me" & Persistent Login Tokens | High | Use a captured remember-me token once, then reuse the same (now-rotated-out) token value again and confirm it triggers revocation/alerting rather than silent success. |
+| SEC-04-15 | `03_Access_Control_Session_Auth/06_forced_reauth_sensitive_actions.md` | Forced Re-Authentication for Sensitive Actions | High | From an already-logged-in session, attempt to change the account email/password without re-entering credentials and confirm it's blocked. |
+| SEC-04-16 | `03_Access_Control_Session_Auth/03_cache_invalidation_on_auth_change.md` | Cache Invalidation on Auth/Privilege Change | High | Downgrade a test user's role, then immediately retry a privileged action with their still-active session and confirm it's now denied. |
+| SEC-04-17 | `03_Access_Control_Session_Auth/04_device_trust_fingerprinting.md` | Device Trust & Fingerprinting | Medium | Replay a captured device-trust identifier from a different browser/device and confirm it does not skip MFA. |