devrites 5.12.0 → 5.13.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [5.13.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.12.0...v5.13.0) (2026-09-25)
+
+### Added
+
+* **skills:** add approval-gated /overhaul skill with engine tools ([#82](https://github.com/ViktorsBaikers/DevRites/issues/82)) ([79d0af0](https://github.com/ViktorsBaikers/DevRites/commit/79d0af0518d2536c5fd9278ca4891c95f4576a59))
+
 ## [5.12.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.11.0...v5.12.0) (2026-09-20)
 
 ### Added

package/README.md

@@ -34,7 +34,7 @@ project-conventional push, tag, or PR action, and archive the workspace.
 Unattended runs may create local WIP checkpoint commits along the way, but they
 remain local unless Ship's disclosed plan includes an approved remote action.
 
-**Status:** [`v5.12.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.12.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v5.13.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.13.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 
@@ -423,8 +423,10 @@ through Claude Code or Codex plugin stores.
 
 ## Skills and agents
 
-The pack ships 44 skills: 33 public and 11 internal. The public surface contains
-the `rite` menu and 32 `rite-*` workflows and utilities. Ten `devrites-*`
+The pack ships 45 skills: 34 public and 11 internal. The public surface contains
+the `rite` menu, 32 `rite-*` workflows and utilities, and the standalone,
+explicit-only `/overhaul` (approval-gated project, PR or branch audit with verified
+repairs; it runs without a DevRites workspace). Ten `devrites-*`
 specialists load when a matching task needs them; `devrites-lib` carries the
 shared contracts and engineering standards.
 

package/docs/architecture.md

@@ -389,8 +389,8 @@ contract.
 
 ## Design choices at a glance
 
-- **Surface**: 32 public `rite-*` skills (44 total), plus the thin `/rite`
-  menu: 33 public and 11 internal. The lifecycle
+- **Surface**: 32 public `rite-*` skills (45 total), plus the thin `/rite`
+  menu and the standalone `overhaul` skill: 34 public and 11 internal. The lifecycle
   includes mandatory adaptive Clarify, optional Temper, mandatory Vet, and
   Converge recovery; Seal **decides** and Ship **executes + closes**. Ten
   `devrites-*` specialist skills are model-invoked; `devrites-lib` is the

package/docs/command-map.md

@@ -22,7 +22,8 @@ visibility. Public utilities use the `rite-*` prefix: `rite-quick`,
 `rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`,
 `rite-pr-feedback`, and `rite-watch-pr`, plus the evidence-gated workspace compatibility command
 `rite-upgrade`. The host may invoke `devrites-*` specialists through the model.
-`devrites-lib` is the non-workflow library exception.
+`devrites-lib` is the non-workflow library exception. `overhaul` is a standalone,
+explicit-only skill outside both prefixes; it runs without any DevRites workspace.
 
 ## Surface lifecycle
 
@@ -121,6 +122,7 @@ See [`cli.md`](cli.md).
 | [`/rite-watch-pr`](../pack/.claude/skills/rite-watch-pr/SKILL.md) | utility | `[PR number\|PR URL\|blank for current branch]` | Observe one GitHub PR/CI/review snapshot, classify one next action, and stop. Safe for capability-admitted native schedules/events; never mutates code, Git, checks, threads, or PR state. | PR/check/review metadata + bounded failed-log excerpts | none |
 | [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3 to 5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
 | [`/rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | diagnostic | none | Diagnose the DevRites binary, pack, schema, and native host permission/profile configuration. | install + host config | none |
+| [`/overhaul`](../pack/.claude/skills/overhaul/SKILL.md) | standalone | `[full \| pr <n\|url> \| branch <head> --base <base> \| audit <scope> \| apply <run-id> --plan <rev> \| status <run-id> \| resume <run-id>]` | Explicit-only, outside the lifecycle. Concurrent frontend and backend engineering review plus boundary, craft and specialist roles (skill-local role files dispatched as fresh contexts); one verified plan; stops for the user's approval of the exact plan revision; then test-first repairs, independent verification, measurement and evidence-backed scoring, cycling inside the approved envelope. `audit` never repairs. Never commits, pushes, stashes or touches the index. | target repository (read-only until approval) | run area outside the repository (JSON records, HTML/Markdown views, evidence); approved target paths only after approval |
 
 `/rite use <slug>` and `/rite guide` are inline router operations owned by
 `/rite`, not separate skills. There is no `/rite-use` or `/rite-guide` shortcut.

package/docs/engine/commands.md

@@ -46,6 +46,7 @@ workflow strategy.
 | `secret-scan [--staged] [--stdin] [slug]` | Scan exact staged blobs, stdin, or touched regular files for credential material. |
 | `open-visual <path-or-name> [--slug <slug>] [--no-open]` | Resolve a local visual HTML file, optionally open it in the OS browser, warn if the sibling outline is missing or inventory ids are absent from HTML, and print agent path tips. No network. |
 | `detect commands [--root <dir>] [--json]` | Resolve the repository's own test/lint/vet/build commands: explicit Makefile targets first, then `package.json` scripts, then language-manifest fallbacks, plus the lockfile-derived package manager. Read-only, no installs, no execution. |
+| `overhaul <records\|admit\|snapshot\|score\|bench\|render> ...` | Deterministic tools behind the standalone `/overhaul` skill: run-record generations and cross-record validation, worker-receipt admission and quote anchoring, index-safe baseline snapshots and per-attempt deltas, exact-rational readiness scoring, benchmark ratio intervals, and escaped offline review/report views. Operates only on explicit run-area and repository paths. See [Overhaul tools](#overhaul-tools). |
 | `version` | Print the engine version. |
 
 `help`, `-h`, and `--help` print this operational inventory. Each operational
@@ -136,6 +137,26 @@ the local file only — never a network fetch. Stdout prints the absolute HTML
 path, outline path tip, playbook index hint, and an `ids=ok` / `ids=mismatch`
 summary when an inventory is present.
 
+## Overhaul tools
+
+`overhaul` serves the explicit-only `/overhaul` skill. Each tool takes explicit
+paths and never resolves a `.devrites` workspace, calls a model or uses the
+network. The skill documents the record schemas and when to call each tool.
+
+| Tool | Forms | Exit codes |
+| --- | --- | --- |
+| `records` | `digest <file>`, `stage <run>`, `publish <run>`, `validate <run>` | 0 ok; 1 violations (listed as `VIOLATION:` lines); 2 usage or I/O |
+| `admit` | `receipt <run> <receipt.json> [--observed <file>]`, `anchor <tree> <proposals.json>` | 0 admissible; 1 rejected; 2 usage or I/O; 3 duplicate or late receipt |
+| `snapshot` | `capture <repo> <out>`, `fingerprint <repo>`, `verify <repo> <out> [--agent-paths <file>]`, `state <repo> <out.json>`, `delta <before.json> <repo>` | 0 ok; 1 index changed or changes outside agent paths; 2 refusal, usage or I/O |
+| `score` | `--rubric <r> --results <s> --gates <g> [--out <file>]`, `compare --rubric <r> --baseline <a> --candidate <b>` | 0 computed; 2 invalid input (nothing counts as scored) |
+| `bench` | `<result.json>` | 0 computed; 2 invalid input |
+| `render` | `<run> <staged-generation> <review\|report>` | 0 written; 2 usage, invalid records or I/O |
+
+`snapshot` runs git read-only with `GIT_OPTIONAL_LOCKS=0`,
+`diff.autoRefreshIndex=false` and no external diff drivers, so `.git/index`
+stays byte-identical. Secret-pattern files and files holding private key material
+are hashed only: never copied into the snapshot tree and never included in its patches.
+
 ## Output and exit contracts
 
 `check candidate` passes with exactly:

package/docs/flow.md

@@ -381,7 +381,7 @@ separately by `disable-model-invocation`.
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true): 33 skills"]
+    subgraph Public["Public (user-invocable: true): 34 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
@@ -416,6 +416,7 @@ flowchart TB
         D1[/rite-zoom-out/]
         D2[/rite-prototype/]
         D3[/rite-handoff/]
+        OVH[/overhaul<br/>standalone, outside the lifecycle/]
     end
     subgraph Internal["Internal (user-invocable: false): 11 skills (10 specialists + devrites-lib library)"]
         direction TB

package/docs/skills.md

@@ -1,8 +1,8 @@
-# All 44 skills
+# All 45 skills
 
-The pack contains 44 skills: the `rite` menu, 32 user-invocable `rite-*`
-workflow and utility skills, 10 model-invoked `devrites-*` specialists, and the
-internal `devrites-lib` library. `devrites-lib` is not a command. It holds shared
+The pack contains 45 skills: the `rite` menu, 32 user-invocable `rite-*`
+workflow and utility skills, the standalone `overhaul` skill,
+10 model-invoked `devrites-*` specialists, and the internal `devrites-lib` library. `devrites-lib` is not a command. It holds shared
 references and the few explicit script exceptions.
 
 Install DevRites through npm with `npx devrites ...`. DevRites is not available
@@ -49,6 +49,9 @@ contract when a rite names parallel reviewers.
 Some specialized utilities set `disable-model-invocation: true` and run only
 when explicitly invoked, which keeps the always-loaded skill surface small.
 `devrites-*` is the specialist and library namespace used to avoid collisions.
+`overhaul` sits outside both namespaces on purpose: it is a standalone,
+explicit-only skill that needs no DevRites workspace or lifecycle; its deterministic
+tools run as `devrites-engine overhaul` commands.
 The `user-invocable:` and `disable-model-invocation:` fields, not the prefix,
 set visibility and invocation policy. [`command-map.md`](command-map.md)
 catalogs the effective values.
@@ -239,6 +242,12 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 | [`rite-pr-feedback`](../pack/.claude/skills/rite-pr-feedback/SKILL.md) | Resolve PR review feedback: fetch unresolved threads, judge centrally, fix valid items, reply, resolve. | Explicit-only: `/rite-pr-feedback` / `/rite pr-feedback`. |
 | [`rite-watch-pr`](../pack/.claude/skills/rite-watch-pr/SKILL.md) | Observe one PR/CI/review snapshot and report one next action without mutation. | Read-only capability-admitted native schedule/event observation or `/rite-watch-pr`. |
 
+### Standalone: approval-gated overhaul
+
+| Skill | What It Does | Use When |
+|---|---|---|
+| [`overhaul`](../pack/.claude/skills/overhaul/SKILL.md) | Audits a whole project, a PR or a branch comparison with separate frontend and backend engineering reviewers running concurrently, plus boundary, craft and specialist roles; reconciles verified findings into one plan and stops for the user's explicit approval of that exact plan revision. After approval it repairs test-first, verifies independently, measures, and keeps cycling inside the approved plan until the evidence-backed scores (global and per-lane 9.7, domains 9.0) and every hard gate pass or an honest blocker remains. It lives outside the DevRites lifecycle: no `.devrites/` workspace and no `/rite-*` phase; its records, admission, snapshot, scoring, benchmark and view tools are `devrites-engine overhaul` commands. Completion evidence is a run area outside the repository with canonical JSON records, a local HTML review and report, and a reviewable local patch; it never commits. | Explicit-only: `/overhaul`, `/overhaul full`, `/overhaul pr <n>`, `/overhaul branch <head> --base <base>`, `/overhaul audit …` (assessment only). |
+
 ### Foundation: engineering rules
 
 | Skill | What It Does | Use When |

package/engine/help.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/devrites/devrites/internal/overhaul"
 	"github.com/devrites/devrites/internal/parallel"
 )
 
@@ -136,7 +137,7 @@ func shouldPrintHelp(args []string) bool {
 		return true
 	}
 	switch args[0] {
-	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate":
+	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate", "overhaul":
 		return len(args) >= 2 && args[1] == "help"
 	default:
 		return false
@@ -194,6 +195,8 @@ func commandHelp(args []string) (string, bool) {
 		return gatesFamilyUsage, true
 	case "note":
 		return noteFamilyUsage, true
+	case "overhaul":
+		return overhaul.Usage, true
 	case "migrate":
 		return migrateUsage, true
 	case "secret-scan":

package/engine/help_test.go

@@ -47,6 +47,8 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"migrate", "--help"}, want: "migrate <slug>"},
 		{args: []string{"secret-scan", "--help"}, want: "secret-scan [--staged] [--stdin]"},
 		{args: []string{"open-visual", "--help"}, want: "open-visual <path-or-name>"},
+		{args: []string{"overhaul", "--help"}, want: "overhaul records validate <run>"},
+		{args: []string{"overhaul", "help"}, want: "overhaul snapshot capture <repo> <out>"},
 		{args: []string{"version", "--help"}, want: "devrites-engine version"},
 		{args: []string{"install", "--help"}, want: "usage: devrites-engine install"},
 		{args: []string{"update", "--help"}, want: "usage: devrites-engine update"},

package/engine/internal/overhaul/admit/admit_test.go

@@ -0,0 +1,170 @@
+package admit
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+type J = map[string]any
+type L = []any
+
+func write(t *testing.T, path string, v any) string {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	b, ok := v.(string)
+	if !ok {
+		raw, err := json.Marshal(v)
+		if err != nil {
+			t.Fatal(err)
+		}
+		b = string(raw)
+	}
+	if err := os.WriteFile(path, []byte(b), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+func run(args ...string) (int, string, string) {
+	var out, errb bytes.Buffer
+	code := Run(args, &out, &errb)
+	return code, out.String(), errb.String()
+}
+
+func newRun(t *testing.T) string {
+	dir := filepath.Join(t.TempDir(), "run")
+	write(t, filepath.Join(dir, "CURRENT"), "g0001\n")
+	write(t, filepath.Join(dir, "g0001/run.json"), J{"run_id": "run-1",
+		"revisions": J{"plan": J{"rev": 1, "file": "revisions/plan-r1.json"}}})
+	write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+		J{"task_id": "T-1", "attempt_id": "A0", "role": "implementer", "lane": "fix", "snapshot": "s1", "status": "admitted"},
+		J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "lane": "fix", "snapshot": "s1", "status": "running"},
+		J{"task_id": "R-1", "attempt_id": "A1", "role": "reviewer", "lane": "security", "snapshot": "s1", "status": "running"},
+	}})
+	write(t, filepath.Join(dir, "revisions/plan-r1.json"), J{"rev": 1, "tasks": L{
+		J{"id": "T-1", "allowed_paths": L{"src/a.py"}}, J{"id": "T-2", "allowed_paths": L{"src/b.py"}}}})
+	return dir
+}
+
+func writerReceipt() J {
+	return J{"schema": "overhaul.receipt/1", "run_id": "run-1", "task_id": "T-1", "attempt_id": "A1",
+		"role": "implementer", "lane": "fix", "snapshot": "s1", "started_at": "t0", "finished_at": "t1",
+		"outcome": "patch", "changed_paths": L{"src/a.py"}}
+}
+
+func TestReceipt(t *testing.T) {
+	cases := []struct {
+		name     string
+		mutate   func(J)
+		observed string // "-" means no --observed flag
+		code     int
+		want     string
+	}{
+		{"writer admissible", func(J) {}, "src/a.py\n\n", 0, `{"verdict": "ADMISSIBLE", "reasons": []}`},
+		{"observed differs", func(J) {}, "src/b.py\n", 1, "observed paths ['src/b.py'] differ from claimed ['src/a.py']"},
+		{"claimed outside contract", func(r J) { r["changed_paths"] = L{"src/a.py", "src/c.py"} }, "src/a.py\nsrc/c.py\n", 1, "changed paths outside contract: ['src/c.py']"},
+		{"writer needs observed", func(J) {}, "-", 1, "writer receipt needs observed changed paths (--observed)"},
+		{"snapshot mismatch", func(r J) { r["snapshot"] = "s2" }, "src/a.py\n", 1, "snapshot differs from the dispatch packet"},
+		{"bad outcome", func(r J) { r["outcome"] = "done" }, "src/a.py\n", 1, "outcome must be one of ['findings', 'gap', 'no-findings', 'patch', 'verdict']"},
+		{"missing finished_at", func(r J) { delete(r, "finished_at") }, "src/a.py\n", 1, "missing finished_at"},
+		{"wrong run", func(r J) { r["run_id"] = "run-2" }, "src/a.py\n", 1, "wrong schema or run"},
+		{"unknown attempt", func(r J) { r["attempt_id"] = "A9" }, "-", 1, "no such dispatched attempt"},
+		{"duplicate or late", func(r J) { r["attempt_id"] = "A0" }, "src/a.py\n", 3, `{"verdict": "DUPLICATE_OR_LATE", "attempt_status": "admitted"}`},
+		{"reviewer no-findings without inspected", func(r J) {
+			r["task_id"], r["role"], r["lane"], r["outcome"] = "R-1", "reviewer", "security", "no-findings"
+			delete(r, "changed_paths")
+		}, "-", 1, "no-findings without inspected ranges is malformed"},
+		{"reviewer admissible", func(r J) {
+			r["task_id"], r["role"], r["lane"], r["outcome"], r["inspected"] = "R-1", "reviewer", "security", "no-findings", L{"src/a.py:1-9"}
+		}, "-", 0, "ADMISSIBLE"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			dir := newRun(t)
+			rc := writerReceipt()
+			c.mutate(rc)
+			args := []string{"receipt", dir, write(t, filepath.Join(dir, "receipts/r.json"), rc)}
+			if c.observed != "-" {
+				args = append(args, "--observed", write(t, filepath.Join(dir, "observed.txt"), c.observed))
+			}
+			code, out, errs := run(args...)
+			if code != c.code || !strings.Contains(out, c.want) {
+				t.Fatalf("want %d with %q, got %d:\n%s%s", c.code, c.want, code, out, errs)
+			}
+		})
+	}
+}
+
+func TestReceiptIOError(t *testing.T) {
+	dir := newRun(t)
+	if code, _, errs := run("receipt", dir, filepath.Join(dir, "missing.json")); code != 2 || !strings.HasPrefix(errs, "ERROR: ") {
+		t.Fatalf("got %d %s", code, errs)
+	}
+	if code, _, _ := run("receipt", dir, "x.json", "--observed"); code != 2 {
+		t.Fatalf("dangling --observed exit %d", code)
+	}
+	if code, _, _ := run("anchor"); code != 2 {
+		t.Fatalf("usage exit %d", code)
+	}
+}
+
+func TestAnchor(t *testing.T) {
+	loc := func(path string, start, end int, quote string) J {
+		return J{"path": path, "start": start, "end": end, "quote": quote}
+	}
+	cases := []struct {
+		name     string
+		findings L
+		code     int
+		want     string
+	}{
+		{"match", L{J{"id": "F-1", "locations": L{loc("src/a.py", 2, 2, "  return   request.user ")}}}, 0, `{"verdict": "ANCHORED", "reasons": []}`},
+		{"multi-line match", L{J{"id": "F-1", "locations": L{loc("src/a.py", 1, 2, "(request): return request")}}}, 0, "ANCHORED"},
+		{"wrong quote", L{J{"id": "F-1", "locations": L{loc("src/a.py", 2, 2, "return request.admin")}}}, 1, "F-1: quote not found at src/a.py:2-2"},
+		{"lines outside file", L{J{"id": "F-1", "locations": L{loc("src/a.py", 2, 9, "return request.user")}}}, 1, "F-1: src/a.py lines 2-9 outside file (3 lines)"},
+		{"path escape", L{J{"id": "F-1", "locations": L{loc("../secret.py", 1, 1, "top secret value")}}}, 1, "F-1: ../secret.py is not a file under the reviewed tree"},
+		{"directory", L{J{"id": "F-1", "locations": L{loc("src", 1, 1, "whatever long")}}}, 1, "is not a file under"},
+		{"too short", L{J{"id": "F-1", "locations": L{loc("src/a.py", 2, 2, "return")}}}, 1, "F-1: quote at src/a.py:2 is too short to anchor; quote the whole line"},
+		{"short quote equal to window", L{J{"id": "F-1", "locations": L{loc("src/a.py", 3, 3, "x = 1")}}}, 0, "ANCHORED"},
+		{"no locations", L{J{"id": "F-2"}}, 1, "F-2: no locations to anchor"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			dir := t.TempDir()
+			tree := filepath.Join(dir, "tree")
+			write(t, filepath.Join(tree, "src/a.py"), "def handler(request):\n    return request.user\nx = 1\n")
+			write(t, filepath.Join(dir, "secret.py"), "top secret value\n")
+			code, out, errs := run("anchor", tree, write(t, filepath.Join(dir, "p.json"), J{"findings": c.findings}))
+			if code != c.code || !strings.Contains(out, c.want) {
+				t.Fatalf("want %d with %q, got %d:\n%s%s", c.code, c.want, code, out, errs)
+			}
+		})
+	}
+}
+
+func TestAnchorBadInput(t *testing.T) {
+	dir := t.TempDir()
+	for _, doc := range []any{J{"findings": L{}}, L{}, J{"items": L{J{"id": "F-1"}}}} {
+		code, _, errs := run("anchor", dir, write(t, filepath.Join(dir, "p.json"), doc))
+		if code != 2 || !strings.Contains(errs, `expected {"findings": [...]} with at least one finding`) {
+			t.Fatalf("%v: got %d %s", doc, code, errs)
+		}
+	}
+}
+
+func TestSplitlines(t *testing.T) {
+	got := splitlines("a\r\nb\rc\n\nd\u2028e")
+	want := []string{"a", "b", "c", "", "d", "e"}
+	if strings.Join(got, "|") != strings.Join(want, "|") {
+		t.Fatalf("splitlines = %q", got)
+	}
+	if pyJSON("é\"<\x01") != `"\u00e9\"<\u0001"` {
+		t.Fatalf("pyJSON = %s", pyJSON("é\"<\x01"))
+	}
+}