devrites 3.0.6 → 3.1.0

package/engine/commands.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -11,18 +12,161 @@ import (
 	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/doctor"
 	"github.com/devrites/devrites/internal/migrate"
+	"github.com/devrites/devrites/internal/rootfacts"
 	"github.com/devrites/devrites/internal/state"
 )
 
-// resolveRootLenient resolves the .devrites root for the workspace-orientation
-// commands (preamble / progress / stuck), which must degrade gracefully outside a
-// workspace rather than erroring like the gates do. When no .devrites is found it
-// returns a nonexistent <cwd>/.devrites so the command reads an empty workspace
-// and no-ops (preamble's "No active workspace", progress's silence).
+type rootMode uint8
+
+const (
+	rootUnused rootMode = iota
+	rootLenient
+	rootStrict
+)
+
+// rootModeFor is the single policy boundary between diagnostic/read-only
+// commands, which may degrade outside a workspace, and commands that can write
+// workspace or Git state, which must never fall back after an unsafe root
+// selection.
+func rootModeFor(command string, args []string) rootMode {
+	subcommand := firstRootOperand(args)
+	switch command {
+	case "first-task", "spec-dedupe", "evidence-fresh", "coverage",
+		"doubt-coverage", "budget", "preamble", "progress",
+		"build-readiness", "readiness-digest", "analyze", "mutation-gate",
+		"test-integrity", "review-integrity", "package-existence",
+		"archive-search", "config", "reviewers", "outside-voice", "docs-stale",
+		"secret-scan", "lanes", "overrides":
+		return rootLenient
+	case "clarify-return", "reconcile", "close-out", "forge":
+		return rootStrict
+	case "resolve":
+		if subcommand == "next-qid" {
+			return rootLenient
+		}
+		return rootStrict
+	case "footprint", "stuck":
+		if subcommand == "log" {
+			return rootStrict
+		}
+		return rootLenient
+	case "recovery":
+		if subcommand == "record" || subcommand == "clear" {
+			return rootStrict
+		}
+		return rootLenient
+	case "decisions":
+		if subcommand == "index" {
+			return rootStrict
+		}
+		return rootLenient
+	case "ledger":
+		if subcommand == "sync" {
+			return rootStrict
+		}
+		return rootLenient
+	case "learnings":
+		if subcommand == "add" {
+			return rootStrict
+		}
+		return rootLenient
+	case "timeline":
+		if subcommand == "log" || subcommand == "purge" {
+			return rootStrict
+		}
+		return rootLenient
+	case "health":
+		if subcommand == "" || subcommand == "run" || subcommand == "check" || subcommand == "record" {
+			return rootStrict
+		}
+		return rootLenient
+	case "review-fingerprints":
+		if hasRootFlag(args, "--write") {
+			return rootStrict
+		}
+		return rootLenient
+	case "reviewer-stats":
+		if subcommand == "record" {
+			return rootStrict
+		}
+		return rootLenient
+	case "extensions":
+		if subcommand == "sync" {
+			return rootStrict
+		}
+		return rootLenient
+	case "context":
+		if subcommand == "sync" {
+			return rootStrict
+		}
+		return rootLenient
+	case "runbook":
+		if subcommand == "run" || subcommand == "resume" {
+			return rootStrict
+		}
+		return rootLenient
+	default:
+		return rootUnused
+	}
+}
+
+func firstRootOperand(args []string) string {
+	for _, arg := range args {
+		if arg == "--json" {
+			continue
+		}
+		return strings.ToLower(strings.TrimSpace(arg))
+	}
+	return ""
+}
+
+func hasRootFlag(args []string, flag string) bool {
+	for _, arg := range args {
+		if arg == flag {
+			return true
+		}
+	}
+	return false
+}
+
+// resolveRootFor resolves exactly once per command invocation. Strict commands
+// retain root-safety refusals; lenient readers preserve their historical
+// diagnostic/no-workspace behavior.
+func resolveRootFor(command string, args []string) (string, int, error) {
+	switch rootModeFor(command, args) {
+	case rootUnused:
+		return "", exitOK, nil
+	case rootLenient:
+		return resolveRootLenient(), exitOK, nil
+	case rootStrict:
+		root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+		if err == nil {
+			return root, exitOK, nil
+		}
+		if errors.Is(err, rootfacts.ErrUnsafeRoot) {
+			return "", exitBlocked, err
+		}
+		if errors.Is(err, rootfacts.ErrNoRoot) {
+			return fallbackRoot(), exitOK, nil
+		}
+		return "", exitUsage, err
+	default:
+		panic("unknown root resolution mode")
+	}
+}
+
+// resolveRootLenient resolves the .devrites root for read-only and diagnostic
+// commands that must degrade cleanly outside a workspace. When no root is found,
+// it returns a nonexistent <cwd>/.devrites so those commands see an empty
+// workspace and keep their established no-workspace behavior.
 func resolveRootLenient() string {
 	if root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT")); err == nil {
 		return root
 	}
