# HUB-SWEEP -- session routine + automation

The realistic version of "make bots that do this automatically." CC can't run persistent
autonomous bots on a schedule -- it runs in-session when invoked. What IS automated: reusable
scripts + a documented routine so every session is high-leverage with minimal steering.

## The scripts (Node, no deps -- run from the repo root)

| Command | What it does | When |
|---|---|---|
| `node handoff-blocks/scripts/hub-check.js` | ONE COMMAND: runs sweep + validate, prints both, exits 0 clean / 1 needs-fix. | Start of session + before commit |
| `node handoff-blocks/scripts/hub-sweep.js` | Read-only scan: broken internal links + orphan pages (false-positives filtered). | (called by hub-check) |
| `node handoff-blocks/scripts/hub-validate.js` | Pre-commit gate. FAILS (exit 1) on: SAMEING-NOW JSON broken, cc_status >= 800 chars, stale/resolved Next-up, index.html tag imbalance, or a NEW broken link. | (called by hub-check) |

`hub-check.js` is the single command. `hub-validate.js` is the guard that prevents the two bugs
we already hit (the 29k-char CC "wall of text" and the stale "Harris steering RESOLVED" Next-up).

## SESSION-START routine (any future session -- CC or planning-chat)

1. **Read** `handoff-blocks/CURRENT-STATE.md` (active threads + YOUR MOVES + approvals). One file, orients fast.
2. **Check**: `node handoff-blocks/scripts/hub-check.js` -> sweep + validate in one command.
3. **Fix safe/additive** only (dead links, relinks, freshness, status flips). BATCH judgment calls (archives/merges/customer/financial) as propose-only.
4. **Keep the landing live**: the hub "Next up" = the first `QUEUED` item in `active_now[]` (in awareness-backlog.md's SAMEING-NOW block); `cc_status` = a SHORT current line (history goes in `cc_log`, not rendered). Update these to reality.
5. **Update** `CURRENT-STATE.md` (threads + the READY-TO-DO top-5 + approvals).
6. **Re-check**: `node handoff-blocks/scripts/hub-check.js` -> must exit 0 (CLEAN) before commit.
7. **Commit + push** (substrate). Report: what was [FIXED] / [PROPOSED] / [READY-TO-DO for Sam].

## The gated automation stack (built 2026-07-08, NOT live)

Designed + built, waiting on Sam's explicit go. Read the plan first:
- **Plan**: `architecture/pending/automation-plan-2026-07-08.md` (what's safe-to-automate vs human, per-piece scope/guardrails/rollback, honest capability statement).
- **Sweep-bot** (scheduled, flag-only): **ACTIVE as of 2026-07-08** -- folded into the existing `.github/workflows/weekly-maintenance.yml` as a separate read-only `hub-check` job (runs weekly + on manual dispatch; `permissions: contents: read`; runs `hub-check.js`; FAILS the run -> GitHub notifies Sam on a regression). No content writes, never touches /manage/customer-data/Firebase/deploy-log. **DISABLE:** delete the `hub-check` job from that workflow, or revert the commit that added it (the `scan` job is unaffected). The standalone `automation/staged/sweep-bot.yml` is now the SUPERSEDED reference copy (kept, not active) -- do not also activate it (avoids two schedulers).
- **Ultracode consolidation** (one-time, multi-agent): `architecture/pending/ultracode-consolidation-plan-2026-07-08.md` -- the bounded IA-map P0-P2 consolidation, its parallel lanes, guardrails, and trigger criteria (after Robo/GM week + Firebase Stage B + a dry-run). Not run.

Bots FLAG, humans (or reviewed CC) WRITE. Nothing autonomous touches the business systems.

## Honest capability breakdown

- **One-command now**: the sweep scan, the pre-commit validation, the Next-up/cc_status staleness guard. Run them and they do the checking.
- **Still needs a human trigger**: starting a CC session (you invoke it), and every judgment call (what to archive, customer/financial actions, sending anything, physical work). CC advances the digital prep to the "ready for Sam" edge; you take the last step.
- **Where a scheduled/cloud agent would fit** (not set up here): a nightly cron that runs the sweep + emails the report. That needs the /schedule (routines) feature or a Cloudflare cron Worker -- propose-only; not built.
- **Where ultracode / multi-agent fits**: big ONE-TIME jobs -- a full consolidation (retire status-tracker + merge customer stores + collapse trackers in one pass), or a repo-wide restyle. Those are fan-out work. This routine approach is for ONGOING maintenance (cheap, per-session). Use ultracode when Sam greenlights a big consolidation; use these scripts every session.

## Hub taxonomy (canonical -- where things live)

One home per concern. New pages go in the right space; automation + humans agree on this map.

| Space | Path | Holds |
|---|---|---|
| Orient file | `handoff-blocks/CURRENT-STATE.md` | THE canonical current-state (threads, YOUR MOVES, approvals). Single source. |
| This week | `personal/this-week/` | Time-sensitive tickable list. Personal to-do surface. |
| Backlog board | `personal/backlog-board/` | Full prioritized queue, all areas, TOP 3. |
| Hub health | `personal/hub-health-*/` | Link/orphan scan + stale triage output. |
| Career | `personal/ai-hub/career/` | Robo, GM apps + interview prep, comp, ceiling. |
| Customer jobs | `customer-jobs/<id>/` | Per-customer job docs (rendered via data/customer-jobs.json). |
| Equipment | `equipment/<id>/` | Sam's boats/machines service guides. |
| Personal projects | `personal/<topic>/` | Appliances, grill, fridge, pump-sink, 3d-printing, financial, tools, research. |
| 3D printing | `personal/3d-printing/projects/` | Print project index + per-project pages. |
| Handoff / process | `handoff-blocks/` | CURRENT-STATE, scripts, patterns, audits, session reports. |
| Automation | `handoff-blocks/scripts/` + `automation/staged/` + `.github/workflows/` | The scripts + the (staged) bot + the live hub-check job. |
| Architecture / plans | `architecture/pending/` | Firebase, automation, ultracode plans (propose-and-pause). |
| Sitemap | `sitemap.html` | Full tree index. KNOWN STALE (add new pages here; full regen = an ultracode target). |

Known misfiled/duplicated (propose-only, folds into the ultracode consolidation):
- `personal/status-tracker/` (legacy, ~18 files) -- superseded by system-overview + this-week + backlog-board. RETIRE.
- Tracker surfaces overlap (system-overview vs this-week vs backlog-board) -- collapse to system-dashboard + personal-to-do.
- `sitemap.html` is stale vs the tree -- add new pages as they land; a full regen is an ultracode lane.
- Overlapping how-it-works docs (METHODOLOGY / SYSTEM-DESIGN / ARCHITECTURE / PRINCIPLES) -- consolidate.

## Notes
- ASCII-only. deny rules (rm, .env) hold even in bypass. Website = propose-and-pause (no prod deploy). deploy-log.json NEVER touched.
- Known-tolerated sweep gaps (not bugs): celtics + metal-3dp subdir pages (planned), Pittsburgh trip photos (Sam-provide). Intentional orphans (share pages, per-person portals, ar-collections) are filtered out of the report.