Activation and achievement same day at user direction ('activate and
start on it'). Activation freshness survey (goals_xref score G-033)
recorded in the detail file: G-043's one-directional reference is the
only unlinked real relationship; G-123/G-127/G-131 overlap by
punk_main.tcl/bin co-location only.
Detail file gains the Progress record (option (a) inline-walk
decision, verification evidence on the rebaked punk91 kit, the
moduledoc-0.1.1 live-help note and the pending vfscommonupdate
promotion) and moves content-identical to goals/archive/; index entry
moves GOALS.md -> GOALS-archive.md.
Reference sweep: G-016/G-047 relationship notes point at the archive
and the ::punkboot::proj_root_find delivery; G-032's Approach now
says the packagemode leader text is LIVE and its remaining lane is
rendering/parse wiring; G-089's Related note records that the visitor
root walk it rides is live, remains defined post-boot, and that the
boot-interface packagemode hint it needs is still absent; G-031 gains
the fork-drift datapoint (proj: landed in punk_main.tcl only,
project_main.tcl still lacks src mode and proj:); G-018/G-035/G-043
mentions gain achieved/archive markers.
goals_lint clean (85 active, 51 archived), architecture_lint clean.
Claude-Session: https://claude.ai/code/session_0156PuejSCGjgeGb7jiABrDU
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Acceptance verified in full against the fixture punkbin server
(PUNKBIN_URL override): ahead/behind verdicts naming both revisions
(behind with fetch+use guidance), current annotation preserved,
pre-family no-basis note + sha1 hash-identity, no-name-fetch one-line
divergence note; ps1/bash verdict-line parity asserted per scenario;
runtimecmd roundtrip pin green; bin/AGENTS.md runtime-manager contract
records the surface. Suite evidence in the detail file's flip record.
Activation and flip both 2026-07-25 (user-directed activation; overlap
survey re-run at activation - only G-033 related, already recorded; no
new Related lines). Detail file: status achieved + activation/flip
evidence records (the goals/ -> goals/archive/ move itself rode the
previous commit as a pure 100% rename; this commit carries the flip's
content edits). Index entry moved to GOALS-archive.md. Reference sweep:
G-033's G-119 note updated to landed-state wording with the archive
path (its package-mode docs must not contradict the shipped freshness
contract on naming); goals_lint clean (83 active / 37 archived);
goals_xref report carries no G-119-bridged unlinked pairs.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- GOALS.md: "Goals-system: v2" front matter; canonical "Goals system versions"
section; Scope structure rule (elements separated by '; ' at top level,
commas only inside parens/braces); Child DOX Index note in root AGENTS.md
- goals_lint.tcl: new finding for top-level commas in Scope lines
(paren/brace depth-aware)
- goals_xref.tcl: repo-local configuration via goals/xref.conf (path roots,
stop words, file extensions, reference containers, module dirs,
bare_path_roots, prefix_anchors); defaults byte-identical to previous
behaviour (verified on this tree)
- goals/AGENTS.md: cross-repo goal references drop the G- prefix; xref.conf
documented in Verification
- Scope delimiter normalisation across GOALS.md, GOALS-archive.md and all
detail files, live and archived: 224 lines, top-level commas only;
conservation verified (goals_xref report byte-identical pre/post, diff
hunks are Scope lines only). Archived tier converted under explicit user
approval; sanctioned exception recorded in GOALS-archive.md.
Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai
Finalises the G-062 achieved flip staged by the prior session (punkshell
0.12.1): LICENSE.txt (BSD-2-Clause, Julian Marcel Noble 2023-2026) at the
repo root, README/punkproject.toml/AGENTS.md license declarations, index
record to GOALS-archive.md and detail file to goals/archive/.
Archive-loss prevention, from the G-015 incident (its achieved-status
verification parenthetical was silently dropped by the 2026-07-11 two-tier
restructure's Status-line normalisation; the text is restored to the G-015
archive file's Notes with provenance):
- root AGENTS.md 'Doc Restructures': deleted-line conservation check before
committing bulk doc migrations, structured-field-normalisation hazard
(relocate prose to body sections first), moves separated from edits
- goals/AGENTS.md: lintable header field grammar (one line per field, bare
Status values), flip-time verification evidence recorded in the body, the
archive move content-identical, and a new archive-time reference sweep:
pending-tense mentions of the archived goal updated in the live tier, and
actionable archived notes pointed to from the affected live goal's Notes
- GOALS.md maintenance rules: achieved-flip clause extended to require the
evidence write-up and the reference sweep
Retroactive reference sweep over all 12 archived goals (25 live detail
files): pending-tense fixes (G-002 G-008 G-013 G-016 G-017 G-021 G-022
G-031 G-042 G-044 G-050 - G-017's Goal/Acceptance annotated as
gate-satisfied, contract meaning unchanged), forward pointers pushed from
archived notes (G-062 license-seeding follow-on -> G-012/G-027, G-037
vendorlib/vfs drift semantics -> G-024, G-058 static-baseline mechanism ->
G-005), and one 'Archived-goal references' Notes bullet per remaining
referencing file so every live mention of an archived goal is resolvable
without consulting the archive index.
scriptlib/developer/goals_lint.tcl (new, plain tclsh): validates detail-file
header grammar, strict status values in both tiers, orphan rules in both
directions, Status/Scope mirror consistency, plus an informational (never
fatal) warning for live files referencing an archived goal with no
achieved/archive marker - baseline now zero warnings. Root AGENTS.md
scriptlib/developer ownership note widened to cover developer utilities.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- GOALS.md collapsed to summary entries (ID/status/title/Scope/detail pointer): 104.6KB -> 23KB so a full read stays cheap; Scope lines kept verbatim so path-grep goal discovery still works
- canonicality split: index canonical for ID/status/title/Scope, detail file canonical for Goal:/Acceptance:; all 61 detail-file headers reconciled from the index (fixes stale copies, e.g. G-036 detail acceptance predated the achieved rework), bodies preserved untouched
- detail files created for the three index-only goals G-017, G-034, G-054; every goal now has one
- 10 achieved goals (G-007 G-015 G-036 G-037 G-040 G-046 G-049 G-054 G-058 G-059) archived: summary records appended to GOALS-archive.md, detail files moved to goals/archive/; archive-on-flip replaces the ~30-achieved-entries trigger
- GOALS.md preamble/rules reworked: read workflow (read index in full, then detail files of scope-intersecting goals before editing), contract spans both tiers with proposal-first unchanged, next-free-ID counts the archive, achieved flip judged against the detail-file Acceptance and includes archiving
- progress convention codified from G-001 increment-1 practice: index entries carry status only, never progress; incremental progress lives in the detail file's ## Progress section (landed/remaining); achieved flip requires the remaining-work list resolved - a partial increment never flips a goal
- goals/AGENTS.md rewritten for the split (required 4-field header, one detail file per goal, orphan rules covering archive/); root AGENTS.md Child DOX Index + Repo-wide Notes updated; GOALS-archive.md preamble updated
- stale detail-file paths updated to goals/archive/ in src/lib/app-punkscript/punkscript.tcl (comment), runtimebash_wsl.test, wslprobe.tcl and the G-042 detail file; propagated copies (root lib/, src/vfs/_vfscommon.vfs, src/_build) left to refresh via normal build steps
- no project version bump: governance docs and source comments only, no user-visible shell behaviour
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Design review outcomes (2026-07-07):
- Syntax: proj is not a fifth ordered token (category error - the dash
list is an ordered sequence of path blocks whose order IS the
same-version tie-break dial, per the verified tm rules and punk_main''s
own comment). Decided form: [proj:]<block>[-<block>...] - the prefix
scopes WHICH project root dev/src resolve against (cwd walk-up to the
nearest VCS repo root vs exe-relative), staying outside the ordered
list whose semantics are untouched. Explicit prefix = no silent rebind
on cd. Rejected: auto-detection, an explicit flag (less convenient),
token-attached qualifiers.
- Shadowing: visitor mode makes cross-lineage same-version-different-code
ties structurally expected (binary and visited project snapshots are
different vintages by definition). Order only arbitrates exact ties -
dev-versioned, higher-versioned and kit-absent modules come from the
project in either order. Canonical documented invocation is
proj:internal-src (kit-first: the visiting shell''s infrastructure
survives ties; for a standalone downloaded binary the kit is its only
trustworthy lineage and internal is location-independent); proj:src
documented as the faithful-vintage variant. Trimmed kits (G-019)
compose gracefully - kit-first only arbitrates ties.
- Required boot notice: detected root + effective precedence.
- packagemode help text drafted and persisted in the detail file as the
designated G-032 source (live only when the prefix ships); G-032 detail
cross-references it.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
G-033: an explicit `proj` package-mode token lets an installed (visitor)
punkshell binary detect the punk project containing the cwd - walking up
to the nearest VCS repo root, the marker punk::repo::is_project_root
already uses - and set up source/dev library resolution against THAT
project, so `punkshell proj shell` explores a project interactively even
when the project builds no shell-capable binary (or no binary at all).
History check recorded: cwd project-structure detection was never active
in the boot modes (src/dev are exe-relative; os is shallow cwd-only), but
the runtime detector find_project already exists and dev commands use it -
so the marker question (VCS repo root, not punkproject.toml which tomlish
lacks) is already answered; this aligns boot modes with it. Explicit token
gates it per user decision (no silent rebind on cd); boot chicken-and-egg
(find_project is in punk::repo, not loadable at the package-mode phase)
handled by a lean inline VCS-root walk-up or post-boot deferral. Reuses
the existing src-mode path machinery, parameterised on the detected root.
Not gated on the module.templates/punk::cap plugin machinery.
G-034: zip-based #modpod modules (e.g. punk::mix::templates) fail to mount
in the shell subcommand's code interp on Tcl 8.6 - `dev module.templates`
errors with `invalid command name vfs::RegisterMount` / no template
providers - while the same call works via the script subcommand /
main interp (reproduced 2026-07-07). The code interp lacks the vfs::zip
library that supplies zip mounting for pre-zipfs Tcl. Tcl 9 (zipfs)
unaffected.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Julian Noble