# goals/

## Purpose

Holds optional detail prose for goals in the root `GOALS.md` index that need more than a one-line summary to state properly. The index entry is canonical; a detail file only elaborates and never contradicts its index entry.

## Ownership

- Files here are owned by the goal authoring workflow described in root `GOALS.md`.
- Only the user adds or edits goals. Agents may draft detail files for user review but must not invent goals.
- The root `GOALS.md` index entry is the source of truth. If index and detail disagree, the index wins; fix the detail.

## Local Contracts

### When a detail file is warranted

A goal earns a detail file when it has any of:
- Non-obvious rationale (rejected alternatives, constraints discovered, why it is not done the obvious way)
- Multi-phase plan with sub-acceptance criteria
- External references or prior art worth citing
- More than ~3 lines of prose to state properly

Simple goals with a clear one-liner and measurable acceptance stay index-only. Do not create empty detail files for completeness.

### Naming

`G-<id>-<slug>.md` — e.g. `G-007-bytecompiler.md`. The `<id>` is the stable reference (taken from the `G-<id>` in the root index); the slug is human-readable and may change without breaking links as long as the ID prefix is preserved. Sortable by `ls goals/`.

### Detail file structure (suggested)

```
# G-<id> <short title>

Status: <as in index>
Scope: <as in index>
Acceptance: <as in index>

## Context
<why this goal exists, what problem it solves>

## Approach
<chosen direction, key design decisions>

## Alternatives considered
- <alt A> — rejected because <reason>
- <alt B> — deferred, see G-NNN

## Notes
<implementation notes, references, links>
```

### Archive

- `goals/archive/` holds detail files for goals that have been achieved and moved to `GOALS-archive.md`.
- On archive: move `goals/G-<id>-<slug>.md` → `goals/archive/G-<id>-<slug>.md`. Do not rename the ID prefix.
- No orphan detail files: every file under `goals/` (excluding `archive/` and this `AGENTS.md`) must correspond to an `active` or `proposed` entry in the root `GOALS.md` index.

## Work Guidance

LF line endings (per root AGENTS.md user preferences).

## Verification

None — this folder is documentation only.

## Child DOX Index

- `archive/` — detail files for achieved/archived goals (no child AGENTS.md needed; this file's archive rules cover it)