feat(framework): Phase 2 PR 4 — approval workflow canonization (closes #67)

dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md

@@ -98,6 +98,9 @@ related:
 | `observability_scope` | OTel instrumentation level: `none \| basic \| full` | When the change involves observability instrumentation |
 | `api_spec_path` | Path to OpenAPI/AsyncAPI specification file | In REQ documents when the requirement involves API interfaces |
 | `api_changes` | List of API endpoints affected | In ADR documents when the decision modifies public APIs |
+| `reviewed_by` | Identity of the human reviewer (email, GitHub handle, or DID) | Set by the reviewer when formally approving a `review_required: true` document |
+| `reviewed_at` | Date of the formal approval (`YYYY-MM-DD`, must be ≥ `created`) | Set with `reviewed_by` |
+| `review_outcome` | Closure signal: `approved \| revisions_requested \| rejected` | Set with `reviewed_by`. Presence is the canonical "human has reviewed" signal — see §4.5 below |
 
 ### Tags Convention
 
@@ -161,6 +164,50 @@ draft ──────► accepted ──────► deprecated
 
 ---
 
+## 3.5 Recording Approval
+
+`status` records the document's lifecycle state, and `review_required: true` records that *human review is needed*. Neither field records that human review *has actually happened*. This section defines the canonical closure signal for documents that need formal approval (AIDEC, ETH, MCARD, ADR, DPIA, INC, SEC and the China-scope variants — see AGENT-RULES.md §4 for the triggers).
+
+### Closure signal
+
+Three optional frontmatter fields, set by the reviewer at approval time:
+
+```yaml
+reviewed_by: pepe@example.com           # email | github-handle | DID
+reviewed_at: 2026-05-02
+review_outcome: approved                # approved | revisions_requested | rejected
+```
+
+Semantics:
+
+- **The presence of `review_outcome` is the closure signal.** A document with `review_required: true` and no `review_outcome` is *pending review*.
+- `review_required: true` is **not** toggled to `false` after approval — it remains as historical record of why review was needed in the first place.
+- `reviewed_at` must be `>= created`. If `reviewed_by` is set, `reviewed_at` and `review_outcome` must also be set (validated by `devtrail validate`).
+- `review_outcome: revisions_requested` allows iterative review cycles: the document is updated, and the reviewer eventually re-approves. The convention is to overwrite the three fields with the latest approval (frontmatter holds only the most recent state); the body section below preserves history.
+
+### Body section (canonical prose form)
+
+Add at the terminal position of the document body (e.g., before `## References` in AIDEC/ADR; after `## Review Schedule` in DPIA; after `## Post-Mortem Review` in INC). For templates that already include a `## Approval` table (ETH, MCARD, SEC, PIPIA, CACFILE, TC260RA, AILABEL), either form is canonical; the frontmatter fields are the machine-readable source of truth.
+
+```markdown
+## Approval
+
+**Approved**: 2026-05-02 by `pepe@example.com`.
+
+<Optional reviewer notes — observations, conditions, scope of approval. Omit
+the entire section if there's nothing to add beyond the frontmatter.>
+```
+
+### Multi-reviewer flows (forward-looking)
+
+For documents that require multiple reviewers (e.g., ETH with both legal and engineering sign-off), the canon for v1 is to append additional `## Approval` blocks chronologically in the body, with the frontmatter reflecting the *latest* approval. A structured `review:` array form (one entry per reviewer) is forward-looking and not part of v1 — it will be added when at least one adopter exercises the multi-reviewer flow with real data.
+
+### CLI tooling
+
+`devtrail approve <doc-id> --outcome approved --reviewer <id> [--notes "..."] [--at YYYY-MM-DD]` writes both the frontmatter fields and the body section in one shot. `devtrail validate --check-pending-reviews [--max-pending-days N]` lists `review_required: true` documents older than `N` days without a `review_outcome` (warn-only, no error). See CLI-REFERENCE.md.
+
+---
+
 ## 4. Risk Levels
 
 | Level | When to use | Requires review |

dist/.devtrail/00-governance/i18n/es/DOCUMENTATION-POLICY.md

@@ -98,6 +98,9 @@ related:
 | `observability_scope` | Nivel de instrumentación OTel: `none \| basic \| full` | Cuando el cambio involucra instrumentación de observabilidad |
 | `api_spec_path` | Ruta al archivo de especificación OpenAPI/AsyncAPI | En documentos REQ cuando el requisito involucra interfaces de API |
 | `api_changes` | Lista de endpoints de API afectados | En documentos ADR cuando la decisión modifica APIs públicas |
+| `reviewed_by` | Identidad del revisor humano (email, usuario de GitHub o DID) | Lo establece el revisor al aprobar formalmente un documento `review_required: true` |
+| `reviewed_at` | Fecha de la aprobación formal (`YYYY-MM-DD`, debe ser ≥ `created`) | Se establece junto con `reviewed_by` |
+| `review_outcome` | Señal de cierre: `approved \| revisions_requested \| rejected` | Se establece junto con `reviewed_by`. Su presencia es la señal canónica de "un humano ya revisó" — ver §3.5 abajo |
 
 ### Convención de Tags
 
@@ -161,6 +164,51 @@ draft ──────► accepted ──────► deprecated
 
 ---
 
+## 3.5 Registro de Aprobación
+
+`status` registra el estado del ciclo de vida del documento, y `review_required: true` registra que *se necesita revisión humana*. Ningún campo registra que la revisión humana *efectivamente ocurrió*. Esta sección define la señal canónica de cierre para documentos que requieren aprobación formal (AIDEC, ETH, MCARD, ADR, DPIA, INC, SEC y las variantes del scope China — ver AGENT-RULES.md §4 para los disparadores).
+
+### Señal de cierre
+
+Tres campos de frontmatter opcionales, establecidos por el revisor al momento de la aprobación:
+
+```yaml
+reviewed_by: pepe@ejemplo.com           # email | usuario-github | DID
+reviewed_at: 2026-05-02
+review_outcome: approved                # approved | revisions_requested | rejected
+```
+
+Semántica:
+
+- **La presencia de `review_outcome` es la señal de cierre.** Un documento con `review_required: true` y sin `review_outcome` está *pendiente de revisión*.
+- `review_required: true` **no** se cambia a `false` después de la aprobación — permanece como registro histórico de por qué hizo falta revisión en primer lugar.
+- `reviewed_at` debe ser `>= created`. Si `reviewed_by` está presente, `reviewed_at` y `review_outcome` también deben estarlo (validado por `devtrail validate`).
+- `review_outcome: revisions_requested` permite ciclos iterativos de revisión: el documento se actualiza y el revisor eventualmente vuelve a aprobar. La convención es sobreescribir los tres campos con la aprobación más reciente (el frontmatter contiene solo el último estado); la sección body de abajo preserva la historia.
+
+### Sección body (forma canónica en prosa)
+
+Agregar en la posición terminal del cuerpo del documento (p. ej., antes de `## References` en AIDEC/ADR; después de `## Review Schedule` en DPIA; después de `## Post-Mortem Review` en INC). Para los templates que ya incluyen una tabla `## Approval` (ETH, MCARD, SEC, PIPIA, CACFILE, TC260RA, AILABEL), cualquiera de las dos formas es canónica; los campos del frontmatter son la fuente de verdad legible-por-máquina.
+
+```markdown
+## Approval
+
+**Approved**: 2026-05-02 by `pepe@ejemplo.com`.
+
+<Notas opcionales del revisor — observaciones, condiciones, alcance de la
+aprobación. Omitir la sección entera si no hay nada que añadir más allá del
+frontmatter.>
+```
+
+### Flujos multi-revisor (forward-looking)
+
+Para documentos que requieren múltiples revisores (p. ej., ETH con sign-off de legal y de ingeniería), el canon de v1 es agregar bloques adicionales `## Approval` cronológicamente en el body, con el frontmatter reflejando la *última* aprobación. Una forma estructurada con array `review:` (una entrada por revisor) es forward-looking y no es parte de v1 — se añadirá cuando al menos un proyecto adoptante ejercite el flujo multi-revisor con datos reales.
+
+### Tooling del CLI
+
+`devtrail approve <doc-id> --outcome approved --reviewer <id> [--notes "..."] [--at YYYY-MM-DD]` escribe los campos del frontmatter y la sección del body en una sola operación. `devtrail validate --check-pending-reviews [--max-pending-days N]` lista documentos con `review_required: true` más antiguos que `N` días sin `review_outcome` (warn-only, no error). Ver CLI-REFERENCE.md.
+
+---
+
 ## 4. Niveles de Riesgo
 
 | Nivel | Cuándo usar | Requiere revisión |

dist/.devtrail/00-governance/i18n/zh-CN/DOCUMENTATION-POLICY.md

@@ -98,6 +98,9 @@ related:
 | `observability_scope` | OTel 埋点级别：`none \| basic \| full` | 当变更涉及可观测性埋点时 |
 | `api_spec_path` | OpenAPI/AsyncAPI 规范文件路径 | 在 REQ 文档中，当需求涉及 API 接口时 |
 | `api_changes` | 受影响的 API 端点列表 | 在 ADR 文档中，当决策修改公共 API 时 |
+| `reviewed_by` | 人工审批人的身份（邮箱、GitHub 用户或 DID） | 由审批人在正式批准 `review_required: true` 文档时填写 |
+| `reviewed_at` | 正式批准日期（`YYYY-MM-DD`，必须 ≥ `created`） | 与 `reviewed_by` 一同设置 |
+| `review_outcome` | 闭环信号：`approved \| revisions_requested \| rejected` | 与 `reviewed_by` 一同设置。其存在即为"人工已审"的规范信号——见下方 §3.5 |
 
 ### 标签约定
 
@@ -161,6 +164,50 @@ draft ──────► accepted ──────► deprecated
 
 ---
 
+## 3.5 审批记录
+
+`status` 记录文档的生命周期状态，`review_required: true` 记录*需要人工审核*。这两个字段都不记录人工审核*实际是否发生*。本节定义了需要正式审批的文档（AIDEC、ETH、MCARD、ADR、DPIA、INC、SEC 以及中国 scope 变体——触发条件见 AGENT-RULES.md §4）的规范闭环信号。
+
+### 闭环信号
+
+三个可选的 frontmatter 字段，由审批人在批准时填写：
+
+```yaml
+reviewed_by: pepe@example.com           # 邮箱 | github 用户 | DID
+reviewed_at: 2026-05-02
+review_outcome: approved                # approved | revisions_requested | rejected
+```
+
+语义：
+
+- **`review_outcome` 的存在即为闭环信号。** 一份 `review_required: true` 且无 `review_outcome` 的文档处于*待审核*状态。
+- 批准之后**不**将 `review_required: true` 改为 `false` —— 它作为"为何最初需要审核"的历史记录保留下来。
+- `reviewed_at` 必须 `>= created`。如果 `reviewed_by` 已设置，`reviewed_at` 与 `review_outcome` 也必须设置（由 `devtrail validate` 校验）。
+- `review_outcome: revisions_requested` 支持迭代审核循环：文档被更新，审批人最终再次批准。约定是用最新一次的审批覆盖三个字段（frontmatter 仅保留最新状态）；下方 body 章节保留历史。
+
+### Body 章节（规范的散文形式）
+
+添加在文档正文的末位（例如：AIDEC/ADR 的 `## References` 之前；DPIA 的 `## Review Schedule` 之后；INC 的 `## Post-Mortem Review` 之后）。对于已包含 `## Approval` 表格形式的模板（ETH、MCARD、SEC、PIPIA、CACFILE、TC260RA、AILABEL），任一形式都是规范的；frontmatter 字段才是机器可读的真相源。
+
+```markdown
+## Approval
+
+**Approved**: 2026-05-02 by `pepe@example.com`.
+
+<可选的审批人备注——观察、条件、批准范围。如果没有需要补充于 frontmatter
+之外的内容，可整节省略。>
+```
+
+### 多审批人流程（前瞻性）
+
+对于需要多审批人的文档（如 ETH 同时需要法务和工程的 sign-off），v1 的规范是在 body 中按时间顺序追加多个 `## Approval` 块，frontmatter 反映*最新*一次的批准。结构化的 `review:` 数组形式（每个审批人一条）属于前瞻性，不在 v1 中——会等到至少一个真实采用项目以真实数据演练多审批人流程后再加入。
+
+### CLI 工具
+
+`devtrail approve <doc-id> --outcome approved --reviewer <id> [--notes "..."] [--at YYYY-MM-DD]` 一次性写入 frontmatter 字段与 body 章节。`devtrail validate --check-pending-reviews [--max-pending-days N]` 列出 `review_required: true` 且早于 `N` 天但仍无 `review_outcome` 的文档（warn-only，不报错）。详见 CLI-REFERENCE.md。
+
+---
+
 ## 4. 风险级别
 
 | 级别 | 使用场景 | 是否需要审核 |

dist/.devtrail/templates/TEMPLATE-ADR.md

@@ -7,6 +7,11 @@ updated: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: high | medium | low
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: medium | high | critical
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 iso_42001_clause: []            # 4 | 5 | 6 | 7 | 8 | 9 | 10

dist/.devtrail/templates/TEMPLATE-AIDEC.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: high | medium | low
 review_required: false
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: low | medium | high | critical
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 nist_genai_risks: []            # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain

dist/.devtrail/templates/TEMPLATE-AILABEL.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: medium
 gb45438_applicable: true
 gb45438_content_types: []  # subset of: text | image | audio | video | virtual_scene

dist/.devtrail/templates/TEMPLATE-CACFILE.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high
 cac_filing_required: true
 cac_filing_type: algorithm  # algorithm | generative_ai | dual

dist/.devtrail/templates/TEMPLATE-DPIA.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: low  # DPIA requires extensive human judgment
 review_required: true  # Always mandatory
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 gdpr_article_35: true  # Art. 35 GDPR triggers DPIA

dist/.devtrail/templates/TEMPLATE-ETH.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: medium | low
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high | critical
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 nist_genai_risks: []            # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain

dist/.devtrail/templates/TEMPLATE-INC.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high | critical
 severity: SEV1 | SEV2 | SEV3 | SEV4
 eu_ai_act_applicable: false

dist/.devtrail/templates/TEMPLATE-MCARD.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: medium
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 nist_genai_risks: []            # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain

dist/.devtrail/templates/TEMPLATE-PIPIA.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: low  # PIPIA requires extensive human judgment
 review_required: true  # Always mandatory under PIPL Art. 55
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high
 pipl_applicable: true
 pipl_article_55_trigger: sensitive_data  # sensitive_data | automated_decision | third_party_disclosure | cross_border | public_disclosure | other

dist/.devtrail/templates/TEMPLATE-SEC.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 iso_42001_clause: [6, 8]

dist/.devtrail/templates/TEMPLATE-TC260RA.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Approval workflow (optional, fill at review time) ---
+# reviewed_by: <reviewer-id>           # email | github-handle | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: high
 tc260_application_scenario: null  # e.g., public_service | healthcare | finance | content_generation | social | safety_critical
 tc260_intelligence_level: null    # narrow | foundation | agentic | general

dist/.devtrail/templates/i18n/es/TEMPLATE-ADR.md

@@ -7,6 +7,11 @@ updated: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: high | medium | low
 review_required: true
+
+# --- Workflow de aprobación (opcional, llenar al momento de la revisión) ---
+# reviewed_by: <id-revisor>            # email | usuario-github | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: medium | high | critical
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 iso_42001_clause: []            # 4 | 5 | 6 | 7 | 8 | 9 | 10

dist/.devtrail/templates/i18n/es/TEMPLATE-AIDEC.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name-v1.0]
 confidence: high | medium | low
 review_required: false
+
+# --- Workflow de aprobación (opcional, llenar al momento de la revisión) ---
+# reviewed_by: <id-revisor>            # email | usuario-github | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: low | medium | high | critical
 eu_ai_act_risk: not_applicable  # unacceptable | high | limited | minimal | not_applicable
 nist_genai_risks: []            # privacy | bias | confabulation | cbrn | dangerous_content | environmental | human_ai_config | information_integrity | information_security | intellectual_property | obscene_content | value_chain

dist/.devtrail/templates/i18n/es/TEMPLATE-AILABEL.md

@@ -6,6 +6,11 @@ created: YYYY-MM-DD
 agent: [agent-name]
 confidence: medium
 review_required: true
+
+# --- Workflow de aprobación (opcional, llenar al momento de la revisión) ---
+# reviewed_by: <id-revisor>            # email | usuario-github | DID
+# reviewed_at: YYYY-MM-DD
+# review_outcome: approved             # approved | revisions_requested | rejected
 risk_level: medium
 gb45438_applicable: true
 gb45438_content_types: []  # subset of: text | image | audio | video | virtual_scene