repo-scoping/workplans/RREG-WP-0003-automatic-repository-exploration.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
RREG-WP-0003	workplan	Repository Ability Registry — Automatic Repository Exploration	capabilities	repo-registry	active	codex	foerster-capabilities	2026-04-26	2026-04-28	c121d462-f2e4-45d3-9d2d-9c04a3556953

RREG-WP-0003 — Automatic Repository Exploration

Goal

Make the first-run experience feel like a useful product: a user can register a repository, ask the registry to explore it, and quickly land on a populated, source-linked ability profile. The system must preserve the core trust model: deterministic facts are observed, interpreted ability claims are reviewable, and canonical registry truth is either explicitly approved by a human or by a clearly configured trusted automation mode.

P0: One-Click Register And Explore

id: RREG-WP-0003-T01
status: done
priority: high
state_hub_task_id: "ab718ce7-d38f-4080-9385-99be1bf80475"

Add a UI and API flow that registers a repository and immediately starts analysis when requested. In the UI, the repository registration form should offer a clear Explore after registration option enabled by default. The resulting screen should show analysis progress/result, observed facts, candidate abilities, and the next recommended action without requiring the user to hunt for the analysis button.

Acceptance: registering /home/worsch/repo-registry from the UI can complete an analysis run in one flow and land on the reviewable candidate graph.

P0: Self-Analysis Quality Pass

id: RREG-WP-0003-T02
status: done
priority: high
state_hub_task_id: "d0d98e1b-8d21-4bdf-af58-edbb34e8a929"

Use this repository as the first golden demo target. Improve deterministic scanning and candidate generation where needed so repo-registry produces a useful ability map for itself: repository ingestion, deterministic scanning, candidate review workflow, discovery/search, UI curation, and operational/state-hub coordination should be visible as source-linked claims.

Acceptance: a self-analysis run produces non-trivial, source-linked candidate abilities and capabilities that a curator would recognize as the repo's real purpose. A one-to-one correspondence of observed fact to generated feature is a quality smell: features should describe user-visible or operational behavior, with facts as drilldown evidence, not mirror individual scanner facts.

P0: Abstraction Strategy And LLM Boundary

id: RREG-WP-0003-T06
status: done
priority: high
state_hub_task_id: "51890aff-511d-4635-85c4-fe4db0b7dd01"

Document and test how the registry should climb from deterministic observed facts to useful ability/capability/feature abstractions. Explicitly compare what can be done deterministically against what likely needs LLM assistance. Preserve the trust boundary: deterministic scanners establish facts; abstraction may propose claims; review or trusted automation decides approved registry truth.

Acceptance: docs/ contains an abstraction strategy note with examples from the three trial repos, and candidate generation has at least one regression guard against feature granularity collapsing into one feature per observed fact.

P1: Guided Review To Populated Registry

id: RREG-WP-0003-T03
status: done
priority: medium
state_hub_task_id: "5c4b5bb1-390c-4782-bb70-104b0006fe67"

Polish the candidate review path so the user can approve, edit, merge, or reject generated claims from a single coherent screen. After approval, route to the approved ability map and make search/discovery/export actions immediately visible.

Acceptance: after self-analysis, a user can populate the canonical registry with approved entries in one review session and then see them in search, discovery, and export.

P1: Trusted Auto-Populate Mode

id: RREG-WP-0003-T04
status: todo
priority: medium
state_hub_task_id: "076385fe-4dbf-4aca-b89f-c7372d9eebd9"

Add an explicit opt-in automation mode for local/demo use that approves a candidate graph automatically after analysis. This must be visibly labeled and record a review decision showing that the approval was automated. The default production posture should remain review-first.

Acceptance: a local user can choose fully automated exploration that registers, analyzes, and populates the approved registry, while default mode still requires review.

P2: First-Run Delight And Diagnostics

id: RREG-WP-0003-T05
status: todo
priority: low
state_hub_task_id: "b812a7fb-19ef-418a-83a2-15bf26fd3f4a"

Add clear success states, useful empty states, and diagnostics for common first-run problems such as invalid local paths, inaccessible Git URLs, empty repos, and runs that produce only weak candidates.

Acceptance: trying the product on repo-registry itself feels understandable and useful even when a scan finds gaps or weak evidence.