@dreb/coding-agent 2.44.0 → 2.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/agents/independent-assessor.md +37 -20
  2. package/docs/mach6.md +21 -10
  3. package/docs/skills.md +2 -2
  4. package/package.json +1 -1
  5. package/skills/mach6-implement/SKILL.md +41 -21
  6. package/skills/mach6-push/SKILL.md +6 -3
  7. package/skills/mach6-review/SKILL.md +56 -18
package/agents/independent-assessor.md CHANGED
@@ -5,34 +5,49 @@ tools: read, grep, find, ls, bash, search
5
5
  model: zai/glm-5.1, anthropic/opus
6
6
  ---
7
7
 
8
- You are an independent assessor. Your single question is: **"Is each review finding a genuine issue, a nitpick, or a false positive?"**
8
+ You are an independent assessor. For every review finding, answer two separate questions:
9
+
10
+ 1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
11
+ 2. **Scope gate:** Must that problem be fixed to deliver the authorized issue or latest explicitly approved plan safely and correctly?
12
+
13
+ A finding is **not genuine merely because it is technically correct or factually observable**. It is genuine only when it passes both gates.
9
14
 
10
15
  You do NOT:
11
16
  - Generate new findings — only assess findings provided to you
12
17
  - Trust finding descriptions at face value — always read the actual source code
13
18
  - Conflate severity with classification — a low-severity genuine issue is still genuine
19
+ - Treat review findings or prior automated assessments as scope authority
14
20
 
15
21
  ## Process
16
22
 
17
- 1. **Read all findings** from the review comment provided in your task prompt
18
- 2. **For each finding:**
19
- a. Read the cited file and lines in the actual codebase
20
- b. Understand the surrounding context (read more of the file if needed)
21
- c. Determine whether the finding accurately describes a real problem
22
- d. Classify the finding (see classifications below)
23
- e. Write a brief justification referencing what you observed in the code
24
- 3. **Produce an action plan** listing genuine issues in priority order
23
+ 1. **Establish authoritative scope before classifying anything:**
24
+ - Read the linked original issue, including its acceptance criteria and relevant human discussion
25
+ - Read the latest explicit plan comment (look for the latest `<!-- mach6-plan -->` marker)
26
+ - Read subsequent scope updates that a human explicitly approved
27
+ - Extract the requirements, deliverables, constraints, and accepted scope changes
28
+ - Review findings and prior automated assessments are evidence only. They do **not** expand scope through novelty, repetition, or earlier classification.
29
+ 2. **Read all findings** from the review comment provided in your task prompt.
30
+ 3. **For each finding:**
31
+ a. Read the cited file and lines in the actual codebase.
32
+ b. Understand the surrounding context (read more of the file if needed).
33
+ c. Apply the **factual gate**: determine whether the finding accurately describes a real current problem.
34
+ d. Apply the **scope gate**: map the required fix to the authoritative scope, or determine that it addresses a regression or correctness, security, safety, or integrity problem introduced by the PR.
35
+ e. Classify the finding using the table below.
36
+ f. Justify the classification with both factual evidence and scope reasoning. Every genuine classification must explicitly explain why both gates pass.
37
+ 4. **Produce an action plan** containing only genuine issues, in priority order.
25
38
 
26
39
  ## Classifications
27
40
 
28
41
  | Classification | Meaning | Action |
29
42
  |---|---|---|
30
- | **Genuine issue** | Real problem confirmed by reading the code. Should fix before merge. | Include in action plan |
31
- | **Nitpick** | Stylistic preference or minor inconsistency. Does not affect correctness. | Skip |
32
- | **False positive** | The code is actually correct. The finding misread the code or missed context. | Skip |
33
- | **Deferred** | Real issue but clearly out of scope for this PR. Should track separately. | Note for follow-up |
43
+ | **Genuine issue** | Passes both gates: a real problem confirmed in the code that must be fixed for the authorized scope to merge safely and correctly. This includes regressions and correctness, security, safety, or integrity failures introduced by the PR. | Include in action plan |
44
+ | **Nitpick** | Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement. | Skip |
45
+ | **False positive** | Fails the factual gate: the current code is correct, the finding missed context, or the issue was already addressed. | Skip |
46
+ | **Deferred** | Passes the factual gate but fails the scope gate: a real observation that is not necessary for this PR's authorized work. | Note separately for optional follow-up; do not include in action plan |
47
+
48
+ Optional hardening, speculative edge cases, unrelated pre-existing defects, architecture preferences, and broader cleanup are not genuine unless the authoritative scope explicitly requires them. They are normally deferred when factually valid. Review findings and automated assessments cannot become authorized requirements merely because multiple agents repeat them.
34
49
 
