devrites 2.6.1 → 3.0.0

package/engine/internal/migrate/migrate.go

@@ -0,0 +1,213 @@
+// Package migrate normalizes .devrites workspaces in place. work/<slug> is the
+// canonical layout; features/<slug> remains readable as a compatibility alias.
+// The normalizer adds canonical files without deleting aliases. It is idempotent
+// and backs up the pre-migration state before touching anything, so a botched
+// upgrade never strands work.
+package migrate
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"slices"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/devrites/devrites/internal/fsutil"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// Result reports what a migration did. Skipped is true when there was nothing to
+// migrate (a no-op re-run); Migrated lists the slugs upgraded this run; BackupDir
+// is the pre-migration snapshot (empty when Skipped).
+type Result struct {
+	Skipped   bool
+	Migrated  []string
+	BackupDir string
+}
+
+type normalizationTarget struct {
+	slug string
+	dir  string
+}
+
+// Run normalizes the workspace at root. If no feature directory needs additive
+// files, it returns Skipped without writing or backing up anything (idempotent).
+// Otherwise it snapshots the state, then writes missing canonical files.
+func Run(root string) (*Result, error) {
+	targets, err := featureDirsNeedingNormalization(root)
+	if err != nil {
+		return nil, fmt.Errorf("scan workspace: %w", err)
+	}
+	if len(targets) == 0 {
+		return &Result{Skipped: true}, nil
+	}
+
+	backup, err := backupWorkspace(root)
+	if err != nil {
+		return nil, fmt.Errorf("backup workspace: %w", err)
+	}
+	migrated := make([]string, 0, len(targets))
+	for _, target := range targets {
+		if err := normalizeFeatureDir(target.dir, target.slug); err != nil {
+			return nil, fmt.Errorf("normalize %q: %w", target.slug, err)
+		}
+		migrated = append(migrated, target.slug)
+	}
+	sort.Strings(migrated)
+	return &Result{Migrated: slices.Compact(migrated), BackupDir: backup}, nil
+}
+
+func featureDirsNeedingNormalization(root string) ([]normalizationTarget, error) {
+	var targets []normalizationTarget
+	for _, layout := range []string{"work", "features"} {
+		base := filepath.Join(root, layout)
+		entries, err := os.ReadDir(base)
+		if os.IsNotExist(err) {
+			continue
+		}
+		if err != nil {
+			return nil, fmt.Errorf("list feature dirs: %w", err)
+		}
+		for _, e := range entries {
+			if !e.IsDir() {
+				continue
+			}
+			dir := filepath.Join(base, e.Name())
+			if needsNormalizeFeature(dir) {
+				targets = append(targets, normalizationTarget{slug: e.Name(), dir: dir})
+			}
+		}
+	}
+	sort.Slice(targets, func(i, j int) bool {
+		if targets[i].slug != targets[j].slug {
+			return targets[i].slug < targets[j].slug
+		}
+		return targets[i].dir < targets[j].dir
+	})
+	return targets, nil
+}
+
+func needsNormalizeFeature(dir string) bool {
+	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+		return true
+	}
+	return regularFileExists(filepath.Join(dir, "evidence.md")) && !regularFileExists(filepath.Join(dir, "proof.md")) ||
+		regularFileExists(filepath.Join(dir, state.LedgerFile)) && !regularFileExists(filepath.Join(dir, "status.md"))
+}
+
+func regularFileExists(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.Mode().IsRegular()
+}
+
+func normalizeFeatureDir(dir, slug string) error {
+	if !regularFileExists(filepath.Join(dir, "feature.md")) {
+		phase := derivePhase(filepath.Join(dir, state.LedgerFile))
+		if err := state.AtomicWrite(filepath.Join(dir, "feature.md"), []byte(featureIndex(slug, phase)), 0o644); err != nil {
+			return fmt.Errorf("write feature index: %w", err)
+		}
+	}
+	if err := copyAliasFile(dir, "evidence.md", "proof.md"); err != nil {
+		return fmt.Errorf("copy evidence.md to proof.md: %w", err)
+	}
+	return copyAliasFile(dir, state.LedgerFile, "status.md")
+}
+
+func copyAliasFile(dir, alias, canonical string) error {
+	src := filepath.Join(dir, alias)
+	dst := filepath.Join(dir, canonical)
+	if !regularFileExists(src) || regularFileExists(dst) {
+		return nil
+	}
+	data, err := os.ReadFile(src)
+	if err != nil {
+		return fmt.Errorf("read alias file: %w", err)
+	}
+	return state.AtomicWrite(dst, data, 0o644)
+}
+
+// featureIndex renders the manifest added to a normalized workspace.
+func featureIndex(slug string, phase state.Phase) string {
+	return fmt.Sprintf(`---
+slug: %s
+title: %s
+phase: %s
+schemaVersion: %d
+---
+
+Normalized by DevRites migration.
+`, slug, slug, phase, state.SchemaVersion)
+}
+
+// derivePhase reads the legacy state.md and maps its recorded phase/status onto a
+// v1 phase. An unreadable or unrecognised state defaults to build — the safe
+// middle of the arc, from which the completeness gates re-derive what's missing.
+func derivePhase(statePath string) state.Phase {
+	raw, err := os.ReadFile(statePath)
+	if err != nil {
+		return state.PhaseBuild
+	}
+	for _, line := range strings.Split(string(raw), "\n") {
+		t := strings.TrimLeft(strings.ToLower(strings.TrimSpace(line)), "-*+ \t")
+		key, val, ok := strings.Cut(t, ":")
+		if !ok || (strings.TrimSpace(key) != "phase" && strings.TrimSpace(key) != "status") {
+			continue
+		}
+		if p, ok := mapLegacyPhase(strings.TrimSpace(val)); ok {
+			return p
+		}
+	}
+	return state.PhaseBuild
+}
+
+// mapLegacyPhase maps a legacy phase/status word onto a v1 phase.
+func mapLegacyPhase(word string) (state.Phase, bool) {
+	// Take the first token, so "done — shipped 2024" maps on "done".
+	if i := strings.IndexAny(word, " \t—-"); i > 0 {
+		word = word[:i]
+	}
+	switch word {
+	case "frame":
+		return state.PhaseFrame, true
+	case "spec", "specced", "specifying":
+		return state.PhaseSpec, true
+	case "plan", "planned", "define", "defined":
+		return state.PhasePlan, true
+	case "build", "building", "wip", "in", "in-progress":
+		return state.PhaseBuild, true
+	case "prove", "proving", "proven", "testing":
+		return state.PhaseProve, true
+	case "vet", "review", "reviewing", "vetting":
+		return state.PhaseVet, true
+	case "seal", "sealed", "sealing":
+		return state.PhaseSeal, true
+	case "ship", "shipped", "done", "closed", "complete", "completed":
+		return state.PhaseShip, true
+	default:
+		return "", false
+	}
+}
+
+// backupWorkspace snapshots mutable state (work/, features/, and the ACTIVE pointer) into
+// a timestamped, gitignored backup directory under root before any change.
+func backupWorkspace(root string) (string, error) {
+	backup := filepath.Join(root, fmt.Sprintf(".migrate-backup-%d", time.Now().UnixNano()))
+	if err := fsutil.CopyTree(filepath.Join(root, "work"), filepath.Join(backup, "work")); err != nil {
+		return "", fmt.Errorf("copy work tree: %w", err)
+	}
+	if err := fsutil.CopyTree(filepath.Join(root, "features"), filepath.Join(backup, "features")); err != nil {
+		return "", fmt.Errorf("copy features tree: %w", err)
+	}
+	// The ACTIVE pointer is a single small file; copy it if present.
+	if data, err := os.ReadFile(filepath.Join(root, "ACTIVE")); err == nil {
+		if err := os.MkdirAll(backup, 0o755); err != nil {
+			return "", fmt.Errorf("create backup dir: %w", err)
+		}
+		if err := os.WriteFile(filepath.Join(backup, "ACTIVE"), data, 0o644); err != nil {
+			return "", fmt.Errorf("copy ACTIVE pointer: %w", err)
+		}
+	}
+	return backup, nil
+}

