---
schema_version: 1
id: RAC-KTTMMPNG4PNE
type: roadmap
---
# RAC v0.8.9 — Explorer Live Workspace and Validation Depth

## Status

Planned

## Context

v0.8.8 completed the Explorer as a reader: a summoned palette, walkable
hypertext, interactive settings, and a refined frame. Living in it surfaced
the next gap: the Explorer is still a snapshot. The RAC workflow is edit in
the editor, check in the tool — and that loop currently has a manual reload
keystroke in the middle of it. When the check fails, the Explorer says an
artifact is invalid but not why; the user drops to the CLI for the reason.

This milestone makes the Explorer a live companion: the repository view
follows the filesystem, an invalid artifact explains itself where it is
displayed, improvement suggestions reach the Findings tab, and the command
surface gains the small depths a daily driver needs — schema reference,
recent artifacts in the palette, and filterable search results. All
intelligence already exists in Core services; this release consumes it
(ADR-015).

## Outcomes

- The Explorer stays current without being asked: edit an artifact in the
  configured editor, and the open views, sidebar, and health chip reflect
  the save when focus returns.
- An invalid artifact answers "why" in place: the validation issues that
  the CLI reports appear on the artifact's own Inspection tab.
- The Findings tab carries everything Core knows how to say about an
  artifact, including improvement suggestions.
- The palette remembers and teaches: recent artifacts surface before a
  character is typed, and schema reference is one command away.

## Initiatives

### Initiative 1 — Live Repository Reload

The Explorer watches the loaded repository and refreshes itself when
artifacts change on disk. A periodic stdlib mtime scan (no new dependency)
detects edits, additions, and removals; a change reloads the repository in
the existing worker, preserving sidebar expansion, cursor, and the open
artifact. The health chip, context tabs, and badges update with it.
Returning from a suspended terminal editor triggers an immediate check, so
the edit-and-look loop closes by itself. The watcher pauses while the
application is suspended and stops with the app. Manual reload remains.

### Initiative 2 — Validation Drill-Down

The Inspection tab's diagnostics section shows the artifact's actual
validation issues — the same issues `rac validate` reports — consumed from
the existing validate service. Each issue carries its severity and message;
a valid artifact states that plainly. The health view's attention list
links into artifacts whose Inspection tab now explains the problem, closing
the "invalid — now what?" dead end without leaving the Explorer.

### Initiative 3 — Improvement Suggestions on Findings

For artifact types the improve service supports, the artifact's Findings
tab gains an improvement group sourced from `improve_file`, alongside the
existing review-derived findings. The Findings badge counts them. Types
without improve support show nothing new. The Explorer renders the
suggestions; it never applies them (ADR-024).

### Initiative 4 — Command Surface Depth

Three palette refinements:

- `schema [type]` — bare lists the artifact types with a one-line purpose;
  with a type, renders the expected structure (sections, metadata) in the
  results view, consumed from the core schema module.
- Recent artifacts in the palette — the workspace records the last
  artifacts opened per repository; summoning the palette with empty input
  shows them above the command registry, Enter reopens one.
- Filterable results — the results view gains a type filter row, cyclable
  from the keyboard, so a broad `find` narrows without retyping.

## Implementation Contract

The following decisions are pinned for v0.8.9.

### Watcher

- A `MainScreen` interval timer (~2s) runs a worker-thread mtime/path-set
  scan over the loaded artifact paths and repository directories; stdlib
  only, no `watchfiles` or similar. A detected change debounces into one
  repository reload through the existing `adapter.load` path. Resume from
  `App.suspend()` forces a scan. The timer never runs before the first
  successful load or after a load error.

### Validation detail

- `rac.explorer.adapter` sources per-artifact issues from
  `rac.services.validate` (`FileValidation.issues`); `ContextState` carries
  them as typed rows (severity, message). No new Core logic, no JSON
  contract movement (ADR-015).

### Improvements

- The adapter calls `rac.services.improve.improve_file` only for specs
  where `supports_improve` holds, on artifact open (not during repository
  load). Suggestions join `ContextState` findings under a distinct group
  label.

### Command surface

- `schema` joins the command registry and routes to the results view;
  schema data comes from `rac.core.schema` through the adapter.
- `rac.explorer.workspace.Workspace` gains a per-repository recent-artifact
  list (limit 8, deduped, additive JSON — older state files load
  unchanged). The palette's empty state lists recents above commands.
- The results-view filter is presentation state only; it refilters rows
  already returned by the existing search.

### Scope

- No new dependencies; no Core or service changes; no new screens. The
  explorer battery absorbs all tests, including watcher debounce and
  workspace round-trip coverage.

## Non-Goals

- Artifact creation from the Explorer (`/new`) — touches the write
  boundary and needs an ADR-024 review first; deferred.
- A stats/portfolio dashboard view — candidate for v0.8.10.
- Diff views, bulk operations, or relationship graph visualization.
- Third-party filesystem watching or inotify integration.
- Applying improvement suggestions to artifact files.

## Success Measures

- Saving an artifact in an external editor updates the open Explorer
  within a few seconds with no keystroke, and sidebar position survives.
- For any invalid artifact, the reason `rac validate` would give is
  readable on its Inspection tab.
- `schema decision` answers the "what sections does it need" question
  without leaving the Explorer.
- Summoning the palette in a familiar repository offers the artifacts the
  user actually works in before any typing.

## Assumptions

- Repository sizes stay in the range where a 2-second mtime scan is
  negligible; the v0.7.x corpus scale (hundreds of artifacts) is the
  design point.
- The validate and improve services remain stable interfaces; the
  Explorer consumes them as-is.

## Risks

- Reload racing an in-progress save could render a half-written artifact;
  debouncing and the existing load-error recovery path bound the damage to
  one cycle.
- Per-open `improve_file` calls add latency to artifact open on large
  documents; the call stays off the repository-load path and can be
  deferred to the Findings tab activation if measured as noticeable.
- The palette's empty state grows two purposes (recents and registry);
  if it reads as cluttered, recents collapse to a single labelled group
  that keyboard users can skip past.

## Related Decisions

- ADR-015
- ADR-024
- ADR-028

## Related Designs

- explorer-command-surface
- explorer-health-model
- explorer-recommendations
- explorer-editor-integrations

## Related Requirements

- rac-product-knowledge-navigator-explorer

## Dependencies

- v0.8.8 explorer command palette
