punkshell

1 Tag

224 MiB

Author	SHA1	Message	Date
Julian Noble	a5f60ce4b1	G-032 ACHIEVED 2026-08-03: launcher help + parsed subcommands (core 0.3.0, 0.48.0) The kit launch surface dogfoods punk::args. Boot core 0.2.1 -> 0.3.0: new built-in 'help' subcommand + '-help' / '<subcommand> -help' render tabled usage from the moduledoc::punkexe ids plus live registrations (per-kit resolved_def clones (script)::punkexe.launcher/.launcherhelp); unknown first arg naming no existing file (and no lib:* reference) is refused with usage (stderr exit 1) instead of a silent script attempt; buildinfo enforces its no-arguments contract through punk::args (pinned one-liner + tabled usage, exit 2 unchanged). Registration extension ::punkboot::project_subcommand_info (summary/argsid/package/parse - documented by moduledoc::punkboot 0.2.0): project subcommands appear in help by registration alone and may opt arguments into declared parsing. Carve-outs: tool-style kits keep help flags routed to their processor (tomlish parity); tclsh intercepts a help flag only as sole argument (stock dash parity); argsid-less registrations keep -help passthrough. G-030 degradation doctrine: lazy guarded requires (normal boots never load punk::args), PUNKBOOT_PLAIN=1 hook, plain-list fallback, rendering degrades independently of parsing. 8.6 trap fixed en route: punk::args choices-grid render needs punk::lib's lpop shim - guarded require added (verified tabled help on metakit punk86). moduledoc::punkexe 0.4.0: (script)::punkexe::help definition; top-level refusal rule + help discovery; per-subcommand -help notes; buildinfo rejection shape; passthrough-vs-parsed decision recorded. Verified on zipfs (punk902z, punk91) and metakit (punk86) kits; launcherhelp.test 22/22 (incl fake-thin-main registration harness + metakit leg); punkexe subtree 140/136/4skip/0fail; full suite failures (4) are pre-existing in untouched subsystems. Goal flipped achieved + archive record + live-tier sweep (G-038 rewrite, pointers to G-077 and G-089); detail-file move to goals/archive follows as a pure rename. Layout _config trio + _vfscommon core seed hand-swept (byte-identical to masters). GOALS.md staged as the G-032-removal hunk only - the uncommitted G-159 draft entry is left to its author. Claude-Session: https://claude.ai/code/session_01Y1diJnhjUxKgEG6EwYAzxj Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	1 week ago
Julian Noble	1eb442ca92	G-031 + G-025: ACHIEVED (2026-08-02) - archive flips, index moves, reference sweep Both goals flip achieved with full acceptance verification recorded in their detail files (G-031: componentized boot proven on punkshell kits, a generated project and tomlish; G-025: buildinfo stamp/report verified across kit, renamed-copy, code-interp, tclsh-hosted and unstamped contexts). Detail files move to goals/archive/ (pure renames; flip edits committed with the move); index entries move GOALS.md -> GOALS-archive.md records. Reference sweep per goals/AGENTS.md Archive rules: pending-tense mentions rewritten with archive markers and actionable outcomes pushed to G-018, G-023, G-026, G-032 (registration model + buildinfo now concrete render sources), G-038 (piped exitinfo quirk re-measured and recorded as its territory), G-089 (boot_state IS the packagemode hint surface), G-131 (mains collapsed - land detection in the core), G-137 (stamp exists - reconcile RT_VERSION against it). goals_lint clean (81 active, 75 archived). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	1 week 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	2 weeks ago
Julian Noble	bac122da9f	G-039 achieved: punk::repl 0.5.0 dead-console watchdog stops orphaned-shell CPU spin (project 0.12.2) An interactive shell orphaned by its hosting console dying (killed conhost/terminal) previously spun ~2 cores forever: the Tcl 9 windows console driver never delivers the dead-console state to the script as a fileevent (tclWinConsole.c ConsoleEventProc only notifies on buffered data) while its reader thread busy-loops on the persistent channel error, so the script level is completely blind and nothing ever closes the channel. Fix: repl::console_watchdog - a self-rescheduling liveness poll (default 5s, repl::console_watchdog_ms; read-only GetConsoleMode probe via chan configure -inputmode) armed by repl::start only for a tcl9 console input channel serving the process-default console on windows. On probe failure it closes the input channel (stopping the driver's reader thread) and finishes the repl via the normal eof done-path; app-punkshell then finds no console reopenable and exits cleanly. Piped, foreign-console and tcl 8.6 inputs never arm it. repl::start's post-vwait reader deregistration now tolerates a watchdog-closed channel. Verification (2026-07-12): kill procedure post-fix exits the orphan in 1.5-2.0s with no traceback (src mode and rebuilt kits punkbi/punk91/ punk902z); 25s live-console soak shows no spurious trigger, CPU delta 0; piped stdin unaffected; repl consolebackends 3/3 and punk::console suites 88 pass / 1 skip; root cause verified against plain tclsh 9.0.3. Upstream ticket filed: https://core.tcl-lang.org/tcl/tktview/f10d91c2d3 Included: - goals: G-039 flipped achieved 2026-07-12 and archived (index entry to GOALS-archive.md, detail file to goals/archive/ with full root-cause, repro and verification record); reference sweep adds the eof done-value producer note to G-038 - src/modules/punk/AGENTS.md: watchdog contract documented - project version 0.12.1 -> 0.12.2 + CHANGELOG entry - vfs payload sync: _vfscommon.vfs punk/repl 0.4.0 -> 0.5.0 Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	4 weeks 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	9ad1a35adc	goal-editing policy: proposal-first with user approval; G-038 console-anchor finding + acceptance clause 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	1 month ago
Julian Noble	6d96819ccb	goal detail housekeeping: embed trap script, record reopen_stdin races, note twapi drift G-036: the CloseHandle trap script is embedded in the detail file (was a dangling reference to session-ephemeral scratchpad). G-038: the repl::reopen_stdin race analysis from the G-036 investigation is written in (the prior cross-reference pointed at content that existed only in conversation), and the goal now explicitly owns that path's fate - it runs for real on console-EOF at an interactive prompt, and the caller-driven restart should cover that scenario so reopen_stdin can be retired. G-037: twapi vendorlib(5.0b1)/kit-vfs(5.2.0) drift recorded - divergence exists in both directions, so the sync step needs explicit authority semantics. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	1 month ago
Julian Noble	b0f5911da0	G-038 detail: subshell continuity note - piped `subshell <name>` landing interactive User note recorded: with per-subshell configs (G-008/G-009), piping `subshell <name>` then going interactive should reasonably land IN that subshell (quit unwinding to the initial shell). Does not fall out of the continuity changes automatically - the subshell stack is repl control flow and unwinds at pipe-EOF under the current nested model. Options recorded: re-enter captured subshell stack on restart (fights nesting) vs the natural fit under G-002 non-nested subshells with console targeting (reattach reopened console to innermost active subshell). Also noted: a -subshell flag on the shell subcommand as the primary entry (G-032 launcher-args candidate). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	1 month ago
Julian Noble	b134b514d1	G-038 reworked (proposed): piped-to-interactive restart continues the same session User identified the general least-surprise violation beyond the original error-retention draft: `'set ::jjj blah' \| punkexe` reaches an interactive prompt where ::jjj does not exist - the piped-EOF restart silently swaps in a fresh codethread/code interp, discarding variables, procs, packages, cwd and errorInfo. Goal reworked to session continuity via the caller-driven restart identified during G-036 (repl::start eof-restart done-mode without codethread teardown; app-punkshell restarts on the reopened console without repl::init). Error inspectability becomes an acceptance criterion that likely falls out free (no re-init means no boot-noise re-stamping of errorInfo); the standalone error-record mechanism is demoted to a recorded fallback. Detail file renamed to match (slug change, ID preserved). Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com	1 month ago

10 Commits (5e956f74190df87465ebcb3cb96b649224f93426)