Compare commits

..

4 Commits

Author SHA1 Message Date
08f3bb5110 feat(federation): register config-atlas and reserve surface.* namespace
Some checks failed
ci / validate-registry (push) Has been cancelled
Add config-atlas as a federation source (capability index) and to the local
repo roster. Document surface.* as a distinct id namespace owned by
config-atlas (typed sibling of capability.*, not federated here) under a new
"Id namespace ownership" section. Raw URL currently 303 (required:false), same
publish block as state-hub/feature-control. Recompose federated.yaml.

Supports config-atlas ATLAS-WP-0002-T05.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-26 23:48:20 +02:00
368fb156d4 Normalize agent instructions and workplan frontmatter (STATE-WP-0067)
Some checks failed
ci / validate-registry (push) Has been cancelled
- Align agent files with on-disk workplan prefixes (infer from workplan ids)
- Set workplan domain to registered domain_slug; add topic_slug where applicable
- Repair frontmatter delimiter formatting; migrate legacy task status literals
- Regenerate AGENTS.md, CLAUDE.md, and .claude/rules from State Hub templates
2026-06-22 23:16:28 +02:00
fe05d60a66 Human-review .repo-classification.yaml (CUST-WP-0050 follow-up)
Some checks failed
ci / validate-registry (push) Has been cancelled
2026-06-22 17:56:16 +02:00
fd078c598c Add .repo-classification.yaml (CUST-WP-0050 T11 agent first-pass) 2026-06-22 17:47:43 +02:00
18 changed files with 166 additions and 193 deletions

25
.repo-classification.yaml Normal file
View File

@@ -0,0 +1,25 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-06-22'
classified_by: human
category: product
domain: infotech
secondary_domains:
- agents
capability_tags:
- capability-registry
- discovery
- reuse
- maturity
- evidence
business_stake:
- technology
- product
- intelligence
- automation
business_mechanics:
- intention
- control
- adaptation
notes: Reuse discovery surface; standard §13.7 — human confirmed.

162
AGENTS.md
View File

