diff --git a/AGENTS.md b/AGENTS.md index 3e8e374e..f827a54f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,10 +36,11 @@ For the full workflow narrative, conventions, and registry schemas, read numerical order. `scripts/lifecycle.py` owns the moves and drift-checks them. - Meta folders are **not** lifecycle states and keep their own names: - `z_features/` (multi-task epic trackers), `z_vault/` (deferred prompts — the - former `shelved/` merged here), and `autoprompt/` (prompts about this repo's - own infrastructure). + Retired non-record material lives in **`complete/archive/`** (skipped by + `lifecycle.py check`/`index`): `archive/epics/` (former `z_features/` + multi-task trackers) and `archive/shelved/` (former `z_vault/` deferred + prompts + dev notes). The old `z_features/`, `z_vault/` and `autoprompt/` + top-level folders were retired here on 2026-07-13. - **Registry** — root-level markdown files, each with one job: `active.md` (in-flight tasks), `planned.md` (scoped, not started), `complete.md` (shipped), `parked.md` (started but not in flight), `queue.md` (ordered @@ -64,11 +65,10 @@ For the full workflow narrative, conventions, and registry schemas, read ## Hard rules 1. **Never rewrite history on any branch with a remote.** No `git init` over an - existing repo, no `git push --force` to `main`. The 2026-04-27 drift incident - that motivated `autoprompt/03_history_rewrite_guard.md` is the reason. + existing repo, no `git push --force` to `main`. (Motivated by the 2026-04-27 + drift incident.) 2. **Pull before edit.** `git fetch && git status` first, every time. If behind - `origin/main`, `git pull --ff-only` before touching anything. See - `autoprompt/04_source_of_truth_rule.md`. + `origin/main`, `git pull --ff-only` before touching anything. 3. **One prompt = one task = one PR.** If a prompt outlines multiple loosely-related changes, split into separate prompt files before issuing. 4. **`tmp/` is scratch.** Never commit anything under it. diff --git a/REFERENCE.md b/REFERENCE.md index 215f9c3f..97c512fb 100644 --- a/REFERENCE.md +++ b/REFERENCE.md @@ -163,14 +163,10 @@ PyAutoMind/ │ ├── AGENTS.md ← archive schema + how to look records up │ └── 2026/07/.md ← bucketed by completion date (zero-padded months) │ -│ LIFECYCLE / META — not work-types; keep their own names. -├── z_features/ ← multi-task epic trackers (one tracker → many sub-prompts) -│ └── complete/ ← archived trackers (all sub-prompts shipped) -│ -├── z_vault/ ← deferred prompts (z_ prefix sorts last in listings) - -│ -├── autoprompt/ ← prompts about THIS repo's own infrastructure (meta) +│ (complete/archive/ holds retired non-record material — see below) +├── complete/archive/ ← skipped by lifecycle.py check/index +│ ├── epics/ ← retired multi-task epic trackers (former z_features/) +│ └── shelved/ ← deferred prompts + dev notes (former z_vault/) │ ├── scripts/ │ ├── status.sh ← prompt inventory helper @@ -249,9 +245,10 @@ experiment/autoarray/jax_sparse_mapping.md ### Not work-types -`active/`, `complete/`, `z_features/`, `z_vault/` are **workflow lifecycle** -folders, and `autoprompt/` holds **meta** prompts about this repo's own -infrastructure. They keep their own names and are not routed by work type. +`active/` and `complete/` are **workflow lifecycle** folders, not routed by work +type. `complete/archive/` holds retired non-record material — `epics/` (former +`z_features/` trackers) and `shelved/` (former `z_vault/` deferred prompts + dev +notes) — and is skipped by `lifecycle.py check`/`index`. ### Migration note @@ -351,47 +348,13 @@ Each task is an H2 section: Long-form description of what landed, gotchas, follow-ups. ``` -### `z_features/` (multi-task epics) - -`z_features/` holds **umbrella trackers** for multi-task epics — single -markdown files listing a sequence of sub-prompts that ship as their own PRs -under `autofit/`, `autogalaxy/`, etc. The tracker itself never becomes an -issue; only its sub-prompts do. - -``` -z_features/ -├── latent_refactor.md ← tracker (lists sub-prompt links) -├── ellipse_fitting_jax.md -├── ... -└── complete/ ← archived trackers (all sub-prompts shipped) -``` +### Epic trackers (retired 2026-07-13) -Use this pattern when a single ask decomposes into 5+ dependent sub-tasks. -`/start_dev z_features/.md` runs in **audit-only mode** — it reports -which sub-prompts are not-yet-issued / in-flight / shipped, and offers to -move the tracker to `z_features/complete/` once everything has landed. - -**Naming convention for clean audit:** the audit derives task-name -candidates from each sub-prompt's `active/` filename stem with `_`→`-`. For -the audit to auto-match against `complete.md` headings, **the task slug in -`active.md` / `complete.md` must equal the issued filename's stem after -that transform**. - -| Issued filename | Task slug that matches | Task slug that does NOT match | -|---|---|---| -| `active/latent_module_autogalaxy.md` | `latent-module-autogalaxy` ✓ | `latent-autogalaxy-module` ✗ | -| `active/latent_smoke_test.md` | `latent-smoke-test` ✓ | `smoke-test-latent` ✗ | -| `active/latent_variables_tutorial_expand_autofit.md` | `latent-variables-tutorial-expand-autofit` ✓ | `latent-tutorial-autofit` ✗ | - -The third row is the trap — if `/start_dev` renames the prompt on move -(e.g. appends a repo suffix for disambiguation) and `active.md`'s task slug -diverges from the issued stem, the audit will report the sub-prompt as -"in flight" forever and never archive the tracker. The cure is to either: - -- Pick the task slug at `/start_dev` time to match the eventual issued - filename stem, or -- Manually archive the tracker (`mv z_features/.md z_features/complete/` - + `prompt_sync_push`) when you know it's all shipped. +Multi-task **epic trackers** (umbrella markdown files listing a sequence of +sub-prompts) formerly lived in `z_features/`. That folder was retired into +`complete/archive/epics/` once the `draft/ → active/ → complete/` lifecycle made +its `z_`-prefixed home redundant. The per-task completion records live in +`complete///`; the archived trackers keep the epic-level narrative. --- @@ -404,7 +367,7 @@ bash scripts/status.sh ``` Prints counts per category, lists the active and recently-completed tasks, and -flags anything in `z_vault/` that's been sitting for a while. +and lists the recently-completed tasks. ### From inside Claude Code diff --git a/ROUTING.md b/ROUTING.md index b4ca4950..d070608d 100644 --- a/ROUTING.md +++ b/ROUTING.md @@ -62,6 +62,6 @@ commands; PyAutoBrain performs the routing.* Bodies + the boundary live in ## Not routed by work type -`active/`, `complete/`, `z_features/`, `z_vault/` are workflow-lifecycle -folders; `autoprompt/` holds meta prompts about this repo's own infrastructure. -None of these are work-type folders and PyAutoBrain does not route them. +`active/` and `complete/` are workflow-lifecycle folders (with +`complete/archive/` for retired epic trackers + shelved prompts). None of these +are work-type folders and PyAutoBrain does not route them. diff --git a/autoprompt/README.md b/autoprompt/README.md deleted file mode 100644 index 9f51e452..00000000 --- a/autoprompt/README.md +++ /dev/null @@ -1,70 +0,0 @@ -# autoprompt/ - -Workflow-infrastructure prompts drafted on 2026-04-27 after a forensic -sweep found local checkouts up to 101 commits behind origin. The eight -prompts addressed root causes structurally — visibility, gitignore noise, -history-rewrite guards, source-of-truth rules, sync tooling, repo -audits, worktree-only enforcement, and persistent test/build summaries. - -This directory now contains only this README. The shipped prompts live -in [`../issued/`](../issued/) (per-prompt `_.md`); the rejected -ones are gone. - -## Outcomes - -| # | Prompt | Outcome | Implementation | -|---|---|---|---| -| 01 | `pyauto-status` shell function | Shipped | [issued/01_status_dashboard.md](../issued/01_status_dashboard.md) — `scripts/pyauto_status.sh` | -| 02 | `.gitignore` workspace artifacts | Shipped | [issued/02_gitignore_noise.md](../issued/02_gitignore_noise.md) — 8 workspace PRs | -| 03 | "Never rewrite history" rule | Shipped | [issued/03_history_rewrite_guard.md](../issued/03_history_rewrite_guard.md) — 17 repos × CLAUDE.md/AGENTS.md | -| 04 | "Pull before edit" rule | **Skipped** | Redundant with 01 (BEHIND counts) + 03 (history guard) | -| 05 | `/sync` slash command | Shipped (re-scoped) | [issued/05_sync_slash_command.md](../issued/05_sync_slash_command.md) — dashboard's "Follow-up commands:" section instead of a heavyweight skill | -| 06 | Monthly repo-health audit | Shipped (re-scoped) | [issued/06_repo_health_audit.md](../issued/06_repo_health_audit.md) — `scripts/pyauto_audit.sh` (on-demand `pyauto-audit`, no cron) | -| 07 | Worktree-only edits enforcement | **Skipped** | Doc-rule layer wasn't worth 17 PRs; shell hook + `/sync` reset depended on rejected pieces | -| 08 | Persistent test/build summary | Shipped | [issued/08_test_summary.md](../issued/08_test_summary.md) — dashboard "Smoke tests:" + "Last autobuild run:" sections | - -## What the sweep actually fixed - -- **Drift visibility.** `pyauto-status` runs on every venv activation and - prints branch / upstream / behind / ahead / dirty counts plus the - `b` flag for forgotten feature branches. Drift can no longer hide. -- **Generated noise.** Workspaces' `.gitignore` files were rationalised - (prompt 02), so `git status` shows real divergence instead of pyc - pollution and stray artifacts. -- **History-rewrite guard.** Every PyAuto repo's `CLAUDE.md` / - `AGENTS.md` documents the forbidden ops (`rm -rf .git && git init`, - `Initial commit` resets, force-push to main, etc.). Catches the - specific pattern that caused ~40 redundant local commits. -- **Actionable dashboard.** Beyond the table, `pyauto-status` prints - copy-pasteable follow-up commands grouped by category (Pull / - Set missing upstream / Investigate manually) — drift recovery is - now one paste away. -- **Structural audit.** `pyauto-audit` finds non-git directories under - `~/Code/PyAutoLabs/`, stashes >14 days old, and abandoned local-only - branches (>30 days). Run on demand. -- **Test + release status.** Dashboard now reads - `~/.cache/pyauto/smoke/.json` (written by the - `/smoke-test` skill) and PyAutoBuild's committed `test_results/` to - show colored smoke counts and the latest autobuild aggregate on - every venv activation. - -## What the sweep deliberately didn't do - -- Doc rules in CLAUDE.md repeating things the dashboard already - surfaces (prompt 04). -- A heavyweight `/sync` slash command with stash-handling and - duplicate-commit detection (prompt 05's full spec — replaced by - copy-pasteable commands in the dashboard). -- A monthly cron schedule for the audit (prompt 06's full spec — the - audit is on-demand only). -- Read-only-mirror enforcement of canonical checkouts via shell hooks - or `/sync` resets (prompt 07 entirely). - -## Reading order - -If you want the historical narrative, read the shipped prompts in -numeric order in [`../issued/`](../issued/) — each preserves its -2026-04-27 framing, including its own caveat about being drafted from -a stale repo state. Re-evaluate before reusing as a template; the -cheap habits (pull before edit, never rewrite history) bought most of -the win. diff --git a/complete/archive/README.md b/complete/archive/README.md new file mode 100644 index 00000000..92265712 --- /dev/null +++ b/complete/archive/README.md @@ -0,0 +1,16 @@ +# complete/archive/ — retired non-record material + +This holds material that isn't a **dated task record** (those live in +`complete///` and pair 1:1 with `complete.md`). `lifecycle.py` +`check` and `index` deliberately **skip** this directory. + +- **`epics/`** — retired multi-task **epic trackers** (formerly `z_features/`). + Each tracked a series of related tasks; the per-task completion records live + in `complete///`. Kept for the epic-level narrative. +- **`shelved/`** — **deferred / shelved** prompts and dev notes (formerly + `z_vault/`). Not shipped; parked here rather than lost. Pull one back into + `draft///` if you decide to action it. + +The `z_features/` and `z_vault/` top-level folders were retired here (2026-07-13) +once the `draft/ → active/ → complete/` lifecycle (issue #71) made them +redundant. diff --git a/z_features/agents_md_standardization.md b/complete/archive/epics/agents_md_standardization.md similarity index 100% rename from z_features/agents_md_standardization.md rename to complete/archive/epics/agents_md_standardization.md diff --git a/z_features/complete/analysis_shared_state.md b/complete/archive/epics/analysis_shared_state.md similarity index 100% rename from z_features/complete/analysis_shared_state.md rename to complete/archive/epics/analysis_shared_state.md diff --git a/z_features/complete/autogalaxy_workspace_test_parity.md b/complete/archive/epics/autogalaxy_workspace_test_parity.md similarity index 100% rename from z_features/complete/autogalaxy_workspace_test_parity.md rename to complete/archive/epics/autogalaxy_workspace_test_parity.md diff --git a/z_features/complete/autolens_profiling.md b/complete/archive/epics/autolens_profiling.md similarity index 100% rename from z_features/complete/autolens_profiling.md rename to complete/archive/epics/autolens_profiling.md diff --git a/z_features/autolens_workspace_developer.md b/complete/archive/epics/autolens_workspace_developer.md similarity index 100% rename from z_features/autolens_workspace_developer.md rename to complete/archive/epics/autolens_workspace_developer.md diff --git a/z_features/cluster_lensing.md b/complete/archive/epics/cluster_lensing.md similarity index 100% rename from z_features/cluster_lensing.md rename to complete/archive/epics/cluster_lensing.md diff --git a/z_features/codex_skill_wrappers.md b/complete/archive/epics/codex_skill_wrappers.md similarity index 100% rename from z_features/codex_skill_wrappers.md rename to complete/archive/epics/codex_skill_wrappers.md diff --git a/z_features/complete/ellipse_fitting_jax.md b/complete/archive/epics/ellipse_fitting_jax.md similarity index 100% rename from z_features/complete/ellipse_fitting_jax.md rename to complete/archive/epics/ellipse_fitting_jax.md diff --git a/z_features/ep_concr.md b/complete/archive/epics/ep_concr.md similarity index 100% rename from z_features/ep_concr.md rename to complete/archive/epics/ep_concr.md diff --git a/z_features/complete/fast_visualization.md b/complete/archive/epics/fast_visualization.md similarity index 100% rename from z_features/complete/fast_visualization.md rename to complete/archive/epics/fast_visualization.md diff --git a/z_features/complete/group_lensing_workspace.md b/complete/archive/epics/group_lensing_workspace.md similarity index 100% rename from z_features/complete/group_lensing_workspace.md rename to complete/archive/epics/group_lensing_workspace.md diff --git a/z_features/complete/interferometer_lensing_workspace.md b/complete/archive/epics/interferometer_lensing_workspace.md similarity index 100% rename from z_features/complete/interferometer_lensing_workspace.md rename to complete/archive/epics/interferometer_lensing_workspace.md diff --git a/z_features/jax_substructure_simulator.md b/complete/archive/epics/jax_substructure_simulator.md similarity index 100% rename from z_features/jax_substructure_simulator.md rename to complete/archive/epics/jax_substructure_simulator.md diff --git a/z_features/complete/jax_user_intro.md b/complete/archive/epics/jax_user_intro.md similarity index 100% rename from z_features/complete/jax_user_intro.md rename to complete/archive/epics/jax_user_intro.md diff --git a/z_features/complete/jax_visualization.md b/complete/archive/epics/jax_visualization.md similarity index 100% rename from z_features/complete/jax_visualization.md rename to complete/archive/epics/jax_visualization.md diff --git a/z_features/complete/latent_refactor.md b/complete/archive/epics/latent_refactor.md similarity index 100% rename from z_features/complete/latent_refactor.md rename to complete/archive/epics/latent_refactor.md diff --git a/z_features/complete/mass_profiles_followup.md b/complete/archive/epics/mass_profiles_followup.md similarity index 100% rename from z_features/complete/mass_profiles_followup.md rename to complete/archive/epics/mass_profiles_followup.md diff --git a/z_features/complete/mass_profiles_refactor.md b/complete/archive/epics/mass_profiles_refactor.md similarity index 100% rename from z_features/complete/mass_profiles_refactor.md rename to complete/archive/epics/mass_profiles_refactor.md diff --git a/z_features/complete/nss_first_class_sampler.md b/complete/archive/epics/nss_first_class_sampler.md similarity index 100% rename from z_features/complete/nss_first_class_sampler.md rename to complete/archive/epics/nss_first_class_sampler.md diff --git a/z_features/complete/visualization_subprocess_feasibility.md b/complete/archive/epics/visualization_subprocess_feasibility.md similarity index 100% rename from z_features/complete/visualization_subprocess_feasibility.md rename to complete/archive/epics/visualization_subprocess_feasibility.md diff --git a/z_features/weak_shear.md b/complete/archive/epics/weak_shear.md similarity index 100% rename from z_features/weak_shear.md rename to complete/archive/epics/weak_shear.md diff --git a/z_vault/admin_dev_notes/README.md b/complete/archive/shelved/admin_dev_notes/README.md similarity index 100% rename from z_vault/admin_dev_notes/README.md rename to complete/archive/shelved/admin_dev_notes/README.md diff --git a/z_vault/admin_dev_notes/autofit.md b/complete/archive/shelved/admin_dev_notes/autofit.md similarity index 100% rename from z_vault/admin_dev_notes/autofit.md rename to complete/archive/shelved/admin_dev_notes/autofit.md diff --git a/z_vault/admin_dev_notes/autogalaxy.md b/complete/archive/shelved/admin_dev_notes/autogalaxy.md similarity index 100% rename from z_vault/admin_dev_notes/autogalaxy.md rename to complete/archive/shelved/admin_dev_notes/autogalaxy.md diff --git a/z_vault/admin_dev_notes/autolens.md b/complete/archive/shelved/admin_dev_notes/autolens.md similarity index 100% rename from z_vault/admin_dev_notes/autolens.md rename to complete/archive/shelved/admin_dev_notes/autolens.md diff --git a/z_vault/admin_dev_notes/build.md b/complete/archive/shelved/admin_dev_notes/build.md similarity index 100% rename from z_vault/admin_dev_notes/build.md rename to complete/archive/shelved/admin_dev_notes/build.md diff --git a/z_vault/admin_dev_notes/workspaces.md b/complete/archive/shelved/admin_dev_notes/workspaces.md similarity index 100% rename from z_vault/admin_dev_notes/workspaces.md rename to complete/archive/shelved/admin_dev_notes/workspaces.md diff --git a/z_vault/delaunay_jax_find_simplex_split.md b/complete/archive/shelved/delaunay_jax_find_simplex_split.md similarity index 100% rename from z_vault/delaunay_jax_find_simplex_split.md rename to complete/archive/shelved/delaunay_jax_find_simplex_split.md diff --git a/z_vault/galaxy_pytree_token.md b/complete/archive/shelved/galaxy_pytree_token.md similarity index 100% rename from z_vault/galaxy_pytree_token.md rename to complete/archive/shelved/galaxy_pytree_token.md diff --git a/z_vault/jax_visualization_inversion_blowup.md b/complete/archive/shelved/jax_visualization_inversion_blowup.md similarity index 100% rename from z_vault/jax_visualization_inversion_blowup.md rename to complete/archive/shelved/jax_visualization_inversion_blowup.md diff --git a/z_vault/test_mode_model.md b/complete/archive/shelved/test_mode_model.md similarity index 100% rename from z_vault/test_mode_model.md rename to complete/archive/shelved/test_mode_model.md diff --git a/autolens/restore_multiple_sources_lensing_of_lens.md b/draft/feature/autolens/restore_multiple_sources_lensing_of_lens.md similarity index 100% rename from autolens/restore_multiple_sources_lensing_of_lens.md rename to draft/feature/autolens/restore_multiple_sources_lensing_of_lens.md diff --git a/scripts/lifecycle.py b/scripts/lifecycle.py index e68872c8..cddda22b 100644 --- a/scripts/lifecycle.py +++ b/scripts/lifecycle.py @@ -53,6 +53,9 @@ ROOT = Path(__file__).resolve().parent.parent ACTIVE_DIR = ROOT / "active" COMPLETE_DIR = ROOT / "complete" +# complete/archive/ holds non-record material (retired epic trackers, shelved +# prompts) — NOT dated task records, so check/index skip it. +ARCHIVE_DIR = COMPLETE_DIR / "archive" DRAFT_DIR = ROOT / "draft" ACTIVE_MD = ROOT / "active.md" COMPLETE_MD = ROOT / "complete.md" @@ -365,7 +368,7 @@ def _all_records() -> "list[tuple[str, str, Path]]": return [] recs = [] for f in COMPLETE_DIR.rglob("*.md"): - if f.name in ("index.md", "AGENTS.md"): + if f.name in ("index.md", "AGENTS.md") or ARCHIVE_DIR in f.parents: continue bucket = "/".join(f.relative_to(COMPLETE_DIR).parts[:-1]) or "unknown" recs.append((bucket, f.stem, f)) @@ -461,7 +464,7 @@ def cmd_check(args) -> int: if COMPLETE_DIR.exists(): for f in COMPLETE_DIR.rglob("*.md"): - if f.name in ("index.md", "AGENTS.md"): + if f.name in ("index.md", "AGENTS.md") or ARCHIVE_DIR in f.parents: continue slug = f.stem if slug not in {safe_name(s) for s in c_slugs}: @@ -474,6 +477,8 @@ def cmd_check(args) -> int: if ACTIVE_DIR.exists() and COMPLETE_DIR.exists(): active_names = {f.name for f in ACTIVE_DIR.glob("*.md")} for f in COMPLETE_DIR.rglob("*.md"): + if ARCHIVE_DIR in f.parents: + continue if f.name in active_names: problems.append(f"file in both active/ and complete/: {f.name}") diff --git a/scripts/spawn.py b/scripts/spawn.py index 4af4ad99..209ba33a 100644 --- a/scripts/spawn.py +++ b/scripts/spawn.py @@ -57,10 +57,9 @@ ("draft/*", "SKELETON"), ("complete/AGENTS.md", "KEEP"), ("active/*", "DROP"), ("complete/*", "DROP"), - ("z_features/*", "DROP"), ("z_vault/*", "DROP"), - ("autoprompt/*", "DROP"), ("docs/*", "DROP"), - # Instance root docs + legacy pre-migration prompt dirs: - ("dashboard.md", "DROP"), ("overview.md", "DROP"), ("autolens/*", "DROP"), + ("docs/*", "DROP"), + # Instance root docs: + ("dashboard.md", "DROP"), ("overview.md", "DROP"), ("skills/*", "KEEP"), ("policy/*", "KEEP"), (".github/*", "KEEP_SUB"), # Agent-discovery symlinks are install artifacts (recreated by the diff --git a/scripts/status.sh b/scripts/status.sh index 9be76330..5d62310e 100755 --- a/scripts/status.sh +++ b/scripts/status.sh @@ -32,11 +32,11 @@ dim() { printf "\033[2m%s\033[0m\n" "$1"; } # active/ issued, in flight # complete/// shipped # Draft prompts are organised by WORK TYPE (feature/, bug/, …) under draft/. -# Meta folders (z_features/, z_vault/, autoprompt/) keep their own names. -# See README "Prompt taxonomy". +# See README "Prompt taxonomy". (The former z_features/ z_vault/ autoprompt/ +# meta folders were retired into complete/archive/ on 2026-07-13.) WORK_TYPES=(feature bug refactor docs test release maintenance research experiment triage) -LIFECYCLE_DIRS=(active complete z_features z_vault autoprompt) +LIFECYCLE_DIRS=(active complete) bold "== Draft prompts (by work type) ==" printf "%-35s %s\n" "category" "count"