devrites 5.14.4 → 6.0.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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`.
 
+## [6.0.0](https://github.com/ViktorsBaikers/DevRites/compare/v5.14.4...v6.0.0) (2026-10-10)
+
+### ⚠ BREAKING CHANGES
+
+* **repo:** install.sh and `npx devrites` verify the release's
+  build-provenance attestation with `gh` and refuse to install when `gh`
+  is missing or verification fails; `npx devrites` uses a devrites-engine
+  found on PATH only when its version matches the release; the npm
+  package no longer runs a prepack script and ships the committed
+  pack/generated; frontmatter validation requires PyYAML; overhaul
+  records reject malformed task ids; the engine toolchain is go1.27.2.
+
+### Fixed
+
+* **no-release:** keep spec-phase gate verdicts out of spec.md ([#98](https://github.com/ViktorsBaikers/DevRites/issues/98)) ([5c62af3](https://github.com/ViktorsBaikers/DevRites/commit/5c62af3993945adc6d8035c86a7cf8436e696ebb))
+* **repo:** apply verified audit repairs across engine, pack and tests ([#99](https://github.com/ViktorsBaikers/DevRites/issues/99)) ([f056b5e](https://github.com/ViktorsBaikers/DevRites/commit/f056b5e76d276e57e469ac288efd16c91d3fd7b1))
+
 ## [5.14.4](https://github.com/ViktorsBaikers/DevRites/compare/v5.14.3...v5.14.4) (2026-10-03)
 
 ### Fixed

package/NOTICE.md

@@ -13,10 +13,12 @@ distributing it, distributing modified versions, or commercial/organizational us
 requires **approval on request**. See [`LICENSE`](LICENSE).
 
 ## Host runtimes
-DevRites integrates with **Claude Code** and **Codex** and follows each host's
-project-local skill, agent, and instruction conventions. "Claude" and "Claude
-Code" are products of Anthropic; "Codex" is a product of OpenAI. DevRites is
-independent and unaffiliated with Anthropic and OpenAI.
+DevRites integrates with **Claude Code**, **Codex**, **omp**, **pi**, and
+**Devin CLI** and follows each host's project-local skill, agent, and instruction
+conventions. "Claude" and "Claude Code" are products of Anthropic; "Codex" is a
+product of OpenAI; omp, pi, and Devin CLI are products of their respective
+owners. DevRites is independent of, and not affiliated with or endorsed by, any
+of these hosts or their makers.
 
 ## Framework identifiers
 

package/README.md

@@ -31,7 +31,7 @@ history can't lose it. After you clear the conversation, switch hosts, or hand
 the feature to another engineer, the next session reads the same plan,
 decisions, and evidence before it continues.
 
-**Status:** [`v5.14.4`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v5.14.4): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v6.0.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v6.0.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 
@@ -47,7 +47,15 @@ This is the latest published release; `main` may contain unreleased work.
 
 ## Quick start
 
-**1. Install** from the root of your project. Node.js 18 or later is required.
+**1. Install** from the root of your project. Node.js 18 or later is required to
+install and run DevRites. Development in this repository (`npm ci`, which
+`.npmrc` runs with `engine-strict=true`) needs Node.js 22.22.2 or later within
+22.x, or 24.15 or later; Node 23.x and 24.0 through 24.14 fail with `EBADENGINE`.
+`gh` (GitHub CLI) must also be installed and authenticated, not merely
+installed, because DevRites verifies the build-provenance attestation of every
+release asset it downloads. Run `gh auth login` once, then `gh auth status` to
+confirm. See [Install, update, and remove](#install-update-and-remove) for
+which routes fail without it and which fall back to a local build.
 
 ```bash
 npx devrites@latest
@@ -307,20 +315,22 @@ Run `npx devrites@latest --help` for common flags and
 <br>
 
 Download the release-owned installer and its checksum before executing it. It
