Ecosystem + Equality Reconcile
Run this on any computer to drive it back into equivalence with the rest of the
ecosystem. It reconciles two surfaces at once:
- Repo-ecosystem hygiene — dirty working trees, behind/ahead upstream, merged-but-
undeleted branches, stale worktrees, stale stashes, across this machine's sibling repos.
- Machine-equality — every cell in this machine's column of the
equality matrix (
docs/reports/machine-equality-matrix.html) that is not
OK / CONFORMS / EQUAL / PARITY.
Driver: scripts/readiness/reconcile-ecosystem.sh (repo-root relative).
It is report-first — the default run mutates nothing.
Safety boundary (load-bearing)
The driver inherits the deny-by-default guard (scripts/lib/worktree_guard.py, #3143). It
never:
- discards dirty work (it stashes — recoverable — only with
--apply --stash-dirty),
- deletes a branch that is unmerged, current, or checked out in any live worktree,
- removes a worktree it cannot prove it owns (foreign / active-session worktrees are surfaced, not pruned),
- does anything but fast-forward on remotes (no reset/force/rebase).
Every action is classified before anything runs:
| Class |
Meaning |
--apply behaviour |
AUTO-SAFE |
reversible / guard-approved |
executed |
NEEDS-APPROVAL |
destructive or judgement-dependent |
printed only — you run it after review |
OPERATOR-ONLY |
off-box (Windows licence probe, hardware, remote host) |
printed only |
Procedure
# 1. SEE the plan (read-only — safe anywhere, anytime)
bash scripts/readiness/reconcile-ecosystem.sh
bash scripts/readiness/reconcile-ecosystem.sh --json # machine-readable, for CI/dispatch
# 2. APPLY only the auto-safe subset (ff-pulls clean repos, etc.)
bash scripts/readiness/reconcile-ecosystem.sh --apply
# 3. Resolve dirty trees deliberately (recoverable stash), then re-pull
bash scripts/readiness/reconcile-ecosystem.sh --apply --stash-dirty
# 4. After the tree is clean + fetched, refresh THIS machine's equality report + matrix
bash scripts/readiness/reconcile-ecosystem.sh --apply --equality
Work the NEEDS-APPROVAL list by hand — each line prints the exact command. For branch /
worktree disposal at scale on the primary, prefer the existing guarded cron
(scripts/cron/daily-cleanup.sh --dry-run then live) rather than ad-hoc deletion.
Machine policy (who may do destructive cleanup)
| Machine (role) |
Hygiene cleanup |
Notes |
dev-primary (ace-linux-1, control-plane) |
report-only for branch/worktree |
runs the intentional worktree-per-feature automation + owns the daily-cleanup cron; the driver auto-sets DESTRUCTIVE_OK=0 here so it never trampls live worktrees |
dev-secondary (ace-linux-2) |
full auto-safe eligible |
scratch/execution box |
ace-win-1, ace-win-2 (Windows) |
scout-only; bug-fixes OK |
licensed hosts; do max work on Linux, keep these thin |
Equality verdict → corrective action (the playbook)
The driver maps each non-OK verdict in this machine's column to a fix:
| Verdict |
Cause |
Corrective action |
STALE-CHECKOUT |
dirty / behind / ahead / origin-ref > 12h |
clean the tree (commit-push or --stash-dirty), git fetch origin main, re-run collect-equality.sh |
MISSING-EVIDENCE (machine dim) |
no fresh report on this box |
run collect-equality.sh here |
MISSING-EVIDENCE (harness:<provider>:*) |
provider/ capability absent — or no Claude baseline on this host (Hermes-only box grades these by design) |
install/auth the provider; on a Hermes-only host, expected |
BELOW-BASELINE solvers |
licence probe emits present ≠ licensed |
operator/Windows licence-probe follow-up (PR #2850 note) |
BELOW-BASELINE data_access |
a required tier-1 sibling isn't cloned |
clone the missing repo under the sibling root |
BELOW-BASELINE compute |
under cores/ram/gpu floor |
operator — hardware, or reconcile harness-config.yaml compute_floor |
DIVERGES / NO-MAJORITY skills |
tracked symlink materialized as a text file (core.symlinks=false) |
git config core.symlinks true; rm + git checkout -- the symlink paths |
DIVERGES / NO-MAJORITY harness / behavior |
runtime/config drift |
build-soul-runtime.sh + install-soul-runtime.sh, then re-collect |
DIVERGES / NO-MAJORITY scheduler |
cron drift |
setup-cron.sh --check, then re-collect |
DIVERGES / NO-MAJORITY (other) |
often a stale peer report inflating divergence |
re-collect on this box first; if it persists, reconcile the config |
UNREACHABLE / EXPECTED-DIFF / EXPECTED-DIVERGENCE |
by design |
no action |
After reconciling
Re-render and (if pushing) refresh the live link per
[[machine-equality-matrix-live-link]]. A divergence that survives a clean re-collect is a
real config drift, not a stale-report artifact — fix the config, don't just re-collect.
Related
repo-ecosystem-hygiene — the read-only detector this complements (it reports; this remediates).worktree-branch-sync-hygiene — branch/worktree disposal workflow for the NEEDS-APPROVAL items.scripts/cron/daily-cleanup.sh — the guarded primary-host cron that owns at-scale auto-disposal.
1---2name: ecosystem-equivalence-reconcile3description: Bring THE CURRENT computer back to ecosystem + machine-equality equivalence — clean repo-hygiene drift (dirty trees, stale branches/worktrees/stashes) and remediate every non-OK equality-matrix verdict. Report-first; destructive actions are guard-gated and opt-in.4---56# Ecosystem + Equality Reconcile78Run this **on any computer** to drive it back into equivalence with the rest of the9ecosystem. It reconciles two surfaces at once:10111. **Repo-ecosystem hygiene** — dirty working trees, behind/ahead upstream, merged-but-12 undeleted branches, stale worktrees, stale stashes, across this machine's sibling repos.132. **Machine-equality** — every cell in this machine's column of the14 equality matrix (`docs/reports/machine-equality-matrix.html`) that is not15 `OK / CONFORMS / EQUAL / PARITY`.1617Driver: `scripts/readiness/reconcile-ecosystem.sh` (repo-root relative).18It is **report-first** — the default run mutates nothing.1920## Safety boundary (load-bearing)2122The driver inherits the deny-by-default guard (`scripts/lib/worktree_guard.py`, #3143). It23**never**:24- discards dirty work (it stashes — recoverable — only with `--apply --stash-dirty`),25- deletes a branch that is unmerged, current, or checked out in any live worktree,26- removes a worktree it cannot prove it owns (foreign / active-session worktrees are surfaced, not pruned),27- does anything but **fast-forward** on remotes (no reset/force/rebase).2829Every action is classified before anything runs:3031| Class | Meaning | `--apply` behaviour |32|---|---|---|33| `AUTO-SAFE` | reversible / guard-approved | executed |34| `NEEDS-APPROVAL` | destructive or judgement-dependent | printed only — you run it after review |35| `OPERATOR-ONLY` | off-box (Windows licence probe, hardware, remote host) | printed only |3637## Procedure3839```bash40# 1. SEE the plan (read-only — safe anywhere, anytime)41bash scripts/readiness/reconcile-ecosystem.sh42bash scripts/readiness/reconcile-ecosystem.sh --json # machine-readable, for CI/dispatch4344# 2. APPLY only the auto-safe subset (ff-pulls clean repos, etc.)45bash scripts/readiness/reconcile-ecosystem.sh --apply4647# 3. Resolve dirty trees deliberately (recoverable stash), then re-pull48bash scripts/readiness/reconcile-ecosystem.sh --apply --stash-dirty4950# 4. After the tree is clean + fetched, refresh THIS machine's equality report + matrix51bash scripts/readiness/reconcile-ecosystem.sh --apply --equality52```5354Work the `NEEDS-APPROVAL` list by hand — each line prints the exact command. For branch /55worktree disposal at scale on the primary, prefer the existing guarded cron56(`scripts/cron/daily-cleanup.sh --dry-run` then live) rather than ad-hoc deletion.5758## Machine policy (who may do destructive cleanup)5960| Machine (role) | Hygiene cleanup | Notes |61|---|---|---|62| `dev-primary` (ace-linux-1, control-plane) | **report-only for branch/worktree** | runs the intentional worktree-per-feature automation + owns the `daily-cleanup` cron; the driver auto-sets `DESTRUCTIVE_OK=0` here so it never trampls live worktrees |63| `dev-secondary` (ace-linux-2) | full auto-safe eligible | scratch/execution box |64| `ace-win-1`, `ace-win-2` (Windows) | scout-only; bug-fixes OK | licensed hosts; do max work on Linux, keep these thin |6566## Equality verdict → corrective action (the playbook)6768The driver maps each non-OK verdict in this machine's column to a fix:6970| Verdict | Cause | Corrective action |71|---|---|---|72| `STALE-CHECKOUT` | dirty / behind / ahead / origin-ref > 12h | clean the tree (commit-push or `--stash-dirty`), `git fetch origin main`, re-run `collect-equality.sh` |73| `MISSING-EVIDENCE` (machine dim) | no fresh report on this box | run `collect-equality.sh` here |74| `MISSING-EVIDENCE` (`harness:<provider>:*`) | provider/ capability absent — or no Claude baseline on this host (Hermes-only box grades these by design) | install/auth the provider; on a Hermes-only host, expected |75| `BELOW-BASELINE` `solvers` | licence probe emits `present` ≠ `licensed` | **operator/Windows** licence-probe follow-up (PR #2850 note) |76| `BELOW-BASELINE` `data_access` | a required tier-1 sibling isn't cloned | clone the missing repo under the sibling root |77| `BELOW-BASELINE` `compute` | under cores/ram/gpu floor | **operator** — hardware, or reconcile `harness-config.yaml` `compute_floor` |78| `DIVERGES` / `NO-MAJORITY` `skills` | tracked symlink materialized as a text file (`core.symlinks=false`) | `git config core.symlinks true`; `rm` + `git checkout --` the symlink paths |79| `DIVERGES` / `NO-MAJORITY` `harness` / `behavior` | runtime/config drift | `build-soul-runtime.sh` + `install-soul-runtime.sh`, then re-collect |80| `DIVERGES` / `NO-MAJORITY` `scheduler` | cron drift | `setup-cron.sh --check`, then re-collect |81| `DIVERGES` / `NO-MAJORITY` (other) | often a **stale peer** report inflating divergence | re-collect on this box first; if it persists, reconcile the config |82| `UNREACHABLE` / `EXPECTED-DIFF` / `EXPECTED-DIVERGENCE` | by design | no action |8384## After reconciling8586Re-render and (if pushing) refresh the live link per87[[machine-equality-matrix-live-link]]. A divergence that survives a clean re-collect is a88**real** config drift, not a stale-report artifact — fix the config, don't just re-collect.8990## Related9192- `repo-ecosystem-hygiene` — the read-only detector this complements (it reports; this remediates).93- `worktree-branch-sync-hygiene` — branch/worktree disposal workflow for the NEEDS-APPROVAL items.94- `scripts/cron/daily-cleanup.sh` — the guarded primary-host cron that owns at-scale auto-disposal.
vamseeachanta