# 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--.md` — e.g. `G-013-raw-mode-default.md`. The `` is the stable reference (taken from the `G-` 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- Status: Scope: Goal: Acceptance: ``` Header field grammar (lintable): each header field is one line carrying only its own content - never parenthetical narrative. `Status:` is exactly one of `proposed`, `active`, `abandoned`, `superseded`, or `achieved YYYY-MM-DD`. Verification evidence, design asides, and remaining manual items belong in body sections (`## Progress`, `## Notes`) - prose riding a header field is invisible to restructures that normalise those fields and gets silently dropped (root `AGENTS.md` "Doc Restructures"). Optional sections after the header, only when they have real content: ``` ## Context ## Approach ## Alternatives considered - — rejected because - — deferred, see G-NNN ## Notes ## Progress ``` ### 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--.md` → `goals/archive/G--.md` and the index entry moves to `GOALS-archive.md`. Do not rename the ID prefix. - At the achieved flip, record the verification evidence in the detail file body (`## Progress` or `## Notes`): what was verified, on which kits/runtimes, design outcomes worth keeping, and any remaining manual items. The `Status:` line itself carries only `achieved YYYY-MM-DD` (header field grammar above). - The archive move is content-identical: the file lands in `archive/` byte-for-byte as it left `goals/`, with the flip's content edits (Status line, evidence write-up) made before or after the move so the move diff is a pure rename (root `AGENTS.md` "Doc Restructures"). - Reference sweep at archive time: grep the live tier (`goals/*.md`, `GOALS.md`) for the archived goal's ID. (a) Rewrite pending-tense phrasing ("once G-x lands", "after G-x is achieved") to reflect achievement, with the archive path - e.g. "(G-x, achieved - see goals/archive/G-x-.md)". (b) For each note in the archived detail file carrying actionable content for a live goal (a follow-on, dependency detail, or design decision that goal will need), add a one-line pointer to that live goal's `## Notes`: "G-x (archived) recorded - see goals/archive/G-x-.md". Mentions that are pure history need nothing. Rationale: an archived file is no longer edited, so its forward-pointing insights must be pushed to their targets when it leaves the active set. These are non-contract Notes updates - no pre-approval needed, report in the completion summary. - 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 `tclsh scriptlib/developer/goals_lint.tcl` — run after editing goal files or either index. Validates the detail-file header grammar (including the bare-`Status:` rule), index/detail orphan rules in both tiers, and the Status/Scope mirror consistency (plain tclsh, no dependencies; exit 0 clean, exit 1 with one line per finding). ## Child DOX Index - `archive/` — detail files for achieved/archived goals (no child AGENTS.md needed; this file's archive rules cover it)