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
Vendored library payloads and vfs kit payloads legitimately carry CRLF
endings (upstream files are kept as-is; the LF preference governs authored
text). Without the globs, large vendor/vfs checkins block on fossil''s
interactive CRLF prompt - the tablelist 7.11 catch-up (fossil 3316d3c7)
had to use --no-warnings. Policy documented in .fossil-settings/AGENTS.md
alongside the binary-glob rationale. crlf-glob is fossil-only (no
.gitignore-style counterpart), so no dual-VCS derivation applies.
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
- .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
Two git/fossil divergence classes discovered during the tracked-set
verification: nested .gitignore files (e.g. in the project-layout templates)
are honoured by git as nested ignores of the outer repo but invisible to
fossil, leaving template content untracked in git yet managed by fossil;
and git ignore matching is case-insensitive on Windows (core.ignorecase)
while fossil globs are case-sensitive (a todo.txt pattern hits vendored
TODO.txt in git only). Both recorded in the coexistence contract with the
prescribed treatment.
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
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 fossil ignore list had drifted well behind .gitignore (missing *.log,
lib_tcl8/9, modules_tcl8/9, vendorbuilds, scratch*, src/testdata,
src/scriptapps/test_*, src/buildsuites, nested _build/_aside, and using
.punkcheck where git has *.punkcheck; carrying a stale 'builds' entry with
no git counterpart). Rewritten to mirror .gitignore as the canonical
statement of intent, translated for fossil glob semantics (verified
empirically against fossil 2.28 with a scratch repo): no negation exists,
so bin/* is ignored wholesale with the source-controlled bin exceptions
(AGENTS.md, *.cmd, *.kit, *.tcl, *.sh, *.bash) handled by explicit
'fossil add' (ignore-glob does not affect already-managed files); a bare
directory name prunes its whole tree; * crosses directory separators; git
patterns matching at any depth get an additional */ variant; # comment
lines are honoured. The header documents the derivation and the semantic
translation rules.
Verification against the live checkout: extras drop 10108 -> 2855 with no
bin/log/scratch leakage; zero extras are git-ignored (no under-ignoring);
git-tracked files invisible to fossil reduce to the designed bin exception
set plus fossil's own generated manifest files and a vendored nmakehlp.exe
(*.exe - needs explicit fossil add, as in git).
Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
Julian Noble