docs(agents): persist independent review reports

.github/agents/complexity-auditor.agent.md

@@ -2,7 +2,7 @@
 name: Complexity Auditor
 description: Code quality auditor that checks cyclomatic and cognitive complexity of code changes. Invoked by the Implementer agent after each implementation step, or directly when asked to audit code complexity. Reports PASS, WARN, or FAIL for each changed function.
 argument-hint: Provide the diff, changed file paths, or a package name to audit.
-tools: [execute, read, search]
+tools: [execute, read, search, edit]
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -66,6 +66,24 @@ Flag functions longer than 50 lines. Long functions are a proxy for missing deco
 4. Check nesting depth and function length.
 5. Report findings using the output format below.
 
+### Persisting Independent Review Reports
+
+When the caller supplies an existing folder-style issue specification path whose primary file is
+`ISSUE.md` or `EPIC.md`, persist this independent review before returning the caller-facing
+verdict. In that specification directory, create `agent-review-reports.md` from
+`docs/templates/AGENT-REVIEW-REPORTS.md` when absent; otherwise append one complete entry after
+the final existing report entry. Read the entire existing report before editing. Preserve all
+earlier entries unchanged and in chronological order; a correction is a new timestamped entry that
+names the earlier conclusion.
+
+If persistence applies, record every audited changed function, the Clippy command and result when
+run, warnings or failures, the terminal audit result, and the required simplification or next-step
+action. Do not alter the reviewed implementation or invoke Committer.
+
+When no folder-style issue specification is supplied, including direct diff/package reviews and
+legacy standalone specifications, do not create, migrate, or modify an issue-local report. State in
+the caller-facing result: `Issue-local report skipped: no folder-style issue specification was supplied.`
+
 ## Output Format
 
 For each audited function, report one line:
@@ -85,6 +103,7 @@ End the report with one of:
 ## Constraints
 
 - Do not rewrite or suggest rewrites of code yourself — report only, let the Implementer decide.
+- Do not alter the reviewed implementation or invoke Committer.
 - Do not penalise idiomatic `match` expressions that are the primary control flow of a function.
 - Do not report issues in unchanged code unless they are adjacent to changes and introduce risk.
 - Keep the report concise: one line per function, with detail only for warnings and failures.

.github/agents/implementer.agent.md

@@ -149,6 +149,11 @@ When all steps are complete and tests are passing, invoke the **Task Reviewer**
 5. Request the Task Reviewer to mark accepted items as done in the issue spec.
 6. Wait for the Task Reviewer report.
 
+When a folder-style issue specification was supplied, Task Reviewer also persists its independent
+review in `agent-review-reports.md`. Include that report and any verified-checkbox changes in the
+pending change set handed to Committer. A failed review report may be committed as focused evidence
+when durable review history is needed; it does not authorize feature-code commits before remediation.
+
 If the Task Reviewer reports gaps, pending tasks, failing behaviour, or
 repository-convention problems, address those issues first and request review again.
 

.github/agents/pr-reviewer.agent.md

@@ -25,6 +25,29 @@ Your job is to review an already-open pull request and provide merge-focused fee
 4. Verify tests and docs expectations from the checklist.
 5. Return a clear merge-readiness verdict.
 
+### Persisting Independent Review Reports
+
+When the caller supplies an existing folder-style issue specification path whose primary file is
+`ISSUE.md` or `EPIC.md`, persist this independent review before returning the caller-facing
+verdict. In that specification directory, create `agent-review-reports.md` from
+`docs/templates/AGENT-REVIEW-REPORTS.md` when absent; otherwise append one complete entry after
+the final existing report entry. Read the entire existing report before editing. Preserve all
+earlier entries unchanged and in chronological order; a correction is a new timestamped entry that
+names the earlier conclusion.
+
+If persistence applies, record the PR number, base branch, reviewed files, CI/check context,
+severity-classified findings, checklist gaps, merge-readiness verdict, and follow-up owner/action.
+This record is independent of Copilot review-thread handling and must not replace the Copilot
+Suggestions Handler tracker.
+
+Do not invoke Committer or self-commit a report. When the report changes a branch or pull-request
+worktree, the caller requests Committer to include it in the coherent reviewed change set or create
+a focused documentation commit.
+
+When no folder-style issue specification is supplied, including direct diff/package reviews and
+legacy standalone specifications, do not create, migrate, or modify an issue-local report. State in
+the caller-facing result: `Issue-local report skipped: no folder-style issue specification was supplied.`
+
 ## Output Format
 
 1. Scope reviewed (PR number and key files)

