What happened
In PR #1806, a structural change to how trusted task rules are sourced (data.trusted_task_rules path removed, rule_data becomes the sole source) left THREAT_MODEL.md stale in 9+ locations. The review agent's docs-review sub-agent detected the staleness and flagged it at high severity, but neither the PR author nor the human reviewer updated the document before merge.
The current AGENTS.md has no guidance about maintaining THREAT_MODEL.md when trust-boundary code changes. The review agent's docs-review skill found the issue post-hoc, but there is no preventive guidance for PR authors to check THREAT_MODEL.md when modifying security-critical data paths in policy/lib/tekton/trusted.rego or similar files.
What could go better
PR authors modifying trust-boundary code (trusted task rules, data input paths, merge logic) should know that THREAT_MODEL.md describes these architectures in detail and must be updated in the same PR. The review agent caught it, but prevention is more effective than detection — especially since agent CHANGES_REQUESTED can be overridden by human approvals.
This is a medium-confidence proposal. The pattern may not recur frequently (trust-boundary changes are relatively rare), but when it does recur, the impact is high — stale security documentation creates incorrect mental models for security reviewers. The existing issue #1801 covers cross-file code consistency but does not address code-to-documentation synchronization for security documents.
Proposed change
Add a subsection to AGENTS.md under the development workflow or review guidance area:
## Security documentation maintenance
When a PR modifies trust-boundary code — specifically files in `policy/lib/tekton/`
that handle trusted task rules, data input paths, or merge/validation logic —
check whether `THREAT_MODEL.md` describes the affected architecture. If it does,
update the relevant sections in the same PR. Key sections to check:
- Section 3.3 (trusted task data flow and merge architecture)
- Threat entries DP-2 and LE-4 (injection and precedence threats)
- The security-critical rule data keys table
- Open questions and recommendations referencing the changed components
This ensures both human PR authors and the code agent include documentation updates when modifying security-critical architecture.
Validation criteria
On the next PR that modifies trust-boundary code in policy/lib/tekton/trusted.rego or related files, the PR author (human or agent) should include THREAT_MODEL.md updates in the same PR if the document references the changed architecture. The review agent should cite this AGENTS.md guidance when flagging stale THREAT_MODEL.md sections, increasing the likelihood that findings are addressed before merge.
Generated by retro agent from #1806
What happened
In PR #1806, a structural change to how trusted task rules are sourced (
data.trusted_task_rulespath removed,rule_databecomes the sole source) left THREAT_MODEL.md stale in 9+ locations. The review agent's docs-review sub-agent detected the staleness and flagged it at high severity, but neither the PR author nor the human reviewer updated the document before merge.The current AGENTS.md has no guidance about maintaining THREAT_MODEL.md when trust-boundary code changes. The review agent's docs-review skill found the issue post-hoc, but there is no preventive guidance for PR authors to check THREAT_MODEL.md when modifying security-critical data paths in
policy/lib/tekton/trusted.regoor similar files.What could go better
PR authors modifying trust-boundary code (trusted task rules, data input paths, merge logic) should know that THREAT_MODEL.md describes these architectures in detail and must be updated in the same PR. The review agent caught it, but prevention is more effective than detection — especially since agent CHANGES_REQUESTED can be overridden by human approvals.
This is a medium-confidence proposal. The pattern may not recur frequently (trust-boundary changes are relatively rare), but when it does recur, the impact is high — stale security documentation creates incorrect mental models for security reviewers. The existing issue #1801 covers cross-file code consistency but does not address code-to-documentation synchronization for security documents.
Proposed change
Add a subsection to AGENTS.md under the development workflow or review guidance area:
This ensures both human PR authors and the code agent include documentation updates when modifying security-critical architecture.
Validation criteria
On the next PR that modifies trust-boundary code in
policy/lib/tekton/trusted.regoor related files, the PR author (human or agent) should include THREAT_MODEL.md updates in the same PR if the document references the changed architecture. The review agent should cite this AGENTS.md guidance when flagging stale THREAT_MODEL.md sections, increasing the likelihood that findings are addressed before merge.Generated by retro agent from #1806