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	done	codex	foerster-capabilities	2026-04-26	2026-04-29	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: done
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: done
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.

Implementation note 2026-04-29: analysis result pages now include a Run Diagnostics panel with explicit success, failure, empty-result, no-candidate, and weak-candidate states. The panel links directly to fact and candidate element lists and gives first-run recovery hints for bad paths, inaccessible sources, credential issues, and upstream timeouts.

P1: Expectation Gap Feedback Loop

id: RREG-WP-0003-T07
status: done
priority: medium
state_hub_task_id: "8f49fffe-c7bf-4b59-b3c3-fafe89d75e53"

Capture the gap between what a curator expected to see and what deterministic analysis actually produced. Treat these gaps as first-class scanner optimization inputs: a user should be able to record missing expected abilities, capabilities, features, facts, or classifications for an analyzed repository. The system should preserve the source of the expectation (human, llm-assisted, or comparison) and link it to the analysis run that missed it.

Acceptance: after inspecting a repository such as llm-connect, a curator can record that expected concepts like OpenRouter provider support, Claude model usage, or provider fallback policy were missing. The gap is visible from the repository/review UI and can be used to create deterministic scanner regression fixtures.

P1: Provider-Aware Deterministic Scanning

id: RREG-WP-0003-T08
status: done
priority: medium
state_hub_task_id: "93fd4bdc-bfdf-4f2b-95ad-1106094c7e23"

Extend deterministic scanning and content indexing to identify provider and integration concepts that generic language/framework/file facts miss. Initial targets are LLM infrastructure repositories: OpenRouter, Anthropic/Claude, OpenAI, Gemini, model-provider registries, credential environment variables, adapter classes, routing rules, and fallback policies. These should appear as source-linked facts and map into useful candidate capabilities/features without requiring LLM assistance.

Acceptance: analyzing llm-connect with LLM assistance disabled can surface source-linked facts and candidate graph entries for OpenRouter support, Claude or Anthropic support where present, provider configuration/credentials, and any explicit model fallback behavior found in code, docs, or config.

P1: Scanner Coevolution Regression Harness

id: RREG-WP-0003-T09
status: done
priority: medium
state_hub_task_id: "fe0a7807-9caa-4425-b66b-c88a2a09ece3"

Create a repeatable improvement loop where reviewed expectation gaps become fixtures and tests. For each trial repository, store a small expectation profile that lists important concepts the deterministic scanner should eventually detect. Compare deterministic outputs against optional LLM-assisted or human-curated expectations, then promote confirmed misses into scanner/candidate-generator regression tests.

Acceptance: the repository has at least one expectation fixture for an LLM infrastructure repo and a test that fails if deterministic analysis stops surfacing expected provider concepts. The workflow remains LLM-optional: LLMs may suggest expectations, but deterministic tests encode the accepted learning.

Follow-up hardening completed 2026-04-29: candidate graphs are normalized before storage so duplicate or overlapping LLM/deterministic claims merge into one review item while preserving stronger descriptions, confidence, source refs, and nested capabilities/features/evidence.

P1: Characteristic Scope And Evidence Model

id: RREG-WP-0003-T10
status: done
priority: medium
state_hub_task_id: "0d3fa9e0-bb3e-4bf2-bf8d-4681c5b7bdf5"

Evolve the registry model from a fixed Ability → Capability → Feature → Evidence presentation into a repository characteristic model with a single Scope root above abilities. Treat abilities, capabilities, and features as characteristics at different abstraction levels. Evidence should be modeled as support for a characteristic and may reference observed facts or lower-level characteristics; upward references from features to capabilities/abilities should be avoided, and same-layer references should be allowed but treated as a review smell that can indicate suboptimal granularity or organization.

Acceptance: the UI explains and presents scope as the root of the approved characteristic tree, separates features from evidence/support under each capability, and allows manual tuning of evidence in a way that makes the support relationship clear. The data model has an additive path toward characteristic references so existing approved/candidate workflows continue to work while future iterations can link evidence to facts or deeper characteristics.

Implementation note 2026-04-29: approved and candidate evidence now carry additive support metadata: target_kind, target_id, reference_kind, and reference_id. Existing capability-bound evidence remains compatible, while the UI exposes these fields as supported-characteristic and reference metadata.

Implementation note 2026-04-29: repository scope is now first-class. A repository_scopes row is created for new repositories and backfilled lazily for existing repositories. The ability-map model and API include scope, and the UI allows editing the scope root above approved abilities.

Implementation note 2026-04-29: the element browser now includes approved scope and support/evidence rows. Count badges link to scope and support listings, and support rows show both the supported characteristic target and the referenced source/fact/characteristic metadata.

Implementation note 2026-04-29: candidate support/evidence can now be accepted from the UI and service layer. Accepting support promotes the parent ability and capability context as needed, records a review decision, marks the candidate support approved, and maps capability support targets to the approved capability ID.

Implementation note 2026-04-29: support rows now show an orientation label based on target/reference abstraction levels. Downward support is normal, same-level support is marked for review, and upward support is marked for review because it usually indicates an abstraction or organization problem.

Implementation note 2026-04-29: support listings now include a support orientation filter so reviewers can isolate downward support, same-level review items, upward review items, or unclassified support.