coulomb-loop/workplans/LOOP-WP-0003-registry-orientation-hygiene.md

---
id: LOOP-WP-0003
type: workplan
title: "Registry & Orientation Hygiene (fleet legibility)"
domain: coulomb_social
repo: coulomb-loop
status: active
owner: coulomb-loop
topic_slug: coulomb_social
supplier: kaizen-agentic
created: "2026-06-18"
updated: "2026-06-18"
depends_on:
  - LOOP-WP-0001
tasks:
  - id: T01
    status: todo
    title: Define hygiene signals and domain rollout order
  - id: T02
    status: todo
    title: Create hourly registry gap sweep ActivityDefinition
  - id: T03
    status: todo
    title: Create scope-analyst orientation task template
  - id: T04
    status: todo
    title: Integrate state-hub SBOM staleness with hygiene roster
  - id: T05
    status: todo
    title: Hourly bootstrap on custodian-domain pilot slice
  - id: T06
    status: todo
    title: Expand to next domain batch after pilot exit
  - id: T07
    status: todo
    title: Promote cadence to daily then weekly
state_hub_workstream_id: "f3a4b60a-7bc2-400d-bf8a-e7209a9e45c4"
---

# LOOP-WP-0003 — Registry & Orientation Hygiene

**Status:** active
**Owner:** coulomb-loop (customer)
**Supplier:** kaizen-agentic (`scope-analyst` agent)
**Partner:** reuse-surface (CLI), state-hub (SBOM status)

## Goal

Prevent **fleet legibility drift** across 56 state-hub repos and 53 reuse-surface
registries. Agents and planners can only improve what they can see; this loop
keeps `SCOPE.md`, capability entries, and SBOM metadata current.

```mermaid
flowchart LR
  SH[state-hub repo roster]
  RS[reuse-surface report gaps]
  SBOM[repo_sbom_status]
  SA[schedule prepare scope-analyst]
  VAL[reuse-surface validate]
  SH --> RS
  SH --> SBOM
  RS --> SA --> VAL
```

## Hygiene signals

| Signal | Source | Action |
|--------|--------|--------|
| Registry gap | `reuse-surface report gaps` | `scope-analyst` + `establish --publish-check` |
| Empty capability scaffold | federation roster `capability_count: 0` | draft capability entry or mark intentional |
| Stale SCOPE | `SCOPE.md` mtime > 90d or missing | `scope-analyst` refresh |
| Stale SBOM | `sbom_age_days > 30` (state-hub) | flag + link to existing activity-core SBOM job |
| Publish check fail | `publish_check: fail` in federation roster | registry fix task |

Signals documented in `loops/registry-hygiene/signals.yml`.

## Domain rollout order

Bootstrap processes **small batches** to avoid task storms:

1. **custodian** (11 repos) — aligns with LOOP-WP-0001 pilots
2. **helix_forge** (4 repos) — reuse-surface home domain
3. **stack** (3 repos) — artifact-store, open-reuse
4. Remaining domains — one per weekly cycle after daily stabilization

## Cadence ramp

| Phase | Cron | Batch size |
|-------|------|------------|
| Bootstrap | `0 * * * *` (hourly) | 3 repos per run (round-robin) |
| Stabilize | `0 7 * * *` (daily) | 1 domain per day |
| Operate | `0 9 * * 1` (weekly Mon) | 1–2 domains per week |

Hourly bootstrap uses **round-robin** across custodian pilot slice (3 repos per
hour), not full fleet scan.

## Part 1 — Signal and template setup

## Define hygiene signals and rollout order

```task
id: LOOP-WP-0003-T01
status: todo
priority: high
state_hub_task_id: "cacc914e-85e6-4067-b39d-cf8a3ae91320"
```

Create:

- `loops/registry-hygiene/signals.yml`
- `loops/registry-hygiene/rollout.yaml` (domain order + repo slugs)
- `loops/registry-hygiene/round-robin-state.json` (cursor for hourly batching)

