From 24e8617677837dc36754bb8cdc5e6acd6fec1575 Mon Sep 17 00:00:00 2001 From: Rafael Brandao Date: Wed, 23 Sep 2026 12:59:38 -0700 Subject: [PATCH 1/2] docs(archdev-skill): store PR review annotations after every push, and verify before stopping ArchDev shows a PR's AI summary, Start here list, and per-hunk risk labels only for a head with a github_pr_review_annotations row. Rows are keyed by the exact head SHA, so every push leaves the new head without one until the agent stores it. Sessions annotate most heads and skip the last push before stopping, which is the head reviewers open. The skill now owns this step (the firstlanding AGENTS.md directive is removed): SKILL.md beats 2 and 3 name it, monitor.md gains a 'PR review annotations' section with the moments, the four commands, and a stopping-point check with 'extract show pr.review-annotations --json' or 'inspect metadata --sha '. --- archdev/SKILL.md | 35 +++++++---- archdev/references/monitor.md | 108 ++++++++++++++++++++++++---------- 2 files changed, 100 insertions(+), 43 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index 29eeda2..6d8d051 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -77,21 +77,32 @@ Read [monitor.md](references/monitor.md). Three beats, one command `log post --kind` — `start` once scope is clear, `lesson` on a reusable root cause or fix, `abandoned` for a failed approach, `done` (with the PR URL) or an `@name` `handoff` at the end. Re-read the room - before committing or opening a PR. + before committing or opening a PR. After `gh pr create` and after + every push that moves a PR head, store that head's review + annotations before doing anything else (see "PR review annotations" + in monitor.md). 3. **Every stopping point:** self-check against the mapped taxonomy and report hits — free text (`agent.message`) or schema-validated payloads (`log post --event`), with `--kind` on the same call when the - event is also a lifecycle moment. + event is also a lifecycle moment. Outside Factory sessions, for every + PR you pushed to this session, confirm its current head has + annotations (`extract show pr.review-annotations --json`) and + store them if it does not. Every post carries human-readable text: structured posts add `--message ""` as the headline over the CLI-rendered -payload summary. A PR created (or updated to a new head) -outside `archdev publish` gets its hunk review annotations stored with -`extract run pr.review-annotations` before the `pr.*` post — except in a -Factory or daemon session (`ARCHDEV_FACTORY_AGENT_ROLE`, `ARCHDEV_JOB_ID`, -or `ARCHDEV_STEP_ID` set), where the host's publish step writes them and -the agent only logs. Computing risk (a sealed assessment or hunk `risk` -annotations) is a loop, not a label: mitigate the risks you find within -scope, then recompute, at most twice, before you post (monitor.md, -Report). No daemon, no log tailing: the model is the sensor until an -event proves reliable enough to promote into the stop hook. +payload summary. + +ArchDev shows a PR's AI summary, Start here list, and per-hunk risk and +theme labels only for a head that has a `github_pr_review_annotations` +row. Rows are keyed by the exact head SHA, so every push leaves the +Overview without a summary or labels until a row for the new head +exists. `archdev publish` writes one; `gh pr create` and `git push` do +not. The exception is a Factory or daemon session (`ARCHDEV_FACTORY_AGENT_ROLE`, +`ARCHDEV_JOB_ID`, or `ARCHDEV_STEP_ID` set), where the host's publish +step writes the row and the agent only logs. Computing risk (a sealed +assessment or hunk `risk` annotations) is a loop, not a label: mitigate +the risks you find within scope, then recompute, at most twice, before +you post (monitor.md, Report and PR review annotations). No daemon, no +log tailing: the model is the sensor until an event proves reliable +enough to promote into the stop hook. diff --git a/archdev/references/monitor.md b/archdev/references/monitor.md index 715f57f..48aa3be 100644 --- a/archdev/references/monitor.md +++ b/archdev/references/monitor.md @@ -9,8 +9,12 @@ tailing. The session runs in three beats: the moment they occur — `start` once scope is clear, `lesson` right away, `abandoned` when an approach dies. Do not hold them for a stopping point. Re-read the room before committing or opening a PR. + After `gh pr create` and after every push that moves a PR head, + store that head's review annotations first (see PR review + annotations). 3. **Every stopping point:** self-check against the taxonomy, report - events, and post any lifecycle moment you missed. + events, post any lifecycle moment you missed, and confirm every PR + head you pushed has its annotations. The start hook (`repo hook start`) injects this flow as the self-check block generated from the repo's own `activity` taxonomy: room reads, @@ -88,8 +92,14 @@ out), ask: 3. Was a task created, started, updated, or closed? (task `detection`: …) 4. Was a commit created or pushed? (commit `detection`: …) 5. Was a PR created, updated, or closed? (pr `detection`: …) → on - created, or updated with a new head, store its hunk metadata first - (see Report). + created, or updated with a new head, store its review annotations + first (see PR review annotations; not in Factory sessions). Then, for + every PR you pushed to this session, run `"$archdev" extract show + pr.review-annotations --json` from that PR's checkout at its + head: an `ExtractionNotFoundError` means the current head has no + row, so store it now, before any `done` or `handoff` post and before + you stop. Any other error means the checkout is not at the PR head, + not that the row is missing. 6. Did substantial work start, finish, fail, or teach something reusable? → it should already be posted; if not, post it now with `--kind` (see below). When the same moment is also an event, put both on one @@ -109,7 +119,7 @@ works on its own or on top of any `--event`. | `start` | scope of substantial work is understood (not on every session) | what and why in one sentence; `-r` task ID or plan path | | `lesson` | right away, on a reusable root cause, failure, or fix | symptom, cause, fix; the exact command, error, or file | | `abandoned` | an approach failed and should not be repeated | what was tried, why it failed | -| `done` | a meaningful outcome is finished | intent, externally visible result, useful findings, actual verification; `-r` PR URL | +| `done` | a meaningful outcome is finished, and the PR's current head already has its review annotations | intent, externally visible result, useful findings, actual verification; `-r` PR URL | | `handoff` | someone else owns the next action | headline starts `@firstname`; current state | | `question` | a decision only a teammate can make | headline starts `@firstname`; evidence and options | @@ -204,33 +214,69 @@ Rules: background worker delivers it with the same key — do not re-send. Attachments cap at 64 KB encoded: cite less, or move bodies to `missingInputs`, when finalize succeeds but log reports oversize. -- PR hunk metadata: on `pr.created`, and on `pr.updated` when the head - moved, store review annotations for the PR's current head *before* - logging the event, so ArchDev opens the PR with its risk, theme, and - note labels per hunk. `archdev publish` already does this; a PR opened - any other way (`gh pr create`, the web UI) has none until you do: - 1. `"$archdev" extract context pr.review-annotations --json` — - copy identity from `key`; read `authoring` for the `auto_reviewed` - paths a focus entry may not name. - 2. Author the value from the patches: sparse `risk` / `semantic_group` - / `note` ranges covering every changed path, plus an optional - `summary` (`intent`, `overall_risk`, up to five `focus` ranges). - 3. Mitigate, then recompute. For each medium or high `risk` range that - is a real defect or gap, fix it in the branch with a test that would - have caught it, and push. The push is a new head, so go back to - step 1 and author annotations for that head. At most two rounds. - Fix only within the PR's scope; a risk whose fix would expand scope - stays annotated, stated plainly, and you move forward. - 4. `"$archdev" extract run pr.review-annotations --runner - file: --json` — the default sink writes the - `github_pr_review_annotations` object for that head. `cached` means - that head already has annotations; do not `--force` over rows you did - not write. - 5. Confirm with `"$archdev" extract show pr.review-annotations - --json`, then log the `pr.*` event. - If step 4 fails (signed out, no GitHub origin, validation error), fix - what it names or say so in the event's `--message`; never skip - silently. In a Factory session, skip this whole bullet (see below). +- PR events: on `pr.created`, and on `pr.updated` when the head moved, + store the head's review annotations *before* logging the event (see + PR review annotations, next). + +## PR review annotations + +ArchDev opens a pull request on its Overview with the AI summary, the +Start here list, and per-hunk risk and theme labels only when the PR's +current head has a `github_pr_review_annotations` row. Rows are keyed by +the exact head SHA and never carry over: a push, a force-push, or a +rebase leaves the new head with no row, and the Overview shows no +summary or labels until one is stored. `archdev publish` writes the row +for the head it pushes; `gh pr create` and a plain `git push` do not. + +Store the row at these moments: + +- right after `gh pr create`; +- right after every push that moves an open PR's head, including a + format fixup, a review-fix commit, and the last push before you stop. + A session that annotated four heads and skipped the fifth leaves the + PR without labels for its reviewers, because the fifth is the head + they open. + +Skip this section only in a Factory or daemon session (see below). + +From the checkout at the PR's head (`HEAD` must equal the PR head, on +its branch): + +1. `"$archdev" extract context pr.review-annotations --json` — + copy identity from `key`; read `authoring` for the `auto_reviewed` + paths a focus entry may not name. +2. Author the value from the patches: sparse `risk` / `semantic_group` + / `note` ranges covering every changed path, plus an optional + `summary` (`intent`, `overall_risk`, up to five `focus` ranges with a + `why`). Every focus range must overlap a medium-or-higher risk + annotation on the same path and side. +3. Mitigate, then recompute. For each medium or high `risk` range that + is a real defect or gap, fix it in the branch with a test that would + have caught it, and push. The push is a new head, so go back to + step 1 and author annotations for that head. At most two rounds. + Fix only within the PR's scope; a risk whose fix would expand scope + stays annotated, stated plainly, and you move forward. +4. `"$archdev" extract run pr.review-annotations --runner + file: --json` — the default sink writes the + `github_pr_review_annotations` object for that head. `status: + "cached"` means that head already has annotations; do not `--force` + over rows you did not write. A validation error names the failing + entry: fix the file and rerun. +5. Confirm with `"$archdev" extract show pr.review-annotations + --json`: it prints the stored row; `ExtractionNotFoundError` means + nothing is stored for this head; any other error means the checkout + is not at the PR head. Then log the `pr.*` event. + +Verify before you stop: at every stopping point, and before any `done` +or `handoff` post, run step 5 for each PR you pushed to this session. +From any checkout, `"$archdev" inspect metadata --sha "$(git +rev-parse HEAD)"` reads the same row and reports "No review annotations +are published" when it is missing. + +If step 4 fails (signed out: `"$archdev" auth status` shows no session; +no GitHub origin; a validation error), fix what it names or say so in +the event's `--message` and in your reply to the user; never skip +silently. ## Factory sessions From 1b8568b709e38e309e3ab25129c899529f567520 Mon Sep 17 00:00:00 2001 From: Rafael Brandao Date: Wed, 23 Sep 2026 14:40:12 -0700 Subject: [PATCH 2/2] docs(archdev-skill): state the annotation mechanism, not the Overview widgets The skill named the AI summary, the Start here list, and the per-hunk labels as what a missing row costs. That inventory drifts with the UI (the Overview no longer shows a summary section as of today) and is not what an agent needs to know. Say the mechanism instead: ArchDev reads a PR's review annotations from the row for its exact head SHA, nothing carries over, and the PR opens unannotated until a row exists. --- archdev/SKILL.md | 11 +++++------ archdev/references/monitor.md | 17 ++++++++--------- 2 files changed, 13 insertions(+), 15 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index 6d8d051..cba816f 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -93,12 +93,11 @@ Every post carries human-readable text: structured posts add `--message ""` as the headline over the CLI-rendered payload summary. -ArchDev shows a PR's AI summary, Start here list, and per-hunk risk and -theme labels only for a head that has a `github_pr_review_annotations` -row. Rows are keyed by the exact head SHA, so every push leaves the -Overview without a summary or labels until a row for the new head -exists. `archdev publish` writes one; `gh pr create` and `git push` do -not. The exception is a Factory or daemon session (`ARCHDEV_FACTORY_AGENT_ROLE`, +ArchDev reads a PR's review annotations from the +`github_pr_review_annotations` row for its exact head SHA. Nothing +carries over between heads, so every push leaves the PR unannotated +until a row for the new head exists. `archdev publish` writes one; +`gh pr create` and `git push` do not. The exception is a Factory or daemon session (`ARCHDEV_FACTORY_AGENT_ROLE`, `ARCHDEV_JOB_ID`, or `ARCHDEV_STEP_ID` set), where the host's publish step writes the row and the agent only logs. Computing risk (a sealed assessment or hunk `risk` annotations) is a loop, not a label: mitigate diff --git a/archdev/references/monitor.md b/archdev/references/monitor.md index 48aa3be..6e7300f 100644 --- a/archdev/references/monitor.md +++ b/archdev/references/monitor.md @@ -220,13 +220,12 @@ Rules: ## PR review annotations -ArchDev opens a pull request on its Overview with the AI summary, the -Start here list, and per-hunk risk and theme labels only when the PR's -current head has a `github_pr_review_annotations` row. Rows are keyed by -the exact head SHA and never carry over: a push, a force-push, or a -rebase leaves the new head with no row, and the Overview shows no -summary or labels until one is stored. `archdev publish` writes the row -for the head it pushes; `gh pr create` and a plain `git push` do not. +ArchDev reads a pull request's review annotations from the +`github_pr_review_annotations` row for its exact head SHA. Rows never +carry over: a push, a force-push, or a rebase leaves the new head with +no row, and the PR opens unannotated until one is stored. `archdev +publish` writes the row for the head it pushes; `gh pr create` and a +plain `git push` do not. Store the row at these moments: @@ -234,8 +233,8 @@ Store the row at these moments: - right after every push that moves an open PR's head, including a format fixup, a review-fix commit, and the last push before you stop. A session that annotated four heads and skipped the fifth leaves the - PR without labels for its reviewers, because the fifth is the head - they open. + PR unannotated for its reviewers, because the fifth is the head they + open. Skip this section only in a Factory or daemon session (see below).