@@ -4,7 +4,7 @@
**Purpose:** Capability registry for planning and implementation reuse based on discovery and delivery maturity.
**Domain:** helix_forge
**Domain:** infotech
**Repo slug:** reuse-surface
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
**Workplan prefix:** `REUSE-WP-`
@@ -101,159 +101,6 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
---
## Local Developer Workflow
The repository is primarily documentation-first with a small Python CLI for
registry validate, query, and export. There is no long-running service.
### Install
```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```
### Build
No separate build step. Treat Markdown, YAML, and workplan edits as source
artifacts.
### Test / lint
```bash
# Registry validation (schema + index drift)
.venv/bin/reuse-surface validate
# Overlap, catalog, federation, and graph
.venv/bin/reuse-surface overlaps
.venv/bin/reuse-surface catalog
.venv/bin/reuse-surface federation compose
.venv/bin/reuse-surface graph --check
# Federation service (local)
# REUSE_SURFACE_TOKEN=dev-token reuse-surface serve
# Hub CLI (against deployed or local service)
# REUSE_SURFACE_URL=http://127.0.0.1:8000 reuse-surface hub status
# Automated tests
.venv/bin/pytest -q
# Repository hygiene
rg --files
git diff --check
```
When workplan files change, sync ADR-001 file state into State Hub:
```bash
curl -s -X POST "http://127.0.0.1:8000/repos/reuse-surface/sync?fix=true" \
| python3 -m json.tool
```
If the HTTP sync endpoint is unavailable, run the consistency script from the
State Hub checkout:
```bash
cd ~/state-hub
.venv/bin/python scripts/consistency_check.py --repo reuse-surface --fix
.venv/bin/python scripts/consistency_check.py --repo reuse-surface
```
The generated instruction in older workplans says `make fix-consistency
REPO=reuse-surface`; that is still valid when `uv` is installed and on PATH.
On this workstation, the `.venv/bin/python` fallback has been verified.
CI runs `reuse-surface validate` on push and pull requests via
`.gitea/workflows/ci.yml`.
### Run
There is no local service to run from this repository.
### Documentation Review Checklist
- Keep `INTENT.md`, `SCOPE.md`, and `specs/` aligned on the registry-first
reuse boundary.
- Keep maturity definitions in `specs/CapabilityMaturityStandard.md` consistent
with `INTENT.md` and `specs/ProductRequirementsDocument.md`.
- Keep registry entries, indexes, and schemas in `registry/`, `schemas/`, and
`templates/` current when capabilities change.
- Record implementation ideas in workplans, not as premature runtime code in
this repository.
---
## Capability Registry
Before building or documenting a new reusable behavior, query the registry to
avoid duplication and to select the best existing capability for planning or
implementation reuse.
### Orient
```bash
# Fast discovery surface — read federated index when multi-repo
cat registry/indexes/federated.yaml
cat registry/indexes/capabilities.yaml
# CLI discovery and export
.venv/bin/reuse-surface query --discovery-min D4
.venv/bin/reuse-surface export --format yaml
# Authoring template and schema
cat templates/capability-entry.template.md
cat schemas/capability.schema.yaml
# Validation and search guidance
cat registry/README.md
cat tools/README.md
```
### Query workflow
1. Run `.venv/bin/reuse-surface query` with filters, or read the index directly.
2. Filter by `vector`, `tags`, `consumption_modes`, `domain`, or `summary`.
3. Open only matching files under `registry/capabilities/`.
4. Compare candidates using `discovery`, `external_evidence`, `availability`,
and `relations` from the entry front matter.
5. Prefer planning reuse when discovery is strong (`D3+`, especially `D5+`).
6. Prefer implementation reuse only when availability is consumable (`A2+` code,
`A3+` CLI, `A4+` API/SDK).
### Add a new capability
1. Search the index for overlap (UC-RS-015) before creating a new entry.
2. Copy `templates/capability-entry.template.md` to
`registry/capabilities/capability.<domain>.<name>.md`.
3. Start at `D0 / A0 / C0 / R0` when evidence is minimal; keep gaps explicit.
4. Add the entry to `registry/indexes/capabilities.yaml`.
5. Run `.venv/bin/reuse-surface validate`.
### Promote a capability
1. Attach evidence required by `specs/CapabilityMaturityStandard.md` for the
target level.
2. Update `maturity` for discovery/availability and `external_evidence` for
completeness/reliability separately.
3. Refresh the index `vector` and record rationale in the entry body.
4. Do not treat higher availability as proof of reliability or completeness.
### MVP acceptance mapping
| Acceptance criterion | Registry surface |
|---|---|
| Add D0/A0/C0/R0 with minimal friction | template + index + registry README |
| Promote through discovery levels | entry front matter + maturity standard |
| Identify current consumption mode | `availability` + index `consumption_modes` |
| Record expectations and broken expectations | `external_evidence.completeness` |
| Record reliability evidence | `external_evidence.reliability` |
| Search by maturity and availability | `reuse-surface query` or index filters |
| Compare candidates | entry vectors + relations + README guidance |
| Avoid duplicate capabilities | index search before add |
---
## Credential and access routing
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
@@ -304,6 +151,11 @@ every repo's agent instructions because it is high-frequency, high-risk, and eas
get wrong.
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
@@ -329,7 +181,7 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
id: REUSE-WP-NNNN
type: workplan
title: "..."
domain: helix_forge
domain: infotech
repo: reuse-surface
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex

View File

@@ -1,17 +1,12 @@
{
"agents": {
"coach": {
"path": "agents/agent-coach.md",
"enabled": true
},
"optimization": {
"path": "agents/agent-optimization.md",
"enabled": true
},
"scope-analyst": {
"path": "agents/agent-scope-analyst.md",
"enabled": true
}
}
}
# reuse-surface — Claude Code Instructions
@SCOPE.md
@.claude/rules/repo-identity.md
@.claude/rules/session-protocol.md
@.claude/rules/first-session.md
@.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
@.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md
@.claude/rules/agents.md

View File

