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

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@ghostbyte/agent-docs-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Documentation governance, evidence-based security audits, and engineering-quality reviews for software projects.",
+  "type": "module",
+  "bin": {
+    "agent-docs": "bin/agent-docs.mjs"
+  },
+  "exports": {
+    ".": "./src/api/index.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "content/",
+    "templates/",
+    "skills/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build-site.mjs && node scripts/build-skill.mjs",
+    "site:preview": "node scripts/preview-site.mjs",
+    "doctor": "node bin/agent-docs.mjs doctor",
+    "test": "node --test",
+    "validate": "node scripts/validate-content.mjs && node bin/agent-docs.mjs validate",
+    "prepublishOnly": "npm run build && npm test && npm run validate"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "ai-agent",
+    "documentation",
+    "security-audit",
+    "engineering-review",
+    "quality"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ghostbyte1014/Agent_Docs_Kit.git"
+  },
+  "homepage": "https://ghostbyte1014.github.io/Agent_Docs_Kit/",
+  "bugs": {
+    "url": "https://github.com/ghostbyte1014/Agent_Docs_Kit/issues"
+  },
+  "license": "MIT",
+  "author": "ghostbyte1014",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "serve.js",
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  }
+}

package/skills/manage-project-quality/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: manage-project-quality
+description: Set up and audit project documentation, perform evidence-based security reviews, or assess engineering practices. Use when asked to create or repair a docs structure, check documentation drift, conduct a security gate or phase audit, review engineering quality, generate audit evidence, or explain Agent Docs & Quality Kit results in standard or learning mode.
+---
+
+# Manage Project Quality
+
+Choose exactly one primary workflow for the request: documentation governance, security assurance, or engineering review. Combine workflows only when the user explicitly requests a broader quality pass.
+
+## Establish the operating context
+
+1. Inspect the repository, its local instructions, and the files relevant to the request.
+2. State the target, scope, exclusions, and interaction style before changing files.
+3. Use `standard` style by default. Use `learning` style when the user asks to learn; explain why each important control matters without inflating routine output.
+4. Preview file creation or replacement. Preserve unrelated user changes and do not overwrite an existing report unless explicitly authorized.
+5. Cite repository evidence with paths and line numbers. Use command output or external-system evidence when a file cannot establish the result.
+
+## Route the request
+
+### Documentation governance
+
+Read [references/documentation-governance.md](references/documentation-governance.md). Use it to establish a navigable documentation structure, identify stale or missing material, separate current scope from future ideas, and preserve decision/change history.
+
+Documentation controls are governance aids, not an infallible technical lock. Report whether evidence supports the stated process; never claim that Markdown alone enforces agent behavior.
+
+### Security assurance
+
+Read [references/security-protocol.md](references/security-protocol.md), [references/evidence-and-reporting.md](references/evidence-and-reporting.md), and only the selected phase references below.
+
+Passive source and configuration review may proceed within the user-provided repository. Before scanning a live target, sending crafted traffic, exercising credentials, changing cloud resources, or running any potentially disruptive test, obtain explicit authorization for the exact target and prefer a non-production environment.
+
+Use only `Pass`, `Fail`, `Unverified`, or `N/A`. A missing observable is `Unverified`, not `Pass` or `N/A`. Treat unresolved Critical or High failures as release blockers unless an accountable owner records a time-bounded exception.
+
+### Engineering review
+
+Read [references/engineering-protocol.md](references/engineering-protocol.md), [references/evidence-and-reporting.md](references/evidence-and-reporting.md), and only the selected topic references below.
+
+Use `Applied`, `Partial`, `Recommended`, `Unverified`, or `N/A`. Engineering recommendations are normally advisory. Clearly separate them from security gates, correctness defects, and release blockers.
+
+## Security phase references
+
+- [01 Design & Architecture](references/security-01-design-architecture.md)
+- [02 Local Development](references/security-02-local-development.md)
+- [03 Database & Backend](references/security-03-database-backend.md)
+- [04 API Layer](references/security-04-api-layer.md)
+- [05 Frontend & UI](references/security-05-frontend-ui.md)
+- [06 Application Security Testing](references/security-06-application-security-testing.md)
+- [07 CI/CD & Release Engineering](references/security-07-cicd-release-engineering.md)
+- [08 Cloud Infrastructure](references/security-08-cloud-infrastructure.md)
+- [09 Edge, CDN & DNS](references/security-09-edge-cdn-dns.md)
+- [10 Release & Rollout](references/security-10-release-rollout.md)
+- [11 Post-release Monitoring & Incident Response](references/security-11-post-release-monitoring-ir.md)
+- [12 Ongoing Operations](references/security-12-ongoing-operations.md)
+- [Full security reference](references/security-full-reference.md): search by heading or control name; do not load the entire file unless the user requests a full audit.
+
+## Engineering topic references
+
+- [01 Query Performance](references/engineering-01-query-performance.md)
+- [02 Networking Fundamentals](references/engineering-02-networking-fundamentals.md)
+- [03 Rate Limiting Algorithms](references/engineering-03-rate-limiting-algorithms.md)
+- [04 Production Debugging](references/engineering-04-production-debugging.md)
+- [05 Code Review Practices](references/engineering-05-code-review-practices.md)
+- [06 Data Modeling](references/engineering-06-data-modeling.md)
+- [07 Cloud Cost Saving](references/engineering-07-cloud-cost-saving.md)
+- [08 Testing Types](references/engineering-08-testing-types.md)
+- [09 Message Queues](references/engineering-09-message-queues.md)
+- [Full engineering reference](references/engineering-full-reference.md): use only for cross-topic review.
+
+## Produce the result
+
+1. Record scope, date, reviewer, interaction style, and evidence limitations.
+2. Assign a status only after collecting evidence.
+3. Rank findings by impact and confidence. Separate observed facts from inference.
+4. Give a concrete remediation, owner, and verification step for each actionable finding.
+5. Summarize blockers first, then non-blocking improvements, then unverified items.
+6. Never expose secrets in output. Redact tokens, credentials, personal data, and sensitive endpoints.
+
+Use [assets/security-report.md](assets/security-report.md), [assets/engineering-report.md](assets/engineering-report.md), or [assets/documentation-report.md](assets/documentation-report.md) when writing a report. Run `node scripts/check-report.mjs <report>` to catch invalid statuses and findings without evidence.

