@ -231,4 +231,4 @@ The project version is fully independent of module versions. A module bump (even
- Runtime Tcl introspection DIRECTIVE for agents: to locate or characterize a Tcl command (definition site, calling interface, loaded module version, runtime body - including subcommand-chain resolution e.g `string is`), run `punk91 src script lib:developer/whatis ?-body? ?-doc? <command> ?subcommand?...` FIRST; to discover what a namespace/package exposes (before writing a new helper, or when starting work in a namespace), run `punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? <nsglob>...` FIRST. Reserve grep for full-text/source-pattern searches: this repo has several coexisting copies of many modules, and grep alone cannot tell you which copy is actually loaded. Both are single sub-1s side-effect-free invocations from the repo root (`punk91` lives in `bin/`; `lib:developer/<name>` = `scriptlib/developer/<name>.tcl`). Full usage and caveats: `.agents/skills/tcl-whatis/SKILL.md` and `.agents/skills/tcl-nslist/SKILL.md`.
- Tcl module authoring conventions live in `src/modules/AGENTS.md` and closer module child docs.
- If AGENTS.md conflicts with CLAUDE.md, AGENTS.md wins.
- Technical project goals live in root `GOALS.md` (summary index: ID, status, title, scope, detail pointer per goal) with the canonical Goal/Acceptance contract prose in `goals/G-<id>-<slug>.md` detail files - read the detail file of every goal whose scope intersects paths being edited. Goals are user-owned: agents add or edit goal contract elements (in either tier) only at the user's request, proposal-first (show the proposed wording, get explicit approval before writing - see the `GOALS.md` maintenance rules); never on their own initiative. Suggesting candidate goals when work surfaces something goal-worthy is welcome and encouraged - as a flagged proposal, not a file edit. Non-contract detail-file updates from user-directed work need only be reported in the completion summary. Agents auto-flip a goal to `achieved <date>` when its detail-file acceptance criterion is met as part of the DOX closeout pass - the flip includes archiving the entry to `GOALS-archive.md` and the detail file to `goals/archive/` - and must flag `proposed`→`active` transitions in their completion report for user confirmation. See `GOALS.md` for the full workflow, including how to author a new goal when asked.
- Technical project goals live in root `GOALS.md` (summary index: ID, status, title, scope, detail pointer per goal) with the canonical Goal/Acceptance contract prose in `goals/G-<id>-<slug>.md` detail files - read the detail file of every goal whose scope intersects paths being edited. Goals are user-owned: agents add or edit goal contract elements (in either tier) only at the user's request, proposal-first (show the proposed wording, get explicit approval before writing - see the `GOALS.md` maintenance rules); never on their own initiative. Suggesting candidate goals when work surfaces something goal-worthy is welcome and encouraged - as a flagged proposal, not a file edit. Non-contract detail-file updates from user-directed work need only be reported in the completion summary. Agents auto-flip a goal to `achieved <date>` when its detail-file acceptance criterion is met as part of the DOX closeout pass - the flip includes archiving the entry to `GOALS-archive.md` and the detail file to `goals/archive/`. `proposed` -> `active` flips follow the two-path rule in the `GOALS.md` maintenance rules: an explicit user instruction to activate (including "work on / implement G-<id>" for a proposed goal) is the confirmation - flip it as part of the work and report it; agents never activate on their own initiative, they flag the candidate instead. See `GOALS.md` for the full workflow, including how to author a new goal when asked.
Goals-system: v4 (canonical; the "Goals system versions" section below defines it)
Goals-system: v5 (canonical; the "Goals system versions" section below defines it)
This file is the canonical, harness-agnostic index of technical project goals for punkshell. It is referenced from the root `AGENTS.md` Child DOX Index and is a required read for any non-trivial work, so that agents can discover goals whose scope intersects their work. It is deliberately summary-only so that reading it in full stays cheap: each entry carries ID, status, title and Scope plus a detail-file pointer, and the goal's full contract prose (Goal statement and Acceptance criterion) lives in its detail file under `goals/` (see `goals/AGENTS.md`).
@ -45,7 +45,10 @@ Scope version references: files whose names carry a real stamped version drift a
- The goal contract spans both tiers: the index entry (title, status tag, Scope) and the detail file's `Goal:` and `Acceptance:` lines.
- Proposal-first: before writing a new goal or changing any contract element in either tier, show the user the proposed wording - the full entry plus detail-file header for a new goal, the changed clause(s) for an edit - and get explicit approval. If the user already supplied or approved the exact wording this session, apply it and report what was written.
- Exception (sanctioned autonomous edit): an agent whose work satisfies a goal's `Acceptance:` (judged against the detail file's criterion, never the index entry alone) must flip that goal to `achieved <date>` as part of its DOX closeout pass, archive it (entry to `GOALS-archive.md` per that file's format, detail file to `goals/archive/`), and report the flip in its completion summary. If the detail file carries a `## Progress` section, the flip additionally requires its remaining-work list to be resolved — empty, or each item verified satisfied; a partial increment never flips a goal. The flip records its verification evidence (what was verified, on which kits/runtimes, any remaining manual items) in the detail file's body — the `Status:` line stays bare `achieved <date>`, per the header field grammar in `goals/AGENTS.md`. The flip records the goal's deferred items as a `## Follow-ons` section of structured disposition lines (`goals/AGENTS.md` Follow-ons). The flip also includes a reference sweep of the live tier (see `goals/AGENTS.md` Archive rules): pending-tense mentions of the archived goal updated to reflect achievement, and any of its notes actionable for a live goal pointed to from that goal's `## Notes`. As part of the same sweep, run `goals_xref.tcl report`: UNLINKED pairs annotated with the archived goal's id under "shared archived refs" lose their only recorded bridge when it leaves the live tier - add a direct `Related:` pointer where the overlap is real (same non-contract Notes mechanism as the sweep).
- Agents must not flip `proposed` → `active`. They flag it in their completion report for the user to confirm. Activation freshness: the flagging agent re-runs the overlap survey (`goals_xref.tcl score G-<id>`) as part of the flag - goals drafted in the interval may overlap; relationships found are recorded as `Related:` Notes lines at activation (non-contract content, reported in the completion summary).
- Activation (`proposed` -> `active`) has exactly two paths:
- User-directed: an explicit user instruction to activate ("activate G-<id>", "activate and implement G-<id>"; an instruction to work on a proposed goal implies activation) IS the confirmation. The agent flips the status as part of the work and reports the flip in the completion summary - no re-asking, no proposal-first step, no deliberation about user ownership.
- Agent-initiated: forbidden. An agent never flips a goal to `active` on its own judgment, including to legitimize, scope, or unblock work it is already doing; it flags the candidate in its completion report for the user's decision.
Activation freshness (both paths): at activation the agent re-runs the overlap survey (`goals_xref.tcl score G-<id>`) - goals drafted in the interval may overlap; relationships found are recorded as `Related:` Notes lines at activation (non-contract content, reported in the completion summary).
- Index entries carry no progress: the status tag is the only state the index records. Incremental progress on an `active` goal (what landed, what remains) is recorded in the detail file's `## Progress` section, never as annotations on the index entry.
- Marking a goal `superseded by G-<id>` or `abandoned` includes a test sweep: search the tree (at minimum `src/tests`) for `G-<old id>` references and for the tests named in the goal's detail-file Acceptance, and record each affected test's disposition in the superseding goal's detail file (or the abandoned goal's own): pinned expectations that transfer to the new goal, pins that stand down to plain behaviour characterization, and any that lapse. The sweep never deletes, skips, or weakens a test on its own — that still requires explicit user direction per `src/tests/AGENTS.md`.
- Detail files may be updated without pre-approval when recording findings, decisions, or verification artifacts from work the user directed on that goal or its subject matter; report such updates in the completion summary. Edits to a detail file's `Goal:` or `Acceptance:` lines are contract changes and follow proposal-first.
@ -74,6 +77,7 @@ The front matter of every repo's GOALS.md declares which goals-system contract v
- v2 (2026-07-24): Scope elements are '; '-separated at top level (lint-enforced); cross-repo goal references drop the G- prefix; goals_xref.tcl gains repo-local configuration (goals/xref.conf - path roots, stop words, file extensions, reference containers, module dirs, bare_path_roots, prefix_anchors).
- v3 (2026-07-25): goals_lint.tcl gains the stale-versioned-reference warning (a live-tier reference to a version-suffixed filename that is missing while a same-stem sibling exists on disk is flagged with the sibling(s) named; archive tier, globs, URLs, absolute/out-of-repo paths and the magic dev version 999999.0a1.0 are exempt; informational, never fatal); Scope-authoring guidance added to the Format section (version-stamped files referenced by glob or magic-version filename, exact versions pinned only in dated prose); this bump-policy paragraph broadened from "contract or required tooling changes" to any interpretation-affecting change.
- v4 (2026-08-03): archived-goal follow-on tracking (drafted as G-159, achieved 2026-08-03 - see goals/archive/G-159-followon-disposition-tracking.md): archived detail files carry a `## Follow-ons` section of structured `Follow-on: <item> => <disposition>` lines (closed vocabulary: open, goal G-<id>, landed YYYY-MM-DD (<where>), declined YYYY-MM-DD (<why>)); disposition-only updates to archived detail files are sanctioned non-contract edits made in the same work unit that acts on a follow-on; the achieved flip records deferred items in the grammar (reference-sweep step (c)) and the authoring workflow flips an enacted follow-on's disposition to `goal G-<new id>`; goals_lint.tcl validates the grammar (malformed line or unknown goal reference = finding); new advisory tool goals_followons.tcl enumerates dispositions and flags archived files carrying follow-on vocabulary with no structured section.
- v5 (2026-08-07): activation rule restated as two named paths - user-directed (an explicit user instruction to activate, including "work on / implement G-<id>" for a proposed goal, IS the confirmation; the agent flips and reports, no re-asking or proposal-first step) vs agent-initiated (forbidden, including activation to legitimize work already in flight; flag the candidate in the completion report); the activation-freshness overlap survey now applies at any activation rather than only at flag time; root AGENTS.md goals bullet aligned. No status-vocabulary, grammar, or tooling change.
