diff --git a/condemned.md b/condemned.md new file mode 100644 index 00000000..5600c04e --- /dev/null +++ b/condemned.md @@ -0,0 +1,77 @@ +# Condemned material + +The catalog of **condemned self-material** — stale branches, `git stash` +entries, dead code and retired tests that a hygiene / `repo_cleanup` sweep is +95%-but-not-100% sure is trash. Symmetric to `parked.md`: `parked.md` holds work +that is *paused and will resume*; this file holds material that is *spent and +awaiting elimination*, recoverable right up until it is voided. + +This is the **index**; the payload is durable **git refs**, not markdown. Fragile +forms (local unmerged branches, stashes) are first materialised as real commits +and pushed under the archive namespace `refs/heads/archive/condemned/` +(a branch prefix — GitHub only accepts pushes to `refs/heads/*` and +`refs/tags/*`, so a custom `refs/archive/*` namespace is unpushable; filter with +`git branch --list 'archive/condemned/*'`) into **PyAutoGut** as the attic remote +— *before* the local copy is deleted. Recovery is a checkout. The organ (PyAutoGut) holds +and voids; the Brain hygiene conductor drives (decides what to condemn, triggers +a sweep), mirroring the Heart ↔ vitals template. See the decision: +`research/pyautobrain/pyautogut_organ_decision.md`. + +## Lifecycle + +1. **Condemn** — the hygiene `tidy` pass files an entry here (async, no + synchronous per-item gate). Fragile forms are archived to a durable ref + first; merged branches and committed deletions need only a SHA recorded. +2. **Transit** — the entry sits with a `sweep-after` date. Until then it is + recoverable (reabsorption): restore the branch/stash from its archive ref. +3. **Void** — a batch `sweep` runs the existing `repo_cleanup` safety gates + against entries past `sweep-after` and eliminates them; the entry moves out + of this file (to a voided log or is deleted). + +## Entry schema + +One `##` block per item. Fields: + +- `type` — `branch` | `stash` | `file` | `test` +- `locator` — the local name/path (e.g. `feature/old-thing`, + `stash@{2}`, `src/legacy/foo.py`) +- `confidence` — how sure it is trash (e.g. `0.95`) +- `reason` — why it is condemned +- `merged` — `yes` | `no` (a merged branch is reachable from `main` forever → + skips the pen; near-zero risk) +- `condemned` — date filed (YYYY-MM-DD) +- `sweep-after` — earliest date it may be voided (the transit clock) +- `breaks-if-wrong` — what is lost if this was a false positive (informs the + gate) +- `archive-ref` — the durable ref + SHA to recover from + (`refs/heads/archive/condemned/` @ ``), or `n/a` for a merged branch / + committed deletion whose bytes live in remote history (record the pre-delete + SHA instead) + +### Recoverability is not uniform + +- **Merged branches** — reachable from `main` forever; `archive-ref: n/a`, a note + is enough. The conductor recommends these straight to deletion without staging. +- **Committed code / test deletions** — the old bytes live in remote history; + record only the pre-delete SHA. +- **Local-only unmerged branches / stashes** — exist in one machine's reflog and + are gc-pruned. These **must** be materialised as an archive ref before deletion; + a manifest that merely *points* at a stash is worthless the moment it is dropped. + + + + diff --git a/feature/pyautobrain/hygiene_pyautogut_drive_seam.md b/feature/pyautobrain/hygiene_pyautogut_drive_seam.md new file mode 100644 index 00000000..0ff9e8ab --- /dev/null +++ b/feature/pyautobrain/hygiene_pyautogut_drive_seam.md @@ -0,0 +1,42 @@ +# Add the hygiene → PyAutoGut drive seam + +Type: feature +Target: PyAutoBrain +Repos: +- PyAutoBrain +- PyAutoGut +- PyAutoMind +Difficulty: medium +Autonomy: supervised +Priority: normal +Status: formalised + +Add the drive seam that lets the hygiene conductor use **@PyAutoGut** — the +second build follow-up from `research/pyautobrain/pyautogut_organ_decision.md`. +Depends on the repo skeleton (`feature/pyautogut/repo_skeleton.md`) existing +first. + +The seam mirrors the **Heart ↔ vitals** template exactly: the organ *holds and +voids*; the @PyAutoBrain hygiene conductor *drives* it (decides what to condemn, +triggers a sweep) and owns none of the storage. + +- **PyAutoGut-aware `tidy` mode.** Instead of the synchronous, one-item-at-a-time + `repo_cleanup` interrogation (the decision doc's pain #1 — decision fatigue at + the point of least context), `tidy` *files candidates into `condemned.md`* + asynchronously, with no per-item gate. This gives the 95%-confident-but-not- + certain items a home (pain #2) and captures the fragile forms' bytes as durable + archive refs before deletion (pain #3). +- **Batch `sweep` mode.** Runs the *existing* `repo_cleanup` safety gates + (`yes, force delete `; stash keep/apply/drop) in batch against the + manifest, at a time the user chooses — the transit-window clock: items with a + past `sweep-after` date are voided; anything still wanted is reabsorbed + (recovered) before then. + +No second gate implementation — reuse `repo_cleanup`'s gates. The conductor +reasons and delegates; @PyAutoGut performs the actual deletion (elimination is a +gut function). + + diff --git a/feature/pyautogut/repo_skeleton.md b/feature/pyautogut/repo_skeleton.md new file mode 100644 index 00000000..c0cc15a4 --- /dev/null +++ b/feature/pyautogut/repo_skeleton.md @@ -0,0 +1,54 @@ +# Stand up the PyAutoGut repo skeleton + +Type: feature +Target: PyAutoGut +Repos: +- PyAutoGut +- PyAutoMind +- PyAutoBrain +Difficulty: medium +Autonomy: supervised +Priority: normal +Status: formalised + +Stand up **@PyAutoGut**, the new peer organ repo that owns the lifecycle of +*condemned self-material* — decided in +`research/pyautobrain/pyautogut_organ_decision.md`. This is the first of that +decision's two build follow-ups (the Brain-side drive seam is the sibling +`feature/pyautobrain/hygiene_pyautogut_drive_seam.md`). + +Scope — the storage substrate only (organ holds + voids; the reasoning stays in +the Brain conductor): + +- **Attic remote + archive-ref convention.** Fragile forms (local unmerged + branches, `git stash` entries) are materialised as real commits and pushed + under an archive namespace — `refs/archive/condemned/` — which stays out + of `git branch -a`, into PyAutoGut as the attic remote, *before* the local + copy is deleted. Recovery is a checkout; a stash becomes a branch/commit via + `git stash branch` or a tagged stash commit. +- **The `condemned.md` manifest schema** (lands in @PyAutoMind, symmetric to + `parked.md`): one entry per item — `type` (branch/stash/file/test), `locator`, + `confidence`, `reason`, `merged?`, `condemned` date, `sweep-after` date, + `breaks-if-wrong`, and the archive ref/SHA to recover from. The `.md` is the + index; the git refs are the payload. Merged branches skip the pen (reachable + from `main` forever); committed code/test deletions need only the pre-delete + SHA recorded. +- **Register PyAutoGut as a peer organ**: add it to @PyAutoMind `repos.yaml` and + to @PyAutoBrain `ORGANISM.md` (then `python3 scripts/repos_sync.py --write`), + as a body organ peer to Heart/Memory/Hands — the storage mirror of Memory + (Memory keeps; Gut sheds, recoverable until voided). + +Boundaries to settle in PyAutoGut's `AGENTS.md` (from the decision doc): vs +Immune/`bug` (self+spent, not foreign+pathological), vs the hygiene conductor +(Heart↔vitals template — the conductor drives, the organ stores/voids), vs +Memory (retention vs release), vs Heart/profiling (no verdict, no compute +measure). + +Note: creating the GitHub repo itself is a human-required step; the rest of the +skeleton (conventions, manifest schema, doctrine wiring) is the supervised work. + + diff --git a/ideas.md b/ideas.md index 10806b5a..adab56d8 100644 --- a/ideas.md +++ b/ideas.md @@ -26,3 +26,5 @@ - [from: PyAutoBuild/to_do_list] Workspace tagging. - [from: PyAutoBuild/to_do_list] Remove annoying report.log and root.log once and for all. - [from: pyautoscientist-3b-smoke, 2026-07-10] Extend spawn --stamp-family to stamp the smoke thin-caller workflow + a starter smoke_install.sh into the template family (spec-gated on the reusable smoke workflow, which is now live). +- [formalised -> feature/pyautogut/repo_skeleton.md] [from: research pyautogut-organ-decision · research/pyautobrain/pyautogut_organ_decision.md] Stand up the PyAutoGut repo skeleton — the new peer organ repo owning condemned self-material: the attic remote, the `refs/archive/condemned/` archive-ref convention (stays out of `git branch -a`), and the `condemned.md` Mind manifest schema (type/locator/confidence/reason/merged?/condemned/sweep-after/breaks-if-wrong/archive-ref+SHA). Work-type feature/pyautogut; also adds PyAutoGut to repos.yaml + ORGANISM.md as a peer organ. +- [formalised -> feature/pyautobrain/hygiene_pyautogut_drive_seam.md] [from: research pyautogut-organ-decision · research/pyautobrain/pyautogut_organ_decision.md] Add the hygiene→PyAutoGut drive seam in the Brain — a PyAutoGut-aware hygiene `tidy` mode that files condemned candidates into `condemned.md` async (no synchronous per-item gate, replacing the mid-sweep repo_cleanup interrogation), plus a batch `sweep` mode that runs the existing repo_cleanup safety gates against the manifest at a user-chosen time. Mirrors the Heart↔vitals template: the organ holds+voids, the conductor drives. Work-type feature/pyautobrain. diff --git a/repos.yaml b/repos.yaml index ade77fbb..6d4bd366 100644 --- a/repos.yaml +++ b/repos.yaml @@ -72,6 +72,11 @@ repos: category: organ organ: Memory role: "Long-term scientific/software/project knowledge (see science pointer below)." + PyAutoGut: + github: PyAutoLabs/PyAutoGut + category: organ + organ: Gut + role: "Owns the lifecycle of condemned self-material (stale branches, stashes, dead code/tests): holds it as durable, recoverable git refs through a transit window and voids it on a sweep. The storage mirror of Memory (retention vs release)." # --- scientific libraries ---------------------------------------------- PyAutoConf: diff --git a/research/pyautobrain/pyautogut_organ_decision.md b/research/pyautobrain/pyautogut_organ_decision.md index cff059a8..65761861 100644 --- a/research/pyautobrain/pyautogut_organ_decision.md +++ b/research/pyautobrain/pyautogut_organ_decision.md @@ -96,10 +96,19 @@ and ecosystem-scale answers converge on one place. - **Payload = durable git refs, never markdown.** Fragile forms (local unmerged branches, stashes) are first materialised as real commits on a remote — pushed - under an archive namespace (e.g. `refs/archive/condemned/`, which stays - out of `git branch -a`) into PyAutoGut as the attic remote — *before* the + under an archive namespace into PyAutoGut as the attic remote — *before* the local copy is deleted. Recovery is a checkout. A stash becomes a branch/commit via `git stash branch` or a tagged stash commit. + + - **Catalog = a manifest in the Mind** (`condemned.md`, symmetric to `parked.md`): one entry per item — `type` (branch/stash/file/test), `locator`, `confidence`, `reason`, `merged?`, `condemned` date, `sweep-after` date,