devrites 3.2.0 → 3.2.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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`.
 
+## [3.2.1](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.0...v3.2.1) (2026-07-24)
+
+### Fixed
+
+* **ci:** govern temporary npm audit exceptions ([c2219e0](https://github.com/ViktorsBaikers/DevRites/commit/c2219e0ff11f11ee3f2e2ffa7c5d35b480c5eb76))
+* **rite:** repair doctor compatibility ([811f339](https://github.com/ViktorsBaikers/DevRites/commit/811f339d22d3ec079549a5d50838d7596c72c7da))
+
 ## [3.2.0](https://github.com/ViktorsBaikers/DevRites/compare/v3.1.0...v3.2.0) (2026-07-24)
 
 ### Added

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.1`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.1): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/docs/engine/commands.md

@@ -77,11 +77,13 @@ hazards: ok
   `3`): the binary won't silently mis-parse newer state.
 - Additive schema changes (older state read by a newer binary) are always fine.
 
-The pack version is discovered from `.claude/devrites.version` or the project
-`package.json`; when neither exists the pack is reported `unknown` and no skew is
-asserted. Doctor also reports linked-worktree/submodule identity, merge/rebase
-state, host-artifact drift, and project extensions that have artifacts but no
-optional `provenance.json`.
+The pack version comes from the installer-owned
+`.claude/devrites.manifest`. The old `.claude/devrites.version` marker remains
+readable for compatibility; without either source the pack is reported
+`unknown` and no skew is asserted. The project's own `package.json` is never
+treated as DevRites provenance. Doctor also reports linked-worktree/submodule
+identity, merge/rebase state, host-artifact drift, and project extensions that
+have artifacts but no optional `provenance.json`.
 
 ### Root safety at command dispatch
 

package/engine/commands.go

