The skills existed but sessions never leaned on them - grep+read wins
the tool-selection contest when descriptions are phrased as information
needs ("use when you need to know how to call...") rather than task
triggers, and grep 'succeeds' without revealing which of the repo's
coexisting module copies is loaded. Changes to convert them from
available options into workflow steps:
- SKILL.md descriptions rewritten task-first ("Use BEFORE reviewing,
testing, editing..." / "Use BEFORE writing any new Tcl helper..."),
with run-it-first wording, the multiple-module-copies rationale, and
cost stated up front (one sub-1s side-effect-free invocation).
- Invocations shortened to lib: script-path form (verified working,
~0.45s each): punk91 src script lib:developer/whatis|nslist.
- New caveat in both: prefer the Bash tool over PowerShell (attached
console can flip colour/terminal detection in punkshell children).
- AGENTS.md Repo-wide Notes entry converted from reference note to
DIRECTIVE: whatis/nslist first, grep reserved for full-text searches.
- .claude/settings.json: allow entries for both scripts (Bash +
PowerShell, punk91/bin/punk91/./bin/punk91 prefixes) so first use is
prompt-free.
.claude/skills copies re-synced from canonical .agents/skills
(diff-verified byte-identical).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Stage 4 - documented overlay semantics implemented (commandset::layout 0.2.0):
layout_materialize resolves a layout to its overlay chain (vendor tier then
custom tier per store+vendor, <name>@<base> derived-layout folders expanding
their base chain first, cycle-guarded) and composes multi-folder chains into a
disposable staging dir applying <item>.anti deletion markers (zero-byte marker
files recommended - committable, unlike the originally documented empty marker
folders, which are also accepted). Single-folder chains with no markers are
used in place, so punk.project (store and zipfs modpod) behaviour is unchanged.
project.new (commandset::project 0.4.0) copies from the materialized path and
the layout listing/scanning commands show the effective merged view.
Fixtures: punk.othersample is now a live derived layout (new custom-deck
fauxlink ref + .gitignore.anti demo marker); extra.txt/store README rewritten
to the implemented semantics. New tcltest suite
src/tests/modules/punk/mix/testsuites/layout/materialize.test (20 tests).
Anti markers deliberately stay a plain filename convention rather than
tag-bearing fauxlinks: a fauxlink is a reference tooling may follow (fcat
auto-follows), a marker is a tombstone with no target.
Stage 5 - retirements and generated-project version seeding:
- The empty unimplemented child-side src/PROJECT_LAYOUTS_CREATE_FROM_... marker
folder is deleted along with its project.new and make.tcl sync exclusions.
- The vendor/custom x _project matrix collapses for layouts: custom/<vendor> is
the one override level; _project folders join no overlay chain (the
pseudo-vendor remains for decktemplates module/utility templates only).
- project.new seeds generated projects post-materialization (only-if-missing,
never from payload): punkproject.toml ([project] name + 0.1.0), a matching
CHANGELOG.md ## [0.1.0] header, and punkorigin.toml - an interim generation
provenance baseline (utc, layout name + resolved store target,
punk::mix::templates version, punkshell version when derivable, origin path)
for the G-027 pull design to adopt (noted in G-027).
Also: script-mode/programmatic project.new robustness (explicit shellrun
require; punk::mix::util askuser/do_in_path/foreach-file fully qualified -
the util:: shorthand exists only after cli commandset import). Includes the
concurrently-landed (other session, previously uncommitted) 0.3.1 early
module-name validation fix in project.new, shipped within the 0.4.0 bump.
G-087 flipped achieved 2026-07-19 (verification in the detail file; archive
move follows in the next commit). punkshell 0.16.0 -> 0.17.0.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
punk::cap::handlers::templates 0.3.0: module-pathtype layout refs resolve
against the providing module's own templates/project_layouts store (sibling of
its layout_refs folder) instead of the never-existing <modulebase>/src tree -
module-carried thin layouts become usable.
punk::mix::templates 0.2.0: ships the thin punk.project layout payload inside
the modpod (payload synced from src/project_layouts by make.tcl - see below);
shellproject_multivendor declaration fixed decktemplates -> src/decktemplates
(shell-project layouts/templates were invisible when cwd was outside any
project).
punk::mix::commandset::project 0.3.0: project.new injects bootsupport into the
generated project at generation time via new lib::bootsupport_inject - manifest
(include_modules.config) driven module resolution from the generating shell's
project bootsupport tree, or a standalone kit's tcl:™️:list paths (999999.*
dev versions never injected; latest-version non-glob semantics matching
make.tcl bootsupport; adjacent non-.tm support files such as struct sets_*.tcl
and textutil .tex data carried along; bootsupport lib* trees copied from a
shell project, notice emitted for manifest-less standalone kits); punkcheck-
recorded with plain-copy degradation. -layout now prefix-matches the live
layout set instead of the package-load-time snapshot.
punkcheck 0.4.0: start_installer_event no longer writes literal '$eventid'/
'$rel_source'/'$rel_target'/'$config' into event headers (braced-literal
expansion bug, latent since inception - collided as duplicate ids when install
and installtrack writers shared one db); sources with no common root vs the
punkcheck folder (e.g //zipfs:/ module-mounted layouts) are recorded as
independent absolute paths instead of erroring.
punk::mix::base 0.1.1 -> 0.1.2 (manually versioned rename): cksum_path no
longer hangs forever on vfs-mounted files - tcllib -file digest modes read via
fileevent+vwait and zipfs channels never deliver fileevents (empty
ZipChannelWatchChannel in core); non-native files are slurped and digested in
data mode (new cksum_data_command per algorithm + cksum_crc_data/
cksum_adler32_data helpers; exec-based sha3 errors cleanly for vfs paths).
make.tcl: custom/_project layout bootsupport-sync retired (project layouts
store no snapshots); sync_layouts retargeted to thin vendor layouts (make.tcl,
build.tcl + bootsupport manifest copies; punkcheck db at
src/project_layouts/.punkcheck) plus store->modpod punk.project payload sync
(excludes bin/sdx.kit and src/PROJECT_LAYOUTS_* marker; fossil settings kept
via core-exclude override); bootsupport copy onto a modpod the running
make.tcl has mounted records OK when target content is already identical
(FAILED-record churn fix); workflow text updated (DIAGRAM 1b) and help/argdoc
texts adjusted.
bootsupport include_modules.config: added previously-recordless-but-required
entries cmdline (fileutil dep), struct::set (make.tcl accelerators), textutil,
textutil::expander, textutil::patch - generated projects' make.tcl now boots
under a plain tclsh.
Docs: root/src/bootsupport/punk AGENTS.md updated for the retired sync and
build-managed modpod payload; goal detail G-087 stage-3 progress record;
CHANGELOG 0.16.0 + punkproject.toml bump.
Claude-Session: https://claude.ai/code/session_01WS3VakZo4sgbFzcQFW3twZ
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New scriptlib/developer/nslist.tcl backing the new cross-framework tcl-nslist
agent skill (.agents/skills/ canonical, .claude/skills/ synced copy): the
discovery counterpart of whatis.tcl - lists what a namespace/package actually
exposes at runtime via punk::ns::get_ns_dicts (the n// machinery): child
namespaces with loadable-package markers, commands classified by kind,
punk::args-documented commands, -synopsis whole-namespace usage lines,
-pathcommands namespace-path resolution. Auto-package-requires unloaded
packages and follows ensemble commands to their implementation namespace.
The tcl-whatis skill/script cross-reference it (whatis redirects with a hint
when the queried name is a namespace, not a command).
punk::ns 0.9.1: get_ns_dicts packagetails/packageprefixes initialization moved
inside the per-namespace loop - with multiple matched namespaces (path globs,
trailing **) every dict after the first carried the union of all earlier
namespaces' entries, mis-marking non-package children in nslist/n// underline
styling and in the returned data; a child with several deeper packages below
it was appended to packageprefixes once per matching package (now once).
Pinned in nslist.test (nslist_classification_multins_package_buckets_reset).
Documentation-only PUNKARGS added for get_ns_dicts (returned dict keys
documented) and nslist_dict; parsing stays manual.
Root AGENTS.md: introspection note + scriptlib/developer inventory updated.
Project version 0.15.1 + CHANGELOG entry. punk::ns suite 102/102 pass.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- User Preferences: never open/update fossil checkouts with tip (newest
check-in on ANY branch); name the branch explicitly and verify the
fossil status tags line. Prompted by TEMP_REFERENCE/tcl9 being parked
on manifest-in-rc-only since 2026-07-08 via a tip checkout race.
- Child DOX Index: add missing TEMP_REFERENCE/ entry (VCS-ignored,
machine-local reference area; tcl9 nested fossil checkout stays on
trunk). The local TEMP_REFERENCE/AGENTS.md carries the refresh
procedure but is unversioned by design.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Multi-process mode previously execd bare test files with no environment
(children died on their first package require) and misreported the
crashes as missing-cleanupTests warnings with the stderr discarded.
- testsupport/child_test_runner.tcl (new): per-file child bootstrap.
Applies a runtests-generated environment payload (prefer latest, test
tm paths, auto_path, modpod ifneeded defs, tcltest options; per-file
-testdir computed child-side), warms 'clock format' before the
module-path wipe (first script-level clock use loads msgcat from the
runtime default paths, which the test paths do not supply), and
mirrors the testinterp preload: package require shellrun plus one
no-op runx -tcl call (runx execution pulls punk::lib; several suites
depend on preloaded punk::* commands).
- runtests.tcl: generate the payload per run; spawn children via plain
exec with file-captured stdout/stderr and immediate-EOF stdin
(mechanism reusable for future parallel -jobs scheduling); classify
nonzero child exits as file-level failures with the stderr tail
surfaced in all report styles (exit-0-no-summary remains the
missing-cleanupTests warning); warn under kit executables (children
boot with kit-stamped punk packages preloaded, shadowing src dev
modules - prefer a native tclsh).
- scriptlib/developer/runtests_parity.tcl (new): compares two
'-report json' captures on result identity (per-file counts,
failure/skip/warning identities; timings ignored), tolerating
preamble noise and the ANSI SGR reset emitted on the JSON line.
Verified on native tclsh 9.0.3: full suite singleproc vs multiproc
PARITY ok (87 files, 989 tests, 973/15/1 with the documented exec-14.3
baseline as the sole failure); crash and warning classification
exercised. Wall time ~5m50s in both modes.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
punk::ns 0.9.0: cmdhelp (i) gains -return text - plain-text argument
documentation for machine/LLM consumption: no ANSI, no table layout, the
argument section of every command form rendered in one output under a common
header ('i -return text after' shows all six forms), G-041 form selection
still honoured when argument words are supplied, no advisory-parse error
preamble (-return dict remains the parse-status surface). Implementation
delegates resolution to the -return dict recursion and renders per-form via
the string renderer.
punk::args 0.12.6 (user direction; string-form layout explicitly not frozen -
no external consumers yet):
- arg_error renders the error message + per-form match detail exactly once,
BELOW the usage display (was above and below); bottom append suppressed for
empty messages.
- string renderer argument rows are single-line
'name TYPE:type(constraints) ?DEFAULT:'val'? ?MULTI:yes?' - type
constraints parenthesize onto the base type instead of line-breaking
mid-row; empty DEFAULT/MULTI labels and whitespace-only help blocks omitted.
- choices render as markdown-subset bullets '- `choice` - label' with label
continuations at a fixed deeper indent - choice names are now
machine-distinguishable from label text without ANSI. Structural contract:
column-0 lines bearing TYPE: are argument rows, indented lines are
documentation, backticked bullets are choices. Table cells unchanged.
New scriptlib/developer/whatis.tcl (runtime command introspection for
agents): resolved name, subcommand-chain resolution via punk::ns::cmdinfo
('whatis string is'), kind, providing package + loaded version, origin file,
proc definition file:line, punk::args synopsis; -body appends the runtime
body with file-relative line numbers, -doc the full plain-text argdoc via
cmdhelp -return text (with fallback for older punk::ns). Backing the
cross-framework tcl-whatis agent skill: canonical .agents/skills/tcl-whatis/
(Agent Skills standard - pi/OpenCode/Codex) with byte-identical copy in
.claude/skills/ for Claude Code; .gitignore gains !.claude/skills/ with the
fossil ignore-glob comment + exception-set docs updated per the dual-VCS
contract (fossil adds staged). Root AGENTS.md: .agents/skills index entry,
whatis pointer in Repo-wide Notes, scriptlib/developer example.
Tests: new pins cmdhelp_return_text_all_forms/_argword_form_selection/
_single_form_plain_marker (cmdhelp.test), rendering_stringmode_singleline_argrows
+ rendering_stringmode_choice_bullets (rendering.test); deliberate-change pin
updates: errorselection.test message matches gained leading * and cmdhelp.test
message pins sample the last line (message placement). Full source-tree suite
963/979 pass, sole failure the pre-existing exec-14.3 baseline; make.tcl
modules clean.
Project version 0.12.42 -> 0.13.0 with CHANGELOG.md entry.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root AGENTS.md User Preferences gains the binding agent-agnostic rule (an
agent editing .gitignore discovers it at the root without walking into
.fossil-settings/): .gitignore canonical, ignore-glob hand-derived, same work
unit, semantic differences translated per .fossil-settings/AGENTS.md. That
child doc's sync procedure is retitled from "when asked" to mandatory for
any ignore-rule change, with the one-sided-change prohibition stated.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Stock tclsh treats any leading-dash arg other than -encoding as argv for an
interactive/stdin session: on a console it hangs at a prompt, with piped stdin
it exits 0 silently ignoring the supposed one-liner. Agents habitually reach
for -e (perl/python/node reflex), wasting time waiting on hung processes.
- root AGENTS.md User Preferences: document the misparse, the correct patterns
(temp .tcl file or script via stdin) and the defensive stdin-redirect habit
- .claude/settings.json: PreToolUse hook denying Bash/PowerShell invocations
of tclsh with -e, anchored to command position (start/pipe/semicolon/paren)
so prose mentions in commit messages or grep args do not false-positive;
corrective guidance returned to the agent
- .gitignore: narrow the .claude ignore so shared settings.json is tracked
while session-local files stay ignored
- .fossil-settings: ignore-glob hand-derived per the no-negation rule
(.claude/* wholesale + explicit fossil add of settings.json), exception set
in AGENTS.md updated; fossil extras under-ignore check verified empty
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
New user-preference bullet: agent-authored text avoids typographic
Unicode (em/en dashes, curly quotes, arrows, ellipses) in favour of ASCII
equivalents, with hard enforcement for outward-bound artifacts; documented
exceptions for non-ASCII subject matter, verbatim quotes, and explicit
requests. Existing files are not bulk-retrofitted.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
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
New agent-maintainable scriptlib/developer/ area (recorded in root
AGENTS.md ownership notes). tkconsole_demo.tcl wires a Tk text widget as a
live ::opunk::TkConsole and runs an interactive repl against it, with a
layer-by-layer commented walkthrough of the mechanics: voo virtual
dispatch, the reflected-channel/input-pipe wiring, repl::init -console
routing and the junction-stack output diversion, and the vwait/Tk event
loop interplay. punk::args-documented options (--help renders the usage
table; the definition is registered for 'i developer::tkconsole_demo'):
-columns/-rows/-font/-title, -demo (auto-typed session via feed, including
a window-resize step showing size queries tracking actual dimensions) and
-autoclose (exercises the <Destroy> -> teardown -> eof path). Includes a
demo-installed code-interp bridge so in-session punk::console::get_size
reports the tk console's current size - documented as a hand-rolled
preview of G-008 scoped console state.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
A scratchpad test repo (fossil-init/opened 2026-07-06 while probing
ignore-glob semantics) registered repo:/ckout: rows in the global
_fossil config-db and persisted as row 1 of dev projects.work.
Instance cleaned up (fossil all ignore + dir removal + ckout prune).
- root AGENTS.md User Preferences: throwaway fossil repos must use a
scratch FOSSIL_HOME so registration lands in a disposable config-db;
includes the remediation recipe.
- G-016 Notes: the staleness concern applies to fossil's own central
config-db, not just a punk-maintained registry; the shipped
enumeration design needs a staleness story for both VCS sources,
especially the -return dict|json machine forms.
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
- new src/tests/modules/punk/mix/testsuites/scriptwrap/multishell.test (9 tests, green on tcl 9.0.3 + 8.7, unix exec case constraint-gated): scriptset wrap via the module-provided punk.multishell.cmd template (payloads + _wrap.toml fixture) - output produced, MULTISHELL magic line, payloads embedded verbatim, configured win32 nextshell present, LF-only endings, byte-identical re-wrap determinism; checkfile 512-byte label/boundary validation reports no label location errors for a fresh wrap AND for the committed bin/runtime.cmd; the runtime scriptset ROUND-TRIP pin - re-wrapping src/scriptapps runtime.ps1+runtime.bash+runtime_wrap.toml reproduces bin/runtime.cmd byte for byte (verified identical before pinning), so hand-edits to the output or unregenerated payload changes both fail; execution smoke - cmd.exe runs the polyglot and dispatches the powershell payload (windows), sh payload execution gated to unix (on windows the shell layer deliberately relaunches via the win32 nextshell)
- guidance strengthened so "fix bin/<name>.cmd" routes to sources: root AGENTS.md bin/ index entry now states the .cmd polyglots are scriptwrap-generated from src/scriptapps; bin/AGENTS.md gains a "Generated polyglot .cmd scripts - never edit in place" section with the 4-step fix workflow (edit payloads/toml, re-wrap with multishell -askme 0, heed checkfile ERRORs, commit source + regenerated output together); src/scriptapps/AGENTS.md documents the scriptset->bin/*.cmd relationship and regeneration command; tests index updated
- context: the polyglot technique is deliberately maintained despite fragility (user direction 2026-07-10) until hiding techniques close in the underlying languages - these pins are the guardrails
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- .fossil-settings/binary-glob set to '*': binary checkins (e.g zips) proceed without fossil
warnings/prompts; the aim of an eventually binary-free tree (G-004/G-005/G-006) is
agent/workflow policy, deliberately not enforced at the local VCS layer
- .fossil-settings/AGENTS.md: new "Commit warning suppression" contract documenting the above
- root AGENTS.md: LF preference clarified - converting CRLF text files to LF when editing is
correct (no CRLF preservation for diff-minimisation; preserve only deliberately mixed-ending
files or on explicit instruction); binary-checkin bullet notes the VCS-layer carve-out
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Policy (GOALS.md maintenance rules, mirrored in root AGENTS.md and goals/AGENTS.md):
- agents apply goal-entry adds/edits only on user request, proposal-first: show the
proposed wording and get explicit approval before writing (replaces "only the user
adds or edits goals" - the user was applying agent-drafted edits by hand anyway)
- suggesting candidate goals is welcome and encouraged when grounded in the work at
hand; a suggestion is a flagged proposal, never a file edit; bulk goal surveys stay
out of bounds
- detail-file updates from user-directed work on a goal proceed without pre-approval,
reported in the completion summary; index stays canonical
- unchanged: achieved-flip on met acceptance (reported), no proposed->active flips
G-038 (user-approved):
- Acceptance gains a post-restart terminal-query clause: a code-interp query (e.g.
'help console') must succeed instead of being refused by the stale settled
can_respond=0 anchor
- detail file records the proven mechanism for the post-restart console failure
(piped phase settles can_respond=0; punkshell.tcl opens CONIN$ as a new channel
leaving the repl thread's stdin as the exhausted pipe; the anchored default console
keeps the dead pair; forced resettle honestly re-settles 0 via layer-1 eof), the
rebind requirements (re-point {in out} AND unsettle), and the hidden-console
repro/regression harness
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
- G-039 (proposed): investigate/reproduce the orphaned-shell one-core spin
observed 2026-07-08 (single hard-looping thread after the hosting terminal
went away); detail file records the observation, repro/diagnosis approach
(reusing the G-036 dump tooling pipeline) and the G-038 coordination point
(dead console = failure branch of the console-EOF restart decision).
- G-036 acceptance reworked per user: standalone minimal repro waived as
moot (root cause proven and fixed upstream); remaining actionable is a
has_bug-style check reporting tcludp < 1.0.13 on Tcl 9 Windows through the
existing check/help machinery (simple version test, no behavioural probe).
Index and detail-file acceptance kept in sync.
- AGENTS.md User Preferences: cmd.exe truncates a heavily populated PATH -
tools resolvable in PowerShell may be not-found under cmd /c; use absolute
exe paths there and suspect truncation before absence.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Adds src/tests/shell/testsuites/punkexe/scriptexec.test (12 tests, all
pass) covering app-punkscript / the script subcommand (G-015): piped
execution and honest exit codes, error->exit 1, exitcode propagation,
stdin result echo, default-env dev alias present without boilerplate,
file-form argv passing, the lib:<name> scriptlib mechanism (subpath,
extensionless, bare-arg reclassification, not-found location listing),
and the tclsh-matching Tk main-loop behaviour (0.4.1): a serviced
after-callback runs and exits, a no-exit GUI script stays alive, an
errored GUI script exits promptly without hanging.
Reuses the shellexit.test built-exe harness pattern (pipe stdin,
half-close for EOF, timeout+force-kill) so runs are hang-proof; Tk cases
gated by an auto-detected punktk constraint (probes whether the kit loads
Tk). Full shell suite: 19 pass / 2 skip (console-only punkgoals) / 0 fail.
lib:/Tk cases resolve committed fixtures under scriptlib/_punktest/ - a
lib:-resolvable fixture cannot live in a tcltest temp dir since resolution
only searches scriptlib locations relative to the exe. The subfolder is
test-owned (README + do-not-edit fixture headers); root AGENTS.md carves
it out as the one agent-manageable exception to scriptlib being
user-only. No project version bump - tests/docs/fixtures only, no shipped
shell behaviour change.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root AGENTS.md "Git Commit Conventions" renamed "Commit Conventions (any
VCS)": the Co-Authored-By/AI-attribution ban and the Assisted-by trailer
apply to git commits and fossil checkins alike (git parses trailers
structurally, fossil comments are free text - either way the trailer is
the last line of the message). Generated projects start fossil-only but
may adopt git; punkshell itself is git-primary today and could flip.
CLAUDE.md mirror section updated to match.
G-027 detail: documentation/goals ownership design input - layout-owned
child AGENTS.md docs ride the pull channel under the
unmodified-since-install classification; project-owned skeletons (thin
root AGENTS.md, GOALS.md, goals/AGENTS.md, empty GOALS-archive.md) are
seeded once and never pulled; commit conventions are part of the seed
(developer-changeable, VCS-neutral); layout-owned marker convention;
transitive chains inherit the parent''s modified docs as their baseline.
G-012 detail: AGENTS.md template payloads recorded as the same hazard
class as live .gitignore payloads - a template AGENTS.md under
src/project_layouts/ is binding DOX for agents walking the punkshell tree
though written for generated projects; needs the same inert storage +
materialize-at-generation treatment.
First field test: the tomlish project was seeded today with the thin root
AGENTS.md + CLAUDE.md + GOALS framework this design describes.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Read-side DOX rule: re-read the canonical source for a topic (GOALS.md,
nearest owning AGENTS.md, punkproject.toml, etc.) on recheck/re-verify
queries, rather than relying on session memory. Directory re-scans are
complementary, not a substitute.
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
Move project-version helper procs (parse_punkproject_version,
read_punkproject_version, read_changelog_latest_version) out of make.tcl
inline definitions into a loadable punkboot::utils module so the parsing
logic is unit-testable.
- src/modules/punkboot/utils-999999.0a1.0.tm: new module (0.1.0) with
the 3 procs in punkboot::utils namespace, PUNKARGS argdoc blocks.
- src/modules/punkboot/utils-buildversion.txt: initial 0.1.0.
- src/tests/modules/punkboot/utils/testsuites/utils/utils.test: 19 tests
covering section tracking, missing fields, wrong sections, whitespace,
quote styles, changelog header parsing, pre-release suffixes. All pass.
- src/make.tcl: inline procs removed; projectversion block now does
package require punkboot::utils and calls punkboot::utils:: procs.
- Layout make.tcl files (punk.shell-0.1, punk.project-0.1): same edit;
punk.basic keeps inline procs (no bootsupport tree).
- include_modules.config: added punkboot::utils entry (main + 2 layouts).
- Bootsupport snapshots propagated via make.tcl bootsupport.
- AGENTS.md: project version bump 0.2.0 -> 0.2.1 (patch: new make.tcl
projectversion subcommand is part of the product surface); added
clarifying line that make.tcl command interface warrants at least a
patch bump; src/project_layouts/ added to directories agents should
not directly modify.
- CHANGELOG.md: 0.2.1 entry.
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
Add a project-level version bumping mechanism for punkshell, tracked in
punkproject.toml, independent of individual module versions.
- root AGENTS.md: new 'Project Versioning' section with change-driven
SEMVER bump policy (patch/minor/major triggers), CHANGELOG.md requirement,
advisory enforcement contract, and independence from module versions.
- src/AGENTS.md: cross-reference to root Project Versioning section so
agents working in src/ discover the rule during their DOX chain walk.
- CHANGELOG.md: new repo-root file with initial 0.2.0 entry; latest
'## [X.Y.Z]' header must match punkproject.toml version.
- src/make.tcl: new 'projectversion' subcommand — read-only, advisory check
that warns on CHANGELOG/punkproject.toml version mismatch and on src/
commits since the last punkproject.toml change. Exempt from bootsupport
staleness abort (same as 'check'). Self-contained Tcl, no punk deps.
Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai
git tracked fossil's generated checkout artifacts (manifest, manifest.tags,
manifest.uuid - regenerated on every fossil checkin/checkout per the
versioned 'manifest' setting value 'rut'), which would churn as soon as
fossil commits begin. They are now untracked and git-ignored with
root-anchored patterns (nested manifest-named files elsewhere are real
content and stay tracked). Fossil control files (.fslckout/_FOSSIL_/
*.fossil) were already correctly git-ignored, and .fossil-settings/
.fossil-custom correctly git-tracked.
New .fossil-settings/AGENTS.md is the canonical home of the git+fossil
contract: which files each system must not track, the ignore-glob
derivation rules (no negation -> wholesale-ignore + explicit fossil add of
tracked exceptions; directory pruning; * crossing /; */ variants for
match-anywhere patterns; default dotfile skipping), and the verification
procedure any future "sync the ignores" request must follow (fossil extras
against git check-ignore, and a tracked-set comparison bounded to the
documented exceptions). The ignore-glob header now points there instead of
duplicating the rules; root AGENTS.md Child DOX Index gains the entry.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
The dash-delimited launch package modes of built punk shells (dev/os/src/
internal, implemented in src/vfs/_config/punk_main.tcl) had no agent-facing
record. bin/AGENTS.md now documents the mode grammar and, in operational
terms, the src mode that matters for verifying working-tree changes:
exe-location-based project-root discovery, the source module paths it
prepends, package prefer latest (dev 999999.0a1.0 modules beating
kit-stamped snapshots), and how 'package present' distinguishes a src-mode
session from a plain kit launch. Also records the both-Tcl-generations
interactive verification convention (a Tcl 8.6-based shell plus the current
Tcl 9-based incarnation, deliberately not version-pinned) and the role of
the plain runtime kits under bin/runtime/ for punk-free probes.
Root AGENTS.md Child DOX Index gains the bin/ entry, and .gitignore gains
a !/bin/AGENTS.md negation alongside the other source-controlled bin items
(the /bin/* ignore is why no doc lived there before).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Root AGENTS.md closeout now includes a step to re-check modified .tm files for new procs lacking PUNKARGS argdoc blocks. src/modules/AGENTS.md Work Guidance explicitly requires argdoc blocks for all new procs in .tm files (documentation-only is acceptable). The Documentation section clarifies that 'user-facing' includes developer-facing utility procs. A new 'Argument Order In PUNKARGS' section explains the distinction between @leaders, @opts, and @values and why putting a leading argument in @values produces an incorrect synopsis. Verification section adds a check for PUNKARGS argdoc blocks on new procs. The interp_sync.test file contains 6 tcltest tests for the new punk::lib helper procs.
Agents must not add new executable binaries (or zip-based .tm modules
embedding executables). Existing committed binaries are intentional
interim state pending goals G-004/G-005/G-006 and must not be flagged
or 'fixed'; the rule does not block the developer's own interim commits.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
