@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/elintp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: elintp
-description: 把一个技术主题、或一份技术文档（PRD、开发计划、技术方案、评审纪要）讲成任何背景的读者都能看懂并复述出来的 HTML 文档——大图示、显眼的关键数字、带图例的图表、表头带释义的表格、尽量少的术语。凡用户输入 /elintp <主题或文档>，或要求「讲得通俗一点 / 把这份 PRD 讲成人话 / 写给业务同事看的说明 / 给不做研发的同事解释这个系统」时使用。Use when the user types /elintp <topic-or-document>, or asks for a plain-language explainer or restatement of a technical document aimed at readers outside the engineering team.
+description: 把一个技术主题、或一份技术文档（PRD、开发计划、技术方案、评审纪要）讲成任何背景的读者都能看懂并复述出来的 HTML 文档——大图示、显眼的关键数字、带图例的图表、表头带释义的表格、尽量少的术语。凡用户输入 /elintp 主题或文档，或要求「讲得通俗一点 / 把这份 PRD 讲成人话 / 写给业务同事看的说明 / 给不做研发的同事解释这个系统」时使用。Use when the user types /elintp topic-or-document, or asks for a plain-language explainer or restatement of a technical document aimed at readers outside the engineering team.
 ---
 
 # elintp · 把事情讲清楚，而不是把读者讲低
@@ -81,6 +81,14 @@ description: 把一个技术主题、或一份技术文档（PRD、开发计划
 
 计划里写着「已完成」而这次会话没有实际验证过，就写「计划记录为已完成」，不写「已经完成」——转述硬规则 3。
 
+#### 已完成计划：补齐引用的过程记录
+
+完成记录里引用的实施日志、里程碑记录、测试报告、验收记录等也是输入，不能只读计划里的汇总。以引用所在文档为基准解析相对路径，读完这些过程文档；如果过程文档继续引用支撑完成结论的记录，也跟进读取，同一来源只处理一次。无关链接不用展开，无法读取的引用注明缺失，不猜内容。
+
+- **每份过程记录都生成摘要**：做了什么、关键决策或变更、验证方法与记录中的结果、问题与处理、剩余缺口。按里程碑或主题合并到最终 HTML 的过程摘要中，保留来源对应关系，不只列原文链接。过程记录同样遵守转述硬规则；来源之间的状态或结果有冲突时，注明出处和差异，不自行裁定。
+- **有截图就附上**：检查过程文档中嵌入或链接的截图，查看可读取的图片，在对应摘要旁嵌入并注明它展示的步骤、结果和来源。截图只证明画面里可见的内容，不据此宣称测试通过或功能全部完成；缺失或无法查看的截图如实标注。
+- **可交给 subagent**：环境支持时，把独立的过程文档分派给 subagent。提供文档路径或内容、摘要重心和转述硬规则，要求返回摘要、精确来源、截图路径及说明、无法读取的引用和未解决问题。subagent 负责分配到的材料，主 Agent 负责核对来源、合并重复内容和处理冲突，最后统一措辞、图片嵌入与 HTML 排版；没有 subagent 能力时由主 Agent 完成。
+
 ### 其他类型
 
 同样先问一句「读者读完要能回答什么问题」，再定重心。判不准类型，或者判不准计划做完没有，就问用户，不要猜。
@@ -111,6 +119,22 @@ description: 把一个技术主题、或一份技术文档（PRD、开发计划
 - 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
 - 文档模式下，正文**末尾**注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
 
