feat(explorer): v0.8.10 — directory view, /new creation, /stats dashboard

[tcballard]

Summary

Implements all three initiatives of rac/roadmaps/v0.8.x-explorer/v0.8.10-explorer-create-and-stats.md — this PR delivers the complete v0.8.10 release: the sidebar mirrors the repository's actual directory structure, /new creates artifacts through Core's create service behind a preview-and-confirm flow, and /stats opens a portfolio dashboard.

The happy path, end to end (first launch → directory sidebar → palette quick-open → reading → health → editor handoff → live reload → settings):

Adds:

• A folders sidebar grouping — the new default — rendering directories as collapsible nodes (name with a trailing / and a dim artifact count), nested exactly as on disk; expansion and cursor survive manual and watcher-driven reloads at any depth, and /open reveals a nested artifact by expanding its ancestor chain
• /new [type] [path]: previews the canonical template (ID noted as assigned on write), y confirms, and the write goes only through Core's create_artifact — the ID is minted against the repository index; existing paths, missing directories, and uninitialized repositories refuse with recoverable guidance and nothing written. On success the Explorer reloads and opens the new artifact, ready for e. Bare /new lists the creatable types.
• /stats: a portfolio dashboard — per-type validity, requirement/metric/risk totals, decision status and category breakdowns, relationship counts — collected from the stats service in a worker on request, never during repository load, scrollable under the keyboard
• /browse [type] listing in the filterable results view in every grouping mode (bare /browse focuses the sidebar)
• The v0.8.10 roadmap contract, the walkthrough GIF as a documentation asset (ADR-019), tests, CLI docs, design updates, and the changelog entry

Roadmap / ADR Trace

Roadmap:

• rac/roadmaps/v0.8.x-explorer/v0.8.10-explorer-create-and-stats.md

Relevant ADRs:

• rac/decisions/adr-015-explorer-as-consumer.md — the adapter builds the directory tree, renders templates via render_artifact, and dashboards via collect_stats; the Explorer owns no intelligence
• rac/decisions/adr-021-templates-product-contracts.md / adr-026-opaque-artifact-identities.md — /new renders no templates and mints no IDs of its own; Core's create service is the only writer
• rac/decisions/adr-024-rac-not-content-store.md — creation is knowledge correctness, not editing: preview-confirmed structure, authoring hands off to the external editor; the boundary reasoning is recorded in the contract
• rac/decisions/adr-023-clean-break-internal-refactors.md — focus_group removed with its only caller
• rac/decisions/adr-028-explorer-surface.md — directory rows and dashboard sections carry text labels, never colour alone
• rac/decisions/adr-019-asset-management.md — the GIF lives as an external asset under docs/images/

Scope

Included

• GROUPING_FOLDERS as the artifact_grouping default; settings cycle folders → type → flat; explicit type/flat config values stay honored
• DirectoryNode on the additive BrowserState.tree; sidebar folder rendering with dir: + relpath data keys (posix-pinned), recursive expansion snapshot, O(1) node map
• The import view generalized into the one write workflow: the pending preview carries its writer, so y runs the right Core service (write_import vs create_artifact); the confirm-write modal is untouched
• Reload-then-open after creation: the screen holds the created path, reloads through the normal worker (refreshing the watcher baseline for free), and opens it once the load lands
• StatsState (section → lines) built synchronously in the adapter; the StatsView owns the collection worker, mirroring the import view's pattern
• Registry gains new and stats (15 commands); statusline hints for the stats region

Excluded

• Lazy folder population — the tree builds eagerly (validated at 1,200 artifacts in the scale test); type grouping keeps its lazy path
• Any filesystem watching changes — the v0.8.9 watcher's reload is reused as-is for folder continuity and post-creation refresh
• rac init from the Explorer — initialization stays a one-time CLI step; /new points at it when missing
• Per-artifact listings in the stats dashboard — browse and find already navigate artifacts
• Tagging/publishing v0.8.10 — the release ships when the maintainer tags

