punkshell

1 Tag

272 MiB

Author	SHA1	Message	Date
Julian Noble	f103b90c3a	G-166 achieved: cmdinfo/cmdhelp surface recognised-but-unavailable landings distinctly Activated at user direction and achieved in the same session. On Tcl 8.6, 'i string is dict' (a class the runtime lacks) and 'i string is true' (a real class) were indistinguishable to both eye and machine: cmdinfo reported cmdtype 'doconly' with identical key sets, and cmdhelp's advisory parse of an argument tail succeeded against the virtual docid, so 'i string is dict 5' rendered exactly like a usable command line. Documentation REACHABILITY for unavailable words is G-073's intent; the INDISTINGUISHABILITY was emergent - nothing structural told a consumer the documented word is rejected here. punk::ns 0.10.0 (a) cmdinfo gains an 'unavailable' key on EVERY result - empty, or the canonical -choiceunavailable name the resolution addressed. It is a SECOND AXIS beside cmdtype, never a cmdtype value: cmdtype answers what kind of executable thing resolution landed on (both 'string is dict' and 'string is true' stay 'doconly'), availability answers whether the resolved word is selectable in this runtime/context. Overloading cmdtype would have broken every consumer switching on cmdtype eq "doconly", and the two only co-occur incidentally. cmd_traverse's yielded/returned records carry a sixth element for the attribution; cmdinfo keeps the final landing's value. Population is nearly free - the level's choices-bearing first leader is resolved once per level via the shared punk::args::choiceword_match, and both the exact space-form landing and the prefix retry consult that one result (the G-051 branch was restructured, not duplicated). (b) PREFIX-LANDING DECIDED, enacting the G-073 doc-walk follow-on: a unique prefix landing on an unavailable name now RESOLVES that name's virtual docid, attributed - the conservative non-resolution was not kept. Encoding availability as resolve-vs-don't-resolve conflated it with addressing and made addressing inconsistent: 'i string is tr' resolved but 'i string is dic' did not, while exact 'true' and 'dict' both did. Now every form of address that names a documented word resolves it, and the availability key plus the render marking carry the rejection story parse reports for the same word. The choice traverse's G-040 parse-parity claim is untouched - an unavailable word still identifies no SUBCOMMAND there, it is only attributed (the path taken when the name has no space-form virtual docid). (c) cmdhelp marks such subjects in every return form from one shared wording (_cmdhelp_unavailable_marking, mirroring punk::args' private::unavailable_choice_msg so a user meeting both reads one story): -return dict carries the key, table/string render the message below the usage under the non-info scheme, -return text leads with an 'UNAVAILABLE:' line. The marking takes precedence over BOTH the ok-parse info render and any parse failure message - the subject not existing here is the more fundamental report, and it is the one a parse against a virtual id cannot make. Parse status still passes through, so argument positions keep their marking. punk::args::moduledoc::tclcore 0.4.1 - on a runtime lacking a curated forward class, that class's per-class virtual id LEADS its help with the unavailability statement (runtime patchlevel + the rejected call shape), then the unchanged static description. The static version note existed but sat at the END of the prose, so a reader met the full class documentation before learning the class does not exist here. Runtimes where the class is live generate the id unchanged. Tests: cmdflow.test gains the flowunavail / flowunavail_nodoc fixtures and 5 pins (key always present; exact landing attributed with cmdtype unchanged; the prefix decision pinned against parse's choiceunavailable rejection; choice-traverse attribution without addressing; attribution surviving an argument tail). cmdhelp.test gains the helpstrua fixture and 5 pins (3 local render, 2 tclcore-gated real-world) plus the two DELIBERATE key-list flips (cmdhelp_cmdinfo_result_shape, cmdhelp_return_dict_valid). tclcoreparity.test gains the virtual-id leading-note pin. All new pins are live-derived, so the modern arm asserts the same shapes with an empty key. Verified: cmdflow 25/25 + cmdhelp 50/50 on native 8.6.10 (THE AFFECTED ARM, unavailable={dict}), 8.7a6 and 9.0.5; full punk/args subtree 341 total / 338 passed / 3 intended skips / 0 failed on all three; full punk/ns 125 green on 9.0.5 and green on 8.6/8.7 apart from two nsprimitives failures verified PRE-EXISTING on both (confirmed with the module changes stashed); broad src/tests/modules/*** sweep on 9.0.5 - 1257 tests, 108 files, 0 failed. Consumer audit: every in-tree cmdinfo consumer reads named keys via dict get, so the added key is inert for all of them. goals_lint and architecture_lint clean. Project 0.56.2 -> 0.57.0 (user-visible shell behaviour) with CHANGELOG entry. Goal flipped to achieved and archived; four follow-ons recorded (to G-050, G-044, G-055, G-167) with reference-sweep pointers pushed into those goals' Notes, and the G-167 back-pointer added at activation - G-166 landing first settles the marking-vocabulary ownership the two goals share. Also corrected two pre-existing stale claims in src/tests/modules/AGENTS.md that this work falsified: tclcoreparity's "version-note labels conditional on class presence" (stale since G-073) and its "under 8.6 run the file directly via a plain tclkit" note (stale since native 8.6 became a supported runner 2026-07-21). Staged deliberately as this change-set only: the concurrent G-172 zig CPU-floor lane (GOALS.md entry, goals/G-172-*.md, the four build.zig files) is left uncommitted in the tree. Claude-Session: https://claude.ai/code/session_01Y5vEJUZkD4p8jmEFEBVhLi Assisted-by: harness=claude; primary-model=claude-opus-5[1m]; api-location=anthropic.com	3 weeks ago
Julian Noble	d3dcc31dc4	goals system v2: semicolon Scope delimiters, version marker, lint delimiter check - 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	1 month ago
Julian Noble	05ffa7ac19	goals: xref reconciliation - subshell/repl/args/textblock cluster (G-009 G-042 G-044 G-048 G-050 G-052 G-053 G-056 G-079 G-080 G-081 G-088, recorded 2026-07-24) Assisted-by: harness=opencode; primary-model=openrouter/moonshotai/kimi-k3; api-location=openrouter.ai	1 month ago
Julian Noble	99af43c8be	goals: G-062 achieved archival + archive-loss prevention (sweep rules, backlink markers, goals_lint) 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	1 month ago
Julian Noble	ae04b3f8c9	GOALS: two-tier index restructure - summary-only GOALS.md, canonical Goal/Acceptance in detail files, archive-on-flip - 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	1 month ago
Julian Noble	ae72dffd91	G-049..G-053 proposed: parse-status model, synopsis marking, cmdinfo doconly+prefix parity, oo method autodef, range-valued -multiple Five user-approved proposed goals with detail files, grounded in the 2026-07-10 characterization work (GAP pins in usagemarking.test/cmdhelp.test map to these): - G-049 punk::args parse-status data model with machine-parsable cmdhelp returns: documented per-argument status structure consumed by both arg_error renderers, cmdhelp -return dict; fixes badarg coverage (type/allocation failures), scheme honoured on failure path, caller attribution, and the stateful shared colour-array scheme handling (nocolour fallthrough + dash-spelling leak). - G-050 synopsis argument-validity marking and status-aware returns: 's' gains the goodarg/badarg marking via the G-049 structure; replaces the curried-alias excess-args length arithmetic with a parse against the resolved definition. - G-051 cmdinfo truthful cmdtype for doc-only pseudo-commands + space-form docid prefix parity via the shared choiceword_match resolver ('i string is tr'). - G-052 TclOO method-level autodef: undocumented methods get an (autodef) from the introspected parameter list instead of the class-summary-only fallback. - G-053 punk::args range-valued -multiple: {min max} occurrence ranges alongside the legacy booleans, expressing "at most once, repeat is an error" without a separate duplicates flag (mirrors the -choicemultiple precedent; motivated by the runtests -include-paths last-wins incident). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	2 months ago

6 Commits (b0a4c6ef29ead2fa9c76553f9b44c0efafa3cfda)