devrites 5.14.4 → 6.0.0

package/docs/command-map.md

@@ -74,7 +74,8 @@ Scans cap captured input at 64 MiB and entries/findings at 4,096; findings expos
 metadata only and source or limit errors fail closed.
 
 Direct `devrites-engine update` acquires the latest exact-release pack and
-platform binary, then hands local paths to the downloaded engine. Shell/npm may
+platform binary, each verified by SHA-256 sidecar and `gh attestation verify`
+(`gh` installed and authenticated), then hands local paths to the downloaded engine. Shell/npm may
 perform the same acquisition before invoking the local path. `--check` compares
 the installed version with latest release metadata without downloading assets;
 engine release selectors are unsupported.
@@ -180,8 +181,9 @@ exact named project role; if that role is unavailable, the workflow stops for
 HITL. The root never executes a specialist role. Reviewer profiles are
 natively read-only. Claude keeps its root in plan mode; Codex uses a
 workspace-capable root so its child can write, while workflow policy forbids
-that root from editing source/tests. Both hosts expose only
-`devrites-slice-wright` as a writable specialist. See
+that root from editing source/tests. Among the lifecycle `devrites-*` specialists, both hosts expose only
+`devrites-slice-wright` as a writable one. The shipped profiles are the full
+role-to-permission map; `/rite-doctor` step 3 checks them. See
 [`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md#source-writing-boundary).
 
 ## Engineering rules (`pack/.claude/skills/devrites-lib/reference/standards/`)

package/docs/engine/state-schema.md

@@ -1,4 +1,4 @@
-# `.devrites/` state schema (v3)
+# `.devrites/` state schema (v4)
 
 The engine reads workflow state from plain files under `.devrites/`. Those
 human-editable files remain authoritative; the engine has no database or

package/docs/flow.md

@@ -346,7 +346,7 @@ erDiagram
     }
     WORKSPACE {
         string slug PK ".devrites/work/<slug>/"
-        int schemaVersion "3; mutations require current schema; older cursors remain readable"
+        int schemaVersion "4; mutations require current schema; older cursors remain readable"
     }
     state {
         string phase "frame | spec | clarify | temper | define | plan | vet | build | converge | prove | polish | review | seal | ship | done"

package/docs/harness-compliance.md

@@ -18,7 +18,7 @@ generation/install/permission/routing tests that exercise them.
 | Session context and compaction | Native | Native | all phases | explicit skill state read | no | high | Both hosts own transcript, session, resume, and compaction context; DevRites does not inject a duplicate lifecycle hook. |
 | Root orchestrator permissions | Native | Instruction-backed | all source mutations | stop if the root edits source | yes | medium | Claude uses project plan mode; Codex needs a workspace-capable parent for native writer-child execution, so its root no-source-writing boundary is instruction-enforced. |
 | Slice-wright exact paths | Instruction-backed | Instruction-backed | build safety | reject an out-of-scope returned diff | yes | medium | Both hosts run the exact write-capable slice-wright under native sandboxing. The task states exact paths; the root compares the returned file list and `git diff --name-only` with that contract. |
-| Native reviewer permissions | Native | Native | review/seal safety | HITL stop; no root inline review | yes | high | Claude reviewer profiles use permissionMode plan; Codex reviewer profiles use `default_permissions = ":read-only"`. No engine reviewer classifier is involved. |
+| Native reviewer permissions | Native | Native | review/seal safety | HITL stop; no root inline review | yes | high | Claude lifecycle `devrites-*` reviewer profiles use permissionMode plan; Codex lifecycle `devrites-*` reviewer profiles use `default_permissions = ":read-only"`. No engine reviewer classifier is involved. |
 | Skill invocation | Native | Native | all public rites | explicit file read | yes | high | Claude invokes /rite natively. Codex invokes $rite natively from the generated/mirrored .agents/skills tree; the mirror delivers artifacts rather than adapting execution. |
 | Candidate identity | Adapter-backed | Adapter-backed | Build through Ship | stop; never substitute a host hash | partial | high | Both hosts expose read-only `devrites-engine check candidate <slug>` with exact two-field output and preserve one binding across evidence, optional browser evidence, review, and seal. Build writes scope, Polish closes it, and Ship is candidate-read-only. |
 | Reviewer subagent dispatch | Native | Native | review/seal confidence | HITL stop; no root inline review | yes | high | Both hosts dispatch the exact named project role. Codex loads developer instructions and the `:read-only` permission profile from the generated custom-agent TOML. |
@@ -34,7 +34,7 @@ native skill procedure, not an engine diagnostic command.
 
 Generation and install tests verify the native profiles and configuration.
 Permission and routing tests prove that both hosts dispatch the exact
-slice-wright while every other specialist remains read-only. Claude grants that
+slice-wright while every other lifecycle `devrites-*` specialist remains read-only. Claude grants that
 writer `acceptEdits`; Codex grants it `:workspace`. Exact-path scope is
 instruction-backed on both hosts and the root rejects a returned diff outside
 the task contract. Candidate compatibility additionally requires the shared

package/docs/release.md

@@ -4,7 +4,7 @@
 each push to `main`, the `release` job in
 [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) checks the merged
 commit messages. A `feat:`, `fix:`, `perf:`, `refactor:`, `build:`,
-`remove:`, `docs(README):`, or `BREAKING CHANGE:` tells it to choose the next SemVer
+`remove:`, `docs(readme):`, or `BREAKING CHANGE:` tells it to choose the next SemVer
 version and run these steps:
 
 1. Waits for the workflow's validation, full shell suite, strict Go-engine checks, Linux cross-compile smoke, Windows and macOS Go tests.
@@ -17,12 +17,12 @@ version and run these steps:
    future npm Trusted Publisher can take over, and today authenticates with
    `secrets.NPM_TOKEN` because npm's OIDC exchange still returns
    "package not found" until that Trusted Publisher is configured for
-   `devrites`. This is what `npx devrites@latest` resolves. `npm pack`
-   regenerates the same `pack/generated/` artifacts during `prepack`; there
-   is no `postpack` cleanup step.
+   `devrites`. This is what `npx devrites@latest` resolves. `npm publish`
+   ships the committed, validate-checked `pack/generated/` (the repo `.npmrc`
+   sets `ignore-scripts=true`, so no lifecycle script runs).
 7. Commits the version bump + changelog as `chore(release): <version> [skip ci]`, creates tag `v<version>`, and publishes a GitHub Release with the tarball, verified installer, binaries, and every checksum sidecar attached. The release job then attests the artifacts with build provenance (`actions/attest-build-provenance`), independent of npm provenance.
 
-Package prepack normally owns host artifact generation; the release archive
+The release archive
 consumes the validated generated files from the same Git index as the rest of
 its payload. Package and release installs validate and copy
 `pack/generated/{claude,codex}`. When a shell install or update shim runs from a
@@ -31,13 +31,15 @@ the missing host payload before handing that local candidate to the engine. The
 engine itself only validates and copies host payloads; it never generates them.
 The npm entrypoint, verified release installer, and direct engine updater acquire
 only an exact-SemVer release bundle or platform binary with its mandatory
-exact-filename SHA-256 sidecar.
+exact-filename SHA-256 sidecar, and each such asset must also pass
+`gh attestation verify` (pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`;
+`gh` must be installed and authenticated, with no bypass).
 
 Verify a downloaded engine binary from a GitHub Release:
 
 ```bash
-curl -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe]"
-curl -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe].sha256"
+curl -q -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe]"
+curl -q -LO "https://github.com/ViktorsBaikers/DevRites/releases/download/v<version>/devrites-<os>-<arch>[.exe].sha256"
 ( cd "$(dirname "$0")" && shasum -a 256 -c devrites-<os>-<arch>[.exe].sha256 )
 ```
 
