Prompt-file lifecycle: draft/ active/ complete/ — structure + rewire (PR-A, #71)

AGENTS.md

@@ -20,16 +20,26 @@ For the full workflow narrative, conventions, and registry schemas, read
 
 ## Layout (operational)
 
-- **Prompts** — `<work-type>/<target>/<name>.md` (free-form markdown, one task
-  per file). The **first** folder is the *kind of work*; the **second** is the
-  *target repo or domain*. Work-types: `feature/`, `bug/`, `refactor/`, `docs/`,
-  `test/`, `release/`, `maintenance/`, `research/`, `experiment/` (plus `triage/`
-  for prompts whose classification is still unclear). PyAutoBrain routes by the
-  first folder — see [README.md](README.md) "Prompt taxonomy" and `ROUTING.md`.
-  Lifecycle/meta folders are **not** work-types and keep their own names:
-  `issued/` (routed prompts), `z_features/` (multi-task epic trackers),
-  `z_vault/` (deferred prompts — the former `shelved/` merged here), and
-  `autoprompt/` (prompts about this repo's own infrastructure).
+- **Prompt lifecycle (issue #71)** — a prompt file advances through three
+  top-level state folders, mirroring the task ledger:
+  - `draft/<work-type>/<target>/<name>.md` — intaken, **not started**. The
+    first folder under `draft/` is the *kind of work*; the second is the
+    *target repo or domain*. Work-types: `feature/`, `bug/`, `refactor/`,
+    `docs/`, `test/`, `release/`, `maintenance/`, `research/`, `experiment/`
+    (plus `triage/` for prompts whose classification is still unclear).
+    PyAutoBrain routes by the work-type folder — see [README.md](README.md)
+    "Prompt taxonomy" and `ROUTING.md`.
+  - `active/<name>.md` — **issued** (an open GitHub issue / in flight). The
+    ship skills advance the file to `complete/` on merge.
+  - `complete/<YYYY>/<MM>/<slug>.md` — **shipped**; the rich completion record
+    (see `complete/AGENTS.md`). Months are zero-padded so lexical order is
+    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).
 - **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
@@ -65,24 +75,25 @@ For the full workflow narrative, conventions, and registry schemas, read
 
 ## When you are asked to add a new prompt
 
-Write the file under `<work-type>/<target>/<name>.md` — pick the work-type from
-the list above (use `triage/` if genuinely unsure) and the target repo/domain as
-the second folder, e.g. `feature/autolens/potential_corrections.md` or
-`bug/autoarray/mask_edge_case.md`. Don't touch `active.md` or `issued/` directly
-— those are managed by `$start-dev` and `$create-issue` (`/start_dev` and
-`/create_issue` in Claude).
+Write the file under `draft/<work-type>/<target>/<name>.md` — pick the work-type
+from the list above (use `triage/` if genuinely unsure) and the target
+repo/domain as the second folder, e.g. `draft/feature/autolens/potential_corrections.md`
+or `draft/bug/autoarray/mask_edge_case.md`. Don't touch `active.md`, `active/`
+or `complete/` directly — those are managed by `$start-dev`, `$create-issue`
+and the ship skills (`/start_dev` and `/create_issue` in Claude).
 
 To skip the manual filing, run **`$intake`** (`/intake` in Claude), the
 PyAutoBrain Intake/Conception Agent. It classifies a raw idea into the right
-`<work-type>/<target>/` folder,
+`draft/<work-type>/<target>/` folder,
 writes the light header (incl. the optional `Difficulty:/Autonomy:/Priority:`
 keys — see README "Prompt file format"), and files the prompt for you. It files a
 prompt only; `$start-dev` (`/start_dev` in Claude) remains the separate next step.
 
 ## When you are asked to start work on an existing prompt
 
-Use `$start-dev <work-type>/<target>/<name>.md` (`/start_dev` in Claude). Older
-`<target>/<name>.md` paths from before the taxonomy migration still work. It
+Use `$start-dev draft/<work-type>/<target>/<name>.md` (`/start_dev` in Claude).
+Older `<work-type>/<target>/<name>.md` and bare `<target>/<name>.md` paths from
+before the lifecycle migration still resolve. It
 routes to `$start-library` or `$start-workspace` (`/start_library` or
 `/start_workspace` in Claude) based on the repos referenced in the prompt body;
 routing keys off `@RepoName` references in the content, not the folder.

README.md

@@ -16,15 +16,19 @@ What lives here:
 | File / folder | What it is |
 |---------------|------------|
 | `ideas.md` | raw incubating ideas, no structure required |
-| `<work-type>/<target>/*.md` | scoped prompts (`feature/`, `bug/`, `docs/`, …) |
-| `active.md`, `planned.md`, `complete.md` | the task registry: in flight, queued, done |
-| `issued/` | prompts that have become tracked issues |
+| `draft/<work-type>/<target>/*.md` | scoped prompts, **not started** (`feature/`, `bug/`, `docs/`, …) |
+| `active/<name>.md` | **issued** prompts — an open issue, in flight |
+| `complete/<YYYY>/<MM>/<slug>.md` | **shipped** — the rich completion record (`complete/AGENTS.md`) |
+| `active.md`, `planned.md`, `complete.md` | the task ledger: in flight, queued, done |
 | `repos.yaml` | the body map — the single source of repo identity |
-| `scripts/` | registry sync + drift checks (`repos_sync.py`) |
-
-A prompt flows: idea → prompt file → `/start_dev` → GitHub issue +
-`active.md` entry → worktree development → PR → `complete.md`. The registry
-is shared state, so any machine or session can pick up an in-flight task.
+| `scripts/` | registry sync + drift checks (`repos_sync.py`, `lifecycle.py`) |
+
+A prompt flows through three file states that mirror the ledger: idea →
+`draft/…` → `/start_dev` → GitHub issue + `active/` + `active.md` entry →
+worktree development → PR → merge → `complete/<YYYY>/<MM>/` +
+`complete.md`. `scripts/lifecycle.py` advances the file and drift-checks the
+invariant. The registry is shared state, so any machine or session can pick up
+an in-flight task.
 
 The schemas and conventions — prompt taxonomy, prompt file format, the
 `active.md` / `complete.md` schemas, epic trackers, bootstrap on a new

REFERENCE.md

@@ -88,12 +88,12 @@ fine — write naturally, the AI fills in the rest.
   idea               ── you write it in ideas.md
     │
     ▼
-  draft prompt       ── you write a markdown file under <work-type>/<target>/<name>.md
-    │
+  draft prompt       ── you write a markdown file under
+    │                   draft/<work-type>/<target>/<name>.md
     ▼
   /start_dev         ── reads the prompt, audits the code, drafts an issue,
     │                   creates the GitHub issue, registers the task in
-    │                   active.md, moves the prompt to issued/
+    │                   active.md, moves the prompt draft/ → active/
     ▼
   active.md entry    ── the task is now tracked across machines and sessions
     │
@@ -111,8 +111,9 @@ fine — write naturally, the AI fills in the rest.
   /ship_workspace
     │
     ▼
-  PR merged          ── post-merge cleanup deletes the worktree, removes the
-    │                   active.md entry, appends a summary to complete.md
+  PR merged          ── post-merge cleanup deletes the worktree, moves the
+    │                   active.md entry to complete.md, and advances the prompt
+    │                   file active/ → complete/<YYYY>/<MM>/ (lifecycle.py move)
     ▼
   done
 ```
@@ -144,28 +145,25 @@ PyAutoMind/
 
 ├── queue.md                 ← processing queue for /register_and_iterate
 │
-│   PROMPTS — organised by WORK TYPE (first folder), then TARGET (second folder).
+│   PROMPT-FILE LIFECYCLE (issue #71): draft/ → active/ → complete/YYYY/MM/.
+│   Drafts are organised by WORK TYPE (first folder), then TARGET (second).
 │   See "Prompt taxonomy" below and ROUTING.md.
-├── feature/                 ← new user-facing or scientific capabilities
-│   ├── autoarray/  autofit/  autogalaxy/  autolens/  autolens_assistant/  …
-│   ├── workspaces/          ← any *_workspace repo
-│   ├── pyautobrain/         ← prompts that implement PyAutoBrain agents
-│   ├── jax_substructure/  weak/  cluster/   ← numbered topic series (kept together)
-├── bug/                     ← incorrect behaviour, crashes, regressions
-│   ├── autofit/  autogalaxy/  autolens/  autoarray/  priors/  …
-├── refactor/                ← internal restructuring, no intended behaviour change
-├── docs/                    ← documentation, tutorials, notebooks, examples
-├── test/                    ← test coverage, smoke tests, validation scripts
-├── release/                 ← packaging, versions, deployment, release readiness
-├── maintenance/             ← dependency updates, hygiene, cleanup, small tech debt
-├── research/                ← exploratory scientific / algorithmic investigation
-├── experiment/              ← prototypes, spikes, proof-of-concept work
-├── triage/                  ← classification still unclear; needs manual review
+├── draft/                   ← NOT STARTED (intaken, pre /start_dev)
+│   ├── feature/             ← new user-facing or scientific capabilities
+│   │   ├── autoarray/  autofit/  autogalaxy/  autolens/  workspaces/  pyautobrain/  …
+│   ├── bug/                 ← incorrect behaviour, crashes, regressions
+│   ├── refactor/            ← internal restructuring, no intended behaviour change
+│   ├── docs/                ← documentation, tutorials, notebooks, examples
+│   ├── test/  release/  maintenance/  research/  experiment/
+│   └── triage/              ← classification still unclear; needs manual review
 │
-│   LIFECYCLE / META — not work-types; keep their own names.
-├── issued/                  ← prompts that have been routed via /start_dev
-│   └── autolens_workspace_developer/   ← per-target subdirs preserved
+├── active/                  ← ISSUED, in flight (moved here by /start_dev)
 │
+├── complete/                ← SHIPPED — rich completion records (see complete/AGENTS.md)
+│   ├── AGENTS.md            ← archive schema + how to look records up
+│   └── 2026/07/<slug>.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)
 │
@@ -176,6 +174,7 @@ PyAutoMind/
 │
 ├── scripts/
 │   ├── status.sh            ← prompt inventory helper
+│   ├── lifecycle.py         ← prompt-file lifecycle engine (move/split/check)
 │   └── prompt_sync.sh       ← commit/push helpers sourced by skills
 │
 └── skills/                  ← Mind-owned skills + the ownership audit
@@ -208,7 +207,8 @@ replaces a now-removed `admin_sync.sh` helper that formerly operated on
 PyAutoMind organises **intent by the kind of thinking required; PyAutoBrain uses
 that structure to choose the right reasoning agent.**
 
-Prompts live at `<work-type>/<target>/<name>.md`:
+Prompts start at `draft/<work-type>/<target>/<name>.md` (and advance
+`draft/ → active/ → complete/YYYY/MM/`; issue #71):
 
 - The **first folder** answers *what kind of thinking or agent is needed?* — the
   work type.
@@ -249,7 +249,7 @@ experiment/autoarray/jax_sparse_mapping.md
 
 ### Not work-types
 
-`issued/`, `z_features/`, `z_vault/` are **workflow lifecycle**
+`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.
 
@@ -372,16 +372,16 @@ 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 `issued/` filename stem with `_`→`-`. For
+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 |
 |---|---|---|
-| `issued/latent_module_autogalaxy.md` | `latent-module-autogalaxy` ✓ | `latent-autogalaxy-module` ✗ |
-| `issued/latent_smoke_test.md` | `latent-smoke-test` ✓ | `smoke-test-latent` ✗ |
-| `issued/latent_variables_tutorial_expand_autofit.md` | `latent-variables-tutorial-expand-autofit` ✓ | `latent-tutorial-autofit` ✗ |
+| `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
@@ -409,7 +409,7 @@ flags anything in `z_vault/` that's been sitting for a while.
 ### From inside Claude Code
 
 - `/health status` — dashboard of registry state (active, planned, recent complete; PyAutoHeart, via the `/health` door)
-- `/start_dev <work-type>/<target>/<name>.md` — read a prompt and route it (PyAutoBrain)
+- `/start_dev draft/<work-type>/<target>/<name>.md` — read a prompt and route it (PyAutoBrain)
 - `/worktree_status` — cross-references registry with task worktrees (PyAutoHeart)
 
 ---

ROUTING.md

@@ -10,9 +10,10 @@ maps that to a reasoning agent.
 
 ## The map
 
-Prompts live at `<work-type>/<target>/<name>.md`. The **work-type** (first folder)
-determines the agent; the **target** (second folder) tells the agent which repo or
-domain is affected.
+Draft prompts live at `draft/<work-type>/<target>/<name>.md`. The **work-type**
+(first folder under `draft/`) determines the agent; the **target** (second
+folder) tells the agent which repo or domain is affected. Once issued the file
+advances to `active/`, and on merge to `complete/<YYYY>/<MM>/` (issue #71).
 
 | Work-type folder | Intent | PyAutoBrain agent |
 |------------------|--------|-------------------|
@@ -61,6 +62,6 @@ commands; PyAutoBrain performs the routing.* Bodies + the boundary live in
 
 ## Not routed by work type
 
-`issued/`, `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/`, `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.