@ghostbyte/agent-docs-kit 0.0.0-stage → 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghostbyte1014
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# Agent Docs & Quality Kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Documentation governance, evidence-based security audits, and engineering-quality reviews in one installable CLI and one progressive Codex skill.
+
+[![CI](https://github.com/ghostbyte1014/Agent_Docs_Kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ghostbyte1014/Agent_Docs_Kit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@ghostbyte/agent-docs-kit.svg)](https://www.npmjs.com/package/@ghostbyte/agent-docs-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## What each part is for
+
+| Workflow | Purpose | Result model |
+|---|---|---|
+| Documentation | Keep scope, architecture, decisions, operations, and change history navigable and current. | Current / Needs update / Reference / Archived |
+| Security | Test security controls with evidence and expose release risk. | Pass / Fail / Unverified / N/A |
+| Engineering | Review maintainability, reliability, performance, testing, operability, and cost tradeoffs. | Applied / Partial / Recommended / Unverified / N/A |
+
+Security can block a release. Engineering advice is normally non-blocking. Documentation policy improves governance but becomes technically enforceable only when backed by hooks or CI.
+
+## Try it without installing
+
+```bash
+npx @ghostbyte/agent-docs-kit@latest
+```
+
+The no-argument command opens a guided menu in an interactive terminal. Direct commands work well in scripts:
+
+```bash
+npx @ghostbyte/agent-docs-kit@latest setup --dry-run
+npx @ghostbyte/agent-docs-kit@latest setup
+npx @ghostbyte/agent-docs-kit@latest audit documentation
+npx @ghostbyte/agent-docs-kit@latest list security
+npx @ghostbyte/agent-docs-kit@latest audit security api-layer --style learning
+npx @ghostbyte/agent-docs-kit@latest review engineering testing-types
+npx @ghostbyte/agent-docs-kit@latest skill install --target project
+```
+
+Installing the package performs no setup and changes no project files. Mutation happens only after an explicit command:
+
+```bash
+npm install --save-dev @ghostbyte/agent-docs-kit
+npx agent-docs setup
+```
+
+Existing files are skipped unless `--force` is supplied. Use `--dry-run` to preview owned writes.
+
+## Codex skill
+
+The package contains `manage-project-quality`, a single router skill whose references are loaded by selected workflow and phase. Install it into the current project with:
+
+```bash
+npx agent-docs skill install --target project
+```
+
+This creates `.agents/skills/manage-project-quality`. For a user-level Codex installation, explicitly run `npx agent-docs skill install --target codex`.
+
+## Maintainer setup
+
+See [GitHub and npm setup](docs/GITHUB_AND_NPM_SETUP.md) for the commands to create/push the repository, enable GitHub Pages, verify the npm package name, publish the first version, and configure trusted publishing. The package name and repository URL are configured for `ghostbyte1014`; change them before release if the actual owner or repository differs.
+
+Further documentation:
+
+- [Purpose and boundaries](docs/PURPOSE.md)
+- [Architecture and complete file structure](docs/ARCHITECTURE.md)
+- [Security model](docs/SECURITY_MODEL.md)
+- [Release process](docs/RELEASE_PROCESS.md)
+- [Legacy v3.2 compiled kit](docs/archive/AGENT_DOCS_KIT_v3.2.md)
+
+## Development
+
+```bash
+npm install
+npm test
+npm run validate
+npm run build
+npm run site:preview
+npm pack --dry-run
+```
+
+There are no runtime dependencies and no lifecycle install script.
+
+## License
+
+[MIT](LICENSE) © ghostbyte1014.

package/bin/agent-docs.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli/main.mjs";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`agent-docs: ${error.message}`);
+  process.exitCode = 1;
+});

package/content/catalog.json

