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>

tools/README.md

@@ -147,7 +147,7 @@ local index YAML. `--discover` drafts capabilities via llm-connect (optional).
 Refresh registry metadata from repo drift signals.
 
 ```bash
-reuse-surface update --capability capability.registry.register --dry-run
+reuse-surface update --capability capability.registry.register
 reuse-surface update --all --from-git-since HEAD~5 --apply
 reuse-surface update --capability capability.registry.register --suggest-maturity
 ```
@@ -155,6 +155,30 @@ reuse-surface update --capability capability.registry.register --suggest-maturit
 Deterministic patches (`vector_drift`, new `tests/` citations) apply with
 `--apply`. LLM suggestions use `--suggest-maturity` and remain review-only.
 
+### maintain
+
+Interactive or automated registry maintenance (REUSE-WP-0016). Preferred entry
+point for sibling repo operators.
+
+```bash
+export LLM_CONNECT_URL=http://127.0.0.1:8088   # optional
+reuse-surface maintain --all --from-git-since origin/main
+reuse-surface maintain --capability capability.registry.register
+reuse-surface maintain --all --auto --no-llm
+reuse-surface maintain --all --auto --from-git-since HEAD~3
+reuse-surface maintain --publish --raw-url https://.../capabilities.yaml --all --auto --no-llm
+```
+
+| Mode | Flags | Behavior |
+|---|---|---|
+| Interactive (TTY) | (default) | Prompt per patch: apply / skip / edit / quit |
+| Full automation | `--auto` or `--yes` | Safe deterministic + gated LLM patches |
+| Deterministic only | `--auto --no-llm` | No llm-connect required |
+| Publish chain | `--publish --raw-url` | maintain → validate → publish-check |
+
+Templates: `templates/Makefile.registry.fragment`, `templates/git-hook.pre-commit.registry`.
+Install hook: `reuse-surface establish --scaffold --hook`.
+
 ### report cohorts
 
 Export capability cohorts for planning or implementation reuse decisions.
@@ -196,6 +220,7 @@ Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).
 | Verify index publish URL | `reuse-surface establish --publish-check` |
 | Draft capabilities (LLM) | `reuse-surface establish --discover` |
 | Refresh entry metadata | `reuse-surface update` |
+| Interactive registry maintain | `reuse-surface maintain` |
 | Planning cohort export | `reuse-surface report cohorts` |
 | Relation graph | `reuse-surface graph` |