.github/agents/task-reviewer.agent.md

@@ -53,6 +53,31 @@ pull request is opened.
    - `REVIEW PASSED` when all required criteria pass and no blocking issues remain.
    - `REVIEW FAILED` when any required criterion fails or blocking issues remain.
 
+### Persisting Independent Review Reports
+
+When the caller supplies an existing folder-style issue specification path whose primary file is
+`ISSUE.md` or `EPIC.md`, persist this independent review before returning the caller-facing
+verdict. In that specification directory, create `agent-review-reports.md` from
+`docs/templates/AGENT-REVIEW-REPORTS.md` when absent; otherwise append one complete entry after
+the final existing report entry. Read the entire existing report before editing. Preserve all
+earlier entries unchanged and in chronological order; a correction is a new timestamped entry that
+names the earlier conclusion.
+
+If persistence applies, update verified issue checkboxes first, then record the acceptance-criteria
+matrix, repository-convention findings, completion-review finding, issue-spec updates, overall
+result, and remediation for every `FAIL` or `PENDING` item. Do not commit the report. Do not ask
+Committer to proceed with an implementation commit when the result is `REVIEW FAILED`; the caller
+may request a focused documentation commit to preserve the failed report as durable evidence.
+
+Do not invoke Committer or self-commit a report. When the report changes a branch or pull-request
+worktree, the caller requests Committer to include it in the coherent reviewed change set or create
+a focused documentation commit. A persisted failed review may be committed as durable evidence;
+that commit does not authorize feature-code work before remediation.
+
+When no folder-style issue specification is supplied, including direct diff/package reviews and
+legacy standalone specifications, do not create, migrate, or modify an issue-local report. State in
+the caller-facing result: `Issue-local report skipped: no folder-style issue specification was supplied.`
+
 ## Output Format
 
 Respond in this order:

