punkshell/goals/G-159-followon-disposition-tracking.md

G-159 Trackable follow-on dispositions in archived goals

Status: active Scope: GOALS.md (goals-system v4 bump + maintenance/authoring rule updates); GOALS-archive.md (archive-edit exception wording); goals/AGENTS.md (Follow-on line grammar, sanctioned disposition edits, archive-sweep update); goals/archive/ (one-time retrofit sweep); scriptlib/developer/goals_lint.tcl (grammar validation); scriptlib/developer/goals_followons.tcl (new advisory report) Goal: Follow-ons recorded in archived goal detail files stay trackable instead of fossilizing: each is a structured line carrying a disposition from a closed vocabulary, the disposition is updated in the same work unit that acts on the follow-on (landing it directly or drafting a goal from it), and an advisory report enumerates open follow-ons and flags unstructured follow-on prose - so "which follow-ons have not been acted on" is answered by running a tool, not by archive archaeology. Acceptance: goals/AGENTS.md defines a lintable Follow-on line grammar for archived detail files with a closed disposition vocabulary covering at least open, became-goal, landed (dated), and declined (dated) - exact tokens and line shape settled in the work - and sanctions disposition-only updates to archived detail files as non-contract edits reported in completion summaries (GOALS-archive.md's do-not-edit rule stays for index records, reworded to name the carve-out); goals_lint validates the grammar - a malformed disposition token, or a disposition goal-reference to an ID present in neither index, is a finding - with existing checks unchanged; scriptlib/developer/goals_followons.tcl (plain tclsh, no dependencies, always exit 0, xref-style advisory) reports every structured follow-on with its archived-goal home and disposition, groups open items, and heuristically flags follow-on-vocabulary prose in goals/archive/ lacking a structured line; a one-time user-approved retrofit sweep (per the 2026-07-24 delimiter-normalisation precedent) converts existing goals/archive/ follow-on prose to structured lines whose dispositions reflect the live tier and landed work (e.g. the RT_VERSION follow-on parked in archived G-057 - goals/archive/G-057-kit-icon-embedding.md - resolves to its enacting live goal G-137), ambiguous items resolved with the user, and after it the report shows zero unresolved heuristic flags on the real archive (output recorded in this file); the archive-flip reference sweep and the goal-authoring workflow are amended so newly archived goals record follow-ons in the structured grammar and an agent acting on an archived follow-on (drafting its goal, or landing it directly at user direction) updates the disposition in the same work unit; the goals-system version bumps to v4 recording the convention so syncing repos port the delta.

Context

The archive-flip reference sweep (goals/AGENTS.md Archive rules) is one-directional and runs once: forward-pointing notes are pushed to live goals' Notes only if a target goal exists at flip time. Afterwards nothing flows back - the stated rationale is "an archived file is no longer edited, so its forward-pointing insights must be pushed to their targets when it leaves the active set". The result: a goal drafted later from an archived follow-on records the linkage only on the new goal's side (dependency-direction convention, back-pointers optional); a follow-on landed directly at user direction records nothing at all, and the archived prose keeps its pending tense ("candidate", "parked", "flagged") indefinitely.

Evidence (2026-08-03 audit): 30+ files under goals/archive/ carry follow-on vocabulary in uncontrolled forms. Back-pointers exist only where drafting coincided with the flip (archived G-122's flip-day note naming G-123, both since archived - goals/archive/G-122-host-target-platform-split.md; the same-day pair archived G-155 -> G-156). An acted-on-later case is discoverable only from the new goal's side (archived G-057's parked RT_VERSION follow-on became live G-137). An apparently-open case: archived G-062's LICENSE.txt layout-seeding follow-on was pushed to G-012's Notes at flip, G-012 has since archived too, and no live goal covers it.

Tooling gap: goals_lint's pending-tense warning covers live-tier references only; goals_xref analyzes live-goal overlap only; nothing reads archive-tier prose.

Approach

• Grammar (candidate, settled in the work): structured lines gathered under a per-file ## Follow-ons section in archived detail files, one line per item: Follow-on: <one-line item> => open | => goal G-<id> | => landed <YYYY-MM-DD> (<where>) | => declined <YYYY-MM-DD> (<why>). Constraints: line-anchored, greppable, closed token vocabulary, lintable without a parser.
• Tool split: deterministic grammar validation goes in goals_lint; the heuristic vocabulary detector (prose saying follow-on/parked/flagged/candidate with no structured line) lives in goals_followons.tcl. Heuristics stay advisory; lint stays crisp.
• Sanctioned-edit carve: goals/AGENTS.md archive rules gain "disposition updates to Follow-on lines are non-contract edits to archived detail files, made in the same work unit that acts on the follow-on, reported in the completion summary"; the "no longer edited" rationale sentence is narrowed accordingly. GOALS-archive.md's index-record rule is unchanged in substance.
• Duty wiring: (a) the archive-flip sweep emits Follow-on lines in the grammar (the flip already writes evidence into the body); (b) the authoring workflow's overlap-survey step gains: a draft enacting an archived follow-on flips that line to goal G-<new> in the same change-set; (c) direct landings at user direction flip to landed.
• Retrofit method: vocabulary grep over goals/archive/ -> per-item classification against the live tier and GOALS-archive.md (CHANGELOG where needed) -> proposed disposition list shown to the user in batches -> applied. One-time restructure under explicit approval.

Alternatives considered

• Record linkage only on the acting goal's side (never touch archive) - rejected: directly-landed follow-ons stay invisible and enumeration still requires archaeology; that is exactly today's state.
• Central FOLLOWONS.md ledger - rejected: duplicates archived content away from its context and drifts; the detail file is where a reader meets the follow-on.
• goals_xref subcommand instead of a new script - deferred to the work: a separate script matches the one-concern-per-tool precedent (lint/xref), but a subcommand home is acceptable if sharing the scanning plumbing wins.

Notes

• Overlap survey (2026-08-03): goals_xref.tcl paths GOALS.md GOALS-archive.md goals scriptlib/developer - no live goal intersects GOALS.md, GOALS-archive.md, or goals/; scriptlib/developer surfaced G-069 and G-156; the unlinked-pair report was reviewed, none touch this territory.
• Related: G-156 - two-way touchpoint: its census records each derived project's seeded goals-system version (this goal's v4 bump becomes measurable drift in that census), and its scanner is sibling developer tooling under scriptlib/developer. Deliberate non-overlap: G-069 shares only the scriptlib/developer script-home precedent (its subject is punk::args splitting, not the goals system).
• The v4 delta reaches repos carrying seeded GOALS systems (e.g. the serversecretsync project) via the existing declared-version delta-porting mechanism - no extra machinery in this goal.
• Origin: gap identified 2026-08-03 during a conversation-level audit of follow-on handling; drafted at user direction the same day.
• Activation survey re-run 2026-08-03 (goals_xref score G-159, per the activation-freshness rule): G-160 and G-161, drafted in the interval, show terms-only noise with no path overlap (commandstack internals / tcltestrun parsing - unrelated territory); standing relationships unchanged (Related: G-156).