Product / Architecture Decisions

• Directory data keys are posix-pinned (PurePath(relpath).as_posix()) so expansion state is stable across platforms
• The creation preview is pure (render_artifact, no writes, no ID) with an explicit "(ID assigned on write)" note — preview and write can never disagree about who mints identity
• create_artifact's six failure modes each translate to a one-line recoverable message; the refusal paths verifiably write nothing
• The sidebar and /browse changes shipped as one commit (removing focus_group would break the route mid-sequence); /new and /stats likewise share one commit because they interleave in the same five files
• Stats collection re-walks the corpus, so it runs only on /stats invocation in an exclusive worker; the view shows a collecting line meanwhile

User-Facing Contract

CLI

No CLI command surface changes. Entry point remains rac explorer [directory].

Human Output (Explorer)

• Sidebar shows decisions/, roadmaps/ … nested exactly as on disk, counts beside each directory; /settings cycles folders | type | flat
• /new decision rac/decisions/adr-xyz.md → template preview → y → "Created … (ID RAC-…)" → the artifact opens; refusals explain themselves and write nothing
• /stats → Portfolio Statistics with Overview, Requirements & Quality, Decisions, and Relationships sections
• /browse decision renders in the results panel (filterable with f) in every mode

JSON Output

None — explorer.json schema unchanged; the new grouping default applies only when the key is absent or unknown.

Exit Codes

Unchanged.

Verification

Ran

pytest --ignore=tests/test_ingest.py   # 839 passed
ruff check . && python -m mypy src/    # clean
rac validate rac/                       # PASS — 85 valid, 0 invalid
rac relationships rac/ --validate       # 0 issues (159 checked)
rac review rac/                         # no priority 1–2 findings

tests/test_ingest.py exclusion is the known container cryptography issue, unrelated to this diff.

Covered

• Directory view: nesting from a real roadmaps/v1/ tree, expansion/cursor across r and watcher reloads, nested /open reveal, directory rows neither opening nor editing, the three-value settings cycle, the 1,200-artifact eager build
• Creation: preview shape (ID note, template body, nothing written); success path in an rac init-ed repo (file exists, frontmatter carries the minted RAC- ID, the context view opens it, the sidebar contains it); refusals — existing target, missing directory, uninitialized repo, unknown type — each write nothing
• Stats: dashboard sections from the portfolio fixture (totals match rac stats' own test corpus); the view renders, scrolls, and Esc returns
• /browse in folders and type modes; bare /new type listing with usage; the registry contract re-pinned for v0.8.10 (15 commands)

Review Path

1. src/rac/explorer/adapter.py — _directory_tree, new_preview/write_new, stats_state, type_rows
2. src/rac/explorer/widgets/views.py — the generalized write workflow (ImportView), StatsView, ArtifactCreated
3. src/rac/explorer/widgets/sidebar.py — folder rendering, expansion snapshot, node map, reveal
4. src/rac/explorer/screens/main.py — /new//stats//browse routing, reload-then-open
5. src/rac/explorer/preferences.py, state.py, commands.py, statusline.py — defaults, DirectoryNode/StatsState, registry, hints
6. Tests (the v0.8.10 sections at the end of the app/adapter batteries), then docs/cli.md, the design artifacts, CHANGELOG.md, the roadmap contract, docs/images/

Notes For Reviewer

• This PR now completes v0.8.10 — earlier revisions of this body listed /new and /stats as excluded follow-ups; they're in
• The branch was rebased onto main before the PR opened, so the commit list is exactly the v0.8.10 work
• The GIF embeds from this branch's raw URL; after merge it resolves on main at the same path
• A bare decision template (TODO placeholders) classifies and validates, which is why the created artifact appears in the sidebar immediately

Implementation Process

Implemented with AI assistance under the roadmap contract. Final scope, review, and acceptance decisions were made by the maintainer.