package/skills/manage-project-quality/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Docs & Quality"
+  short_description: "Govern docs and review project quality"
+  default_prompt: "Use $manage-project-quality to set up project documentation or run an evidence-based security or engineering review."

package/skills/manage-project-quality/assets/documentation-report.md

@@ -0,0 +1,12 @@
+# Documentation audit: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+
+| Document or rule | Status | Evidence | Required update |
+|---|---|---|---|
+| | Unverified | | |
+
+## Missing or conflicting authorities
+
+Record gaps, duplicate sources of truth, stale content, and broken navigation.

package/skills/manage-project-quality/assets/engineering-report.md

@@ -0,0 +1,13 @@
+# Engineering review: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+- Overall status: Unverified
+
+| Practice | Status | Evidence | Impact | Recommendation / verification |
+|---|---|---|---|---|
+| | Unverified | | | |
+
+## Priority recommendations
+
+Record the highest-value improvements and their expected tradeoffs.

package/skills/manage-project-quality/assets/security-report.md

@@ -0,0 +1,18 @@
+# Security audit: {{scope}}
+
+- Date: {{date}}
+- Reviewer: {{reviewer}}
+- Authorized target: {{target}}
+- Overall status: Unverified
+
+| Control | Severity | Status | Evidence | Remediation / verification |
+|---|---|---|---|---|
+| | | Unverified | | |
+
+## Release blockers
+
+None established yet.
+
+## Limitations and exceptions
+
+Record unavailable external evidence and approved, time-bounded risk exceptions.

package/skills/manage-project-quality/references/documentation-governance.md