+	return fallbackRoot()
+}
+
+func fallbackRoot() string {
 	cwd, err := os.Getwd()
 	if err != nil {
 		return ".devrites"
@@ -54,8 +198,11 @@ func gitDir(projectDir string) string {
 	return path
 }
 
-func gitOperation(projectDir string) string {
-	dir := gitDir(projectDir)
+func gitOperation(projectDir, resolvedGitDir string) string {
+	dir := resolvedGitDir
+	if dir == "" {
+		dir = gitDir(projectDir)
+	}
 	if _, err := os.Stat(filepath.Join(dir, "MERGE_HEAD")); err == nil {
 		return "merge"
 	}
@@ -67,37 +214,37 @@ func gitOperation(projectDir string) string {
 	return ""
 }
 
-// cmdDoctor reports the binary / pack / state-schema version triangle and its
-// skew verdict. It exits non-zero only when the state schema is a newer major
-// than the binary can safely parse (a genuine refuse); a mere pack-vs-binary
-// skew is a warning that still exits 0.
+// cmdDoctor reports canonical root facts and the binary, pack, and state schema
+// 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")
 		return exitUsage
 	}
-	root, err := state.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
-	if err != nil {
-		fmt.Fprintf(stderr, "devrites: %v\n", err)
+	facts, resolveErr := rootfacts.Resolve(os.Getenv("DEVRITES_ROOT"))
+	if resolveErr != nil && len(facts.Hazards) == 0 {
+		fmt.Fprintf(stderr, "devrites: %v\n", resolveErr)
 		return exitUsage
 	}
-	// The project directory is the parent of the .devrites root: that is where
-	// an installed pack's version marker (.claude/devrites.version, package.json)
-	// lives.
-	projectDir := filepath.Dir(root)
-	report, err := doctor.Diagnose(projectDir, root)
+	root := facts.PhysicalRoot
+	projectDir := facts.PhysicalProject
+	report, err := doctor.DiagnoseFacts(facts)
 	if err != nil {
 		fmt.Fprintf(stderr, "devrites: %v\n", err)
 		return exitUsage
 	}
 	fmt.Fprint(stdout, report.Render())
-	if op := gitOperation(projectDir); op != "" {
+	if op := gitOperation(projectDir, facts.Git.Dir); op != "" {
 		fmt.Fprintf(stdout, "git-state: %s in progress: resolve with .claude/skills/devrites-lib/reference/standards/git-workflow.md#merge-conflict-recovery\n", op)
 	}
-	for _, warning := range extensionProvenanceWarnings(root) {
-		fmt.Fprintf(stdout, "warning: %s\n", warning)
+	if root != "" {
+		for _, warning := range extensionProvenanceWarnings(root) {
+			fmt.Fprintf(stdout, "warning: %s\n", warning)
+		}
 	}
-	if slug := strings.TrimSpace(readFile(filepath.Join(root, "ACTIVE"))); slug != "" {
+	if root != "" {
+		slug := strings.TrimSpace(readFile(filepath.Join(root, "ACTIVE")))
 		if snap, err := state.Snapshot(root, slug); err == nil {
 			fmt.Fprintln(stdout)
 			fmt.Fprintln(stdout, "readiness-dashboard:")

package/engine/git_guard.go

@@ -0,0 +1,187 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/devrites/devrites/internal/harness"
+	"github.com/devrites/devrites/internal/lib"
+	"github.com/devrites/devrites/internal/orient"
+	drvreason "github.com/devrites/devrites/internal/reason"
+	"github.com/devrites/devrites/internal/toolpolicy"
+)
+
+const gitGuardSuffix = " (devrites-git-guard)"
+
+// hookGitGuard denies ambiguous high-impact Git and requires an exact, fresh,
+// consumed-on-attempt authority record for an unambiguous destructive command.
+func hookGitGuard(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
+	in := h.ParsePreToolInput(stdin)
+	if !isShellTool(in.ToolName) || strings.TrimSpace(in.Command) == "" {
+		return exitOK
+	}
+
+	classified := toolpolicy.ClassifyGitCommand(in.Command)
+	if classified.Verdict == toolpolicy.VerdictSafe {
+		return exitOK
+	}
+	classifierReasons := gitClassifierReasons(classified)
+	if classified.Verdict == toolpolicy.VerdictAmbiguous {
+		primary := gitReasonID(classified.ReasonID, drvreason.GitAuthorityUnavailable)
+		root, slug := gitGuardWorkspace()
+		recordGitPolicy(root, slug, h, primary, classifierReasons, lib.OutcomeDenied)
+		return emitGitDeny(h, stdout, stderr,
+			fmt.Sprintf("DevRites denied an ambiguous high-impact Git request (%s). %s%s",
+				primary, classified.Remediation, gitGuardSuffix))
+	}
+
+	root, slug := gitGuardWorkspace()
+	if root == "" {
+		return emitGitDeny(h, stdout, stderr,
+			"DevRites cannot authorize destructive Git without an active DevRites workspace ("+
+				string(drvreason.GitWorkspaceUnavailable)+")."+gitGuardSuffix)
+	}
+	if slug == "" {
+		recordGitPolicy(root, "", h, drvreason.GitWorkspaceUnavailable, classifierReasons, lib.OutcomeDenied)
+		return emitGitDeny(h, stdout, stderr,
+			"DevRites cannot authorize destructive Git without an active DevRites workspace ("+
+				string(drvreason.GitWorkspaceUnavailable)+")."+gitGuardSuffix)
+	}
+
+	decision := lib.AuthorizeGitOperation(root, slug, classified.Digest, destructiveClassifierReasons(classified))
+	if decision.Allowed {
+		out, err := h.PreToolAllow("DevRites consumed one fresh exact-operation Git authorization (" +
+			string(decision.ReasonID) + ")." + gitGuardSuffix)
+		if err != nil {
+			recordGitPolicy(root, slug, h, drvreason.GitAuthorityUnavailable, classifierReasons, lib.OutcomeDenied)
+			return exitOK
+		}
+		fmt.Fprintln(stdout, out)
+		recordGitPolicy(root, slug, h, decision.ReasonID, classifierReasons, lib.OutcomeAllowed)
+		return exitOK
+	}
+
+	recordGitPolicy(root, slug, h, decision.ReasonID, classifierReasons, lib.OutcomeDenied)
+	return emitGitDeny(h, stdout, stderr, gitAuthorityDenyMessage(decision))
+}
+
+func gitGuardWorkspace() (string, string) {
+	root, err := orient.ResolveRoot(os.Getenv("DEVRITES_ROOT"))
+	if err != nil {
+		return "", ""
+	}
+	slug, err := orient.ActiveSlug(root)
+	if err != nil {
+		return root, ""
+	}
+	return root, slug
+}
+
+func emitGitDeny(h harness.Harness, stdout, stderr io.Writer, message string) int {
+	out, err := h.PreToolDeny(message)
+	if err != nil {
+		debugf(stderr, "git-guard decision unavailable")
+		return exitOK
+	}
+	fmt.Fprintln(stdout, out)
+	return exitOK
+}
+
+func gitAuthorityDenyMessage(decision lib.GitAuthorityDecision) string {
+	reasonID := string(decision.ReasonID)
+	switch decision.ReasonID {
+	case drvreason.GitAuthorityPending, drvreason.GitAuthorityExpired, drvreason.GitAuthorityReplayed:
+		if decision.QuestionID != "" {
+			return fmt.Sprintf(
+				`DevRites requires one fresh exact-operation Git authorization (%s). Resolve %s with /rite-resolve %s "%s", then retry.%s`,
+				reasonID, decision.QuestionID, decision.QuestionID, lib.GitAuthorityAnswer, gitGuardSuffix)
+		}
+	case drvreason.GitAuthorityRefused:
+		return fmt.Sprintf("DevRites denied this destructive Git operation because its exact authorization was refused (%s).%s",
+			reasonID, gitGuardSuffix)
+	case drvreason.GitAuthorityCorrupt:
+		return fmt.Sprintf("DevRites denied destructive Git because its authority record or consumption ledger "+
+			"is invalid (%s). Repair the workspace authority state before retrying.%s",
+			reasonID, gitGuardSuffix)
+	case drvreason.GitWorkspaceUnavailable:
+		return fmt.Sprintf("DevRites cannot authorize destructive Git without an active DevRites workspace (%s).%s",
+			reasonID, gitGuardSuffix)
+	}
+	return fmt.Sprintf("DevRites could not persist or consume destructive Git authority (%s). Repair the workspace or hook, then retry.%s",
+		reasonID, gitGuardSuffix)
+}
+
+func destructiveClassifierReasons(classified toolpolicy.Result) []toolpolicy.ReasonID {
+	seen := map[toolpolicy.ReasonID]bool{}
+	var out []toolpolicy.ReasonID
+	for _, finding := range classified.Findings {
+		if finding.Verdict != toolpolicy.VerdictDestructive || seen[finding.ReasonID] {
+			continue
+		}
+		seen[finding.ReasonID] = true
+		out = append(out, finding.ReasonID)
+	}
+	return out
+}
+
+func gitClassifierReasons(classified toolpolicy.Result) []drvreason.ID {
+	seen := map[drvreason.ID]bool{}
+	var out []drvreason.ID
+	for _, finding := range classified.Findings {
+		id := gitReasonID(finding.ReasonID, "")
+		if id == "" || seen[id] {
+			continue
+		}
+		seen[id] = true
+		out = append(out, id)
+	}
+	if len(out) == 0 {
+		if id := gitReasonID(classified.ReasonID, ""); id != "" {
+			out = append(out, id)
+		}
+	}
+	return out
+}
+
+func gitReasonID(value toolpolicy.ReasonID, fallback drvreason.ID) drvreason.ID {
+	id, err := drvreason.Parse(string(value))
+	if err != nil {
+		return fallback
+	}
+	return id
+}
+
+func recordGitPolicy(root, slug string, h harness.Harness, primary drvreason.ID, classifier []drvreason.ID, outcome lib.EventOutcome) {
+	if root == "" || !drvreason.Known(primary) {
+		return
+	}
+	ev := lib.NewEventV1(lib.BoundaryGitPolicy, "git-guard", primary)
+	ev.GuardStrength = lib.GuardEnforced
+	ev.Outcome = outcome
+	ev.Host = lib.EventHost(h)
+	if ev.Host != lib.HostClaude && ev.Host != lib.HostCodex {
+		ev.Host = lib.HostEngine
+	}
+	ev.RuleIDs = []drvreason.ID{primary}
+	for _, id := range classifier {
+		if len(ev.RuleIDs) == 16 {
+			break
+		}
+		duplicate := false
+		for _, existing := range ev.RuleIDs {
+			if existing == id {
+				duplicate = true
+				break
+			}
+		}
+		if !duplicate {
+			ev.RuleIDs = append(ev.RuleIDs, id)
+		}
+	}
+	if err := lib.BindEventWorkspace(root, slug, &ev); err != nil {
+		return
+	}
+	_ = lib.AppendEventV1(root, ev)
+}