35
- If a finding was already addressed in prior commits or PR discussion, classify as false positive with a note.
50
+ Missing tests for behavior added or changed by the PR are in scope. A scoped implementation must not regress existing behavior or introduce correctness, security, safety, or integrity problems even when the original issue did not enumerate the exact failure.
36
51
 
37
52
  ## Output Format
38
53
 
@@ -40,22 +55,24 @@ If a finding was already addressed in prior commits or PR discussion, classify a
40
55
 
41
56
  | Finding | Classification | Reasoning |
42
57
  |---|---|---|
43
- | Finding 1: <title> | genuine/nitpick/false-positive/deferred | <1-2 sentences referencing what you saw in the code> |
58
+ | Finding 1: <title> | genuine/nitpick/false-positive/deferred | **Factual:** <what the current code proves>. **Scope:** <why the finding is or is not necessary for the authorized PR>. |
59
+
60
+ Classify every supplied finding. For every genuine classification, both the **Factual** and **Scope** explanations are mandatory.
44
61
 
45
62
  ### Action Plan
46
63
 
47
- <Numbered list of genuine issues to fix, ordered by priority — critical first>
64
+ <Numbered list of genuine issues necessary for the authorized PR to merge, ordered by priority — critical first. Do not include deferred, nitpick, or false-positive findings.>
48
65
 
49
- If no genuine issues found, say "No action needed before merge — all findings are nitpicks, false positives, or deferred." with a brief summary. Note any deferred items separately for follow-up tracking.
66
+ If no genuine issues are found, say "No action needed before merge — all findings are nitpicks, false positives, or deferred." with a brief summary. Note deferred items separately for optional follow-up, outside the action plan.
50
67
 
51
68
  ## Important
52
69
 
53
70
  - You have full codebase access. USE IT. Read every file referenced by every finding.
54
- - Be specific. Quote the actual code when explaining your classification.
55
- - Disagree with the original reviewer when the code proves them wrong — that's your job.
71
+ - Be specific. Quote the actual code when explaining factual validity.
72
+ - Cite the issue, acceptance criterion, plan item, approved scope update, or PR-introduced regression when explaining scope relevance.
73
+ - Disagree with the original reviewer when either gate fails — that is your job.
56
74
  - Do NOT use `#N` notation in your output (GitHub auto-links it to issues). Use "finding N" or "item N" instead.
57
75
 
58
-
59
76
  ## Constraints
60
77
 
61
78
  - **Never post to GitHub.** Do not run `gh pr comment`, `gh issue comment`, `gh issue create`, or any command that writes to GitHub. Your job is to return findings to the caller — the orchestrator handles all GitHub interaction.
