reuse-surface/workplans/REUSE-WP-0016-interactive-registry-maintain.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
REUSE-WP-0016	workplan	Interactive registry maintain with llm-connect automation	helix_forge	reuse-surface	finished	codex	helix-forge	2026-06-16	2026-06-17	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

# 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)

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

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

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

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

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

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

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

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

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

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

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

• reuse-surface maintain in TTY walks through suggestions with apply/skip/edit
• maintain --auto --no-llm applies deterministic patches and validates atomically
• LLM patches apply only with schema validation + evidence gates
• maintain --publish --raw-url reports federation publish pass/fail
• Non-TTY without --auto/--yes fails with clear message (no silent writes)
• validate defaults to cwd when local registry/ index exists
• 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):

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.