devrites 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [4.2.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.1.0...v4.2.0) (2026-08-23)
+
+### Added
+
+* **rite:** ship workflow artifact, reslice, and observation ([#36](https://github.com/ViktorsBaikers/DevRites/issues/36)) ([456a00e](https://github.com/ViktorsBaikers/DevRites/commit/456a00e8280acdab9525a762a267be7084b26a9f))
+
 ## [4.1.0](https://github.com/ViktorsBaikers/DevRites/compare/v4.0.12...v4.1.0) (2026-08-12)
 
 ### Added

package/README.md

@@ -28,7 +28,7 @@ project-conventional push, tag, or PR action, and archive the workspace.
 Unattended runs may create local WIP checkpoint commits along the way, but they
 remain local unless Ship's disclosed plan includes an approved remote action.
 
-**Status:** [`v4.1.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.1.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v4.2.0`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.2.0): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 This is the latest published release; `main` may contain unreleased work.
 

package/docs/engine/commands.md

@@ -12,9 +12,9 @@ workflow strategy.
 | `update [flags]` | Refresh an existing managed installation. |
 | `uninstall [flags]` | Remove managed artifacts while preserving runtime workspace state. |
 | `check candidate <slug>` | Validate the strict manifest and compute the content-bound project-candidate identity. |
-| `check readiness <slug>` | Check phase files, human gates, and the current stable Build-input binding when applicable. |
+| `check readiness <slug>` | Check target-Phase files, open human gates from Clarify onward, and the current stable Build-input binding when applicable. |
 | `check readiness --emit-binding <slug>` | Render the exact stable Build-input binding for Vet to record after review. |
-| `check seal <slug>` | Check final files, human gates, the stable Build-input binding, and exact candidate bindings. |
+| `check seal <slug>` | Check files required by target Phase `seal`, open human gates, the stable Build-input binding, and exact candidate bindings. |
 | `state resolve <qid> "<answer>"` | Resolve an open question and update `questions.md` plus `state.md` atomically. |
 | `state close <slug>` | Archive a shipped workspace and clear matching `ACTIVE`. |
 | `secret-scan [--staged] [--stdin] [slug]` | Scan exact staged blobs, stdin, or touched regular files for credential material. |
@@ -29,10 +29,12 @@ not to the engine command namespace.
 ## Check boundary
 
 The candidate gate validates and hashes path/state/type/mode/content identity;
-it does not infer scope from Git. The readiness gate checks structure plus the
-exact stable Build-input binding after Vet. The seal gate repeats that binding
-and checks exact candidate bindings in evidence, optional browser evidence,
-review, and seal. None judges the meaning of `CLEAR`/`READY` prose,
+it does not infer scope from Git. The readiness gate checks target-Phase
+structure and applies open-question blocking only when that target is Clarify
+or later, plus the exact stable Build-input binding after Vet. The seal gate
+always targets Phase `seal`, repeats that binding, and checks exact candidate
+bindings in evidence, optional browser evidence, review, and seal. None judges
+the meaning of `CLEAR`/`READY` prose,
 parses reviewer narratives, infers acceptance coverage, counts assertions,
 interprets capability deltas, or decides whether a technical plan is sound.
 
@@ -104,6 +106,63 @@ ambient Git state. Ordinary readiness and Seal require that exact standalone
 line in `eng-review.md`; stale input returns
 `reason: DRV-GATE-READINESS-STALE` and routes through `/rite-vet`.
 
+### Workspace observation diagnostics
+
+Lifecycle checks acquire the fixed workspace Markdown inventory once. Each
+artifact is classified as `absent`, `empty`, `malformed`, `unsafe`,
+`unreadable`, or `present`. Retained content is limited to 1 MiB per file and
+8 MiB aggregate. Diagnostic lines use this exact shape:
+`artifact: <logical-path>: <state> (<code>)`.
+
+The closed diagnostic codes and recoveries are:
+
+| Code | Exact Gate recovery | Exact standalone readiness-binding payload |
+|---|---|---|
+| `malformed_markdown` | `next: repair <logical-path>: replace invalid Markdown with valid Markdown; required artifacts need substantive content` | `readiness input <logical-path> is malformed (malformed_markdown); replace invalid Markdown with valid Markdown` |
+| `parent_symlink` | `next: repair <logical-path>: replace the symlinked parent with a real directory` | `readiness input <logical-path> is unsafe (parent_symlink); replace the symlinked parent with a real directory` |
+| `final_symlink` | `next: repair <logical-path>: replace the symlink with a regular file` | `readiness input <logical-path> is unsafe (final_symlink); replace the symlink with a regular file` |
+| `non_regular` | `next: repair <logical-path>: replace the non-regular entry with a regular file` | `readiness input <logical-path> is unsafe (non_regular); replace the non-regular entry with a regular file` |
+| `file_too_large` | `next: repair <logical-path>: reduce the file to at most 1 MiB` | `readiness input <logical-path> is unsafe (file_too_large); reduce the file to at most 1 MiB` |
+| `permission_denied` | `next: repair <logical-path>: grant read permission` | `readiness input <logical-path> is unreadable (permission_denied); grant read permission` |
+| `read_failure` | `next: repair <logical-path>: restore a readable regular file` | `readiness input <logical-path> is unreadable (read_failure); restore a readable regular file` |
+
+The Gate recovery column remains exact for target-policy-required artifacts. For
+a selected optional readiness input, the same code-specific repair appends
+`; optional readiness input may instead be removed` and does not call the input
+required.
+
+These seven codes are the closed Workspace Observation classification and
+recovery mapping outcomes. A selected public consumer emits only a code
+reachable for its consumed fixed logical path. Invalid workspace ancestry is
+`workspace_invalid`, not an artifact `parent_symlink` diagnostic.
+
+Status emits diagnostics without recovery or `next:` lines, after section rows
+and before `result`. Gate emits diagnostics after `reason` and before recovery,
+`invariant`, and `retry` lines. Generic add-content recovery applies only to
+absent or empty target-required artifacts. Standalone readiness-binding
+failures use the existing `readiness-binding: BLOCKED:` prefix and the logical
+readiness-input state/code plus recovery; they never disclose physical paths or
+content.
+
+Whole observation failures are `workspace_invalid`, `aggregate_too_large`, and
+`concurrent_change`. Their disclosure-safe payloads are exact:
+
+- `workspace observation: workspace_invalid: workspace is unavailable; verify the selected logical workspace and canonical workspace override, then retry`
+- `workspace observation: aggregate_too_large: retained content exceeds the 8 MiB aggregate limit; reduce retained Markdown below 8 MiB, then retry`
+- `workspace observation: concurrent_change: workspace changed during acquisition; retry`
+
+An absent or empty `state.md` appends `add real content to state.md and retry` to
+the existing logical error. A malformed, unsafe, or unreadable `state.md`
+appends `repair state.md and retry`. A ledger without a phase appends `record
+phase in state.md and retry`; an unknown phase appends `record a known phase in
+state.md and retry`.
+
+Whole observation failures use stderr, exit `2`, and no lifecycle result or
+reason on stdout. Standalone readiness-binding failures use one stderr line,
+exit `3`, and empty stdout. Per-artifact lifecycle blocks keep existing reason
+IDs and stdout exit `3`; successful checks keep stdout exit `0`. Seal evidence
+freshness still runs separately after a successful Seal gate.
+
 - `0`: passed or completed.
 - `2`: common invalid request or unreadable-state result.
 - `3`: common deterministic lifecycle or safety block.

package/engine/go.mod

@@ -2,4 +2,4 @@ module github.com/devrites/devrites
 
 go 1.26
 
-toolchain go1.26.5
+toolchain go1.26.7

package/engine/internal/gate/gate.go

@@ -6,11 +6,8 @@ package gate
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 
-	"github.com/devrites/devrites/internal/devritespaths"
 	"github.com/devrites/devrites/internal/reason"
 	"github.com/devrites/devrites/internal/state"
 )
@@ -27,50 +24,82 @@ const (
 	Seal Kind = "seal"
 )
 
-// Result is a gate outcome. Blocked is true iff a required section is missing;
-// Missing lists them in canonical order for an actionable message.
+// Result is a gate outcome. Blocked is true iff a deterministic requirement
+// failed; missing files and diagnostics retain their canonical policy order.
 type Result struct {
-	Kind          Kind
-	Slug          string
-	Phase         state.Phase
-	Target        state.Phase     // the phase whose requirements were checked
-	Missing       []state.Section // compact legacy view
-	MissingFiles  []string        // authoritative per-file view
-	StateProblems []string        // deterministic cross-file invariant failures
-	Blocked       bool
-	ReasonID      reason.ID
+	Kind            Kind
+	Slug            string
+	Phase           state.Phase
+	Target          state.Phase
+	Missing         []state.Section
+	MissingFiles    []string
+	Diagnostics     []state.ArtifactDiagnostic
+	AddContentFiles []string
+	StateProblems   []string
+	Blocked         bool
+	ReasonID        reason.ID
 }
 
-// Check runs a gate against feature <slug> under root. It reads workspace files
-// directly instead of trusting a cache. Invalid requests and unreadable state
-// return errors; missing required content returns a blocked Result.
+// Check runs a gate against feature <slug> under root. One workspace observation
+// supplies every lifecycle, question, and readiness fact used by the result.
 func Check(kind Kind, root, slug string) (*Result, error) {
-	f, err := state.LoadFeature(root, slug)
+	observation, err := state.ObserveWorkspace(root, slug)
 	if err != nil {
 		return nil, fmt.Errorf("gate %s: %w", kind, err)
 	}
-	target := f.Phase
+	result, err := checkObservation(kind, observation)
+	if err != nil {
+		return nil, fmt.Errorf("gate %s: %w", kind, err)
+	}
+	return result, nil
+}
+
+func checkObservation(kind Kind, observation *state.WorkspaceObservation) (*Result, error) {
+	phase, err := observation.DeclaredPhase()
+	if err != nil {
+		return nil, err
+	}
+	target := phase
 	if kind == Seal {
 		target = state.PhaseSeal
 	}
-	missing := state.MissingFor(f, target)
-	missingFiles := state.MissingWorkspaceFiles(f, target)
+	policy, ok := state.PolicyFor(target)
+	if !ok {
+		return nil, fmt.Errorf("unknown target phase %q", target)
+	}
+	target = policy.Target
+
+	missing := missingSections(observation, policy.RequiredSections)
+	missingArtifacts, diagnostics := observation.Missing(policy.RequiredArtifacts)
+	missingFiles := make([]string, len(missingArtifacts))
+	var addContentFiles []string
+	for i, artifact := range missingArtifacts {
+		missingFiles[i] = string(artifact)
+		fact, ok := observation.Fact(artifact)
+		if ok && (fact.State() == state.ArtifactAbsent || fact.State() == state.ArtifactEmpty) {
+			addContentFiles = append(addContentFiles, string(artifact))
+		}
+	}
 	blocked := len(missingFiles) > 0
 	readinessStale := false
 	var stateProblems []string
-	if gates, awaitingHuman := openHumanGates(devritespaths.FeatureDir(root, slug)); len(gates) > 0 {
-		problem := fmt.Sprintf("open %s human question(s) remain in questions.md", strings.Join(gates, "/"))
-		if !awaitingHuman {
-			problem += " but state.md is not awaiting_human"
+
+	if policy.BlocksOpenQuestions {
+		if gates, awaitingHuman := retainedHumanGates(observation); len(gates) > 0 {
+			problem := fmt.Sprintf("open %s human question(s) remain in questions.md", strings.Join(gates, "/"))
+			if !awaitingHuman {
+				problem += " but state.md is not awaiting_human"
+			}
+			stateProblems = append(stateProblems, problem)
+			blocked = true
 		}
-		stateProblems = append(stateProblems, problem)
-		blocked = true
 	}
-	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(target) {
-		expected, bindingErr := verifyReadinessBinding(root, slug)
+	if len(missingFiles) == 0 && phaseRequiresReadinessBinding(policy) {
+		expected, bindingErr := verifyReadinessBinding(observation)
 		if bindingErr != nil {
 			readinessStale = true
 			blocked = true
+			diagnostics = append(diagnostics, readinessDiagnostics(observation)...)
 			if expected == "" {
 				stateProblems = append(stateProblems, bindingErr.Error()+"; repair the input and rerun /rite-vet")
 			} else {
@@ -78,15 +107,18 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 			}
 		}
 	}
+
 	result := &Result{
-		Kind:          kind,
-		Slug:          slug,
-		Phase:         f.Phase,
-		Target:        target,
-		Missing:       missing,
-		MissingFiles:  missingFiles,
-		StateProblems: stateProblems,
-		Blocked:       blocked,
+		Kind:            kind,
+		Slug:            observation.Slug(),
+		Phase:           phase,
+		Target:          target,
+		Missing:         missing,
+		MissingFiles:    missingFiles,
+		Diagnostics:     diagnostics,
+		AddContentFiles: addContentFiles,
+		StateProblems:   stateProblems,
+		Blocked:         blocked,
 	}
 	result.ReasonID = ResultReasonID(kind, blocked)
 	if readinessStale {
@@ -95,6 +127,24 @@ func Check(kind Kind, root, slug string) (*Result, error) {
 	return result, nil
 }
 
+func missingSections(observation *state.WorkspaceObservation, required []state.Section) []state.Section {
+	var missing []state.Section
+	for _, section := range required {
+		artifact := state.ArtifactPath(string(section) + ".md")
+		switch section {
+		case state.SectionProof:
+			artifact = state.EvidenceFile
+		case state.SectionStatus:
+			artifact = state.LedgerFile
+		}
+		fact, ok := observation.Fact(artifact)
+		if !ok || fact.State() != state.ArtifactPresent {
+			missing = append(missing, section)
+		}
+	}
+	return missing
+}
+
 // ResultReasonID returns the typed outcome owned by the lifecycle gate.
 func ResultReasonID(kind Kind, blocked bool) reason.ID {
 	switch kind {
@@ -114,7 +164,7 @@ func ResultReasonID(kind Kind, blocked bool) reason.ID {
 }
 
 // Render returns stable, greppable output with a trailing newline. A blocked
-// result names the missing files and the command to rerun.
+// result names missing files, selected diagnostics, recovery, and the retry.
 func (r *Result) Render() string {
 	var b strings.Builder
 	fmt.Fprintf(&b, "gate: %s\n", r.Kind)
@@ -135,8 +185,17 @@ func (r *Result) Render() string {
 		fmt.Fprintf(&b, "result: blocked (missing to leave %q: %s)\n", r.Phase, strings.Join(missing, ", "))
 	}
 	fmt.Fprintf(&b, "reason: %s\n", r.ReasonID)
-	if len(missing) > 0 {
-		fmt.Fprintf(&b, "next: add real content to %s\n", strings.Join(missing, ", "))
+	for _, diagnostic := range r.Diagnostics {
+		fmt.Fprintf(&b, "artifact: %s: %s (%s)\n", diagnostic.Path, diagnostic.State, diagnostic.Code)
+	}
+	if len(r.AddContentFiles) > 0 {
+		fmt.Fprintf(&b, "next: add real content to %s\n", strings.Join(r.AddContentFiles, ", "))
+	}
+	for _, diagnostic := range r.Diagnostics {
+		if recovery := diagnosticRecovery(diagnostic, targetRequiresArtifact(r.Target, diagnostic.Path)); recovery != "" {
+			b.WriteString(recovery)
+			b.WriteByte('\n')
+		}
 	}
 	for _, problem := range r.StateProblems {
 		fmt.Fprintf(&b, "invariant: %s\n", problem)
@@ -145,19 +204,68 @@ func (r *Result) Render() string {
 	return b.String()
 }
 
+func diagnosticRecovery(diagnostic state.ArtifactDiagnostic, required bool) string {
+	prefix := fmt.Sprintf("next: repair %s: ", diagnostic.Path)
+	repair := diagnosticRepair(diagnostic.Code)
+	if repair == "" {
+		return ""
+	}
+	if required && diagnostic.Code == state.DiagnosticMalformedMarkdown {
+		repair += "; required artifacts need substantive content"
+	}
+	if !required {
+		repair += "; optional readiness input may instead be removed"
+	}
+	return prefix + repair
+}
+
+func targetRequiresArtifact(target state.Phase, path state.ArtifactPath) bool {
+	policy, ok := state.PolicyFor(target)
+	if !ok {
+		return false
+	}
+	for _, required := range policy.RequiredArtifacts {
+		if required == path {
+			return true
+		}
+	}
+	return false
+}
+
+func diagnosticRepair(code state.DiagnosticCode) string {
+	switch code {
+	case state.DiagnosticMalformedMarkdown:
+		return "replace invalid Markdown with valid Markdown"
+	case state.DiagnosticParentSymlink:
+		return "replace the symlinked parent with a real directory"
+	case state.DiagnosticFinalSymlink:
+		return "replace the symlink with a regular file"
+	case state.DiagnosticNonRegular:
+		return "replace the non-regular entry with a regular file"
+	case state.DiagnosticFileTooLarge:
+		return "reduce the file to at most 1 MiB"
+	case state.DiagnosticPermissionDenied:
+		return "grant read permission"
+	case state.DiagnosticReadFailure:
+		return "restore a readable regular file"
+	default:
+		return ""
+	}
+}
+
 const gateSpaceChars = " \t\n\v\f\r"
 
-func openHumanGates(featureDir string) ([]string, bool) {
-	qdata, err := os.ReadFile(filepath.Join(featureDir, "questions.md"))
-	if err != nil {
+func retainedHumanGates(observation *state.WorkspaceObservation) ([]string, bool) {
+	questions, ok := observation.Fact("questions.md")
+	if !ok || (questions.State() != state.ArtifactPresent && questions.State() != state.ArtifactEmpty) {
 		return nil, false
 	}
-	gates := openBlockingQuestionGates(qdata)
+	gates := openBlockingQuestionGates(questions.Bytes())
 	if len(gates) == 0 {
 		return nil, false
 	}
-	sdata, err := os.ReadFile(filepath.Join(featureDir, "state.md"))
-	return gates, err == nil && stateAwaitingHuman(sdata)
+	ledger, ok := observation.Fact(state.LedgerFile)
+	return gates, ok && ledger.State() == state.ArtifactPresent && stateAwaitingHuman(ledger.Bytes())
 }
 
 func openBlockingQuestionGates(data []byte) []string {