@@ -0,0 +1,196 @@
+{
+  "schemaVersion": 1,
+  "security": [
+    {
+      "id": "01",
+      "slug": "design-architecture",
+      "title": "Design & Architecture",
+      "aliases": [
+        "1"
+      ],
+      "source": "content/security/01-design-architecture.md"
+    },
+    {
+      "id": "02",
+      "slug": "local-development",
+      "title": "Local Development",
+      "aliases": [
+        "2"
+      ],
+      "source": "content/security/02-local-development.md"
+    },
+    {
+      "id": "03",
+      "slug": "database-backend",
+      "title": "Database & Backend",
+      "aliases": [
+        "3"
+      ],
+      "source": "content/security/03-database-backend.md"
+    },
+    {
+      "id": "04",
+      "slug": "api-layer",
+      "title": "API Layer",
+      "aliases": [
+        "4"
+      ],
+      "source": "content/security/04-api-layer.md"
+    },
+    {
+      "id": "05",
+      "slug": "frontend-ui",
+      "title": "Frontend & UI",
+      "aliases": [
+        "5"
+      ],
+      "source": "content/security/05-frontend-ui.md"
+    },
+    {
+      "id": "06",
+      "slug": "application-security-testing",
+      "title": "Application Security Testing",
+      "aliases": [
+        "6"
+      ],
+      "source": "content/security/06-application-security-testing.md"
+    },
+    {
+      "id": "07",
+      "slug": "cicd-release-engineering",
+      "title": "CI/CD & Release Engineering",
+      "aliases": [
+        "7"
+      ],
+      "source": "content/security/07-cicd-release-engineering.md"
+    },
+    {
+      "id": "08",
+      "slug": "cloud-infrastructure",
+      "title": "Cloud Infrastructure",
+      "aliases": [
+        "8"
+      ],
+      "source": "content/security/08-cloud-infrastructure.md"
+    },
+    {
+      "id": "09",
+      "slug": "edge-cdn-dns",
+      "title": "Edge, CDN & DNS",
+      "aliases": [
+        "9"
+      ],
+      "source": "content/security/09-edge-cdn-dns.md"
+    },
+    {
+      "id": "10",
+      "slug": "release-rollout",
+      "title": "Release & Rollout",
+      "aliases": [
+        "10"
+      ],
+      "source": "content/security/10-release-rollout.md"
+    },
+    {
+      "id": "11",
+      "slug": "post-release-monitoring-ir",
+      "title": "Post-release Monitoring & Incident Response",
+      "aliases": [
+        "11"
+      ],
+      "source": "content/security/11-post-release-monitoring-ir.md"
+    },
+    {
+      "id": "12",
+      "slug": "ongoing-operations",
+      "title": "Ongoing Operations",
+      "aliases": [
+        "12"
+      ],
+      "source": "content/security/12-ongoing-operations.md"
+    }
+  ],
+  "engineering": [
+    {
+      "id": "01",
+      "slug": "query-performance",
+      "title": "Query Performance & Slow Query Diagnosis",
+      "aliases": [
+        "1"
+      ],
+      "source": "content/engineering/01-query-performance.md"
+    },
+    {
+      "id": "02",
+      "slug": "networking-fundamentals",
+      "title": "Networking Fundamentals",
+      "aliases": [
+        "2"
+      ],
+      "source": "content/engineering/02-networking-fundamentals.md"
+    },
+    {
+      "id": "03",
+      "slug": "rate-limiting-algorithms",
+      "title": "Rate Limiting Algorithm Choices",
+      "aliases": [
+        "3"
+      ],
+      "source": "content/engineering/03-rate-limiting-algorithms.md"
+    },
+    {
+      "id": "04",
+      "slug": "production-debugging",
+      "title": "Production Debugging",
+      "aliases": [
+        "4"
+      ],
+      "source": "content/engineering/04-production-debugging.md"
+    },
+    {
+      "id": "05",
+      "slug": "code-review-practices",
+      "title": "Code Review Practices",
+      "aliases": [
+        "5"
+      ],
+      "source": "content/engineering/05-code-review-practices.md"
+    },
+    {
+      "id": "06",
+      "slug": "data-modeling",
+      "title": "Data Modeling",
+      "aliases": [
+        "6"
+      ],
+      "source": "content/engineering/06-data-modeling.md"
+    },
+    {
+      "id": "07",
+      "slug": "cloud-cost-saving",
+      "title": "Cloud Cost Saving",
+      "aliases": [
+        "7"
+      ],
+      "source": "content/engineering/07-cloud-cost-saving.md"
+    },
+    {
+      "id": "08",
+      "slug": "testing-types",
+      "title": "Testing Types",
+      "aliases": [
+        "8"
+      ],
+      "source": "content/engineering/08-testing-types.md"
+    },
+    {
+      "id": "09",
+      "slug": "message-queues",
+      "title": "Message Queues",
+      "aliases": [
+        "9"
+      ],
+      "source": "content/engineering/09-message-queues.md"
+    }
+  ]
+}