-needs `curl`, `gzip`, and `tar`.
+needs `curl`, `gzip`, and `tar`, plus `gh` (GitHub CLI) installed and
+authenticated (`gh auth login`).
 
 ```bash
 bootstrap_dir="$(mktemp -d)"
+project_dir="$PWD"
 (
   set -e
   trap 'rm -rf "$bootstrap_dir"' EXIT HUP INT TERM
   cd "$bootstrap_dir"
   release=https://github.com/ViktorsBaikers/DevRites/releases/latest/download
-  curl -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 60 --max-filesize 1048576 "$release/install.sh" | head -c 1048577 > install.sh
+  curl -q -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 60 --max-filesize 1048576 "$release/install.sh" | head -c 1048577 > install.sh
   install_status="${PIPESTATUS[0]}"
   [ "$(wc -c < install.sh)" -le 1048576 ] || { echo 'error: install.sh exceeds 1 MiB' >&2; exit 1; }
   [ "$install_status" -eq 0 ] || { echo 'error: install.sh download failed' >&2; exit 1; }
-  curl -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 30 --max-filesize 4096 "$release/install.sh.sha256" | head -c 4097 > install.sh.sha256
+  curl -q -fL --proto '=https' --proto-redir '=https' --connect-timeout 10 --max-time 30 --max-filesize 4096 "$release/install.sh.sha256" | head -c 4097 > install.sh.sha256
   sidecar_status="${PIPESTATUS[0]}"
   [ "$(wc -c < install.sh.sha256)" -le 4096 ] || { echo 'error: install.sh.sha256 exceeds 4 KiB' >&2; exit 1; }
   [ "$sidecar_status" -eq 0 ] || { echo 'error: install.sh.sha256 download failed' >&2; exit 1; }
@@ -339,13 +349,14 @@ bootstrap_dir="$(mktemp -d)"
     exit 1
   fi
   [ "$got" = "$want" ] || { echo 'error: install.sh checksum mismatch' >&2; exit 1; }
+  command -v gh >/dev/null 2>&1 || { echo 'error: gh (GitHub CLI) is required and was not found' >&2; exit 1; }
+  gh attestation verify install.sh --repo ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main || { if gh auth status >/dev/null 2>&1; then echo 'error: install.sh attestation verification failed: no build provenance from ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main' >&2; else echo 'error: gh is not authenticated; run gh auth login' >&2; fi; exit 1; }
 
   # Choose one Node-free operation:
-  bash ./install.sh                         # install here
-  # bash ./install.sh --target /path/to/project
-  # bash ./install.sh --dry-run
-  # bash ./install.sh update
-  # bash ./install.sh uninstall
+  bash ./install.sh --target "$project_dir"  # install into the directory you ran this from
+  # bash ./install.sh --dry-run --target "$project_dir"
+  # bash ./install.sh update --target "$project_dir"
+  # bash ./install.sh uninstall --target "$project_dir"
 )
 ```
 
@@ -392,14 +403,59 @@ proof. `devrites-engine migrate` owns deterministic v5 schema normalization.
 See the [CLI contract](docs/cli.md) and
 [ADR-0029](docs/adr/0029-v5-workspace-schema-and-native-migration.md).
 
+Every release asset is verified with `gh attestation verify` before it is
+decompressed, extracted, or executed, so `gh` must be installed and
+authenticated (`gh auth login`). Without that, the Bash bootstrap (`install.sh`
+fetched with `curl`) and `devrites-engine update` are fatal: they stop with no
+fallback. `npx devrites@latest` instead falls back to compiling the shipped
+`engine/` with `go build` when Go is installed, and the engine acquisition in
+`scripts/install-lib.sh` (used by `install.sh` from a clone or an extracted
+bundle) has its own fallback of the same kind.
+
 Release binaries and installers ship with SHA-256 sidecars and
-build-provenance attestations. Verify a download with
-`shasum -a 256 -c <file>.sha256` or
-`gh attestation verify <file> -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`.
+build-provenance attestations. Verify a download with both
+`shasum -a 256 -c <file>.sha256` and
+`gh attestation verify <file> -R ViktorsBaikers/DevRites --signer-workflow ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`
+before it runs; the checksum alone is not enough (see the verified Bash
+bootstrap above).
 Pin the signer workflow, because valid provenance shows where a build ran
 but does not show that the intended publishing step produced it. See
 [docs/release.md](docs/release.md).
 
+Read a failure as "prove provenance or stop", not as a verdict about your
+build. The bootstrap checks `gh` itself, exits 1 before `install.sh` runs, and
+prints the cause. It says `error: gh (GitHub CLI) is required and was not
+found` when `gh` is absent. When `gh` is present but logged out (`gh auth
+status` fails) it says `error: gh is not authenticated; run gh auth login`.
+Only when `gh` is logged in and still rejects the attestation does it say
+`error: install.sh attestation verification failed: no build provenance from
+ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`. After that,
+`install.sh` verifies the release bundle `devrites-<tag>.tar.gz` and reports the
+same three causes as `attestation verification failed: gh (GitHub CLI) is
+required and was not found`, `attestation verification failed: gh is not
+authenticated ...; run 'gh auth login' and retry`, and `attestation verification
+failed: no build provenance from <signer>`. The engine binary is acquired
+separately: the bundled installer (`scripts/install-lib.sh`) and the npm route
+report `attestation verification failed (gh must be installed and
+authenticated)` for any of these causes, discard the downloaded binary, and
+fall back to other sources. The bundled installer builds from the bundle's
+`engine/` source when `go` is available, then tries an already-installed
+`devrites-engine`, and only when none works does `install.sh` exit 1 with
+`could not acquire devrites-engine` followed by that cause. `npx devrites@latest` repeats the combined message
+before exiting 127 when no other engine is available. `devrites-engine update` reports `gh (GitHub CLI) is
+required and must be authenticated for attestation verification` when `gh` is
+absent, and `attestation verification failed for <asset>` whenever a present
+`gh` rejects the asset, logged out or not.
+
+There is no flag to skip, disable, or bypass attestation verification. The
+`.sha256` sidecar is fetched from the same origin as the artifact, so a
+substituted origin supplies a digest that matches its own payload, which is why
+the sidecar is a corruption check and not a provenance one. If you cannot run
+`gh auth login`, install Go and use `npx devrites@latest`, or clone this
+repository and run `bash install.sh`: both compile `engine/` locally when the
+download is refused, with `cd engine && go build -o devrites-engine .` as the
+manual equivalent.
+
 </details>
 
 ## Hosts
