punkshell/goals/AGENTS.md

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>

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
<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.
• 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)