@@ -0,0 +1,39 @@
+# Documentation governance
+
+## Purpose
+
+Documentation governance keeps project intent, implementation facts, decisions, and operating knowledge findable and current. It reduces context loss for humans and agents. It does not, by itself, prevent repository mutation.
+
+## Recommended project layout
+
+```text
+.agent-docs/
+  config.json
+docs/
+  README.md
+  01-system/
+  02-project/
+  03-development/
+    audits/
+    engineering-reviews/
+  04-testing/
+    security-audits/
+    evidence/
+  05-operations/
+  06-future-enhancements/
+  archive/
+```
+
+Keep the layout proportional to the project. Do not create empty documents merely to satisfy a tree. Every index must describe what belongs beneath it and identify authoritative documents.
+
+## Audit sequence
+
+1. Locate local instructions and the documentation index.
+2. Compare claimed behavior with code, configuration, tests, and deployment files.
+3. Find broken links, duplicate authorities, stale dates, unresolved placeholders, and undocumented operational dependencies.
+4. Classify each document as `Current`, `Needs update`, `Reference`, or `Archived`.
+5. Propose the smallest repair that restores a single clear source of truth.
+
+## Change records
+
+Record what changed, why it changed, files affected, validation performed, and approval when required by the project. Prefer commit-linked records. Treat a “change freeze” as a declared collaboration policy unless a technical hook or CI rule actually enforces it.

package/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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/skills/manage-project-quality/references/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)? |

package/skills/manage-project-quality/references/engineering-07-cloud-cost-saving.md

@@ -0,0 +1,48 @@
+# Cloud Cost Saving
+
+# Engineering Topic 7: Cloud Cost-Saving Techniques
+
+**When to run this:** During a cost review, before scaling up infrastructure, or when a cloud bill increase needs investigating.
+
+**Goal of this pass:** Work through the standard cost levers systematically instead of just cutting the first expensive-looking line item.
+
+## 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 7: Cloud Cost-Saving Techniques
+
+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 | Spot instances | Substantially cheaper than on-demand, but can be reclaimed with short notice — only right for interruption-tolerant workloads. | Are interruption-tolerant workloads (batch jobs, stateless workers) running on spot instead of on-demand? |
+| 2 | Autoscaling | Paying for peak capacity 24/7 wastes money during predictable low-traffic periods. | Does capacity actually scale down during known low-traffic periods, not just scale up under load? |
+| 3 | Reserved capacity | Committing to steady-state baseline load ahead of time is cheaper than paying on-demand rates for it continuously. | Has the stable, predictable-load portion of infrastructure been covered by reserved/committed-use pricing? |
+| 4 | Right-sizing | Over-provisioned instances (low CPU/memory utilization) are a direct, ongoing waste that compounds over time. | Have instance sizes been checked against actual utilization recently, not just set once at launch and left alone? |
+| 5 | Storage tiering | Infrequently accessed data doesn't need to sit on the most expensive, fastest storage tier. | Is cold/infrequently-accessed data moved to a cheaper storage tier rather than left on the default hot tier? |
+| 6 | CDN offloading | Serving static/cacheable content from origin instead of a CDN costs more in bandwidth and origin load. | Is static and cacheable content served from a CDN rather than hitting origin servers for every request? |
+| 7 | Serverless for spiky loads | Paying for always-on servers to handle infrequent, spiky workloads is wasteful compared to pay-per-invocation. | Are low-frequency, spiky workloads running serverless rather than on dedicated always-on infrastructure? |
+| 8 | Idle resource cleanup | Unattached volumes, unused load balancers, and orphaned snapshots accumulate cost silently over time. | Is there a recurring process to find and remove idle/orphaned cloud resources? |
+| 9 | Compression | Uncompressed data transfer and storage costs more in both bandwidth and storage fees than it needs to. | Is compression enabled where it's cheap to apply (asset delivery, log storage, backups)? |
+| 10 | Multi-region arbitrage | Compute/storage/egress pricing varies meaningfully by region — running in the highest-cost region without a reason is avoidable spend. | Has region choice been checked against pricing, not just picked for proximity or default? |