@@ -78,7 +80,8 @@ or path breach before extraction (at most 10,000 members, 4,096-byte paths, and
 256 MiB expanded files). Metadata is capped at 1 MiB, sidecars at 4 KiB,
 archives/binaries at 64 MiB, and the Node adapter follows at most five redirects.
 There is no raw, source-archive, tag, or default-branch acquisition fallback;
-exact-release guarantees begin at the checksummed release `install.sh` asset.
+exact-release guarantees begin at the checksummed release `install.sh` asset that
+also passes `gh attestation verify` (pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`).
 The Go release boundary may acquire the latest stable candidate; the downloaded
 engine then supplies local paths to the manifest-owned update core. Engine
 `update --check` resolves release metadata but downloads no assets. `--to` and
@@ -120,9 +123,10 @@ remove the exception.
 | --- | --- |
 | `feat:` | **minor** (`0.1.0` → `0.2.0`) |
 | `remove:` | **minor**; grouped under Removed in release notes |
-| `fix:` / `perf:` / `refactor:` / `build:` / `docs(README):` | **patch** (`0.1.0` → `0.1.1`) |
+| `fix:` / `perf:` / `refactor:` / `build:` / `docs(readme):` | **patch** (`0.1.0` → `0.1.1`) |
 | Any type with `BREAKING CHANGE:` footer or `!` after type (e.g. `feat!:`) | **major** (`0.1.0` → `1.0.0`) |
-| `chore:` / `ci:` / `test:` / `docs:` (non-README) | no release |
+| `revert:` | **patch** |
+| `build(deps-dev):` / `chore:` / `ci:` / `test:` / `style:` / `docs:` (non-README) | no release |
 | Any scope `(no-release)` (e.g. `feat(no-release): …`) | no release |
 
 Husky + commitlint reject non-conventional messages at commit time, so you can't accidentally bypass the rules.

package/docs/usage.md

@@ -334,7 +334,7 @@ by its cap and pause rules.
 # Drop the sentinel before bed. Keys are optional: empty file works.
 cat > .devrites/AFK <<'EOF'
 max_slices: 10
-notify: "curl -d \"$DEVRITES_QID: $DEVRITES_QUESTION\" ntfy.sh/my-topic"
+notify: "curl -fsS -m 10 -d \"$DEVRITES_QID: $DEVRITES_QUESTION\" ntfy.sh/my-topic"
 allow_gates: [advisory, validating]
 EOF
 

package/engine/commands.go

@@ -25,7 +25,7 @@ const (
 // workspace or Git state, which must never fall back after an unsafe root
 // selection.
 func rootModeFor(command string, args []string) rootMode {
-	if hasHelpFlag(args) || (len(args) > 0 && isHelpToken(args[0])) {
+	if hasHelpFlag(command, args) || (len(args) > 0 && isHelpToken(args[0])) {
 		return rootUnused
 	}
 	subcommand := firstRootOperand(args)

package/engine/go.mod

@@ -2,4 +2,4 @@ module github.com/devrites/devrites
 
 go 1.26
 
-toolchain go1.27.1
+toolchain go1.27.2

package/engine/help.go

@@ -5,6 +5,7 @@ import (
 	"io"
 	"strings"
 
+	"github.com/devrites/devrites/internal/notes"
 	"github.com/devrites/devrites/internal/overhaul"
 	"github.com/devrites/devrites/internal/parallel"
 )
@@ -33,6 +34,9 @@ const (
   state resolve <qid> "<answer>"
   state resolve --drop <qid> ["<reason>"]
   state resolve --batch <file>
+  state resolve --human <qid> "<answer>"
+  state resolve --human --drop <qid> ["<reason>"]
+  state resolve --human --batch <file>
   state merge-manifest <slug> [<predecessor>...]
   state close <slug>
 `
@@ -79,7 +83,7 @@ const (
 	detectUsageLine     = "usage: devrites-engine detect commands [--root <dir>] [--json]"
 	windowsUsageLine    = "usage: devrites-engine check windows <slug> [--worktree|--staged|--base <ref>] [--cwd <dir>]"
 	dupUsageLine        = "usage: devrites-engine check dup [slug] [--all|--worktree|--staged|--base <ref>] [--min-lines n] [--threshold f] [--ignore-file <path>] [--limit n] [--exclude <csv>] [--phase p] [--cwd <dir>]"
-	resolveUsage        = `usage: devrites-engine state resolve <qid> "<answer>"  |  state resolve --drop <qid> ["<reason>"]  |  state resolve --batch <file>`
+	resolveUsage        = `usage: devrites-engine state resolve <qid> "<answer>"  |  state resolve --drop <qid> ["<reason>"]  |  state resolve --batch <file>  |  state resolve --human <qid> "<answer>"  |  state resolve --human --drop <qid> ["<reason>"]  |  state resolve --human --batch <file>`
 	mergeManifestUsage  = "usage: devrites-engine state merge-manifest <slug> [<predecessor>...]"
 	closeUsage          = "usage: devrites-engine state close <slug>"
 	observeSliceUsage   = "usage: devrites-engine observe slice <slug> <SLICE-ID>"
@@ -93,14 +97,6 @@ const (
   gates lint <slug> [--strict]     Audit oracle quality without executing
   gates attest <slug> <id> <note>  Record human evidence on a manual gate
   gates abandon <slug> <id> <why>  Record a terminal ABANDON handoff on a gate
-`
-	noteFamilyUsage = `usage: devrites-engine note <add|list|check|rm> <slug> ...
-
-  note add <slug> <subject> <quote> <title> [body]
-                                  Anchor a workspace note to verbatim code text
-  note list <slug>                List notes.md entries with their current grade
-  note check <slug> [--repair]    Regrade every anchor; --repair rewrites moved subjects
-  note rm <slug> <NOTE-id>        Remove a note
 `
 )
 
@@ -117,11 +113,41 @@ func isHelpToken(arg string) bool {
 	return isHelpFlag(arg) || arg == "help"
 }
 
-func hasHelpFlag(args []string) bool {
-	for _, arg := range args {
-		if isHelpFlag(arg) {
+// takesSubcommand reports whether command's first argument names a subcommand.
+// A subcommand is consumed by dispatch, so a help flag directly after it is
+// still in flag position rather than in a value position.
+func takesSubcommand(command string) bool {
+	switch command {
+	case "check", "state", "observe", "parallel", "gates", "claim", "note", "metrics", "detect", "overhaul":
+		return true
+	default:
+		return false
+	}
+}
+
+// claimValueFlags are the claim flags that consume the next argument as a value.
+var claimValueFlags = map[string]bool{"--session": true, "--reason": true, "--ttl": true, "--id": true}
+
+// hasHelpFlag reports whether args (the arguments after the command word) are a
+// help request. The command path is consumed by dispatch, so a help flag is
+// honoured among the leading flags that follow it. The scan stops at the first
+// argument that does not start with a dash, because from there the engine
+// cannot tell a flag from a value or operand. Only claim, whose value flags are
+// known, honours a help flag later, and never one that is the value of such a
+// flag.
+func hasHelpFlag(command string, args []string) bool {
+	if len(args) > 0 && !strings.HasPrefix(args[0], "-") && takesSubcommand(command) {
+		args = args[1:]
+	}
+	for i := 0; i < len(args); i++ {
+		if isHelpFlag(args[i]) {
 			return true
 		}
+		if command == "claim" && claimValueFlags[args[i]] {
+			i++
+		} else if command != "claim" && !strings.HasPrefix(args[i], "-") {
+			return false
+		}
 	}
 	return false
 }
@@ -133,11 +159,11 @@ func shouldPrintHelp(args []string) bool {
 	if isHelpToken(args[0]) {
 		return true
 	}
-	if hasHelpFlag(args) {
+	if hasHelpFlag(args[0], args[1:]) {
 		return true
 	}
 	switch args[0] {
-	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate", "overhaul":
+	case "check", "state", "observe", "parallel", "gates", "claim", "detect", "note", "metrics", "handoff", "context", "orient", "migrate", "overhaul", "next", "dispatch", "secret-scan", "open-visual":
 		return len(args) >= 2 && args[1] == "help"
 	default:
 		return false
@@ -194,7 +220,7 @@ func commandHelp(args []string) (string, bool) {
 	case "gates":
 		return gatesFamilyUsage, true
 	case "note":
-		return noteFamilyUsage, true
+		return notes.Usage, true
 	case "overhaul":
 		return overhaul.Usage, true
 	case "migrate":

package/engine/help_test.go

@@ -2,8 +2,12 @@ package main
 
 import (
 	"bytes"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/devrites/devrites/internal/notes"
 )
 
 func TestCommandHelp(t *testing.T) {
@@ -42,6 +46,10 @@ func TestCommandHelp(t *testing.T) {
 		{args: []string{"observe", "slice", "--help"}, want: "observe slice <slug> <SLICE-ID>"},
 		{args: []string{"orient", "--help"}, want: "orient [slug]"},
 		{args: []string{"handoff", "--help"}, want: "handoff [slug]"},
+		{args: []string{"next", "help"}, want: "devrites-engine next [slug]"},
+		{args: []string{"dispatch", "help"}, want: "devrites-engine dispatch <slug>"},
+		{args: []string{"secret-scan", "help"}, want: "secret-scan [--staged] [--stdin]"},
+		{args: []string{"open-visual", "help"}, want: "open-visual <path-or-name>"},
 		{args: []string{"claim", "--help"}, want: "claim <add|release|list|check>"},
 		{args: []string{"claim", "help"}, want: "claim <add|release|list|check>"},
 		{args: []string{"migrate", "--help"}, want: "migrate <slug>"},
@@ -104,3 +112,129 @@ func TestUnknownCommandHelpStillUnknown(t *testing.T) {
 		t.Fatalf("stderr = %q, want unknown-command diagnostic", stderr.String())
 	}
 }
+
+func TestHelpTokenInValuePositionDoesNotShortCircuit(t *testing.T) {
+	for _, quote := range []string{"maxConns = 4", "--help", "-h", "-help"} {
+		t.Run(quote, func(t *testing.T) {
+			project, _ := noteWorkspace(t)
+			writeBasenameFile(t, project, "pool.go", "package src\n\n// flags: --help -h -help\nconst maxConns = 4\n")
+			var stdout, stderr bytes.Buffer
+			args := []string{"note", "add", "feature", "pool.go", quote, "some title"}
+			code := run(args, strings.NewReader(""), &stdout, &stderr)
+			notes := filepath.Join(project, ".devrites", "work", "feature", "notes.md")
+			if _, err := os.Stat(notes); err != nil {
+				t.Fatalf("notes.md absent (code=%d stdout=%.80q stderr=%q)", code, stdout.String(), stderr.String())
+			}
+			if code != exitOK || !strings.Contains(stdout.String(), "added: NOTE-001") {
+				t.Fatalf("code=%d stdout=%q", code, stdout.String())
+			}
+		})
+	}
+	for _, args := range [][]string{{"note", "add", "--help"}, {"note", "--help"}, {"check", "seal", "--help"}} {
+		var stdout, stderr bytes.Buffer
+		if code := run(args, strings.NewReader(""), &stdout, &stderr); code != exitOK || !strings.Contains(stdout.String(), "usage") && !strings.Contains(stdout.String(), "Usage") {
+			t.Fatalf("%v code=%d stdout=%.80q", args, code, stdout.String())
+		}
+	}
+}
+
+func TestHelpTokenAsFlagValueOrOperandIsNotHelp(t *testing.T) {
+	for _, tok := range []string{"--help", "-h", "-help"} {
+		_, root := noteWorkspace(t)
+		var stdout, stderr bytes.Buffer
+		code := run([]string{"claim", "add", "--reason", tok, "--session", "s1", "src/a.go"}, strings.NewReader(""), &stdout, &stderr)
+		if _, err := os.Stat(filepath.Join(root, "claims.jsonl")); err != nil || code != exitOK {
+			t.Fatalf("reason=%s: code=%d claims absent (%v) stdout=%.60q", tok, code, err, stdout.String())
+		}
+		_, root = noteWorkspace(t)
+		stdout.Reset()
+		code = run([]string{"claim", "add", "--session", "s1", "src/a.go", tok}, strings.NewReader(""), &stdout, &stderr)
+		if _, err := os.Stat(filepath.Join(root, "claims.jsonl")); err == nil {
+			t.Fatalf("trailing %s wrote a claim", tok)
+		}
+		if code != exitOK || !strings.Contains(stdout.String(), "claim") {
+			t.Fatalf("trailing %s code=%d stdout=%.60q", tok, code, stdout.String())
+		}
+	}
+	_, root := noteWorkspace(t)
+	var stdout, stderr bytes.Buffer
+	if code := run([]string{"claim", "add", "--reason", "ordinary", "--session", "s1", "src/a.go"}, strings.NewReader(""), &stdout, &stderr); code != exitOK {
+		t.Fatalf("control code=%d", code)
+	}
+	if _, err := os.Stat(filepath.Join(root, "claims.jsonl")); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestHelpFlagAfterOtherFlagsPrintsHelp(t *testing.T) {
+	t.Setenv("DEVRITES_ROOT", "")
+	for _, test := range []struct {
+		args []string
+		want string
+	}{
+		{[]string{"secret-scan", "--staged", "--help"}, "secret-scan [--staged] [--stdin]"},
+		{[]string{"secret-scan", "--staged", "--stdin", "-h"}, "secret-scan [--staged] [--stdin]"},
+		{[]string{"check", "indexes", "--json", "-help"}, "check indexes [--root <dir>]"},
+		{[]string{"parallel", "create", "--json", "--help"}, "parallel create"},
+	} {
+		var stdout, stderr bytes.Buffer
+		code := run(test.args, strings.NewReader(""), &stdout, &stderr)
+		if code != exitOK || stderr.Len() != 0 || !strings.Contains(stdout.String(), test.want) {
+			t.Fatalf("run(%q) code=%d stdout=%.80q stderr=%q", test.args, code, stdout.String(), stderr.String())
+		}
+	}
+}
+
+func TestUsageListsRuntimeFailureExit(t *testing.T) {
+	if !strings.Contains(usage, "\n  1  runtime/I/O failure\n") {
+		t.Fatalf("usage Exit codes block omits exit 1:\n%s", usage)
+	}
+}
+
+func TestCLIDocsStateCloseExitCodes(t *testing.T) {
+	data, err := os.ReadFile(filepath.Join("..", "docs", "cli.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc := string(data)
+	for _, want := range []string{
+		"`state close` exits `4` for usage or a missing workspace",
+		"`3` for a schema refusal",
+		"`5` when an archive already exists",
+		"`1` for an invalid workspace, archive directory, or ACTIVE cursor",
+	} {
+		if !strings.Contains(doc, want) {
+			t.Errorf("docs/cli.md omits %q", want)
+		}
+	}
+}
+
+func TestNoteHelpAndErrorPathShareLegendAndExitCodes(t *testing.T) {
+	const grades = "Grades: exact | moved | stale | ambiguous | lost"
+	const exits = "Exit codes: 0 ok, 2 usage, 3 blocked"
+	for _, args := range [][]string{
+		{"note", "--help"},
+		{"note", "help"},
+		{"note", "add", "--help"},
+	} {
+		var stdout, stderr bytes.Buffer
+		code := run(args, strings.NewReader(""), &stdout, &stderr)
+		if code != exitOK || stderr.Len() != 0 {
+			t.Fatalf("run(%q) code=%d stderr=%q", args, code, stderr.String())
+		}
+		for _, want := range []string{grades, exits} {
+			if !strings.Contains(stdout.String(), want) {
+				t.Errorf("run(%q) help omits %q:\n%s", args, want, stdout.String())
+			}
+		}
+	}
+	var stdout, stderr bytes.Buffer
+	if code := notes.Run(t.TempDir(), nil, &stdout, &stderr); code != notes.ExitUsage {
+		t.Fatalf("notes.Run with no args = %d, want usage", code)
+	}
+	for _, want := range []string{grades, exits} {
+		if !strings.Contains(stderr.String(), want) {
+			t.Errorf("note usage error omits %q:\n%s", want, stderr.String())
+		}
+	}
+}