diff --git a/GOALS.md b/GOALS.md index b12b948f..5482e0d4 100644 --- a/GOALS.md +++ b/GOALS.md @@ -111,7 +111,7 @@ Scope: src/modules/punk/console-999999.0a1.0.tm; src/modules/opunk/console-99999 Detail: goals/G-011-console-stderr-semantics.md ### G-012 [proposed] Template system: inert VCS-config payloads and explicit layout refresh -Scope: src/project_layouts/; src/make.tcl; src/modules/punk/mix/ (layout instantiation); fauxlink module (bootsupport 0.1.1 - promoted if chosen as mechanism) +Scope: src/project_layouts/; src/make.tcl; src/modules/punk/mix/ (layout instantiation); fauxlink module (bootsupport 0.2.0 - promoted if chosen as mechanism) Detail: goals/G-012-template-payload-safety.md ### G-013 [proposed] Raw mode as the repl's default input mode @@ -119,7 +119,7 @@ Scope: src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/console-999999.0a Detail: goals/G-013-raw-mode-default.md ### G-014 [proposed] ::punk::config stored configuration: toml files with named-subshell scoping -Scope: src/modules/punk/config-0.1.tm; src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/repl/codethread-999999.0a1.0.tm; src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) +Scope: src/modules/punk/config-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/repl/codethread-999999.0a1.0.tm; src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) Detail: goals/G-014-punk-config-toml.md ### G-016 [proposed] `projects.work` discovers git-based projects alongside fossil @@ -195,7 +195,7 @@ Scope: src/modules/punk/mix/ (modpod mount path); vfs::zip availability in the r Detail: goals/G-034-modpod-codeinterp-tcl86.md ### G-035 [proposed] Characterise mixed .tm / pkgIndex.tcl provision of the same package -Scope: src/tests/modules/punk/libunknown/testsuites/ (characterization suite); src/modules/punk/libunknown-0.1.tm and src/modules/punk/packagepreference-999999.0a1.0.tm (as characterised, fixed only if outright bugs surface); src/modules/AGENTS.md + src/lib/AGENTS.md (resulting guidance) +Scope: src/tests/modules/punk/libunknown/testsuites/ (characterization suite); src/modules/punk/libunknown-0.2.2.tm and src/modules/punk/packagepreference-999999.0a1.0.tm (as characterised, fixed only if outright bugs surface); src/modules/AGENTS.md + src/lib/AGENTS.md (resulting guidance) Detail: goals/G-035-mixed-tm-pkgindex-provision.md ### G-038 [proposed] Piped-to-interactive restart continues the same session (context preserved) @@ -203,11 +203,11 @@ Scope: src/lib/app-punkshell/punkshell.tcl (eof-restart handover); src/modules/p Detail: goals/G-038-piped-session-continuity.md ### G-042 [proposed] Subshell-declared help topics via punk::config with defined shadowing policy -Scope: src/modules/punk-999999.0a1.0.tm (::punk::helptopic registry); src/modules/punk/config-0.1.tm (stored declaration source); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit hooks) +Scope: src/modules/punk-999999.0a1.0.tm (::punk::helptopic registry); src/modules/punk/config-999999.0a1.0.tm (stored declaration source); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit hooks) Detail: goals/G-042-subshell-help-topics.md ### G-043 [proposed] Subshell definition plugins: punk.subshell capability composing commandsets, help topics and config defaults -Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler); src/modules/punk/overlay-999999.0a1.0.tm (commandset composition); src/modules/punk/pluginmgr-0.5.1.tm (discovery/trust layer); src/modules/punk/mix-999999.0a1.0.tm (init wiring precedent); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit); src/modules/punk/config-0.1.tm (data-declaration overlap with G-014/G-042) +Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler); src/modules/punk/overlay-999999.0a1.0.tm (commandset composition); src/modules/punk/pluginmgr-0.5.1.tm (discovery/trust layer); src/modules/punk/mix-999999.0a1.0.tm (init wiring precedent); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit); src/modules/punk/config-999999.0a1.0.tm (data-declaration overlap with G-014/G-042) Detail: goals/G-043-subshell-definition-plugins.md ### G-044 [proposed] punk::args-driven interactive command completion and hinting in the repl (raw mode primary) @@ -367,7 +367,7 @@ Scope: src/buildsuites/suite_tcl90/ (build905.zig debug knobs + tcl::test wiring Detail: goals/G-108-buildsuite-debug-tier.md ### G-109 [proposed] libunknown manifest-declared multi-name discovery for zip-based .tm modules -Scope: src/modules/punk/libunknown-0.2.1.tm (scan/registration); modpod (manifest emission + load stub; canonical source c:/repo/jn/tclmodules/modpod, vendored copies as consumed); src/modules/punk/mix/ (modpod wrap tooling as touched); src/tests/modules/punk/libunknown/ (new suites + scan-performance characterization) +Scope: src/modules/punk/libunknown-0.2.2.tm (scan/registration); modpod (manifest emission + load stub; canonical source c:/repo/jn/tclmodules/modpod, vendored copies as consumed); src/modules/punk/mix/ (modpod wrap tooling as touched); src/tests/modules/punk/libunknown/ (new suites + scan-performance characterization) Detail: goals/G-109-libunknown-manifest-multiname-tm.md ### G-110 [proposed] Shared-lib extraction cache: single content-addressed user cache vs per-run temp copies (investigation) diff --git a/goals/G-012-template-payload-safety.md b/goals/G-012-template-payload-safety.md index 037c50d8..cc731bd5 100644 --- a/goals/G-012-template-payload-safety.md +++ b/goals/G-012-template-payload-safety.md @@ -1,7 +1,7 @@ # G-012 Template system: inert VCS-config payloads and explicit layout refresh Status: proposed -Scope: src/project_layouts/; src/make.tcl; src/modules/punk/mix/ (layout instantiation); fauxlink module (bootsupport 0.1.1 - promoted if chosen as mechanism) +Scope: src/project_layouts/; src/make.tcl; src/modules/punk/mix/ (layout instantiation); fauxlink module (bootsupport 0.2.0 - promoted if chosen as mechanism) Goal: project layouts carry no live nested VCS-config files - template .gitignore payloads are stored inert (renamed, or fauxlink-encoded) and materialized at project generation - and src/make.tcl has an explicit punkcheck-tracked step that refreshes layout payloads from their canonical sources. Acceptance: a scan of src/project_layouts finds no file named .gitignore, and git check-ignore --no-index over every layout file matches only root-.gitignore rules (nested rules provably inert); a project generated from each affected layout receives a working .gitignore whose content matches the canonical payload/target; after editing a canonical source (e.g. root .gitignore), the make.tcl template-refresh step updates the derived layout payloads (punkcheck-tracked), covering vendor/punk layouts as well as custom/_project; the previously hidden template files (layout READMEs, vendored TODO-class files) remain git-tracked without per-file force-add exceptions. @@ -38,7 +38,7 @@ payload drift is unmanaged. instantiation renames it to `.gitignore` in the generated project. Simple, no new dependency; templates keep a literal copy (drift handled by the refresh step). - *Fauxlink*: payload stored as `#.fauxlink` (see fauxlink module, - currently bootsupport 0.1.1) and resolved at generation. Inert for git by construction, + currently bootsupport 0.2.0) and resolved at generation. Inert for git by construction, and the target can be the canonical root `.gitignore` itself - eliminating copy drift rather than managing it. Requires generation-time resolution in punk::mix and possibly promoting fauxlink to a first-class module dependency. @@ -83,7 +83,7 @@ payload drift is unmanaged. treatment as the .gitignore payloads. - fauxlink background: target encoded in the filename (`+` for `/`, url-style escapes), no filesystem support required, application-driven resolution - see - `src/bootsupport/modules/fauxlink-0.1.1.tm` doctools header. + `src/bootsupport/modules/fauxlink-0.2.0.tm` doctools header. - Verification tie-in: the dual-VCS sync checks in `.fossil-settings/AGENTS.md` double as a regression detector for this class - after this goal, the "git-tracked invisible to fossil" comparison should show no template-payload entries. diff --git a/goals/G-014-punk-config-toml.md b/goals/G-014-punk-config-toml.md index 8332f1b4..fb30751e 100644 --- a/goals/G-014-punk-config-toml.md +++ b/goals/G-014-punk-config-toml.md @@ -1,7 +1,7 @@ # G-014 ::punk::config stored configuration: toml files with named-subshell scoping Status: proposed -Scope: src/modules/punk/config-0.1.tm; src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/repl/codethread-999999.0a1.0.tm; src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) +Scope: src/modules/punk/config-999999.0a1.0.tm; src/modules/punk/repl-999999.0a1.0.tm; src/modules/punk/repl/codethread-999999.0a1.0.tm; src/vendormodules/tomlish-*.tm (vendored; canonical source in the external tomlish project space) Goal: ::punk::config loads stored configuration from toml files in the XDG-located config dir - parsed via the vendored tomlish module, never an ad-hoc parser - and consumers resolve settings with per-named-subshell overrides, so features like the G-013 debug-view startup defaults read declared user configuration instead of hardcoded fallbacks. Acceptance: a setting declared in a toml file under the XDG-located config dir is visible through the punk::config API at repl startup, and with no config files present built-in defaults apply with no errors beyond the existing missing-dir notice; a named subshell resolves its own overriding value for a key also defined at the parent/default scope, and a subshell with no override inherits the outer value (proven with at least one real key); at least one shipped feature (the G-013 editbuf-view startup default is the natural first) reads its default through this path rather than a hardcoded value; all toml reading/writing in punk::config goes through the tomlish module, and the tomlish API procs punk::config consumes carry punk::args (PUNKARGS) documentation - added upstream in the tomlish project and re-vendored here before punk::config implementation proceeds. @@ -25,8 +25,9 @@ shell keeps it off). ## Precondition: tomlish punk::args documentation All toml parsing/serialisation goes through the tomlish module - no ad-hoc toml -parsing in punk::config. tomlish is vendored (src/vendormodules/tomlish-1.1.8.tm -at time of writing, with a bootsupport copy) but its canonical source lives in a +parsing in punk::config. tomlish is vendored (src/vendormodules/tomlish-1.1.12.tm +at time of writing, with a bootsupport copy; older vendored versions coexist in +the series) but its canonical source lives in a separate project space under our control: documentation work happens upstream there and lands here by re-vendoring, not by editing the vendored copies. diff --git a/goals/G-035-mixed-tm-pkgindex-provision.md b/goals/G-035-mixed-tm-pkgindex-provision.md index ee5775d6..a3e319bc 100644 --- a/goals/G-035-mixed-tm-pkgindex-provision.md +++ b/goals/G-035-mixed-tm-pkgindex-provision.md @@ -1,7 +1,7 @@ # G-035 Characterise mixed .tm / pkgIndex.tcl provision of the same package Status: proposed -Scope: src/tests/modules/punk/libunknown/testsuites/ (characterization suite); src/modules/punk/libunknown-0.1.tm and src/modules/punk/packagepreference-999999.0a1.0.tm (as characterised, fixed only if outright bugs surface); src/modules/AGENTS.md + src/lib/AGENTS.md (resulting guidance) +Scope: src/tests/modules/punk/libunknown/testsuites/ (characterization suite); src/modules/punk/libunknown-0.2.2.tm and src/modules/punk/packagepreference-999999.0a1.0.tm (as characterised, fixed only if outright bugs surface); src/modules/AGENTS.md + src/lib/AGENTS.md (resulting guidance) Goal: the behaviour when the same package is provided both as a .tm module and as a pkgIndex.tcl-based library - same or differing versions, under the standard package unknown, punk::libunknown and punk::packagepreference - is characterised by committed tests, and the currently informal working rule ("avoid mixing provision forms for one package - unexpected behaviour even with libunknown's improvements") is either substantiated with the specific failure modes named in AGENTS.md guidance, or retired if the characterisation shows the machinery now handles mixing predictably. Acceptance: a committed test suite (extending src/tests/modules/punk/libunknown/testsuites/) characterises at least: same name+version provided via .tm and via pkgIndex.tcl (which registration wins, and whether it is deterministic across scan-trigger orderings) under the standard scanner, under punk::libunknown, and with punk::packagepreference active; differing versions across the two forms (version selection integrity including package prefer latest, and whether the losing form's registration lingers); re-registration effects (package forget then re-require crossing forms); surprising-but-accepted behaviours are pinned with GAP/known-quirk comments (the fossilmove characterization pattern), outright bugs fixed or filed as goals; the resulting do/don't guidance lands in src/modules/AGENTS.md and src/lib/AGENTS.md naming the characterised failure modes (or explicitly lifting the avoid-mixing rule if unwarranted). diff --git a/goals/G-042-subshell-help-topics.md b/goals/G-042-subshell-help-topics.md index 32797a0b..5202029a 100644 --- a/goals/G-042-subshell-help-topics.md +++ b/goals/G-042-subshell-help-topics.md @@ -1,7 +1,7 @@ # G-042 Subshell-declared help topics via punk::config with defined shadowing policy Status: proposed -Scope: src/modules/punk-999999.0a1.0.tm (::punk::helptopic registry); src/modules/punk/config-0.1.tm (stored declaration source); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit hooks) +Scope: src/modules/punk-999999.0a1.0.tm (::punk::helptopic registry); src/modules/punk/config-999999.0a1.0.tm (stored declaration source); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit hooks) Goal: a named subshell can declare its own help topics (name, aliases, summary, text content) in punk::config stored configuration - registered into the ::punk::helptopic registry on subshell entry and removed/restored on exit - so 'help' inside a customised subshell presents that subshell's topics with 'help topics' and 'i help' staying accurate (the registry already regenerates the punk::args definitions), under a defined precedence policy between topics and command-name fallthrough. Acceptance: a subshell whose configuration declares at least one custom topic shows it in 'help topics' and renders its configured content via 'help ' inside that subshell, and 'i help' lists it as a documented choice; on quit/switch-away the parent's topic set is restored (no leakage, proven by declaring a topic in a subshell and checking the parent after exit); configuration is read through punk::config (toml per G-014 - no ad-hoc parsing) and a shell with no topic configuration behaves unchanged; config-declared topics are text-content only - they cannot name code to execute (or a recorded design decision to the contrary with its sandboxing rationale in the detail file); the shadowing policy is implemented and documented: a declared topic colliding with a built-in topic is rejected (or explicitly overrides per a documented rule), a topic name shadowing a command name wins over command fallthrough as today with 'i '/'s ' documented as the command-help escape hatch; depends on G-014 for the stored-config substrate - the registry-side registration/restore mechanism may land earlier behind a programmatic API, with the config binding completing when G-014 lands. diff --git a/goals/G-043-subshell-definition-plugins.md b/goals/G-043-subshell-definition-plugins.md index 02f04b4a..b589838f 100644 --- a/goals/G-043-subshell-definition-plugins.md +++ b/goals/G-043-subshell-definition-plugins.md @@ -1,7 +1,7 @@ # G-043 Subshell definition plugins: punk.subshell capability composing commandsets, help topics and config defaults Status: proposed -Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler); src/modules/punk/overlay-999999.0a1.0.tm (commandset composition); src/modules/punk/pluginmgr-0.5.1.tm (discovery/trust layer); src/modules/punk/mix-999999.0a1.0.tm (init wiring precedent); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit); src/modules/punk/config-0.1.tm (data-declaration overlap with G-014/G-042) +Scope: src/modules/punk/cap-999999.0a1.0.tm (+ new punk.subshell handler); src/modules/punk/overlay-999999.0a1.0.tm (commandset composition); src/modules/punk/pluginmgr-0.5.1.tm (discovery/trust layer); src/modules/punk/mix-999999.0a1.0.tm (init wiring precedent); src/modules/punk/repl-999999.0a1.0.tm (subshell entry/exit); src/modules/punk/config-999999.0a1.0.tm (data-declaration overlap with G-014/G-042) Goal: a named subshell's definition - commandset imports (punk::overlay), help topics (the G-042 registry API) and config defaults - can be supplied by provider packages registered through a punk.subshell capability (punk::cap handler validating declarations) and/or declared in stored config (toml per G-014, naming already-installed commandset packages - absorbing punk::overlay's "toml configuration files for defining CLI configurations" todo), with punk::pluginmgr as the discovery/safe-interp trust layer for providers not already trusted - so entering a subshell composes its command surface and help from declarations instead of hardcoded init code. Acceptance: a provider package declaring the punk.subshell capability supplies at least a commandset binding (namespace + prefix) and a help-topic set for a named subshell, and entering that subshell composes them (prefixed commands callable, topics in 'help topics'/'i help') with quit/switch-away restoring the parent surface (no leakage); the punk.subshell punk::cap handler validates declarations (malformed declarations vetoed with a useful message); a subshell's commandset composition can equivalently be declared in stored config without a provider package (G-014 substrate), and the existing hardcoded 'dev' CLI composition keeps working unchanged; declarations for capabilities with no registered handler are discoverable (query or report - closing the silent punk.isbogus gap); punk::cap pkg_unregister leaves no stale handler state (the 'destroy api objects?' review resolved); punk::pluginmgr-based discovery/loading of a provider is either demonstrated end-to-end (including .tm module loading in the safe interp) or explicitly deferred with the remaining pluginmgr gaps recorded in the detail file; G-042's registry mechanism is consumed, not duplicated. diff --git a/goals/G-109-libunknown-manifest-multiname-tm.md b/goals/G-109-libunknown-manifest-multiname-tm.md index 2222b069..efe66b5b 100644 --- a/goals/G-109-libunknown-manifest-multiname-tm.md +++ b/goals/G-109-libunknown-manifest-multiname-tm.md @@ -1,7 +1,7 @@ # G-109 libunknown manifest-declared multi-name discovery for zip-based .tm modules Status: proposed -Scope: src/modules/punk/libunknown-0.2.1.tm (scan/registration); modpod (manifest emission + load stub; canonical source c:/repo/jn/tclmodules/modpod, vendored copies as consumed); src/modules/punk/mix/ (modpod wrap tooling as touched); src/tests/modules/punk/libunknown/ (new suites + scan-performance characterization) +Scope: src/modules/punk/libunknown-0.2.2.tm (scan/registration); modpod (manifest emission + load stub; canonical source c:/repo/jn/tclmodules/modpod, vendored copies as consumed); src/modules/punk/mix/ (modpod wrap tooling as touched); src/tests/modules/punk/libunknown/ (new suites + scan-performance characterization) Goal: a zip-based .tm (modpod) can declare additional package-require names - case variants (Thread/thread) and sub-packages - in a manifest at a well-known internal location, and punkshell's libunknown discovers those declarations during module scanning and registers them so package require of ANY declared name loads the single .tm file; real-disk scan performance is preserved: libunknown exists to fix slow-drive/large-multi-path-tree scan cost, so with manifest support enabled the worst-case target is parity with plain tclsh's builtin tm handler on the same tree (zipfs trees remain the fast path). Acceptance: a demonstration modpod .tm declaring a case-variant name and a sub-package name resolves via package require of each declared name on the tcl9 kit (8.6 covered, or its limitation recorded per G-034), from both a real-disk module path and a zipfs module path; the manifest location and format are documented and emitted by the modpod wrap tooling; plain-tclsh behaviour is documented prominently (the filename-derived name loads anywhere zipfs exists; extra names are punkshell/libunknown-only); a scan-performance characterization test compares libunknown-with-manifest-support against plain tclsh's builtin handler over a generated large multi-path real-disk tree and records the numbers in this file showing no worse than parity; extensive suites under src/tests/modules/punk/libunknown/ cover registration, case-variant and sub-package loading, refresh/epoch staleness, and the no-manifest fast path.