@@ -159,9 +159,9 @@ Copy `templates/Makefile.registry.fragment` for `make registry-maintain` /
5. Optionally `reuse-surface hub sync --merge` to refresh local `sources.yaml`.
**Current blocks (2026-06-16):** `state-hub`, `feature-control`,
`identity-canon`, and `shard-wiki` raw URLs return **303** (not published).
See `history/2026-06-16-hub-registration-blocks.md` for probe evidence and owner
follow-ups.
`identity-canon`, `shard-wiki`, and `config-atlas` raw URLs return **303** (not
published). See `history/2026-06-16-hub-registration-blocks.md` for probe evidence
and owner follow-ups.
## Compose workflow
@@ -191,6 +191,19 @@ remote sources without cache fail compose with a clear error.
`warn` (default): duplicate IDs across sources are kept but reported as
warnings. Consumers must inspect `source_repo` before choosing an entry.
### Id namespace ownership
Federation aggregates `capability.*` ids. A few repos own **distinct id families**
that are *not* capability indexes and therefore never collide with `capability.*`:
| Namespace | Owner repo | Index (not federated here) |
|---|---|---|
| `surface.*` (configuration surfaces) | `config-atlas` | `registry/indexes/surfaces.yaml` |
config-atlas federates only its `capabilities.yaml` (the atlas capability itself);
its `surface.*` registry is a typed sibling. The `surface.*` namespace is reserved
for config-atlas so the two id families stay orthogonal under `collision_policy`.
### Owner migration and deduplication
After REUSE-WP-0014, many capabilities remain in both `reuse-surface` and their

View File

@@ -1,17 +1,17 @@
version: 1
updated: '2026-06-16'
updated: '2026-06-26'
workstation_root: /home/worsch
definition: All git repositories one level under the workstation home directory (e.g.
/home/worsch/<slug> with a .git directory). Excludes nested worktrees and non-git
folders.
summary:
total: 60
established: 60
total: 61
established: 61
pending: 0
with_reuse_surface_seed: 8
hub_registered: 60
hub_registered: 61
publish_pass: 60
publish_fail: 0
publish_fail: 1
publish_sweep: '2026-06-16'
repos:
- slug: activity-core
@@ -87,6 +87,17 @@ repos:
hub_registered: true
publish_check: pass
batch: B01
- slug: config-atlas
path: /home/worsch/config-atlas
status: established
capability_count: 1
seed_from_reuse_surface: false
seed_capability_ids:
- capability.infotech.config-surface-atlas
hub_registered: true
publish_check: fail
publish_note: 303 not published (same block as state-hub/feature-control)
batch: B02
- slug: coordination-engine
path: /home/worsch/coordination-engine
status: established

View File

@@ -58,6 +58,18 @@ sources:
domain: helix_forge
cache_ttl_seconds: 86400
auth_header: Authorization
- repo: config-atlas
url: https://gitea.coulomb.social/coulomb/config-atlas/raw/main/registry/indexes/capabilities.yaml
enabled: true
required: false
domain: helix_forge
description: >-
Configuration Surface Atlas. Owns the `surface.*` id namespace (configuration
surfaces in registry/indexes/surfaces.yaml) as a typed sibling of `capability.*`;
only its capability index is federated here. Raw URL returns 303 until publish
is resolved (same block as state-hub/feature-control).
cache_ttl_seconds: 86400
auth_header: Authorization
- repo: coordination-engine
url: https://gitea.coulomb.social/coulomb/coordination-engine/raw/main/registry/indexes/capabilities.yaml
enabled: true

View File

