From f74acaef7ac91b2813da264841b6fba2d63b7eae Mon Sep 17 00:00:00 2001 From: joseph Date: Wed, 30 Sep 2026 10:08:24 +0000 Subject: [PATCH 1/2] 0.2.1: wait for the searcher, re-review on change, a home for the report Fixes from an execution test of 0.2.0 on a real defect, run headless: - The runbook let the independent searcher run in the background whilst the rule was written, and nothing said to wait for it, so the original was fixed before the search returned, and a headless run emitted its final result early. Step 2 now forbids any fix until the findings are in hand at step 5, and forbids ending the turn whilst it runs. - The conformance review ran once; a finding that changed the rule left later commits unreviewed. The reviewer is now re-dispatched whenever the defence's commits change. - A project with no records place and no pull request gave the report nowhere to go, and the version statement was lost with it. The report now goes into the final message in that case, and the final message always opens with the specification version and source. - The reviewer's worktree isolation left a worktree-agent branch in the project under review. It now reproduces in a detached worktree of its own and removes it, creating no branches. Co-Authored-By: Claude Opus 5.5 --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- agents/conformance-reviewer.md | 8 +++++--- skills/dbf/SKILL.md | 15 +++++++++++---- 4 files changed, 18 insertions(+), 9 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cfced85..45f391d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ "name": "defence-before-fix", "displayName": "Defence Before Fix", "description": "Runs the Defence Before Fix (DBF) method when a defect is found. Invoke with /dbf.", - "version": "0.2.0", + "version": "0.2.1", "homepage": "https://defence-before-fix.github.io/", "source": "./", "keywords": ["defence-before-fix", "dbf", "static-analysis", "quality", "methodology"] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bbbb57e..587b265 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "defence-before-fix", "displayName": "Defence Before Fix", - "version": "0.2.0", + "version": "0.2.1", "description": "Runs the Defence Before Fix (DBF) method when a defect is found: attribute it to a class, write and prove a detector rule, sweep and fix every instance, then fix the defect. Invoke with /dbf.", "author": { "name": "Joseph Edmonds", diff --git a/agents/conformance-reviewer.md b/agents/conformance-reviewer.md index d00c7de..f171a21 100644 --- a/agents/conformance-reviewer.md +++ b/agents/conformance-reviewer.md @@ -3,15 +3,17 @@ name: conformance-reviewer description: Reviews a finished Defence Before Fix remediation against the method specification before its report issues, by reproducing the defence red and green through the project's own entry point rather than trusting the report. Dispatched by the dbf skill; changes nothing in the branch under review. tools: Read, Grep, Glob, Bash model: sonnet -isolation: worktree --- You are the conformance reviewer for a Defence Before Fix remediation. The coordinator gives you the commit that introduced the defence, the final commit, the project's entry point for its checks, the draft report, the path to the method specification, and the paths of the toolchain contract and the language guides the remediation used. You check the work -against the specification and return findings. You change nothing in the branch under review; -work in the worktree you were given. +against the specification and return findings. You change nothing in the project under review. +Do the reproduction runs in a detached worktree of your own outside the project directory +(`git worktree add --detach `), switch commits in it with +`git checkout --detach`, and remove it with `git worktree remove` when you finish. Create no +branches, commits or tags. Read the specification's section 3 (the method), section 4 (authority), section 7 (review) and section 8 (operating under AI-assisted development) before you look at the work, and cite diff --git a/skills/dbf/SKILL.md b/skills/dbf/SKILL.md index fb30732..58a8387 100644 --- a/skills/dbf/SKILL.md +++ b/skills/dbf/SKILL.md @@ -97,14 +97,16 @@ The project prompt gives the order and the rules. In outline: exist unchanged had the rule never been written. Dispatch `defence-before-fix:independent-searcher` with the class and hazard sentence, the paths of the detector's rule and configuration directories to keep out of, and a file to write to. - Let it run whilst you write the rule. + Let it run whilst you write and prove the rule, but fix nothing, the original included, + until its findings are in hand at step 5. If it runs in the background, wait for it to + finish before step 5, and do not end your turn or give a final answer whilst it is running. 3. **Write the rule** in the project's detector, through the toolchain's single-rule harness where one exists. Draw it wider than the one instance and no wider than the hazard. Name the next wider rule you considered and why you did not build it; the record requires it. 4. **Prove the rule fires** on the originating instance or on a fixture you keep as its test, and commit the defence red, as a commit of its own, before any instance is fixed. The contract's proof section and the guide's harness say how, for the host you chose. -5. **Reconcile with the search.** Where the searcher's findings exceed the rule's, widen the +5. **Reconcile with the search**, once the searcher has returned. Where the searcher's findings exceed the rule's, widen the rule; the search wins. Record what each of its two techniques found that the other could not have checked. 6. **Sweep and count.** Run the rule everywhere the pattern can occur: first-party source in @@ -132,11 +134,16 @@ Before the report issues, dispatch `defence-before-fix:conformance-reviewer` wit that introduced the defence, the final commit, the project's entry point, the draft report, the path to `SPEC.md`, and the paths of the toolchain contract and the guides you used. It reproduces the red and green runs rather than trusting the report, checks the work against -sections 3, 4, 7 and 8, and returns findings. Resolve them or record why not. +sections 3, 4, 7 and 8, and returns findings. Resolve them or record why not. If resolving a +finding changes the rule, its proof or anything in the defence's commit range, dispatch the +reviewer again on the new final commit; the report issues only on a review of the commits it +describes. Write the report using `${CLAUDE_SKILL_DIR}/references/REPORT-TEMPLATE.md`, every heading filled. The report goes where the project keeps such records, or into the pull request -description if it has no such place. +description if it has no such place. Where there is neither, give the whole report in your +final message and ask the owner where it should be kept. Whatever happens to the report, open +your final message with the line stating the specification version and source. ## What this skill will not do From c3faa6fec8662c2486bf0168217241e422ea9aed Mon Sep 17 00:00:00 2001 From: joseph Date: Wed, 30 Sep 2026 10:09:44 +0000 Subject: [PATCH 2/2] 0.2.1 review: foreground searcher, default report path, worktree setup Independent review of the previous commit: - "Do not end your turn" is not actionable for a background agent. The searcher is now dispatched in the foreground, so its result is in hand before the rule is written. - The report had no default path. It now defaults to .dbf/reports/-.md, committed with the remediation, and the final message names the location after the version line. - The reviewer's detached worktree lacks ignored files and could be left registered by an interrupted run. It now prunes first and installs the project's dependencies in the worktree, or marks the run unverified. Co-Authored-By: Claude Opus 5.5 --- agents/conformance-reviewer.md | 10 ++++++---- skills/dbf/SKILL.md | 15 ++++++++------- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/agents/conformance-reviewer.md b/agents/conformance-reviewer.md index f171a21..2580d48 100644 --- a/agents/conformance-reviewer.md +++ b/agents/conformance-reviewer.md @@ -10,10 +10,12 @@ you the commit that introduced the defence, the final commit, the project's entr its checks, the draft report, the path to the method specification, and the paths of the toolchain contract and the language guides the remediation used. You check the work against the specification and return findings. You change nothing in the project under review. -Do the reproduction runs in a detached worktree of your own outside the project directory -(`git worktree add --detach `), switch commits in it with -`git checkout --detach`, and remove it with `git worktree remove` when you finish. Create no -branches, commits or tags. +Do the reproduction runs in a detached worktree of your own outside the project directory: +run `git worktree prune`, then `git worktree add --detach `, +switch commits in it with `git checkout --detach`, and remove it with `git worktree remove` +when you finish. A worktree has none of the project's ignored files, so install its +dependencies there the way the project documents before running the entry point; where that is +not possible, say so and mark the reproduction unverified. Create no branches, commits or tags. Read the specification's section 3 (the method), section 4 (authority), section 7 (review) and section 8 (operating under AI-assisted development) before you look at the work, and cite diff --git a/skills/dbf/SKILL.md b/skills/dbf/SKILL.md index 58a8387..3d57793 100644 --- a/skills/dbf/SKILL.md +++ b/skills/dbf/SKILL.md @@ -97,16 +97,16 @@ The project prompt gives the order and the rules. In outline: exist unchanged had the rule never been written. Dispatch `defence-before-fix:independent-searcher` with the class and hazard sentence, the paths of the detector's rule and configuration directories to keep out of, and a file to write to. - Let it run whilst you write and prove the rule, but fix nothing, the original included, - until its findings are in hand at step 5. If it runs in the background, wait for it to - finish before step 5, and do not end your turn or give a final answer whilst it is running. + Dispatch it in the foreground, so that its result is in hand before you write the rule; a + background dispatch lets the remediation run ahead of its own search. Fix nothing, the + original included, until you have reconciled with it at step 5. 3. **Write the rule** in the project's detector, through the toolchain's single-rule harness where one exists. Draw it wider than the one instance and no wider than the hazard. Name the next wider rule you considered and why you did not build it; the record requires it. 4. **Prove the rule fires** on the originating instance or on a fixture you keep as its test, and commit the defence red, as a commit of its own, before any instance is fixed. The contract's proof section and the guide's harness say how, for the host you chose. -5. **Reconcile with the search**, once the searcher has returned. Where the searcher's findings exceed the rule's, widen the +5. **Reconcile with the search.** Where the searcher's findings exceed the rule's, widen the rule; the search wins. Record what each of its two techniques found that the other could not have checked. 6. **Sweep and count.** Run the rule everywhere the pattern can occur: first-party source in @@ -141,9 +141,10 @@ describes. Write the report using `${CLAUDE_SKILL_DIR}/references/REPORT-TEMPLATE.md`, every heading filled. The report goes where the project keeps such records, or into the pull request -description if it has no such place. Where there is neither, give the whole report in your -final message and ask the owner where it should be kept. Whatever happens to the report, open -your final message with the line stating the specification version and source. +description if it has no such place. Where there is neither, write it to +`.dbf/reports/-.md` at the project root, with the date as YYYY-MM-DD and the class +as a short kebab-case name, and commit it with the remediation. Open your final message with the +line stating the specification version and source, followed by the report's location. ## What this skill will not do