## Hourly registry gap sweep ActivityDefinition

```task
id: LOOP-WP-0003-T02
status: todo
priority: high
state_hub_task_id: "7c6b15cd-a5ac-4602-956f-61de72a55fef"
```

Create `coulomb-loop/activity-definitions/hourly-registry-hygiene-sweep.md`:

```yaml
trigger:
  cron_expression: "20 * * * *"
context_sources:
  - type: state-hub
    query: repo_sbom_status
    bind_to: context.repos
  - type: shell
    query: reuse_surface_report_gaps
    params:
      roster: coulomb-loop/loops/registry-hygiene/rollout.yaml
    bind_to: context.gaps
```

Rule: for each repo in current hourly batch with any hygiene signal, create task:

```
kaizen-agentic schedule prepare scope-analyst
reuse-surface validate
reuse-surface establish --publish-check   # when registry touched
```

`enabled: false` until shell resolver wrapper exists in activity-core.

## scope-analyst orientation template

```task
id: LOOP-WP-0003-T03
status: todo
priority: medium
state_hub_task_id: "e8eb2700-8ef5-43fb-8d2e-ec080fa86f6f"
```

Create `loops/registry-hygiene/session-template.md` — standard task description
for scope-analyst sessions: read SCOPE, compare to INTENT, update registry index,
file state-hub progress event.

## Part 2 — Integration

## Integrate SBOM staleness with hygiene roster

```task
id: LOOP-WP-0003-T04
status: todo
priority: medium
state_hub_task_id: "09cec748-0bfa-4870-b44f-50813f7ed626"
```

Document handoff with existing `activity-core/weekly-sbom-staleness`:

- Do not duplicate SBOM rescans in this loop
- Hygiene task **links** to SBOM job when `sbom_age_days > 30`
- Shared label: `fleet-hygiene`

Add cross-reference in `loops/registry-hygiene/signals.yml`.

## Hourly bootstrap on custodian pilot slice

```task
id: LOOP-WP-0003-T05
status: todo
priority: medium
state_hub_task_id: "76029879-01ed-4db2-afcf-3876db45b395"
```

Pilot batch: `kaizen-agentic`, `the-custodian`, `activity-core`.

Manual smoke test (before activity-core enable):

```bash
reuse-surface report gaps --roster <rollout.yaml>
kaizen-agentic schedule prepare scope-analyst --target /home/worsch/kaizen-agentic
reuse-surface validate  # in target repo
```

**Bootstrap exit:** 3 hourly rounds complete without duplicate tasks for same repo+signal.

## Expand domain batch

```task
id: LOOP-WP-0003-T06
status: todo
priority: low
state_hub_task_id: "f6e5a9d5-2c32-439d-9e95-aa6d6fd3c6ab"
```

After regulator approval, add helix_forge domain to rollout. Increase batch size
when false-positive rate stays below 20%.

## Promote cadence

```task
id: LOOP-WP-0003-T07
status: todo
priority: low
state_hub_task_id: "5b6bb667-42e1-4e41-968e-4025ac2e72ce"
```

| Promotion | Condition |
|-----------|-----------|
| hourly → daily | bootstrap exit + LOOP-WP-0004 approval |
| daily → weekly | 2 weeks daily with &lt; 10% repeat tasks for same signal |

Update activity-core definitions and `loops/registry-hygiene/cadence.yml`.

## Definition of done

- Hygiene sweep creates actionable scope-analyst tasks on pilot repos
- reuse-surface validate passes after hygiene session on at least one repo
- SBOM staleness delegated to existing activity-core job (no duplicate work)
- Domain rollout order and cadence ramp documented

## Out of scope

- Implementing `reuse-surface report gaps` resolver in coulomb-loop
- Mandatory capability maturity promotion (planning-only in bootstrap)
- Full 56-repo hourly scan

## Supplier feedback

Document whether `scope-analyst` needs engagement-specific briefing template.
Feed reuse-surface + kaizen-agentic supplier playbook.