@@ -412,8 +468,10 @@ but does not show that the intended publishing step produced it. See
 | **pi** | `.pi/skills/` | `.pi/agents/` | Prompt commands in `.pi/prompts/`, marked block in `AGENTS.md` | `/rite-spec` or `/skill:rite-spec` |
 | **Devin CLI** | `.devin/skills/` | `.devin/agents/` | Marked block in `AGENTS.md` | `/rite-spec` |
 
-On every host, `devrites-slice-wright` is the only writable specialist, and
-every other specialist is read-only and hook-free. Existing
+On every host, among the lifecycle `devrites-*` specialists only
+`devrites-slice-wright` is writable and the rest are read-only and hook-free;
+the shipped profiles are the full role-to-permission map, and `/rite-doctor`
+step 3 checks them. Existing
 settings and user content stay in place. On Devin CLI, dispatch goes through
 `run_subagent` with the exact `devrites-<role>` profile, and a missing profile
 stops for HITL instead of substituting `subagent_general`. Profiles load when a
@@ -470,7 +528,10 @@ traces. DevRites detects these tools but does not install them.
 - Installed host artifacts stay in the project. Use `--no-binary` or
   `DEVRITES_NO_BINARY=1` to avoid keeping a shared binary outside it.
 - npm, Bash, and `devrites-engine update` all require checksummed release