+### 出图：已安装 archify 就调用
+
+需要以下类型的图时，由 Agent 自行检查当前环境的可用 skill 列表；列表中未找到或列表未提供时，直接查找本 skill 同级目录及当前环境的项目级、用户级 skill 目录中的 `archify/SKILL.md`。找到后加载或读取它，按其流程生成、校验和交付图。**不新增或调用 archify 安装检测脚本，不自动安装 skill。**
+
+| 文档里的图 | archify 类型 |
+|---|---|
+| 系统上下文图、容器图、部署拓扑、模块依赖 | `architecture` |
+| 请求链路、接口调用时序、鉴权 / token 交换握手 | `sequence` |
+| 业务流程、审批流、CI/CD、操作步骤 | `workflow` |
+| 数据管道、ETL、数据血缘、事件流 | `dataflow` |
+| 状态机、订单或任务的状态流转、重试与终态 | `lifecycle` |
+
+图中的事实来自输入材料，标签遵守本 skill 的语言和写作准则。JSON 格式、布局、校验、修复与浏览器检查遵守已安装 archify 的 `SKILL.md`，这里不复述。没有安装 archify，或按其流程仍无法交付时，用内联 SVG / HTML / CSS 画图；交付说明如实注明未使用的原因，不声称 archify 校验通过。
+
+**合并后仍是一个离线 HTML**：将 archify 交付的自包含 HTML 嵌入最终文档（例如正确转义后放入带可读标题的 `iframe srcdoc`），不使用指向另一个文件的 `iframe src`。过程截图以 data URI 嵌入。嵌入区域要有足够高度和移动端宽内容滚动，不能裁掉图、标签或图例。合并后检查最终 HTML 的图和截图是否完整显示；archify 原图的校验结果不能代替最终页面检查。
+
 ## 交付前自检
 
 1. 通读全文，搜一遍有没有描述读者身份/水平的句子——有就删掉，不要改写成委婉版本，直接删。
@@ -120,6 +144,8 @@ description: 把一个技术主题、或一份技术文档（PRD、开发计划
 5. 文档模式：重心里的那几个问题，文档能逐个答上来吗？答不上来的补。
 6. 文档模式：把新文档的小标题和原文目录并排看——如果一节对一节、顺序基本一致，说明你只是在逐段换说法，按重心重组。
 7. 文档模式再加一遍对照：原文的每条警告、风险、数字、前提，在新文档里都能找到吗？找不到的补回去。
+8. 已完成的开发计划：完成记录引用的每份相关过程文档都有摘要和来源吗？可读取的截图都附在对应摘要旁了吗？缺失材料和来源冲突是否注明？
+9. 属于上表的图：是否由 Agent 检查 archify 并在可用时调用？最终 HTML 离线打开后，嵌入的图和截图是否完整、可读？只报告实际做过的校验与检查。
 
 ## 常见坑
 

package/skills/figure-it-out/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: figure-it-out
+description: "Design an auditable playbook when no narrower one fits: a large migration, an ambitious multi-part change, or work a human reviews after stepping away. Scales rigor to the task, runs a hypothesis loop, and logs decisions via show-me-your-work. Use for /figure-it-out, 'figure it out', a large migration, or when no narrower playbook applies."
+disable-model-invocation: true
+---
+
+# Figure it out
+
+When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away.
+
+## Start
+
+Open a todolist whose first item is to read the Principles section of the **poteto-mode** skill. Then add the phases below as todos.
+
+## Phase A: Frame
+
+Ground first, then commit. Don't start the run until you can state:
+
+- The definition of done as a falsifiable predicate (the **prove-it-works** principle skill).
+- Scope, quantified: rough units and effort, plus the blockers grounding surfaced.
+- The rigor level, biased high. One-way doors and high blast radius get more. Reversible low-stakes steps get less. Rigor is gates and artifacts, not "try harder".
+
+Present the framing and tradeoffs before committing to a long run. Reversible work proceeds (the **never-block-on-the-human** principle skill), but a multi-hour run earns one checkpoint.
+
+## Phase B: Design the workflow
+
+Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first. Scaffold and verification come before features (the **foundational-thinking** principle skill).
+
+- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
+- For one-way-door design decisions, run the **architect** skill (it runs **arena**). Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
+- Decide what fans out. Parallelize only across seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan.
+- Write the designed phase list down. That list is what the human reviews.
+
+Then execute the design. Add its steps to the todolist as concrete items, after the Phase C entry and before Phase D. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
+
+## Phase C: Run the loop
+
+Each unit is an experiment. State the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't.
+Apply the **sequence-verifiable-units** principle skill, verifying each unit before starting the next instead of batching checks at the end.
+
+- Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system.
+- Pair delegated work with a judge. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
+- A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Inconclusive is not a pass. Don't hide a negative.
+
+## Phase D: Keep the audit trail
+
+Log the run via the **show-me-your-work** skill. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work.
+
+## Phase E: Verify and hand back
+
+Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script (the **encode-lessons-in-structure** principle skill).
+
+**Reply:** the playbook you designed, the rigor level and why, the decision-trail path, what's verified against the predicate, and what's still open.

