devrites 4.0.12 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 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
+
+* **rite:** add bounded host-native loop operations ([af8f50e](https://github.com/ViktorsBaikers/DevRites/commit/af8f50e434160a7ab33d7e4c8b5b387c4097bfdc))
+* **rite:** deepen engineering risk guidance ([a109d35](https://github.com/ViktorsBaikers/DevRites/commit/a109d35788d831f037361cbc5c491d0b2cb2dd64))
+* **rite:** govern decision horizons and learnings ([af48088](https://github.com/ViktorsBaikers/DevRites/commit/af48088157107e08f60a82659d7e445180ed1e96))
+
 ## [4.0.12](https://github.com/ViktorsBaikers/DevRites/compare/v4.0.11...v4.0.12) (2026-08-09)
 
 ### Fixed

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.0.12`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v4.0.12): 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.
 
@@ -381,8 +381,8 @@ through Claude Code or Codex plugin stores.
 
 ## Skills and agents
 
-The pack ships 43 skills: 32 public and 11 internal. The public surface contains
-the `rite` menu and 31 `rite-*` workflows and utilities. Ten `devrites-*`
+The pack ships 44 skills: 33 public and 11 internal. The public surface contains
+the `rite` menu and 32 `rite-*` workflows and utilities. Ten `devrites-*`
 specialists load when a matching task needs them; `devrites-lib` carries the
 shared contracts and engineering standards.
 

package/docs/architecture.md

@@ -33,8 +33,8 @@ cursor readers, traceability rules, and phase-relative completeness model, see
 2. **Public utility and on-ramp skills**: `rite-adopt`, `rite-quick`,
    `rite-frame`, `rite-status`, `rite-doctor`, `rite-upgrade`, `rite-learn`, `rite-explain`,
    `rite-customize`, `rite-zoom-out`, `rite-prototype`, `rite-handoff`,
-   `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, and
-   `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
+   `rite-pressure-test`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`,
+   `rite-watch-pr`, and `rite-autocomplete`. These are public commands. `rite-autocomplete` is the
    unattended orchestrator. By default it drives the reversible lifecycle
    through Seal GO and stops. Explicit `--ship` enters Ship preflight but still
    waits for a fresh literal `GO` and native approval before mutation. It
@@ -381,8 +381,8 @@ contract.
 
 ## Design choices at a glance
 
-- **Surface**: 31 public `rite-*` skills (43 total), plus the thin `/rite`
-  menu: 32 public and 11 internal. The lifecycle
+- **Surface**: 32 public `rite-*` skills (44 total), plus the thin `/rite`
+  menu: 33 public and 11 internal. The lifecycle
   includes mandatory adaptive Clarify, optional Temper, mandatory Vet, and
   Converge recovery; Seal **decides** and Ship **executes + closes**. Ten
   `devrites-*` specialist skills are model-invoked; `devrites-lib` is the

package/docs/command-map.md

@@ -19,8 +19,8 @@ mean that a skill is internal; each `SKILL.md` uses `user-invocable:` to set
 visibility. Public utilities use the `rite-*` prefix: `rite-quick`,
 `rite-frame`, `rite-adopt`, `rite-learn`, `rite-doctor`, `rite-customize`,
 `rite-zoom-out`, `rite-prototype`, `rite-handoff`, `rite-pressure-test`,
-`rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`, and
-`rite-pr-feedback`, plus the evidence-gated workspace compatibility command
+`rite-autocomplete`, `rite-explain`, `rite-pov`, `rite-dogfood`,
+`rite-pr-feedback`, and `rite-watch-pr`, plus the evidence-gated workspace compatibility command
 `rite-upgrade`. The host may invoke `devrites-*` specialists through the model.
 `devrites-lib` is the non-workflow library exception.
 
@@ -113,6 +113,7 @@ See [`cli.md`](cli.md).
 | [`/rite-pov`](../pack/.claude/skills/rite-pov/SKILL.md) | utility | `[candidate/link/question]` | Project-grounded verdict on one outside option after live repository and primary-source evidence. | live code/docs + external sources | `decisions.md` or ADR only on request |
 | [`/rite-dogfood`](../pack/.claude/skills/rite-dogfood/SKILL.md) | utility | `[feature-slug\|branch] [--port N]` | Diff-scoped browser QA: map changed user journeys, run scenario matrix, fix small obvious breakages, write dogfood report. Explicit-only. | diff + app routes + browser | `.devrites/work/<slug>/dogfood.md` + safe fixes |
 | [`/rite-pr-feedback`](../pack/.claude/skills/rite-pr-feedback/SKILL.md) | utility | `[PR number\|thread URL\|blank for current branch]` | Resolve GitHub PR review feedback: fetch unresolved threads, judge centrally, fix valid items, reply, resolve. Explicit-only. | PR threads + code | code/tests + PR replies/resolutions |
+| [`/rite-watch-pr`](../pack/.claude/skills/rite-watch-pr/SKILL.md) | utility | `[PR number\|PR URL\|blank for current branch]` | Observe one GitHub PR/CI/review snapshot, classify one next action, and stop. Safe for capability-admitted native schedules/events; never mutates code, Git, checks, threads, or PR state. | PR/check/review metadata + bounded failed-log excerpts | none |
 | [`/rite-pressure-test`](../pack/.claude/skills/rite-pressure-test/SKILL.md) | utility | `[idea]` | Pressure-test a rough idea: 3 to 5 genuinely different options → converge on one with trade-off + hinge. | spec / surrounding code | `decisions.md` (optional) |
 | [`/rite-doctor`](../pack/.claude/skills/rite-doctor/SKILL.md) | diagnostic | none | Diagnose the DevRites binary, pack, schema, and native host permission/profile configuration. | install + host config | none |
 
@@ -183,7 +184,7 @@ index is in
 [`pack/.claude/skills/devrites-lib/reference/standards/README.md`](../pack/.claude/skills/devrites-lib/reference/standards/README.md).
 
 - `core.md` (always-on): operating rules + universal anti-rationalizations + 1-line craft disciplines + persistence-before-stopping summary.
-- On-demand rules and checklists (read by the phase that needs them): `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `edge-case-trace.md` · `principles.md` · `security.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `ci-cd.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `elicitation.md` · `agents.md` · `context-hygiene.md` · `anti-patterns.md` · `afk-hitl.md` · `tooling.md` · `skill-authoring.md` · `definition-of-done.md` · `review-checklist.md` · `test-proof-checklist.md` · `browser-proof-checklist.md` · `security-checklist.md`
+- On-demand rules and checklists (read by the phase that needs them): `coding-style.md` · `prose-style.md` · `error-handling.md` · `testing.md` · `spec-grammar.md` · `code-review.md` · `edge-case-trace.md` · `principles.md` · `security.md` · `repository-topology.md` · `data-integrity.md` · `integration-reliability.md` · `performance.md` · `observability.md` · `developer-experience.md` · `patterns.md` · `git-workflow.md` · `ci-cd.md` · `hooks.md` · `documentation.md` · `development-workflow.md` · `deprecation.md` · `elicitation.md` · `agents.md` · `context-hygiene.md` · `anti-patterns.md` · `afk-hitl.md` · `loop-operations.md` · `tooling.md` · `skill-authoring.md` · `definition-of-done.md` · `review-checklist.md` · `test-proof-checklist.md` · `browser-proof-checklist.md` · `security-checklist.md`
 - `anti-patterns.md`: pack-wide rationalizations + red flags. Loaded by each per-phase `rite-*/reference/anti-patterns.md`; can be loaded directly for cross-phase reluctance.
 
 ## Trigger conditions (auto-selection)

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/docs/flow.md

@@ -375,7 +375,7 @@ separately by `disable-model-invocation`.
 
 ```mermaid
 flowchart TB
-    subgraph Public["Public (user-invocable: true): 32 skills"]
+    subgraph Public["Public (user-invocable: true): 33 skills"]
         direction TB
         R1[/rite/]
         R2[/rite-spec/]
@@ -405,6 +405,7 @@ flowchart TB
         RDO[/rite-dogfood/]
         RPOV[/rite-pov/]
         RPF[/rite-pr-feedback/]
+        RWP[/rite-watch-pr/]
         IPT[/rite-pressure-test/]
         D1[/rite-zoom-out/]
         D2[/rite-prototype/]

package/docs/orchestration.md

@@ -28,8 +28,9 @@ root reconciles semantics; engine checks deterministic structure/state/safety
   workspace-capable for its writer child to execute.
 - The role catalog has one source/test writer, `devrites-slice-wright`. Claude
   and Codex make only that exact specialist writable.
-- Leaves never invoke leaves, ask the human, change phase, commit, push, deploy,
-  migrate live data, or write canonical workflow state.
+- Leaves never invoke leaves, ask the human, change phase, push, deploy, migrate live
+  data, or write canonical workflow state. Only an eligible isolated-worktree wright
+  may create one local unpushed transfer commit; same-worktree leaves never commit.
 
 Skills name the exact role and bounded task in normal language. The host owns
 internal spawn fields, scheduling, waiting, follow-ups, and result delivery.
@@ -65,6 +66,35 @@ sibling cannot erase it.
 An evidenced clean result is valid. Reviewers must account for their rubric and
 inspected scope, but they never manufacture a finding to fill a quota.
 
+## Read-only Claude workflow pilot
+
+Claude installs `.claude/workflows/devrites-readonly-review.js` as an optional
+adapter for immutable-candidate discovery, four independent reviewer roles, one
+adversarial verification pass, and a completeness check. Its script owns only
+transient fan-out and intermediate results. It cannot write source, tests,
+`.devrites/**`, Git, proof, lifecycle state, or shared services; it never invokes
+`devrites-slice-wright`.
+
+The caller still admits every returned role result under the normal result-closure
+contract and performs final reconciliation. A workflow timeout, missing role,
+malformed result, unread input, or incomplete verification is a gap. The adapter does
+not replace `/rite-review`, alter required rosters, or create another durable state
+plane.
+
+Codex keeps the same portable skill/agent semantics through native agent dispatch and
+has no fake workflow mirror. Provider parity applies to review meaning and evidence,
+not to this optional Claude orchestration optimization. Use the pilot only when an
+immutable candidate already exists; lifecycle writes, proof execution, human gates,
+and final decisions remain with the rite root.
+
+Host capabilities are admitted independently. Codex CLI agent threads and inherited
+sandboxes establish context/permission separation, not filesystem worktree isolation;
+without an explicit named-agent worktree and reconciliation interface, Codex uses the
+serial same-worktree writer. Likewise, goals or hooks do not prove native time/event
+activation. Unsupported activation remains `unavailable` rather than being emulated by
+a DevRites scheduler or shell loop. The claim-bounded acceptance rows live in
+[`codex-acceptance.json`](../evals/native-host/codex-acceptance.json).
+
 ## Slice-wright lifecycle
 
 For Claude or Codex, the root states the smallest exact project-relative source
@@ -86,8 +116,19 @@ symlink escapes, duplicates, and `.devrites/**` are invalid.
 Exact-path scope is instruction-backed on both hosts; native sandboxes provide
 the broader writer/read-only split. An unauthorized delta is rejected and the
 same bounded writer must restore it before work continues. The root never
-widens the contract or rewrites source. Parallel source writers in one worktree
-are forbidden.
+widens the contract or rewrites source.
+
+A serial native-worktree pilot may isolate `devrites-slice-wright` when the candidate
+baseline is committed and clean, the repository is not a submodule child, baseline
+proof is green, and the host exposes explicit result reconciliation. The wright
+returns one local unpushed transfer commit; root proves its exact paths and unchanged
+base before native transfer, then re-proves the reconciled candidate. Missing transfer,
+conflict, extra paths, moved base, or cleanup failure stops with worktree evidence
+preserved. No ad hoc copy/cherry-pick/merge occurs from the read-only root.
+
+Isolation does not authorize throughput. At most one writer runs across all linked
+worktrees for the workspace; parallel writers remain forbidden until serial transfer,
+conflict, proof, and review measurements justify a separate design.
 
 ## Engine boundary
 

package/docs/skills.md

@@ -1,6 +1,6 @@
-# All 43 skills
+# All 44 skills
 
-The pack contains 43 skills: the `rite` menu, 31 user-invocable `rite-*`
+The pack contains 44 skills: the `rite` menu, 32 user-invocable `rite-*`
 workflow and utility skills, 10 model-invoked `devrites-*` specialists, and the
 internal `devrites-lib` library. `devrites-lib` is not a command. It holds shared
 references and the few explicit script exceptions.
@@ -37,7 +37,7 @@ contract when a rite names parallel reviewers.
 
 `rite-*` is the namespace for lifecycle and utility commands. Its utilities are
 `rite-quick`, `rite-frame`, `rite-adopt`, `rite-learn`, `rite-customize`,
-`rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-doctor`,
+`rite-explain`, `rite-pov`, `rite-dogfood`, `rite-pr-feedback`, `rite-watch-pr`, `rite-doctor`,
 `rite-upgrade`, `rite-prototype`, `rite-handoff`, `rite-zoom-out`, and
 `rite-pressure-test`.
 Some specialized utilities set `disable-model-invocation: true` and run only
@@ -231,6 +231,7 @@ and `Shipped`. Utility commands keep the same compact labels and one-next-action
 | [`rite-pov`](../pack/.claude/skills/rite-pov/SKILL.md) | Project-grounded verdict on a named external option: adopt / trial / hold / reject / not-our-problem after project + external floors clear. | "should we adopt X", "switch to Y", CVE/deprecation relevance, bounded external comparisons. |
 | [`rite-dogfood`](../pack/.claude/skills/rite-dogfood/SKILL.md) | Diff-scoped browser QA: map changed user journeys, run scenario matrix, fix small obvious breakages, write `dogfood.md`. | Explicit-only after prove/polish/review when browser UX confidence matters. |
 | [`rite-pr-feedback`](../pack/.claude/skills/rite-pr-feedback/SKILL.md) | Resolve PR review feedback: fetch unresolved threads, judge centrally, fix valid items, reply, resolve. | Explicit-only: `/rite-pr-feedback` / `/rite pr-feedback`. |
+| [`rite-watch-pr`](../pack/.claude/skills/rite-watch-pr/SKILL.md) | Observe one PR/CI/review snapshot and report one next action without mutation. | Read-only capability-admitted native schedule/event observation or `/rite-watch-pr`. |
 
 ### Foundation: engineering rules
 

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/devritespaths/paths.go

@@ -13,10 +13,11 @@ import (
 const (
 	DevritesRootName = ".devrites"
 
-	ClaudeSkillsTarget = ".claude/skills"
-	CodexSkillsTarget  = ".agents/skills"
-	ClaudeAgentsTarget = ".claude/agents"
-	CodexAgentsTarget  = ".codex/agents"
+	ClaudeSkillsTarget    = ".claude/skills"
+	CodexSkillsTarget     = ".agents/skills"
+	ClaudeAgentsTarget    = ".claude/agents"
+	CodexAgentsTarget     = ".codex/agents"
+	ClaudeWorkflowsTarget = ".claude/workflows"
 
 	ManifestName = ".claude/devrites.manifest"
 )

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 {