@@ -1,7 +1,7 @@
# Composed federated capability index. Regenerate with:
# reuse-surface federation compose
version: 1
updated: '2026-06-18'
updated: '2026-06-26'
domain: helix_forge
collision_policy: warn
sources:
@@ -37,6 +37,10 @@ sources:
count: 0
url: https://gitea.coulomb.social/coulomb/citation-work/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/citation-work.yaml
- repo: config-atlas
count: 1
url: https://gitea.coulomb.social/coulomb/config-atlas/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/config-atlas.yaml
- repo: coordination-engine
count: 0
url: https://gitea.coulomb.social/coulomb/coordination-engine/raw/main/registry/indexes/capabilities.yaml
@@ -82,7 +86,7 @@ sources:
url: https://gitea.coulomb.social/coulomb/hub-core/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/hub-core.yaml
- repo: human-resources
count: 0
count: 1
url: https://gitea.coulomb.social/coulomb/human-resources/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/human-resources.yaml
- repo: identity-canon
@@ -202,7 +206,7 @@ sources:
url: https://gitea.coulomb.social/coulomb/repo-scoping/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/repo-scoping.yaml
- repo: repo-seed
count: 0
count: 1
url: https://gitea.coulomb.social/coulomb/repo-seed/raw/main/registry/indexes/capabilities.yaml
cache: registry/federation/cache/repo-seed.yaml
- repo: reuse-surface
@@ -355,6 +359,25 @@ capabilities:
source_repo: feature-control
source_url: https://gitea.coulomb.social/coulomb/feature-control/raw/main/registry/indexes/capabilities.yaml
source_index: registry/federation/cache/feature-control.yaml
- id: capability.hr.workflow-catalog
name: HR Workflow Catalog
summary: Markdown-first registry of HR planning workflows with an iterative assessment
loop tied to INTENT phases.
vector: D3 / A1 / C1 / R0
domain: consumer
status: draft
owner: human-resources
path: registry/capabilities/capability.hr.workflow-catalog.md
tags:
- hr
- workflows
- assessment
- planning
consumption_modes:
- informational
source_repo: human-resources
source_url: https://gitea.coulomb.social/coulomb/human-resources/raw/main/registry/indexes/capabilities.yaml
source_index: registry/federation/cache/human-resources.yaml
- id: capability.identity.subject-resolution
name: Identity Subject Resolution
summary: Resolve who or what is acting by mapping principals, accounts, actors,
@@ -391,6 +414,48 @@ capabilities:
source_repo: identity-canon
source_url: https://gitea.coulomb.social/coulomb/identity-canon/raw/main/registry/indexes/capabilities.yaml
source_index: registry/federation/cache/identity-canon.yaml
- id: capability.infotech.config-surface-atlas
name: Configuration Surface Atlas
summary: "Read-first, cross-kind map and evidence layer for configuration surfaces\
\ \u2014 what configures a system, who owns it, its scope, and where the source\
\ of truth lives."
vector: D5 / A0 / C2 / R2
domain: infotech
status: draft
owner: config-atlas
path: registry/capabilities/capability.infotech.config-surface-atlas.md
tags:
- configuration
- registry
- control-plane
- effective-config
- evidence
consumption_modes:
- informational
- source module
source_repo: config-atlas
source_url: https://gitea.coulomb.social/coulomb/config-atlas/raw/main/registry/indexes/capabilities.yaml
source_index: registry/federation/cache/config-atlas.yaml
- id: capability.infotech.repo-template
name: Coulomb Repository Template
summary: Bootstrap new git repositories with agent instructions, registry scaffold,
and State Hub onboarding conventions.
vector: D3 / A3 / C2 / R2
domain: infotech
status: draft
owner: repo-seed
path: registry/capabilities/capability.infotech.repo-template.md
tags:
- template
- bootstrap
- state-hub
- onboarding
consumption_modes:
- git clone
- informational
source_repo: repo-seed
source_url: https://gitea.coulomb.social/coulomb/repo-seed/raw/main/registry/indexes/capabilities.yaml
source_index: registry/federation/cache/repo-seed.yaml
- id: capability.registry.register
name: Capability Registration
summary: Register a new capability so it becomes visible for planning and implementation

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0001
type: workplan
title: "Bootstrap State Hub integration"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0002
type: workplan
title: "MVP registry foundation"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0003
type: workplan
title: "Close intent-scope gaps: docs, tooling, and registry growth"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0004
type: workplan
title: "Registry hardening: CI, overlap detection, and catalog"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0005
type: workplan
title: "Registry federation and relation graphs"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0006
type: workplan
title: "Registry hygiene and coverage expansion"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0007
type: workplan
title: "Interactive capability catalog"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0008
type: workplan
title: "Interactive relation graph explorer"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0009
type: workplan
title: "CLI hardening and test suite"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0010
type: workplan
title: "Network federation for remote indexes"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex

View File

@@ -2,7 +2,7 @@
id: REUSE-WP-0016
type: workplan
title: "Interactive registry maintain with llm-connect automation"
domain: helix_forge
domain: infotech
repo: reuse-surface
status: finished
owner: codex