package/skills/gdpr-compliant/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: gdpr-compliant
+description: 'Apply GDPR-compliant engineering practices across your codebase. Use this skill whenever you are designing APIs, writing data models, building authentication flows, implementing logging, handling user data, writing retention/deletion jobs, designing cloud infrastructure, or reviewing pull requests for privacy compliance. Trigger this skill for any task involving personal data, user accounts, cookies, analytics, emails, audit logs, encryption, pseudonymization, anonymization, data exports, breach response, CI/CD pipelines that process real data, or any question framed as "is this GDPR-compliant?". Inspired by CNIL developer guidance and GDPR Articles 5, 25, 32, 33, 35.'
+---
+
+# GDPR Engineering Skill
+
+Actionable GDPR reference for engineers, architects, DevOps, and tech leads.
+Inspired by CNIL developer guidance and GDPR Articles 5, 25, 32, 33, 35.
+
+> **Golden Rule:** Collect less. Store less. Expose less. Retain less.
+
+For deep dives, read the reference files in `references/`:
+- `references/data-rights.md` — user rights endpoints, DSR workflow, RoPA
+- `references/security.md` — encryption, hashing, secrets, anonymization
+- `references/operations.md` — cloud, CI/CD, incident response, architecture patterns
+
+---
+
+## 1. Core GDPR Principles (Article 5)
+
+| Principle | Engineering obligation |
+|---|---|
+| Lawfulness, fairness, transparency | Document legal basis for every processing activity in the RoPA |
+| Purpose limitation | Data collected for purpose A **MUST NOT** be reused for purpose B without a new legal basis |
+| Data minimization | Collect only fields with a documented business need today |
+| Accuracy | Provide update endpoints; propagate corrections to downstream stores |
+| Storage limitation | Define TTL at schema design time — never after |
+| Integrity & confidentiality | Encrypt at rest and in transit; restrict and audit access |
+| Accountability | Maintain evidence of compliance; RoPA ready for DPA inspection at any time |
+
+---
+
+## 2. Privacy by Design & by Default
+
+**MUST**
+- Add `CreatedAt`, `RetentionExpiresAt` to every table holding personal data at creation time.
+- Default all optional data collection to **off**. Users opt in; they never opt out of a default-on setting.
+- Conduct a **DPIA** before building high-risk processing (biometrics, health data, large-scale profiling, systematic monitoring).
+- Update the **RoPA** with every new feature that introduces a processing activity.
+- Sign a **DPA** with every sub-processor before data flows to them.
+
+**MUST NOT**
+- Ship a new data collection feature without a documented legal basis.
+- Enable analytics, tracking, or telemetry by default without explicit consent.
+- Store personal data in a system not listed in the RoPA.
+
+---
+
+## 3. Data Minimization
+
+**MUST**
+- Map every DTO/model field to a concrete business need. Remove undocumented fields.
+- Use **separate DTOs** for create, read, and update — never reuse the same object.
+- Return only what the caller is authorized to see — use response projections.
+- Mask sensitive values at the edge: return `****1234` for card numbers, never the full value.
+- Exclude sensitive fields (DOB, national ID, health) from default list/search projections.
+
+**MUST NOT**
+- Log full request/response bodies if they may contain personal data.
+- Include personal data in URL path segments or query parameters (CDN logs, browser history).
+- Collect `dateOfBirth`, national ID, or health data without an explicit legal basis.
+
+---
+
+## 4. Purpose Limitation
+
+**MUST**
+- Document the purpose of every processing activity in code comments and in the RoPA.
+- Obtain a new legal basis or perform a compatibility analysis before reusing data for a secondary purpose.
+
+**MUST NOT**
+- Share personal data collected for service delivery with advertising networks without explicit consent.
+- Use support ticket content to train ML models without a separate legal basis and user notice.
+
+---
+
+## 5. Storage Limitation & Retention
+
+**MUST**
+- Every table holding personal data **MUST** have a defined retention period.
+- Enforce retention automatically via a scheduled job (Hangfire, cron) — never a manual process.
+- Anonymize or delete data when retention expires — never leave expired data silently in production.
+
+**Recommended defaults**
+
+| Data type | Max retention |
+|---|---|
+| Auth / audit logs | 12–24 months |
+| Session / refresh tokens | 30–90 days |
+| Email / notification logs | 6 months |
+| Inactive user accounts | 12 months after last login → notify → delete |
+| Payment records | As required by tax law (7–10 years), minimized |
+| Analytics events | 13 months |
+
+**SHOULD**
+- Add `RetentionExpiresAt` column — compute at insert time.
+- Use soft-delete (`DeletedAt`) with a scheduled hard-delete after the erasure request window (30 days).
+
+**MUST NOT**
+- Retain personal data indefinitely "in case it becomes useful later."
+
+---
+
+## 6. API Design Rules
+
+**MUST**
+- MUST NOT include personal data in URL paths or query parameters.
+  - `GET /users/{userId}`
+- Authenticate all endpoints that return or accept personal data.
+- Extract the acting user's identity from the JWT — never from the request body.
+- Validate ownership on every resource: `if (resource.OwnerId != currentUserId) return 403`.
+- Use UUIDs or opaque identifiers — never sequential integers as public resource IDs.
+
+**SHOULD**
+- Rate-limit sensitive endpoints (login, data export, password reset).
+- Set `Referrer-Policy: no-referrer` and an explicit `CORS` allowlist.
+
+**MUST NOT**
+- Return stack traces, internal paths, or database errors in API responses.
+- Use `Access-Control-Allow-Origin: *` on authenticated APIs.
+
+---
+
+## 7. Logging Rules
+
+**MUST**
+- Anonymize IPs in application logs — mask last octet (IPv4) or last 80 bits (IPv6).
+  - `192.168.1.xxx`
+- MUST NOT log: passwords, tokens, session IDs, credentials, card numbers, national IDs, health data.
+- MUST NOT log full request/response bodies where PII may be present.
+- Enforce log retention — purge automatically after the defined period.
+
+**SHOULD**
+- Log **events** not data: `"User {UserId} updated email"` not `"Email changed from a@b.com to c@d.com"`.
+- Use structured logging (JSON) with `userId` as an internal identifier, not the email address.
+- Separate audit logs (sensitive access, admin actions) from application logs — different retention and ACLs.
+
+---
+
+## 8. Error Handling
+
+**MUST**
+- Return generic error messages — never expose stack traces, internal paths, or DB errors.
+  - `"Column 'email' violates unique constraint on table 'users'"`
+  - `"A user with this email address already exists."`
+- Use **Problem Details (RFC 7807)** for all error responses.
+- Log the full error server-side with a correlation ID; return only the correlation ID to the client.
+
+**MUST NOT**
+- Include file paths, class names, or line numbers in error responses.
+- Include personal data in error messages (e.g., "User john@example.com not found").
+
+---
+
+## 9. Encryption (summary — see `references/security.md` for full detail)
+
+| Scope | Minimum standard |
+|---|---|
+| Standard personal data | AES-256 disk/volume encryption |
+| Sensitive data (health, financial, biometric) | AES-256 **column-level** + envelope encryption via KMS |
+| In transit | TLS 1.2+ (prefer 1.3); HSTS enforced |
+| Keys | HSM-backed KMS; rotate DEKs annually |
+
+**MUST NOT** allow TLS 1.0/1.1, null cipher suites, or hardcoded encryption keys.
+
+---
+
+## 10. Password Hashing
+
+**MUST**
+- Use **Argon2id** (recommended) or **bcrypt** (cost ≥ 12). Never MD5, SHA-1, or SHA-256.
+- Use a unique salt per password. Store only the hash.
+
+**MUST NOT**
+- Log passwords in any form. Transmit passwords in URLs. Store reset tokens in plaintext.
+
+---
+
+## 11. Secrets Management
+
+**MUST**
+- Store all secrets in a KMS: Azure Key Vault, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.
+- Use pre-commit hooks (`gitleaks`, `detect-secrets`) to prevent secret commits.
+- Rotate secrets on developer offboarding, annual schedule, or suspected compromise.
+
+**`.gitignore` MUST include:** `.env`, `.env.*`, `*.pem`, `*.key`, `*.pfx`, `*.p12`, `secrets/`
+
+**MUST NOT**
+- Commit secrets to source code. Store secrets as plain-text environment variable defaults.
+
+---
+
+## 12. Anonymization & Pseudonymization (summary — see `references/security.md`)
+
+- **Anonymization** = irreversible → falls outside GDPR scope. Use for retained records after erasure.
+- **Pseudonymization** = reversible with a key → still personal data, reduced risk.
+- When erasing a user, anonymize records that must be retained (financial, audit) rather than deleting them.
+- Store the pseudonymization key in the KMS — never in the same database as the pseudonymized data.
+
+**MUST NOT** call data "anonymized" if re-identification is possible through linkage attacks.
+
+---
+
+## 13. Testing with Fake Data
+
+**MUST**
+- MUST NOT use production personal data in dev, staging, or CI environments.
+- MUST NOT restore production DB backups to non-production without scrubbing PII first.
+- Use synthetic data generators: `Bogus` (.NET), `Faker` (JS/Python/Ruby).
+- Use `@example.com` for all test email addresses.
+
+---
+
+## 14. Anti-Patterns
+
+| Anti-pattern | Correct approach |
+|---|---|
+| PII in URLs | Opaque UUIDs as public identifiers |
+| Logging full request bodies | Log structured event metadata only |
+| "Keep forever" schema | TTL defined at design time |
+| Production data in dev/test | Synthetic data + scrubbing pipeline |
+| Shared credentials across teams | Individual accounts + RBAC |
+| Hardcoded secrets | KMS + secret manager |
+| `Access-Control-Allow-Origin: *` on auth APIs | Explicit CORS allowlist |
+| Storing consent with profile data | Dedicated consent store |
+| PII in GET query params | POST body or authenticated session |
+| Sequential integer IDs in public URLs | UUIDs |
+| "Anonymized" data with quasi-identifiers | Apply k-anonymity, test linkage resistance |
+| Mixing backup regions outside EEA | Explicit region lockdown on backup jobs |
+
+---
+
+## 15. PR Review Checklist
+
+### Data model
+- Every new PII column has a documented purpose and retention period.
+- Sensitive fields (health, financial, national ID) use column-level encryption.
+- No sequential integer PKs as public-facing identifiers.
+
+### API
+- No PII in URL paths or query parameters.
+- All endpoints returning personal data are authenticated.
+- Ownership checks present — user cannot access another user's resource.
+- Rate limiting applied to sensitive endpoints.
+
+### Logging
+- No passwords, tokens, or credentials logged.
+- IPs anonymized (last octet masked).
+- No full request/response bodies logged where PII may be present.
+
+### Infrastructure
+- No public storage buckets or public-IP databases.
+- New cloud resources tagged with `DataClassification`.
+- Encryption at rest enabled for new storage resources.
+- New geographic regions for data storage are EEA-compliant or covered by SCCs.
+
+### Secrets & CI/CD
+- No secrets in source code or committed config files.
+- New secrets added to KMS and secrets inventory document.
+- CI/CD secrets masked in pipeline logs.
+
+### Retention & erasure
+- Retention enforcement job or policy covers new data store or field.
+- Erasure pipeline updated to cover new data store.
+
+### User rights & governance
+- Data export endpoint includes any new personal data field.
+- RoPA updated if a new processing activity is introduced.
+- New sub-processors have a signed DPA and a RoPA entry.
+- DPIA triggered if the change involves high-risk processing.
+
+---
+
+> **Golden Rule:** Collect less. Store less. Expose less. Retain less.
+>
+> Every byte of personal data you do not collect is a byte you cannot lose,
+> cannot breach, and cannot be held liable for.
+
+---
+
+*Inspired by CNIL developer GDPR guidance, GDPR Articles 5, 25, 32, 33, 35,
+ENISA, OWASP, and NIST engineering best practices.*

