From 59bdb1ec49bb6fe4bcf1b9a72b0cfa521e94270f Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 28 Jul 2026 17:14:40 +1000 Subject: [PATCH] G-033 achieved: flip, archive, reference sweep (proj: visitor mode live) 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 --- GOALS-archive.md | 4 ++ GOALS.md | 4 -- goals/G-016-projects-work-git-discovery.md | 10 ++-- goals/G-018-zig-plain-tclsh-kits.md | 3 +- goals/G-031-componentized-kit-boot.md | 5 ++ goals/G-032-launcher-punkargs.md | 10 ++-- goals/G-035-mixed-tm-pkgindex-provision.md | 3 +- goals/G-043-subshell-definition-plugins.md | 3 +- goals/G-047-declared-primary-vcs.md | 8 +-- goals/G-089-scriptlib-kits-and-modes.md | 9 ++-- .../G-033-proj-mode-cwd-project.md | 53 ++++++++++++++++++- 11 files changed, 90 insertions(+), 22 deletions(-) rename goals/{ => archive}/G-033-proj-mode-cwd-project.md (79%) diff --git a/GOALS-archive.md b/GOALS-archive.md index 4d8474cc..551eb9e5 100644 --- a/GOALS-archive.md +++ b/GOALS-archive.md @@ -32,6 +32,10 @@ Acceptance: from a running punk session's code interp, without `repl eval`: `con Scope: src/vfs/_config/punk_main.tcl; src/lib/app-punkshell/punkshell.tcl (script path or a leaner dedicated app package) Acceptance: piping commands to ` script` runs them and terminates at stdin EOF with no trailing `exit` required, exit code 0 on success; a failing piped command terminates the process with a nonzero exit code and the error on stderr, never landing in an interactive shell regardless of console availability or PUNK_PIPE_EOF; ` script [...]` executes the file with conventional ::argv0/::argv and propagates its error status the same way; the script path installs none of the `shell` subcommand's shellfilter stacks/transforms and the launch plumbing itself emits nothing on stdout/stderr (the current stub's stderr diagnostics removed) so exec-style callers see only the script's own output; the motivating example works with no package require boilerplate: piping `dev projects.work **` to ` script` emits the matching-project table and exits 0, because the script interp carries the default punk shell module/alias environment. +### G-033 [achieved 2026-07-28] `proj:` package-mode scope prefix: visitor binary resolves dev/src against the cwd's project → detail: goals/archive/G-033-proj-mode-cwd-project.md +Scope: src/vfs/_config/punk_main.tcl (package-mode dispatch and boot-time root discovery); src/modules/punk/repo-999999.0a1.0.tm (find_project / is_project_root - reuse or lean boot mirror); bin/AGENTS.md (mode docs) +Acceptance: ` proj:internal-src shell` (the documented canonical visitor invocation - kit copies win same-version ties, protecting the visiting shell's infrastructure; `proj:src` is the documented faithful-vintage variant where the project's copies win) launched from within a punk project's tree discovers the project root by walking up from cwd to the nearest VCS repo root and feeds it to the existing src-mode path machinery (src/modules, src/bootsupport/modules, src/vendormodules on the module path, src/lib on auto_path), so the session loads the project's dev-versioned modules while ordinary version resolution still lets the project supply anything the kit lacks or exceeds; the launch reports the detected project root and effective path precedence (never a silent rebind); with no project found walking up from cwd, or a `proj:` string containing no root-using block (dev/src), it warns and proceeds without false rebind; proven for a standalone binary outside any source tree (internal = kit contents regardless of binary location) against a project that builds no executable (tomlish is the natural first); exe-relative `src`/`dev` discovery is unchanged for a binary that IS in a project's bin/; the packagemode help text drafted in the detail file becomes the live punk::args documentation when implemented (rendered via G-032). + ### G-036 [achieved 2026-07-08] Root-cause the Tcl 9 console+udp worker-thread event-loop wedge; minimal repro for possible upstream reporting → detail: goals/archive/G-036-tcl9-udp-console-worker-wedge.md Scope: src/modules/shellthread-999999.0a1.0.tm; src/bootsupport/modules/shellthread-1.6.2.tm; src/modules/shellfilter-999999.0a1.0.tm (as characterised - no product-code changes required by this goal; the punkshell mitigations are separate fixes) Acceptance: (reworked 2026-07-08 after the root cause was found) the wedge mechanism is identified and written up in the detail file - DONE: bundled tcludp 1.0.12's Windows per-thread UDP_ExitProc closes the process-global synchronization events, proven by dump handle-table analysis plus a live CloseHandle breakpoint and confirmed by the upstream 1.0.12->1.0.13 diff, which already fixes it (so no upstream report is required; the standalone minimal repro originally required here is waived as moot by the user); the tcl9 kits bundle tcludp >= 1.0.13 with the in-context batch harness baseline resolved - DONE 2026-07-08 (run-2 syslog workers alive vs the 4/4-wedged 1.0.12 baseline); DONE 2026-07-08 (punk::lib 0.3.0 has_libbug_udp_threadexit, surfaced via 'help tcl' in punk 0.2.1): a has_bug-style detection in the punkshell check machinery (in the vein of punk::lib::check::has_tclbug_* / punk::console::check::has_bug_*, surfaced through the same reporting as 'help tcl'/'help console') reports the vulnerable combination - simple version-based detection (loaded/bundled tcludp < 1.0.13 on Tcl 9 Windows) is sufficient, no behavioural probe needed; loose-end decisions (punk8win 8.6 kit's udp 1.0.12 swap; optional upstream tickets for residual tcludp trunk weaknesses) recorded in the detail file when made (open as of 2026-07-08 - non-gating). diff --git a/GOALS.md b/GOALS.md index 3c1be4ec..4098c8f4 100644 --- a/GOALS.md +++ b/GOALS.md @@ -189,10 +189,6 @@ Detail: goals/G-031-componentized-kit-boot.md Scope: src/vfs/_config/ (default dispatch); src/lib/app-punkshell and sibling app packages as touched Detail: goals/G-032-launcher-punkargs.md -### G-033 [proposed] `proj:` package-mode scope prefix: visitor binary resolves dev/src against the cwd's project -Scope: src/vfs/_config/punk_main.tcl (package-mode dispatch and boot-time root discovery); src/modules/punk/repo-999999.0a1.0.tm (find_project / is_project_root - reuse or lean boot mirror); bin/AGENTS.md (mode docs) -Detail: goals/G-033-proj-mode-cwd-project.md - ### G-034 [proposed] Zip-based #modpod modules mount in the shell code-interp on Tcl 8.6 Scope: src/modules/punk/mix/ (modpod mount path); vfs::zip availability in the repl code interp; src/modules/punk/cap/ (templates capability handler) Detail: goals/G-034-modpod-codeinterp-tcl86.md diff --git a/goals/G-016-projects-work-git-discovery.md b/goals/G-016-projects-work-git-discovery.md index b2434105..7dbd6f15 100644 --- a/goals/G-016-projects-work-git-discovery.md +++ b/goals/G-016-projects-work-git-discovery.md @@ -87,8 +87,10 @@ Result-shape considerations: (reliable piped invocation - achieved 2026-07-07) and G-017 (agent guidance documenting the call). - The `-cd` / `-detail` options and case-insensitive glob behaviour of the existing command are contracts to preserve. -- G-033 relationship (recorded 2026-07-24 after overlap review): proj:'s - cwd-anchored root discovery (punk::repo find_project/is_project_root) is the - interactive counterpart of this goal's registry enumeration - a project found by - one surface should be found by the other. +- G-033 relationship (recorded 2026-07-24 after overlap review; G-033 achieved + 2026-07-28 - see goals/archive/G-033-proj-mode-cwd-project.md): proj:'s + cwd-anchored root discovery (delivered as a lean boot mirror of + punk::repo find_project/is_project_root - ::punkboot::proj_root_find in + punk_main.tcl) is the interactive counterpart of this goal's registry + enumeration - a project found by one surface should be found by the other. - Archived-goal references in this file: G-049 achieved 2026-07-10 (goals/archive/G-049-punkargs-parse-status-model.md). diff --git a/goals/G-018-zig-plain-tclsh-kits.md b/goals/G-018-zig-plain-tclsh-kits.md index 41c72cf1..176fc4d3 100644 --- a/goals/G-018-zig-plain-tclsh-kits.md +++ b/goals/G-018-zig-plain-tclsh-kits.md @@ -69,4 +69,5 @@ This defines one end of a deliberate spectrum of buildable executables: make.tcl surfacing of suite builds landed as G-104 (achieved 2026-07-25 - see goals/archive/G-104-maketcl-buildsuite-surface.md: 'make.tcl buildsuite list/info/build'). The executable-spectrum framing - this goal contributed remains referenced from G-019/G-023/G-031/G-033. + this goal contributed remains referenced from G-019/G-023/G-031 and G-033 + (achieved 2026-07-28 - see goals/archive/G-033-proj-mode-cwd-project.md). diff --git a/goals/G-031-componentized-kit-boot.md b/goals/G-031-componentized-kit-boot.md index 670f53a4..970f43dc 100644 --- a/goals/G-031-componentized-kit-boot.md +++ b/goals/G-031-componentized-kit-boot.md @@ -80,6 +80,11 @@ permanently own - a thousand lines of boot code. (boot-core vintage reporting), G-032 (punk::args-defined dispatch built on the registration model), G-012 (layout payload hygiene), G-018 (plain tclsh kits deliberately carry NO punk boot layer - out of scope here). +- G-033 (archived) recorded a fork-drift datapoint for this goal: the proj: + scope prefix and its `::punkboot::proj_root_find` walk-up landed in + punk_main.tcl only - project_main.tcl still lacks src mode and now also + proj:, widening the divergence this consolidation resolves - see + goals/archive/G-033-proj-mode-cwd-project.md. - G-089 relationship (recorded 2026-07-24 after overlap review): its boot-provided packagemode hint (for scriptlib resolution) is a boot-core interface this goal's registration model should carry - one boot "running diff --git a/goals/G-032-launcher-punkargs.md b/goals/G-032-launcher-punkargs.md index 2f59efbe..6a9dfe7e 100644 --- a/goals/G-032-launcher-punkargs.md +++ b/goals/G-032-launcher-punkargs.md @@ -27,11 +27,13 @@ in `-help` by registration alone. with @cmd summaries, package-mode leader documented) and per-subcommand options. ` -help`, ` help `, and ` -help` all render tabled usage. -- The packagemode leader's help text is pre-drafted in G-033's detail file +- The packagemode leader's help text is LIVE as of G-033's achievement + (2026-07-28, goals/archive/G-033-proj-mode-cwd-project.md): the drafted text (block semantics, ordering-as-tie-break rule, the `proj:` scope prefix with - the kit-first `proj:internal-src` canonical example) - use that as the source - text, noting the `proj:` portions go live only when G-033 implements the - prefix. + the kit-first `proj:internal-src` canonical example) now sits as the + packagemode leader in punk::args::moduledoc::punkexe 0.1.1's + `(script)::punkexe` definition. This goal's remaining lane is the + rendering/parse wiring that consumes it. - Parse errors on declared subcommands produce punk::args usage errors (tabled), not silent fallthrough. The unknown-first-arg -> script reclassification survives only where it does not swallow obvious mistakes - diff --git a/goals/G-035-mixed-tm-pkgindex-provision.md b/goals/G-035-mixed-tm-pkgindex-provision.md index 67e22c95..f0321efe 100644 --- a/goals/G-035-mixed-tm-pkgindex-provision.md +++ b/goals/G-035-mixed-tm-pkgindex-provision.md @@ -62,7 +62,8 @@ is a realistic hazard - and same-version-different-content drift (the ## Notes - Related: the shadowing pin-tests (same suite family - this goal's tests - extend them), G-033 (visitor-mode path mixing makes cross-form collisions + extend them), G-033 (achieved 2026-07-28, goals/archive/G-033-proj-mode-cwd-project.md - + visitor-mode path mixing is now live, making cross-form collisions more reachable: a kit's internal libs vs a visited project's .tm trees), G-026/G-024 (same-version drift provenance), punk::packagepreference 0.1.1 (its moduledoc auto-load hook lives in exactly this machinery). diff --git a/goals/G-043-subshell-definition-plugins.md b/goals/G-043-subshell-definition-plugins.md index b589838f..a1b07bf2 100644 --- a/goals/G-043-subshell-definition-plugins.md +++ b/goals/G-043-subshell-definition-plugins.md @@ -99,7 +99,8 @@ Phases: is a natural bundle of this goal's composition plus theme/restrictions), G-002/G-010 (non-nested subshells - restore-on-switch semantics), G-003 (restricted subshells - a restricted subshell composing plugin commandsets needs the expose/hide interaction - considered), G-033 (visitor binaries - shellproject-anchored resources vs cwd-project + considered), G-033 (achieved 2026-07-28, goals/archive/G-033-proj-mode-cwd-project.md - + visitor binaries: shellproject-anchored resources vs cwd-project resources, same anchor question as the templates pathtypes). - Rough edges catalogued 2026-07-08 (this goal's acceptance covers the first two): punk::cap pkg_unregister "destroy api objects?" review; silent unhandled-capability diff --git a/goals/G-047-declared-primary-vcs.md b/goals/G-047-declared-primary-vcs.md index a829a5d9..c9b22ed0 100644 --- a/goals/G-047-declared-primary-vcs.md +++ b/goals/G-047-declared-primary-vcs.md @@ -49,6 +49,8 @@ The original G-047 draft (2026-07-08) declared a single team-wide primary with t three layout copies carry the bake/bakehouse vocabulary); its AGENTS.md workflow edits landed - this goal's Commit-Conventions edit touches other sections of the same docs. -- G-033 relationship: its proj: visitor root discovery and this goal's primary-VCS - anchoring share the punk::repo::is_project_root marker as the root test - a nested - punkproject.toml must never fool either reader. +- G-033 relationship (G-033 achieved 2026-07-28 - see + goals/archive/G-033-proj-mode-cwd-project.md): its proj: visitor root discovery + (boot mirror ::punkboot::proj_root_find in punk_main.tcl) and this goal's + primary-VCS anchoring share the punk::repo::is_project_root marker as the root + test - a nested punkproject.toml must never fool either reader. diff --git a/goals/G-089-scriptlib-kits-and-modes.md b/goals/G-089-scriptlib-kits-and-modes.md index 25e73dbe..7368050f 100644 --- a/goals/G-089-scriptlib-kits-and-modes.md +++ b/goals/G-089-scriptlib-kits-and-modes.md @@ -47,9 +47,12 @@ Findings from the 2026-07-18 lib: extensionless work (punk::path 0.3.0): ## Notes -- Related goals: G-033 (proj: scope prefix - the visitor root discovery this - goal's proj: scriptlib clause rides on; its notes already flag that - `proj:... script` benefits), G-018/G-019 (installable/trimmed kits), +- Related goals: G-033 (achieved 2026-07-28, goals/archive/G-033-proj-mode-cwd-project.md - + the proj: visitor root discovery this goal's proj: scriptlib clause rides on + is now live: ::punkboot::proj_root_find in punk_main.tcl remains defined + post-boot, so this goal can re-derive the visited root; the boot-interface + packagemode hint this goal needs is still absent - the discovered proj root + is a boot-local variable, not exposed), G-018/G-019 (installable/trimmed kits), G-015 (achieved - script subcommand, goals/archive/G-015-script-subcommand-piped-stdin.md). - `lib:.kit` dispatch (restored in punkshell 0.14.0 via punk::path 0.3.0's known-extensions fix) has no committed test fixture - a `.kit` diff --git a/goals/G-033-proj-mode-cwd-project.md b/goals/archive/G-033-proj-mode-cwd-project.md similarity index 79% rename from goals/G-033-proj-mode-cwd-project.md rename to goals/archive/G-033-proj-mode-cwd-project.md index f5307af6..72c93b7c 100644 --- a/goals/G-033-proj-mode-cwd-project.md +++ b/goals/archive/G-033-proj-mode-cwd-project.md @@ -1,6 +1,6 @@ # G-033 `proj:` package-mode scope prefix: visitor binary resolves dev/src against the cwd's project -Status: proposed +Status: achieved 2026-07-28 Scope: src/vfs/_config/punk_main.tcl (package-mode dispatch and boot-time root discovery); src/modules/punk/repo-999999.0a1.0.tm (find_project / is_project_root - reuse or lean boot mirror); bin/AGENTS.md (mode docs) Goal: a `proj:` prefix on the package-mode string (e.g. `punkshell proj:internal-src shell`) makes the dev/src path blocks resolve against the punk project containing the current working directory - walking up to the nearest VCS repo root, the marker punk::repo::is_project_root already uses - instead of the executable's own project, so an installed ("visitor") punkshell binary, including one downloaded standalone with no source tree around it, can interactively explore a project that builds no shell-capable binary or no binary at all; the prefix scopes WHICH project, staying outside the ordered dash-list whose block order remains the same-version tie-break dial, and the explicit prefix gates the behaviour so no `cd` silently rebinds a normal launch. Acceptance: ` proj:internal-src shell` (the documented canonical visitor invocation - kit copies win same-version ties, protecting the visiting shell's infrastructure; `proj:src` is the documented faithful-vintage variant where the project's copies win) launched from within a punk project's tree discovers the project root by walking up from cwd to the nearest VCS repo root and feeds it to the existing src-mode path machinery (src/modules, src/bootsupport/modules, src/vendormodules on the module path, src/lib on auto_path), so the session loads the project's dev-versioned modules while ordinary version resolution still lets the project supply anything the kit lacks or exceeds; the launch reports the detected project root and effective path precedence (never a silent rebind); with no project found walking up from cwd, or a `proj:` string containing no root-using block (dev/src), it warns and proceeds without false rebind; proven for a standalone binary outside any source tree (internal = kit contents regardless of binary location) against a project that builds no executable (tomlish is the natural first); exe-relative `src`/`dev` discovery is unchanged for a binary that IS in a project's bin/; the packagemode help text drafted in the detail file becomes the live punk::args documentation when implemented (rendered via G-032). @@ -188,3 +188,54 @@ ships with the prefix, not before): already flag that `proj:... script` benefits; the two share the same root walk and the same never-silent rebind rule. - Archived-goal references in this file: G-015 achieved 2026-07-07 (goals/archive/G-015-script-subcommand-piped-stdin.md). +- Related: G-043 references this goal one-directionally (visitor binaries: shellproject-anchored + resources vs cwd-project resources) - relationship recorded at activation (2026-07-28 + goals_xref survey; the other moderate-score overlaps G-123/G-127/G-131 share only + punk_main.tcl/bin co-location, no proj: semantics). + +## Progress + +Implemented and verified 2026-07-28 (activation and achievement same day; punkshell +0.29.0, punk::args::moduledoc::punkexe 0.1.1): + +- Boot chicken-and-egg decision: option (a) - lean inline walk-up in punk_main.tcl + using only Tcl builtins, as `::punkboot::proj_root_find` (remains defined post-boot + for probing, like the G-129 mount procs). It mirrors punk::repo::is_project_root + including the is_candidate_root requirements (unwise-path exclusion; ./src plus one + of src/modules, src/vfs, src/scriptapps, or punkproject.toml) so boot-time and + runtime discovery agree (the G-016 findable-by-both principle). One recorded + divergence: `.git` is accepted as file OR directory (worktree/submodule checkouts), + where punk::repo::is_git_root requires a directory. +- proj: with an invalid mode remainder is not consumed (whole arg passes through as + subcommand/script, matching the existing invalid-mode fallthrough); bare `proj:` + is consumed as internal and then warned as having no root-using block. +- dev under proj: resolves /modules{,_tcl} and /lib{,_tcl} + only - the exe-relative and cwd-relative lib candidates of the exe-anchored dev + mode are deliberately not mixed in. +- Verification (punk91 kit rebaked with the new boot; standalone copy of the kit + placed in a session scratchpad outside any source tree): + - `punkvisit.exe proj:internal-src script ` from c:/repo/jn/tclmodules/tomlish + (fossil root, builds no executable): root detected and reported, precedence line + reported, tomlish src paths appended after kit-internal paths, and + `package require tomlish` -> 999999.0a1.0 sourced from tomlish/src/modules. + - Same from C:/repo/jn/shellspy: "src mode: registered 6 #modpod modules" (modpod + scanner fed by the visited root) and the punkexe moduledoc loads from the visited + project's src/modules at 999999.0a1.0. + - `proj:src` variant: tomlish src paths BEFORE kit-internal paths (faithful-vintage + ordering). + - No-project case (cwd = scratchpad): warns and proceeds, script still runs, + dev/src unbound. + - `proj:os`: warns 'proj:' has no effect (no dev/src block). + - Exe-relative regression: `bin/punk91 src script ` unchanged (modpods + registered, dev module versions load); piped `punk` subcommand under + proj:internal-src evaluates in the shell environment with the visited project's + modules (its exit code 1 on piped `exit` is pre-existing, present without proj:). +- packagemode help text is live: the drafted leader text (extended with the proj: + wording) sits in punk::args::moduledoc::punkexe 0.1.1 as the packagemode leader of + `(script)::punkexe` (@leaders max raised to 2); rendering/parse wiring remains + G-032's lane. The freshly deployed kit still carries moduledoc 0.1.0 - the 0.1.1 + stamp reaches kits at the next vfscommonupdate promotion (deliberately not run from + a dirty tree in this change-set). +- Docs: bin/AGENTS.md launch-package-modes section (proj: contract + canonical + invocations), src/vfs/AGENTS.md punk_main contract line, ARCHITECTURE.md entry-point + bullet; CHANGELOG 0.29.0 entry (minor bump - new launch invocation).