RFC: Canonical approval workflow for review_required documents (AIDEC, ETH, MCARD, ADR)

[montfort]

Summary

DevTrail format v4.4.0 defines review_required: true | false as a flag in
the document frontmatter (DOCUMENTATION-POLICY.md §2), but the canon does
not define how a reviewer formally records their approval. As a result,
documents that need human review accumulate in an ambiguous state: the agent
marks them status: accepted (its own acceptance), review_required: true
stays as a flag, and there is no canonical signal that a human has actually
reviewed and approved the document.

This RFC proposes adding a small set of optional frontmatter fields and a
canonical ## Approval body section so the approval lifecycle becomes
machine-readable and auditable.

Evidence: the gap is operational, not theoretical

In a downstream project (Sentinel, internal Strange Days Tech), I observed
two AIDECs with review_required: true that demonstrate the gap:

1. AIDEC-2026-04-23-001-saga-step-3-no-rollback.md — created
   2026-04-23 with review_required: true. Ten days later (2026-05-02),
   no formal approval signal exists in the document. Whether it was
   actually reviewed is invisible to any automated tool or future reader.

2. AIDEC-2026-05-02-001-devtrail-post-merge-plan-doc-cleanup-canon-gap.md
   — created 2026-05-02 with review_required: true to propose adoption
   of a process pattern. Without an approval mechanism, "reviewed and
   accepted" is verbal rather than documented.

The same gap likely exists across other repos that use DevTrail. For
documents whose review_required: true is set automatically (SEC, MCARD,
DPIA per AGENT-RULES.md §3), the gap compounds — every such document piles
up without a closure signal.

Current state of the canon

DOCUMENTATION-POLICY.md §2 lists:

• status: draft | accepted | deprecated | superseded
• review_required: true | false

AGENT-RULES.md §4 ("When to Request Human Review") lists 10 triggers for
setting review_required: true, but provides no instruction for what
happens after the review.

Proposed change

Add three optional frontmatter fields and a canonical body section. None
of these break backward compatibility — existing documents that don't use
them remain valid.

1. New optional frontmatter fields

reviewed_by: <reviewer identity>           # email, GitHub handle, or DID
reviewed_at: <YYYY-MM-DD>                  # date of approval
review_outcome: approved | revisions_requested | rejected

Semantics:

• reviewed_by, reviewed_at, review_outcome only appear once a human
  reviewer has acted. Their absence in a document with review_required: true
  signals "still pending review" — making the open backlog queryable.
• review_required: true is not toggled to false after approval.
  It remains as historical record of why the document needed review in
  the first place. The presence of review_outcome is the closure signal.
• review_outcome: revisions_requested allows iterative review cycles —
  the document can be updated and re-approved by adding a second approval
  block (see §3 below for multi-approval pattern).

2. New canonical body section

## Approval

**Approved**: <YYYY-MM-DD> by `<reviewer>`.

<Optional reviewer notes — observations, conditions, scope of approval>

Lives between ## Implementation and ## References in AIDEC, or in the
equivalent terminal position for other types.

3. Multi-approval support (optional, for future)

For documents that require multiple reviewers (e.g. ETH with both legal
and engineering sign-off, or MCARD with model owner + risk officer), the
fields become arrays:

review:
  - by: legal-counsel@example.com
    at: 2026-05-02
    outcome: approved
    notes: "Reviewed for GDPR compliance"
  - by: owner@example.com
    at: 2026-05-03
    outcome: approved
    notes: "Approved for deployment"

This is forward-looking and not required for v1 of the workflow. The
single-reviewer scalar fields cover the common case.

Adoption strategy

1. Templates: add the fields to TEMPLATE-AIDEC.md, TEMPLATE-ETH.md,
   TEMPLATE-MCARD.md, TEMPLATE-DPIA.md, TEMPLATE-INC.md,
   TEMPLATE-SEC.md, and the China-scope variants (TEMPLATE-PIPIA.md,
   TEMPLATE-CACFILE.md, TEMPLATE-TC260RA.md, TEMPLATE-AILABEL.md)
   as commented optional fields with brief explanation.

2. Documentation: extend DOCUMENTATION-POLICY.md §2 Optional Fields
   to list the new fields. Add a new section "§4.5 Recording Approval"
   immediately after "§4 When to Request Human Review" that explains
   the lifecycle.

3. CLI (optional follow-up): a devtrail approve <doc-id> --outcome=approved
   command that adds the frontmatter fields and the body section in one
   shot, with --reviewer and --notes flags. Reduces friction.

4. Validation (optional follow-up): extend devtrail validate (or the
   GitHub Actions workflow docs-validation.yml shipped with the framework)
   to warn when a document has review_required: true and is older than
   N days without review_outcome. Surfaces the queue of pending reviews.

Adjacent gap (related)

The same class of "convention mentioned but not operationalized" appears in
docs/plans/README.md §Cómo cerrar un plan §1 (downstream Sentinel), which
says "actualizar el Plan-doc post-merge si el AILOG documentó divergencias"
but provides no trigger. AIDEC-2026-05-02-001 in the Sentinel repo documents
that gap and proposes four alternatives (hook README pasivo, CI auto-checklist,
status intermedio, squash atomic). The two gaps are structurally identical:
the canon defines the signal (review_required, "Plan-doc drift") but
not the closure mechanism.

If this RFC is adopted, the same approach (optional frontmatter fields +
canonical body section) could close the Plan-doc cleanup gap symmetrically.

Background and source

This proposal emerged from real operation of DevTrail in the Sentinel repo
during a multi-PR session on 2026-05-02. Five PRs were merged in that
session, two of which (PR #25 and PR #26 in StrangeDaysTech/sentinel)
exposed the approval workflow gap end-to-end — first by creating an
AIDEC review_required: true and then by realizing there was no canonical
way to close the loop. The downstream repo applied the proposed pattern
locally as Opción B (extend frontmatter + body section) and references this
upstream RFC as the path to canonization.

Decision needed

Adopt or reject the proposed fields. If adopted, the framework version
that introduces them (suggested: format v4.5 or v5.0) should also include
migration guidance for existing repos that adopted similar patterns
locally before canonization.