package/skills/gdpr-compliant/references/Security.md

@@ -0,0 +1,266 @@
+# GDPR Reference — Security, Operations & Architecture
+
+Load this file when you need implementation detail on:
+encryption, password hashing, secrets management, anonymization/pseudonymization,
+cloud/DevOps practices, CI/CD controls, incident response, architecture patterns.
+
+---
+
+## Encryption
+
+### At-Rest Encryption
+
+| Data sensitivity | Minimum standard |
+|---|---|
+| Standard personal data (name, address, email) | AES-256 disk/volume encryption (cloud provider default) |
+| Sensitive personal data (health, biometric, financial, national ID) | AES-256 **column-level** encryption + envelope encryption via KMS |
+| Encryption keys | HSM-backed KMS (Azure Key Vault Premium / AWS KMS CMK / GCP Cloud KMS) |
+
+**Envelope encryption pattern:**
+1. Encrypt data with a **Data Encryption Key (DEK)** (AES-256, generated per record or per table).
+2. Encrypt the DEK with a **Key Encryption Key (KEK)** stored in the KMS.
+3. Store the encrypted DEK alongside the encrypted data.
+4. Deleting the KEK = effective crypto-shredding of all data encrypted with it.
+
+### In-Transit Encryption
+
+- **MUST** enforce TLS 1.2 minimum; prefer TLS 1.3.
+- **MUST** set `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`.
+- **MUST NOT** allow TLS 1.0, TLS 1.1, null cipher suites, or export-grade ciphers.
+- **MUST NOT** use self-signed certificates in production.
+
+### Key Management
+
+- Rotate DEKs annually minimum; rotate immediately upon suspected compromise.
+- Use separate key namespaces per environment (dev / staging / prod).
+- Log all KMS key access events — alert on anomalous access patterns.
+- MUST NOT hardcode encryption keys in source code or configuration files.
+
+---
+
+## Password Hashing
+
+| Algorithm | Parameters | Notes |
+|---|---|---|
+| **Argon2id**  recommended | memory ≥ 64 MB, iterations ≥ 3, parallelism ≥ 4 | OWASP and NIST recommended |
+| **bcrypt**  acceptable | cost factor ≥ 12 | Widely supported; use if Argon2id unavailable |
+| **scrypt**  acceptable | N=32768, r=8, p=1 | Good alternative |
+| MD5  | — | Never — trivially broken |
+| SHA-1 / SHA-256  | — | Never for passwords — not designed for this purpose |
+
+**MUST**
+- Use a unique salt per password (built into all three algorithms above).
+- Store only the hash — never the plaintext, never a reversible encoding.
+- Re-hash on login if the stored hash uses an outdated algorithm — upgrade transparently.
+
+**SHOULD**
+- Add a **pepper** (server-side secret added before hashing) stored in the KMS, not in the DB.
+- Check passwords against known breach lists at registration (`haveibeenpwned` API, k-anonymity mode).
+- Enforce minimum password length of 12 characters.
+
+**MUST NOT**
+- Log passwords in any form — not during registration, not during failed login.
+- Transmit passwords in URLs or query strings.
+- Store password reset tokens in plaintext — hash them before storage.
+
+---
+
+## Secrets Management
+
+**MUST**
+- Store all secrets in a dedicated secret manager: Azure Key Vault, AWS Secrets Manager,
+  GCP Secret Manager, or HashiCorp Vault.
+- Use pre-commit hooks to prevent secret commits: `gitleaks`, `detect-secrets`, GitHub native secret scanning.
+- Rotate secrets immediately upon: developer offboarding, suspected compromise, annual schedule.
+- Maintain a **secrets inventory document** — every secret listed with its purpose and rotation date.
+
+**SHOULD**
+- Use **short-lived credentials** via OIDC federation (GitHub Actions → Azure/AWS/GCP) instead of long-lived API keys.
+- Audit all KMS secret access — alert on access outside business hours or from unexpected sources.
+- Use separate secret namespaces per environment.
+
+**`.gitignore` MUST include:**
+```
+.env
+.env.*
+*.pem
+*.key
+*.pfx
+*.p12
+secrets/
+appsettings.*.json   # if it may contain connection strings
+```
+
+**MUST NOT**
+- Commit secrets to source code repositories.
+- Pass secrets as plain-text CLI arguments (they appear in process lists and shell history).
+- Store secrets as unencrypted environment variable defaults in code.
+
+---
+
+## Anonymization & Pseudonymization
+
+### Definitions
+
+| Term | Reversible? | GDPR scope? | Use case |
+|---|---|---|---|
+| **Anonymization** | No | Outside GDPR scope | Retained records after erasure, analytics datasets |
+| **Pseudonymization** | Yes (with key) | Still personal data | Analytics pipelines, audit logs, reduced-risk processing |
+
+### Anonymization Techniques
+
+| Technique | How | When |
+|---|---|---|
+| Suppression | Remove the field entirely | Fields with no analytical value |
+| Masking | Replace with fixed placeholder (`"ANONYMIZED_USER"`) | Audit log identifiers after erasure |
+| Generalization | Replace exact value with a range (age 34 → "30–40") | Analytics |
+| Noise addition | Add statistical noise to numerical values | Aggregate analytics |
+| Aggregation | Report group statistics, never individual values | Reporting |
+| K-anonymity | Ensure each record is indistinguishable from k-1 others | Analytics datasets |
+
+### Pseudonymization Techniques
+
+| Technique | How |
+|---|---|
+| HMAC-SHA256 with secret key | Consistent, one-way, keyed. Use for user IDs in analytics. Key in KMS. |
+| Tokenization | Replace value with opaque token; mapping in separate secure vault. |
+| Encryption with separate key | Decrypt only with explicit KMS authorization. |
+
+**MUST**
+- When erasing a user, **anonymize** records that must be retained (financial, audit logs) — replace identifying fields with `"ANONYMIZED"` or a hashed placeholder.
+- Store the pseudonymization key in the KMS — never in the same database as the pseudonymized data.
+- Test anonymization routines with assertions: the original value MUST NOT be recoverable from the output.
+
+**Crypto-shredding pattern (event sourcing):**
+Encrypt personal data in events with a per-user DEK. Store the DEK in the KMS.
+On erasure: delete the DEK from the KMS → all events for that user are effectively anonymized.
+
+**MUST NOT**
+- Call data "anonymized" if re-identification is possible through linkage with other datasets.
+- Apply pseudonymization and store the mapping key in the same table as the pseudonymized data.
+
+---
+
+## Cloud & DevOps Practices
+
+**MUST**
+- Enable encryption at rest for all cloud storage: blobs, managed databases, queues, caches.
+- Use **private endpoints** — databases MUST NOT be publicly accessible.
+- Apply network security groups / firewall rules: restrict DB access to application layers only.
+- Enable cloud-native audit logging: Azure Monitor / AWS CloudTrail / GCP Cloud Audit Logs.
+- Store personal data only in **approved geographic regions** (EEA, or adequacy decision / SCCs).
+- Tag all cloud resources processing personal data with a `DataClassification` tag.
+
+**SHOULD**
+- Enable Microsoft Defender for Cloud / AWS Security Hub / GCP SCC — review recommendations weekly.
+- Use **managed identities** (Azure) or **IAM roles** (AWS/GCP) instead of long-lived access keys.
+- Enable soft delete and versioning on object storage.
+- Apply DLP policies on cloud storage to detect PII written to unprotected buckets.
+- Enable database-level audit logging for SELECT on sensitive tables.
+
+**MUST NOT**
+- Store personal data in public storage buckets without access controls.
+- Deploy databases with public IPs in production.
+- Use the same cloud account/subscription for production and non-production if data could bleed across.
+
+---
+
+## CI/CD Controls
+
+**MUST**
+- Run **secret scanning** on every commit: `gitleaks`, `detect-secrets`, GitHub secret scanning.
+- Run **dependency vulnerability scanning** on every build: `npm audit`, `dotnet list package --vulnerable`, `trivy`, `snyk`.
+- MUST NOT use real personal data in CI test jobs.
+- MUST NOT log environment variables in CI pipelines — mask all secrets.
+
+**SHOULD**
+- Run **SAST**: SonarQube, Semgrep, or CodeQL on every PR.
+- Run **container image scanning**: `trivy`, Snyk Container, or AWS ECR scanning.
+- Add a **GDPR compliance gate** to the pipeline:
+  - New migrations without a documented retention period → fail.
+  - Log statements containing known PII field names → warn.
+
+**Pipeline secret rules:**
+```yaml
+# MUST: mask secrets before use
+- name: Mask secret
+  run: echo "::add-mask::${{ secrets.MY_SECRET }}"
+
+# MUST NOT: echo secrets to console
+- run: echo "Key=$API_KEY"   # Never
+
+# SHOULD: use OIDC federation (no long-lived keys)
+- uses: azure/login@v1
+  with:
+    client-id: ${{ vars.AZURE_CLIENT_ID }}
+    tenant-id: ${{ vars.AZURE_TENANT_ID }}
+    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+```
+
+---
+
+## Incident & Breach Handling
+
+### Regulatory Timeline
+
+| Window | Obligation |
+|---|---|
+| **72 hours** from awareness | Notify the supervisory authority (CNIL, APD, ICO…) — unless breach is unlikely to risk individuals |
+| **Without undue delay** | Notify affected data subjects if breach is likely to result in **high risk** to their rights |
+
+Log **all** personal data breaches internally — even those that do not require DPA notification.
+
+### Breach Response Runbook (template)
+
+1. **Detection** — Define criteria: what triggers an incident (credential leak, DB dump exposed, ransomware, accidental public bucket).
+2. **Severity classification** — Low / Medium / High / Critical based on data sensitivity and volume.
+3. **Containment** — Revoke compromised credentials; isolate affected systems; preserve evidence (do NOT delete logs).
+4. **Assessment** — What data was exposed? How many subjects? What is the risk level?
+5. **DPA notification** — Use the supervisory authority's online portal; include: nature of breach, categories and approximate number of data subjects, categories and approximate number of records, contact point, likely consequences, measures taken.
+6. **Data subject notification** — If high risk: clear language, nature of breach, likely consequences, measures taken, DPO contact.
+7. **Post-incident review** — Root cause analysis; corrective measures; update runbook.
+
+### Automated Breach Detection Alerts
+
+Configure alerts for:
+- Unusual volume of data exports (threshold per hour)
+- Access to sensitive tables outside business hours
+- Bulk deletion events
+- Failed authentication spikes
+- New credentials appearing in public breach databases (HaveIBeenPwned monitoring)
+
+Store breach records internally for at least **5 years**.
+
+---
+
+## Architecture Patterns
+
+### Data Store Separation
+Separate operational data (transactional DB) from analytical data (data warehouse).
+Apply different retention periods and access controls to each.
+The analytics store MUST NOT read directly from production operational tables.
+
+### Dedicated Consent Store
+Track consent as an immutable event log in a separate store, not a boolean column on the user table.
+This enables: auditable consent history, version tracking, easy withdrawal without data loss.
+
+### Audit Log Segregation
+Store audit logs in a separate, append-only store.
+The application service account MUST NOT be able to delete audit log entries.
+Use a separate DB user with INSERT-only rights on the audit table.
+
+### DSR Queue Pattern
+Implement Data Subject Requests as an asynchronous workflow:
+`POST /api/v1/me/erasure-request` → enqueue a job → worker scrubs all stores → notify user on completion.
+This handles the complexity of multi-store scrubbing reliably and provides a retry mechanism.
+
+### Pseudonymization Gateway
+For analytics pipelines, implement a pseudonymization service at the boundary between
+operational and analytical systems.
+The mapping key (HMAC secret or tokenization vault) never leaves the operational zone.
+The analytics zone receives only pseudonymized identifiers.
+
+### Crypto-Shredding (Event Sourcing)
+Encrypt personal data in events with a per-user DEK stored in the KMS.
+On user erasure: delete the DEK → all historical events for that user are effectively anonymized
+without modifying the event log.