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>

Cross-references to other repos' goals

Mention another repo's goals WITHOUT the G- prefix - write "the omnisystems2026 repo's goal 001", never "G-001". The G-<id> token is reserved for this repo's own goals: goals_lint's reference warnings and goals_xref's link classification match G-\d+ literally, so a cross-repo mention registers as a false link or a dangling reference.

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/, this AGENTS.md, and xref.conf) 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). Informational, never fatal: warnings for stale references to archived goals lacking an achieved/archive marker, and for references to goal IDs present in neither index (dangling).

tclsh scriptlib/developer/goals_xref.tcl - advisory relationship analysis (plain tclsh, no dependencies; always exit 0). Cross-references the live goals against scope overlap: report lists UNLINKED overlap pairs (overlapping goals that never reference each other) plus ONE-DIRECTIONAL pairs (back-pointer candidates), with path/term evidence per pair; paths <p...> lists the goals whose Scope intersects the given repo paths (the instrument for the "read intersecting goals before editing" step in root GOALS.md and for drafting-time overlap surveys); score <G-id> shows one goal's overlap pairs classified linked/one-directional/unlinked; refs lists dangling references. Scoring is IDF-weighted so ubiquitous anchors count for little; it ranks lexical overlap honestly but cannot see purely conceptual relationships - treat its output as a survey aid, never a gate. Repo-specific scoring vocabularies (path roots, stop words, file extensions, reference-container damps, module dirs, bare-root anchoring) may be adjusted per repo via an optional goals/xref.conf (key list in the tool's header comment; a template ships at goals/xref.conf with every line disabled, so the compiled-in punkshell defaults apply unchanged).

Child DOX Index

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