@dreb/coding-agent 2.43.3 → 2.45.0

package/README.md

@@ -81,7 +81,7 @@ Or use a custom provider (corporate proxy, Bedrock, etc.) — see [Custom provid
 
 Then just talk to dreb. All 11 built-in tools are enabled by default: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`, `web_search`, `web_fetch`, `subagent`, and `wait`. Use `--tools` to restrict to a subset (e.g., `--tools read,grep,find,ls` for read-only). Three additional tools — `search`, `skill`, and `tasks_update` — are always active regardless of `--tools`. `suggest_next` is active by default but excluded when `--tools` is specified. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [packages](#packages).
 
-**Also available:** [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`). [`@dreb/dashboard`](https://www.npmjs.com/package/@dreb/dashboard) — run `dreb dashboard` for a browser UI with fleet overview, full chat steering, subagent observability, host file browser, curated appearance themes (per-browser light/dark), and Tailscale/rotating-code pairing (`npm install -g @dreb/dashboard`; see [docs/dashboard.md](docs/dashboard.md)). Its top bar and persistent session header indicators report connecting, connected, retrying, resyncing, disconnected, or auth failed; bounded SSE replay plus an explicit snapshot barrier restores session state and tasks after a reload, restart, gap, backpressure disconnect, or stalled stream.
+**Also available:** [`@dreb/telegram`](https://www.npmjs.com/package/@dreb/telegram) — run dreb as a Telegram bot with live tool status and visible results for user-facing tools (`npm install -g @dreb/telegram`). [`@dreb/dashboard`](https://www.npmjs.com/package/@dreb/dashboard) — run `dreb dashboard` for a browser UI with fleet overview, full chat steering, subagent observability, host file browser, curated appearance themes (per-browser light/dark), and Tailscale/rotating-code pairing (`npm install -g @dreb/dashboard`; see [docs/dashboard.md](docs/dashboard.md)). Compact SSE snapshots update live fleet cards without repeatedly fetching the cross-project inventory, and session drill-in hydrates state, messages, and background agents through one ordered snapshot request. Its top bar and persistent session header indicators report connecting, connected, retrying, resyncing, disconnected, or auth failed; bounded SSE replay plus an explicit snapshot barrier restores session state and tasks after a reload, restart, gap, backpressure disconnect, or stalled stream.
 
 **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 

package/agents/independent-assessor.md

@@ -5,34 +5,49 @@ tools: read, grep, find, ls, bash, search
 model: zai/glm-5.1, anthropic/opus
 ---
 
-You are an independent assessor. Your single question is: **"Is each review finding a genuine issue, a nitpick, or a false positive?"**
+You are an independent assessor. For every review finding, answer two separate questions:
+
+1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
+2. **Scope gate:** Must that problem be fixed to deliver the authorized issue or latest explicitly approved plan safely and correctly?
+
+A finding is **not genuine merely because it is technically correct or factually observable**. It is genuine only when it passes both gates.
 
 You do NOT:
 - Generate new findings — only assess findings provided to you
 - Trust finding descriptions at face value — always read the actual source code
 - Conflate severity with classification — a low-severity genuine issue is still genuine
+- Treat review findings or prior automated assessments as scope authority
 
 ## Process
 
-1. **Read all findings** from the review comment provided in your task prompt
-2. **For each finding:**
-   a. Read the cited file and lines in the actual codebase
-   b. Understand the surrounding context (read more of the file if needed)
-   c. Determine whether the finding accurately describes a real problem
-   d. Classify the finding (see classifications below)
-   e. Write a brief justification referencing what you observed in the code
-3. **Produce an action plan** listing genuine issues in priority order
+1. **Establish authoritative scope before classifying anything:**
+   - Read the linked original issue, including its acceptance criteria and relevant human discussion
+   - Read the latest explicit plan comment (look for the latest `<!-- mach6-plan -->` marker)
+   - Read subsequent scope updates that a human explicitly approved
+   - Extract the requirements, deliverables, constraints, and accepted scope changes
+   - Review findings and prior automated assessments are evidence only. They do **not** expand scope through novelty, repetition, or earlier classification.
+2. **Read all findings** from the review comment provided in your task prompt.
+3. **For each finding:**
+   a. Read the cited file and lines in the actual codebase.
+   b. Understand the surrounding context (read more of the file if needed).
+   c. Apply the **factual gate**: determine whether the finding accurately describes a real current problem.
+   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.
+   e. Classify the finding using the table below.
+   f. Justify the classification with both factual evidence and scope reasoning. Every genuine classification must explicitly explain why both gates pass.
+4. **Produce an action plan** containing only genuine issues, in priority order.
 
 ## Classifications
 
 | Classification | Meaning | Action |
 |---|---|---|
-| **Genuine issue** | Real problem confirmed by reading the code. Should fix before merge. | Include in action plan |
-| **Nitpick** | Stylistic preference or minor inconsistency. Does not affect correctness. | Skip |
-| **False positive** | The code is actually correct. The finding misread the code or missed context. | Skip |
-| **Deferred** | Real issue but clearly out of scope for this PR. Should track separately. | Note for follow-up |
+| **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 |
+| **Nitpick** | Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement. | Skip |
+| **False positive** | Fails the factual gate: the current code is correct, the finding missed context, or the issue was already addressed. | Skip |
+| **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 |
+
+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.
 
-If a finding was already addressed in prior commits or PR discussion, classify as false positive with a note.
+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.
 
 ## Output Format
 
@@ -40,22 +55,24 @@ If a finding was already addressed in prior commits or PR discussion, classify a
 
 | Finding | Classification | Reasoning |
 |---|---|---|
-| Finding 1: <title> | genuine/nitpick/false-positive/deferred | <1-2 sentences referencing what you saw in the code> |
+| 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>. |
+
+Classify every supplied finding. For every genuine classification, both the **Factual** and **Scope** explanations are mandatory.
 
 ### Action Plan
 
-<Numbered list of genuine issues to fix, ordered by priority — critical first>
+<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.>
 
-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.
+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.
 
 ## Important
 
 - You have full codebase access. USE IT. Read every file referenced by every finding.
-- Be specific. Quote the actual code when explaining your classification.
-- Disagree with the original reviewer when the code proves them wrong — that's your job.
+- Be specific. Quote the actual code when explaining factual validity.
+- Cite the issue, acceptance criterion, plan item, approved scope update, or PR-introduced regression when explaining scope relevance.
+- Disagree with the original reviewer when either gate fails — that is your job.
 - Do NOT use `#N` notation in your output (GitHub auto-links it to issues). Use "finding N" or "item N" instead.
 
-
 ## Constraints
 
 - **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/dashboard.md

@@ -126,6 +126,34 @@ networking window above.
 | **Settings** | Persistent defaults (default model, thinking level, steering/follow-up queue modes, auto-compaction, auto-retry) via `get_settings`/`set_settings` — validation errors are shown verbatim. Entering Settings flushes pending writes and reloads durable global + project settings, so external edits appear; read, parse, or write failures fail loudly instead of showing stale settings. The global-only nested-context policy lists every explicit trusted root for audit and revoke, offers a simple add-by-path control, and includes a prominently warned expert trust-all toggle; the Files view remains the primary place to grant trust while browsing. Most defaults seed new sessions; context-trust changes are observed by active main/subagent processes for future lazy loads, but cannot remove already injected content. Dashboard-local preferences (always expand thinking, needs-attention notification permission) live in the browser, alongside an appearance section: a theme gallery of eight curated themes (entropist.ca, Dim, Solarized, Gruvbox, Caves of Qud, Van Gogh, and the colorblind-safe Okabe-Ito and Paul Tol) with live preview cards and a system/light/dark mode selector, saved per browser. Shows the current rotating pairing code on the host/local dashboard, plus the paired-devices list with unpair. |
 | **Pairing** | Remote first-login: identity echo, rotating-code entry, and the security copy explaining what pairing grants. |
 
+## Fleet transport and freshness
+
+A normal dashboard load makes one authoritative `GET /api/fleet`; the fleet is
+also included in the ordered `/api/resync` response only during exceptional
+recovery. After initial load, global event-derived `fleet_snapshot` SSE frames
+update live runtime cards. The runtime pool emits those frames with a 200 ms
+debounce from its in-memory state, so an update performs neither child RPC calls
+nor a disk inventory scan.
+
+Live runtime state and on-disk session inventory have separate refresh paths.
+After creating, resuming, stopping, or deleting a session, the client narrowly
+refreshes the disk list through `GET /api/sessions` rather than reloading the
+whole fleet. While the Fleet screen is visible, it polls each live runtime's
+stats no more often than every 30 seconds. That poll is single-flight, retains a
+card's last good stats if an update fails, and surfaces failures in the Fleet UI.
+
+For the activity preview, a card prefers the newest assistant text derived from
+its hydrated client transcript entries. Until those entries exist, the
+authoritative initial-load or resync fleet preview is the fallback. `ctx%` is
+never a browser estimate: it comes from authoritative session state or stats.
+Live card ordering remains deterministic by project path and then session start
+time, not mutable activity.
+
+A session drill-in hydrates through one `GET /api/runtimes/:key/hydrate` request.
+The server backs it with one `getDashboardSnapshot` RPC call and its matching
+barrier, rather than three independently timed state/message/background-agent
+calls. Replay and resync retain their ordering guarantees below.
+
 ## Live connection and recovery
 
 The top bar and persistent session header expose the live-stream state as an accessible text `output`, not color alone: **connecting**, **connected**, **retrying** (including its delay), **resyncing**, **disconnected**, or **auth failed**. The session-header indicator remains visible when the session details or composer controls are collapsed. This is the state of the dashboard's single SSE connection, not the state of an individual agent.
@@ -284,6 +312,22 @@ session view prioritizes read-and-steer (model/thinking switchers collapse into
 Composer modes, abort, and needs-attention affordances are never reduced away
 — steering a running agent from a phone is the primary remote use case.
 
+## Mobile transport profiling
+
+The opt-in profiler runs locally on the dashboard host:
+
+```bash
+npm run --workspace @dreb/dashboard profile:mobile -- http://127.0.0.1:5343
+```
+
+Its output is aggregate and payload-free: HTTP response sizes/timings plus SSE
+sizes, event types, and burst summaries; it does not retain fleet or event
+contents. The default capture is 60 seconds. Profile a realistic workload of at
+least five live runtimes so both fleet and event behavior are representative.
+
+For browser acceptance, use Chromium's network throttling with 100 ms RTT and
+1.5 Mbps. This profile does not emulate HTTP packet loss.
+
 ## Architecture
 
 ```

package/docs/mach6.md

@@ -11,10 +11,10 @@ Inspired by [mach10](https://github.com/LeanAndMean/mach10) (MIT, by Kevin Ryan)
 /skill:mach6-plan 42           # Plan, branch, open draft PR
 # ... implement the plan ...
 /skill:mach6-push              # Commit, push, post progress
-/skill:mach6-review 53         # Multi-agent code review
+/skill:mach6-review 53         # User explicitly starts review
 /skill:mach6-implement 53 1,2   # Fix review findings
-/skill:mach6-push              # Push fixes
-/skill:mach6-review 53         # Re-review (repeat until clean)
+/skill:mach6-push              # Durably save fixes
+/skill:mach6-review 53         # User explicitly starts re-review
 /skill:mach6-publish 53        # Docs update, merge, tag, release
 ```
 
@@ -64,10 +64,12 @@ Commit changes, push to remote, and post a progress comment.
 - Matches the repository's existing commit style
 - Auto-detects the associated PR from the current branch
 - Posts a `<!-- mach6-progress -->` comment with a summary of changes
+- Establishes the durable accountability and recovery checkpoint before formal review
+- Stops after pushing and suggests the review command; it never starts review itself
 
 ### mach6-review
 
-Run specialized review agents in parallel, post findings, then independently assess each finding.
+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.
 
 ```
 /skill:mach6-review 53                     # Full review (all agents)
@@ -78,7 +80,9 @@ Run specialized review agents in parallel, post findings, then independently ass
 Produces two PR comments:
 
 1. **Review** (`<!-- mach6-review -->`) — findings organized by severity (critical, important, suggestions), plus strengths
-2. **Assessment** (`<!-- mach6-assessment -->`) — each finding independently classified as genuine issue, nitpick, false positive, or deferred, with a prioritized action plan
+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
+
+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.
 
 See [Review Agents](#review-agents) below.
 
@@ -92,9 +96,13 @@ Implement a plan from a PR, or fix review findings / CI failures.
 /skill:mach6-implement 53 ci          # Fix CI failures
 ```
 
-**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.
+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.
+
+**Implement mode** (PR number only): Reads the `<!-- mach6-plan -->` comment, decides the implementation, and either works directly or delegates precisely specified execution.
+
+**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.
 
-**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.
+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.
 
 ### mach6-publish
 
@@ -115,7 +123,7 @@ Pre-merge checks, version bump, docs update, merge, tag, and release.
 
 ### feature-dev
 
-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.
+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.
 
 ### Review Agents
 
@@ -136,8 +144,11 @@ Agents run as [subagents](../README.md#subagents) — `code-reviewer`, `error-au
 ## Design Principles
 
 - **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.
-- **Independent assessment** — Review findings are independently verified before suggesting fixes, separating genuine issues from nitpicks and false positives.
-- **Iterative review cycles** — Review → fix → push → review, repeating until no genuine issues remain.
+- **Scope-aware independent assessment** — Review findings must be both factually valid and necessary for authorized scope before they become genuine action items.
+- **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.
+- **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.
+- **Focused checks remain available** — One-off reviewer/checker subagents may answer narrow correctness questions without becoming a formal mach6 review cycle.
+- **Parent-owned implementation** — The parent model owns design and may implement directly; delegation is optional execution support for mechanically settled grunt work.
 - **Safe git** — Never `git add -A`, never stage secrets, stage files by name.
 - **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).
 

package/docs/skills.md

@@ -282,11 +282,11 @@ dreb ships with **mach6**, a development workflow that orchestrates the full iss
 | `mach6-issue` | Assess an existing issue or create a new one |
 | `mach6-plan` | Explore codebase, plan, create branch and draft PR |
 | `mach6-push` | Commit, push, post progress comment |
-| `mach6-review` | Multi-agent code review with independent assessment |
+| `mach6-review` | Explicitly user-triggered multi-agent review with scope-aware independent assessment |
 | `mach6-implement` | Implement plans, fix review findings, or fix CI failures |
 | `mach6-publish` | Pre-merge checks, docs update, merge, tag, release |
 
-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).
+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.
 
 See [docs/mach6.md](mach6.md) for full documentation.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dreb/coding-agent",
-	"version": "2.43.3",
+	"version": "2.45.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"drebConfig": {

package/skills/mach6-implement/SKILL.md

@@ -20,6 +20,18 @@ This skill has two modes:
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
 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.
 
+## Parent ownership and the formal-review checkpoint
+
+These rules apply in both implement and fix modes, even if you never load the `mach6-push` or `mach6-review` skills:
+
+- **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.
+- **Direct implementation is generally acceptable.** The parent may implement any deliverable or fix directly; this is not limited to trivial work.
+- **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.
+- **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.
+- **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.
+- **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.
+- **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.
+
 ## Step 1: Parse input
 
 Extract:
@@ -71,20 +83,24 @@ Read all files mentioned in the plan. Understand the existing code before making
 
 ### Step 6i: Implement
 
-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.
+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.
 
-**For each deliverable in the plan**, launch a `feature-dev` subagent via the `subagent` tool. Provide each agent with:
-- The specific deliverable to implement (files to modify, what to change, expected behavior)
-- The full plan context and any relevant PR discussion
-- The list of files to read for understanding existing patterns
-- Instructions to run tests and linting after making changes
-- **If the plan includes tests for this deliverable, tests MUST be written as part of the implementation — not deferred**
+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.
 
-**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.
+When delegating, provide a complete execution plan containing:
+- The authorized deliverable and why it is in scope
+- Exact files or a precisely bounded file set
+- Specific changes and content-dependent decision rules
+- Existing code patterns and constraints to preserve
+- Required tests, linting, and validation commands
+- Expected observable result and completion criteria
+- Relevant plan and PR discussion context
 
-**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.
+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.
 
-**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.
+**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.
+
+**Parallelism:** Parallelize only independent, mechanically specified tasks that do not overlap files or depend on unresolved work. Otherwise implement directly or sequence the work.
 
 Update task tracking as each deliverable completes.
 
@@ -97,7 +113,7 @@ After all `feature-dev` agents complete:
 - Verify each deliverable from the plan is addressed
 - If any agent reported issues or partial completion, address the gaps
 
-Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for review.
+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.
 
 ---
 
@@ -149,19 +165,23 @@ If more than batch size, fix first batch and tell user to re-run.
 
 ### Step 6f: Implement fixes
 
-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.
+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.
+
+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.
 
-**For each finding** (or batch of related findings), launch a `feature-dev` subagent with:
-- The finding description and the assessment's classification/reasoning
-- The specific files and code locations involved
-- Instructions on what to fix and how
-- Instructions to run tests after fixing
+When delegating, provide:
+- The finding and its factual and scope reasoning
+- Exact files and code locations, or a precisely bounded file set
+- The complete fix design and content-dependent decision rules
+- Existing patterns and constraints to preserve
+- Required regression tests and validation commands
+- Expected result and completion criteria
 
-**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.
+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.
 
-**Simple fixes** (typos, naming, one-line changes): You may fix these directly instead of delegating.
+**Parallelism:** Parallelize only independent, mechanically specified fixes that do not overlap files. Otherwise implement directly or sequence them.
 
-Defer out-of-scope items to new issues. Update task tracking per finding.
+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.
 
 ### Step 7f: Verify
 
@@ -170,4 +190,4 @@ After all `feature-dev` agents complete:
 - Verify each fix addresses its finding
 - If any agent reported issues, address the gaps
 
-Suggest next step: `/skill:mach6-push` then `/skill:mach6-review <pr-number>` for re-review.
+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

@@ -16,6 +16,7 @@ argument-hint: "[commit message]"
 4. **Safe git** — Never use `git add -A` or `git add .`. Stage files by name. Never stage secrets (.env, credentials, tokens, keys).
 5. **Task tracking** — Use the `tasks_update` tool to show progress.
 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.
+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.
 
 ## Step 1: Set up task tracking
 
@@ -98,9 +99,11 @@ gh pr comment <number> --body-file "$GH_BODY"
 
 Update task: comment → completed.
 
-Report: what was committed, where pushed, where the comment was posted (with link).
+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.
 
-Suggest next step based on context:
+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.
+
+Use `suggest_next` for exactly one context-appropriate command, then end the turn:
 - If on a feature branch with a PR: `/skill:mach6-review <pr-number>`
 - If on a feature branch without a PR: `/skill:mach6-plan <issue-number>` to create one
-- If on the default branch: issue-oriented next steps
+- If on the default branch: an issue-oriented next step

package/skills/mach6-review/SKILL.md

@@ -15,8 +15,10 @@ argument-hint: "<pr-number> [code|errors|tests|completeness|simplify]"
 3. **No `#N` in comment bodies** — Use "finding 3", "item 3", "stage 2" etc. instead.
 4. **Task tracking** — Use the `tasks_update` tool to show progress.
 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.
+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.
+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.
 
-**Important: Do NOT fix any issues in this session. Fixes happen via `/skill:mach6-implement`.**
+**Important: Do NOT fix any issues in this session. Fixes happen via a later, user-invoked `/skill:mach6-implement`.**
 
 ## Step 1: Set up task tracking
 
@@ -37,25 +39,51 @@ Extract:
 - **PR number** (required)
 - **Review aspects** (optional) — if specified, only run matching agents
 
-## Step 3: Prepare
+## Step 3: Prepare and enforce the durable-work checkpoint
+
+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.
+
+Check out and update the PR branch:
 
 ```bash
 gh pr checkout <pr-number>
-git pull
+git pull --ff-only
 ```
 
-Mark the PR as ready for review (it was opened as a draft by mach6-plan):
+**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:
+
 ```bash
-gh pr ready <pr-number>
+git status --porcelain
+LOCAL_HEAD="$(git rev-parse HEAD)"
+PR_HEAD="$(gh pr view <pr-number> --json headRefOid --jq '.headRefOid')"
+test "$LOCAL_HEAD" = "$PR_HEAD"
 ```
 
-Gather PR context — read ALL comments, not just specific markers:
+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`.
+
+Once the durable-work checks pass, gather all authoritative scope and PR context:
+
 ```bash
-gh pr view <pr-number> --json title,body,comments,files
+gh pr view <pr-number> --json title,body,comments,files,headRefOid
 gh pr diff <pr-number>
+gh issue view <linked-issue-number> --comments
 ```
 
-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.
+Read the PR description, **all** comments, and the linked original issue. Establish authoritative scope from:
+
+- The linked original issue and its acceptance criteria
+- The latest explicit plan comment (the latest `<!-- mach6-plan -->` marker)
+- Subsequent scope updates explicitly approved by a human
+
+Review findings and prior automated assessments are evidence only. They do not expand scope through novelty, repetition, or earlier classification.
+
+Now mark the PR as ready for review (it was opened as a draft by mach6-plan):
+
+```bash
+gh pr ready <pr-number>
+```
+
+Provide the full PR context and authoritative scope to every review agent so they understand what was intended and what has already been approved.
 
 Update task: prepare → completed, review → in_progress.
 
@@ -84,7 +112,9 @@ These agents are **pre-existing agent definitions** shipped with dreb — do not
 
 Provide each agent with:
 - The list of changed files with paths
-- The PR description and linked issue context
+- The full PR context: title, body, and all comments
+- The authoritative scope: linked original issue and acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
+- The rule that review findings and prior automated assessments are evidence only and cannot expand scope
 - Instructions to read the actual changed files for full context
 
 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
 
 Provide the assessor with:
 - The full review text
-- The PR context (title, body, comments)
+- The PR context (title, body, and all comments)
+- The authoritative scope context: linked original issue, acceptance criteria, latest explicit `mach6-plan`, and subsequent human-approved scope updates
 - Instructions to **read the actual code** for each finding and verify independently
 
+Repeat this two-gate rule in the assessor task:
+
+1. **Factual gate:** Does the finding accurately describe a real problem in the current code?
+2. **Scope gate:** Must that problem be fixed to deliver the authoritative scope safely and correctly?
+
+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.
+
 The assessor classifies each finding as:
-- **Genuine issue** — Real problem, should fix before merge. Explain why.
-- **Nitpick** — Stylistic, doesn't affect correctness. Explain why it doesn't matter.
-- **False positive** — Not actually an issue. Explain why the code is correct.
-- **Deferred** — Real issue but out of scope. Should track separately.
+- **Genuine issue** — Passes both gates. The reasoning must separately explain factual evidence and scope relevance.
+- **Nitpick** — Stylistic preference or minor inconsistency that does not affect correctness or an authorized requirement.
+- **False positive** — Fails the factual gate because the current code is correct, context was missed, or the issue was already addressed.
+- **Deferred** — Passes the factual gate but fails the scope gate. Note separately for optional follow-up; never include in the action plan.
 
-If a finding was already addressed in prior commits or PR discussion, classify as false positive with a note.
+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.
 
-After classifying all findings, produce an **action plan** listing what to fix, in what order.
+After classifying every finding, produce an **action plan containing only genuine issues** necessary for the scoped PR to merge, ordered by priority.
 
 **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.
 
@@ -168,11 +206,11 @@ cat > "$GH_BODY" << 'MACH6_EOF'
 
 | Finding | Classification | Reasoning |
 |---|---|---|
-| <summary> | genuine/nitpick/false-positive/deferred | <1-2 sentences> |
+| <summary> | genuine/nitpick/false-positive/deferred | **Factual:** <what the code proves>. **Scope:** <why this is or is not required by authoritative scope>. |
 
 ### Action Plan
 
-<numbered list of what to fix, ordered by priority>
+<numbered list of genuine issues only, ordered by priority>
 
 ---
 *Assessment by mach6*