devrites 4.6.0 → 5.0.0

package/engine/internal/lib/environment_report.go

@@ -0,0 +1,109 @@
+package lib
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/version"
+)
+
+// PathProbe records whether one project-relative path exists.
+type PathProbe struct {
+	Path    string `json:"path"`
+	Present bool   `json:"present"`
+}
+
+// EnvironmentReport is a read-only snapshot of install and code-index presence.
+type EnvironmentReport struct {
+	EngineVersion string      `json:"engine_version"`
+	ProjectRoot   string      `json:"project_root"`
+	DevritesRoot  string      `json:"devrites_root,omitempty"`
+	Manifest      PathProbe   `json:"manifest"`
+	Indexes       []PathProbe `json:"indexes"`
+}
+
+func projectRootFromDevritesRoot(root string) string {
+	if root == "" {
+		wd, err := os.Getwd()
+		if err != nil {
+			return "."
+		}
+		return wd
+	}
+	if filepath.Base(root) == devritespaths.DevritesRootName {
+		return filepath.Dir(root)
+	}
+	return root
+}
+
+func probePath(projectRoot, rel string) PathProbe {
+	abs := filepath.Join(projectRoot, filepath.FromSlash(rel))
+	info, err := os.Stat(abs)
+	return PathProbe{Path: rel, Present: err == nil && info != nil}
+}
+
+// EnvironmentReportFor builds a report for one project root.
+func EnvironmentReportFor(devritesRoot, projectRoot string) (EnvironmentReport, error) {
+	if projectRoot == "" {
+		projectRoot = projectRootFromDevritesRoot(devritesRoot)
+	}
+	abs, err := filepath.Abs(projectRoot)
+	if err != nil {
+		return EnvironmentReport{}, err
+	}
+	report := EnvironmentReport{
+		EngineVersion: version.Version,
+		ProjectRoot:   abs,
+		Manifest:      probePath(abs, devritespaths.ManifestName),
+		Indexes: []PathProbe{
+			probePath(abs, ".codegraph"),
+			probePath(abs, ".code-review-graph"),
+			probePath(abs, ".codebase-memory"),
+		},
+	}
+	if devritesRoot != "" {
+		report.DevritesRoot = devritesRoot
+	}
+	return report, nil
+}
+
+// WriteEnvironmentReportJSON prints one JSON object to stdout.
+func WriteEnvironmentReportJSON(devritesRoot, projectRoot string, stdout io.Writer) error {
+	report, err := EnvironmentReportFor(devritesRoot, projectRoot)
+	if err != nil {
+		return fmt.Errorf("build environment report: %w", err)
+	}
+	enc := json.NewEncoder(stdout)
+	enc.SetIndent("", "  ")
+	if err := enc.Encode(report); err != nil {
+		return fmt.Errorf("encode environment report: %w", err)
+	}
+	return nil
+}
+
+// RunEnvironmentCheck implements `devrites-engine check indexes`.
+func RunEnvironmentCheck(devritesRoot string, args []string, stdout, stderr io.Writer) int {
+	projectRoot := ""
+	for i := 0; i < len(args); i++ {
+		if args[i] == "--root" {
+			if i+1 >= len(args) {
+				fmt.Fprintln(stderr, "indexes: --root requires a path")
+				return 2
+			}
+			projectRoot = args[i+1]
+			i++
+			continue
+		}
+		fmt.Fprintf(stderr, "indexes: unexpected argument %q\n", args[i])
+		return 2
+	}
+	if err := WriteEnvironmentReportJSON(devritesRoot, projectRoot, stdout); err != nil {
+		fmt.Fprintf(stderr, "indexes: %v\n", err)
+		return 2
+	}
+	return 0
+}

package/engine/internal/lib/environment_report_test.go

