WP-0016 finished: interactive registry maintain with llm-connect automation

Closes the registry maintenance loop from inside each domain repo: interactive prompting for judgment calls, full automation for safe and high-confidence changes, both backed by the llm-connect HTTP bridge. - New modules: maintain.py, maintain_llm.py, patches.py, interactive.py - Schema: schemas/registry-patch.schema.json - CLI: reuse-surface maintain; establish --scaffold --hook - Sibling templates: Makefile fragment, pre-commit hook - Deterministic signal collectors extended; validate cwd auto-detect - Docs, gap priority 28, SCOPE update - Tests: test_maintain.py, test_interactive.py (59 pytest total) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-18 04:00:39 +02:00
parent 1afa7e5ee5
commit b24ec507aa
22 changed files with 3604 additions and 39 deletions
--- a/workplans/REUSE-WP-0016-interactive-registry-maintain.md
+++ b/workplans/REUSE-WP-0016-interactive-registry-maintain.md
@@ -0,0 +1,377 @@
+---
+id: REUSE-WP-0016
+type: workplan
+title: "Interactive registry maintain with llm-connect automation"
+domain: helix_forge
+repo: reuse-surface
+status: finished
+owner: codex
+topic_slug: helix-forge
+created: "2026-06-16"
+updated: "2026-06-17"
+state_hub_workstream_id: "2a7565a4-2627-44ca-a856-6c3f18576f92"
+---
+
+# Interactive registry maintain with llm-connect automation
+
+Follow-up to **REUSE-WP-0013** (`establish`, `update`, `stats`). Workstation
+rollout (**REUSE-WP-0014**) gave every sibling repo a registry scaffold; operators
+still maintain entries manually or run `reuse-surface update` as a **non-interactive
+report**. LLM maturity hints (`--suggest-maturity`) dump JSON for human review
+with no apply path.
+
+This workplan closes the **registry maintenance loop** from inside each domain
+repo: interactive prompting for judgment calls, full automation for safe and
+high-confidence changes, both backed by the existing **llm-connect** HTTP bridge.
+
+**Baseline vector:** `D5 / A4 / C5 / R3`  
+**Target vector:** `D5 / A4 / C5–C6 / R3` (tooling depth; reliability unchanged
+until consumer telemetry program)
+
+## Problem statement
+
+| Pain | Today (WP-0013) | Target |
+|---|---|---|
+| Update registry after code changes | `update` prints suggestions; user must remember `--apply` | Guided session with per-change prompts |
+| Maturity / evidence refresh | `--suggest-maturity` → JSON only | Structured LLM patches with review or auto-apply |
+| Publish hygiene | Manual validate → commit → publish-check | `maintain` chains update → validate → optional publish-check |
+| Agent vs human UX | Same stdout for both | TTY prompts for humans; JSON/event stream for agents |
+| Sibling repo friction | `validate` defaults to install root | Auto-detect `registry/` in cwd |
+
+## Design principles
+
+1. **Deterministic first** — vector drift, missing index rows, and cited artifact
+   paths apply without LLM; same safe-apply list as WP-0013-T06, extended.
+2. **Interactive by default in TTY** — `reuse-surface maintain` prompts before
+   any non-deterministic write; non-TTY requires `--yes` or `--auto`.
+3. **Full automation is explicit** — `--auto` applies deterministic patches plus
+   LLM proposals that pass schema validation and evidence gates; never silent
+   promotion above configured ceilings (default: no auto D/A/C/R jumps > 1 level).
+4. **LLM optional** — deterministic-only paths work without `LLM_CONNECT_URL`;
+   LLM steps skip gracefully with a clear message.
+5. **Validate gate** — every write path ends with `reuse-surface validate --root
+   <repo>`; failed validation rolls back the session batch (atomic apply).
+6. **Evidence-bound promotions** — auto-apply for maturity changes requires
+   cited repo paths (tests, workflows, docs) present on disk; align checks with
+   `specs/CapabilityMaturityStandard.md`.
+7. **Boundary** — reuse-surface does not host models; llm-connect owns routing
+   and credentials (`POST {LLM_CONNECT_URL}/execute`).
+
+## Proposed CLI surface
+
+```bash
+# Interactive maintain (default in TTY)
+cd ~/state-hub
+export LLM_CONNECT_URL=http://127.0.0.1:8088   # optional
+reuse-surface maintain
+reuse-surface maintain --from-git-since origin/main
+reuse-surface maintain --capability capability.statehub.workstream-coordinate
+
+# Full automation (CI, agents, pre-commit)
+reuse-surface maintain --auto --from-git-since HEAD~1
+reuse-surface maintain --auto --no-llm          # deterministic only
+
+# Non-interactive apply-all-safe (current update behavior, preserved)
+reuse-surface update --all --from-git-since origin/main --apply
+
+# Federation publish helper (chains maintain + validate + publish-check)
+reuse-surface maintain --publish --raw-url https://gitea.../capabilities.yaml
+```
+
+### Interactive prompt flow (TTY)
+
+```text
+reuse-surface maintain
+  → collect repo signals (git diff, index drift, roster stats)
+  → deterministic suggestions (always listed first)
+  → optional LLM patch proposals per capability (llm-connect)
+  → for each pending change:
+       [a]pply  [s]kip  [e]dit in $EDITOR  [q]uit  [A]pply all safe
+  → atomic write + validate
+  → summary: files changed, remaining manual items, publish reminder
+```
+
+### Automation tiers (`--auto`)
+
+| Tier | Applies without prompt |
+|---|---|
+| `safe` | Deterministic patches (vector drift, evidence path append) |
+| `llm-metadata` | LLM `consumer_feedback`, `notes`, non-level field updates |
+| `llm-promote` | Single-step maturity bumps with on-disk evidence citations |
+
+Configure ceiling via `--auto-max-delta 1` (default) or `--auto-max-delta 0` to
+disable promotions.
+
+## Suggested execution order
+
+```text
+T01 registry-patch JSON schema + LLM prompt templates
+  → T02 expand deterministic signal collectors
+  → T03 interactive prompt module (TTY + non-TTY)
+  → T04 maintain command (orchestrator)
+  → T05 LLM patch apply path with evidence gates
+  → T06 --auto mode + atomic batch apply/rollback
+  → T07 validate cwd auto-detect; index.updated bump
+  → T08 sibling integration (Makefile template, optional hook generator)
+  → T09 docs, tests, gap-analysis priority 28
+```
+
+## Dependencies
+
+| Dependency | Owner | Notes |
+|---|---|---|
+| llm-connect | llm-connect | `LLM_CONNECT_URL`; mocked in pytest |
+| WP-0013 modules | reuse-surface | `registry_update.py`, `llm_bridge.py`, `establish.py` |
+| Maturity standard | reuse-surface | Promotion evidence rules in prompts and gates |
+| Sibling repo adoption | Domain owners | Run `maintain` in each checkout; optional CI step |
+
+---
+
+## Add Registry Patch Schema And LLM Templates
+
+```task
+id: REUSE-WP-0016-T01
+status: done
+priority: high
+state_hub_task_id: "f5daf384-ca4e-42ec-8530-bf5d46155284"
+```
+
+Define `schemas/registry-patch.schema.json` for structured update proposals
+(consumed by interactive and `--auto` paths):
+
+- `patches[]`: `{ capability_id, kind, confidence, rationale, field_path, value |
+  append, promotion_history_entry }`
+- `kinds`: `vector_sync`, `evidence_append`, `artifact_append`, `maturity_promote`,
+  `consumer_feedback`, `relation_add`, `index_row_add`
+- `evidence_citations[]`: repo-relative paths supporting each patch
+
+Add prompt builders in `reuse_surface/registry_update.py` (or
+`reuse_surface/maintain_llm.py`):
+
+- `build_maintain_prompt(repo_root, capability_id, git_since, context_files)`
+- Schema-constrained JSON via `request_json_object` + validator
+- Reuse maturity level definitions from `CapabilityMaturityStandard.md` in prompt
+  context (summary table, not full doc)
+
+Pytest: fixture repo + mocked llm-connect returning valid/invalid patches.
+
+## Expand Deterministic Signal Collectors
+
+```task
+id: REUSE-WP-0016-T02
+status: done
+priority: high
+state_hub_task_id: "55e6d943-6237-4332-9b01-2fa42aceff1f"
+```
+
+Extend `collect_deterministic_suggestions` in `registry_update.py`:
+
+| Signal | Suggested field |
+|---|---|
+| `.gitea/workflows/*.yml` changed | `evidence.tests` or `evidence.documentation` |
+| `docs/**` changed | `evidence.documentation` |
+| `pyproject.toml` / `[project.scripts]` added | `availability.current_artifacts` |
+| New `registry/capabilities/*.md` without index row | `index_row_add` patch |
+| `index.updated` stale vs last git touch on `registry/` | bump `updated` date |
+| Missing entry file for index row | `missing_entry` (blocking warning) |
+
+Keep `--apply` safe-list explicit in code (document in module docstring). Add
+regression tests in `tests/test_registry_update.py`.
+
+## Implement Interactive Prompt Module
+
+```task
+id: REUSE-WP-0016-T03
+status: done
+priority: high
+state_hub_task_id: "fe3a2e99-8c40-48a7-9d70-0e92b48146d2"
+```
+
+New module `reuse_surface/interactive.py`:
+
+- Detect TTY (`sys.stdin.isatty()`)
+- `prompt_patch(patch) -> Literal["apply","skip","edit","quit"]` with short
+  summary (kind, capability_id, rationale, field preview)
+- `prompt_batch(patches) -> list[patch]` supporting **Apply all safe** for
+  deterministic kinds only
+- Non-TTY: raise unless `assume_yes` / `auto_mode` set; emit JSON lines
+  (`{"event":"suggestion",...}`) for agent consumers
+- Optional `$EDITOR` flow: write temp YAML snippet, re-parse on save
+
+No llm-connect dependency. Pytest with stdin mocked via `io.StringIO`.
+
+## Implement maintain Command
+
+```task
+id: REUSE-WP-0016-T04
+status: done
+priority: high
+state_hub_task_id: "6e3a7b3d-1037-49ed-ad7c-341d21c333da"
+```
+
+Add `reuse-surface maintain` in `cli.py` (or alias `update --interactive` if
+prefer fewer top-level verbs — default to **`maintain`** as the user-facing
+entry point):
+
+**Flags:**
+
+| Flag | Purpose |
+|---|---|
+| `--path` | Repo root (default cwd) |
+| `--capability` / `--all` | Scope |
+| `--from-git-since` | Git ref for change detection |
+| `--llm-url` | Override `LLM_CONNECT_URL` |
+| `--no-llm` | Skip LLM phase |
+| `--publish` | Run `establish --publish-check` after successful validate |
+| `--raw-url` | Required when `--publish` |
+| `--format json` | Machine-readable session result |
+
+**Flow:**
+
+1. Run T02 collectors
+2. If LLM enabled: run T01 prompts per capability in scope
+3. Merge deterministic + LLM into ordered patch list (deterministic first)
+4. T03 interactive selection (unless `--auto` — T06)
+5. T05 apply + T06 atomic validate
+
+Preserve existing `update` command unchanged for scripting backward compatibility.
+
+## LLM Patch Apply Path With Evidence Gates
+
+```task
+id: REUSE-WP-0016-T05
+status: done
+priority: medium
+state_hub_task_id: "f0baa772-b7f0-4143-9fd9-9c96db17f532"
+```
+
+Implement `apply_patches(repo_root, patches) -> list[str]`:
+
+- Reuse `apply_deterministic_suggestions` for overlapping kinds
+- New writers: `promotion_history` append, `maturity.*.current` with vector
+  sync to index, `consumer_feedback` append, `relations.*` append (optional v1)
+- **Evidence gate:** for `maturity_promote`, require every
+  `evidence_citations` path to exist under `repo_root`; reject patch if not
+- **Level gate:** refuse promotion if delta > `--auto-max-delta` unless
+  interactive user confirms
+- Bump `registry/indexes/capabilities.yaml` `updated` field on any write
+
+Pytest: promote with/without evidence files; vector/index consistency after apply.
+
+## Implement --auto Mode And Atomic Batch
+
+```task
+id: REUSE-WP-0016-T06
+status: done
+priority: medium
+state_hub_task_id: "bd8f6243-24a3-44f8-9824-4cc2518ad8d9"
+```
+
+`maintain --auto`:
+
+- Apply all `safe` deterministic patches
+- Apply LLM patches with `confidence >= --auto-confidence` (default `high`) and
+  passing evidence gates
+- `--auto-max-delta` (default `1`) caps promotion steps per dimension per session
+- `--yes` on non-TTY equivalent to `--auto` with default thresholds
+
+**Atomic batch:** write all entry/index changes to temp files under
+`.reuse-surface-session/`; on validate success, rename into place; on failure,
+discard and print validator errors.
+
+Exit codes: `0` ok, `1` validation/schema failure, `2` partial skip (no writes).
+
+## Validate Cwd Auto-Detect And Publish Helper
+
+```task
+id: REUSE-WP-0016-T07
+status: done
+priority: low
+state_hub_task_id: "a61c0843-f44b-4e75-9043-7d042087e015"
+```
+
+- When `--root` / `--path` omitted and `./registry/indexes/capabilities.yaml`
+  exists, default repo root to cwd (validate, update, maintain, stats)
+- `maintain --publish --raw-url` chains: maintain session → validate →
+  `establish.publish_check` → print pass/fail markdown
+- Document raw URL convention in session summary when `REUSE_SURFACE_RAW_URL` set
+
+## Sibling Integration Templates
+
+```task
+id: REUSE-WP-0016-T08
+status: done
+priority: low
+state_hub_task_id: "ec2d58a3-c797-464b-9fb3-464f71360c9c"
+```
+
+Ship copy-paste artifacts (not installed into sibling repos automatically):
+
+- `templates/Makefile.registry.fragment` — `registry-maintain`, `registry-check`
+- `templates/git-hook.pre-commit.registry` — `maintain --auto --no-llm` when
+  `registry/` changed
+- `establish --scaffold` append: optional `--hook` writes `.git/hooks/pre-commit`
+  (refuse overwrite unless `--force`)
+
+Dogfood: run against `state-hub` checkout when available.
+
+## Documentation, Tests, And Gap Note
+
+```task
+id: REUSE-WP-0016-T09
+status: done
+priority: low
+state_hub_task_id: "85f8f549-7df9-493c-b43b-f1b67af3ee6c"
+```
+
+- `tools/README.md` — `maintain` command reference; interactive vs `--auto`
+- `docs/RegistryFederation.md` — link maintain + publish to sibling onboarding
+- `registry/README.md` — operator checklist after `maintain` session
+- `docs/IntentScopeGapAnalysis.md` — add priority **28** (registry maintenance
+  automation); mark open
+- `SCOPE.md` — extend "What Is Possible Now" when T04 ships
+- CI: `maintain --auto --no-llm` on reuse-surface self-registry (informational
+  or gated); no live llm-connect in CI
+- Pytest count increase; `reuse-surface validate` unchanged for default path
+
+---
+
+## Acceptance
+
+- [x] `reuse-surface maintain` in TTY walks through suggestions with apply/skip/edit
+- [x] `maintain --auto --no-llm` applies deterministic patches and validates atomically
+- [x] LLM patches apply only with schema validation + evidence gates
+- [x] `maintain --publish --raw-url` reports federation publish pass/fail
+- [x] Non-TTY without `--auto`/`--yes` fails with clear message (no silent writes)
+- [x] `validate` defaults to cwd when local `registry/` index exists
+- [x] All new behavior documented; gap priority 28 recorded
+
+## Completion notes (2026-06-17)
+
+- Modules: `maintain.py`, `maintain_llm.py`, `patches.py`, `interactive.py`
+- Schema: `schemas/registry-patch.schema.json`
+- Templates: `templates/Makefile.registry.fragment`, `templates/git-hook.pre-commit.registry`
+- CLI: `reuse-surface maintain`; `establish --scaffold --hook`
+- Tests: `tests/test_maintain.py`, `tests/test_interactive.py` (59 pytest total)
+
+## Out of scope
+
+- Hub cache invalidation webhooks (gap priority from §3.1 — separate workplan)
+- Auto `hub register` (still operator step with token)
+- Embedding / ML overlap detection (keep `overlaps` heuristic)
+- llm-connect hosting or provider configuration inside reuse-surface
+- Fully unattended maturity promotion without evidence citations
+
+## Dogfood target
+
+From `~/state-hub` (or any roster repo with `publish_check: pass`):
+
+```bash
+export LLM_CONNECT_URL=http://127.0.0.1:8088
+reuse-surface maintain --from-git-since origin/main
+reuse-surface maintain --auto --from-git-since HEAD~3
+reuse-surface maintain --publish \
+  --raw-url https://gitea.coulomb.social/coulomb/state-hub/raw/main/registry/indexes/capabilities.yaml
+```
+
+Success: registry files updated, `validate --root .` passes, publish-check 200.