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

0. **Read** `handoff-blocks/RESUME.md` FIRST. If `STATUS: ACTIVE`, the previous session was
   interrupted (abrupt close) -> RECOVER from its checkpoint before anything else: resume at the
   first unchecked box, and check its "Uncommitted / in-flight" list against `git status` (anything
   listed but not in git = redo it). If `STATUS: IDLE`, proceed. Then mark RESUME.md ACTIVE for
   this session (copy the ACTIVE template, fill goal + steps). See "Session resilience" below.
0b. **If Sam says "run NEXT"**: read `prompts/NEXT.md`, confirm the Title back to Sam in one line,
    then run it. (The prompt body lives in the repo instead of a copy-paste wall. Human trigger
    stays -- CC never auto-runs it.) See "Shared prompt handoff" below.
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). Update `RESUME.md` at each major step (current step, checklist ticks, uncommitted list).
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].
8. **SESSION-END (clean finish)**: reset `handoff-blocks/RESUME.md` to `STATUS: IDLE` (everything
   committed, nothing in flight). If this session ran a `prompts/NEXT.md` prompt: write
   `prompts/LAST-REPORT.md`, archive the used prompt to `prompts/archive/<date>-<slug>.md`, and
   reset `NEXT.md` to `STATUS: EMPTY`.

## Session resilience (RESUME.md -- crash checkpoint)

`handoff-blocks/RESUME.md` is the recover-after-crash trail (the terminal has closed mid-run 2x;
uncommitted work vanished with no trace). A session writes its goal + live progress there and
updates it at each major step; an abrupt close then leaves a readable "what was I doing" for the
next session. Clean finishes reset it to IDLE. Rule: anything written to disk but not yet committed
MUST be listed under "Uncommitted / in-flight" so a crash leaves it findable. The file itself
documents its template + cadence. This is the cheap fix that de-risks long multi-step runs (e.g. the
ultracode consolidation).

## Shared prompt handoff (prompts/NEXT.md -- less copy-paste)

`prompts/NEXT.md` lets the planning chat commit the next prompt to the repo instead of Sam pasting
a wall of text into the terminal. Sam says "run NEXT"; CC reads it, confirms the title, runs it,
then writes `prompts/LAST-REPORT.md`, archives the used prompt, and empties NEXT.md. **The human
trigger stays** -- CC never polls or auto-runs; Sam always invokes. Full convention: `prompts/README.md`.

## 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. |
| System dashboard | `personal/system-overview/` | CANONICAL system dashboard (B3, 2026-07-15). Recent-activity + health signals; fetches `cc-session-reports/latest.md` at runtime. (The old internal `handoff-blocks/architecture/system-overview.*` was archived.) |
| 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, RESUME (crash checkpoint), scripts, patterns, audits, session reports. |
| Prompt handoff | `prompts/` | `NEXT.md` (planning chat's next prompt), `LAST-REPORT.md` (CC's report back), `archive/` (used prompts). Human-triggered, not autonomous. |
| 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). |

Ultracode consolidation status (executed 2026-07-15, lanes 2/3/4-partial/5/7 done; see
`architecture/dry-run-ultracode-2026-07-15.md`):
- DONE Lane 2: `guides/` retired -> `equipment/` (tombstone archived).
- DONE Lane 3: overlapping how-it-works docs (METHODOLOGY / SYSTEM-DESIGN / ARCHITECTURE / PRINCIPLES /
  SESSION-PRELUDE) -- consolidated via a canonical entry (METHODOLOGY) + cross-ref headers on all 5
  (kept distinct + cross-linked, not physically merged; a file-count merge is an optional follow-on).
- DONE Lane 4 (partial): 20 May-2026 one-off audit logs archived. cc-session-reports NOT moved (it is a
  LIVE runtime dep of personal/system-overview -- fetches latest.md).
- DONE Lane 7: `sitemap.html` accuracy refreshed; it is a CURATED index (not a full tree dump) -- a
  mechanical regen is UNSAFE (would expose sensitive direct-URL pages + lose curation). Not auto-generated.
- DONE Lane 1 (2026-07-15 pm3): `personal/status-tracker/` RETIRED -- ~29 live referrers repointed per a
  canonical map, 28 files archived to `archive/superseded/status-tracker-2026-07-15/`, canonical + fallback
  redirects added. `deploy-log.json` kept live in place (B1, wildcard has no `!` so it is never shadowed).
- DONE Lane 6 (2026-07-15 pm3, B3 resolved: **`personal/system-overview/` is CANONICAL**): archived the
  internal `handoff-blocks/architecture/system-overview.*` (diagram + design doc) ->
  `archive/superseded/system-overview-handoff-2026-07-15/`, redirected old URLs -> canonical page. The
  canonical dashboard's runtime dep (`cc-session-reports/latest.md`) is preserved + verified working.
  Canonical tracker set now: CURRENT-STATE.md (orient) | /personal/this-week/ | /personal/backlog-board/
  | /personal/system-overview/ (dashboard). No other duplicate surfaces remain.

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