devrites 5.4.0 → 5.5.0

package/engine/internal/lib/observe_budgets_test.go

@@ -0,0 +1,142 @@
+package lib
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/devrites/devrites/internal/state"
+)
+
+const budgetTasks = `# Tasks
+
+Current checkpoint: intro text.
+
+## SLICE-001 First
+Goal: one
+Dependencies: none
+depends_on: []
+
+### Notes
+nested heading stays inside the slice
+
+## SLICE-002 Second
+Goal: two
+Dependencies: SLICE-001
+depends_on: [SLICE-001]
+
+## Trailing section
+not a slice
+`
+
+func writeBudgetWorkspace(t *testing.T, files map[string]string) (root, workspace string) {
+	t.Helper()
+	root = filepath.Join(t.TempDir(), ".devrites")
+	workspace = filepath.Join(root, "work", "feature")
+	if err := os.MkdirAll(workspace, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for name, body := range files {
+		if err := os.WriteFile(filepath.Join(workspace, name), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root, workspace
+}
+
+func TestExtractTaskSliceStopsAtNextH2AndKeepsH3(t *testing.T) {
+	block, ok := state.ExtractTaskSlice([]byte(budgetTasks), "SLICE-001")
+	if !ok {
+		t.Fatal("expected SLICE-001")
+	}
+	if !strings.HasPrefix(block, "## SLICE-001 First\n") || !strings.Contains(block, "### Notes") {
+		t.Fatalf("block=%q", block)
+	}
+	if strings.Contains(block, "SLICE-002") || strings.Contains(block, "Trailing") {
+		t.Fatalf("block leaked past the next heading: %q", block)
+	}
+	last, ok := state.ExtractTaskSlice([]byte(budgetTasks), "SLICE-002")
+	if !ok || strings.Contains(last, "Trailing section") {
+		t.Fatalf("last=%q ok=%v", last, ok)
+	}
+	if _, ok := state.ExtractTaskSlice([]byte(budgetTasks), "SLICE-003"); ok {
+		t.Fatal("SLICE-003 must not resolve")
+	}
+}
+
+func TestRunObserveSlicePrintsOneSection(t *testing.T) {
+	root, _ := writeBudgetWorkspace(t, map[string]string{"tasks.md": budgetTasks})
+	var stdout, stderr bytes.Buffer
+	if code := RunObserveSlice(root, "feature", "SLICE-002", &stdout, &stderr); code != 0 {
+		t.Fatalf("code=%d stderr=%s", code, stderr.String())
+	}
+	if got := stdout.String(); !strings.HasPrefix(got, "## SLICE-002 Second\n") || strings.Contains(got, "SLICE-001 First") {
+		t.Fatalf("stdout=%q", got)
+	}
+
+	stdout.Reset()
+	if code := RunObserveSlice(root, "feature", "SLICE-009", &stdout, &stderr); code != 3 || !strings.Contains(stdout.String(), "BLOCKED") {
+		t.Fatalf("code=%d stdout=%q", code, stdout.String())
+	}
+	if code := RunObserveSlice(root, "feature", "slice-1", &stdout, &stderr); code != 2 {
+		t.Fatalf("code=%d for malformed id", code)
+	}
+}
+
+func TestObserveSummaryReportsBudgetsAndBulkFiles(t *testing.T) {
+	longLine := strings.Repeat("x", 60_000) + "\n"
+	root, _ := writeBudgetWorkspace(t, map[string]string{
+		"state.md":                "| phase | build |\n| schema | 3 |\n" + longLine,
+		"tasks.md":                budgetTasks,
+		"vet-review-input-1.json": strings.Repeat("{}", 40_000),
+		"small-note.json":         "{}",
+	})
+	summary, err := ObserveSummaryFor(root, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	byFile := map[string]ArtifactBudget{}
+	for _, b := range summary.ArtifactBudgets {
+		byFile[b.File] = b
+	}
+	if st, ok := byFile["state.md"]; !ok || !st.Over || st.Lines != 3 || st.ByteBudget != 120*state.BudgetBytesPerLine {
+		t.Fatalf("state.md budget=%+v ok=%v (long line must trip the byte budget)", st, ok)
+	}
+	if tk, ok := byFile["tasks.md"]; !ok || tk.Over {
+		t.Fatalf("tasks.md budget=%+v ok=%v", tk, ok)
+	}
+	if summary.TaskGraph == nil || len(summary.TaskGraph.Slices) != 2 ||
+		summary.TaskGraph.Slices[0].ID != "SLICE-001" || len(summary.TaskGraph.Slices[0].DependsOn) != 0 ||
+		summary.TaskGraph.Slices[1].DependsOn[0] != "SLICE-001" {
+		t.Fatalf("task_graph.slices=%+v", summary.TaskGraph)
+	}
+	if len(summary.BulkFiles) != 1 || summary.BulkFiles[0].File != "vet-review-input-1.json" {
+		t.Fatalf("bulk_files=%+v", summary.BulkFiles)
+	}
+}
+
+func TestObserveSummaryReportsSequenceCursor(t *testing.T) {
+	root, _ := writeBudgetWorkspace(t, map[string]string{
+		"state.md": "| phase | build |\n| schema | 3 |\n| sequence_parent | feat-1 |\n| sequence_position | 2 |\n| sequence_workspaces_remaining | 3 |\n",
+	})
+	summary, err := ObserveSummaryFor(root, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	seq := summary.Sequence
+	if seq == nil || seq.Parent != "feat-1" || seq.Position != "2" || seq.WorkspacesRemaining != "3" {
+		t.Fatalf("sequence=%+v", seq)
+	}
+	root, _ = writeBudgetWorkspace(t, map[string]string{
+		"state.md": "| phase | build |\n| schema | 3 |\n",
+	})
+	summary, err = ObserveSummaryFor(root, "feature")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if summary.Sequence != nil {
+		t.Fatalf("sequence must be absent without cursor fields: %+v", summary.Sequence)
+	}
+}

package/engine/internal/lib/observe_summary.go

@@ -2,30 +2,50 @@ package lib
 
 import (
 	"encoding/json"
+	"fmt"
 	"io"
 
+	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/state"
 )
 
+// ObserveSlice is one slice's identity and ordering edges, enough for a root to pick
+// the next buildable slice without loading tasks.md.
+type ObserveSlice struct {
+	ID        string   `json:"id"`
+	DependsOn []string `json:"depends_on"`
+}
+
 // ObserveTaskGraph is the slice-graph subset of ObserveSummary.
 type ObserveTaskGraph struct {
-	SliceCount int      `json:"slice_count"`
-	Cycle      []string `json:"cycle,omitempty"`
-	Unknown    []string `json:"unknown_dependencies,omitempty"`
-	Problems   []string `json:"problems,omitempty"`
-	OK         bool     `json:"ok"`
+	SliceCount int            `json:"slice_count"`
+	Slices     []ObserveSlice `json:"slices,omitempty"`
+	Cycle      []string       `json:"cycle,omitempty"`
+	Unknown    []string       `json:"unknown_dependencies,omitempty"`
+	Problems   []string       `json:"problems,omitempty"`
+	OK         bool           `json:"ok"`
 }
 
 // ObserveSummary is a sanitized, machine-readable workspace snapshot.
+type ObserveSequenceCursor struct {
+	Parent              string `json:"parent"`
+	Position            string `json:"position"`
+	WorkspacesRemaining string `json:"workspaces_remaining"`
+	Role                string `json:"role,omitempty"`
+}
+
 type ObserveSummary struct {
-	Slug              string            `json:"slug"`
-	Phase             string            `json:"phase,omitempty"`
-	Status            string            `json:"status,omitempty"`
-	NextAction        string            `json:"next_action,omitempty"`
-	MissingSections   []string          `json:"missing_sections,omitempty"`
-	MissingFiles      []string          `json:"missing_files,omitempty"`
-	PrinciplesPresent bool              `json:"principles_present"`
-	TaskGraph         *ObserveTaskGraph `json:"task_graph,omitempty"`
+	Slug              string                 `json:"slug"`
+	Phase             string                 `json:"phase,omitempty"`
+	Status            string                 `json:"status,omitempty"`
+	NextAction        string                 `json:"next_action,omitempty"`
+	MissingSections   []string               `json:"missing_sections,omitempty"`
+	MissingFiles      []string               `json:"missing_files,omitempty"`
+	PrinciplesPresent bool                   `json:"principles_present"`
+	TaskGraph         *ObserveTaskGraph      `json:"task_graph,omitempty"`
+	ArtifactBudgets   []ArtifactBudget       `json:"artifact_budgets,omitempty"`
+	BulkFiles         []BulkFile             `json:"bulk_files,omitempty"`
+	Sequence          *ObserveSequenceCursor `json:"sequence,omitempty"`
 }
 
 // ObserveSummaryFor builds a summary for one feature slug.
@@ -45,17 +65,58 @@ func ObserveSummaryFor(root, slug string) (ObserveSummary, error) {
 	}
 
 	if graph, graphErr := CheckTaskGraph(root, slug); graphErr == nil && (len(graph.Slices) > 0 || len(graph.Problems) > 0) {
+		slices := make([]ObserveSlice, 0, len(graph.Slices))
+		for _, slice := range graph.Slices {
+			deps := make([]string, 0, len(slice.Dependencies))
+			deps = append(deps, slice.Dependencies...)
+			slices = append(slices, ObserveSlice{ID: slice.ID, DependsOn: deps})
+		}
 		summary.TaskGraph = &ObserveTaskGraph{
 			SliceCount: len(graph.Slices),
+			Slices:     slices,
 			Cycle:      append([]string(nil), graph.Cycle...),
 			Unknown:    append([]string(nil), graph.Unknown...),
 			Problems:   append([]string(nil), graph.Problems...),
 			OK:         len(graph.Problems) == 0,
 		}
 	}
+	if report.SequenceParent != "" || report.SequencePosition != "" || report.SequenceWorkspacesRemaining != "" || report.SequenceRole != "" {
+		summary.Sequence = &ObserveSequenceCursor{
+			Parent:              report.SequenceParent,
+			Position:            report.SequencePosition,
+			WorkspacesRemaining: report.SequenceWorkspacesRemaining,
+			Role:                report.SequenceRole,
+		}
+	}
+	if workspace, wsErr := devritespaths.ExistingFeatureDirChecked(root, slug); wsErr == nil {
+		if budgets, bulk, budgetErr := observeArtifactBudgets(workspace); budgetErr == nil {
+			summary.ArtifactBudgets = budgets
+			summary.BulkFiles = bulk
+		}
+	}
 	return summary, nil
 }
 
+// RunObserveSlice prints one SLICE-### section of tasks.md for a slug.
+func RunObserveSlice(root, slug, id string, stdout, stderr io.Writer) int {
+	if !state.ValidSliceID(id) {
+		fmt.Fprintf(stderr, "observe slice: %q is not a SLICE-### id\n", id)
+		return 2
+	}
+	raw, err := readWorkspaceArtifact(root, slug, "tasks.md")
+	if err != nil {
+		fmt.Fprintf(stderr, "observe slice: %v\n", err)
+		return 2
+	}
+	block, ok := state.ExtractTaskSlice(raw, id)
+	if !ok {
+		fmt.Fprintf(stdout, "observe slice: BLOCKED: %s not found in tasks.md\n", id)
+		return 3
+	}
+	fmt.Fprint(stdout, block)
+	return 0
+}
+
 func missingSectionNames(sections []state.Section) []string {
 	if len(sections) == 0 {
 		return nil

package/engine/internal/lib/workspace_read.go

@@ -8,23 +8,28 @@ import (
 	"github.com/devrites/devrites/internal/devritespaths"
 )
 
+// workspaceArtifactLimit bounds one artifact read. Slice extraction must keep
+// working on a workspace whose tasks.md is over budget: the budget gate flags the
+// file, while Build still reads its own slice instead of the whole document.
+const workspaceArtifactLimit = 16 << 20
+
 func readWorkspaceArtifact(root, slug, name string) ([]byte, error) {
 	workspace, err := devritespaths.ExistingFeatureDirChecked(root, slug)
 	if err != nil {
-		return nil, fmt.Errorf("task-graph: workspace unavailable: %w", err)
+		return nil, fmt.Errorf("workspace artifact: workspace unavailable: %w", err)
 	}
 	path := filepath.Join(workspace, name)
 	info, err := os.Stat(path)
 	if err != nil {
-		return nil, fmt.Errorf("task-graph: %s unavailable: %w", name, err)
+		return nil, fmt.Errorf("workspace artifact: %s unavailable: %w", name, err)
 	}
-	if info.Size() > 1<<20 {
-		return nil, fmt.Errorf("task-graph: %s exceeds 1 MiB limit", name)
+	if info.Size() > workspaceArtifactLimit {
+		return nil, fmt.Errorf("workspace artifact: %s exceeds %d MiB limit", name, workspaceArtifactLimit>>20)
 	}
-	// #nosec G304 -- workspace task-graph file; 1 MiB cap checked above
+	// #nosec G304 -- workspace artifact; size cap checked above
 	raw, err := os.ReadFile(path)
 	if err != nil {
-		return nil, fmt.Errorf("task-graph: cannot read %s: %w", name, err)
+		return nil, fmt.Errorf("workspace artifact: cannot read %s: %w", name, err)
 	}
 	return raw, nil
 }

package/engine/internal/state/budgets.go

@@ -0,0 +1,163 @@
+package state
+
+import (
+	"bytes"
+	"strings"
+)
+
+// Artifact budgets mirror workspace-artifact-schema.md "What each file owns".
+// A line budget also bounds bytes at BudgetBytesPerLine per budgeted line so a
+// few very long lines cannot evade it.
+const (
+	BudgetBytesPerLine = 400
+	// BudgetBlockFactor is the material-overshoot threshold. At or above this
+	// multiple of a line or byte budget a gate blocks unless the artifact
+	// records a structural `Budget override:` line; smaller overshoots are
+	// reported by `orient` and stay advisory.
+	BudgetBlockFactor = 1.5
+	// MaxArtifactBytes is the per-artifact read cap. A larger artifact cannot be
+	// observed and blocks as file_too_large, so callers that explain a size
+	// problem quote the same number the observer enforced.
+	MaxArtifactBytes = maxArtifactBytes
+	// PacketMaxBytes is the serialized-packet ceiling from context-hygiene.md:
+	// "A serialized packet stays <= 64 KiB; larger means the scope is wrong".
+	// A non-canonical workspace-root file over it is unsanctioned placement.
+	PacketMaxBytes = 64 << 10
+)
+
+var artifactLineBudgets = map[string]int{
+	"README.md":            120,
+	"brief.md":             80,
+	"spec.md":              260,
+	"decision-coverage.md": 200,
+	"strategy.md":          180,
+	"architecture.md":      180,
+	"flows.md":             160,
+	"decisions.md":         200,
+	"assumptions.md":       160,
+	"questions.md":         180,
+	"plan.md":              220,
+	"tasks.md":             280,
+	"traceability.md":      220,
+	"eng-review.md":        240,
+	"test-plan.md":         260,
+	"state.md":             120,
+	"evidence.md":          280,
+	"browser-evidence.md":  220,
+	"drift.md":             160,
+	"touched-files.md":     160,
+	"design-brief.md":      160,
+	"handoff.md":           120,
+	"polish-report.md":     200,
+	"ship.md":              120,
+	"review.md":            240,
+	"seal.md":              200,
+	"ai-spec.md":           160,
+}
+
+// advisoryOnlyArtifacts are append-only proof ledgers: they scale with proof
+// volume, not with planning surface, so their budget stays advisory in `orient`
+// and never blocks a gate. touched-files.md keeps its own deterministic
+// manifest limits.
+var advisoryOnlyArtifacts = map[string]bool{
+	"evidence.md":         true,
+	"browser-evidence.md": true,
+	"touched-files.md":    true,
+}
+
+// ArtifactLineBudget returns the documented line budget for a canonical artifact.
+func ArtifactLineBudget(name string) (int, bool) {
+	budget, ok := artifactLineBudgets[name]
+	return budget, ok
+}
+
+// sanctionedRootFiles are workspace-root files the schema places there without a
+// line budget: conditional artifacts (`references.md`, `investigation-map.md`,
+// `dogfood.md`) and the engine-owned parallel lease. Anything else in the root
+// is unsanctioned placement — `packets/` and `history/` own by-reference
+// packets and relocated narrative (workspace-artifact-schema.md "Required by
+// phase").
+var sanctionedRootFiles = map[string]bool{
+	"references.md":        true,
+	"investigation-map.md": true,
+	"dogfood.md":           true,
+	"parallel-lease.md":    true,
+}
+
+// SanctionedRootFile reports whether name is a legitimate workspace-root file:
+// a budgeted canonical artifact or a documented unbudgeted one.
+func SanctionedRootFile(name string) bool {
+	if _, ok := artifactLineBudgets[name]; ok {
+		return true
+	}
+	return sanctionedRootFiles[name]
+}
+
+// ArtifactBudgetGateApplies reports whether the deterministic material-overshoot
+// gate covers this artifact (canonical and not an advisory-only proof ledger).
+func ArtifactBudgetGateApplies(name string) bool {
+	_, ok := artifactLineBudgets[name]
+	return ok && !advisoryOnlyArtifacts[name]
+}
+
+// ArtifactBudgetStatus is one canonical artifact measured against its budget.
+type ArtifactBudgetStatus struct {
+	File       string
+	Lines      int
+	Bytes      int64
+	LineBudget int
+	ByteBudget int64
+	Over       bool
+	Material   bool
+	Override   bool
+}
+
+// ArtifactBudget measures raw against the named artifact's budget. ok is false
+// for a non-canonical file name.
+func ArtifactBudget(name string, raw []byte) (ArtifactBudgetStatus, bool) {
+	lineBudget, ok := artifactLineBudgets[name]
+	if !ok {
+		return ArtifactBudgetStatus{}, false
+	}
+	status := ArtifactBudgetStatus{
+		File:       name,
+		Lines:      CountLines(raw),
+		Bytes:      int64(len(raw)),
+		LineBudget: lineBudget,
+		ByteBudget: int64(lineBudget) * BudgetBytesPerLine,
+	}
+	status.Over = status.Lines > lineBudget || status.Bytes > status.ByteBudget
+	status.Material = float64(status.Lines) >= float64(lineBudget)*BudgetBlockFactor ||
+		float64(status.Bytes) >= float64(status.ByteBudget)*BudgetBlockFactor
+	status.Override = HasBudgetOverride(raw)
+	return status, true
+}
+
+// CountLines counts newline-terminated lines plus a final unterminated line.
+func CountLines(raw []byte) int {
+	if len(raw) == 0 {
+		return 0
+	}
+	lines := bytes.Count(raw, []byte{'\n'})
+	if raw[len(raw)-1] != '\n' {
+		lines++
+	}
+	return lines
+}
+
+// HasBudgetOverride reports a structural `Budget override:` line outside fenced
+// code blocks; a fenced example never counts.
+func HasBudgetOverride(raw []byte) bool {
+	fenced := false
+	for _, line := range strings.Split(string(raw), "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "```") {
+			fenced = !fenced
+			continue
+		}
+		if !fenced && strings.HasPrefix(trimmed, "Budget override:") {
+			return true
+		}
+	}
+	return false
+}

package/engine/internal/state/budgets_test.go

@@ -0,0 +1,42 @@
+package state
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestArtifactBudgetMeasuresLinesBytesAndMateriality(t *testing.T) {
+	if _, ok := ArtifactBudget("notes.json", []byte("x")); ok {
+		t.Fatal("non-canonical files have no budget")
+	}
+	within, ok := ArtifactBudget("tasks.md", []byte("# Tasks\n## SLICE-001 A\nDependencies: none\n"))
+	if !ok || within.Over || within.Material {
+		t.Fatalf("within=%+v", within)
+	}
+	over, _ := ArtifactBudget("tasks.md", []byte(strings.Repeat("x\n", 300)))
+	if !over.Over || over.Material {
+		t.Fatalf("300 lines against a 280-line budget must be over but not material: %+v", over)
+	}
+	material, _ := ArtifactBudget("tasks.md", []byte(strings.Repeat("x\n", 500)))
+	if !material.Material {
+		t.Fatalf("500 lines must be material: %+v", material)
+	}
+	longLine, _ := ArtifactBudget("state.md", []byte(strings.Repeat("y", 100_000)+"\n"))
+	if !longLine.Material || longLine.Lines != 1 {
+		t.Fatalf("one very long line must trip the byte budget: %+v", longLine)
+	}
+}
+
+func TestHasBudgetOverrideIgnoresFencedExamples(t *testing.T) {
+	if HasBudgetOverride([]byte("plain text\nBudget override: relocation pending\n")) != true {
+		t.Fatal("structural override line must be recognized")
+	}
+	fenced := "See the schema:\n\n```markdown\nBudget override: <reason>\n```\n\nNothing recorded.\n"
+	if HasBudgetOverride([]byte(fenced)) {
+		t.Fatal("a fenced example is not an override")
+	}
+	indented := "  Budget override: table form is required\n"
+	if !HasBudgetOverride([]byte(indented)) {
+		t.Fatal("leading whitespace must not hide a real override line")
+	}
+}

package/engine/internal/state/cursor.go

@@ -12,15 +12,19 @@ import (
 // remain local to the cursor package; normalizeCursorKey still accepts legacy
 // presentation aliases at the text boundary.
 const (
-	CursorPhase              = "phase"
-	CursorStatus             = "status"
-	CursorNextAction         = "next_action"
-	CursorQuestionID         = "question_id"
-	CursorActiveSlice        = "active_slice"
-	CursorAFKSlicesRemaining = "afk_slices_remaining"
-	CursorReturnPhase        = "return_phase"
-	CursorReturnNextAction   = "return_next_action"
-	CursorSchema             = "schema"
+	CursorPhase                    = "phase"
+	CursorStatus                   = "status"
+	CursorNextAction               = "next_action"
+	CursorQuestionID               = "question_id"
+	CursorActiveSlice              = "active_slice"
+	CursorAFKSlicesRemaining       = "afk_slices_remaining"
+	CursorSequenceParent           = "sequence_parent"
+	CursorSequencePosition         = "sequence_position"
+	CursorSequenceWorkspacesRemain = "sequence_workspaces_remaining"
+	CursorSequenceRole             = "sequence_role"
+	CursorReturnPhase              = "return_phase"
+	CursorReturnNextAction         = "return_next_action"
+	CursorSchema                   = "schema"
 )
 
 var cursorKeyAliases = map[string]string{
@@ -273,7 +277,9 @@ func isMigratableCursorKey(key string) bool {
 func canonicalCursorSpelling(key string) (string, bool) {
 	normalized := normalizeCursorKey(key)
 	canonicals := []string{CursorPhase, CursorStatus, CursorNextAction, CursorQuestionID,
-		CursorActiveSlice, CursorAFKSlicesRemaining, CursorReturnPhase,
+		CursorActiveSlice, CursorAFKSlicesRemaining, CursorSequenceParent,
+		CursorSequencePosition, CursorSequenceWorkspacesRemain, CursorSequenceRole,
+		CursorReturnPhase,
 		CursorReturnNextAction, CursorSchema}
 	for _, canonical := range canonicals {
 		if normalized == normalizeCursorKey(canonical) {

package/engine/internal/state/observation.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"sort"
 	"strings"
 
 	"github.com/devrites/devrites/internal/devritespaths"
@@ -90,9 +91,22 @@ func (f ArtifactFact) Diagnostic() (ArtifactDiagnostic, bool) {
 }
 
 type WorkspaceObservation struct {
-	slug  string
-	facts []ArtifactFact
-	index map[ArtifactPath]int
+	slug      string
+	facts     []ArtifactFact
+	index     map[ArtifactPath]int
+	rootFiles []RootFile
+}
+
+// RootFile is one regular file directly inside the workspace root.
+type RootFile struct {
+	Name  string
+	Bytes int64
+}
+
+// RootFiles lists the workspace root's regular files so a consumer can judge
+// placement without acquiring the directory itself.
+func (o *WorkspaceObservation) RootFiles() []RootFile {
+	return append([]RootFile(nil), o.rootFiles...)
 }
 
 func (o *WorkspaceObservation) Slug() string { return o.slug }
@@ -296,7 +310,39 @@ func observeWorkspace(root, slug string, callback observationCallback) (*Workspa
 	for i, fact := range facts {
 		index[fact.path] = i
 	}
-	return &WorkspaceObservation{slug: slug, facts: facts, index: index}, nil
+	rootFiles, err := readRootFiles(roots.workspace)
+	if err != nil {
+		return nil, ObservationWorkspaceInvalid
+	}
+	return &WorkspaceObservation{slug: slug, facts: facts, index: index, rootFiles: rootFiles}, nil
+}
+
+// readRootFiles lists the workspace directory's regular entries through the
+// already-verified root handle, so the list describes the same snapshot as the
+// artifact facts.
+func readRootFiles(root *os.Root) ([]RootFile, error) {
+	dir, err := root.Open(".")
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = dir.Close() }()
+	entries, err := dir.ReadDir(-1)
+	if err != nil {
+		return nil, err
+	}
+	files := make([]RootFile, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.Type().IsRegular() {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			return nil, err
+		}
+		files = append(files, RootFile{Name: entry.Name(), Bytes: info.Size()})
+	}
+	sort.Slice(files, func(i, j int) bool { return files[i].Name < files[j].Name })
+	return files, nil
 }
 
 func observationWorkspaceOverrideValid(root, slug string) bool {