-  assets. Remote fetches use HTTPS at every redirect hop, are bounded in size,
+  assets that also pass `gh attestation verify`, pinned to
+  `ViktorsBaikers/DevRites` and signer workflow
+  `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main` (see
+  [Install, update, and remove](#install-update-and-remove)). Remote fetches use HTTPS at every redirect hop, are bounded in size,
   and never fall back to an unchecked raw file, source archive, tag, or default
   branch.
 - Install, update, and uninstall do not inspect target-project Git. Retained

package/SECURITY.md

@@ -15,7 +15,7 @@ Please include:
 - A clear description of the vulnerability and its impact.
 - A minimal reproduction (commands, files, or a target project layout).
 - The DevRites version (commit SHA or release tag), affected host, and host
-  version (Claude Code or Codex).
+  version (Claude Code, Codex, omp, pi, or Devin CLI).
 - Your name / handle for credit (optional).
 
 You should receive an acknowledgement within **5 business days** and a triage
@@ -119,17 +119,23 @@ and `.codex/config.toml` without replacing unrelated user settings. The shared
 `devrites-engine` executable is the only allowed artifact outside the project.
 It is installed to `DEVRITES_BIN_DIR`, a writable `~/.local/bin`, or a writable
 `/usr/local/bin`; `--no-binary` / `DEVRITES_NO_BINARY=1` skips it. The bootstrap
-and direct updater may fetch the release bundle and checksummed engine assets.
+and direct updater may fetch the release bundle and checksummed engine assets,
+each of which must also pass `gh attestation verify` (pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`).
 They never invoke `sudo` or edit shell startup files.
 
 The documented Node-free boundary downloads the release-owned `install.sh` and
-its exact-name sidecar before execution; mutable default-branch scripts are not
-recommended. Legacy local and extracted shim invocations remain compatible, but
+its exact-name sidecar, then requires both the checksum and the build-provenance
+attestation (`gh attestation verify`, pinned to `ViktorsBaikers/DevRites` and
+signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`)
+to pass before execution, as in the README "verified Bash bootstrap"; mutable
+default-branch scripts are not recommended. Legacy local and extracted shim invocations remain compatible, but
 their exact-release guarantee begins at that verified asset. A piped shim never
 treats current-directory siblings as its bundle.
 
 Network acquisition accepts only an exact SemVer release asset and its mandatory
-exact-filename SHA-256 sidecar. Every redirect hop must remain HTTPS, private
+exact-filename SHA-256 sidecar, and every release 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). Every redirect hop must remain HTTPS, private
 temporary-directory creation must succeed, and unchecked raw/source/default-
 branch fallbacks are absent. Representative in-stream ceilings are 1 MiB for
 release metadata, 4 KiB for a sidecar, and 64 MiB for an archive or binary, with
@@ -148,8 +154,9 @@ and [ADR-0028](docs/adr/0028-self-contained-engine-update.md) own the rationale.
 With `npx devrites@latest`, the CLI (`bin/devrites.mjs`) calls
 `devrites-engine` directly instead of running `install.sh`. The bundled host
 payload is pinned to the requested npm package version. The shim first tries the
-matching exact-release binary and its mandatory SHA-256 sidecar, then a
-package-local Go build, and then an existing engine. Remote responses are
+matching exact-release binary, which must pass its mandatory SHA-256 sidecar and
+`gh attestation verify` (pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`),
+then a package-local Go build, and then an existing engine. Remote responses are
 byte-bounded and every redirect is checked before following it. It has no
 runtime npm dependencies. The same project and shared-binary boundaries apply
 to the Bash installer.
@@ -180,11 +187,17 @@ separate type-`GO` workflow gate still applies.
 Reviewer profiles are natively read-only. Claude keeps the root in project plan
 mode. Codex uses a workspace-capable root because a child cannot elevate above
 its parent; root source/test non-writing is therefore a workflow rule, not a
-Codex sandbox guarantee. On both hosts, `devrites-slice-wright` is the only
-writable specialist. Its task states the exact project-relative paths. The root
+Codex sandbox guarantee. Among the lifecycle `devrites-*` specialists,
+`devrites-slice-wright` is the only writable one on either host; the shipped
+profiles are the full role-to-permission map, and `/rite-doctor` step 3 checks
+them. Its task states the exact project-relative paths. The root
 waits, compares the returned file list and `git diff --name-only` with that
 contract, and rejects out-of-scope work. Exact-path scope is instruction-backed,
 not a per-task filesystem allowlist.
+The standalone explicit skills ship their own writers: the `overhaul-*` agents
+(ADR-0031) and `fast-builder` (ADR-0033) are write-capable (Codex `:workspace`,
+Claude edit-capable); they run only when the user explicitly invokes /overhaul
+or /rite-fast.
 Agent lifecycle, session history, compaction, presentation, browsing, indexes,
 and irreversible-action approval remain native host responsibilities.
 
@@ -200,8 +213,9 @@ Unrelated Git variables are preserved. Go and shell parity is covered by
 ### Third-party trust
 
 DevRites vendors no third-party code (see `NOTICE.md`). It runs through the
-external Claude Code or Codex host selected by the user and is independent of
-Anthropic and OpenAI. Codegraph, graphify, and Playwright MCP are optional
+external host selected by the user (Claude Code, Codex, omp, pi, or Devin CLI)
+and is independent of, and not affiliated with or endorsed by, any of these
+hosts or their makers. Codegraph, graphify, and Playwright MCP are optional
 user-selected tools that DevRites calls through their documented interfaces
 rather than bundling them.
 

package/bin/devrites.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 // devrites - npx entry point for the engine-owned DevRites installer.
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { chmodSync, createReadStream, existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { open } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import { constants as osConstants, tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -16,6 +16,7 @@ const MAX_REDIRECTS = 5;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const temporaryDirs = new Set();
 let acquisitionFailure = null;
+let engineChild = null;
 
 class DownloadError extends Error {}
 
@@ -31,6 +32,9 @@ function cleanupTemporaryDirs() {
 }
 
 process.on('exit', cleanupTemporaryDirs);
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => (engineChild ? engineChild.kill(signal) : process.exit(128 + osConstants.signals[signal])));
+}
 
 const SUBCOMMAND_ALIASES = new Map([
   ['install', 'install'],
@@ -81,15 +85,26 @@ function run(command, args, options = {}) {
   return spawnSync(command, args, { stdio: options.stdio || 'inherit', cwd: options.cwd || process.cwd(), env: options.env || process.env });
 }
 
-function firstWorking(candidates, args, env = process.env) {
-  let lastError = null;
-  for (const candidate of candidates.filter(Boolean)) {
-    const res = run(candidate, args, { env });
-    if (!res.error) process.exit(res.status === null ? 1 : res.status);
-    lastError = res.error;
-    if (res.error.code !== 'ENOENT') break;
-  }
-  return lastError;
+function runEngine(command, args, env) {
+  return new Promise((resolve) => {
+    let launchFailed = false;
+    const failLaunch = (error) => {
+      launchFailed = true;
+      engineChild = null;
+      resolve(error);
+    };
+    try {
+      engineChild = spawn(command, args, { stdio: 'inherit', env });
+    } catch (error) {
+      error.message = `${error.message} ${command}`;
+      failLaunch(error);
+      return;
+    }
+    engineChild.once('error', failLaunch);
+    engineChild.once('close', (code, signal) => {
+      if (!launchFailed) process.exit(signal ? 128 + osConstants.signals[signal] : code);
+    });
+  });
 }
 
 async function acquireEngine() {
@@ -98,6 +113,7 @@ async function acquireEngine() {
   if (!validRepository(repo) || !tag) throw new Error('DevRites repository and release tag must identify an exact release');
   const envEngine = process.env.DEVRITES_ENGINE_CLI || process.env.DEVRITES_CLI;
   if (envEngine && existsSync(envEngine)) return envEngine;
+  if (command === 'uninstall' && spawnSync('devrites-engine', ['uninstall', '-h'], { stdio: 'ignore' }).status === 0) return 'devrites-engine';
 
   const downloaded = await downloadEngine();
   if (downloaded) return downloaded;
@@ -121,7 +137,10 @@ async function acquireEngine() {
     }
   }
 
-  return 'devrites-engine';
+  if (command === 'uninstall') return 'devrites-engine';
+  const probe = spawnSync('devrites-engine', ['version'], { encoding: 'utf8' });
+  if (!probe.error && probe.status === 0 && String(probe.stdout).trim().replace(/^v/, '') === tag.slice(1)) return 'devrites-engine';
+  return null;
 }
 
 function findGo() {
@@ -171,6 +190,14 @@ async function downloadEngine() {
     rmSync(`${out}.sha256`, { force: true });
     return null;
   }
+  const signer = `${repo}/.github/workflows/ci.yml@refs/heads/main`;
+  const attestation = spawnSync('gh', ['attestation', 'verify', out, '--repo', repo, '--signer-workflow', signer], { stdio: 'ignore', timeout: 120_000 });
+  if (attestation.error || attestation.status !== 0) {
+    acquisitionFailure = `release ${tag} asset ${name}: attestation verification failed (gh must be installed and authenticated)`;
+    rmSync(out, { force: true });
+    rmSync(`${out}.sha256`, { force: true });
+    return null;
+  }
   try {
     chmodSync(out, 0o755);
   } catch {
@@ -282,6 +309,10 @@ try {
   console.error(`devrites: ${error.message}`);
   process.exit(1);
 }
+if (!engine) {
+  console.error(`devrites: devrites-engine was not found and could not be acquired${acquisitionFailure ? ` (${acquisitionFailure})` : ''}.`);
+  process.exit(127);
+}
 const payloadDir = process.env.DEVRITES_HOST_ARTIFACT_DIR || join(root, 'pack', 'generated');
 const installerCommand = command === 'install' || command === 'update' || command === 'uninstall';
 const engineEnv = { ...process.env, DEVRITES_ENGINE_CLI: engine };
@@ -294,9 +325,12 @@ if (command === 'install' || command === 'update') {
 }
 args.push(...rest);
 
-const candidates = [engine, 'devrites-engine'];
-const lastError = firstWorking(candidates, args, engineEnv);
-if (lastError && lastError.code !== 'ENOENT') {
+let lastError = null;
+for (const candidate of [engine, 'devrites-engine']) {
+  lastError = await runEngine(candidate, args, engineEnv);
+  if (lastError.code !== 'ENOENT') break;
+}
+if (lastError.code !== 'ENOENT') {
   console.error('devrites: failed to launch devrites-engine:', lastError.message);
 } else {
   console.error(`devrites: devrites-engine was not found and could not be acquired${acquisitionFailure ? ` (${acquisitionFailure})` : ''}.`);

package/docs/adr/0001-go-engine-as-control-plane.md

@@ -3,9 +3,12 @@
 - **Status:** Accepted
 - **Date:** 2026-07-08 (backfilled; decision predates the ADR log)
 
-> Network scope was narrowed by [ADR-0008](0008-sanctioned-engine-network-boundary.md):
-> deterministic workspace operations remain network-free, while explicit
-> updater/source-cache I/O is isolated in `internal/iohooks`.
+> Network scope was narrowed by [ADR-0008](0008-sanctioned-engine-network-boundary.md),
+> whose engine network allowance was superseded by
+> [ADR-0024](0024-native-policy-offline-installer-boundary.md) and then reintroduced
+> for release acquisition only, confined to `engine/internal/release`, by
+> [ADR-0028](0028-self-contained-engine-update.md). Deterministic workspace
+> operations remain network-free.
 
 ## Context
 

package/docs/adr/0029-v5-workspace-schema-and-native-migration.md

@@ -60,3 +60,12 @@ by the v5 pack declare the row at creation.
 
 Guard tests: `engine/internal/state/workspaceschema_test.go`,
 `engine/tests/parity_resolve_test.go`, `engine/tests/parity_closeout_test.go`.
+
+## Amendment (2026-10-06)
+
+The Context section's "the current contract is schema 3" records the contract at
+adoption. `state.SchemaVersion` is now 4: schema 4 adds the `gates.md`
+acceptance ledger to the vetted artifact set (`engine/internal/state/schema.go`).
+The decision above is unchanged — the engine declares the current workspace
+schema, `state resolve` and `state close` refuse mismatched workspaces, and
+`devrites-engine migrate` performs fail-closed normalization.

package/docs/adr/README.md

@@ -47,13 +47,13 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | ADR | Title | Status | Guard test |
 |-----|-------|--------|-----------|
 | [0001](0001-go-engine-as-control-plane.md) | Go engine as deterministic control plane | Accepted in part; all-state-transition/derivation scope superseded by 0024 | none |
-| [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted | `engine/tests/parity_*_test.go` |
+| [0002](0002-dual-host-harness.md) | Dual-host harness (Claude + Codex) | Accepted in part; the `internal/harness` adapter and `harness-matrix` mechanism no longer exist, and the two-host count is superseded by the five host packs under `pack/generated/` (claude, codex, omp, pi, devin) | historical |
 | [0003](0003-gate-model-hitl-pause.md) | Gates block as HITL pause, never crash | Accepted | `engine/tests/adr_0003_gate_exit_code_test.go` |
 | [0004](0004-state-schema-phases-sections.md) | Phase-relative section completeness | Accepted | `engine/tests/adr_0004_required_by_phase_test.go`, `engine/internal/state/state_test.go` |
 | [0005](0005-hooks-as-engine-subcommands.md) | Hooks are engine subcommands, not shell scripts | Accepted; active hook clause superseded by 0018 | historical |
 | [0006](0006-clock-seam-and-engine-ci-gates.md) | Clock seam + Go static-analysis CI gates | Accepted in part; next-qid seam/guard superseded by 0024, CI analyzer wiring superseded by 0032 | historical |
 | [0007](0007-canonical-live-workspace-filenames.md) | Canonical live workspace filenames | Accepted; unsupported alias/migration clauses superseded by 0022 | `engine/internal/state/state_test.go`, `engine/internal/lib/cursor_compat_test.go` |
-| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted in part; engine network allowance superseded by 0024 | `engine/tests/meta_test.go` |
+| [0008](0008-sanctioned-engine-network-boundary.md) | Sanctioned engine network boundary | Accepted in part; engine network allowance superseded by 0024, then reintroduced for release acquisition in `engine/internal/release` by 0028 | `engine/tests/meta_test.go` |
 | [0009](0009-prebuild-decision-coverage-and-readiness.md) | Pre-build decision coverage and implementation readiness | Accepted; semantic engine-gate implementation superseded by 0022 | historical |
 | [0010](0010-agent-first-fresh-context-orchestration.md) | Agent-first fresh-context orchestration | Accepted | `tests/native-orchestration-contract-test.sh`, `tests/codex-agent-generation-test.sh` |
 | [0011](0011-define-plan-transition-rights.md) | Separate Define authoring from the Plan checkpoint | Accepted | `engine/internal/state/state_test.go`, `engine/tests/adr_0011_define_plan_test.go` |
@@ -75,6 +75,7 @@ architecture; per-feature `decisions.md` files stay scoped to that feature.
 | [0027](0027-content-bound-build-readiness.md) | Content-bound build readiness | Accepted; AC ID map amended 2026-09-04 | `engine/tests/adr_0027_readiness_binding_test.go`, `engine/internal/state/acceptance_test.go` |
 | [0028](0028-self-contained-engine-update.md) | Self-contained engine update | Accepted | `engine/internal/install/install_test.go`, `engine/internal/release/release_test.go`, `engine/tests/meta_test.go` |
 | [0029](0029-v5-workspace-schema-and-native-migration.md) | v5 workspace schema and native migration | Accepted | `engine/internal/state/workspaceschema_test.go`, `engine/tests/parity_resolve_test.go`, `engine/tests/parity_closeout_test.go` |
+| 0030 | Reserved number; no ADR is published under it | Unpublished | none |
 | [0031](0031-overhaul-agents-keep-every-tool.md) | `/overhaul` ships its own agents that keep every tool | Accepted; scopes the one-writer clauses of 0010/0015/0017/0018/0019 to `devrites-*` specialists | `scripts/validate-agent-composition.py`, `tests/codex-agent-generation-test.sh` |
 | [0032](0032-single-lint-gate-and-cached-pr-tests.md) | One engine lint gate, and PR tests that reuse main's results | Accepted | `tests/validation-governance-test.sh` |
 | [0033](0033-rite-fast-own-agents.md) | `/rite-fast` ships its own agents and its own writer | Accepted; adds `fast-builder` as a writer outside the `devrites-*` one-writer rule | `scripts/validate-agent-composition.py`, `tests/rite-fast-contract-test.sh` |

package/docs/agents/issue-tracker.md

@@ -11,7 +11,7 @@ Issues and PRDs for this repo live as markdown files in `.scratch/`. For the end
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading
 - An issue discovered while working another records `Found during: NN` (the parent issue number) near the `Status:` line; the discovery trail survives so a later audit can see where it came from
 - Ordering is recorded as optional lines near `Status:`: `Blocked by: NN, NN` (cannot start until those resolve), `Blocks: NN` (this issue gates those), `Relates: NN` (context link, no ordering). A dependency that would create a cycle is flagged and resolved by a human, never silently recorded.
-- An issue is **ready** when its `Status:` is open, every `Blocked by:` target is `resolved`, and nothing has claimed it. Pick work by lowest ready number; a blocked issue is skipped, not partially started. `scripts/issue-ready.sh` computes the ready frontier deterministically (optionally scoped to one feature slug) — use it instead of re-reading every file.
+- An issue is **ready** when its `Status:` is `open` or `ready-for-agent`, every `Blocked by:` target is `resolved`, `done`, `wontfix` or `closed`, and nothing has claimed it. Pick work by lowest ready number; a blocked issue is skipped, not partially started. `scripts/issue-ready.sh` computes the ready frontier deterministically (optionally scoped to one feature slug) — use it instead of re-reading every file.
 
 ## When a skill says "publish to the issue tracker"
 

package/docs/architecture.md

@@ -154,7 +154,8 @@ consume only local source, payload, and binary candidates.
 
 Direct `devrites-engine update` uses the separate `engine/internal/release`
 boundary to resolve the latest stable release and acquire its checksummed bundle
-and platform engine. It then invokes the downloaded engine with local paths, so
+and platform engine, each also checked with `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). It then invokes the downloaded engine with local paths, so
 the candidate validates its own payload schema. `update --check` resolves only
 release metadata and downloads no assets. Engine `--to` and `--pre` selectors do
 not exist.
@@ -163,7 +164,9 @@ The shell entrypoints
 (`bin/devrites.mjs`) remain equivalent acquisition adapters. They acquire and
 verify the exact-release bundle or binary, then pass local paths and user flags
 through to the deterministic engine operation. All network paths require exact SemVer,
-HTTPS-only redirects, exact-filename SHA-256 sidecars, private temporary
+HTTPS-only redirects, exact-filename SHA-256 sidecars, a `gh attestation verify`
+pass for every release asset (pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`;
+see [Install, update, and remove](../README.md#install-update-and-remove)), private temporary
 directories, bounded transfers, and full archive preflight. They provide no
 unchecked raw, source-archive, tag, or default-branch fallback.
 
@@ -216,7 +219,7 @@ never synthesizes a historical pass; ambiguous legacy candidate scope is a gap.
 
 The engine owns deterministic v5 schema normalization (`devrites-engine migrate`),
 not compatibility telemetry. Readers accept official v1/v2 bullet and v3 table
-`state.md` cursors; mutations require the current state schema (v3). Migration
+`state.md` cursors; mutations require the current state schema (v4). Migration
 can create missing artifact stubs, but those stubs prove neither semantic
 readiness nor completed work. Wider pre-release compatibility experiments are
 not runtime contracts. [ADR-0029](adr/0029-v5-workspace-schema-and-native-migration.md)

package/docs/cli.md

@@ -11,7 +11,8 @@ cross-host primitives; it never dispatches an agent or grades reviewer prose.
 `help`, `-h`, `--help`, `version`, and `--version` forms also remain supported.
 Each operational command and subcommand accepts `-h` / `--help` and prints that
 command's usage to stdout (exit 0) without requiring a workspace. Missing
-required arguments still print usage to stderr and exit 2.
+required arguments still print usage to stderr and exit 2, except `state close`,
+which exits 4 (see Output and exits).
 
 ```text
 devrites-engine install [flags]
@@ -48,16 +49,21 @@ devrites-engine gates <subcommand> <slug>
 devrites-engine claim <add|release|list|check>
 devrites-engine note <add|list|check|rm> <slug>
 
-devrites-engine state resolve <qid> "<answer>"
+devrites-engine state resolve [--human] <qid> "<answer>"
 devrites-engine state merge-manifest <slug> [pred...]
 devrites-engine state close <slug>
 devrites-engine migrate <slug> [--dry-run] [--answer id=choice]
 
 devrites-engine secret-scan [--staged] [--stdin] [slug]
 devrites-engine open-visual <path-or-name> [--slug <slug>] [--no-open]
+devrites-engine overhaul <tool> ...
 devrites-engine version
 ```
 
+`overhaul <tool>` provides the run-record, admission, snapshot, scoring,
+benchmark, and view tools used by the `/overhaul` skill; run
+`devrites-engine overhaul --help` for its tools.
+
 Commands outside this operational list and the standard help/version forms are
 unsupported. There are no legacy engine aliases, tombstones, agent-protocol
 versions, semantic-readiness digests, or compatibility telemetry.
@@ -70,8 +76,11 @@ Run `devrites-engine update` in an installed project to resolve the latest
 stable release and update the project pack plus shared engine binary. The
 command downloads the release bundle and platform engine, verifies both exact
 filenames against their SHA-256 sidecars, then hands the extracted candidate to
-the downloaded engine. This avoids asking an old engine to validate a newer
-payload schema.
+the downloaded engine. Each release asset must also pass `gh attestation verify`,
+pinned to `ViktorsBaikers/DevRites` and signer workflow `ViktorsBaikers/DevRites/.github/workflows/ci.yml@refs/heads/main`,
+so `gh` must be installed and authenticated, with no bypass (see
+[Install, update, and remove](../README.md#install-update-and-remove)). This
+avoids asking an old engine to validate a newer payload schema.
 
 `devrites-engine update --check` resolves and compares release metadata without
 downloading assets. `--source-dir` and `--payload-dir` remain the advanced local
@@ -91,9 +100,12 @@ comparison without changing the installation. Use
 retaining the shared `devrites-engine` binary.
 
 If an older direct engine reports `missing codex/hooks.json` or asks for
-`--source-dir`, run `npx devrites@latest update`, or use a checksum-verified
-release `install.sh` and run `bash ./install.sh update` once to install a release
-with the self-contained updater.
+`--source-dir`, run `npx devrites@latest update`, or use a release `install.sh` that is both
+checksum-verified and attestation-verified (pinned repo and signer workflow, see
+the verified Bash bootstrap under
+[README Install, update, and remove](../README.md#install-update-and-remove))
+and run `bash ./install.sh update` once to install a release with the
+self-contained updater.
 
 ## Checks
 
@@ -190,6 +202,9 @@ ledger blocks the phase exit.
 ## Atomic state operations
 
 `state resolve` also supports `--drop <qid> ["<reason>"]` and `--batch <file>`.
+A leading `--human` (for the answer, `--drop` and `--batch` forms:
+`state resolve --human --drop <qid>`, `state resolve --human --batch <file>`) also writes `answered_by: human`;
+without it any `answered_by:` line in the resolved block, whatever its indentation or case, is removed.
 `state close` transactionally archives a shipped workspace and clears matching
 `ACTIVE`.
 
@@ -237,10 +252,15 @@ selection exits `2`; a malformed/unsafe manifest or candidate mismatch prints
 `candidate: BLOCKED: <reason>` to stderr and exits `3`.
 
 - `0`: passed or completed.
+- `1`: runtime or I/O failure.
 - `2`: common invalid request or unreadable-state result.
 - `3`: common deterministic lifecycle or safety block.
 - Atomic state operations retain their documented operation-specific nonzero
   results.
+- `state close` exits `4` for usage or a missing workspace.
+- `state close` exits `3` for a schema refusal.
+- `state close` exits `5` when an archive already exists.
+- `state close` exits `1` for an invalid workspace, archive directory, or ACTIVE cursor.
 
 ## Root safety
 
@@ -251,8 +271,11 @@ commands refuse ambiguous, escaped, symlinked, or otherwise unsafe roots.
 Install, update application, and uninstall remain manifest-owned local
 operations. Direct engine update, shell, and npm may acquire a release candidate;
 all remote acquisition uses exact SemVer, HTTPS-only redirect hops, mandatory
-exact-filename SHA-256 sidecars, private temporary directories, and byte/archive
-bounds, with no unchecked raw/source/default-branch fallback. Update accepts
+exact-filename SHA-256 sidecars, a `gh attestation verify` check of every release
+asset (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), private temporary
+directories, and byte/archive bounds, with no unchecked raw/source/default-branch
+fallback. Update accepts
 `--check` to compare the installed manifest version with the latest stable
 release without downloading assets. Remote-selector flags such as `--to` and
 `--pre` are unsupported.