devrites 2.6.1 → 3.0.0

package/engine/internal/lib/session.go

@@ -0,0 +1,328 @@
+package lib
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/devrites/devrites/internal/fsutil"
+)
+
+type timelineEntry struct {
+	TS       string `json:"ts"`
+	Event    string `json:"event"`
+	Skill    string `json:"skill,omitempty"`
+	Slug     string `json:"slug,omitempty"`
+	Outcome  string `json:"outcome,omitempty"`
+	Decision string `json:"decision,omitempty"`
+	From     string `json:"from,omitempty"`
+	To       string `json:"to,omitempty"`
+	Note     string `json:"note,omitempty"`
+}
+
+type healthEntry struct {
+	TS    string  `json:"ts"`
+	Score float64 `json:"score"`
+	Label string  `json:"label"`
+	Note  string  `json:"note,omitempty"`
+}
+
+type reviewFingerprint struct {
+	ID       string `json:"id"`
+	Severity string `json:"severity"`
+	Text     string `json:"text"`
+}
+
+// Timeline is the append-only session trace: what happened, which gate/skill did
+// it, and which durable decision or state transition resulted.
+func Timeline(root string, args []string, stdout, stderr io.Writer) int {
+	switch argAt(args, 0) {
+	case "log":
+		entry := timelineEntry{TS: nowUTC()}
+		rest := args[1:]
+		if len(rest) > 0 && !strings.HasPrefix(rest[0], "--") {
+			entry.Event = rest[0]
+			rest = rest[1:]
+		}
+		for i := 0; i < len(rest); i++ {
+			next := func(name string) (string, bool) {
+				i++
+				if i >= len(rest) {
+					fmt.Fprintf(stderr, "timeline: %s needs a value\n", name)
+					return "", false
+				}
+				return rest[i], true
+			}
+			switch rest[i] {
+			case "--event":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Event = v
+			case "--skill":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Skill = v
+			case "--slug":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Slug = v
+			case "--outcome":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Outcome = v
+			case "--decision":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Decision = v
+			case "--from":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.From = v
+			case "--to":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.To = v
+			case "--note":
+				v, ok := next(rest[i])
+				if !ok {
+					return 2
+				}
+				entry.Note = v
+			default:
+				fmt.Fprintf(stderr, "timeline: unknown option %s\n", rest[i])
+				return 2
+			}
+		}
+		if entry.Event == "" {
+			fmt.Fprintln(stderr, "usage: devrites-engine timeline log <event> [--skill S] [--slug S] [--outcome O] [--decision D] [--from A --to B] [--note N]")
+			return 2
+		}
+		if err := appendJSONLine(filepath.Join(root, "timeline.jsonl"), entry); err != nil {
+			fmt.Fprintf(stderr, "timeline: %v\n", err)
+			return 1
+		}
+		fmt.Fprintln(stdout, "timeline: recorded.")
+		return 0
+	case "list":
+		limit := 20
+		if argAt(args, 1) == "--limit" {
+			n, err := strconv.Atoi(argAt(args, 2))
+			if err != nil || n < 0 {
+				fmt.Fprintln(stderr, "timeline: --limit must be a non-negative integer")
+				return 2
+			}
+			limit = n
+		}
+		printTail(filepath.Join(root, "timeline.jsonl"), limit, "timeline", stdout)
+		return 0
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine timeline log|list [...]")
+		return 2
+	}
+}
+
+// Health records one compact score (legacy record/list) or runs the project code-health dashboard.
+func Health(root string, args []string, stdout, stderr io.Writer) int {
+	if len(args) == 0 || argAt(args, 0) == "run" || argAt(args, 0) == "check" {
+		return CodeHealth(root, args, stdout, stderr)
+	}
+	switch argAt(args, 0) {
+	case "record":
+		score, ok := parseHealthScore(argAt(args, 1))
+		if !ok {
+			fmt.Fprintln(stderr, "usage: devrites-engine health record <score 0..10> <label> [--note N]")
+			return 2
+		}
+		labelParts := []string{}
+		note := ""
+		for i := 2; i < len(args); i++ {
+			if args[i] == "--note" {
+				i++
+				if i >= len(args) {
+					fmt.Fprintln(stderr, "health: --note needs a value")
+					return 2
+				}
+				note = args[i]
+				continue
+			}
+			labelParts = append(labelParts, args[i])
+		}
+		label := strings.TrimSpace(strings.Join(labelParts, " "))
+		if label == "" {
+			fmt.Fprintln(stderr, "usage: devrites-engine health record <score 0..10> <label> [--note N]")
+			return 2
+		}
+		if err := appendJSONLine(filepath.Join(root, "health-history.jsonl"), healthEntry{
+			TS:    nowUTC(),
+			Score: score,
+			Label: label,
+			Note:  note,
+		}); err != nil {
+			fmt.Fprintf(stderr, "health: %v\n", err)
+			return 1
+		}
+		fmt.Fprintln(stdout, "health: recorded.")
+		return 0
+	case "list":
+		limit := 20
+		if argAt(args, 1) == "--limit" {
+			n, err := strconv.Atoi(argAt(args, 2))
+			if err != nil || n < 0 {
+				fmt.Fprintln(stderr, "health: --limit must be a non-negative integer")
+				return 2
+			}
+			limit = n
+		}
+		path := filepath.Join(root, "health.jsonl")
+		if !isFile(path) {
+			path = filepath.Join(root, "health-history.jsonl")
+		}
+		printTail(path, limit, "health", stdout)
+		return 0
+	default:
+		fmt.Fprintln(stderr, "usage: devrites-engine health [run|check] | record|list [...]")
+		return 2
+	}
+}
+
+func ReviewFingerprints(root string, args []string, stdout, stderr io.Writer) int {
+	write := false
+	slug := ""
+	for _, a := range args {
+		if a == "--write" {
+			write = true
+			continue
+		}
+		if slug == "" {
+			slug = a
+		}
+	}
+	if slug == "" {
+		slug = activeSlug(root)
+	}
+	if slug == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine review-fingerprints [--write] <slug>")
+		return 2
+	}
+	dir := featureDir(root, slug)
+	review, ok := readFileOK(filepath.Join(dir, "review.md"))
+	if !ok {
+		fmt.Fprintln(stdout, "review-fingerprints: no review.md — nothing to fingerprint.")
+		return 0
+	}
+	records := reviewFindingFingerprints(review)
+	if len(records) == 0 {
+		fmt.Fprintln(stdout, "review-fingerprints: no findings.")
+		return 0
+	}
+	var jsonl strings.Builder
+	for _, r := range records {
+		fmt.Fprintf(stdout, "%s %s %s\n", r.ID, r.Severity, r.Text)
+		if b, err := json.Marshal(r); err == nil {
+			jsonl.Write(b)
+			jsonl.WriteByte('\n')
+		}
+	}
+	if write {
+		if err := fsutil.WriteFileAtomic(filepath.Join(dir, "review-fingerprints.jsonl"), []byte(jsonl.String()), 0o644); err != nil {
+			fmt.Fprintf(stderr, "review-fingerprints: %v\n", err)
+			return 1
+		}
+	}
+	return 0
+}
+
+func reviewFindingFingerprints(md string) []reviewFingerprint {
+	var out []reviewFingerprint
+	for _, line := range markdownLines(md) {
+		m := findingLabel.FindStringSubmatch(line)
+		if m == nil {
+			continue
+		}
+		text := normalizeFindingLine(line)
+		sum := sha256.Sum256([]byte(strings.ToLower(m[1]) + "\n" + text))
+		out = append(out, reviewFingerprint{
+			ID:       hex.EncodeToString(sum[:])[:12],
+			Severity: m[1],
+			Text:     text,
+		})
+	}
+	return out
+}
+
+func normalizeFindingLine(line string) string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "-")
+	line = strings.TrimSpace(line)
+	return strings.Join(strings.Fields(line), " ")
+}
+
+func markdownLines(md string) []string {
+	md = strings.TrimRight(md, "\n")
+	if md == "" {
+		return nil
+	}
+	return strings.Split(md, "\n")
+}
+
+func parseHealthScore(s string) (float64, bool) {
+	score, err := strconv.ParseFloat(strings.TrimSpace(s), 64)
+	if err != nil || score < 0 || score > 10 {
+		return 0, false
+	}
+	return score, true
+}
+
+func appendJSONLine(path string, v any) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return fmt.Errorf("create log dir: %w", err)
+	}
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		return fmt.Errorf("append log: %w", err)
+	}
+	defer f.Close()
+	b, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Errorf("marshal entry: %w", err)
+	}
+	if _, err := f.Write(append(b, '\n')); err != nil {
+		return fmt.Errorf("append log: %w", err)
+	}
+	return nil
+}
+
+func printTail(path string, limit int, label string, stdout io.Writer) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		fmt.Fprintf(stdout, "%s: no history at %s.\n", label, path)
+		return
+	}
+	lines := splitLinesNoTrailing(data)
+	if limit > 0 && len(lines) > limit {
+		lines = lines[len(lines)-limit:]
+	}
+	for _, line := range lines {
+		fmt.Fprintln(stdout, line)
+	}
+}

