From e912fa3d2efa25f2a65b8b26fad6498e300b0591 Mon Sep 17 00:00:00 2001 From: Ahmet Taspinar Date: Fri, 2 Oct 2026 20:21:06 +0200 Subject: [PATCH] Publish review and triage reports on the Issue instead of committing them .agents/reviews/ and .agents/triage/ are ignored by Git. After an approved triage, triage-review.sh publishes the review and triage reports, rendered from the validated JSON, as a comment on the source Issue, split into numbered parts rather than shortened when they exceed one comment. A failed publication keeps the stored triage and prints the commands to retry. The Definition of Done and the PR template refer to the published triage. Closes #40 Co-Authored-By: Claude Opus 5.5 --- .agents/triage/.gitkeep | 0 .github/PULL_REQUEST_TEMPLATE.md | 1 + .gitignore | 6 +++ AGENTS.md | 3 +- CONTRIBUTING.md | 6 +-- docs/agentic-workflow.md | 7 +++- docs/development.md | 12 +++++- scripts/triage-review.sh | 68 ++++++++++++++++++++++++++++++++ tests/triage-review-test.sh | 62 ++++++++++++++++++++++++++++- 9 files changed, 157 insertions(+), 8 deletions(-) create mode 100644 .agents/triage/.gitkeep diff --git a/.agents/triage/.gitkeep b/.agents/triage/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fcd2bce..714b37f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,6 +12,7 @@ Closes # - [ ] `./scripts/verify.sh` passed - [ ] Tests added/updated where appropriate - [ ] Independent review completed when required +- [ ] Approved triage published on the feature Issue (link the comment): - [ ] Architecture/docs/ADR updated when required ## Agent involvement diff --git a/.gitignore b/.gitignore index cdb3093..a184f6e 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,9 @@ venv/ *.key service-account*.json credentials*.json +# Review and triage results are working files; their reports are published +# on the feature Issue instead of being committed. +.agents/reviews/* +!.agents/reviews/.gitkeep +.agents/triage/* +!.agents/triage/.gitkeep diff --git a/AGENTS.md b/AGENTS.md index e376301..b98d2f8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,7 +29,8 @@ If a material conflict remains, stop and report it. - Verification evidence is recorded in the active plan or PR. - Required independent review is complete and no Critical or Major findings remain unresolved. -- Required review findings have an approved triage artifact. +- Required review findings have an approved triage, published on the feature + Issue by `triage-review.sh`. - Deferred findings have a linked follow-up Issue; accepted findings have an explicit rationale. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddc70c6..fd3577d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,9 +7,9 @@ All non-trivial changes should originate from a GitHub Issue and use a feature b Everything committed to the template repository is inherited by every project created from it. When developing the template: -- Do not commit the plans, reviews, triage artifacts, or handoffs of that - work under `.agents/`. Keep the design in the GitHub Issue and the review - outcome in the Pull Request. +- Do not commit the plans or handoffs of that work under `.agents/`. Keep the + design in the GitHub Issue. Review and triage results are ignored by Git and + published on the Issue, as in any project. - Record design decisions about the template in the Issue and in the workflow documentation under `docs/`. `docs/decisions/` is reserved for the ADRs of projects that use the template. diff --git a/docs/agentic-workflow.md b/docs/agentic-workflow.md index 6a9aa55..9331b1c 100644 --- a/docs/agentic-workflow.md +++ b/docs/agentic-workflow.md @@ -31,9 +31,12 @@ See `docs/development.md` for the concrete commands. - `.agents/plans/`: active implementation state for complex work. - `.agents/handoffs/`: compressed continuation context. - `.agents/reviews/`: independent-review results as validated JSON, each with a - generated Markdown report. + generated Markdown report. Working files, ignored by Git. - `.agents/triage/`: approved finding decisions and deferred-Issue traceability - as validated JSON, each with a generated Markdown report. + as validated JSON, each with a generated Markdown report. Working files, + ignored by Git. +- Feature Issue comments: the published review and triage reports of each + round. - `.agents/schemas/`: the schemas of those results. - `.agents/lessons/`: recurring failure lessons awaiting/promoting durable rules. - Git history: what actually changed. diff --git a/docs/development.md b/docs/development.md index a74a206..d1ae4ea 100644 --- a/docs/development.md +++ b/docs/development.md @@ -264,7 +264,13 @@ write a persistent, uniquely named artifact such as: ``` That artifact maps the source review findings to their decisions and any -created Issue numbers. Declining the proposal creates neither an artifact nor +created Issue numbers. After storing it, the script publishes the review and +triage reports as one comment on the source Issue, so the outcome is visible in +the Issue and, through `Closes #12`, from the pull request. The reports are +rendered from the JSON. When they exceed the size of one GitHub comment, they +are published in numbered parts rather than shortened. A failed publication +keeps the stored triage and prints the command to retry each unpublished +part. Declining the proposal creates neither an artifact nor Issues. The source review remains unchanged. The artifact is stored only after every follow-up Issue exists; if creating one fails, nothing is stored and a new triage reuses the Issues created so far, which it finds by their trace @@ -316,6 +322,10 @@ each triage is stored as two files with the same name: - `.md` is a report generated from the JSON for reading. It is never parsed; editing it has no effect. +Both are working files for the scripts during a feature and are ignored by +Git, so `git add .` does not commit them. The record that stays is the comment +on the Issue and the follow-up Issues, each of which names its source finding. + The agent's result must match a schema in `.agents/schemas/` (`review.schema.json`, `triage.schema.json`). The schema is passed to the provider CLI and the script checks the result again with `jq`, including rules diff --git a/scripts/triage-review.sh b/scripts/triage-review.sh index 109f988..38c2b4f 100755 --- a/scripts/triage-review.sh +++ b/scripts/triage-review.sh @@ -223,6 +223,7 @@ deferred_count="$(jq '[.[] | select(.decision == "DEFER")] | length' "$proposal_ if [[ "$deferred_count" -gt 0 ]]; then echo "Approval will create $deferred_count follow-up GitHub issue(s)." fi +echo "Approval will publish the review and triage reports as a comment on Issue #$source_issue." printf "Proceed with this triage? [y/N] " approval="" @@ -361,3 +362,70 @@ echo " $artifact_relative.md (generated report)" echo jq '.decisions' "$artifact.json" >"$tmp_work/final.json" render_proposal "$tmp_work/final.json" + +# The reports are published on the Issue instead of being committed, rendered +# from the validated JSON. A comment holds at most 65,536 characters: when both +# reports do not fit in one comment, they are published in numbered parts, so +# the record is never shortened. +round="$(jq -r '.round' "$review_path")" +comment_base="$artifact-comment" +rm -f "$comment_base"*.md +heading="## Independent review and triage — round $round" +{ + echo "Reviewer verdict: $(jq -r '.verdict | gsub("_"; " ")' "$review_path")" + echo + echo "
" + echo "Review report" + echo + review_render_markdown "$review_path" "$review_stem.json" | sed '1{/^