# goals/

## Purpose

Holds the per-goal detail files for the root `GOALS.md` index. Every goal has a detail file: it carries the goal's canonical contract prose (`Goal:` and `Acceptance:`) plus any supporting detail (context, approach, decisions, verification records). The index entry in root `GOALS.md` stays summary-only (ID, status, title, Scope, detail pointer).

## Ownership

- Files here are owned by the goal authoring workflow described in root `GOALS.md`.
- Goals are user-owned: agents add or edit goals only at the user's request or with explicit approval, proposal-first for any contract element (see the root `GOALS.md` maintenance rules). The contract spans both tiers: the index entry (title, status, Scope) and this folder's `Goal:`/`Acceptance:` lines. Agents must not write goals on their own initiative - suggesting candidate goals for user approval is welcome and encouraged.
- Non-contract content (Context, Approach, Alternatives, Notes, Progress, findings, decisions, verification artifacts) may be updated without pre-approval during user-directed work on the goal or its subject matter; report such updates in the completion summary.
- Canonicality split: a detail file is canonical for its `Goal:` and `Acceptance:`; the root index is canonical for ID, status, title and Scope. The `Status:`/`Scope:` lines here mirror the index - if they disagree, the index wins and the mirror here is fixed.

## Local Contracts

### One detail file per goal

Every entry in root `GOALS.md` has exactly one detail file here. A minimal detail file is just the header block below - do not pad it with empty sections; add Context/Approach/etc. only when there is real content.

### Naming

`G-<id>-<slug>.md` — e.g. `G-013-raw-mode-default.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

Required header (the first lines of every detail file):

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

Status: <as in index>
Scope: <as in index>
Goal: <canonical - outcome-focused statement of what done looks like>
Acceptance: <canonical measurable, verifiable pass/fail criterion>
```

Optional sections after the header, only when they have real content:

```
## 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, findings, verification records>

## Progress
<active goals worked incrementally: what landed (dated), what remains for acceptance>
```

### Progress tracking (active goals)

When user-directed work on an `active` goal lands without satisfying its `Acceptance:`, record it in the detail file's `## Progress` section: what landed (dated) and what remains for acceptance. Progress is non-contract content — updatable without pre-approval, reported in the completion summary. The achieved flip requires the remaining-work list to be resolved (empty, or each item verified satisfied); a partial increment never flips a goal. Increment numbering in commit messages is free-form and carries no contract meaning.

### Archive

- `goals/archive/` holds detail files for achieved goals. Archiving happens as part of the achieved flip (see the root `GOALS.md` maintenance rules): the detail file moves `goals/G-<id>-<slug>.md` → `goals/archive/G-<id>-<slug>.md` and the index entry moves to `GOALS-archive.md`. Do not rename the ID prefix.
- No orphan detail files: every file here (excluding `archive/` and this `AGENTS.md`) corresponds to a `proposed`, `active`, `abandoned` or `superseded` entry in root `GOALS.md`; every file under `archive/` corresponds to a record in `GOALS-archive.md`.

## 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)