Archive closed workplans with completion-date prefixes
Moves the remaining finished workplans into workplans/archived/. Prefixes use each workplan's own completion date per the convention, not the date the archive sweep ran. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Assistant: claude-code Assistant-Model: opus Assistant-Process: 4609@bnt-lap001 Assistant-Session: 085df492-f02a-4fe6-acad-2aa52789fe1b
This commit is contained in:
parent
152e88a38e
commit
1df9c19c96
15 changed files with 2 additions and 2 deletions
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
id: REUSE-WP-0001
|
||||
type: workplan
|
||||
title: "Bootstrap State Hub integration"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-14"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "293ef16d-c15b-41cc-9258-4a3a233f4bf2"
|
||||
---
|
||||
|
||||
# Bootstrap State Hub integration
|
||||
|
||||
Capability registry for planning and implementation reuse based on discovery and delivery maturity.
|
||||
|
||||
## Review Generated Integration Files
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0001-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "18c811c8-f9f6-4452-b3f0-b713c91918a4"
|
||||
```
|
||||
|
||||
Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
|
||||
Replace generated placeholders with repo-specific facts where needed.
|
||||
|
||||
Completed by reviewing the generated integration files, preserving
|
||||
`.custodian-brief.md` as generated output, and refining `SCOPE.md` to the
|
||||
actual registry-first repository boundary. `INTENT.md` already contained
|
||||
repo-specific intent and maturity model content; no placeholder replacement was
|
||||
needed there.
|
||||
|
||||
## Verify Local Developer Workflow
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0001-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "0877cf67-6abe-48c3-b76c-df552620d678"
|
||||
```
|
||||
|
||||
Identify the repo's install, test, lint, build, and run commands. Add or refine
|
||||
those commands in the agent instructions so future coding sessions can verify
|
||||
changes confidently.
|
||||
|
||||
Completed by adding the local developer workflow to `AGENTS.md`. The repository
|
||||
is documentation-only: no install, build, runtime service, package manifest, or
|
||||
configured test runner exists. Current verification is `rg --files`, `git diff
|
||||
--check`, and State Hub ADR-001 consistency sync after workplan changes.
|
||||
|
||||
## Seed First Real Workplan
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0001-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "f480aa11-f7e1-45fe-bf0b-4a3c164eb85b"
|
||||
```
|
||||
|
||||
Create the first implementation workplan for the repository's most important
|
||||
next change. After workplan file updates, run from `~/state-hub`:
|
||||
|
||||
```bash
|
||||
make fix-consistency REPO=reuse-surface
|
||||
```
|
||||
|
||||
Completed by `REUSE-WP-0002`, which seeds the MVP registry foundation:
|
||||
schema, templates, sample capabilities, index, validation guidance, and agent
|
||||
registry instructions.
|
||||
|
|
@ -0,0 +1,129 @@
|
|||
---
|
||||
id: REUSE-WP-0002
|
||||
type: workplan
|
||||
title: "MVP registry foundation"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "32e0f249-65dd-4401-831c-736b229c5865"
|
||||
---
|
||||
|
||||
# MVP registry foundation
|
||||
|
||||
This workplan implements the first registry artifacts required by
|
||||
`specs/ProductRequirementsDocument.md` section 15 (MVP Requirements) and section
|
||||
16 (MVP Acceptance Criteria). The repository already has `INTENT.md`, the
|
||||
product requirements, use case catalog, and capability maturity standard under
|
||||
`specs/`. The remaining MVP work is to make the registry usable by humans and
|
||||
agents.
|
||||
|
||||
## Design decisions
|
||||
|
||||
- **Canonical format:** Markdown capability entries with YAML front matter under
|
||||
`registry/capabilities/`. The index at `registry/indexes/capabilities.yaml`
|
||||
is the machine-readable discovery surface for agents.
|
||||
- **Schema alignment:** Follow `INTENT.md` and `specs/CapabilityMaturityStandard.md`
|
||||
section 10. Internal maturity uses `maturity.discovery` and
|
||||
`maturity.availability`. Consumer evidence uses `external_evidence.completeness`
|
||||
and `external_evidence.reliability` — not nested under `maturity`.
|
||||
- **Sample capabilities:** Seed three helix_forge entries illustrating different
|
||||
vectors: registry meta (`capability.registry.register`), implementation-ready
|
||||
feature control (`capability.feature-control.evaluate`), and research-heavy
|
||||
identity canon (`capability.identity.vocabulary-canonicalize`).
|
||||
- **Validation:** Document manual validation rules in `registry/README.md` and
|
||||
`tools/README.md` for MVP. Automated CLI validation is out of scope here.
|
||||
|
||||
## Define Capability Schema
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "431edb19-2166-4715-bb3d-4428149aa2bc"
|
||||
```
|
||||
|
||||
Create `schemas/capability.schema.yaml` as a JSON Schema draft (YAML syntax)
|
||||
for registry entry front matter. Cover stable IDs, `maturity` (discovery and
|
||||
availability only), `external_evidence`, discovery scope fields, availability
|
||||
artifacts, relations, evidence references, and consumer guidance. Enum values
|
||||
must match `specs/CapabilityMaturityStandard.md`.
|
||||
|
||||
## Create Capability Entry Template
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a4763385-954f-4141-9f16-a85e96704f46"
|
||||
```
|
||||
|
||||
Create `templates/capability-entry.template.md` as the Markdown-first authoring
|
||||
template. Include YAML front matter with required fields, commented guidance
|
||||
for assessors, and placeholders for evidence, relations, and consumer guidance.
|
||||
The template must be consistent with the schema from T01.
|
||||
|
||||
## Seed Sample Registry Entries
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "96078fbb-f2cc-4d4f-ac7c-6a1744c33e0b"
|
||||
```
|
||||
|
||||
Create three sample entries under `registry/capabilities/`:
|
||||
|
||||
- `capability.registry.register.md` — D3/A0, meta registry capability
|
||||
- `capability.feature-control.evaluate.md` — D5/A4, implementation-ready example
|
||||
- `capability.identity.vocabulary-canonicalize.md` — D4/A0, research/planning example
|
||||
|
||||
Each entry must conform to the schema and illustrate distinct maturity vectors.
|
||||
Include relations between entries where appropriate.
|
||||
|
||||
## Build Capability Index
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "19e0d200-fe1f-4273-9f47-abdf4a67b517"
|
||||
```
|
||||
|
||||
Create `registry/indexes/capabilities.yaml` as a manually maintained index.
|
||||
Include IDs, names, summaries, compact maturity vectors, domain, and paths to
|
||||
entry files. The index must list all three sample capabilities from T03.
|
||||
|
||||
## Add Validation And Search Guidance
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "bf0dd838-9c13-480e-93b9-47d4ae5edc82"
|
||||
```
|
||||
|
||||
Create `registry/README.md` and `tools/README.md` documenting:
|
||||
|
||||
- Required and recommended fields
|
||||
- Manual validation checklist (schema enums, relation ID format, broken references)
|
||||
- Search/filter guidance for UC-RS-004, UC-RS-005, UC-RS-006, and UC-RS-015
|
||||
- How to add a D0/A0/C0/R0 entry with minimal friction (MVP acceptance criteria)
|
||||
|
||||
## Extend Agent Registry Instructions
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0002-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "a78fc037-b432-4af3-a068-132690344bb2"
|
||||
```
|
||||
|
||||
Add a **Capability Registry** section to `AGENTS.md` explaining how coding
|
||||
agents should orient to the registry, query the index, add or promote entries
|
||||
using the template, validate manually, and avoid duplicating existing
|
||||
capabilities. Reference paths created in earlier tasks and map guidance to MVP
|
||||
acceptance criteria in `specs/ProductRequirementsDocument.md` section 16.
|
||||
|
|
@ -0,0 +1,189 @@
|
|||
---
|
||||
id: REUSE-WP-0003
|
||||
type: workplan
|
||||
title: "Close intent-scope gaps: docs, tooling, and registry growth"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "302ea071-68ab-43e4-97ce-8cf1fb805aaa"
|
||||
---
|
||||
|
||||
# Close intent-scope gaps: docs, tooling, and registry growth
|
||||
|
||||
Follow-up to `docs/IntentScopeGapAnalysis.md` section 8 (Priority Gap Closure
|
||||
Order). `REUSE-WP-0002` delivered the MVP registry foundation at A0. This
|
||||
workplan closes the highest-priority gaps between `INTENT.md` and `SCOPE.md` by
|
||||
aligning documentation, raising availability toward A3, and strengthening
|
||||
registry coverage and evidence.
|
||||
|
||||
**Target vector after completion:** `D5 / A3 / C4 / R2` for reuse-surface as a
|
||||
registry product.
|
||||
|
||||
## Suggested execution order
|
||||
|
||||
```text
|
||||
T01, T04 (documentation — parallel)
|
||||
→ T05 (schema: promotion history)
|
||||
→ T02 (validate CLI)
|
||||
→ T06, T07 (query + export — parallel after T02)
|
||||
→ T03 (expand registry entries)
|
||||
→ T08 (dogfood evidence + gap analysis refresh)
|
||||
```
|
||||
|
||||
## Align INTENT With Delivered Layout
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "51c58b43-7b0f-4737-bf48-51efd6f50ead"
|
||||
```
|
||||
|
||||
Close gap analysis item 1. Update `INTENT.md`:
|
||||
|
||||
- Replace the stale "Initial Repository Role" tree with the layout in `SCOPE.md`
|
||||
- Fix the registry entry example to use `external_evidence.*.level` (not
|
||||
`current`) to match `schemas/capability.schema.yaml`
|
||||
- Add a short pointer to `docs/IntentScopeGapAnalysis.md` and
|
||||
`docs/CapabilityRegistryConcept.md` (once T04 lands)
|
||||
- Keep product intent unchanged; only correct delivery drift
|
||||
|
||||
## Add Automated Registry Validation
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "570a036a-d310-4cb7-9812-594a7f4de904"
|
||||
```
|
||||
|
||||
Close gap analysis item 2 and UC-RS-023. Add a minimal Python CLI under
|
||||
`tools/` that validates capability entry front matter against
|
||||
`schemas/capability.schema.yaml`. Requirements:
|
||||
|
||||
- Validate one file or all files under `registry/capabilities/`
|
||||
- Check required fields, enum values, and capability ID format
|
||||
- Warn on index drift (entry exists but missing from
|
||||
`registry/indexes/capabilities.yaml`, or vice versa)
|
||||
- Document usage in `tools/README.md` and `AGENTS.md`
|
||||
- Add `pyproject.toml` with minimal dependencies if needed for packaging
|
||||
|
||||
## Expand helix_forge Registry Coverage
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "2c59041d-6c27-4610-afc0-c83873e18b9b"
|
||||
```
|
||||
|
||||
Close gap analysis item 3. Register at least three additional helix_forge
|
||||
capabilities beyond the MVP samples. Candidates to evaluate:
|
||||
|
||||
- `state-hub` — workstream/task coordination
|
||||
- `feature-control` siblings (rollout, visibility) if distinct from evaluate
|
||||
- `identity-canon` — subject resolution or other canon primitives
|
||||
- Adjacent helix_forge repos with clear bounded capabilities
|
||||
|
||||
Each new entry must pass the validator from T02, appear in the index, and
|
||||
illustrate a different planning or consumption profile than existing entries.
|
||||
|
||||
## Add Capability Registry Concept Guide
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "70077cfe-f5ca-4a61-97b2-81829a6b4565"
|
||||
```
|
||||
|
||||
Close gap analysis item 4. Create `docs/CapabilityRegistryConcept.md` distilled
|
||||
from `INTENT.md` for human onboarding. Cover:
|
||||
|
||||
- Registry-first boundary and reuse-over-inventory principle
|
||||
- Four maturity dimensions and when to use each
|
||||
- Planning reuse vs implementation reuse
|
||||
- How entries, index, schema, and template fit together
|
||||
- What remains manual vs what tooling provides (cross-link `SCOPE.md`)
|
||||
|
||||
Do not duplicate the full maturity standard — link to `specs/` instead.
|
||||
|
||||
## Add Promotion History Support
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "22a3db94-21c7-44d6-8d77-5235f9f10537"
|
||||
```
|
||||
|
||||
Close gap analysis item 5. Extend the registry model to track maturity changes
|
||||
over time (UC-RS-022). Requirements:
|
||||
|
||||
- Add optional `promotion_history` to `schemas/capability.schema.yaml`
|
||||
- Update `templates/capability-entry.template.md` with an example history block
|
||||
- Document when and how to append history in `registry/README.md`
|
||||
- Backfill at least one sample entry (e.g. `capability.registry.register`) with
|
||||
a plausible promotion record
|
||||
- Extend the validator from T02 to check history entry shape when present
|
||||
|
||||
## Add CLI Query And Filter
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "1958f555-a3a6-46a8-84cd-c570d6706cb3"
|
||||
```
|
||||
|
||||
Close gap analysis item 6 and UC-RS-004/005. Extend the `tools/` CLI with a
|
||||
`query` command that reads `registry/indexes/capabilities.yaml` and filters by:
|
||||
|
||||
- Discovery minimum (e.g. `--discovery-min D4`)
|
||||
- Availability minimum (e.g. `--availability-min A3`)
|
||||
- Tags, domain, consumption mode, and summary keyword
|
||||
|
||||
Output a concise candidate list with vectors and entry paths. Document example
|
||||
queries in `registry/README.md` and `AGENTS.md`.
|
||||
|
||||
## Add Registry Export Bundle
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6e595b66-ce73-4867-af79-5d0a43a0056d"
|
||||
```
|
||||
|
||||
Close gap analysis item 7 and UC-RS-019. Extend the `tools/` CLI with an
|
||||
`export` command that produces a machine-readable bundle (YAML or JSON) combining
|
||||
the index and parsed front matter from all capability entries. Requirements:
|
||||
|
||||
- Stable IDs and maturity fields in export output
|
||||
- Document export format in `tools/README.md`
|
||||
- Export must pass a smoke check: all index entries resolve to readable front matter
|
||||
|
||||
## Dogfood Reliability Evidence And Refresh Gap Analysis
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0003-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "d876f449-68e3-4785-ba3c-7d91c4abbafc"
|
||||
```
|
||||
|
||||
Close gap analysis item 8. Record consumer-relevant friction from building T02–T07
|
||||
as reliability evidence for `capability.registry.register` (and optionally a
|
||||
meta-entry for reuse-surface itself). Requirements:
|
||||
|
||||
- Update `external_evidence.reliability` with honest R1–R3 assessment and known
|
||||
risks (manual index maintenance, validator gaps, etc.)
|
||||
- Refresh `docs/IntentScopeGapAnalysis.md`: close resolved gaps, update the
|
||||
self-assessment vector, add a change-log entry referencing REUSE-WP-0003
|
||||
- Update `SCOPE.md` "What Is Possible Now / Not Possible Yet" to reflect new CLI
|
||||
capabilities
|
||||
- Promote `capability.registry.register` availability to A3 if CLI ships
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
id: REUSE-WP-0004
|
||||
type: workplan
|
||||
title: "Registry hardening: CI, overlap detection, and catalog"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "8e792e1e-8f28-4f7f-8c53-2b04ef078e61"
|
||||
---
|
||||
|
||||
# Registry hardening: CI, overlap detection, and catalog
|
||||
|
||||
Follow-up to `docs/IntentScopeGapAnalysis.md` section 8 next recommended work
|
||||
(priorities 9–11). Raise registry quality through automated CI validation, overlap
|
||||
reporting (UC-RS-015), and a generated human-readable catalog (UC-RS-018).
|
||||
|
||||
## Add CI Validation Workflow
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0004-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "750e7fd6-f9b3-4945-a2f5-9a405ca3af6b"
|
||||
```
|
||||
|
||||
Add `.gitea/workflows/ci.yml` that runs on push and pull requests to `main`.
|
||||
Install the package and run `reuse-surface validate`. Document the workflow in
|
||||
`AGENTS.md`.
|
||||
|
||||
## Add Overlap Detection Command
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0004-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8c5febb0-758d-4983-958c-093e5c481f2c"
|
||||
```
|
||||
|
||||
Add `reuse-surface overlaps` that flags potential duplicate or overlapping
|
||||
capabilities using summary/tags/includes similarity and relation signals.
|
||||
Document usage in `registry/README.md` and `tools/README.md`.
|
||||
|
||||
## Add Catalog Generation Command
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0004-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "2cae7d58-b943-4ef6-b404-2ad126450e0a"
|
||||
```
|
||||
|
||||
Add `reuse-surface catalog` that generates `docs/CapabilityCatalog.md` and
|
||||
`docs/catalog/index.html` from the index and entry front matter. Group by domain
|
||||
and show maturity vectors.
|
||||
|
||||
## Refresh Docs And Gap Analysis
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0004-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "a9660e01-81af-45fb-8d51-4f16fbaa94c2"
|
||||
```
|
||||
|
||||
Update `SCOPE.md`, `tools/README.md`, and `docs/IntentScopeGapAnalysis.md` to
|
||||
reflect CI, overlaps, and catalog capabilities. Close gap analysis priorities
|
||||
9–11.
|
||||
116
workplans/archived/260615-REUSE-WP-0005-registry-federation.md
Normal file
116
workplans/archived/260615-REUSE-WP-0005-registry-federation.md
Normal file
|
|
@ -0,0 +1,116 @@
|
|||
---
|
||||
id: REUSE-WP-0005
|
||||
type: workplan
|
||||
title: "Registry federation and relation graphs"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "df6a3b58-2c32-4893-8771-87a822c12aa5"
|
||||
---
|
||||
|
||||
# Registry federation and relation graphs
|
||||
|
||||
Follow-up to `docs/IntentScopeGapAnalysis.md` open priorities 12 and 14.
|
||||
Extend the registry beyond a single-repo index by composing federated indexes
|
||||
from configured sources and generating relation graphs for architects (UC-RS-016).
|
||||
|
||||
## Design decisions
|
||||
|
||||
- **Federation scope (MVP):** Filesystem-local index composition only. A manifest
|
||||
lists index files from this repo and sibling helix_forge checkouts; no network
|
||||
fetch or runtime federation service.
|
||||
- **Source attribution:** Federated entries carry `source_repo` and
|
||||
`source_index` so ID collisions are visible, not silently merged.
|
||||
- **Graph output:** Mermaid diagram derived from entry `relations` fields;
|
||||
suitable for docs and PR review, not interactive visualization yet.
|
||||
- **Cycle policy:** `depends_on` cycles are reported as warnings during graph
|
||||
generation and federation compose validation.
|
||||
|
||||
## Define Federation Manifest And Schema
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0005-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9a9732ea-c546-49fe-bf61-0f3bdf94406a"
|
||||
```
|
||||
|
||||
Create `schemas/federation.schema.yaml` and
|
||||
`registry/federation/sources.yaml` describing federation sources for
|
||||
helix_forge. The manifest must support:
|
||||
|
||||
- Local primary index (`registry/indexes/capabilities.yaml`)
|
||||
- Optional sibling repo indexes via absolute or home-relative paths
|
||||
- Per-source `enabled`, `domain`, and `repo` metadata
|
||||
- Documented collision policy (`warn`, not auto-merge)
|
||||
|
||||
Include commented placeholders for `state-hub`, `feature-control`, and
|
||||
`identity-canon` indexes to federate when those repos publish them.
|
||||
|
||||
## Add Federation Compose Command
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0005-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9539c609-ac44-40a7-90bc-6f294fe085b9"
|
||||
```
|
||||
|
||||
Add `reuse-surface federation compose` that reads `registry/federation/sources.yaml`
|
||||
and writes `registry/indexes/federated.yaml`. Requirements:
|
||||
|
||||
- Merge capability rows from all enabled sources
|
||||
- Preserve `source_repo`, `source_index`, and original `path` per entry
|
||||
- Warn on duplicate IDs across sources
|
||||
- Skip missing optional external indexes with a clear warning (not a hard fail)
|
||||
- Document command in `tools/README.md` and `AGENTS.md`
|
||||
|
||||
## Add Relation Graph Command
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0005-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "4f7e85a5-c73a-49b6-a044-ba1fabc54d8a"
|
||||
```
|
||||
|
||||
Add `reuse-surface graph` that emits a Mermaid `graph LR` diagram from capability
|
||||
entry relations. Requirements:
|
||||
|
||||
- Include all relation types present in entries
|
||||
- Write `docs/graph/capability-graph.mmd` by default; support `--stdout`
|
||||
- Nodes labeled with capability ID and compact vector from the index
|
||||
- Document regeneration in `registry/README.md`
|
||||
|
||||
## Add Cycle And Broken-Reference Checks
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0005-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6f7e2913-9634-4ebb-841f-9024b35961ef"
|
||||
```
|
||||
|
||||
Extend validation or graph generation to report:
|
||||
|
||||
- `depends_on` cycles within the registered graph
|
||||
- Relation targets that reference unknown capability IDs in the composed index
|
||||
- Output as warnings via `reuse-surface graph --check` or `validate --relations`
|
||||
|
||||
## Document Federation And Refresh Gap Analysis
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0005-T05
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "8d69121b-9961-41c2-8802-d9c5b5d94c69"
|
||||
```
|
||||
|
||||
Create `docs/RegistryFederation.md` covering manifest format, compose workflow,
|
||||
collision handling, and how agents should query federated indexes. Update
|
||||
`SCOPE.md`, `docs/IntentScopeGapAnalysis.md`, and CI if federation compose
|
||||
should run in the validate pipeline.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
---
|
||||
id: REUSE-WP-0006
|
||||
type: workplan
|
||||
title: "Registry hygiene and coverage expansion"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "d3d0b3ae-dedc-48bc-a6d2-16975e10acc3"
|
||||
---
|
||||
|
||||
# Registry hygiene and coverage expansion
|
||||
|
||||
Close broken relation references, register missing adjacent capabilities, and
|
||||
expand helix_forge registry coverage so `reuse-surface graph --check` and
|
||||
`validate --relations` run clean.
|
||||
|
||||
## Register Missing Relation Targets
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0006-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "183b42ae-7773-484f-afe7-4966e26f1768"
|
||||
```
|
||||
|
||||
Register three capabilities referenced by existing relations but not yet in the
|
||||
index:
|
||||
|
||||
- `capability.registry.validate`
|
||||
- `capability.feature-control.visibility`
|
||||
- `capability.statehub.progress-log`
|
||||
|
||||
Each entry must pass validation and appear in the index.
|
||||
|
||||
## Expand helix_forge Coverage
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0006-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "3c6b4e4a-07c0-4a06-a64b-f152f8bdb35d"
|
||||
```
|
||||
|
||||
Register at least three additional helix_forge capabilities from adjacent repos:
|
||||
|
||||
- `capability.authorization.policy-evaluate` (flex-auth)
|
||||
- `capability.activity.event-coordinate` (activity-core)
|
||||
- `capability.audit.event-retain` (audit-core)
|
||||
|
||||
Illustrate distinct vectors and link relations where appropriate.
|
||||
|
||||
## Regenerate Derived Artifacts
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0006-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "417e7a0d-2bdd-43fd-8604-3d48cc1fc083"
|
||||
```
|
||||
|
||||
Run and commit outputs from `federation compose`, `graph`, `catalog`, and
|
||||
`export`. Confirm `validate --relations` reports no broken references.
|
||||
|
||||
## Update Documentation
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0006-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "9e061f46-5de8-4cf7-a7f1-b0e886391b7d"
|
||||
```
|
||||
|
||||
Update `SCOPE.md` capability inventory and `docs/IntentScopeGapAnalysis.md`
|
||||
self-assessment after coverage growth.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
id: REUSE-WP-0007
|
||||
type: workplan
|
||||
title: "Interactive capability catalog"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "1afa1322-7d60-41aa-bf7e-3ef29bb4d3a5"
|
||||
---
|
||||
|
||||
# Interactive capability catalog
|
||||
|
||||
Close gap analysis priority 13 (UC-RS-018 enhancement). Build a static,
|
||||
searchable catalog UI over exported registry data.
|
||||
|
||||
## Add Catalog Site Generator
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0007-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "84c56268-2e0b-42e6-b20e-6fbf059dcc20"
|
||||
```
|
||||
|
||||
Extend `reuse-surface catalog` (or add `catalog site`) to emit
|
||||
`docs/catalog/registry.json` alongside existing MD/HTML outputs.
|
||||
|
||||
## Build Searchable Catalog UI
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0007-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d587bc50-adb2-424a-a9d3-600a2ec5ba9b"
|
||||
```
|
||||
|
||||
Create `docs/catalog/search.html` with client-side filter by name, summary, tags,
|
||||
vector, and consumption mode. No backend required.
|
||||
|
||||
## Wire Catalog Into CI And Docs
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0007-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "eca7438c-3c2f-4027-9b40-67df5f17aca7"
|
||||
```
|
||||
|
||||
Update CI to regenerate catalog artifacts, document browsing in
|
||||
`docs/CapabilityRegistryConcept.md` and `SCOPE.md`.
|
||||
42
workplans/archived/260615-REUSE-WP-0008-graph-explorer.md
Normal file
42
workplans/archived/260615-REUSE-WP-0008-graph-explorer.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
id: REUSE-WP-0008
|
||||
type: workplan
|
||||
title: "Interactive relation graph explorer"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "63f8a2da-d179-4875-8cff-40a0fa2ca067"
|
||||
---
|
||||
|
||||
# Interactive relation graph explorer
|
||||
|
||||
Close gap analysis priority 16. Provide a browsable HTML view of
|
||||
`docs/graph/capability-graph.mmd` for architects (UC-RS-016).
|
||||
|
||||
## Add Graph Explorer Page
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0008-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "2d08de47-d3c0-484f-a945-9691da9688e4"
|
||||
```
|
||||
|
||||
Create `docs/graph/index.html` that renders the Mermaid graph in-browser with
|
||||
node labels and a legend for relation types.
|
||||
|
||||
## Integrate Graph Generation
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0008-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "ada96492-88d0-438e-8d2b-ae0fdd8abb06"
|
||||
```
|
||||
|
||||
Ensure `reuse-surface graph` documents and regenerates both `.mmd` and the
|
||||
explorer page dependency. Update `registry/README.md` and `AGENTS.md`.
|
||||
55
workplans/archived/260615-REUSE-WP-0009-cli-hardening.md
Normal file
55
workplans/archived/260615-REUSE-WP-0009-cli-hardening.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
---
|
||||
id: REUSE-WP-0009
|
||||
type: workplan
|
||||
title: "CLI hardening and test suite"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "9121d16f-879f-4db3-9df6-06f7543481d8"
|
||||
---
|
||||
|
||||
# CLI hardening and test suite
|
||||
|
||||
Raise registry tooling reliability toward R3 with automated tests and stricter
|
||||
CI gates after WP-0006 relation hygiene.
|
||||
|
||||
## Add pytest Suite
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0009-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "57d0869a-38bb-409a-b5b1-b3c73ff31a96"
|
||||
```
|
||||
|
||||
Add `tests/` covering validate, query, export, overlaps, federation compose,
|
||||
graph, and catalog commands. Add `[dev]` optional deps and document
|
||||
`.venv/bin/pytest` in `AGENTS.md`.
|
||||
|
||||
## Add Fail-On-Warnings Flags
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0009-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "d10fde06-e09b-4292-b6c8-ced5e5ef213c"
|
||||
```
|
||||
|
||||
Add `--fail-on-warnings` to `validate` and `graph --check`. Use in CI once
|
||||
WP-0006 relation hygiene is complete.
|
||||
|
||||
## Tighten CI Pipeline
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0009-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "79c0fa70-7ec1-4762-9a7c-9783f0997016"
|
||||
```
|
||||
|
||||
Update `.gitea/workflows/ci.yml` to run pytest and fail on relation warnings.
|
||||
Record reliability evidence on `capability.registry.register`.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
id: REUSE-WP-0010
|
||||
type: workplan
|
||||
title: "Network federation for remote indexes"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: codex
|
||||
topic_slug: helix-forge
|
||||
created: "2026-06-15"
|
||||
updated: "2026-06-15"
|
||||
state_hub_workstream_id: "da812165-d56e-47fa-9901-bb3747522ec4"
|
||||
---
|
||||
|
||||
# Network federation for remote indexes
|
||||
|
||||
Close gap analysis priority 15. Extend federation beyond filesystem paths to
|
||||
fetch capability indexes from HTTP URLs or git raw endpoints.
|
||||
|
||||
## Extend Federation Schema For URLs
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0010-T01
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "6f181057-e0f7-4879-9eb9-928a527a01ee"
|
||||
```
|
||||
|
||||
Extend `schemas/federation.schema.yaml` and manifest format to support `url`
|
||||
sources alongside `index` file paths, with optional auth and TTL metadata.
|
||||
|
||||
## Implement Remote Index Fetch
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0010-T02
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "a2fac7d5-9383-4a42-bd23-3e8dbc7d550b"
|
||||
```
|
||||
|
||||
Add HTTP fetch to `federation compose` with local cache under
|
||||
`registry/federation/cache/`. Clear errors when remote source unavailable.
|
||||
|
||||
## Document Federation Operations
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0010-T03
|
||||
status: done
|
||||
priority: low
|
||||
state_hub_task_id: "73996193-ecae-4fb4-84f7-fe84a5cd8898"
|
||||
```
|
||||
|
||||
Update `docs/RegistryFederation.md` with remote source examples and agent
|
||||
guidance for cross-repo discovery without local checkout.
|
||||
|
|
@ -0,0 +1,377 @@
|
|||
---
|
||||
id: REUSE-WP-0016
|
||||
type: workplan
|
||||
title: "Interactive registry maintain with llm-connect automation"
|
||||
domain: infotech
|
||||
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.
|
||||
|
|
@ -0,0 +1,468 @@
|
|||
---
|
||||
id: REUSE-WP-0020
|
||||
type: workplan
|
||||
title: "CoulombCore retirement cutover: federation sources, image, and compose resilience"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: claude
|
||||
topic_slug: helix-forge
|
||||
created: "2026-08-20"
|
||||
updated: "2026-08-21"
|
||||
state_hub_workstream_id: "415598bb-c53f-5aa3-b8d1-0aebf3ce3bf2"
|
||||
---
|
||||
|
||||
# CoulombCore retirement cutover
|
||||
|
||||
CoulombCore is switched off **2026-08-31** (operator decision, 2026-08-20).
|
||||
`gitea.coulomb.social` runs on it. Raised by `prj-state-hub-retirement`
|
||||
(SHR-WP-0002-T07) as a stale-image report; investigation found a second,
|
||||
more urgent problem underneath it.
|
||||
|
||||
**Two independent failures**, not one:
|
||||
|
||||
1. **Federation source data** — the production hub's *registrations* pointed
|
||||
50 of 61 sources at `gitea.coulomb.social`. This breaks on 08-31 with
|
||||
nobody restarting anything. It is database state, not code:
|
||||
`registry/federation/sources.yaml` at HEAD has been 61/61 Forgejo since
|
||||
`d1c1313` (RAIL-HO-WP-0006).
|
||||
2. **Deployed image** — `railiance-apps/helm/reuse-surface-values.yaml` pins
|
||||
`image.tag: "e3ae22e"`. The chart's `repository` was already migrated to
|
||||
Forgejo in `railiance-apps@04be416`, but `e3ae22e` is commit-dated
|
||||
2026-07-07 18:25 and CI only began publishing to Forgejo at 21:25 the same
|
||||
day — so a Forgejo `:e3ae22e` tag most likely never existed. Any restart,
|
||||
reschedule, or node reboot risks `ImagePullBackOff` **now**, not on 08-31.
|
||||
|
||||
Item 1 was resolved on 2026-08-20 (see T01). Doing so exposed a third issue:
|
||||
a single malformed member index takes the whole federated endpoint down.
|
||||
|
||||
**Baseline vector:** `D5 / A4 / C5 / R3` — unchanged by this workplan;
|
||||
this is operational continuity, not capability growth.
|
||||
|
||||
## Scope boundary
|
||||
|
||||
The Deployment manifest is **not in this repo**. It lives in `railiance-apps`
|
||||
(`charts/reuse-surface/`, `helm/reuse-surface-values.yaml`, RAILIANCE-WP-0007).
|
||||
This repo owns the image contents, the deploy guide, and the federation data;
|
||||
applying the manifest change requires a working `KUBECONFIG=~/.kube/config-hosteurope`,
|
||||
which is not reachable from the workstation without an ops-bridge tunnel.
|
||||
|
||||
---
|
||||
|
||||
## Repoint Production Federation Sources To Forgejo
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "4d91cda4-1a0e-5ccf-8d9b-e457ca2c11d3"
|
||||
```
|
||||
|
||||
**Completed 2026-08-20.** Updated 50 enabled hub registrations from
|
||||
`gitea.coulomb.social/<repo>/raw/main/...` to
|
||||
`forgejo.coulomb.social/<repo>/raw/branch/main/...` via
|
||||
`reuse-surface hub update --repo <r> --url <new>`.
|
||||
|
||||
Notes for the record:
|
||||
|
||||
- All 50 new URLs were pre-verified `200` before any write.
|
||||
- The canonical Forgejo raw form is `/raw/branch/main/`. `/raw/main/` answers
|
||||
`303` and works only because `urllib.request.urlopen` follows redirects —
|
||||
`registry/federation/sources.yaml` still uses the redirecting form. Harmless,
|
||||
but prefer the canonical form in new writes.
|
||||
- One registration (`inter-hub`, already `disabled`) still carries a Gitea URL.
|
||||
Its Forgejo equivalent answers `307`, so it was left alone rather than
|
||||
repointed to something unverified. It contributes nothing while disabled.
|
||||
|
||||
Verified: `GET /v1/federated` → 60 sources, all Forgejo, 62 capabilities.
|
||||
|
||||
## Harden Compose Against A Malformed Member Index
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "8dbbf790-51d2-5abb-915f-1137ab9e038e"
|
||||
```
|
||||
|
||||
T01 briefly took `/v1/federated` to HTTP 500. Root cause: `evidence-binder`'s
|
||||
live index has two capability entries with **no `id` field**, and
|
||||
`compose_federated_index` does `cap_id = item["id"]` unguarded. Its Gitea copy
|
||||
was a stale snapshot returning a non-mapping, so the entries had never been
|
||||
parsed before.
|
||||
|
||||
**One bad member index must not take down the federated endpoint.** In
|
||||
`reuse_surface/federation.py::compose_federated_index`, guard the per-source
|
||||
body so a failure degrades to a warning and the remaining sources still
|
||||
compose:
|
||||
|
||||
| Failure | Current | Wanted |
|
||||
|---|---|---|
|
||||
| `item["id"]` missing | `KeyError`, 500 | skip entry, warn, keep source |
|
||||
| `yaml.safe_load` → non-mapping | `AttributeError`, 500 | skip source, warn |
|
||||
| `yaml.safe_load` → `None` (empty file) | `AttributeError`, 500 | skip source, warn |
|
||||
| YAML parse error | `YAMLError`, 500 | skip source, warn |
|
||||
| `sorted(key=item["id"])` | `KeyError` | unreachable once entries are filtered |
|
||||
|
||||
Confirmed present at HEAD, not only in the deployed image — deploying HEAD
|
||||
would **not** have fixed this. Land T02 before T04.
|
||||
|
||||
Pytest in `tests/test_federation.py`: member index with a missing `id`, an
|
||||
empty file, a non-mapping body, and unparseable YAML — each composes the
|
||||
other sources successfully and emits a warning naming the source.
|
||||
|
||||
**Done 2026-08-20.** Extracted `_read_index_entries()`; every read failure now
|
||||
returns an empty row list plus a warning, and rows without an `id` are skipped
|
||||
individually. A failed source stays in `sources` with `count: 0` rather than
|
||||
vanishing, so operators can still see it. Six tests added. Verified against the
|
||||
real `evidence-binder` index: composes clean with two skip warnings instead of
|
||||
raising.
|
||||
|
||||
## Fix The evidence-binder Capability Index
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "9b46a7c0-cb13-5ea7-b6c4-74f3f563cfb2"
|
||||
```
|
||||
|
||||
Cross-repo, in `~/evidence-binder`. **Routed 2026-08-20**, not edited directly —
|
||||
that repo is active (last commit 2026-07-30) and has its own identity and topic.
|
||||
|
||||
The defect is larger than the missing `id`. Both rows use an entirely
|
||||
non-conforming shape — `type` / `title` / `description` / `keywords` instead of
|
||||
`id` / `name` / `summary` / `vector` / `domain` / `status` / `owner` / `path` /
|
||||
`tags` / `consumption_modes`. History shows `597b489` added the
|
||||
REUSE-WP-0014-T04 scaffold and then `a10f080` ("Extract binder package from
|
||||
citation-evidence") hand-wrote these two rows around it. `registry/capabilities/`
|
||||
is empty, so both index rows are orphans with no backing entry Markdown.
|
||||
|
||||
Left to that repo's owner because the remaining judgment is theirs: reshaping
|
||||
the rows is mechanical, but assigning D/A/C/R maturity vectors is an assessment
|
||||
of their own delivery state, and invented values would be wrong in a way that is
|
||||
hard to notice later. The message offers `capabilities: []` as an honest
|
||||
alternative — ten other federation members sit at count 0 — and offers to do the
|
||||
work here if they supply vectors or accept a conservative `D1/A0/C0/R0`
|
||||
placeholder marked for review.
|
||||
|
||||
Suggested ids: `capability.evidence.binding`,
|
||||
`capability.evidence.rect-registry`.
|
||||
|
||||
## Re-Enable The evidence-binder Source
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T04
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "9c8ba743-6f76-5627-9bb5-237047fbdcaf"
|
||||
```
|
||||
|
||||
**Done 2026-08-21.** `evidence-binder` fixed and published their index at
|
||||
`e462775` (their EBIND-WP-0002), correctly holding the re-enable request until
|
||||
the Forgejo index was actually visible.
|
||||
|
||||
Pre-checks first this time, given T01's outcome: both backing entry files
|
||||
return `200`, and a local compose of all 61 sources produced 64 capabilities
|
||||
with **zero warnings and no duplicate IDs**. Only then was the source enabled.
|
||||
|
||||
Confirmed on the public endpoint — 61 sources, **64 capabilities**,
|
||||
`composed_at 2026-08-21T08:45:24Z`, `evidence-binder` source count 2, both
|
||||
`capability.evidence.binding` and `capability.evidence.rect-registry` at
|
||||
`D3 / A2 / C3 / R3`.
|
||||
|
||||
**Re-enabling alone was not enough**, and this is the finding worth keeping:
|
||||
after `hub update --enabled`, the endpoint still served a cached compose —
|
||||
62 capabilities, `composed_at` from before the change. It took an explicit
|
||||
`POST /v1/federated/compose` to pick the source up. See T09.
|
||||
|
||||
## Repoint The Production Deployment To A Forgejo Image
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9b500fd0-fb16-5bf7-bea0-9f706d666abc"
|
||||
```
|
||||
|
||||
Deadline-bound: must land before **2026-08-31**.
|
||||
|
||||
1. ~~Verify which tags actually exist.~~ **Done 2026-08-20.** Authenticated
|
||||
against the registry with the workstation's stored Forgejo credentials:
|
||||
|
||||
```
|
||||
GET /v2/coulomb/reuse-surface/tags/list
|
||||
→ {"tags": ["latest", "main-bca7165", "main-f9d957a"]}
|
||||
```
|
||||
|
||||
**There is no `e3ae22e` tag.** The pinned manifest cannot pull today — this
|
||||
is confirmed, not inferred. `main-f9d957a` (2026-07-08, REUSE-WP-0019-T06)
|
||||
is the newest build; the 10 commits between it and HEAD were docs, workplans,
|
||||
and licence changes that do not match the image workflow's path filters, so
|
||||
no newer image exists yet.
|
||||
2. Bump `image.tag` in `railiance-apps/helm/reuse-surface-values.yaml` from
|
||||
`e3ae22e` to a verified Forgejo tag.
|
||||
|
||||
**Done 2026-08-20** — `railiance-apps@029460d` pins `main-b035664`, verified
|
||||
to resolve (manifest `200`). CI built it after `fix-consistency` pushed the
|
||||
T02/T08 commits. It carries the compose hardening, which `main-f9d957a` does
|
||||
not: without it, re-enabling `evidence-binder` (T04) would take production
|
||||
back to HTTP 500.
|
||||
|
||||
Committed but **not applied**. `railiance-apps` has no ArgoCD or Flux
|
||||
controller, so a commit there deploys nothing — `make reuse-deploy` is a
|
||||
manual `helm upgrade` requiring `REUSE_KUBECONFIG` for Railiance01.
|
||||
3. ~~Correct `docs/deploy/reuse-kubernetes.md`.~~ **Done 2026-08-20** (`b035664`).
|
||||
4. **Applied 2026-08-21 00:44 CEST — Helm revision 7, `Upgrade complete`.**
|
||||
|
||||
Access note worth keeping: `RAILIANCE01_KUBECONFIG` defaults to
|
||||
`~/.kube/config-hosteurope` (`127.0.0.1:16443`), which has **no tunnel**.
|
||||
The working path is `~/.kube/config-railiance01` (`127.0.0.1:16444`), served
|
||||
by the `k3s-api-railiance01` ops-bridge tunnel. Deploy with
|
||||
`RAILIANCE01_KUBECONFIG=$HOME/.kube/config-railiance01 make reuse-deploy`
|
||||
until the Makefile default is corrected.
|
||||
|
||||
Pre-flight checks that mattered:
|
||||
|
||||
- The live Deployment really was on `gitea.coulomb.social/coulomb/reuse-surface:e3ae22e`
|
||||
with `pullPolicy: IfNotPresent` — it had survived 18 restarts only because
|
||||
the image was cached on the node. One eviction or image GC would have
|
||||
ended it, retirement date or not.
|
||||
- **No `imagePullSecrets` anywhere** in the chart or the namespace, and the
|
||||
Forgejo `/v2/` endpoint answers `401` anonymously — which looked fatal.
|
||||
It is not: that `401` is Forgejo's token handshake, and peers like
|
||||
`audit-core` pull from the same registry with no secret. Verified properly
|
||||
via the anonymous token flow (`/v2/token?scope=repository:coulomb/reuse-surface:pull`)
|
||||
→ manifest `200`. No pull secret needed.
|
||||
|
||||
Post-deploy verification:
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| Pod | `reuse-surface-7f79d88c-fz7fd`, 0 restarts, ready |
|
||||
| Image | `forgejo.coulomb.social/coulomb/reuse-surface:main-b035664` |
|
||||
| PVC | `reuse-surface-data` bound to the same `pvc-98165f95…` — data kept |
|
||||
| Registrations | all 61 survived |
|
||||
| `/v1/repos`, `/v1/federated` | 200; 60 sources, all Forgejo, 62 capabilities |
|
||||
| `/v1/reuse-events` | **200** (was 404) — REUSE-WP-0019 T04/T05 finally live |
|
||||
| TLS certificate | `condition met` |
|
||||
|
||||
Rollback if ever needed: `helm rollback reuse 6 -n reuse` — but note revision 6
|
||||
pins the Gitea image, which only pulls while the node cache holds it and not
|
||||
at all after 2026-08-31. Rolling forward is the safer direction.
|
||||
|
||||
Superseded steps, kept for context:
|
||||
|
||||
```bash
|
||||
make reuse-dry-run # helm template, no apply
|
||||
make reuse-deploy # helm upgrade --install --wait
|
||||
make reuse-status # pods, svc, ingress, pvc, certificate
|
||||
curl -s https://reuse.coulomb.social/v1/federated | head -c 300
|
||||
curl -s https://reuse.coulomb.social/v1/reuse-events # 404 today; 200 proves T04/T05 shipped
|
||||
```
|
||||
|
||||
Confirm the PVC at `/data` survived, since `reuse.db` and the remote index
|
||||
cache live there.
|
||||
|
||||
**`make reuse-smoke` still fails** — it runs `curl -fsS $(REUSE_URL)/health`,
|
||||
and `/health` returns nginx `404` through the ingress (T06). Everything else
|
||||
in that target passes; the failure is a false negative.
|
||||
|
||||
Ships REUSE-WP-0019 **T04/T05/T06** as a side effect — telemetry store,
|
||||
R-axis aggregation, and hub freshness monitoring were closed as finished but
|
||||
landed after the deployed commit and have never run in production.
|
||||
`GET /v1/reuse-events` returning `404` on production confirms this.
|
||||
|
||||
Review the six weeks of change between `e3ae22e` and HEAD before applying.
|
||||
|
||||
## Correct Hub Freshness And Health Routing
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b1156b36-b9a9-5723-8f33-2b1d33d753f4"
|
||||
```
|
||||
|
||||
Two smaller production inconsistencies found while verifying T01:
|
||||
|
||||
- `GET /health` returns nginx `404` through the ingress. **Diagnosed
|
||||
2026-08-21, not yet fixed.** The application is fine: in-cluster
|
||||
`http://reuse-surface:8000/health` returns `200`. The ingress rule is also
|
||||
correct on paper — `/health` `Exact` → `reuse-surface:8000`, ahead of `/`
|
||||
`Prefix` → `reuse-surface-landing:8080`. The problem is Traefik: it derives
|
||||
router priority from the length of the generated rule string, and
|
||||
``Path(`/health`)`` and ``PathPrefix(`/`)`` are the *same length*, so the
|
||||
tiebreak is arbitrary and the landing route wins. Confirmed by the response
|
||||
carrying `server: nginx/1.27.5` (the landing container) rather than
|
||||
`uvicorn`.
|
||||
|
||||
**Fixed 2026-08-21** — `railiance-apps@a365635`, Helm revision 8. The
|
||||
`router.priority` annotation applies per *Ingress*, not per path, so the
|
||||
landing catch-all moved into its own Ingress (`landing-ingress.yaml`) with
|
||||
`priority: 1`; every API route now outranks it regardless of rule length.
|
||||
|
||||
| Path | Before | After |
|
||||
|---|---|---|
|
||||
| `/health` | `404`, `server: nginx` | **`200`, `server: uvicorn`** |
|
||||
| `/` | `200`, landing | `200`, landing (unchanged) |
|
||||
| `/v1/*` | `200` | `200` (unchanged) |
|
||||
|
||||
`make reuse-smoke` now passes end to end.
|
||||
- `composed_at` stayed at `2026-08-20T20:44:12` with `stale: false` across a
|
||||
recompose that demonstrably changed output (61 → 62 capabilities). **Resolved
|
||||
by T05, not a bug.** The build deployed at the time predated
|
||||
REUSE-WP-0019-T06; `composed_at` now advances with each recompose
|
||||
(`2026-08-21T00:18:02` observed after the redeploy).
|
||||
|
||||
## Refresh SCOPE.md Standard Sections
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T07
|
||||
status: done
|
||||
priority: low
|
||||
state_hub_task_id: "f8cc497b-a429-58ab-b20b-399826b14564"
|
||||
```
|
||||
|
||||
Unrelated to the retirement, recorded so it is not lost. The hub's repo scope
|
||||
check reported `C5b`/`C5c` warnings: `SCOPE.md` was missing the standard H2
|
||||
sections *Relevant When*, *Not Relevant When*, *How It Fits*, *Terminology*,
|
||||
*Related / Overlapping*, *Provided Capabilities*, and carried no fenced
|
||||
capability block.
|
||||
|
||||
**Done 2026-08-21** (`823ce9e`). All six sections added plus three `capability`
|
||||
blocks.
|
||||
|
||||
Writing this section surfaced the **root cause of T03**. The fenced `capability`
|
||||
blocks that belong in `SCOPE.md` use `type` / `title` / `description` /
|
||||
`keywords` — which is *exactly* the shape `evidence-binder` put in its
|
||||
`registry/indexes/capabilities.yaml`, where the required shape is `id` / `name`
|
||||
/ `summary` / `vector` / `domain` / `status` / `owner` / `path` / `tags` /
|
||||
`consumption_modes`. They did not invent a broken format; they copied a valid
|
||||
one from the wrong place.
|
||||
|
||||
That makes it a systemic trap rather than a one-off mistake, so the Terminology
|
||||
section now documents the distinction explicitly, and the compose warning now
|
||||
names it:
|
||||
|
||||
```
|
||||
evidence-binder: capability #0 has no id, skipped — looks like a SCOPE.md
|
||||
capability block (type/title/description/keywords); an index row needs
|
||||
id/name/summary/vector/domain/status/owner/path
|
||||
```
|
||||
|
||||
**Federation swept 2026-08-21.** Composed all 61 sources with `--refresh`:
|
||||
`evidence-binder` is the **only** affected member. The other ten zero-count
|
||||
repos are genuine empty scaffolds and produced no warnings, so the confusion has
|
||||
not spread.
|
||||
|
||||
## Fix Wall-Clock Rot In The Plan-Check Test Suite
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "a06ee643-caf1-5d38-8772-704e865d26fb"
|
||||
```
|
||||
|
||||
Found while verifying T02: `tests/test_plan_check.py` was already failing at
|
||||
clean HEAD, independent of any change here. Three tests pinned the federated
|
||||
index compose date to the literal `"2026-07-06"`, and
|
||||
`test_run_plan_check_reuse_verdict` asserts no staleness warning — so the test
|
||||
passed when written and started failing once wall-clock time drifted past
|
||||
`STALE_DAYS`. **CI is red today for this reason alone**, which matters because
|
||||
T05 calls for verifying the image workflow is green.
|
||||
|
||||
**Done 2026-08-20.** Replaced the literals with a `_recent_date()` helper
|
||||
derived from `STALE_DAYS`. Full suite: 179 passed.
|
||||
|
||||
## Invalidate The Composed Index When A Registration Changes
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0020-T09
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "b0b73c3c-ab8e-5e2f-815e-35c268737b44"
|
||||
```
|
||||
|
||||
Found closing T04. Enabling a federation source on the hub does **not**
|
||||
invalidate the composed index. After `hub update --repo evidence-binder
|
||||
--enabled`, `GET /v1/federated` kept serving the previous compose — 62
|
||||
capabilities, stale `composed_at` — until `POST /v1/federated/compose` was
|
||||
called by hand.
|
||||
|
||||
The consequence is quiet and bad: **a repo can be correctly registered and
|
||||
still be invisible for as long as the cache holds**, with nothing in the
|
||||
response indicating anything is pending. `stale: false` was reported
|
||||
throughout. The webhook path (REUSE-WP-0019-T02) covers *content* changes in a
|
||||
member's `registry/indexes/`, but nothing covers a *registration* change made
|
||||
through the hub's own API.
|
||||
|
||||
Fix: have the write paths on `/v1/repos` (create, and update where `enabled`,
|
||||
`url`, or `required` change) mark the composed index dirty, so the next
|
||||
`GET /v1/federated` recomposes — or at minimum report `stale: true` so a caller
|
||||
can tell the served view no longer matches the registrations behind it.
|
||||
|
||||
**Done 2026-08-21.** `POST /v1/repos`, `DELETE /v1/repos/{repo}`, and a
|
||||
`PATCH` touching `COMPOSITION_FIELDS` (`enabled`, `url`, `index`, `required`,
|
||||
`domain`) now call `mark_stale()`; a plain `GET /v1/federated` recomposes when
|
||||
the flag is set and clears it. A cosmetic `PATCH` (description only) leaves the
|
||||
cache alone. `specs/FederationHubAPI.md` updated — this changes a documented
|
||||
contract, so the spec's staleness section was rewritten rather than left to
|
||||
drift.
|
||||
|
||||
Three tests added. **The first two I wrote were worthless** and it is worth
|
||||
recording why: they passed with the fix removed. A *newly* registered repo has
|
||||
no cache entry, so a plain `GET` fetches it regardless — that was never the
|
||||
bug. The real failure needs a **populated cache holding the old content**:
|
||||
evidence-binder's cached index was the broken pre-repair copy, still inside the
|
||||
24h `cache_ttl_seconds`, so the plain `GET` kept serving zero rows from it.
|
||||
|
||||
`test_re_enabled_source_refetches_a_stale_cache` reproduces exactly that —
|
||||
cache the broken index, disable, republish repaired content, re-enable, plain
|
||||
`GET` — and fails with an assertion error on pre-T09 code.
|
||||
|
||||
Verified by mutation: reverting the three `mark_stale()` calls makes both
|
||||
behavioural tests fail. 184 tests pass on the fix.
|
||||
|
||||
**Deployed and verified in production 2026-08-21**, Helm revision 10, image
|
||||
`main-6cbc862`.
|
||||
|
||||
Revision 9 was a **no-op deploy** and is worth recording as its own lesson: it
|
||||
reported `STATUS: deployed` and `Upgrade complete` while shipping nothing,
|
||||
because `helm/reuse-surface-values.yaml` still pinned `main-b035664`. A
|
||||
successful `helm upgrade` proves the chart applied, *not* that the code
|
||||
changed. Always confirm the running image afterwards:
|
||||
|
||||
```bash
|
||||
kubectl get deploy reuse-surface -n reuse -o jsonpath='{.spec.template.spec.containers[*].image}'
|
||||
```
|
||||
|
||||
Live verification of both halves of the contract, against the real hub:
|
||||
|
||||
| Change | `composed_at` | Result |
|
||||
|---|---|---|
|
||||
| `PATCH {"description": ...}` | `12:18:01`, unchanged | no needless recompose |
|
||||
| `PATCH {"required": false}` | advanced to `14:24:27` on a plain `GET` | self-healed, no manual compose |
|
||||
|
||||
Capabilities stayed at 64 and all 62 registrations were intact throughout.
|
||||
|
||||
Cleanup note: the cosmetic probe wrote a description onto `activity-core`,
|
||||
which had none — 60 of 62 registrations carry no description. Reverted to `""`;
|
||||
the schema rejects `null` with a `400`, so it is falsy like its peers rather
|
||||
than strictly absent. Prior value was not captured before the write, which it
|
||||
should have been.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
python3 -m pytest tests/test_federation.py -q
|
||||
python3 -m reuse_surface.cli validate
|
||||
python3 -m reuse_surface.cli federation compose --refresh
|
||||
REUSE_SURFACE_URL=https://reuse.coulomb.social python3 -m reuse_surface.cli hub list
|
||||
curl -s https://reuse.coulomb.social/v1/federated | python3 -m json.tool | head -20
|
||||
```
|
||||
|
||||
No source may reference `gitea.coulomb.social` after this workplan closes.
|
||||
80
workplans/archived/260908-REUSE-WP-0022-hosted-plan-check.md
Normal file
80
workplans/archived/260908-REUSE-WP-0022-hosted-plan-check.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
---
|
||||
id: REUSE-WP-0022
|
||||
type: workplan
|
||||
title: "Use current hosted capability discovery in factory planning"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
owner: the-custodian
|
||||
topic_slug: helix-forge
|
||||
created: "2026-09-08"
|
||||
updated: "2026-09-08"
|
||||
related: [HFACT-WP-0001, VERGABE-WP-0018]
|
||||
state_hub_workstream_id: "9f90448a-b149-5d04-91b5-0bfc163a9ea2"
|
||||
---
|
||||
|
||||
# Hosted query-before-build
|
||||
|
||||
## Core Idea
|
||||
|
||||
The hosted index contains capabilities absent from the checked-in federation.
|
||||
Provide an explicit hosted plan-check that fetches current discovery, preserves
|
||||
its provenance and refuses incomplete or stale source evidence before producing
|
||||
a recommendation. Vergabe-teilnahme is the first delivery-workflow consumer.
|
||||
|
||||
## Implement and verify hosted planning
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0022-T01
|
||||
status: done
|
||||
priority: high
|
||||
assignee: the-custodian
|
||||
state_hub_task_id: "004ba579-64d0-5b56-9847-b4b02fbf0f7a"
|
||||
```
|
||||
|
||||
Use the existing public GET /v1/federated. Preserve local mode compatibility.
|
||||
Accept only bounded, structurally usable, recently composed, unwarned responses;
|
||||
report endpoint, counts, composition/retrieval times and response digest. Never
|
||||
convert source failure into a NEW verdict, gap request or local fallback. Test
|
||||
hosted-only matches, malformed/stale/partial sources and transport failures.
|
||||
No additional service, model call or mutation credential is necessary.
|
||||
|
||||
## Publish and return the consumer receipt
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0022-T02
|
||||
status: done
|
||||
priority: high
|
||||
assignee: the-custodian
|
||||
depends_on: [REUSE-WP-0022-T01]
|
||||
state_hub_task_id: "a97e7347-70b1-5ce6-93fa-ff9fb1df2133"
|
||||
```
|
||||
|
||||
Publish the tested implementation through the existing Forgejo review path.
|
||||
Capture a real hosted check invoked from vergabe-teilnahme with pinned source
|
||||
revision. Return source and consumer evidence to HFACT-WP-0001-T06; it is source
|
||||
preparation, not proof that the governed Railiance worker performed the change.
|
||||
|
||||
## Verification — 2026-09-08
|
||||
|
||||
Implementation at `2621cf2`: full suite **208 passed** (one upstream Starlette
|
||||
warning). Vergabe-teilnahme invoked the CLI against the real hosted federation:
|
||||
65 capabilities, no warning, `stale: false`, snapshot digest
|
||||
`bfb6b79970867ac981fc48286dea24b2ff766cf732d3675f73ccbddb8971e498`.
|
||||
Consumer receipt: `vergabe-teilnahme/docs/evidence/2026-09-08-hosted-plan-check.json`.
|
||||
This attended implementation does not count as a governed factory run.
|
||||
|
||||
## Completion and handoff
|
||||
|
||||
Integrated on published `main` at `998a5ef3efd42af728fb276594f634f516855daa`
|
||||
after PR 1 and live CI run 331 passed. Main CI 333 and image publication 334
|
||||
passed. Image `main-998a5ef` has digest
|
||||
`sha256:b510acc6bb1aee0e70709f65e53c61a96336ca837eba6dd75ceaa1f5cbf3d441`.
|
||||
Vergabe-teilnahme's consumer and build gate are integrated and its image is
|
||||
published under VERGABE-WP-0018. No production deployment is claimed here.
|
||||
|
||||
Residual integration/operating acceptance remains live in HFACT-WP-0001-T06/T07.
|
||||
HFACT-WP-0001-T02 also owns disposition of three archived REUSE-WP-0017/0018/0019
|
||||
null-ID consistency findings; these are historical projection issues, not failed
|
||||
checks for REUSE-WP-0022. Forgejo PR 1 metadata still needs the authenticated
|
||||
`manually-merged` receipt after OpenBao caller login; source is already on main.
|
||||
|
|
@ -0,0 +1,124 @@
|
|||
---
|
||||
id: REUSE-WP-0021
|
||||
type: workplan
|
||||
title: "Follow the CommerceCanon repository rename in federation sources"
|
||||
domain: infotech
|
||||
repo: reuse-surface
|
||||
status: finished
|
||||
flavor: residual
|
||||
owner: codex
|
||||
origin: residual
|
||||
origin_ref: IDENTITY-WP-0004
|
||||
created: "2026-09-05"
|
||||
updated: "2026-09-20"
|
||||
state_hub_workstream_id: "0d1beafd-e638-5bb9-b91d-13543ac42a04"
|
||||
---
|
||||
|
||||
# CommerceCanon source-coordinate handoff
|
||||
|
||||
identity-canon was renamed to commerce-canon under CFED-WP-0001-T03 and
|
||||
IDENTITY-WP-0004. Forge repository ID 46 is unchanged, and the old URL is a
|
||||
redirect. Project task CFED-WP-0001-T09 owns fleet acceptance and consumes this
|
||||
repository's source/refresh evidence.
|
||||
|
||||
## Update source coordinates and verify federation
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0021-T01
|
||||
status: done
|
||||
flavor: residual
|
||||
priority: medium
|
||||
state_hub_task_id: "b7803b7d-0b70-5aac-8f6a-2704794fccf2"
|
||||
```
|
||||
|
||||
Update registry/federation/sources.yaml and local-repo-roster.yaml to the
|
||||
canonical commerce-canon URL/path. Refresh the affected source cache and
|
||||
registry/indexes/federated.yaml through the repository's federation tooling.
|
||||
Preserve capability.identity.subject-resolution and
|
||||
capability.identity.vocabulary-canonicalize identifiers; a repository rename
|
||||
alone does not redefine capabilities. Source owner/URL/cache metadata should
|
||||
match the newly published commerce-canon registry.
|
||||
|
||||
Verify both capability entries remain discoverable with canonical source links,
|
||||
record command/results and commit, and hand evidence back to CFED-WP-0001-T09.
|
||||
Leave historical workplan/completion provenance intact. No credential, runtime
|
||||
service, or capability-semantic migration is authorized by this task.
|
||||
|
||||
|
||||
## Repair archived workplan bindings reported during handoff registration
|
||||
|
||||
```task
|
||||
id: REUSE-WP-0021-T02
|
||||
status: done
|
||||
flavor: residual
|
||||
priority: low
|
||||
state_hub_task_id: "ceba0cd4-3992-5f16-bdd2-1f054055d10b"
|
||||
```
|
||||
|
||||
The 2026-09-05 handoff registration created this workplan and T01 successfully,
|
||||
but the full consistency audit reported pre-existing invalid `None` bindings in
|
||||
archived REUSE-WP-0017, REUSE-WP-0018 and REUSE-WP-0019 (C-03, plus C-08 on their
|
||||
closed DB records); binding upload returned 422. Reconcile these through the
|
||||
supported identifier/projection tooling, preserving work-record identity and
|
||||
history, then rerun the audit. This is an index-repair follow-up, not a failure
|
||||
of the completed commerce-canon Forge/State Hub rename.
|
||||
|
||||
## Source refresh result — 2026-09-06
|
||||
|
||||
T01 passes: source manifest and roster use commerce-canon; the federation
|
||||
composer refreshed that source with no warnings. Both capability.identity ids
|
||||
and vectors are unchanged; 60 unrelated local index rows are preserved.
|
||||
The live reuse service has an enabled commerce-canon registration and retains
|
||||
the old registration disabled with a replacement note. Its fresh composed index
|
||||
serves both ids from canonical URLs and cache paths, with no target warnings.
|
||||
Existing federation tests: 15 passed. CFED-WP-0001-T09 owns consolidated evidence.
|
||||
|
||||
## Binding repair limitation — 2026-09-06
|
||||
|
||||
T02 remains live and waiting for supported legacy-binding restoration. Null
|
||||
frontmatter fields were deliberately cleared in commit 8b04f91. Current primary
|
||||
workplans remain finished under existing UUIDs:
|
||||
|
||||
- REUSE-WP-0017: a2d83504-fcd0-4561-8688-b77a01cb7f06
|
||||
- REUSE-WP-0018: cd8683ff-6e6c-4f6c-a62f-565bd55113ea
|
||||
- REUSE-WP-0019: 569be717-34f8-4039-bb26-497685f60159
|
||||
|
||||
Repo Manager ensure_missing_work_record_identifiers(execute=False) rejects the
|
||||
blank scalar (expected None, found empty string); moreover its deterministic
|
||||
UUIDs differ from all three existing identities. Ordinary assignment is not a
|
||||
restoration mechanism. State Hub stringifies null as None and classifies it as
|
||||
a stale UUID. Do not manually substitute identifiers or run a derived-identity
|
||||
migration to quiet this audit. T02 must use a reviewed restoration tool that
|
||||
verifies existing primary records and historical source provenance. These
|
||||
archived binding defects do not invalidate the source-coordinate refresh.
|
||||
|
||||
## Binding repair completed — 2026-09-20
|
||||
|
||||
T02 is done. The restoration used the State Hub's own authoritative records
|
||||
rather than derived identifiers, so work-record identity and history are intact.
|
||||
|
||||
**Workplan bindings.** The hub already carried correct `backing_relative_path`
|
||||
and `backing_archived: true` for all three archived workplans, which confirmed
|
||||
each UUID against its file. The verified existing identities were written back
|
||||
into the blank frontmatter fields — the same three UUIDs recorded in the
|
||||
2026-09-06 note above, not newly derived ones. `bindings` upload then returned
|
||||
`synced 22/22` instead of 422; C-03 cleared at the workplan level.
|
||||
|
||||
**Task bindings.** The file task ids matched neither DB set. The hub holds each
|
||||
archived task twice: the original records created 2026-07-06 at registration,
|
||||
and a deterministic UUIDv5 duplicate set created 2026-08-28 by an unrelated
|
||||
migration. The files were rebound to the **2026-07-06 originals** — the
|
||||
historical identities — matched one-to-one by section heading and creation
|
||||
order, with every title aligning exactly. The v5 duplicates were left in place;
|
||||
removing them is hub-side data repair and is not authorized from this repo.
|
||||
|
||||
**One collateral repair.** An intermediate `fix-consistency` run canceled
|
||||
REUSE-WP-0019-T06 (`a9f44d45…`) as an orphan while its file binding was still
|
||||
missing. Once rebound, the task was restored to `done` via
|
||||
`PATCH /tasks/{id}` — a sanctioned status update reflecting work already
|
||||
completed in 2026-07.
|
||||
|
||||
`statehub fix-consistency --repo reuse-surface` now reports
|
||||
**0 automation-error, 0 assessment-fail, PASS (with warnings)**. Remaining
|
||||
warnings are unrelated: C-24 capability-tag advisories and an unread flex-auth
|
||||
inbox message (C-28/C-29, FLEX-WP-0020 handoff).
|
||||
Loading…
Add table
Add a link
Reference in a new issue