package/content/engineering/01-query-performance.md

@@ -0,0 +1,48 @@
+# Query Performance & Slow Query Diagnosis
+
+# Engineering Topic 1: Query Performance & Slow Query Diagnosis
+
+**When to run this:** When a query, endpoint, or report is running slower than expected, or before shipping a new query against a table that will grow.
+
+**Goal of this pass:** Work through the standard diagnostic order for a slow query instead of guessing at fixes — read the plan first, fix the cheapest thing, and don't reach for denormalization until indexing is exhausted.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 1: Query Performance & Slow Query Diagnosis
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Start with the explain plan | Reveals whether the DB is scanning, sorting, or joining in a way that doesn't match intent — guessing at fixes without this wastes time. | Have you run EXPLAIN (or EXPLAIN ANALYZE) on the slow query and read where the time actually goes? |
+| 2 | Add the missing index | Full table scans get linearly worse as data grows; the right index turns O(n) into O(log n). | Does the WHERE/JOIN/ORDER BY column set have a supporting index? |
+| 3 | Stop selecting * | Pulling unused columns wastes I/O and network, and can defeat a covering index. | Does the query request only the columns actually used downstream? |
+| 4 | Fix N+1 queries | One query per row in a loop turns a single request into hundreds; batching/joining collapses it back to one or few. | Does any code path issue a query inside a loop over another query's results? |
+| 5 | Use a covering index | An index that includes all selected columns lets the DB answer from the index alone, skipping the table lookup. | For hot read queries, does the index include every column the query selects? |
+| 6 | Cache repeated queries | Identical, expensive, low-volatility queries don't need to hit the DB every time. | Are the same expensive read queries re-run frequently with unchanged results, and if so, are they cached? |
+| 7 | Prune partitions | Partition pruning lets the DB skip irrelevant partitions entirely instead of scanning the whole table. | For large time-series/partitioned tables, does the query filter on the partition key so pruning can kick in? |
+| 8 | Denormalize for reads | Trading write complexity/redundancy for fewer joins can be the right call once indexing alone isn't enough. | Has indexing been exhausted before reaching for denormalization, and is the redundancy kept in sync deliberately? |
+| 9 | Batch your writes | Many small write round-trips cost more in overhead than one larger batched write. | Are writes that happen together (e.g. in a loop or transaction) batched instead of issued one at a time? |
+| 10 | Update table statistics | A stale planner (out-of-date row-count/distribution stats) can pick a bad plan even with the right indexes present. | Are table statistics refreshed on a schedule (ANALYZE / equivalent), especially after large data changes? |

package/content/engineering/02-networking-fundamentals.md

