From 04faa6e6f3f18906993994a038556da5d1258842 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 26 Apr 2026 12:54:13 +0200 Subject: [PATCH] Closed mvp implementation workplan with followup for production hardening --- workplans/ImplementationWorkplan.md | 22 +++ workplans/ProductionHardeningWorkplan.md | 185 +++++++++++++++++++++++ 2 files changed, 207 insertions(+) create mode 100644 workplans/ProductionHardeningWorkplan.md diff --git a/workplans/ImplementationWorkplan.md b/workplans/ImplementationWorkplan.md index 3b2de56..36fd6c9 100644 --- a/workplans/ImplementationWorkplan.md +++ b/workplans/ImplementationWorkplan.md @@ -1,5 +1,27 @@ # Repository Ability Registry Implementation Workplan +## MVP Closure + +Status: closed as MVP complete on 2026-04-26. + +The v0.1 implementation now covers the core product loop: + +```text +Register repository +Analyze repository +Generate source-linked candidate map +Review and approve candidates +Publish approved profile +Search, inspect, compare, gap-check, and export registry entries +``` + +The full test suite passed at closure with `63 passed`. + +Remaining work is no longer considered part of this MVP workplan. Production +hardening items have moved to `workplans/ProductionHardeningWorkplan.md`, +including first-class analysis-run diffs, semantic/vector search, broader +fixture coverage, and richer UI surfaces for discovery workflows. + ## 1. Documentation Review Summary The wiki defines a coherent v0.1 product: a registry that turns Git repositories into reviewable, source-linked maps of: diff --git a/workplans/ProductionHardeningWorkplan.md b/workplans/ProductionHardeningWorkplan.md new file mode 100644 index 0000000..f80333d --- /dev/null +++ b/workplans/ProductionHardeningWorkplan.md @@ -0,0 +1,185 @@ +# Repository Ability Registry Production Hardening Workplan + +Status: open +Created: 2026-04-26 + +This workplan starts after the v0.1 MVP closure. The MVP proves the core loop: + +```text +Register -> Analyze -> Review -> Approve -> Search/Inspect +``` + +Production hardening should improve trust, search quality, update safety, and +operational readiness without weakening the core rule: + +```text +observed facts are deterministic +interpreted claims are reviewable +approved registry truth is explicit +``` + +## 1. Priorities + +### P0: Update Safety and Change Review + +Goal: make repeated analysis after repository changes first-class. + +Current state: + +- A repository can be analyzed repeatedly. +- Each run records a snapshot, observed facts, chunks, and candidates. +- Existing approved profiles are not corrupted by later runs. +- There is no explicit analysis-run diff or change-review workflow. + +Deliverables: + +- Analysis-run diff model for facts, chunks, candidates, and approved entries. +- API endpoint to compare two analysis runs for a repository. +- Review view for changed, added, removed, or weakened claims. +- Review decisions that record change acceptance/rejection. +- Tests proving approved profiles remain stable until changes are approved. + +Candidate endpoints: + +```text +GET /repos/{id}/analysis-runs/{base_run_id}/diff/{target_run_id} +POST /repos/{id}/analysis-runs/{target_run_id}/changes/approve +``` + +Acceptance criteria: + +- A user can see what changed between two analysis runs. +- New claims are not published automatically. +- Removed or weakened evidence is visible before approval. +- Review decisions preserve the reason for accepting or rejecting changes. + +### P1: Search Quality and Semantic Retrieval + +Goal: improve discovery beyond simple text matching while keeping results +explainable. + +Current state: + +- Text search covers repositories, abilities, capabilities, features, and evidence. +- Filters exist for status, language, framework, ability, and capability. +- Result explanations include matched field and context. +- Semantic/vector search is not implemented. + +Deliverables: + +- Embedding abstraction for approved registry entries and content chunks. +- Local/offline fake embedding provider for tests. +- Optional pgvector/PostgreSQL backend path, without breaking SQLite dev mode. +- Hybrid ranking that combines text match, filters, confidence, and vector score. +- Search response fields that explain text and semantic match reasons. + +Acceptance criteria: + +- Existing text search behavior remains stable. +- Semantic search can be enabled optionally. +- Search results remain source-linked and explainable. +- Tests cover ranking, filters, and fallback when embeddings are unavailable. + +### P1: Discovery UI + +Goal: make comparison, gap analysis, and export usable from the curator UI. + +Current state: + +- API endpoints exist for repository comparison, capability-gap reports, and YAML export. +- There are no dedicated UI workflows for these discovery helpers. + +Deliverables: + +- Repository comparison screen. +- Capability-gap input and report screen. +- Export action from repository profile. +- Clear empty states for repositories without approved profiles. + +Acceptance criteria: + +- A user can compare at least two approved repositories from the UI. +- A user can enter desired capabilities and inspect missing/weak/duplicate results. +- A user can export a registry entry without using raw API calls. + +### P1: Fixture Breadth and Regression Confidence + +Goal: broaden real-world coverage across repository styles. + +Current state: + +- Tests cover manual registry, FastAPI-like routes, docs/tests/examples, UI loops, + LLM fallback, and source-linked approval. +- Fixture helper coverage exists for README-only, Python CLI, and misleading-docs + repositories, but not every fixture style has full e2e coverage. + +Deliverables: + +- E2E tests for README-only repositories. +- E2E tests for Python CLI repositories. +- E2E tests for JavaScript/TypeScript packages. +- E2E tests for repositories with weak or misleading documentation. +- Negative tests for unsupported or empty repositories. + +Acceptance criteria: + +- Candidate extraction stays conservative when docs are weak. +- CLI and frontend/package repositories produce useful facts and candidates. +- Misleading docs do not become approved truth without review. + +### P2: Operational Readiness + +Goal: make the service easier to run and diagnose outside local development. + +Deliverables: + +- Structured logging around ingestion, analysis, LLM extraction, and review actions. +- Configuration documentation for database, checkout root, and LLM provider settings. +- Basic metrics or health details for database and checkout root reachability. +- Backup/restore guidance for SQLite MVP deployments. +- Migration strategy notes for a future PostgreSQL deployment. + +Acceptance criteria: + +- Operators can diagnose failed analyses from logs and API state. +- Configuration is documented in one place. +- Database migration and backup expectations are clear. + +### P2: API Contract Stability + +Goal: make agent/tooling integration safer as the API grows. + +Deliverables: + +- Versioned API path or explicit compatibility policy. +- Golden OpenAPI snapshot test or schema-diff check. +- More response examples for discovery and change-review endpoints. +- Error response schema for common 400/404 cases. + +Acceptance criteria: + +- Breaking API changes are deliberate and visible in tests. +- Agent-facing endpoints have stable request/response models. + +## 2. First Implementation Sequence + +Recommended next sequence: + +1. Add analysis-run diff data structures and a read-only diff endpoint. +2. Add e2e tests for rerun diff behavior with added/removed routes and evidence. +3. Add UI display for analysis-run diffs. +4. Add approval workflow for selected changes. +5. Broaden fixture e2e coverage for README-only, CLI, JS/TS, and weak-doc repos. +6. Add discovery UI for compare, gaps, and export. +7. Prototype optional semantic search behind a feature/config boundary. + +## 3. Definition of Done + +This hardening plan can be closed when: + +- Re-analysis changes are explicit, reviewable, and tested end to end. +- Search supports an optional semantic mode while preserving explainability. +- Discovery workflows are available in both API and UI. +- Fixture coverage represents the major repository shapes in the use case catalog. +- API contract changes are guarded by tests. +- Operational docs cover running, configuring, diagnosing, and backing up the service.