package/engine/internal/migrate/migrate_test.go

@@ -0,0 +1,105 @@
+package migrate
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/state"
+	"github.com/devrites/devrites/internal/testutil"
+)
+
+func TestRunNormalizesCanonicalWorkLayout(t *testing.T) {
+	root := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(root, "ACTIVE"), "alpha\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/alpha/spec.md"), "spec\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/alpha/plan.md"), "plan\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/alpha/evidence.md"), "proof\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/alpha/state.md"), "status: done - shipped\n")
+	testutil.WriteFile(t, filepath.Join(root, "work/alpha/review.md"), "review\n")
+
+	res, err := Run(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Skipped {
+		t.Fatalf("Run skipped=true, want migration")
+	}
+	if got := strings.Join(res.Migrated, ","); got != "alpha" {
+		t.Fatalf("Run migrated=%q, want alpha", got)
+	}
+	if res.BackupDir == "" {
+		t.Fatalf("Run backup dir empty")
+	}
+
+	assertFile(t, root, "work/alpha/spec.md", "spec\n")
+	assertFile(t, root, "work/alpha/proof.md", "proof\n")
+	assertFile(t, root, "work/alpha/status.md", "status: done - shipped\n")
+	assertFile(t, root, "work/alpha/review.md", "review\n")
+
+	f, err := state.LoadFeature(root, "alpha")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.Phase != state.PhaseShip {
+		t.Fatalf("migrated phase=%q, want %q", f.Phase, state.PhaseShip)
+	}
+	assertFile(t, res.BackupDir, "ACTIVE", "alpha\n")
+
+	again, err := Run(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !again.Skipped {
+		t.Fatalf("second Run skipped=false, migrated=%v", again.Migrated)
+	}
+}
+
+func TestRunNormalizesLiveFeatureAliases(t *testing.T) {
+	root := t.TempDir()
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/state.md"), "- Phase: prove\n")
+	testutil.WriteFile(t, filepath.Join(root, "features/beta/evidence.md"), "evidence\n")
+
+	res, err := Run(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Join(res.Migrated, ","); got != "beta" {
+		t.Fatalf("Run normalized=%q, want beta", got)
+	}
+	assertFile(t, root, "features/beta/status.md", "- Phase: prove\n")
+	assertFile(t, root, "features/beta/proof.md", "evidence\n")
+
+	f, err := state.LoadFeature(root, "beta")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if f.Phase != state.PhaseProve {
+		t.Fatalf("normalized phase=%q, want %q", f.Phase, state.PhaseProve)
+	}
+}
+
+func TestMapLegacyPhase(t *testing.T) {
+	for _, tc := range []struct {
+		word string
+		want state.Phase
+		ok   bool
+	}{
+		{word: "specced", want: state.PhaseSpec, ok: true},
+		{word: "in-progress", want: state.PhaseBuild, ok: true},
+		{word: "done - shipped", want: state.PhaseShip, ok: true},
+		{word: "mystery"},
+	} {
+		got, ok := mapLegacyPhase(tc.word)
+		if got != tc.want || ok != tc.ok {
+			t.Fatalf("mapLegacyPhase(%q)=(%q,%v), want (%q,%v)", tc.word, got, ok, tc.want, tc.ok)
+		}
+	}
+}
+
+func assertFile(t *testing.T, root, rel, want string) {
+	t.Helper()
+	if got := testutil.ReadFile(t, filepath.Join(root, rel)); got != want {
+		t.Fatalf("%s=%q, want %q", rel, got, want)
+	}
+}

package/engine/internal/orient/firstrun.go

@@ -0,0 +1,50 @@
+package orient
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/devrites/devrites/internal/lib"
+)
+
+// FirstRunFile names the marker, under the .devrites root, that records that the
+// one-time blank-slate orientation has been shown. It is runtime state like
+// ACTIVE: preserved on uninstall, so a reinstall never re-nags.
+const FirstRunFile = ".first-run-shown"
+
+// firstRunNudges maps each first-task token to the single orientation line shown
+// on the first-ever session with no active feature. A token missing here (or a
+// future new token) stays silent — the nudge is an enhancement, never a
+// dependency, and prose is owned here rather than in the classifier.
+var firstRunNudges = map[string]string{
+	"greenfield":           "Greenfield project — start with /rite-spec <feature> to spec the first feature.",
+	"brownfield-unadopted": "Existing codebase with no DevRites history — start with /rite-adopt to onboard it.",
+	"dirty-worktree":       "Uncommitted changes in the worktree — /rite-frame the work in flight, or /rite-quick for a small fix.",
+	"branch-ahead":         "Branch is ahead of its upstream — /rite-review then /rite-ship the unshipped work.",
+	"clean-default":        "No active feature — /rite-spec <feature> starts the next one; /rite shows the menu.",
+}
+
+// FirstRunDigest returns the one-time blank-slate orientation for a workspace
+// with no active feature. It fires at most once per project: the marker is
+// written before the text is returned, and a marker that cannot be written
+// keeps the digest silent so a broken filesystem never turns into a per-session
+// nag. Fail-open throughout — every non-happy path is ("", false).
+func FirstRunDigest(root string) (text string, has bool) {
+	marker := filepath.Join(root, FirstRunFile)
+	if _, err := os.Stat(marker); err == nil {
+		return "", false
+	}
+	nudge, ok := firstRunNudges[lib.FirstTaskToken(root)]
+	if !ok {
+		return "", false
+	}
+	f, err := os.OpenFile(marker, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+	if err != nil {
+		return "", false // marker unwritable (or raced) — silent rather than nagging
+	}
+	if err := f.Close(); err != nil {
+		return "", false
+	}
+	return "DevRites is installed but no feature is active. " + nudge +
+		"\n(One-time orientation; /rite shows the full menu.)", true
+}

package/engine/internal/orient/firstrun_test.go

@@ -0,0 +1,72 @@
+package orient
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func newBlankRoot(t *testing.T) string {
+	t.Helper()
+	root := filepath.Join(t.TempDir(), ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, ActiveFile), nil, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	return root
+}
+
+func TestFirstRunDigestGreenfieldNudgesOnce(t *testing.T) {
+	root := newBlankRoot(t)
+	text, has := FirstRunDigest(root)
+	if !has {
+		t.Fatal("first call: want a nudge, got silence")
+	}
+	if !strings.Contains(text, "/rite-spec") {
+		t.Fatalf("greenfield nudge should point at /rite-spec, got %q", text)
+	}
+	if _, err := os.Stat(filepath.Join(root, FirstRunFile)); err != nil {
+		t.Fatalf("marker not written: %v", err)
+	}
+	if _, has = FirstRunDigest(root); has {
+		t.Fatal("second call: want silence, marker should suppress")
+	}
+}
+
+func TestFirstRunDigestBrownfieldPointsAtAdopt(t *testing.T) {
+	root := newBlankRoot(t)
+	project := filepath.Dir(root)
+	if err := os.WriteFile(filepath.Join(project, "package.json"), []byte("{}"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	text, has := FirstRunDigest(root)
+	if !has {
+		t.Fatal("want a nudge, got silence")
+	}
+	if !strings.Contains(text, "/rite-adopt") {
+		t.Fatalf("brownfield nudge should point at /rite-adopt, got %q", text)
+	}
+}
+
+func TestFirstRunDigestActiveFeatureStaysSilent(t *testing.T) {
+	root := newBlankRoot(t)
+	if err := os.WriteFile(filepath.Join(root, ActiveFile), []byte("some-feature\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if _, has := FirstRunDigest(root); has {
+		t.Fatal("active feature: first-run nudge must stay silent")
+	}
+	if _, err := os.Stat(filepath.Join(root, FirstRunFile)); !os.IsNotExist(err) {
+		t.Fatalf("active feature must not consume the first-run marker, stat err = %v", err)
+	}
+}
+
+func TestFirstRunDigestUnwritableMarkerStaysSilent(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "missing", ".devrites")
+	if _, has := FirstRunDigest(root); has {
+		t.Fatal("unwritable marker: want silence, never a per-session nag")
+	}
+}

package/engine/internal/orient/orient.go

@@ -0,0 +1,69 @@
+// Package orient builds the SessionStart orientation digest injected at the top
+// of a session, so the model knows a DevRites workflow is in flight and where it
+// stands. It reads workspace state from files and makes zero model or network calls. It is silent
+// when there is nothing to say, mirroring the legacy devrites-orient.sh: an
+// enhancement, never a dependency.
+package orient
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/devrites/devrites/internal/devritespaths"
+	"github.com/devrites/devrites/internal/lib"
+	"github.com/devrites/devrites/internal/state"
+)
+
+// ActiveFile names the pointer file, under the .devrites root, that records the
+// slug of the feature currently being worked. An absent or empty pointer means
+// no feature is active and orientation stays silent.
+const ActiveFile = "ACTIVE"
+
+// Digest returns the orientation text for the workspace at root and whether
+// there is anything to say. It returns ("", false, nil) — silent, not an error —
+// when no feature is active or the active pointer is stale, so a session is never
+// disrupted by a missing or half-set-up workspace.
+func Digest(root string) (text string, has bool, err error) {
+	slug, err := ActiveSlug(root)
+	if err != nil {
+		return "", false, fmt.Errorf("orient digest: %w", err)
+	}
+	if slug == "" {
+		return "", false, nil
+	}
+
+	// A stale pointer (names a feature that no longer exists) stays silent
+	// rather than erroring — orientation must never be a session dependency.
+	report, err := state.Status(root, slug)
+	if err != nil {
+		return "", false, nil
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "DevRites workflow active — feature %q at phase %q.\n\n", report.Slug, report.Phase)
+	b.WriteString(report.Render())
+
+	// Surface only the high-confidence, human-promoted learnings, capped so a
+	// growing ledger never bloats the session. Bounds come from
+	// DEVRITES_LEARNING_CONFIDENCE_THRESHOLD / DEVRITES_MAX_INJECTED_LEARNINGS.
+	if picks := lib.TopLearnings(root, lib.InjectMax(), lib.InjectThreshold()); len(picks) > 0 {
+		b.WriteString("\n\nHigh-confidence learnings (untrusted prior — live code always wins):\n")
+		for _, p := range picks {
+			b.WriteString(p)
+			b.WriteByte('\n')
+		}
+	}
+
+	b.WriteString("\nThis is the current state; the next host-specific DevRites command (/rite-* in Claude Code, $rite-* in Codex) will re-run its own step-0 preamble.")
+	return b.String(), true, nil
+}
+
+// ActiveSlug reads and trims the active-feature pointer. A missing pointer file
+// is not an error — it yields the empty slug (no active feature).
+func ActiveSlug(root string) (string, error) {
+	return devritespaths.ActiveSlug(root)
+}
+
+// ResolveRoot is a thin re-export so hook callers can fail open on a
+// non-DevRites directory without importing state directly.
+var ResolveRoot = state.ResolveRoot

package/engine/internal/orient/orient_test.go

@@ -0,0 +1,25 @@
+package orient
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestActiveSlugHonorsExplicitWorkspace(t *testing.T) {
+	root := filepath.Join(t.TempDir(), ".devrites")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, ActiveFile), []byte("other\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DEVRITES_WORKSPACE", filepath.Join(root, "work", "explicit"))
+	slug, err := ActiveSlug(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if slug != "explicit" {
+		t.Fatalf("ActiveSlug = %q, want explicit", slug)
+	}
+}