@@ -0,0 +1,48 @@
+# Networking Fundamentals
+
+# Engineering Topic 2: Networking Fundamentals
+
+**When to run this:** When debugging connectivity, latency, or TLS issues, or before making infra decisions (load balancer, CDN, multi-region) that depend on understanding the network path.
+
+**Goal of this pass:** Confirm the team can reason about what happens between a client request and a server response — not memorize trivia, but recognize which layer a given production issue actually lives in.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 2: Networking Fundamentals
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | DNS resolution | Wrong TTLs or stale records cause outages/slow failover that look like application bugs. | Do you know your DNS TTLs and what happens on a DNS provider outage or a failed cutover? |
+| 2 | TCP handshake | SYN/SYN-ACK/ACK latency adds to every new connection; connection reuse avoids paying it repeatedly. | Are connections being reused (keep-alive/pooling) where the handshake cost matters? |
+| 3 | TLS handshake | Adds round trips and CPU cost on top of TCP; session resumption and TLS version choice affect both. | Is TLS session resumption enabled, and is the minimum TLS version intentionally set? |
+| 4 | NAT | Explains why a server sees one client IP for many real users, and why some P2P/inbound-connection patterns don't work as expected. | Does any rate-limiting or per-client logic depend on client IP, and does it account for NAT'd clients sharing an IP? |
+| 5 | Load balancer types | L4 vs L7 balancers differ in what they can inspect and route on (raw TCP vs HTTP headers/paths). | Does the current load balancer type actually support the routing/health-check behavior the app needs? |
+| 6 | CDN edge caching | Wrong cache-control headers cause either stale content served for too long or origin overload from no caching at all. | Are cache-control/CDN cache-key rules deliberately set per route, not left at CDN defaults? |
+| 7 | Packet loss & retransmit | Retransmits show up as latency and timeouts that look application-side but are actually network-layer. | When debugging intermittent slowness, has packet loss been ruled out before blaming application code? |
+| 8 | MTU / fragmentation | Oversized packets get fragmented or dropped, which shows up as weird partial-failure behavior, especially over VPNs/tunnels. | Has MTU mismatch been considered for any VPN, tunnel, or container network path in play? |
+| 9 | Keep-alive | Persistent connections avoid the handshake cost per request but tie up server resources if left open too long. | Are keep-alive timeouts tuned deliberately on both client and server, not left at framework defaults? |
+| 10 | BGP routing | Explains internet-scale outages and route leaks — usually outside your control, but recognizable when it's the actual cause. | When a broad, upstream-looking outage occurs, is BGP/routing considered as a possible cause rather than assumed to be your infra? |

package/content/engineering/03-rate-limiting-algorithms.md

@@ -0,0 +1,48 @@
+# Rate Limiting Algorithm Choices
+
+# Engineering Topic 3: Rate Limiting Algorithm Choices
+
+**When to run this:** When designing or reviewing a rate limiter — this is a companion to the security check in security-gate/SECURITY_CHECKLIST.md → 01_API_Security/01_rate_limiting.md, focused on picking the right algorithm rather than confirming a limiter exists.
+
+**Goal of this pass:** Make sure the chosen algorithm actually matches the traffic pattern being protected against, instead of defaulting to whatever's easiest to implement.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 3: Rate Limiting Algorithm Choices
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Fixed window | Simple to implement but allows a burst of 2x the limit right at the window boundary. | If fixed window is used, is the boundary-burst behavior acceptable for this endpoint? |
+| 2 | Sliding window log | Precise (tracks every request timestamp) but memory-heavy at scale. | If precision matters and volume is low/medium, is sliding window log a better fit than fixed window? |
+| 3 | Sliding window counter | Approximates the sliding log with much less memory by weighting two adjacent fixed windows. | For high-volume endpoints needing better accuracy than fixed window, is sliding window counter being used instead of the log variant? |
+| 4 | Token bucket | Allows controlled bursts up to the bucket size while enforcing a steady refill rate — good for bursty-but-bounded traffic. | Does the traffic pattern need to allow short bursts, and if so, is token bucket the chosen algorithm? |
+| 5 | Leaky bucket | Smooths bursty input into a constant output rate — good for protecting a downstream system that can't handle spikes at all. | Is there a downstream system that needs a strictly constant request rate, and if so, is leaky bucket used to enforce it? |
+| 6 | Distributed rate limiting | A per-instance limiter is meaningless behind a load balancer with multiple app servers — limits get multiplied by instance count. | If the app runs on more than one instance, is the rate limit state shared (e.g. via Redis) rather than per-instance? |
+| 7 | Client-side throttling | Reduces wasted requests and improves UX, but is never sufficient alone since a client can be bypassed or malicious. | Does the client throttle its own request rate, and is server-side enforcement still present as the actual control? |
+| 8 | Adaptive rate limiting | Static limits can be too strict in quiet periods or too loose under load; adaptive limits adjust to current system health. | Does the limiter adjust based on current load/error rate, or is it a single static number regardless of system state? |
+| 9 | Concurrency limiting | Limits in-flight requests, not just requests-per-second — protects against slow requests piling up and exhausting resources. | Is there a cap on concurrent in-flight requests per client, separate from the requests-per-second limit? |
+| 10 | Back pressure | Signals upstream to slow down instead of silently dropping or queuing indefinitely when a system is overloaded. | When downstream capacity is exceeded, does the system push back (429/503, queue limits) rather than accepting unbounded work? |

