generated from coulomb/repo-seed
265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
---
|
|
id: RREG-WP-0003
|
|
type: workplan
|
|
title: "Repository Ability Registry — Automatic Repository Exploration"
|
|
domain: capabilities
|
|
repo: repo-registry
|
|
status: done
|
|
owner: codex
|
|
topic_slug: foerster-capabilities
|
|
created: "2026-04-26"
|
|
updated: "2026-04-29"
|
|
state_hub_workstream_id: "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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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.
|