devrites 2.6.1 → 3.0.0

package/engine/internal/lib/extensions_test.go

@@ -0,0 +1,305 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func writeExtSkill(t *testing.T, root, ext, frontmatter string) {
+	t.Helper()
+	dir := filepath.Join(root, "extensions", ext, "skill")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte(frontmatter), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func writeExtAgent(t *testing.T, root, ext, frontmatter string) {
+	t.Helper()
+	dir := filepath.Join(root, "extensions", ext)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "agent.md"), []byte(frontmatter), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+const goodSkill = "---\nname: rite-audit-lite\ndescription: A house audit rite.\n---\n\n# body\n"
+const goodAgent = "---\nname: house-reviewer\ndescription: A house reviewer.\n---\n\n# body\n"
+
+func TestExtensionsValidateGood(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtAgent(t, root, "audit-lite", goodAgent)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 0 {
+		t.Fatalf("valid extension should pass, got %d\n%s%s", code, stdout, stderr)
+	}
+}
+
+func TestExtensionsValidateComponentManifestV2Passes(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "base", "---\nname: base-skill\ndescription: Base.\n---\n")
+	writeExtSkill(t, root, "audit-lite", "---\nname: audit-lite\ndescription: Audit.\n---\n")
+	writeExtManifest(t, root, "base", `schema_version: "1.1"
+kind: extension
+id: base
+tier: core
+requires: []
+owns:
+  skills: [audit-lite]
+  agents: [house-reviewer]
+surface:
+  clusters: [review]
+safety:
+  may_weaken_gates: false
+  executable: false
+`)
+	writeExtManifest(t, root, "audit-lite", `schema_version: "1.1"
+kind: extension
+id: audit-lite
+tier: standard
+requires: [base]
+safety:
+  may_weaken_gates: false
+  executable: false
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 0 {
+		t.Fatalf("safe v2 manifests should pass, got %d\n%s%s", code, stdout, stderr)
+	}
+}
+
+func TestExtensionsValidateComponentManifestV2RejectsCyclesAndFirstPartyClaims(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "one", goodSkill)
+	writeExtSkill(t, root, "two", goodSkill)
+	writeExtManifest(t, root, "one", `schema_version: "1.1"
+kind: extension
+id: one
+requires: [two]
+owns:
+  skills: [rite-build]
+safety:
+  may_weaken_gates: false
+`)
+	writeExtManifest(t, root, "two", `schema_version: "1.1"
+kind: extension
+id: two
+requires: [one]
+safety:
+  may_weaken_gates: false
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("unsafe v2 manifests should fail, got %d\n%s%s", code, stdout, stderr)
+	}
+	for _, want := range []string{"collides with the first-party DevRites pack", "dependency graph must be acyclic"} {
+		if !contains(stderr.String(), want) {
+			t.Fatalf("want %q in stderr, got:\n%s", want, stderr.String())
+		}
+	}
+}
+
+func TestExtensionsValidateComponentManifestPasses(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtManifest(t, root, "audit-lite", `schema_version: "1.0"
+component:
+  id: audit-lite
+  kind: extension
+  version: 0.1.0
+  scope: project-local
+  distribution: npx-managed
+permissions:
+  writes:
+    - .devrites/**
+    - .claude/**
+safety:
+  may_weaken_gates: false
+  requires_type_go_bypass: false
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 0 {
+		t.Fatalf("safe component manifest should pass, got %d\n%s%s", code, stdout, stderr)
+	}
+	if !contains(stdout.String(), "manifest") {
+		t.Fatalf("validation should report manifest coverage, got:\n%s", stdout.String())
+	}
+}
+
+func TestExtensionsValidateComponentManifestRejectsPluginDistribution(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtManifest(t, root, "audit-lite", `component:
+  id: audit-lite
+  kind: extension
+  scope: project-local
+  distribution: claude-plugin
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("plugin distribution should fail, got %d\n%s%s", code, stdout, stderr)
+	}
+	if !contains(stderr.String(), "distribution must be npx-managed") {
+		t.Fatalf("want distribution complaint, got:\n%s", stderr.String())
+	}
+}
+
+func TestExtensionsValidateComponentManifestRejectsUnsafeClaims(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtManifest(t, root, "audit-lite", `component:
+  id: audit-lite
+  kind: extension
+  scope: global
+  distribution: npx-managed
+permissions:
+  writes:
+    - ~/.claude/**
+safety:
+  may_weaken_gates: true
+  requires_type_go_bypass: true
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("unsafe component manifest should fail, got %d\n%s%s", code, stdout, stderr)
+	}
+	for _, want := range []string{"scope must be project-local", "write root", "may_weaken_gates must be false", "requires_type_go_bypass must be false"} {
+		if !contains(stderr.String(), want) {
+			t.Fatalf("want %q in stderr, got:\n%s", want, stderr.String())
+		}
+	}
+}
+
+func TestExtensionsValidateWarnsWhenGateSurfaceIsInactive(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtManifest(t, root, "audit-lite", `schema_version: "1.1"
+kind: extension
+id: audit-lite
+surface:
+  clusters: [review]
+safety:
+  executable: true
+`)
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("unsafe gate-like extension should fail, got %d\n%s%s", code, stdout, stderr)
+	}
+	if !contains(stderr.String(), "declared review/gate surface is inactive") {
+		t.Fatalf("want inactive gate warning, got:\n%s", stderr.String())
+	}
+}
+
+func writeExtManifest(t *testing.T, root, ext, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "extensions", ext)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "component.yaml"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestExtensionsValidateMissingFrontmatter(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "broken", "# no frontmatter here\n")
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("missing frontmatter should fail with 1, got %d\n%s%s", code, stdout, stderr)
+	}
+	if !contains(stderr.String(), "missing YAML frontmatter") {
+		t.Fatalf("want frontmatter complaint, got:\n%s", stderr.String())
+	}
+}
+
+func TestExtensionsValidateEmptyExtension(t *testing.T) {
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, "extensions", "hollow"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("empty extension should fail, got %d", code)
+	}
+}
+
+func TestExtensionsValidateDuplicateName(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "one", goodSkill)
+	writeExtSkill(t, root, "two", goodSkill) // same skill name in both
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"validate"}, stdout, stderr); code != 1 {
+		t.Fatalf("duplicate skill name should fail, got %d\n%s", code, stderr)
+	}
+}
+
+func TestExtensionsNoneIsClean(t *testing.T) {
+	root := t.TempDir()
+	if code := Extensions(root, []string{"validate"}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("no extensions dir should pass, got %d", code)
+	}
+}
+
+func TestExtensionsSyncMirrorsIntoClaude(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	writeExtSkill(t, root, "audit-lite", goodSkill)
+	writeExtAgent(t, root, "audit-lite", goodAgent)
+
+	stdout, stderr := &bytes.Buffer{}, &bytes.Buffer{}
+	if code := Extensions(root, []string{"sync"}, stdout, stderr); code != 0 {
+		t.Fatalf("sync should succeed, got %d\n%s%s", code, stdout, stderr)
+	}
+	if !isFile(filepath.Join(project, ".claude", "skills", "audit-lite", "SKILL.md")) {
+		t.Fatal("skill not mirrored into .claude/skills/")
+	}
+	if !isFile(filepath.Join(project, ".claude", "agents", "audit-lite.md")) {
+		t.Fatal("agent not mirrored into .claude/agents/")
+	}
+	if isFile(filepath.Join(project, ".codex", "agents", "audit-lite.toml")) {
+		t.Fatal("extension sync must not generate Codex agent mirrors")
+	}
+	if isFile(filepath.Join(project, ".agents", "skills", "audit-lite", "SKILL.md")) {
+		t.Fatal("extension sync must not generate Codex skill mirrors")
+	}
+	// Idempotent second sync.
+	if code := Extensions(root, []string{"sync"}, &bytes.Buffer{}, &bytes.Buffer{}); code != 0 {
+		t.Fatalf("re-sync should be idempotent, got %d", code)
+	}
+}
+
+func TestExtensionsSyncRefusesBroken(t *testing.T) {
+	project := t.TempDir()
+	root := filepath.Join(project, ".devrites")
+	writeExtSkill(t, root, "broken", "# no frontmatter\n")
+	if code := Extensions(root, []string{"sync"}, &bytes.Buffer{}, &bytes.Buffer{}); code != 1 {
+		t.Fatalf("sync should refuse a broken set, got %d", code)
+	}
+	if isFile(filepath.Join(project, ".claude", "skills", "broken", "SKILL.md")) {
+		t.Fatal("broken extension must not be synced")
+	}
+}
+
+func TestExtensionsAliases(t *testing.T) {
+	root := t.TempDir()
+	writeExtSkill(t, root, "renamed", goodSkill)
+	meta := "aliases: [old-audit, legacy-audit]\n"
+	if err := os.WriteFile(filepath.Join(root, "extensions", "renamed", "extension.yaml"), []byte(meta), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	exts, err := discoverExtensions(filepath.Join(root, "extensions"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(exts) != 1 || len(exts[0].aliases) != 2 || exts[0].aliases[0] != "old-audit" {
+		t.Fatalf("aliases not parsed: %+v", exts)
+	}
+}

package/engine/internal/lib/footprint.go

@@ -0,0 +1,239 @@
+package lib
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Footprint reports the fan-out footprint of a feature run — how many subagents
+// were dispatched, of which kinds, across how many slices and minutes — from the
+// append-only dispatch log at .devrites/work/<slug>/footprint.log. It never
+// derives a token or dollar figure: those cannot be sourced truthfully, and
+// inventing one would violate the proof thesis.
+//
+// base is the project directory that contains the .devrites tree. The stdout
+// output and the exit code are the interface; stderr carries only usage errors.
+//
+//	log <slug> <kind> [label]  record one dispatch (exit 0; 2 on usage)
+//	render <slug>              print the one-line footprint
+//	roster <slug>              review-accounting gate: 0 complete · 1 always-on skipped · 3 unaccounted
+func Footprint(root string, args []string, stdout, stderr io.Writer) int {
+	const usage = "usage: devrites-engine footprint log|render|roster <slug> [...]"
+
+	cmd, slug := "", ""
+	if len(args) > 0 {
+		cmd = args[0]
+	}
+	if len(args) > 1 {
+		slug = args[1]
+	}
+	if cmd == "" || slug == "" {
+		fmt.Fprintln(stderr, usage)
+		return 2
+	}
+
+	dir := featureDir(root, slug)
+	logPath := filepath.Join(dir, "footprint.log")
+	switch cmd {
+	case "log":
+		return footprintLog(dir, logPath, args[2:], stderr)
+	case "render":
+		return footprintRender(logPath, stdout)
+	case "roster":
+		return footprintRoster(logPath, stdout)
+	default:
+		fmt.Fprintln(stderr, usage)
+		return 2
+	}
+}
+
+// footprintLog appends one dispatch record. Recording is best-effort: with no
+// workspace, or an unwritable log, it silently succeeds — bookkeeping must never
+// fail the orchestrator it instruments.
+func footprintLog(dir, logPath string, rest []string, stderr io.Writer) int {
+	kind, label := "", ""
+	if len(rest) > 0 {
+		kind = rest[0]
+	}
+	if len(rest) > 1 {
+		label = rest[1]
+	}
+	if kind == "" {
+		fmt.Fprintln(stderr, "usage: devrites-engine footprint log <slug> <kind> [label]")
+		return 2
+	}
+	if !isDir(dir) {
+		return 0
+	}
+	f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	if err != nil {
+		return 0
+	}
+	defer f.Close()
+
+	// Match footprint.sh's `printf '%s %s %s\n'` exactly: three fields always,
+	// so an empty label still writes its trailing space. render/roster tokenize
+	// on whitespace, so the extra field is harmless — but keeping the byte format
+	// identical means the persisted log is parity-clean too.
+	record := strconv.FormatInt(time.Now().Unix(), 10) + " " + kind + " " + label
+	fmt.Fprintln(f, record)
+	return 0
+}
+
+// footprintRender prints the one-line footprint: the subagent count with a
+// per-kind breakdown, the slice count (one per wright dispatch), and the active
+// span in whole minutes between the first and last record. A "skip" record — a
+// conscious non-dispatch — is not a subagent and never counts.
+func footprintRender(logPath string, stdout io.Writer) int {
+	f, err := os.Open(logPath)
+	if err != nil {
+		fmt.Fprintln(stdout, "Footprint: n/a (no dispatch records)")
+		return 0
+	}
+	defer f.Close()
+
+	var total int
+	byKind := map[string]int{}
+	var first, last int64
+	seen := false
+	sc := newLineScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 2 || fields[1] == "skip" {
+			continue
+		}
+		total++
+		byKind[fields[1]]++
+		epoch, _ := strconv.ParseInt(fields[0], 10, 64)
+		if !seen || epoch < first {
+			first = epoch
+		}
+		if epoch > last {
+			last = epoch
+		}
+		seen = true
+	}
+
+	minutes := 0
+	if last > first {
+		minutes = int((last - first) / 60)
+	}
+	slices := byKind["wright"]
+	fmt.Fprintf(stdout, "Footprint: %d subagent%s (%s) · %d slice%s · ~%dm active\n",
+		total, plural(total), kindBreakdown(byKind), slices, plural(slices), minutes)
+	return 0
+}
+
+// kindBreakdown renders the dispatched kinds in a fixed order — wright, reviewer,
+// audit, doubt — each with its count, joined by " · ". Only kinds actually
+// present appear; reviewers and audits pluralize, wright and doubt do not.
+func kindBreakdown(byKind map[string]int) string {
+	kinds := []struct {
+		key       string
+		pluralize bool
+	}{
+		{"wright", false},
+		{"reviewer", true},
+		{"audit", true},
+		{"doubt", false},
+	}
+	var parts []string
+	for _, k := range kinds {
+		n := byKind[k.key]
+		if n == 0 {
+			continue
+		}
+		noun := k.key
+		if k.pluralize {
+			noun += plural(n)
+		}
+		parts = append(parts, fmt.Sprintf("%d %s", n, noun))
+	}
+	return strings.Join(parts, " · ")
+}
+
+// footprintRoster is the review fan-out accounting gate. Every reviewer on the
+// roster must carry a recorded decision — dispatched, or a conscious skip. An
+// unaccounted reviewer is the silent omission this catches. The roster mirrors
+// devrites-lib/reference/parallel-dispatch.md, its single source of truth.
+//
+//	3  a reviewer has neither a dispatch nor a skip record
+//	1  an always-on reviewer was skip-recorded (allowed; verify it is a carry-forward)
+//	0  every reviewer accounted for
+func footprintRoster(logPath string, stdout io.Writer) int {
+	alwaysOn := []string{"spec-reviewer", "code-reviewer", "test-analyst"}
+	conditional := []string{"frontend-reviewer", "security-auditor", "performance-reviewer", "devex-reviewer"}
+
+	f, err := os.Open(logPath)
+	if err != nil {
+		fmt.Fprintln(stdout, "roster: n/a (no dispatch records — fan-out did not run)")
+		return 0
+	}
+	defer f.Close()
+
+	dispatched, skipped := map[string]bool{}, map[string]bool{}
+	sc := newLineScanner(f)
+	for sc.Scan() {
+		fields := strings.Fields(sc.Text())
+		if len(fields) < 3 {
+			continue
+		}
+		name := strings.TrimPrefix(fields[2], "devrites-") // names log with or without the prefix
+		switch fields[1] {
+		case "reviewer":
+			dispatched[name] = true
+		case "skip":
+			skipped[name] = true
+		}
+	}
+
+	var unaccounted, alwaysOnSkipped []string
+	for _, r := range alwaysOn {
+		switch {
+		case dispatched[r]:
+			fmt.Fprintf(stdout, "  %s: dispatched\n", r)
+		case skipped[r]:
+			fmt.Fprintf(stdout, "  %s: skipped (always-on — verify carry-forward)\n", r)
+			alwaysOnSkipped = append(alwaysOnSkipped, r)
+		default:
+			fmt.Fprintf(stdout, "  %s: UNACCOUNTED\n", r)
+			unaccounted = append(unaccounted, r)
+		}
+	}
+	for _, r := range conditional {
+		switch {
+		case dispatched[r]:
+			fmt.Fprintf(stdout, "  %s: dispatched\n", r)
+		case skipped[r]:
+			fmt.Fprintf(stdout, "  %s: skipped\n", r)
+		default:
+			fmt.Fprintf(stdout, "  %s: UNACCOUNTED\n", r)
+			unaccounted = append(unaccounted, r)
+		}
+	}
+
+	switch {
+	case len(unaccounted) > 0:
+		fmt.Fprintf(stdout, "roster: UNACCOUNTED — %s\n", strings.Join(unaccounted, " "))
+		return 3
+	case len(alwaysOnSkipped) > 0:
+		fmt.Fprintf(stdout, "roster: always-on skipped — %s\n", strings.Join(alwaysOnSkipped, " "))
+		return 1
+	default:
+		fmt.Fprintln(stdout, "roster: complete (every reviewer accounted for)")
+		return 0
+	}
+}
+
+// plural returns the English plural suffix for a count: "" for one, "s" otherwise.
+func plural(n int) string {
+	if n == 1 {
+		return ""
+	}
+	return "s"
+}

package/engine/internal/lib/jsonout.go

@@ -0,0 +1,115 @@
+package lib
+
+import (
+	"encoding/json"
+	"io"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// The machine-readable agent contract. A `--json` run of an AFK-parsed command
+// wraps its normal text output in a stable envelope so an unattended driver reads
+// a structured result instead of scraping prose. The command's own logic is
+// unchanged — the envelope captures its stdout (as data.text), its stderr (parsed
+// into diagnostics), and the exit code. Full contract: docs/engine/agent-contract.md.
+
+// Envelope is the top-level JSON result of a `--json` command run.
+type Envelope struct {
+	Command     string        `json:"command"`
+	OK          bool          `json:"ok"`
+	ExitCode    int           `json:"exitCode"`
+	Data        *EnvelopeData `json:"data,omitempty"`
+	Diagnostics []Diagnostic  `json:"diagnostics,omitempty"`
+}
+
+// EnvelopeData carries the command's human-readable stdout verbatim, so nothing is
+// lost versus the text form while structured consumers key on ok/exitCode/diagnostics.
+type EnvelopeData struct {
+	Text string `json:"text"`
+}
+
+// Diagnostic is one stderr line, classified. Path and Line are populated when the
+// emitting command used the `ERROR:<path>: <msg> (line N)` shape (spec-validate,
+// ledger validate); otherwise they are empty.
+type Diagnostic struct {
+	Code     string `json:"code"`
+	Severity string `json:"severity"` // error | warning | info
+	Message  string `json:"message"`
+	Path     string `json:"path,omitempty"`
+	Line     int    `json:"line,omitempty"`
+}
+
+var (
+	diagLineRe   = regexp.MustCompile(`\(line[[:space:]]+(\d+)\)`)
+	diagPathRe   = regexp.MustCompile(`^([^:]*(?:/[^:]*)?\.[A-Za-z0-9]+):[[:space:]]+(.*)$`)
+	diagCodeWord = regexp.MustCompile(`[^a-z0-9]+`)
+)
+
+// NewEnvelope builds the result envelope from a captured command run.
+func NewEnvelope(command string, code int, stdout, stderr string) Envelope {
+	env := Envelope{Command: command, OK: code == 0, ExitCode: code}
+	if s := strings.TrimRight(stdout, "\n"); s != "" {
+		env.Data = &EnvelopeData{Text: s}
+	}
+	for _, line := range strings.Split(stderr, "\n") {
+		line = strings.TrimRight(line, "\r")
+		if strings.TrimSpace(line) == "" {
+			continue
+		}
+		env.Diagnostics = append(env.Diagnostics, parseDiagnostic(command, line))
+	}
+	return env
+}
+
+// parseDiagnostic classifies one stderr line. It recognizes the ERROR:/WARN:
+// prefixes and the `<path>: <message> (line N)` shape the spec/ledger validators
+// emit; anything else becomes an info-level diagnostic with the raw text.
+func parseDiagnostic(command, line string) Diagnostic {
+	d := Diagnostic{Severity: "info", Message: line}
+	rest := line
+	switch {
+	case strings.HasPrefix(line, "ERROR:"):
+		d.Severity = "error"
+		rest = strings.TrimPrefix(line, "ERROR:")
+	case strings.HasPrefix(line, "WARN:"), strings.HasPrefix(line, "WARNING:"):
+		d.Severity = "warning"
+		rest = strings.TrimPrefix(strings.TrimPrefix(line, "WARNING:"), "WARN:")
+	}
+	rest = strings.TrimSpace(rest)
+	d.Message = rest
+	if m := diagPathRe.FindStringSubmatch(rest); m != nil {
+		d.Path = m[1]
+		d.Message = m[2]
+	}
+	if m := diagLineRe.FindStringSubmatch(rest); m != nil {
+		if n, err := strconv.Atoi(m[1]); err == nil {
+			d.Line = n
+		}
+	}
+	d.Code = diagnosticCode(command, d.Severity, d.Message)
+	return d
+}
+
+// diagnosticCode assigns a stable, greppable code. It is intentionally coarse in
+// v1 — a `<command>_<severity>` slug — so the catalog in agent-contract.md can grow
+// specific codes over time without breaking consumers that match on the prefix.
+func diagnosticCode(command, severity, message string) string {
+	base := diagCodeWord.ReplaceAllString(strings.ToLower(command), "_")
+	switch {
+	case strings.Contains(message, "marked ADDED") || strings.Contains(message, "marked MODIFIED") || strings.Contains(message, "marked REMOVED"):
+		return base + "_delta_mismatch"
+	case strings.Contains(message, "SHALL") || strings.Contains(message, "WHEN") || strings.Contains(message, "THEN") || strings.Contains(message, "Scenario"):
+		return base + "_grammar"
+	}
+	return base + "_" + severity
+}
+
+// WriteEnvelope marshals an envelope as indented JSON followed by a newline.
+func WriteEnvelope(w io.Writer, env Envelope) {
+	b, err := json.MarshalIndent(env, "", "  ")
+	if err != nil {
+		return
+	}
+	_, _ = w.Write(append(b, '\n'))
+}