@@ -0,0 +1,54 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+)
+
+func TestEnvironmentReportForDetectsManifestAndIndexes(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, devritespaths.DevritesRootName)
+	manifestPath := filepath.Join(project, devritespaths.ManifestName)
+	if err := os.MkdirAll(filepath.Dir(manifestPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(manifestPath, []byte("devrites\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.MkdirAll(filepath.Join(project, ".codegraph"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+
+	report, err := EnvironmentReportFor(root, project)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if report.ProjectRoot != project {
+		t.Fatalf("project root = %q, want %q", report.ProjectRoot, project)
+	}
+	if !report.Manifest.Present {
+		t.Fatal("expected manifest present")
+	}
+	if len(report.Indexes) != 3 {
+		t.Fatalf("indexes = %d, want 3", len(report.Indexes))
+	}
+	if !report.Indexes[0].Present {
+		t.Fatalf("expected .codegraph present, got %+v", report.Indexes)
+	}
+}
+
+func TestRunEnvironmentCheckWritesJSON(t *testing.T) {
+	project := t.TempDir()
+	var stdout, stderr bytes.Buffer
+	if code := RunEnvironmentCheck("", []string{"--root", project}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"engine_version"`) || !strings.Contains(stdout.String(), `"manifest"`) {
+		t.Fatalf("stdout=%q", stdout.String())
+	}
+}

package/engine/internal/lib/migrate.go

@@ -0,0 +1,220 @@
+package lib
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/fsutil"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// migrateStep is one deterministic action of a migration plan.
+type migrateStep struct {
+	kind   string // "phase", "cursor", "schema", or "stub"
+	path   string // workspace-relative file a stub creates
+	detail string
+}
+
+type migrateQuestion struct {
+	id     string
+	prompt string
+}
+
+type migratePlan struct {
+	phase     string
+	steps     []migrateStep
+	questions []migrateQuestion
+}
+
+// Migrate normalizes a pre-v5 feature workspace to the current schema: it
+// converts legacy bullet cursor fields into canonical table rows, records the
+// schema row, and creates missing required artifacts as empty stubs. Bound
+// proof files are preserved byte-exact; content is never synthesized. The
+// command is one-shot and fail-closed: on ambiguity it writes nothing, prints
+// its questions, and exits non-zero; answers arrive on rerun via
+// --answer id=choice. --dry-run prints the plan and always writes nothing.
+func Migrate(root string, args []string, stdout, stderr io.Writer) int {
+	flags := flag.NewFlagSet("migrate", flag.ContinueOnError)
+	flags.SetOutput(io.Discard)
+	dryRun := flags.Bool("dry-run", false, "print the plan without writing")
+	var answerPairs stringSlice
+	flags.Var(&answerPairs, "answer", "answer a migration question: id=choice")
+	// Parse with interleaving support: stdlib stops at the first positional,
+	// so re-parse the remainder and collect positionals along the way.
+	var positionals []string
+	remaining := args
+	for {
+		if err := flags.Parse(remaining); err != nil {
+			fmt.Fprintf(stderr, "devrites: %v\n", err)
+			return 2
+		}
+		rest := flags.Args()
+		if len(rest) == 0 {
+			break
+		}
+		positionals = append(positionals, rest[0])
+		remaining = rest[1:]
+	}
+	if len(positionals) != 1 {
+		fmt.Fprintln(stderr, "usage: devrites-engine migrate <slug> [--dry-run] [--answer id=choice]")
+		return 2
+	}
+	slug := positionals[0]
+
+	work, err := devritespaths.ExistingFeatureDirChecked(root, slug)
+	if err != nil {
+		fmt.Fprintf(stderr, "migrate: %v\n", err)
+		return 2
+	}
+	answered := map[string]string{}
+	for _, pair := range answerPairs {
+		id, value, ok := strings.Cut(pair, "=")
+		if !ok || strings.TrimSpace(id) == "" {
+			fmt.Fprintf(stderr, "devrites: invalid --answer %q (want id=choice)\n", pair)
+			return 2
+		}
+		answered[strings.TrimSpace(id)] = strings.TrimSpace(value)
+	}
+
+	// Read, plan, and apply under one feature lock so a concurrent
+	// `state resolve`/`close` can never be clobbered by a stale read.
+	ledger := filepath.Join(work, "state.md")
+	var applied int
+	var exit int
+	var result string
+	err = state.WithFeatureLock(root, slug, func() error {
+		// #nosec G304 -- workspace ledger path resolved from the operator root
+		raw, err := os.ReadFile(ledger)
+		if err != nil {
+			return err
+		}
+		lines := strings.Split(strings.ReplaceAll(string(raw), "\r\n", "\n"), "\n")
+
+		version, err := state.WorkspaceSchema(root, slug)
+		if err != nil {
+			return err
+		}
+		if version > state.SchemaVersion {
+			fmt.Fprintf(stderr, "migrate: workspace %s declares schema %d, newer than this engine's %d; upgrade devrites\n", slug, version, state.SchemaVersion)
+			exit = 3
+			return nil
+		}
+		if version == state.SchemaVersion {
+			result = fmt.Sprintf("migrate: %s already at schema %d; nothing to do\n", slug, version)
+			exit = 0
+			return nil
+		}
+
+		plan := buildMigratePlan(root, slug, lines, answered)
+		if len(plan.questions) > 0 {
+			for _, q := range plan.questions {
+				fmt.Fprintf(stderr, "migrate: question %s: %s\n", q.id, q.prompt)
+			}
+			fmt.Fprintln(stderr, "migrate: nothing written; re-run with --answer id=choice")
+			exit = 3
+			return nil
+		}
+
+		if *dryRun {
+			fmt.Fprintf(stdout, "migrate: plan for %s\n", slug)
+			for _, step := range plan.steps {
+				fmt.Fprintf(stdout, "  [%s] %s\n", step.kind, step.detail)
+			}
+			fmt.Fprintln(stdout, "migrate: dry run; nothing written")
+			exit = 0
+			return nil
+		}
+
+		// New stub files go first: they are idempotent, never bound, and
+		// state.md is the commit point written last.
+		for _, step := range plan.steps {
+			if step.kind != "stub" {
+				continue
+			}
+			path := filepath.Join(work, filepath.FromSlash(step.path))
+			if _, statErr := os.Stat(path); statErr == nil {
+				return fmt.Errorf("stub target %s appeared during migration; re-run migrate", step.path)
+			}
+			if err := fsutil.WriteFileAtomic(path, nil, 0o644); err != nil {
+				return err
+			}
+			applied++
+		}
+		next := lines
+		for _, step := range plan.steps {
+			if step.kind == "phase" {
+				next = state.UpsertCursorField(next, state.CursorPhase, plan.phase)
+			}
+		}
+		if converted, changed := state.ConvertCursorToTable(next); changed {
+			next = converted
+		}
+		next = state.UpsertCursorField(next, state.CursorSchema, fmt.Sprint(state.SchemaVersion))
+		if err := fsutil.WriteFileAtomic(ledger, []byte(strings.Join(next, "\n")), 0o644); err != nil {
+			return err
+		}
+		result = fmt.Sprintf("migrate: %s normalized to schema %d (%d stub(s) created)\n", slug, state.SchemaVersion, applied)
+		exit = 0
+		return nil
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "migrate: %v\n", err)
+		return 1
+	}
+	fmt.Fprint(stdout, result)
+	return exit
+}
+
+func buildMigratePlan(root, slug string, lines []string, answered map[string]string) migratePlan {
+	plan := migratePlan{}
+	phase, hasPhase := state.CursorField(lines, state.CursorPhase)
+
+	if value, ok := answered["phase"]; ok {
+		plan.steps = append(plan.steps, migrateStep{kind: "phase", detail: "record phase " + value + " from answer"})
+		phase, hasPhase = value, true
+	}
+	if !hasPhase {
+		plan.questions = append(plan.questions, migrateQuestion{id: "phase",
+			prompt: "state.md records no phase; re-run with --answer phase=<phase>"})
+		return plan
+	}
+	if _, ok := state.PolicyFor(state.Phase(phase)); !ok {
+		plan.questions = append(plan.questions, migrateQuestion{id: "phase",
+			prompt: "state.md records unknown phase " + phase + "; re-run with --answer phase=<phase>"})
+		return plan
+	}
+	plan.phase = phase
+
+	if state.CursorForm(lines) == "legacy" {
+		plan.steps = append(plan.steps, migrateStep{kind: "cursor", detail: "convert legacy cursor bullets to canonical table rows"})
+	}
+	plan.steps = append(plan.steps, migrateStep{kind: "schema", detail: fmt.Sprintf("record schema %d in state.md", state.SchemaVersion)})
+
+	policy, _ := state.PolicyFor(state.Phase(phase))
+	for _, artifact := range policy.RequiredArtifacts {
+		name := string(artifact)
+		if name == state.LedgerFile {
+			continue
+		}
+		if _, err := os.Stat(filepath.Join(devritespaths.FeatureDir(root, slug), filepath.FromSlash(name))); err == nil {
+			continue
+		}
+		plan.steps = append(plan.steps, migrateStep{kind: "stub", path: name, detail: "create missing " + name + " as an empty stub"})
+	}
+	return plan
+}
+
+// stringSlice collects repeated string flag values.
+type stringSlice []string
+
+func (s *stringSlice) String() string { return strings.Join(*s, ",") }
+
+func (s *stringSlice) Set(value string) error {
+	*s = append(*s, value)
+	return nil
+}

package/engine/internal/lib/migrate_test.go

@@ -0,0 +1,154 @@
+package lib
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// seedPreV5Workspace builds a pre-v5 workspace with a bullet cursor, prose,
+// and no required artifacts beyond state.md.
+func seedPreV5Workspace(t *testing.T, phase string) (root, workspace string) {
+	t.Helper()
+	root = t.TempDir()
+	workspace = filepath.Join(root, "work", "feature")
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := "- Phase: " + phase + "\n- Status: running\n- Next step: continue slice S-2\n\n# Status\n\nMinting middleware landed.\n"
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root, workspace
+}
+
+func TestMigrateDryRunPlansWithoutWriting(t *testing.T) {
+	root, workspace := seedPreV5Workspace(t, "build")
+	var stdout, stderr strings.Builder
+	if code := Migrate(root, []string{"feature", "--dry-run"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "migrate: plan for feature") ||
+		!strings.Contains(out, "[cursor] convert legacy cursor bullets") ||
+		!strings.Contains(out, "[schema] record schema") ||
+		!strings.Contains(out, "[stub] create missing spec.md") {
+		t.Fatalf("plan incomplete:\n%s", out)
+	}
+	// Nothing written: state.md bytes unchanged and no stub exists.
+	body, err := os.ReadFile(filepath.Join(workspace, "state.md"))
+	if err != nil || !strings.HasPrefix(string(body), "- Phase: build\n") {
+		t.Fatalf("state.md changed during dry run: %v %q", err, body)
+	}
+	if _, err := os.Stat(filepath.Join(workspace, "spec.md")); !os.IsNotExist(err) {
+		t.Fatalf("stub created during dry run: %v", err)
+	}
+}
+
+func TestMigrateExecutesCursorConversionAndStubs(t *testing.T) {
+	root, workspace := seedPreV5Workspace(t, "build")
+	var stdout, stderr strings.Builder
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	body, err := os.ReadFile(filepath.Join(workspace, "state.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	text := string(body)
+	if !strings.Contains(text, "| phase | build |") || !strings.Contains(text, "| status | running |") {
+		t.Fatalf("cursor bullets not converted:\n%s", text)
+	}
+	if !strings.Contains(text, "| next_action | continue slice S-2 |") {
+		t.Fatalf("next step not converted to canonical spelling:\n%s", text)
+	}
+	if strings.Contains(text, "- Next step:") {
+		t.Fatalf("legacy next step bullet survived:\n%s", text)
+	}
+	if !strings.Contains(text, "| schema | 3 |") {
+		t.Fatalf("schema row missing:\n%s", text)
+	}
+	if !strings.Contains(text, "# Status\n\nMinting middleware landed.") {
+		t.Fatalf("prose not preserved:\n%s", text)
+	}
+	// Required artifacts for build exist as empty stubs.
+	for _, name := range []string{"spec.md", "brief.md", "eng-review.md", "test-plan.md"} {
+		info, err := os.Stat(filepath.Join(workspace, name))
+		if err != nil {
+			t.Fatalf("stub %s: %v", name, err)
+		}
+		if info.Size() != 0 {
+			t.Fatalf("stub %s synthesized content", name)
+		}
+	}
+	// Idempotent: a second run is a no-op.
+	stdout.Reset()
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("second run code=%d stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "nothing to do") {
+		t.Fatalf("second run should be a no-op, got %q", stdout.String())
+	}
+}
+
+func TestMigrateUnknownPhaseAsksAndWritesNothing(t *testing.T) {
+	root, workspace := seedPreV5Workspace(t, "research")
+	var stdout, stderr strings.Builder
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 3 {
+		t.Fatalf("code=%d want 3", code)
+	}
+	if !strings.Contains(stderr.String(), "question phase:") || !strings.Contains(stderr.String(), "nothing written") {
+		t.Fatalf("stderr=%q", stderr.String())
+	}
+	body, _ := os.ReadFile(filepath.Join(workspace, "state.md"))
+	if !strings.HasPrefix(string(body), "- Phase: research\n") {
+		t.Fatalf("state.md changed on refusal: %q", body)
+	}
+
+	// Answering the question on rerun proceeds.
+	if code := Migrate(root, []string{"feature", "--answer", "phase=build"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("answer rerun code=%d stderr=%q", code, stderr.String())
+	}
+	body, _ = os.ReadFile(filepath.Join(workspace, "state.md"))
+	if !strings.Contains(string(body), "| phase | build |") || !strings.Contains(string(body), "| schema | 3 |") {
+		t.Fatalf("answer rerun did not migrate:\n%s", body)
+	}
+}
+
+// A done workspace migrates like any other: it is fully artifacted (zero
+// stubs), and normalizing it unblocks `state close`, which refuses pre-v5
+// workspaces. A special no-op would strand done workspaces between migrate
+// and close.
+func TestMigrateDoneWorkspaceNormalizesWithoutStubs(t *testing.T) {
+	root, workspace := seedPreV5Workspace(t, "done")
+	var stdout, stderr strings.Builder
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%q", code, stderr.String())
+	}
+	body, _ := os.ReadFile(filepath.Join(workspace, "state.md"))
+	if !strings.Contains(string(body), "| schema | 3 |") {
+		t.Fatalf("done workspace not normalized:\n%s", body)
+	}
+	if !strings.Contains(stdout.String(), "normalized to schema 3") {
+		t.Fatalf("stdout=%q", stdout.String())
+	}
+}
+
+func TestMigrateCurrentAndNewerSchemaAreRefused(t *testing.T) {
+	root, workspace := seedPreV5Workspace(t, "build")
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | build |\n| schema | 3 |\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	var stdout, stderr strings.Builder
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 0 || !strings.Contains(stdout.String(), "nothing to do") {
+		t.Fatalf("current schema: code=%d stdout=%q", code, stdout.String())
+	}
+
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | build |\n| schema | 9 |\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if code := Migrate(root, []string{"feature"}, &stdout, &stderr); code != 3 || !strings.Contains(stderr.String(), "upgrade devrites") {
+		t.Fatalf("newer schema: code=%d stderr=%q", code, stderr.String())
+	}
+}

package/engine/internal/lib/open_visual.go

@@ -77,7 +77,9 @@ func OpenVisual(root string, args []string, stdout, stderr io.Writer) int {
 	var idReport VisualIDConsistency
 	idsChecked := false
 	if !outlineMissing {
+		// #nosec G304 -- visual evidence files inside the workspace
 		htmlBody, herr := os.ReadFile(htmlPath)
+		// #nosec G304 -- visual evidence files inside the workspace
 		outlineBody, oerr := os.ReadFile(outlinePath)
 		switch {
 		case herr != nil:
@@ -239,12 +241,15 @@ func openLocalFile(path string) error {
 	switch runtime.GOOS {
 	case "darwin":
 		// argv only — no shell.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("open", path)
 	case "windows":
 		// Avoid cmd.exe /c shell composition; FileProtocolHandler takes one path argv.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("rundll32.exe", "url.dll,FileProtocolHandler", path)
 	default:
 		// argv only — no shell.
+		// #nosec G204 -- fixed platform opener; path passed as argv, no shell
 		cmd = exec.Command("xdg-open", path)
 	}
 	if err := cmd.Start(); err != nil {

package/engine/internal/lib/resolve.go

@@ -35,6 +35,9 @@ func Resolve(root string, args []string, stdout, stderr io.Writer) int {
 	if !isFile(sfile) {
 		return fail(stderr, "state.md missing at "+sfile, 2)
 	}
+	if err := state.RequireWorkspaceSchema(root, slug); err != nil {
+		return fail(stderr, err.Error(), 3)
+	}
 
 	var mode, qid, payload string
 	switch first := argAt(args, 0); first {
@@ -95,6 +98,7 @@ func resolveMutation(mode, qid, payload, qfile, sfile string, stdout, stderr io.
 		fmt.Fprintf(stdout, "Reason:   %s\n", payload)
 		fmt.Fprintf(stdout, "Workspace: questions.md + state.md updated.\n")
 	case "batch":
+		// #nosec G304 -- operator-passed --batch file argument
 		data, err := os.ReadFile(payload)
 		if err != nil {
 			return fail(stderr, "Batch file not found: "+payload, 5)
@@ -185,6 +189,7 @@ func nowUTC() string { return clockNow().UTC().Format("2006-01-02T15:04:05Z") }
 // status, answer, and answered-at time in one pass. Returns 0, or 3 (qid
 // not found) / 4 (qid not open), writing the message on failure.
 func resolveQuestion(qfile, qid, status, answer string, stderr io.Writer) int {
+	// #nosec G304 -- questions.md path inside the feature workspace
 	data, err := os.ReadFile(qfile)
 	if err != nil {
 		return fail(stderr, "questions.md missing at "+qfile, 2)
@@ -281,6 +286,7 @@ var (
 // running, clears the Next step, and appends a Log entry. It is a no-op when the
 // workspace is not waiting on this question.
 func clearAwaiting(sfile, qid string) error {
+	// #nosec G304 -- state.md path inside the feature workspace
 	data, err := os.ReadFile(sfile)
 	if err != nil {
 		return fmt.Errorf("read state %s: %w", sfile, err)

package/engine/internal/lib/resolve_remediation_test.go

@@ -55,6 +55,6 @@ func resolveWorkspace(t *testing.T, questions string) string {
 	root := t.TempDir()
 	testutil.WriteFile(t, filepath.Join(root, "ACTIVE"), "feat\n")
 	testutil.WriteFile(t, filepath.Join(root, "work", "feat", "questions.md"), questions)
-	testutil.WriteFile(t, filepath.Join(root, "work", "feat", "state.md"), "- Status: running\n- Next step: continue\n")
+	testutil.WriteFile(t, filepath.Join(root, "work", "feat", "state.md"), "- Status: running\n- Next step: continue\n- Schema: 3\n")
 	return root
 }

package/engine/internal/lib/secretscan.go

@@ -385,6 +385,7 @@ func scanWorktreePaths(project string, paths []string, budget *secretScanBudget)
 		if info.Size() < 0 || info.Size() > budget.bytesRemaining {
 			return nil, errSecretScanLimit
 		}
+		// #nosec G304 -- workspace walk; size budget checked above
 		file, err := os.Open(fullPath)
 		if err != nil {
 			return nil, err

package/engine/internal/lib/secretscan_test.go

@@ -348,6 +348,7 @@ func TestSecretScanBlocksHighSeverityTouchedFile(t *testing.T) {
 	root := filepath.Join(project, ".devrites")
 	testutil.WriteFile(t, filepath.Join(root, "ACTIVE"), "leak\n")
 	testutil.WriteFile(t, filepath.Join(root, "work", "leak", "touched-files.md"), candidateTestManifest(candidateTestRow{state: "present", path: "secrets.txt", slice: "S-1", reason: "Credential check."}))
+	testutil.WriteFile(t, filepath.Join(root, "work", "leak", "state.md"), "| schema | 3 |\n")
 	secret := "ghp_" + strings.Repeat("f", 32)
 	testutil.WriteFile(t, filepath.Join(project, "secrets.txt"), secret+"\n")
 	var out, err bytes.Buffer

package/engine/internal/lib/skilltrust.go

@@ -68,11 +68,12 @@ func ScanSkillTrust(path string) (SkillTrustResult, error) {
 	if info.Size() > 1<<20 {
 		return SkillTrustResult{}, fmt.Errorf("skill-trust: %q exceeds 1 MiB limit", path)
 	}
+	// #nosec G304 -- installed skill file; 1 MiB cap checked above
 	file, err := os.Open(path)
 	if err != nil {
 		return SkillTrustResult{}, err
 	}
-	defer file.Close()
+	defer func() { _ = file.Close() }()
 	raw, err := io.ReadAll(io.LimitReader(file, 1<<20+1))
 	if err != nil {
 		return SkillTrustResult{}, err

package/engine/internal/lib/taskgraph_test.go

@@ -259,7 +259,7 @@ func TestObserveSummaryExposesTaskGraphProblems(t *testing.T) {
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | define |\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | define |\n| schema | 3 |\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	body := `# Tasks
@@ -308,7 +308,7 @@ func TestObserveSummaryExposesProblemsWhenNoSliceHeaders(t *testing.T) {
 	if err := os.MkdirAll(workspace, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | define |\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(workspace, "state.md"), []byte("| phase | define |\n| schema | 3 |\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	if err := os.WriteFile(filepath.Join(workspace, "tasks.md"), []byte("# Tasks\n\n- do the work\n"), 0o644); err != nil {

package/engine/internal/lib/util.go

@@ -65,6 +65,7 @@ func runGitCommandIO(dir string, env []string, input []byte, stdout io.Writer, a
 	ctx, cancel := context.WithTimeout(context.Background(), gitCommandTimeout)
 	defer cancel()
 	commandArgs := append([]string{"-C", dir}, args...)
+	// #nosec G204 -- git -C <operator repo dir>; fixed binary, sanitized env
 	cmd := exec.CommandContext(ctx, "git", commandArgs...)
 	cmd.WaitDelay = 2 * time.Second
 	if input != nil {

package/engine/internal/lib/workspace_read.go

@@ -21,6 +21,7 @@ func readWorkspaceArtifact(root, slug, name string) ([]byte, error) {
 	if info.Size() > 1<<20 {
 		return nil, fmt.Errorf("task-graph: %s exceeds 1 MiB limit", name)
 	}
+	// #nosec G304 -- workspace task-graph file; 1 MiB cap checked above
 	raw, err := os.ReadFile(path)
 	if err != nil {
 		return nil, fmt.Errorf("task-graph: cannot read %s: %w", name, err)