# planning

Active work-in-progress. Content here is being actively decided or specified.
Nothing here is considered settled.

---

## Structure

```
planning/
├── decisions/       ← Architectural and technical decisions in progress
├── specs/           ← Feature specs being designed before implementation
└── reviews/         ← Code review campaigns
    ├── TRACKER.md   ← Master status table across all review batches
    └── findings/    ← One findings doc per completed batch
```

**`decisions/`** — Use for questions of architecture, tooling choice, or process that
need to be reasoned through before acting. Example: CI/CD pipeline design, repo
structure decisions, package strategy.

**`specs/`** — Use for feature specifications before implementation begins. Write a
spec here first, then implement in `architect-language-tools/`, then promote or discard.

**`reviews/`** — Use for structured code review campaigns. `TRACKER.md` is the
single source of truth for batch status. Each completed batch produces a findings
document in `findings/` recording issues by severity. Fixes are a separate step —
never mix review and implementation in the same session.

---

## The graduation rule

When work in `planning/` reaches a conclusion:

| Outcome | Action |
|---|---|
| Decision made / feature shipped | Promote the document to `ai-workspace/docs/` and delete it from here |
| Abandoned / superseded | Delete it — do not promote to `ai-workspace/` |
| Ongoing / multi-phase | Keep it here until all active phases are complete |

`CICD_ARCHITECTURE.md` is currently here because Phases 2–5 are still pending.
Once CI/CD integration is fully delivered, it graduates to `ai-workspace/docs/`.

---

## What does NOT belong here

- Throwaway session notes → use `tmp/` instead
- Stable reference material → that belongs in `ai-workspace/`
- Product documentation → that belongs in `architect-language-tools/dev-docs/`