package/content/engineering/04-production-debugging.md

@@ -0,0 +1,48 @@
+# Production Debugging
+
+# Engineering Topic 4: Debugging Production Issues
+
+**When to run this:** Before an incident happens — this is about having the right tooling and habits in place, not what to do during a live fire.
+
+**Goal of this pass:** Confirm the team has the observability primitives needed to actually diagnose a production issue quickly, not just react to alerts.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 4: Debugging Production Issues
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Correlation IDs | Without a shared ID, tracing one user's request across multiple services means grepping logs by timestamp and guessing. | Does every request get a correlation/request ID that's propagated across all services it touches and included in every log line? |
+| 2 | Distributed tracing | Shows exactly where time is spent across a multi-service call chain — impossible to reconstruct from logs alone at scale. | Is distributed tracing (e.g. OpenTelemetry) instrumented across service boundaries? |
+| 3 | Feature flag rollback | Turning off a bad feature via flag is faster and safer than a code rollback/redeploy under incident pressure. | Can the riskiest recent features be disabled via flag without a deploy? |
+| 4 | Canary analysis | Rolling out to a small subset first catches regressions before they hit 100% of traffic. | Are risky changes rolled out to a canary/subset with automated comparison against the baseline before full rollout? |
+| 5 | Replay traffic | Re-running real production requests against a fix confirms it actually resolves the issue, not just a synthetic test case. | Is there a way to replay real production traffic (or a sample) against a candidate fix before it ships? |
+| 6 | Heap dumps | A heap dump is often the only way to root-cause a memory leak instead of guessing from symptoms. | Is heap-dump capture available (manually or via crash trigger) for services with memory-related symptoms? |
+| 7 | Chaos testing | Deliberately injecting failure in a controlled way surfaces weaknesses before real, uncontrolled failure does. | Has chaos testing (killing instances, injecting latency/errors) been run against critical paths? |
+| 8 | Synthetic monitoring | Catches outages and regressions from the outside, the way a real user would experience them, independent of internal metrics. | Are synthetic checks running against critical user journeys from outside the infrastructure? |
+| 9 | Error budgets | Gives a quantified, agreed-upon threshold for how much unreliability is acceptable, so incident response isn't a judgment call every time. | Is there an agreed error budget per service, and does exceeding it trigger a defined response (e.g. freeze on new features)? |
+| 10 | Postmortems | Without a blameless, written record, the same class of incident tends to recur because the lesson isn't institutionalized. | Does every significant incident get a blameless postmortem with concrete follow-up actions that are actually tracked to completion? |

package/content/engineering/05-code-review-practices.md

@@ -0,0 +1,48 @@
+# Code Review Practices
+
+# Engineering Topic 5: Code Review Practices
+
+**When to run this:** Ongoing — use this to periodically check whether the team's actual review habits match its stated process, not just once.
+
+**Goal of this pass:** Keep review effective and fast rather than either a rubber stamp or a bottleneck.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 5: Code Review Practices
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Small PRs | Large PRs get worse review (reviewers skim or rubber-stamp) and take longer to land. | Is there a rough size norm for PRs, and are oversized PRs flagged for splitting? |
+| 2 | Clear description | A reviewer without context re-derives the 'why' from the diff alone, which is slower and more error-prone than being told. | Does every PR description explain what changed and why, not just restate the diff? |
+| 3 | Constructive feedback | Feedback that reads as personal or vague either gets ignored or damages the reviewer/author relationship over time. | Is feedback phrased around the code/tradeoff rather than the author, with a suggested direction, not just a criticism? |
+| 4 | Nitpick vs blocker | Without this distinction, minor style opinions can block a merge as if they were correctness issues. | Are non-blocking comments explicitly labeled (e.g. 'nit:') so the author knows what's optional vs required? |
+| 5 | Fast turnaround | A PR that sits for days loses context for both author and reviewer and blocks downstream work. | Is there a target turnaround time for first review, and is it generally being met? |
+| 6 | Automated checks first | Humans shouldn't spend review time on things a linter/CI can catch automatically. | Do lint, format, and test checks run and pass before a human reviews the PR? |
+| 7 | Context before code | Reviewing code without understanding the surrounding system leads to reviews that miss integration-level problems. | Does the reviewer understand the relevant part of the system before diving into line-by-line comments? |
+| 8 | Approve vs request changes | Conflating 'I have a question' with 'this is blocked' slows things down or sends mixed signals. | Is the approve/comment/request-changes distinction used deliberately, not defaulted to whichever is habit? |
+| 9 | Self-review first | Authors catch a meaningful fraction of their own issues by re-reading the diff before asking someone else to. | Does the author review their own diff (and leave self-notes where useful) before requesting review? |
+| 10 | Learning from reviews | Review comments that aren't retained just repeat themselves across future PRs instead of becoming shared knowledge. | Do recurring review comments get turned into a lint rule, style-guide entry, or documented convention? |

