@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/elintp/SKILL.md

@@ -0,0 +1,155 @@
+---
+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.
+---
+
+# elintp · 把事情讲清楚，而不是把读者讲低
+
+输入：$ARGUMENTS
+
+目标：读者看完能用自己的话把这件事讲给别人听。
+
+## 两种输入
+
+**输入是主题**（一个系统、一个概念、一次故障）：自己组织内容，按下面的准则写。
+
+**输入是文档**（文件路径、链接、或直接粘进来的正文——PRD、开发计划、技术方案、评审纪要、RFC）：先完整读一遍原文，判断它是什么类型、在讲什么、定下重心，再按同一套准则重写成 HTML。产出形态、红线、写作准则全都一样，只多两层约束——**先判型再定重心**，以及**你在转述，不在创作**。
+
+分不清用户给的是主题还是文档，就问一句，不要猜。
+
+## 语言选择
+
+用户没指定语言就用简体中文；用户用哪种语言提问就用哪种，文档模式下也可以从原文判断。代码、文件名、标识符保持英文。
+
+## 红线：文档里不出现关于读者的话
+
+只写主题本身，不写读者是谁、懂不懂、需不需要懂。下面这类句子**一句都不能出现**——正文、开场白、副标题、图注、脚注，一律算：
+
+- 「这份说明写给不写代码的人。」
+- 「面向非技术人员 / 业务同事 / 小白 / 外行 / 门外汉」
+- 「你不需要懂技术也能看明白」
+- 「用大白话讲 / 通俗版 / 简化版 / 人话版」
+- 「简单来说，你只要记住一句话就够了」
+
+**为什么**：这类句子对理解主题零贡献，却把整篇的定位从「解释一件事」降成「照顾一群人」，读的人会觉得被冒犯。读者的背景决定的是**你怎么写**，不是**你写什么**——它应该体现在措辞里，而不是被声明出来。
+
+**替代做法**：开篇第一句直接给主题本身的事实或结论。
+
+- ✗ 「这份文档写给不写代码的同事，介绍我们的消息队列。」
+- ✓ 「订单提交后不会立刻扣库存，中间隔着一个排队环节，平均等待 200 毫秒。」
+
+## 写作准则
+
+- **先给结论，再给机制。** 每一节的第一句就是这一节的答案，后面才是它为什么成立。开篇不要铺垫，第一行就是答案。
+- **一句话一个意思**；写操作步骤时，一句话一个动作。
+- **主动语态，写清是谁做了什么。** 「校验拦下了这次发布」，不写「这次发布被拦下了」。
+- **句子要短。** 读到一半得换口气的句子，本来就是两句。
+- **一个词一个意思，一个意思一个词。** 同一个东西不要换着叫——读者会以为你在指不同的东西。
+- **用现在时**，除非时间本身就是要讲的事实。
+- **宁可用列表，也不要密不透风的段落**——但列表不等于可以丢掉条目之间的关系，该写清先后、因果、依赖就写清。
+- **术语该用就用，但首次出现时用一句话给出含义**，紧跟在术语后面，不要道歉、不要加引号强调「这个词很专业」。实在没有通俗说法的术语，就写读者会看到什么、要做什么，术语本身在括号里出现一次。
+- **代码、命令、配置项是精确字符串。** 用户要敲、要跑的东西一个字都不改，解释写在它周围。
+- **类比服务于精确，不服务于亲切。** 一个类比只有在它能让读者对下一段做出正确推断时才留下；不要为了显得亲切而把事情说成儿童故事。
+- **不省略读者会用到的量级。** 多快、多少、多贵、失败率多高——数字比形容词管用。
+- **不确定的地方直说不确定**，不要用模糊表述糊过去。
+- **篇幅目标是原文的一半以内**，除非「转述硬规则 1」或用户点名的条数不允许。
+
+## 文档模式第一步：判型，定重心
+
+拿到文档，动笔前先做两件事：
+
+1. **判型。** 这是 PRD、开发计划、技术方案、评审纪要，还是故障复盘？
+2. **定重心。** 读者读完要能回答哪几个问题？重心决定什么放前面、展开写，什么退到后面、一句带过。
+
+**重写不是把原文逐段换个说法再过一遍。** 原文的目录是按写作者的思路排的（背景、目标、方案、排期、风险……），新文档按读者的问题排。两者的顺序本来就不该一样。
+
+### PRD
+
+读者要能回答：
+
+- **会多出什么？** 用用户能看到的行为写，不写模块名。
+- **做完之后系统变成什么样？** 和现在的差别在哪。
+- **建议怎么实施？** 分几步、先后顺序、每一步做完能看到什么。
+
+### 开发计划
+
+先看计划里的记录，判断它做完了没有——勾选框、状态字段、进度回写小节、修订记录都是信号。
+
+- **还没做完**：重心是**要开发什么**，以及**技术路线是什么**——选了哪条路，为什么是它，代价是什么。
+- **已经做完**：重心是**做出了什么**、**读者怎么自己验证**（具体到点哪里、跑什么命令、看哪个数），以及**还有什么遗漏和要接着跟的**。
+- **做了一半**：两段都写。先讲已完成的和怎么验证，再讲剩下的和技术路线。哪部分算完，以原文的记录为准。
+
+计划里写着「已完成」而这次会话没有实际验证过，就写「计划记录为已完成」，不写「已经完成」——转述硬规则 3。
+
+#### 已完成计划：补齐引用的过程记录
+
+完成记录里引用的实施日志、里程碑记录、测试报告、验收记录等也是输入，不能只读计划里的汇总。以引用所在文档为基准解析相对路径，读完这些过程文档；如果过程文档继续引用支撑完成结论的记录，也跟进读取，同一来源只处理一次。无关链接不用展开，无法读取的引用注明缺失，不猜内容。
+
+- **每份过程记录都生成摘要**：做了什么、关键决策或变更、验证方法与记录中的结果、问题与处理、剩余缺口。按里程碑或主题合并到最终 HTML 的过程摘要中，保留来源对应关系，不只列原文链接。过程记录同样遵守转述硬规则；来源之间的状态或结果有冲突时，注明出处和差异，不自行裁定。
+- **有截图就附上**：检查过程文档中嵌入或链接的截图，查看可读取的图片，在对应摘要旁嵌入并注明它展示的步骤、结果和来源。截图只证明画面里可见的内容，不据此宣称测试通过或功能全部完成；缺失或无法查看的截图如实标注。
+- **可交给 subagent**：环境支持时，把独立的过程文档分派给 subagent。提供文档路径或内容、摘要重心和转述硬规则，要求返回摘要、精确来源、截图路径及说明、无法读取的引用和未解决问题。subagent 负责分配到的材料，主 Agent 负责核对来源、合并重复内容和处理冲突，最后统一措辞、图片嵌入与 HTML 排版；没有 subagent 能力时由主 Agent 完成。
+
+### 其他类型
+
+同样先问一句「读者读完要能回答什么问题」，再定重心。判不准类型，或者判不准计划做完没有，就问用户，不要猜。
+
+### 重心不是丢东西的借口
+
+重心决定的是**顺序和详略**，不决定去留。转述硬规则 1 照旧：原文的每条警告、风险、数字、前提，重心之外的也要在文档里出现——可以放到后面、压成一行，但不能没有。
+
+## 转述硬规则（输入是文档时）
+
+1. **只做减法，不做粉饰。** 原文里的每一条警告、风险、数字、前提条件，重写后都还在。丢掉 ⚠ 那行的「摘要」是一种谎。涉及安全、数据丢失、以及任何难以撤销的操作，展开写全，不缩写。
+2. **数字原样。** 金额、数量、日期不四舍五入。指明某个动作的工单号、PR 号照抄。
+3. **和原文一样真，不比原文更真。** 原文的说法仍然是说法：写「计划里说测试会全部通过」，不写「测试会全部通过」——除非这次会话里你自己验证过。
+4. **不清楚的地方保持不清楚。** 原文含糊的地方就写「原文没有说」，不要靠猜把它补圆。
+
+## 产出形态：一个本地 HTML 文件
+
+**默认写到本地，不发布。** 单文件、样式与脚本内联、不依赖外网资源，双击就能打开、也能直接当附件发出去。路径听用户的；用户没指定就放当前目录（仓库里已有 `docs/` 就放 `docs/`），文件名用主题命名，文档模式下跟着原文档的名字走。写完把路径告诉用户。
+
+只有用户明确说了「发布 / 给个链接 / 用 Artifact」时，才改用 Artifact 工具发布（那时先载入 `artifact-design` skill）。
+
+这份文档要靠看，不靠读：
+
+- **大图示**：核心流程/结构用一张占满宽度的图讲完，图能独立看懂（自带标注，不依赖正文）。
+- **关键数字做成指标块**：数值大字号，旁边一行说明它意味着什么（`200ms` 下面写「用户几乎察觉不到」）。
+- **图表必须带图例和轴标签**，颜色不是唯一区分手段。
+- **表格的表头带释义**：每个可能不自明的列名挂 tooltip（`title` 或自绘 tooltip），把这一列到底在说什么讲清楚。
+- 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
+- 文档模式下，正文**末尾**注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
+
+### 出图：已安装 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. 通读全文，搜一遍有没有描述读者身份/水平的句子——有就删掉，不要改写成委婉版本，直接删。
+2. 第一句话是不是主题本身的事实？如果它在介绍这份文档，重写。
+3. 每张图、每个数字：去掉它，读者会不会漏掉一个结论？不会就说明它是装饰，删。
+4. 找一个具体问题（「出故障时会怎样？」「这东西一天处理多少？」），看文档能不能答上来。答不上来就补。
+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.*