package/docs/mach6.md CHANGED
@@ -11,10 +11,10 @@ Inspired by [mach10](https://github.com/LeanAndMean/mach10) (MIT, by Kevin Ryan)
11
11
  /skill:mach6-plan 42 # Plan, branch, open draft PR
12
12
  # ... implement the plan ...
13
13
  /skill:mach6-push # Commit, push, post progress
14
- /skill:mach6-review 53 # Multi-agent code review
14
+ /skill:mach6-review 53 # User explicitly starts review
15
15
  /skill:mach6-implement 53 1,2 # Fix review findings
16
- /skill:mach6-push # Push fixes
17
- /skill:mach6-review 53 # Re-review (repeat until clean)
16
+ /skill:mach6-push # Durably save fixes
17
+ /skill:mach6-review 53 # User explicitly starts re-review
18
18
  /skill:mach6-publish 53 # Docs update, merge, tag, release
19
19
  ```
20
20
 
@@ -64,10 +64,12 @@ Commit changes, push to remote, and post a progress comment.
64
64
  - Matches the repository's existing commit style
65
65
  - Auto-detects the associated PR from the current branch
66
66
  - Posts a `<!-- mach6-progress -->` comment with a summary of changes
67
+ - Establishes the durable accountability and recovery checkpoint before formal review
68
+ - Stops after pushing and suggests the review command; it never starts review itself
67
69
 
68
70
  ### mach6-review
69
71
 
70
- Run specialized review agents in parallel, post findings, then independently assess each finding.
72
+ Run specialized review agents in parallel, post findings, then independently assess each finding. Formal review is an explicit user-controlled checkpoint: start it with the slash command or directly instruct an agent to invoke it. Agents never start it autonomously, and it refuses to run until the worktree is clean and local `HEAD` matches the pushed PR head.
71
73
 
72
74
  ```
73
75
  /skill:mach6-review 53 # Full review (all agents)
@@ -78,7 +80,9 @@ Run specialized review agents in parallel, post findings, then independently ass
78
80
  Produces two PR comments:
79
81
 
80
82
  1. **Review** (`<!-- mach6-review -->`) — findings organized by severity (critical, important, suggestions), plus strengths
81
- 2. **Assessment** (`<!-- mach6-assessment -->`) — each finding independently classified as genuine issue, nitpick, false positive, or deferred, with a prioritized action plan
83
+ 2. **Assessment** (`<!-- mach6-assessment -->`) — each finding independently classified as genuine issue, nitpick, false positive, or deferred, with a prioritized action plan containing genuine issues only
84
+
85
+ A finding is genuine only when it passes both a **factual gate** (the current code contains the problem) and a **scope gate** (the problem must be fixed to deliver the authorized work safely and correctly). Authoritative scope comes from the linked original issue and acceptance criteria, the latest explicit `mach6-plan`, and subsequent human-approved updates. Automated review findings and earlier assessments do not expand scope by repetition. Factually valid but unrelated observations are normally deferred; PR-introduced regressions and correctness, security, safety, or integrity failures remain in scope.
82
86
 
83
87
  See [Review Agents](#review-agents) below.
84
88
 
@@ -92,9 +96,13 @@ Implement a plan from a PR, or fix review findings / CI failures.
92
96
  /skill:mach6-implement 53 ci # Fix CI failures
93
97
  ```
94
98
 
95
- **Implement mode** (PR number only): Reads the `<!-- mach6-plan -->` comment and delegates each deliverable to `feature-dev` subagents — strong-tier coding agents with full tool access. Independent deliverables run in parallel.
99
+ In both modes, the parent model owns implementation reasoning: design, decomposition, exact changes, decision rules, tests, and verification. Direct parent implementation is generally acceptable. `feature-dev` delegation is optional and is best reserved for high-volume, repetitive, mechanically scoped execution after the parent has settled the design—for example, applying a content-dependent transformation across dozens of files. Every delegated task receives clear, detailed, specific instructions rather than an open-ended design problem.
100
+
101
+ **Implement mode** (PR number only): Reads the `<!-- mach6-plan -->` comment, decides the implementation, and either works directly or delegates precisely specified execution.
102
+
103
+ **Fix mode** (with finding numbers or `ci`): Reads review and assessment comments via HTML markers, verifies each authorized finding, decides the fix, and then implements directly or delegates mechanically settled execution.
96
104
 
97
- **Fix mode** (with finding numbers or `ci`): Reads review and assessment comments via HTML markers, delegates fixes to `feature-dev` subagents, applies batch sizing heuristics (~10 simple, ~6 moderate, ~3 complex fixes per batch), and suggests `/skill:mach6-push` then `/skill:mach6-review` after fixing.
105
+ After direct verification, `mach6-implement` stops at the accountability checkpoint and suggests `/skill:mach6-push`. Committing, pushing, and posting progress protects work from loss or repeated unsupervised rewriting. The user can subsequently start formal `mach6-review` with its slash command or by directly instructing an agent to invoke it; agents never start review autonomously. Focused one-off reviewer/checker subagents remain available for narrow correctness questions or second opinions; they are not a formal mach6 review cycle.
98
106
 
99
107
  ### mach6-publish
100
108
 
@@ -115,7 +123,7 @@ Pre-merge checks, version bump, docs update, merge, tag, and release.
115
123
 
116
124
  ### feature-dev
117
125
 
118
- Strong general-purpose coding agent used by `mach6-implement` for plan implementation and fix application. Has full tool access (read, write, edit, grep, find, ls, bash, search) and uses a strong-tier model with provider fallback list. Each deliverable or finding gets its own `feature-dev` subagent, enabling parallel execution of independent work.
126
+ Strong general-purpose coding agent optionally used by `mach6-implement` for precisely specified execution. It has full tool access (read, write, edit, grep, find, ls, bash, search) and uses a strong-tier model with a provider fallback list. The parent model retains design ownership and may implement directly; `feature-dev` is most useful for high-volume, repetitive work with settled decision rules.
119
127
 
120
128
  ### Review Agents
121
129
 
@@ -136,8 +144,11 @@ Agents run as [subagents](../README.md#subagents) — `code-reviewer`, `error-au
136
144
  ## Design Principles
137
145
 
138
146
  - **GitHub as shared memory** — Plans, reviews, assessments, and progress are posted as PR/issue comments with HTML markers (`<!-- mach6-plan -->`, `<!-- mach6-review -->`, etc.) so any future session can pick up context.
139
- - **Independent assessment** — Review findings are independently verified before suggesting fixes, separating genuine issues from nitpicks and false positives.
140
- - **Iterative review cycles** — Review → fix → push → review, repeating until no genuine issues remain.
147
+ - **Scope-aware independent assessment** — Review findings must be both factually valid and necessary for authorized scope before they become genuine action items.
148
+ - **Durable accountability checkpoint** — Implementation and fixes are committed, pushed, and recorded before formal review so work cannot be lost or repeatedly rewritten while still local.
149
+ - **User-controlled review cycles** — Only the user starts each formal review or re-review. Agents stop at the checkpoint and suggest the next command rather than autonomously chaining review and fix cycles.
150
+ - **Focused checks remain available** — One-off reviewer/checker subagents may answer narrow correctness questions without becoming a formal mach6 review cycle.
151
+ - **Parent-owned implementation** — The parent model owns design and may implement directly; delegation is optional execution support for mechanically settled grunt work.
141
152
  - **Safe git** — Never `git add -A`, never stage secrets, stage files by name.
142
153
  - **Overridable** — Both skills and review agents can be overridden by placing files with the same name in `~/.dreb/agent/skills/` or `~/.dreb/agents/` (user-level) or `.dreb/skills/` or `.dreb/agents/` (project-level).
143
154
 
package/docs/skills.md CHANGED
@@ -282,11 +282,11 @@ dreb ships with **mach6**, a development workflow that orchestrates the full iss
282
282
  | `mach6-issue` | Assess an existing issue or create a new one |
283
283
  | `mach6-plan` | Explore codebase, plan, create branch and draft PR |
284
284
  | `mach6-push` | Commit, push, post progress comment |
285
- | `mach6-review` | Multi-agent code review with independent assessment |
285
+ | `mach6-review` | Explicitly user-triggered multi-agent review with scope-aware independent assessment |
286
286
  | `mach6-implement` | Implement plans, fix review findings, or fix CI failures |
287
287
  | `mach6-publish` | Pre-merge checks, docs update, merge, tag, release |
288
288
 
289
- Built-in skills are always available and can be overridden by placing a skill with the same name in any [user or project location](#locations).
289
+ Built-in skills are always available and can be overridden by placing a skill with the same name in any [user or project location](#locations). `mach6-review` is model-invocable when the user directly asks an agent to run it, as well as user-invocable through its slash command. Agents must never start formal review autonomously; implementation must first be committed and pushed.
290
290
 
291
291
  See [docs/mach6.md](mach6.md) for full documentation.
292
292
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dreb/coding-agent",
3
- "version": "2.44.0",
3
+ "version": "2.45.0",
4
4
  "description": "Coding agent CLI with read, bash, edit, write tools and session management",
5
5
  "type": "module",
6
6
  "drebConfig": {
package/skills/mach6-implement/SKILL.md CHANGED
@@ -20,6 +20,18 @@ This skill has two modes:
20
20
  4. **Task tracking** — Use the `tasks_update` tool to show progress.
21
21
  5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
22
22
 
23
+ ## Parent ownership and the formal-review checkpoint
24
+
25
+ These rules apply in both implement and fix modes, even if you never load the `mach6-push` or `mach6-review` skills:
26
+
27
+ - **The parent model owns implementation reasoning.** You decide the design, decomposition, exact changes, constraints, and verification strategy. Do not use a subagent as a substitute for thinking through the implementation.
28
+ - **Direct implementation is generally acceptable.** The parent may implement any deliverable or fix directly; this is not limited to trivial work.
29
+ - **Delegate execution, not unresolved design.** `feature-dev` is optional and is most useful for high-volume, repetitive, mechanically scoped grunt work after you have settled the rules—for example, applying a content-dependent transformation across dozens of files. Ordinary reading and writing alone is not a reason to delegate.
30
+ - **Every delegated task must be clear, detailed, and specific.** Give the agent the intended changes, exact relevant files, existing patterns to follow, decision rules, constraints, required tests, and expected verification. Resolve ambiguity yourself before delegation; never hand off a vague deliverable and ask the agent to design it.
31
+ - **Focused checks remain allowed.** You may launch a focused, one-off reviewer or checker subagent for a narrow correctness question or second opinion. Do not turn that into the formal mach6 multi-agent review/assessment workflow or an autonomous review-fix-review loop.
32
+ - **Save work before formal review.** A successful implementation is not yet durable shared work. Committing, pushing, and posting a GitHub progress comment creates the accountability and recovery boundary, reducing the risk that unsupervised review cycles repeatedly rewrite or destroy work before it is saved.
33
+ - **Only the user starts formal `mach6-review`.** After implementation and direct verification, do not invoke `mach6-review` and do not begin a review cycle. Use `suggest_next` to offer `/skill:mach6-push`, then stop. After the push is complete, the user decides whether to explicitly invoke review.
34
+
23
35
  ## Step 1: Parse input
24
36
 
25
37
  Extract:
@@ -71,20 +83,24 @@ Read all files mentioned in the plan. Understand the existing code before making
71
83
 
72
84
  ### Step 6i: Implement
73
85
 
74
- Use the `feature-dev` subagent to implement each deliverable. `feature-dev` is a **pre-existing agent definition** shipped with dreb — it has full tool access (read, write, edit, grep, find, ls, bash, search) and uses a strong-tier model with a provider fallback list. Do not override its model unless there's a specific reason.
86
+ For each deliverable, first decide the implementation yourself: map it to the approved plan, inspect the relevant code, settle the design and decision rules, identify exact files and patterns, and define the required tests and verification.
75
87
 
76
- **For each deliverable in the plan**, launch a `feature-dev` subagent via the `subagent` tool. Provide each agent with:
77
- - The specific deliverable to implement (files to modify, what to change, expected behavior)
78
- - The full plan context and any relevant PR discussion
79
- - The list of files to read for understanding existing patterns
80
- - Instructions to run tests and linting after making changes
81
- - **If the plan includes tests for this deliverable, tests MUST be written as part of the implementation — not deferred**
88
+ Implement directly unless delegation has a concrete context-preservation benefit. Direct parent implementation is generally acceptable regardless of plan size. Use the pre-existing `feature-dev` agent only for execution that is sufficiently high-volume, repetitive, and mechanically specified to justify delegation; do not delegate merely because a task involves reading and writing code.
82
89
 
83
- **Test coverage is part of the deliverable, not an afterthought.** If the plan specifies tests for a deliverable, the feature-dev agent must implement them. If the target package lacks test infrastructure, add it.
90
+ When delegating, provide a complete execution plan containing:
91
+ - The authorized deliverable and why it is in scope
92
+ - Exact files or a precisely bounded file set
93
+ - Specific changes and content-dependent decision rules
94
+ - Existing code patterns and constraints to preserve
95
+ - Required tests, linting, and validation commands
96
+ - Expected observable result and completion criteria
97
+ - Relevant plan and PR discussion context
84
98
 
85
- **Parallelism:** If deliverables are independent (don't modify the same files), run their `feature-dev` agents in parallel. If they have dependencies, use chain mode or run them sequentially — later features may depend on earlier ones.
99
+ A `feature-dev` agent should be able to execute without inventing design decisions. If direction is ambiguous, the parent must resolve it before delegation. Do not override the agent's model unless there is a specific reason.
86
100
 
87
- **Small plans (1-2 simple deliverables):** You may implement directly instead of delegating, if the changes are straightforward enough that subagent overhead isn't justified.
101
+ **Test coverage is part of the deliverable, not an afterthought.** Implement all planned tests with the behavior they cover. If the target package lacks test infrastructure, add it.
102
+
103
+ **Parallelism:** Parallelize only independent, mechanically specified tasks that do not overlap files or depend on unresolved work. Otherwise implement directly or sequence the work.
88
104
 
89
105
  Update task tracking as each deliverable completes.
90
106
 
@@ -97,7 +113,7 @@ After all `feature-dev` agents complete:
97
113
  - Verify each deliverable from the plan is addressed
98
114
  - If any agent reported issues or partial completion, address the gaps
99
115
 
100
- Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for review.
116
+ Stop at the accountability checkpoint. Do **not** invoke `mach6-review` or begin a formal review cycle. Explain that the implementation must be committed, pushed, and recorded before the user decides whether to review. Use `suggest_next` to offer `/skill:mach6-push`, then end the turn.
101
117
 
102
118
  ---
103
119
 
@@ -149,19 +165,23 @@ If more than batch size, fix first batch and tell user to re-run.
149
165
 
150
166
  ### Step 6f: Implement fixes
151
167
 
152
- Use the `feature-dev` subagent to implement fixes. `feature-dev` is a **pre-existing agent definition** shipped with dreb — it has full tool access and uses a strong-tier model with a provider fallback list. Do not override its model unless there's a specific reason.
168
+ For each authorized finding, the parent must verify the assessment against the current code, decide the exact fix, identify affected files and patterns, and define the regression tests and validation before editing or delegating.
169
+
170
+ Implement fixes directly by default. Use the pre-existing `feature-dev` agent only when a fix has high-volume, repetitive, mechanically settled execution that benefits from context isolation. Direct parent implementation is acceptable for simple and complex fixes alike.
153
171
 
154
- **For each finding** (or batch of related findings), launch a `feature-dev` subagent with:
155
- - The finding description and the assessment's classification/reasoning
156
- - The specific files and code locations involved
157
- - Instructions on what to fix and how
158
- - Instructions to run tests after fixing
172
+ When delegating, provide:
173
+ - The finding and its factual and scope reasoning
174
+ - Exact files and code locations, or a precisely bounded file set
175
+ - The complete fix design and content-dependent decision rules
176
+ - Existing patterns and constraints to preserve
177
+ - Required regression tests and validation commands
178
+ - Expected result and completion criteria
159
179
 
160
- **Parallelism:** If findings touch different files, run their `feature-dev` agents in parallel. If findings overlap (same file/function), batch them into a single agent.
180
+ Do not ask `feature-dev` to determine the design. Resolve ambiguity before delegation, and do not override its model unless there is a specific reason.
161
181
 
162
- **Simple fixes** (typos, naming, one-line changes): You may fix these directly instead of delegating.
182
+ **Parallelism:** Parallelize only independent, mechanically specified fixes that do not overlap files. Otherwise implement directly or sequence them.
163
183
 
164
- Defer out-of-scope items to new issues. Update task tracking per finding.
184
+ Defer only review-surfaced items that are factually valid but outside the authoritative PR scope. User-approved requirements are in scope. Update task tracking per finding.
165
185
 
166
186
  ### Step 7f: Verify
167
187
 
@@ -170,4 +190,4 @@ After all `feature-dev` agents complete:
170
190
  - Verify each fix addresses its finding
171
191
  - If any agent reported issues, address the gaps
172
192
 
173
- Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for re-review.
193
+ Stop at the accountability checkpoint. Do **not** invoke `mach6-review` or begin a formal re-review cycle. Explain that the fixes must be committed, pushed, and recorded before the user decides whether to re-review. Use `suggest_next` to offer `/skill:mach6-push`, then end the turn.
package/skills/mach6-push/SKILL.md CHANGED
@@ -16,6 +16,7 @@ argument-hint: "[commit message]"
16
16
  4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets (.env, credentials, tokens, keys).
17
17
  5. **Task tracking** — Use the `tasks_update` tool to show progress.
18
18
  6. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
19
+ 7. **Stop after durable progress** — The commit, push, and GitHub progress comment are the accountability and recovery boundary. Do not invoke `mach6-review` or continue into a formal review cycle. Only the user may start formal review; offer it with `suggest_next` and stop.
19
20
 
20
21
  ## Step 1: Set up task tracking
21
22
 
@@ -98,9 +99,11 @@ gh pr comment <number> --body-file "$GH_BODY"
98
99
 
99
100
  Update task: comment → completed.
100
101
 
101
- Report: what was committed, where pushed, where the comment was posted (with link).
102
+ Report: what was committed, where pushed, and where the comment was posted (with link). The work is now durably saved and available for accountable review.
102
103
 
103
- Suggest next step based on context:
104
+ Stop here. Do not invoke `mach6-review`, launch formal review agents, or begin a review-fix-review loop. Only the user may start formal review.
105
+
106
+ Use `suggest_next` for exactly one context-appropriate command, then end the turn:
104
107
  - If on a feature branch with a PR: `/skill:mach6-review <pr-number>`
105
108
  - If on a feature branch without a PR: `/skill:mach6-plan <issue-number>` to create one
106
- - If on the default branch: issue-oriented next steps
109
+ - If on the default branch: an issue-oriented next step
package/skills/mach6-review/SKILL.md CHANGED
@@ -15,8 +15,10 @@ argument-hint: "<pr-number> [code|errors|tests|completeness|simplify]"
15
15
  3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
16
16
  4. **Task tracking** — Use the `tasks_update` tool to show progress.
17
17
  5. **Non-interactive `gh`** — Set `GH_PAGER=cat` and `GH_EDITOR=cat` before all `gh` commands to prevent interactive prompts from hanging the agent. Use `--body-file` instead of inline `--body` for all `gh pr comment`, `gh pr create`, and `gh issue create` calls to avoid shell interpretation of backticks. Write each body to a **unique per-invocation temp file** via `mktemp` (e.g. `GH_BODY="$(mktemp /tmp/gh-comment.XXXXXX.md)"`) — never a fixed path like `/tmp/gh-comment.md`, which concurrent mach6 sessions on the same machine would clobber, cross-posting one session's body to another's PR/issue.
18
+ 6. **User-controlled checkpoint** — This formal multi-agent review runs only from an explicit user request, either through its slash command or a direct instruction to an agent to invoke it. An agent may invoke it in response to that request; otherwise agents must only offer it with `suggest_next`, never invoke it autonomously or start a review-fix-review loop.
19
+ 7. **Review durable work only** — Do not launch formal review agents against uncommitted or unpushed work. The commit, push, and GitHub progress comment are the accountability and recovery boundary.
18
20
 
19
- **Important: Do NOT fix any issues in this session. Fixes happen via `/skill:mach6-implement`.**
21
+ **Important: Do NOT fix any issues in this session. Fixes happen via a later, user-invoked `/skill:mach6-implement`.**
20
22
 
21
23
  ## Step 1: Set up task tracking
22
24
 
@@ -37,25 +39,51 @@ Extract:
37
39
  - **PR number** (required)
38
40
  - **Review aspects** (optional) — if specified, only run matching agents
39
41
 
40
- ## Step 3: Prepare
42
+ ## Step 3: Prepare and enforce the durable-work checkpoint
43
+
44
+ Before switching branches, run `git status --porcelain`. If it returns anything, stop and use `suggest_next` to offer `/skill:mach6-push`; do not risk carrying or overwriting unsaved work during checkout.
45
+
46
+ Check out and update the PR branch:
41
47
 
42
48
  ```bash
43
49
  gh pr checkout <pr-number>
44
- git pull
50
+ git pull --ff-only
45
51
  ```
46
52
 
47
- Mark the PR as ready for review (it was opened as a draft by mach6-plan):
53
+ **Before marking the PR ready, reading local source for review, or launching any review agent**, verify again that the worktree is clean and local `HEAD` is exactly the pushed PR head:
54
+
48
55
  ```bash
49
- gh pr ready <pr-number>
56
+ git status --porcelain
57
+ LOCAL_HEAD="$(git rev-parse HEAD)"
58
+ PR_HEAD="$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid')"
59
+ test "$LOCAL_HEAD" = "$PR_HEAD"
50
60
  ```
51
61
 
52
- Gather PR context — read ALL comments, not just specific markers:
62
+ If `git status --porcelain` returns anything, or the commit IDs differ, stop immediately. Do not mark the PR ready, post review comments, or launch review agents. Explain that formal review only evaluates durably saved work, then use `suggest_next` to offer `/skill:mach6-push`.
63
+
64
+ Once the durable-work checks pass, gather all authoritative scope and PR context:
65
+
53
66
  ```bash
54
- gh pr view <pr-number> --json title,body,comments,files
67
+ gh pr view <pr-number> --json title,body,comments,files,headRefOid
55
68
  gh pr diff <pr-number>
69
+ gh issue view <linked-issue-number> --comments
56
70
  ```
57
71
 
58
- Read the PR description, ALL comments (plans, progress updates, prior reviews, discussion), and the linked issue. This full context must be provided to review agents so they understand what was intended and what has already been discussed.
72
+ Read the PR description, **all** comments, and the linked original issue. Establish authoritative scope from:
73
+
74
+ - The linked original issue and its acceptance criteria
75
+ - The latest explicit plan comment (the latest `<!-- mach6-plan -->` marker)
76
+ - Subsequent scope updates explicitly approved by a human
77
+
78
+ Review findings and prior automated assessments are evidence only. They do not expand scope through novelty, repetition, or earlier classification.
79
+
80
+ Now mark the PR as ready for review (it was opened as a draft by mach6-plan):
81
+
82
+ ```bash
83
+ gh pr ready <pr-number>
84
+ ```
85
+
86
+ Provide the full PR context and authoritative scope to every review agent so they understand what was intended and what has already been approved.
59
87
 
60
88
  Update task: prepare → completed, review → in_progress.
61
89
 
@@ -84,7 +112,9 @@ These agents are **pre-existing agent definitions** shipped with dreb — do not
84
112
 
85
113
  Provide each agent with:
86
114
  - The list of changed files with paths
87
- - The PR description and linked issue context
115
+ - The full PR context: title, body, and all comments
116
+ - The authoritative scope: linked original issue and acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
117
+ - The rule that review findings and prior automated assessments are evidence only and cannot expand scope
88
118
  - Instructions to read the actual changed files for full context
89
119
 
90
120
  All agents use confidence scoring (0-100, only report findings ≥ 80).
@@ -137,18 +167,26 @@ Launch a subagent with `agent: "independent-assessor"`. This is a **pre-existing
137
167
 
138
168
  Provide the assessor with:
139
169
  - The full review text
140
- - The PR context (title, body, comments)
170
+ - The PR context (title, body, and all comments)
171
+ - The authoritative scope context: linked original issue, acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
141
172
  - Instructions to **read the actual code** for each finding and verify independently
142
173
 
174
+ Repeat this two-gate rule in the assessor task:
175
+
176
+ 1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
177
+ 2. **Scope gate:** Must that problem be fixed to deliver the authoritative scope safely and correctly?
178
+
179
+ A finding is not genuine merely because it is technically correct or factually observable. It is genuine only when both gates pass. Review findings and prior automated assessments are not scope updates and cannot become authoritative through novelty, repetition, or earlier classification.
180
+
143
181
  The assessor classifies each finding as:
144
- - **Genuine issue** — Real problem, should fix before merge. Explain why.
145
- - **Nitpick** — Stylistic, doesn't affect correctness. Explain why it doesn't matter.
146
- - **False positive** — Not actually an issue. Explain why the code is correct.
147
- - **Deferred** — Real issue but out of scope. Should track separately.
182
+ - **Genuine issue** — Passes both gates. The reasoning must separately explain factual evidence and scope relevance.
183
+ - **Nitpick** — Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement.
184
+ - **False positive** — Fails the factual gate because the current code is correct, context was missed, or the issue was already addressed.
185
+ - **Deferred** — Passes the factual gate but fails the scope gate. Note separately for optional follow-up; never include in the action plan.
148
186
 
149
- If a finding was already addressed in prior commits or PR discussion, classify as false positive with a note.
187
+ Optional improvements, speculative hardening, unrelated pre-existing defects, architecture preferences, and broader cleanup are normally deferred when factually valid unless a human explicitly authorized them. Regressions and correctness, security, safety, or integrity failures introduced by the PR remain eligible for genuine classification because the scoped implementation must be safe and must not break existing behavior.
150
188
 
151
- After classifying all findings, produce an **action plan** listing what to fix, in what order.
189
+ After classifying every finding, produce an **action plan containing only genuine issues** necessary for the scoped PR to merge, ordered by priority.
152
190
 
153
191
  **Important guidance on "deferred" classifications:** Test coverage gaps should NOT be automatically deferred. If a PR adds new testable code, tests should ship with it — even if that means adding test infrastructure to a package that lacks it. Only defer tests when the gap is truly unrelated to the PR's changes (e.g., pre-existing untested code that the PR happens to touch). When tests are deferred, the assessor must note whether a tracking issue exists or needs to be created.
154
192
 
@@ -168,11 +206,11 @@ cat > "$GH_BODY" << 'MACH6_EOF'
168
206
 
169
207
  | Finding | Classification | Reasoning |
170
208
  |---|---|---|
171
- | <summary> | genuine/nitpick/false-positive/deferred | <1-2 sentences> |
209
+ | <summary> | genuine/nitpick/false-positive/deferred | **Factual:** <what the code proves>. **Scope:** <why this is or is not required by authoritative scope>. |
172
210
 
173
211
  ### Action Plan
174
212
 
175
- <numbered list of what to fix, ordered by priority>
213
+ <numbered list of genuine issues only, ordered by priority>
176
214
 
177
215
  ---
178
216
  *Assessment by mach6*