diff --git a/GOALS.md b/GOALS.md index 1d217d30..c9306bb6 100644 --- a/GOALS.md +++ b/GOALS.md @@ -402,3 +402,7 @@ Detail: goals/G-157-exeless-kits-materialized.md Scope: src/make.tcl (sdx resolution ladder suite-shell rung - shared seam with G-157 approach step 4; kit wrap path; runtime_caps/kit_type_mismatch accommodation); src/buildsuites/suite_tcl86/ (build_kithead86 bi-class head variant, mk4kit_attach battery payloads); src/runtime/mapvfs.toml (suite-head runtime rows + kit entries); bin/runtime/win32-x86_64/ (uncommitted local materialization slot for the heads - publication is follow-on); src/tests/shell/testsuites/punkexe/ (bake-path characterization); bin/sdx.kit (consumed by the ladder - its committed status is G-157's contract, not this goal's) Detail: goals/G-158-punk86-kit-parity.md +### G-159 [proposed] Trackable follow-on dispositions in archived goals +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) +Detail: goals/G-159-followon-disposition-tracking.md + diff --git a/goals/G-159-followon-disposition-tracking.md b/goals/G-159-followon-disposition-tracking.md new file mode 100644 index 00000000..582cd26b --- /dev/null +++ b/goals/G-159-followon-disposition-tracking.md @@ -0,0 +1,88 @@ +# G-159 Trackable follow-on dispositions in archived goals + +Status: proposed +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: => open` | `=> goal G-` | `=> landed + ()` | `=> declined ()`. 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-` 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.