contrib/dev-tools/checks/tests/test-agent-review-report-contract.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# Structural contract tests for the independent agent-review report workflow.
+#
+# Run manually after modifying the template or reviewer profiles:
+#   bash contrib/dev-tools/checks/tests/test-agent-review-report-contract.sh
+# This test verifies tracked documentation/profile contracts, not autonomous agent behavior.
+
+set -euo pipefail
+
+PROJECT_ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../../../.." && pwd)
+TEMPLATE="${PROJECT_ROOT}/docs/templates/AGENT-REVIEW-REPORTS.md"
+COMPLEXITY_AUDITOR="${PROJECT_ROOT}/.github/agents/complexity-auditor.agent.md"
+TASK_REVIEWER="${PROJECT_ROOT}/.github/agents/task-reviewer.agent.md"
+PR_REVIEWER="${PROJECT_ROOT}/.github/agents/pr-reviewer.agent.md"
+COPILOT_HANDLER="${PROJECT_ROOT}/.github/agents/copilot-suggestions-handler.agent.md"
+
+require_text() {
+    local file_path=$1
+    local expected_text=$2
+
+    if ! grep -F -q -- "${expected_text}" "${file_path}"; then
+        printf 'Expected %s to contain: %s\n' "${file_path}" "${expected_text}" >&2
+        return 1
+    fi
+}
+
+require_wrapped_text() {
+    local file_path=$1
+    local expected_text=$2
+
+    if ! tr '\n' ' ' <"${file_path}" | grep -F -q -- "${expected_text}"; then
+        printf 'Expected %s to contain wrapped text: %s\n' "${file_path}" "${expected_text}" >&2
+        return 1
+    fi
+}
+
+require_absent_text() {
+    local file_path=$1
+    local unexpected_text=$2
+
+    if grep -F -q -- "${unexpected_text}" "${file_path}"; then
+        printf 'Expected %s not to contain: %s\n' "${file_path}" "${unexpected_text}" >&2
+        return 1
+    fi
+}
+
+require_yaml_frontmatter() {
+    local file_path=$1
+
+    if [[ $(sed -n '1p' "${file_path}") != '---' ]] || ! sed -n '2,/^---$/p' "${file_path}" | grep -Fx -q -- '---'; then
+        printf 'Expected %s to begin with closed YAML frontmatter.\n' "${file_path}" >&2
+        return 1
+    fi
+}
+
+require_tools_declaration_with_edit() {
+    local file_path=$1
+
+    if ! awk '/^tools:/ { declaration = declaration $0 } declaration && /edit/ { found = 1 } /^---$/ && NR > 1 { exit } END { exit !found }' "${file_path}"; then
+        printf 'Expected %s tools declaration to include edit.\n' "${file_path}" >&2
+        return 1
+    fi
+}
+
+it_should_define_the_reusable_report_template_contract() {
+    require_yaml_frontmatter "${TEMPLATE}"
+    require_text "${TEMPLATE}" 'Append one completed independent-review entry at a time.'
+    require_text "${TEMPLATE}" '### {YYYY-MM-DD HH:MM UTC} - {Reviewer}'
+    require_text "${TEMPLATE}" '- Invocation scope:'
+    require_text "${TEMPLATE}" '- Inputs:'
+    require_text "${TEMPLATE}" '- Evidence:'
+    require_text "${TEMPLATE}" '- Findings:'
+    require_text "${TEMPLATE}" '- Verdict:'
+    require_text "${TEMPLATE}" '- Follow-up actions:'
+}
+
+it_should_grant_each_independent_reviewer_edit_access() {
+    require_tools_declaration_with_edit "${COMPLEXITY_AUDITOR}"
+    require_tools_declaration_with_edit "${TASK_REVIEWER}"
+    require_tools_declaration_with_edit "${PR_REVIEWER}"
+}
+
+it_should_define_the_shared_create_append_or_skip_policy() {
+    local reviewer
+
+    for reviewer in "${COMPLEXITY_AUDITOR}" "${TASK_REVIEWER}" "${PR_REVIEWER}"; do
+        # shellcheck disable=SC2016 # Expected text includes literal Markdown code spans.
+        require_wrapped_text "${reviewer}" 'When the caller supplies an existing folder-style issue specification path whose primary file is `ISSUE.md` or `EPIC.md`, persist this independent review before returning the caller-facing verdict.'
+        # shellcheck disable=SC2016 # Expected text includes literal Markdown code spans.
+        require_wrapped_text "${reviewer}" 'create `agent-review-reports.md` from `docs/templates/AGENT-REVIEW-REPORTS.md` when absent; otherwise append one complete entry after the final existing report entry.'
+        require_wrapped_text "${reviewer}" 'Issue-local report skipped: no folder-style issue specification was supplied.'
+    done
+}
+
+it_should_keep_commit_authority_with_the_caller_and_committer() {
+    local reviewer
+
+    require_absent_text "${COMPLEXITY_AUDITOR}" 'git commit'
+    require_text "${COMPLEXITY_AUDITOR}" 'Do not alter the reviewed implementation or invoke Committer.'
+
+    for reviewer in "${TASK_REVIEWER}" "${PR_REVIEWER}"; do
+        require_wrapped_text "${reviewer}" 'Do not invoke Committer or self-commit a report. When the report changes a branch or pull-request worktree, the caller requests Committer to include it in the coherent reviewed change set or create a focused documentation commit.'
+    done
+}
+
+it_should_keep_copilot_tracking_separate_from_independent_reviews() {
+    require_absent_text "${COPILOT_HANDLER}" 'agent-review-reports.md'
+    require_text "${COPILOT_HANDLER}" 'docs/copilot-pr-reviews/pr-<PR_NUMBER>-copilot-suggestions.md'
+}
+
+it_should_define_the_reusable_report_template_contract
+it_should_grant_each_independent_reviewer_edit_access
+it_should_define_the_shared_create_append_or_skip_policy
+it_should_keep_commit_authority_with_the_caller_and_committer
+it_should_keep_copilot_tracking_separate_from_independent_reviews
+
+printf 'All agent review report contract tests passed.\n'