package/engine/internal/lib/session_test.go

@@ -0,0 +1,110 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestTimelineLogAndList(t *testing.T) {
+	t.Setenv("DEVRITES_NOW", "2026-07-09T10:11:12Z")
+	root := t.TempDir()
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+
+	code := Timeline(root, []string{"log", "completed", "--skill", "rite-review", "--slug", "auth", "--outcome", "ok", "--decision", "ship"}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("timeline log failed: code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	data, err := os.ReadFile(filepath.Join(root, "timeline.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := string(data)
+	for _, want := range []string{`"ts":"2026-07-09T10:11:12Z"`, `"event":"completed"`, `"skill":"rite-review"`, `"slug":"auth"`, `"decision":"ship"`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("timeline entry missing %s: %s", want, got)
+		}
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := Timeline(root, []string{"list", "--limit", "1"}, stdout, stderr); code != 0 {
+		t.Fatalf("timeline list failed: %d %s", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), `"event":"completed"`) {
+		t.Fatalf("timeline list did not print entry: %q", stdout.String())
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := Timeline(root, []string{"log", "completed", "--skill"}, stdout, stderr); code != 2 {
+		t.Fatalf("missing timeline option value should be usage error, got %d", code)
+	}
+}
+
+func TestHealthRecordValidatesScore(t *testing.T) {
+	t.Setenv("DEVRITES_NOW", "2026-07-09")
+	root := t.TempDir()
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+
+	code := Health(root, []string{"record", "9.5", "ci green", "--note", "staticcheck+tests"}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("health record failed: code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	data, err := os.ReadFile(filepath.Join(root, "health-history.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := string(data)
+	for _, want := range []string{`"score":9.5`, `"label":"ci green"`, `"note":"staticcheck+tests"`} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("health entry missing %s: %s", want, got)
+		}
+	}
+
+	stdout.Reset()
+	stderr.Reset()
+	if code := Health(root, []string{"record", "11", "too high"}, stdout, stderr); code != 2 {
+		t.Fatalf("out-of-range score should be usage error, got %d", code)
+	}
+}
+
+func TestReviewFingerprintsStableAndWritable(t *testing.T) {
+	root := t.TempDir()
+	writeReview(t, root, "feat", `# Review
+
+## Spec
+- **Critical** — AC-003 is unproven.
+
+## Code review
+- **Important** — missing error handling.`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	code := ReviewFingerprints(root, []string{"--write", "feat"}, stdout, stderr)
+	if code != 0 {
+		t.Fatalf("review-fingerprints failed: code=%d stdout=%q stderr=%q", code, stdout.String(), stderr.String())
+	}
+	lines := strings.Split(strings.TrimSpace(stdout.String()), "\n")
+	if len(lines) != 2 {
+		t.Fatalf("expected 2 fingerprints, got %d: %q", len(lines), stdout.String())
+	}
+	firstID := strings.Fields(lines[0])[0]
+	if len(firstID) != 12 {
+		t.Fatalf("fingerprint id should be 12 hex chars, got %q", firstID)
+	}
+	stdout.Reset()
+	if code := ReviewFingerprints(root, []string{"feat"}, stdout, stderr); code != 0 {
+		t.Fatalf("second fingerprint run failed: %d", code)
+	}
+	if secondID := strings.Fields(strings.Split(strings.TrimSpace(stdout.String()), "\n")[0])[0]; secondID != firstID {
+		t.Fatalf("fingerprint changed across identical input: %s vs %s", firstID, secondID)
+	}
+	data, err := os.ReadFile(filepath.Join(root, "work", "feat", "review-fingerprints.jsonl"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(data), `"severity":"Critical"`) || !strings.Contains(string(data), `"severity":"Important"`) {
+		t.Fatalf("written JSONL missing severities: %s", string(data))
+	}
+}

package/engine/internal/lib/specparse.go

@@ -0,0 +1,125 @@
+package lib
+
+import (
+	"fmt"
+	"os"
+	"regexp"
+	"strings"
+)
+
+// Structured parse of a spec.md into its Requirement blocks, tagged with the
+// delta kind (added/modified/removed) and capability of the "## … Requirements
+// — capability: <c>" section they sit under. It is the shared reader behind two
+// consumers: the spec-validate `--against` ledger cross-check (specvalidate.go)
+// and the capability-ledger fold (ledger.go). The grammar linter (lintSpec) is
+// deliberately left untouched — delta H2 headers are transparent to it — so this
+// parser adds delta-awareness without perturbing the flat-spec lint contract.
+
+// Delta kinds, lower-cased. A requirement outside any delta section has kind "".
+const (
+	DeltaAdded    = "added"
+	DeltaModified = "modified"
+	DeltaRemoved  = "removed"
+)
+
+var (
+	// "## ADDED Requirements", "## Modified Requirements — capability: theming".
+	deltaSectionRe = regexp.MustCompile(`(?i)^[[:space:]]*##[[:space:]]+(ADDED|MODIFIED|REMOVED)[[:space:]]+Requirements\b`)
+	// The capability tag on a delta section header. Accepts an em dash, en dash,
+	// or hyphen separator; the capability token runs to end-of-line, trimmed.
+	capabilityTagRe = regexp.MustCompile(`(?i)capability:[[:space:]]*(.+?)[[:space:]]*$`)
+	// Any H2/H3 header terminates the preceding requirement block.
+	blockBoundaryRe = regexp.MustCompile(`^[[:space:]]*###?[[:space:]]`)
+)
+
+// Requirement is one "### Requirement: <name>" block with its delta context.
+type Requirement struct {
+	Name       string // header text after "Requirement:", trailing space trimmed
+	Key        string // strings.ToLower(Name) — the identity used to match across specs
+	Kind       string // added | modified | removed | "" (flat, no delta section)
+	Capability string // from the section tag; "" when untagged
+	HeaderLine int    // 1-based line of the "### Requirement:" header
+	Raw        string // the full block text (header through the line before the next ##/### or EOF), one trailing newline
+}
+
+// SpecDoc is the parsed view of a spec.md.
+type SpecDoc struct {
+	Requirements []Requirement
+	HasDelta     bool // at least one "## … Requirements" delta section was seen
+}
+
+// ParseSpec reads and structures a spec.md. It never fails on grammar problems —
+// that is lintSpec's job; ParseSpec only extracts blocks and their delta context.
+func ParseSpec(file string) (*SpecDoc, error) {
+	f, err := os.Open(file)
+	if err != nil {
+		return nil, fmt.Errorf("read spec: %w", err)
+	}
+	defer f.Close()
+
+	// Read all lines first so a requirement's Raw block can span forward to its
+	// boundary without a second pass.
+	var lines []string
+	sc := newLineScanner(f)
+	for sc.Scan() {
+		lines = append(lines, sc.Text())
+	}
+	if err := sc.Err(); err != nil {
+		return nil, fmt.Errorf("scan %s: %w", file, err)
+	}
+
+	doc := &SpecDoc{}
+	curKind := ""
+	curCap := ""
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+		if m := deltaSectionRe.FindStringSubmatch(line); m != nil {
+			doc.HasDelta = true
+			curKind = strings.ToLower(m[1])
+			curCap = ""
+			if c := capabilityTagRe.FindStringSubmatch(line); c != nil {
+				curCap = strings.TrimSpace(c[1])
+			}
+			continue
+		}
+		if reqHeaderRe.MatchString(line) {
+			name := trailWSRe.ReplaceAllString(reqPrefixRe.ReplaceAllString(line, ""), "")
+			// Raw block: this header line through the line before the next ##/###
+			// header or EOF, so a fold stores a self-contained block.
+			end := len(lines)
+			for j := i + 1; j < len(lines); j++ {
+				if blockBoundaryRe.MatchString(lines[j]) || deltaSectionRe.MatchString(lines[j]) {
+					end = j
+					break
+				}
+			}
+			raw := strings.Join(lines[i:end], "\n")
+			raw = strings.TrimRight(raw, "\n") + "\n"
+			doc.Requirements = append(doc.Requirements, Requirement{
+				Name:       name,
+				Key:        strings.ToLower(name),
+				Kind:       curKind,
+				Capability: curCap,
+				HeaderLine: i + 1,
+				Raw:        raw,
+			})
+		}
+	}
+	return doc, nil
+}
+
+// requirementKeys returns the set of lower-cased requirement names present in a
+// spec file — the identity index a cross-spec existence check consults. A missing
+// or unreadable file yields an empty set (the caller decides whether that is an
+// error), matching how the ledger treats an unseeded capability.
+func requirementKeys(file string) map[string]bool {
+	keys := map[string]bool{}
+	doc, err := ParseSpec(file)
+	if err != nil {
+		return keys
+	}
+	for _, r := range doc.Requirements {
+		keys[r.Key] = true
+	}
+	return keys
+}

package/engine/internal/lib/specskeleton.go

@@ -0,0 +1,79 @@
+package lib
+
+import (
+	"bufio"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+)
+
+var specSkeletonSections = []string{
+	"Problem",
+	"Goal",
+	"Non-goals",
+	"Users / actors",
+	"Requirements",
+	"Acceptance criteria",
+	"Edge Coverage",
+	"Prohibitions (must-NOT)",
+	"Edge cases",
+	"Measurable success",
+	"Scope boundaries",
+}
+
+// SpecSkeleton checks that a spec.md declares the required top-level contract
+// sections. It is separate from SpecValidate so the structured acceptance grammar
+// output remains stable.
+func SpecSkeleton(arg, cwd string, stdout, stderr io.Writer) int {
+	spec, code, ok := resolveSpecPath("spec-skeleton", arg, stderr)
+	if !ok {
+		return code
+	}
+
+	present, err := specTopLevelSections(spec)
+	if err != nil {
+		fmt.Fprintf(stderr, "spec-skeleton: %v\n", err)
+		return 2
+	}
+
+	rel := strings.TrimPrefix(spec, cwd+"/")
+	var missing []string
+	for _, section := range specSkeletonSections {
+		if !present[strings.ToLower(section)] {
+			missing = append(missing, section)
+		}
+	}
+	if len(missing) > 0 {
+		fmt.Fprintf(stdout, "spec-skeleton: BLOCKED — %s: missing top-level section(s): %s\n", rel, strings.Join(missing, ", "))
+		return 3
+	}
+
+	fmt.Fprintf(stdout, "spec-skeleton: OK — %s: all required top-level sections present\n", rel)
+	return 0
+}
+
+func specTopLevelSections(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("read spec: %w", err)
+	}
+	defer f.Close()
+
+	present := make(map[string]bool, len(specSkeletonSections))
+	sc := bufio.NewScanner(f)
+	sc.Buffer(make([]byte, 0, 64*1024), maxScanLine)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if !strings.HasPrefix(line, "## ") || strings.HasPrefix(line, "###") {
+			continue
+		}
+		heading := strings.TrimSpace(strings.TrimPrefix(line, "## "))
+		heading = strings.TrimRight(heading, "# \t")
+		present[strings.ToLower(heading)] = true
+	}
+	if err := sc.Err(); err != nil {
+		return nil, fmt.Errorf("scan %s: %w", path, err)
+	}
+	return present, nil
+}