package/content/engineering/06-data-modeling.md

@@ -0,0 +1,48 @@
+# Data Modeling
+
+# Engineering Topic 6: Data Modeling Concepts
+
+**When to run this:** When designing a new schema, adding a table/relationship to an existing one, or reviewing a migration before it ships.
+
+**Goal of this pass:** Confirm the schema decisions are deliberate — the right relationship type, the right key strategy, the right precision — rather than whatever the ORM defaulted to.
+
+## Files in this folder
+
+| 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.
+
+## Wrap-up
+
+- This isn't a gate — nothing here blocks a release the way
+  Critical/High security items in `../../security-gate/phases/` 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 6: Data Modeling Concepts
+
+Reference list only — no status column. Use `RESULTS_TEMPLATE.md` in
+this same folder to actually record a pass.
+
+| # | Concept | Why it matters | Self-check |
+|---|---|---|---|
+| 1 | Primary vs foreign keys | Gets the basic referential integrity of the schema right; missing FK constraints let orphaned/inconsistent data accumulate silently. | Does every relationship that should be enforced have an actual FK constraint, not just an implied convention? |
+| 2 | One-to-many | The most common relationship shape; modeling it as many-to-many or vice versa causes either data duplication or missing constraints. | For each relationship, has one-to-many vs many-to-many actually been verified against real-world cardinality, not assumed? |
+| 3 | Many-to-many | Requires a join table; skipping it (e.g. storing a comma-separated list) breaks referential integrity and queryability. | Are many-to-many relationships modeled with a proper join table rather than a denormalized list column? |
+| 4 | Composite keys | Sometimes the natural key is a combination of columns, not a synthetic ID — forcing a synthetic key can hide a real uniqueness constraint. | Where a natural composite key exists (e.g. user_id + role_id), is it enforced as a unique constraint even if a synthetic PK is also used? |
+| 5 | Soft deletes | A `deleted_at` column preserves history/auditability but means every query must remember to filter it, or leaked 'deleted' data appears. | If soft deletes are used, do all reads consistently filter them out (e.g. via a default scope), and is that not forgotten in raw queries? |
+| 6 | Polymorphic associations | Lets one table reference multiple other table types, but sacrifices FK constraint enforcement at the DB level — a known tradeoff, not a free pattern. | Where a polymorphic association is used, was that tradeoff (no DB-level FK) made deliberately, with integrity checks handled elsewhere? |
+| 7 | Enum vs lookup table | A hardcoded enum is faster to query but requires a migration/deploy to add a value; a lookup table is more flexible but adds a join. | Was the enum-vs-lookup-table choice made based on how often the value set changes, not just habit? |
+| 8 | Audit columns | Without created_at/updated_at/created_by-style columns, debugging 'when did this change and who did it' becomes guesswork. | Do tables that matter for debugging/compliance have consistent audit columns? |
+| 9 | Schema migrations | Migrations that aren't reversible or aren't tested against production-scale data can cause downtime or data loss when they run for real. | Are migrations reviewed for reversibility and tested against realistic data volume before running on production? |
+| 10 | Precision & data types | Using float for money, or too-small an int type for a growing counter, causes rounding errors or overflow that surface much later. | Are numeric types chosen deliberately (e.g. decimal for currency, right-sized int for counters expected to grow)? |