@@ -218,8 +218,8 @@ func gitOperation(projectDir, resolvedGitDir string) string {
 // versions. It exits nonzero for an unsafe root or newer state schema. Missing
 // optional data and warnings remain diagnostic.
 func cmdDoctor(args []string, stdout, stderr io.Writer) int {
-	if len(args) != 0 {
-		fmt.Fprintln(stderr, "usage: devrites-engine doctor")
+	if len(args) > 1 || len(args) == 1 && args[0] != "--verbose" {
+		fmt.Fprintln(stderr, "usage: devrites-engine doctor [--verbose]")
 		return exitUsage
 	}
 	facts, resolveErr := rootfacts.Resolve(os.Getenv("DEVRITES_ROOT"))

package/engine/internal/doctor/doctor.go

@@ -5,13 +5,13 @@ package doctor
 
 import (
 	"crypto/sha256"
-	"encoding/json"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 
+	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/rootfacts"
 	"github.com/devrites/devrites/internal/state"
 	"github.com/devrites/devrites/internal/version"
@@ -160,20 +160,32 @@ func (r *Report) Render() string {
 	return b.String()
 }
 
-// packVersion discovers the installed DevRites pack version. It prefers an
-// explicit marker (.claude/devrites.version) and falls back to the npm
-// package.json at the project root; either absent leaves the pack Unknown so no
-// false skew is asserted.
+// packVersion discovers the installed DevRites pack version from the install
+// manifest. The old standalone marker remains readable for compatibility.
 func packVersion(projectDir string) string {
-	if v := firstLine(filepath.Join(projectDir, ".claude", "devrites.version")); v != "" {
+	if v := manifestVersion(filepath.Join(projectDir, filepath.FromSlash(devritespaths.ManifestName))); v != "" {
 		return v
 	}
-	if v := packageJSONVersion(filepath.Join(projectDir, "package.json")); v != "" {
+	if v := firstLine(filepath.Join(projectDir, ".claude", "devrites.version")); v != "" {
 		return v
 	}
 	return Unknown
 }
 
+func manifestVersion(path string) string {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return ""
+	}
+	const prefix = "# devrites-version:"
+	for _, line := range strings.Split(string(raw), "\n") {
+		if strings.HasPrefix(line, prefix) {
+			return strings.TrimSpace(strings.TrimPrefix(line, prefix))
+		}
+	}
+	return ""
+}
+
 func firstLine(path string) string {
 	raw, err := os.ReadFile(path)
 	if err != nil {
@@ -200,8 +212,8 @@ func driftChecks(projectDir string) []string {
 	if isDir(filepath.Join(projectDir, ".claude", "agents")) && !isDir(filepath.Join(projectDir, ".codex", "agents")) {
 		checks = append(checks, "WARN: Claude agents installed but Codex agent mirror .codex/agents is missing")
 	}
-	if firstLine(filepath.Join(projectDir, ".claude", "devrites.version")) == "" && isDir(filepath.Join(projectDir, ".claude", "skills")) {
-		checks = append(checks, "WARN: installed skills have no .claude/devrites.version marker")
+	if packVersion(projectDir) == Unknown && isDir(filepath.Join(projectDir, ".claude", "skills")) {
+		checks = append(checks, "WARN: installed skills have no versioned .claude/devrites.manifest provenance")
 	}
 	if generatedClaudeDrift(projectDir) {
 		checks = append(checks, "[DRV-GENERATED-DRIFT] WARN: pack/generated/claude differs from canonical pack/.claude; run `bash scripts/build-host-artifacts.sh`")
@@ -292,17 +304,3 @@ func isDir(path string) bool {
 	info, err := os.Stat(path)
 	return err == nil && info.IsDir()
 }
-
-func packageJSONVersion(path string) string {
-	raw, err := os.ReadFile(path)
-	if err != nil {
-		return ""
-	}
-	var pkg struct {
-		Version string `json:"version"`
-	}
-	if err := json.Unmarshal(raw, &pkg); err != nil {
-		return ""
-	}
-	return strings.TrimSpace(pkg.Version)
-}

package/engine/internal/doctor/doctor_test.go

@@ -64,12 +64,13 @@ func TestDiagnoseOKWhenAligned(t *testing.T) {
 func TestDiagnoseWarnsWhenBinaryOlderThanPack(t *testing.T) {
 	withBinaryVersion(t, "1.0.0")
 	projectDir := t.TempDir()
-	// Pack marker newer than the binary → warn, not refuse.
+	// Installed pack newer than the binary → warn, not refuse.
 	claude := filepath.Join(projectDir, ".claude")
 	if err := os.MkdirAll(claude, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("2.0.0\n"), 0o644); err != nil {
+	manifest := "# devrites-version: 2.0.0\n.claude/skills/rite/SKILL.md\tabc\n"
+	if err := os.WriteFile(filepath.Join(claude, "devrites.manifest"), []byte(manifest), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	root := t.TempDir()
@@ -90,6 +91,33 @@ func TestDiagnoseWarnsWhenBinaryOlderThanPack(t *testing.T) {
 	}
 }
 
+func TestPackVersionUsesManifestBeforeLegacyMarker(t *testing.T) {
+	projectDir := t.TempDir()
+	claude := filepath.Join(projectDir, ".claude")
+	if err := os.MkdirAll(claude, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(claude, "devrites.manifest"), []byte("# devrites-version: 3.2.0\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(claude, "devrites.version"), []byte("2.9.0\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := packVersion(projectDir); got != "3.2.0" {
+		t.Fatalf("packVersion() = %q, want installer manifest version 3.2.0", got)
+	}
+}
+
+func TestPackVersionIgnoresProjectPackageJSON(t *testing.T) {
+	projectDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(projectDir, "package.json"), []byte(`{"version":"99.0.0"}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if got := packVersion(projectDir); got != Unknown {
+		t.Fatalf("packVersion() = %q, want %q without DevRites install provenance", got, Unknown)
+	}
+}
+
 func TestDiagnoseRefusesNewerStateSchema(t *testing.T) {
 	withBinaryVersion(t, "2.6.1")
 	root := t.TempDir()
@@ -143,7 +171,7 @@ func TestDiagnoseReportsHostArtifactDrift(t *testing.T) {
 		t.Fatal("expected drift checks")
 	}
 	out := r.Render()
-	for _, want := range []string{"devrites-engine hooks", "Codex skill mirror", "devrites.version marker"} {
+	for _, want := range []string{"devrites-engine hooks", "Codex skill mirror", "devrites.manifest provenance"} {
 		if !strings.Contains(out, want) {
 			t.Fatalf("doctor output missing %q:\n%s", want, out)
 		}

package/engine/tests/doctor_cli_test.go

@@ -25,6 +25,21 @@ func TestDoctorPrintsTriangle(t *testing.T) {
 	}
 }
 
+func TestDoctorVerboseMatchesPlainDoctor(t *testing.T) {
+	root := newWorkspace(t)
+	plainOut, plainErr, plainCode := runDevrites(t, root, "doctor")
+	verboseOut, verboseErr, verboseCode := runDevrites(t, root, "doctor", "--verbose")
+	if plainCode != 0 || verboseCode != 0 {
+		t.Fatalf("doctor exits: plain=%d verbose=%d", plainCode, verboseCode)
+	}
+	if verboseCode != plainCode || verboseOut != plainOut || verboseErr != plainErr {
+		t.Fatalf(
+			"doctor --verbose differs from doctor:\nplain: code=%d stdout=%q stderr=%q\nverbose: code=%d stdout=%q stderr=%q",
+			plainCode, plainOut, plainErr, verboseCode, verboseOut, verboseErr,
+		)
+	}
+}
+
 func TestDoctorReportsStaleActiveWithPasteableRepair(t *testing.T) {
 	root := newWorkspace(t)
 	if err := os.WriteFile(filepath.Join(root, "ACTIVE"), []byte("ghost\n"), 0o644); err != nil {

package/pack/.claude/skills/rite-doctor/SKILL.md

@@ -19,7 +19,7 @@ It is **read-only**: it never edits the workspace, never advances a phase, never
 ## Workflow
 1. Run the diagnose core verbosely (resolve across install layouts):
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
 1a. **Surface the learnings nudge**: point the user at `/rite-learn` when a pattern recurs across
    shipped features (read-only; silent when there's nothing to say):
@@ -68,7 +68,7 @@ progress`, but it follows the compact labels and one-next-action rule from
 ```
 Done: DevRites health checked; <OK | n issues>.
 Changed: workspace only
-Evidence: devrites-engine doctor --verbose rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
+Evidence: devrites-engine doctor rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
 Open: <none | issue count and top issue>
 Next: <single command for the most urgent issue>
 Record: not applicable

package/pack/.claude/skills/rite-upgrade/SKILL.md

@@ -42,7 +42,7 @@ Plan, Vet, Converge, and Build phase contracts needed by the assessment.
 
 0. **Orient and normalize structure.** Read the active slug or `$ARGUMENTS`. Run:
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
    A binary/pack integrity mismatch stops at `/rite-doctor`; do not run migration or
    mutate semantic artifacts. Once healthy, orient without writing:

package/pack/generated/claude/skills/rite-doctor/SKILL.md

@@ -19,7 +19,7 @@ It is **read-only**: it never edits the workspace, never advances a phase, never
 ## Workflow
 1. Run the diagnose core verbosely (resolve across install layouts):
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
 1a. **Surface the learnings nudge**: point the user at `/rite-learn` when a pattern recurs across
    shipped features (read-only; silent when there's nothing to say):
@@ -68,7 +68,7 @@ progress`, but it follows the compact labels and one-next-action rule from
 ```
 Done: DevRites health checked; <OK | n issues>.
 Changed: workspace only
-Evidence: devrites-engine doctor --verbose rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
+Evidence: devrites-engine doctor rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
 Open: <none | issue count and top issue>
 Next: <single command for the most urgent issue>
 Record: not applicable

package/pack/generated/claude/skills/rite-upgrade/SKILL.md

@@ -42,7 +42,7 @@ Plan, Vet, Converge, and Build phase contracts needed by the assessment.
 
 0. **Orient and normalize structure.** Read the active slug or `$ARGUMENTS`. Run:
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
    A binary/pack integrity mismatch stops at `/rite-doctor`; do not run migration or
    mutate semantic artifacts. Once healthy, orient without writing:

package/pack/generated/codex/skills/rite-doctor/SKILL.md

@@ -35,7 +35,7 @@ It is **read-only**: it never edits the workspace, never advances a phase, never
 ## Workflow
 1. Run the diagnose core verbosely (resolve across install layouts):
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
 1a. **Surface the learnings nudge**: point the user at `$rite-learn` when a pattern recurs across
    shipped features (read-only; silent when there's nothing to say):
@@ -84,7 +84,7 @@ progress`, but it follows the compact labels and one-next-action rule from
 ```
 Done: DevRites health checked; <OK | n issues>.
 Changed: workspace only
-Evidence: devrites-engine doctor --verbose rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
+Evidence: devrites-engine doctor rc=<0|1>; health <skipped|PASS|WARN|FAIL>; reindex <skipped|result>; learnings nudge <summary|none>; extensions/overrides <ok|n issues>
 Open: <none | issue count and top issue>
 Next: <single command for the most urgent issue>
 Record: not applicable

package/pack/generated/codex/skills/rite-upgrade/SKILL.md

@@ -58,7 +58,7 @@ Plan, Vet, Converge, and Build phase contracts needed by the assessment.
 
 0. **Orient and normalize structure.** Read the active slug or `$ARGUMENTS`. Run:
    ```bash
-   devrites-engine doctor --verbose; echo "doctor rc=$?"
+   devrites-engine doctor; echo "doctor rc=$?"
    ```
    A binary/pack integrity mismatch stops at `$rite-doctor`; do not run migration or
    mutate semantic artifacts. Once healthy, orient without writing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devrites",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "DevRites: a disciplined senior-engineer workflow pack for Claude Code and Codex",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/ViktorsBaikers/DevRites#readme",
@@ -54,7 +54,7 @@
     "test:fast": "node scripts/run-tests.mjs --fast",
     "test:parallel": "node scripts/run-tests.mjs",
     "test:serial": "node scripts/run-tests.mjs --serial",
-    "audit": "npm audit --audit-level=moderate",
+    "audit": "node scripts/check-npm-audit.mjs",
     "size:baseline": "node scripts/check-instruction-size-baseline.mjs --write",
     "release": "semantic-release",
     "release:dry": "semantic-release --dry-run --no-ci"

package/scripts/check-npm-audit.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const option = (name, fallback) => {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : fallback;
+};
+const input = option('--input', '');
+const exceptionsPath = resolve(option('--exceptions', resolve(root, 'scripts', 'npm-audit-exceptions.json')));
+const blocking = new Set(['moderate', 'high', 'critical']);
+const failures = [];
+const fail = (message) => failures.push(message);
+const load = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+let report;
+if (input) {
+  report = load(resolve(input));
+} else {
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(npm, ['audit', '--json'], { cwd: root, encoding: 'utf8' });
+  if (result.error || ![0, 1].includes(result.status)) {
+    console.error(result.stderr || result.error?.message || `npm audit exited ${result.status}`);
+    process.exit(1);
+  }
+  try {
+    report = JSON.parse(result.stdout);
+  } catch {
+    console.error('FAIL: npm audit did not return valid JSON');
+    process.exit(1);
+  }
+}
+
+const concrete = new Map();
+let affected = 0;
+for (const [packageName, vulnerability] of Object.entries(report.vulnerabilities || {})) {
+  if (!blocking.has(vulnerability.severity)) continue;
+  affected++;
+  for (const via of vulnerability.via || []) {
+    if (!via || typeof via !== 'object' || !blocking.has(via.severity)) continue;
+    const id = via.url?.match(/GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}/i)?.[0];
+    if (!id) {
+      fail(`${packageName}: blocking advisory has no GHSA identifier`);
+      continue;
+    }
+    const finding = concrete.get(id) || {
+      id,
+      package: via.name || packageName,
+      range: via.range || vulnerability.range,
+      source: via.url,
+      nodes: [],
+    };
+    finding.nodes = [...new Set([...finding.nodes, ...(vulnerability.nodes || [])])].sort();
+    concrete.set(id, finding);
+  }
+}
+if (affected > 0 && concrete.size === 0) fail('blocking audit findings have no concrete advisory records');
+
+const exceptions = load(exceptionsPath);
+if (!Array.isArray(exceptions)) fail('npm audit exceptions must be a JSON array');
+const today = new Date().toISOString().slice(0, 10);
+const seen = new Set();
+for (const exception of Array.isArray(exceptions) ? exceptions : []) {
+  const required = ['id', 'package', 'range', 'source', 'owner', 'reason', 'expires'];
+  const missing = required.filter((field) => !exception?.[field]);
+  if (!Array.isArray(exception?.nodes) || exception.nodes.length === 0) missing.push('nodes');
+  if (missing.length) {
+    fail(`${exception?.id || 'unknown exception'}: missing ${missing.join(', ')}`);
+    continue;
+  }
+  if (!/^GHSA-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}$/i.test(exception.id) || !/^\d{4}-\d{2}-\d{2}$/.test(exception.expires)) {
+    fail(`${exception.id}: invalid id or expiry`);
+    continue;
+  }
+  if (seen.has(exception.id)) fail(`${exception.id}: duplicate exception`);
+  seen.add(exception.id);
+  if (exception.expires < today) fail(`${exception.id}: exception expired ${exception.expires}`);
+
+  const finding = concrete.get(exception.id);
+  if (!finding) {
+    fail(`${exception.id}: exception is stale; advisory is absent`);
+    continue;
+  }
+  for (const field of ['package', 'range', 'source']) {
+    if (exception[field] !== finding[field]) {
+      fail(`${exception.id}: ${field} mismatch (expected ${finding[field]})`);
+    }
+  }
+  if (JSON.stringify([...exception.nodes].sort()) !== JSON.stringify(finding.nodes)) {
+    fail(`${exception.id}: nodes mismatch (expected ${finding.nodes.join(', ')})`);
+  }
+}
+for (const finding of concrete.values()) {
+  if (!seen.has(finding.id)) fail(`${finding.id}: blocking advisory is not excepted`);
+}
+
+for (const message of failures) console.error(`FAIL: ${message}`);
+if (failures.length) process.exit(1);
+if (affected === 0) {
+  console.log('npm-audit: no moderate-or-higher advisories');
+} else {
+  for (const exception of exceptions) {
+    console.log(`npm-audit: temporary ${exception.id} exception owned by ${exception.owner}, expires ${exception.expires}`);
+  }
+  console.log(`npm-audit: ${concrete.size} exact temporary exception(s), ${affected} affected package record(s)`);
+}

package/scripts/npm-audit-exceptions.json

@@ -0,0 +1,14 @@
+[
+  {
+    "id": "GHSA-r292-9mhp-454m",
+    "package": "tar",
+    "range": "<=7.5.20",
+    "nodes": [
+      "node_modules/npm/node_modules/tar"
+    ],
+    "source": "https://github.com/advisories/GHSA-r292-9mhp-454m",
+    "owner": "release-maintainers",
+    "reason": "npm@11.18.0 bundles tar@7.5.19 through @semantic-release/npm. The plugin invokes npm for authentication and publishing operations over trusted local source; it does not select or extract members from untrusted tar archives. Remove this exception as soon as npm bundles tar@7.5.21 or newer.",
+    "expires": "2026-08-07"
+  }
+]