From 58decdde39f10626a5e22e3dffc69e94a50c9b78 Mon Sep 17 00:00:00 2001 From: calvin-archastro Date: Wed, 23 Sep 2026 12:53:24 -0700 Subject: [PATCH 1/2] docs(archdev-skill): mitigate risks found while computing risk, then recompute A sealed risk assessment and PR hunk risk annotations were computed once and posted as labels. Now both are a loop: fix the medium/high risks in the subject itself (code, tests, guards, plan), re-author and finalize (or annotate the new head), and post what remains as named residual risk. The grade must follow the work, never an edited assessment; one mitigation round; scope-changing fixes go to the human. Co-Authored-By: Claude Opus 5.5 (1M context) --- archdev/SKILL.md | 8 +++++--- archdev/references/monitor.md | 26 +++++++++++++++++++++----- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index a215b33..ca58862 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -89,6 +89,8 @@ 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. No daemon, no log tailing: the model is the sensor -until an event proves reliable enough to promote into the stop -hook. +the agent only logs. Computing risk (a sealed assessment or hunk `risk` +annotations) is a loop, not a label: mitigate the risks you find, then +recompute 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. diff --git a/archdev/references/monitor.md b/archdev/references/monitor.md index b899b0f..b5fd341 100644 --- a/archdev/references/monitor.md +++ b/archdev/references/monitor.md @@ -163,7 +163,7 @@ Rules: - Free text: `"$archdev" log post ""` — posts to the org room as event `agent.message`. - Structured: plan/task/pr events carry a sealed risk assessment; - commit/agent events do not. Four steps: + commit/agent events do not. Five steps: 1. `"$archdev" extract brief risk. --out ./brief/` — rubric for this session (instructions, input/output schemas, worked example). Fetch once per definition; reuse via the digest in `brief.json`. @@ -179,7 +179,17 @@ Rules: 3. `"$archdev" extract finalize risk. ./judgment.json --out ./sealed/` — validates the schemas, derives the combined grade, prints the digest. Fix what the named stage reports. - 4. `"$archdev" log post --event --payload-file --assessment + 4. Mitigate, then recompute. For each medium or high risk driver the + assessment names, reduce the risk in the subject itself: fix the + code, add the missing test or guard, split the unverifiable step, + tighten the plan. Then re-author `{input, assessment}` from the + changed subject and finalize again. Never lower a grade by editing + the assessment alone; the grade must follow the work. Run one + mitigation round, then post what remains. A mitigation that would + change scope or needs a decision is not yours to make: ask the human + and record it as residual risk. Name the residual risks and what you + mitigated in `--message`. + 5. `"$archdev" log post --event --payload-file --assessment ./sealed/result.json --message ""`. Every structured post must read well to a human in the room, whatever its schema. The CLI renders the payload as text (`▶ Task tsk_1 @@ -204,14 +214,20 @@ Rules: 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. `"$archdev" extract run pr.review-annotations --runner + 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. Keep annotating the + risks you could not mitigate, stated plainly. One round, then + continue; scope-changing mitigations go to the human. + 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. - 4. Confirm with `"$archdev" extract show pr.review-annotations + 5. Confirm with `"$archdev" extract show pr.review-annotations --json`, then log the `pr.*` event. - If step 3 fails (signed out, no GitHub origin, validation error), fix + 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). From ba4a9c24bb74077ada1c0af8dc3a15e0d8843a0b Mon Sep 17 00:00:00 2001 From: calvin-archastro Date: Wed, 23 Sep 2026 12:54:46 -0700 Subject: [PATCH 2/2] docs(archdev-skill): cap the risk mitigation loop at two rounds and never expand scope A fix that would expand scope is not made; the risk is recorded as residual and the agent moves forward. Co-Authored-By: Claude Opus 5.5 (1M context) --- archdev/SKILL.md | 8 ++++---- archdev/references/monitor.md | 17 +++++++++-------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index ca58862..075c961 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -90,7 +90,7 @@ outside `archdev publish` gets its hunk review annotations stored with 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, then -recompute 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. +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. diff --git a/archdev/references/monitor.md b/archdev/references/monitor.md index b5fd341..715f57f 100644 --- a/archdev/references/monitor.md +++ b/archdev/references/monitor.md @@ -184,11 +184,12 @@ Rules: code, add the missing test or guard, split the unverifiable step, tighten the plan. Then re-author `{input, assessment}` from the changed subject and finalize again. Never lower a grade by editing - the assessment alone; the grade must follow the work. Run one - mitigation round, then post what remains. A mitigation that would - change scope or needs a decision is not yours to make: ask the human - and record it as residual risk. Name the residual risks and what you - mitigated in `--message`. + the assessment alone; the grade must follow the work. Run at most + two mitigate-and-recompute rounds, then post what remains. Only + mitigate within the work's existing scope: if a fix would expand + scope (new features, other components, unrelated refactors), do not + make it; record it as residual risk and move forward. Name the + residual risks and what you mitigated in `--message`. 5. `"$archdev" log post --event --payload-file --assessment ./sealed/result.json --message ""`. Every structured post must read well to a human in the room, whatever @@ -217,9 +218,9 @@ Rules: 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. Keep annotating the - risks you could not mitigate, stated plainly. One round, then - continue; scope-changing mitigations go to the human. + 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