punkshell/GOALS.md

Project Goals

This file is the canonical, harness-agnostic index of technical project goals for punkshell. It is referenced from the root AGENTS.md Child DOX Index and is a required read for any non-trivial work, so that agents can discover goals whose scope intersects their work. It is deliberately summary-only so that reading it in full stays cheap: each entry carries ID, status, title and Scope plus a detail-file pointer, and the goal's full contract prose (Goal statement and Acceptance criterion) lives in its detail file under goals/ (see goals/AGENTS.md).

How agents use this index

1. Read this file in full (it is small by design).
2. Identify every entry whose Scope intersects the paths or module areas being inspected or edited. Scope lines name real repo paths, so path search works (e.g. searching this file for punk/repl finds the goals touching that module).
3. Before editing those paths, read the detail file of each intersecting goal.

Canonicality

• The index entry (this file) is canonical for ID, status, title and Scope.
• The detail file is canonical for the Goal statement and the Acceptance criterion.
• The tiers must not contradict: Status: and Scope: repeated in a detail file mirror the index. On disagreement the index wins for status/title/Scope and the detail file wins for Goal/Acceptance; fix the stale copy.

Format

Each goal is one compact entry:

### G-<id> [<status>] <short title>
Scope: <repo paths or module areas this goal touches>
Detail: goals/G-<id>-<slug>.md

Every goal has a detail file; it holds the canonical Goal and Acceptance plus any supporting prose (structure in goals/AGENTS.md). The index entry must stay safe standalone: title plus Scope alone must be enough that an agent who reads no detail file still does no harm.

Status tags

• proposed — not yet started; awaiting user confirmation to go active
• active — in progress
• achieved <YYYY-MM-DD> — done. The flip includes archiving: the entry moves to GOALS-archive.md as a summary record and its detail file to goals/archive/. Achieved entries do not accumulate in this file.
• abandoned — dropped; one line on why stays in the entry
• superseded by G-<id> — replaced; do not delete the old entry

Maintenance rules

• Goals are user-owned. Agents add or edit goal entries only at the user's request or with the user's explicit approval - never on their own initiative, and never in bulk from an agent's own survey of what "should" be goals.
• Suggesting is always allowed and encouraged when grounded in the work at hand: a discovered gap, a recurring manual step, a deferred design decision, or a natural follow-on that fits what is currently being worked on. Flag it as a candidate goal in conversation or the completion report, optionally with a drafted entry ready for approval. A suggestion is not an edit - nothing is written to this file or goals/ until the user approves per the proposal-first rule.
• The goal contract spans both tiers: the index entry (title, status tag, Scope) and the detail file's Goal: and Acceptance: lines.
• Proposal-first: before writing a new goal or changing any contract element in either tier, show the user the proposed wording - the full entry plus detail-file header for a new goal, the changed clause(s) for an edit - and get explicit approval. If the user already supplied or approved the exact wording this session, apply it and report what was written.
• Exception (sanctioned autonomous edit): an agent whose work satisfies a goal's Acceptance: (judged against the detail file's criterion, never the index entry alone) must flip that goal to achieved <date> as part of its DOX closeout pass, archive it (entry to GOALS-archive.md per that file's format, detail file to goals/archive/), and report the flip in its completion summary. If the detail file carries a ## Progress section, the flip additionally requires its remaining-work list to be resolved — empty, or each item verified satisfied; a partial increment never flips a goal. The flip records its verification evidence (what was verified, on which kits/runtimes, any remaining manual items) in the detail file's body — the Status: line stays bare achieved <date>, per the header field grammar in goals/AGENTS.md. The flip also includes a reference sweep of the live tier (see goals/AGENTS.md Archive rules): pending-tense mentions of the archived goal updated to reflect achievement, and any of its notes actionable for a live goal pointed to from that goal's ## Notes.
• Agents must not flip proposed → active. They flag it in their completion report for the user to confirm.
• Index entries carry no progress: the status tag is the only state the index records. Incremental progress on an active goal (what landed, what remains) is recorded in the detail file's ## Progress section, never as annotations on the index entry.
• Marking a goal superseded by G-<id> or abandoned includes a test sweep: search the tree (at minimum src/tests) for G-<old id> references and for the tests named in the goal's detail-file Acceptance, and record each affected test's disposition in the superseding goal's detail file (or the abandoned goal's own): pinned expectations that transfer to the new goal, pins that stand down to plain behaviour characterization, and any that lapse. The sweep never deletes, skips, or weakens a test on its own — that still requires explicit user direction per src/tests/AGENTS.md.
• Detail files may be updated without pre-approval when recording findings, decisions, or verification artifacts from work the user directed on that goal or its subject matter; report such updates in the completion summary. Edits to a detail file's Goal: or Acceptance: lines are contract changes and follow proposal-first.
• If a goal cannot be summarized safely by its title and Scope alone, that is a signal it is really two goals — split it.

Authoring a new goal (for agents)

When the user asks to "write a goal for X" or "help me draft a goal for Y", do the following:

1. Read this file in full and pick the next free G-<id>. IDs are never reused: the next free ID is one past the highest ID across GOALS.md and GOALS-archive.md (achieved goals leave this file, so ID gaps here are normal).
2. Ask the user only the questions below. Do not invent answers; ask them one at a time or batched if the user prefers. Stop asking once every required field has a real answer.
   • Scope: Which repo paths or module areas does this goal touch? (paths are preferred; module names are acceptable if paths are not yet known)
   • Goal: In one or a few sentences, what does done look like? Push for an outcome, not an activity ("X compiles to bytecode ≤ 1.10× cost of Y", not "improve compiler performance").
   • Acceptance: What is the measurable, verifiable pass/fail criterion an agent can check against? If the user cannot state one, propose 2-3 candidate criteria and ask them to pick or refine.
   • Status: Default to proposed unless the user says it is already in progress (active).
3. Draft the index entry (this file's format) and the detail file (header block per goals/AGENTS.md, plus Context/Approach/etc. sections only when there is real content for them) and show both to the user for review, applying them only after approval (per the maintenance rules). Do not set it active unless the user confirms.
4. Do not delete or rewrite existing goals to make room for a new one. Append with the next free ID.

Goals

G-002 [proposed] Non-nested subshell with console targeting and inter-subshell comms

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-002-non-nested-subshell.md

G-003 [proposed] Configurable resource limits and sandboxing on subshell interps

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-003-subshell-resource-limits.md

G-004 [proposed] No executable binaries committed to the repository

Scope: repo-wide (bin/, src/vfs/, src/vendorlib/, src/vendormodules/, src/bootsupport/) Detail: goals/G-004-no-committed-binaries.md

G-005 [proposed] Zig-based build infrastructure for binary dependencies from source

Scope: src/runtime/, build.zig / build.zig.zon (new), src/make.tcl integration Detail: goals/G-005-zig-build-infrastructure.md

G-006 [proposed] Optional pre-built binary artifact download with consent gating

Scope: src/runtime/, src/make.tcl integration, user-config (consent flags) Detail: goals/G-006-prebuilt-artifact-download.md

G-008 [proposed] Scoped console state for same-console subshells (activatable state sets)

Scope: src/modules/punk/console-999999.0a1.0.tm, src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-008-scoped-console-state.md

G-009 [proposed] Themed subshell profiles binding poshinfo schemes to behavioural configuration

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/poshinfo-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm, src/modules/punk/island-999999.0a1.0.tm Detail: goals/G-009-themed-subshell-profiles.md

G-010 [proposed] Subshell suspend/resume and tree navigation

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/repl/codethread-999999.0a1.0.tm Detail: goals/G-010-subshell-tree-navigation.md

G-011 [proposed] Optional per-console err channel with defined stderr semantics

Scope: src/modules/punk/console-999999.0a1.0.tm, src/modules/opunk/console-999999.0a1.0.tm, src/modules/punk/repl-999999.0a1.0.tm 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) Detail: goals/G-012-template-payload-safety.md

G-013 [proposed] Raw mode as the repl's default input mode

Scope: src/modules/punk/repl-999999.0a1.0.tm, src/modules/punk/console-999999.0a1.0.tm 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) Detail: goals/G-014-punk-config-toml.md

G-016 [proposed] projects.work discovers git-based projects alongside fossil

Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm, src/modules/punk/repo-999999.0a1.0.tm Detail: goals/G-016-projects-work-git-discovery.md

G-017 [proposed] Agents locate local projects via piped projects.work calls, not filesystem scanning

Scope: AGENTS.md (root) or a child doc it indexes (guidance content only - no code) Detail: goals/G-017-agent-project-discovery.md

G-018 [proposed] Zig-built plain tclsh kits: self-contained zip-based executables without punk infrastructure

Scope: build.zig / build.zig.zon (per G-005), src/runtime/, src/make.tcl integration Detail: goals/G-018-zig-plain-tclsh-kits.md

G-019 [proposed] Dependency-scan-driven module trimming for punk-based executables

Scope: src/make.tcl, src/modules/punk/lib-999999.0a1.0.tm (tclparser use), src/vfs/ (kit assembly), scanning module (new or existing punk module - to be determined) Detail: goals/G-019-dependency-scan-module-trimming.md

G-020 [proposed] Screen capture and input injection module with per-platform backends (Windows first)

Scope: src/modules/punk/ (new module - name TBD), src/vfs/punk9win.vfs/lib_tcl9/ (existing treectrl/Img/twapi payloads); scriptlib/aloupe.tcl stays untouched as a standalone app Detail: goals/G-020-screencap-input-module.md

G-021 [proposed] Agent-drivable visual/UI verification via piped snapshot and interaction calls

Scope: src/modules/punk/ (G-020 module's agent-facing surface), AGENTS.md guidance (post G-015 pattern), src/tests/ (visual-verification test hooks) Detail: goals/G-021-agent-visual-verification.md

G-022 [proposed] Scriptable safe fossil move/rename in dev repo; rename this project's fossil repo to punkshell

Scope: src/modules/punk/mix/commandset/repo-999999.0a1.0.tm, src/modules/punk/repo-999999.0a1.0.tm, src/tests/modules/punk/mix/testsuites/repo/ Detail: goals/G-022-fossil-rename-punkshell.md

G-023 [proposed] Version-named punk binaries per Tcl generation (versioned / dev / release-gated plain names)

Scope: src/make.tcl, src/runtime/ (mapping config - see G-024), bin/ (build outputs) Detail: goals/G-023-version-named-binaries.md

G-024 [proposed] mapvfs.config converted to toml (tomlish-parsed) with succinct scheme declarations

Scope: src/runtime/mapvfs.config (replaced/deprecated), src/make.tcl (parsing), src/bootsupport/modules/tomlish-*.tm (parser dependency) Detail: goals/G-024-mapvfs-toml.md

G-025 [proposed] Punk executables self-report project version and build provenance

Scope: src/vfs/_config/punk_main.tcl (subcommand dispatch), src/make.tcl (stamping build info into the vfs), src/vfs/ (stamp payload location), src/modules/punk/ (in-shell command - the single implementation) Detail: goals/G-025-exe-selfreport.md

G-026 [proposed] Enforceable clean-checkout provenance policy for vendor and bootsupport pulls

Scope: src/make.tcl (vendorupdate and bootsupport steps), src/vendormodules/include_modules.config, src/bootsupport/modules*/include_modules.config Detail: goals/G-026-vendor-provenance-policy.md

G-027 [proposed] Pull-based infrastructure updates for punkshell-derived projects

Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new push path), src/modules/punkcheck-999999.0a1.0.tm (install provenance records), src/make.tcl (derived-project pull entrypoint) Detail: goals/G-027-derived-project-pull-updates.md

G-028 [proposed] Name the process locking a file when builds cannot replace a target

Scope: src/modules/punkboot/utils-999999.0a1.0.tm (locker-report helper), src/make.tcl (kit deploy failure reporting) Detail: goals/G-028-file-locker-identification.md

G-029 [proposed] Build packaged test:: #modpod modules from src/tests

Scope: src/make.tcl (test-module packaging step), src/tests/ (source of truth), src/modules/test/ (generated #modpod targets), src/modules/punk/mix/ (modpod tooling as needed) Detail: goals/G-029-testmodules-from-srctests.md

G-031 [proposed] Componentized kit boot: thin project-owned main + shared layout-owned boot core

Scope: src/vfs/_config/ (punk_main.tcl, project_main.tcl restructure), src/vfs/_vfscommon.vfs (boot core delivery), src/project_layouts/ (thin-main skeleton, via established sync channels) Detail: goals/G-031-componentized-kit-boot.md

G-032 [proposed] Kit launcher dogfoods punk::args: tabled help and parsed subcommands

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

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) Detail: goals/G-035-mixed-tm-pkgindex-provision.md

G-038 [proposed] Piped-to-interactive restart continues the same session (context preserved)

Scope: src/lib/app-punkshell/punkshell.tcl (eof-restart handover), src/modules/punk/repl-999999.0a1.0.tm (eof-restart done-mode that skips codethread teardown), src/modules/punk/repl/codethread-999999.0a1.0.tm (as touched) 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) 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) 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)

Scope: src/modules/punk/repl-999999.0a1.0.tm (editbuf/reader integration, provider seam), src/modules/punk/args-999999.0a1.0.tm + src/modules/punk/ns-999999.0a1.0.tm (introspection surfaces as consumed), src/modules/punk/console-999999.0a1.0.tm (rendering) Detail: goals/G-044-repl-command-completion.md

G-047 [proposed] Declared primary VCS in punkproject.toml with per-developer commit-target override

Scope: punkproject.toml (schema), punkproject.local.toml (new, uncommitted per-checkout override), root AGENTS.md (Commit Conventions (any VCS) section), .gitignore + .fossil-settings/ignore-glob (ignore rules for the local file, per the coexistence contract), src/project_layouts/ (layout template payload - default values and ignore seeding only; project.new validation is follow-on work) Detail: goals/G-047-declared-primary-vcs.md

G-048 [proposed] textblock::table: parse via punk::args with shared passthrough documentation for table constructor options

Scope: src/modules/textblock-999999.0a1.0.tm (textblock::table proc + PUNKARGS, textblock::class::table class - constructor, opts_table_defaults, methods) Detail: goals/G-048-textblock-table-punkargs.md

G-050 [proposed] punk::ns::synopsis argument-validity marking and status-aware returns

Scope: src/modules/punk/ns-999999.0a1.0.tm (synopsis), src/modules/punk/args-999999.0a1.0.tm (synopsis renderer), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (synopsis pins) Detail: goals/G-050-synopsis-validity-marking.md

G-052 [proposed] TclOO method-level autodef documentation

Scope: src/modules/punk/ns-999999.0a1.0.tm (generate_autodef oo branches, cmd_traverse), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test Detail: goals/G-052-oo-method-autodef.md

G-053 [proposed] punk::args range-valued -multiple: occurrence arity with strict duplicate handling

Scope: src/modules/punk/args-999999.0a1.0.tm (spec compiler, parse, arg_error/synopsis renderers), src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-053-punkargs-multiple-ranges.md

G-055 [proposed] Agent-driven tclcore moduledoc regeneration workflow with behavioural parity verification

Scope: goals/G-055-tclcore-regen-workflow.md (workflow doc), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (+ buildversion), src/tests/modules/punk/args/testsuites/args/ (parity pins), TEMP_REFERENCE/tcl9 (read-only source input; source retrieval mechanism deferred to the buildsuites toml configs / G-005 era) Detail: goals/G-055-tclcore-regen-workflow.md

G-056 [proposed] punk::args display-time word wrapping for help content

Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error table and string renderers, helpers), src/modules/textblock-999999.0a1.0.tm (only if cell/column-level wrap is the chosen mechanism), src/tests/modules/punk/args/testsuites/args/ (new wrapping characterization + existing rendering suites) Detail: goals/G-056-punkargs-word-wrapping.md

G-057 [proposed] Windows kit builds embed a configurable icon (twapi resource replacement, per-vfs override)

Scope: src/make.tcl (kit/zipkit wrap steps), src/runtime/punk1.ico (project default, existing), src/vfs/*.vfs (override placement convention), src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism), TEMP_REFERENCE/tcl-sfe (read-only reference), helper proc location decided in the work (make.tcl inline vs punk::mix lib) Detail: goals/G-057-kit-icon-embedding.md

G-060 [proposed] QEMU-based cross-platform test matrix (arm's-length integration, GPL-safe posture)

Scope: build/test orchestration config and scripts (location to be settled with the buildsuites toml work - see G-005/buildsuites direction), goals/G-060-qemu-test-matrix.md (workflow + license posture), src/tests/ (any guest-driving hooks) Detail: goals/G-060-qemu-test-matrix.md

G-061 [proposed] Pseudoconsole expect-alternative for interactive shell testing (ConPTY + unix pty)

Scope: test-harness support (location TBD during the work: src/tests/testsupport/ and/or a small punk module), src/tests/shell/ (capability-gated interactive suites), goals/G-061-pseudoconsole-expect.md Detail: goals/G-061-pseudoconsole-expect.md

G-063 [proposed] Per-package license tracking: SPDX-normalized indications with copyleft audit

Scope: src/modules (Meta license headers), src/vendormodules/ + src/vendorlib/ (vendored license recording), punk::mix module templates (%license% seeding), mapping module (new, name TBD), audit surface (src/make.tcl or dev commandset - TBD) Detail: goals/G-063-package-license-tracking.md

G-064 [proposed] lib.search machine-parsable returns (dict/json) and license surfacing option

Scope: src/modules/punk/mix/commandset/loadedlib-999999.0a1.0.tm, src/tests/modules/punk/mix/ (new testsuite), G-063 mapping module (as consumed) Detail: goals/G-064-libsearch-machine-returns.md

G-065 [proposed] Declarative vendoring: toml-declared external packages with pinning, provenance and binary gating

Scope: punkproject.toml or sibling vendor manifest (schema - settled in the work), src/modules/punk/mix/ (vendor-sync command surface), src/vendorlib/ + src/vendormodules/ + src/vfs/ (materialization targets), src/make.tcl (integration) Detail: goals/G-065-declarative-vendoring.md

G-066 [proposed] pkgIndex.tcl-to-.tm repackaging: lib.copyasmodule expansion with embedded metadata and distribution-unit tracking

Scope: src/modules/punk/mix/commandset/loadedlib-999999.0a1.0.tm (lib.copyasmodule), src/modules/punk/mix/ (modpod/zipkit tooling as needed), src/tests/modules/punk/mix/ (converter testsuite) Detail: goals/G-066-pkgindex-tm-repackaging.md

G-067 [proposed] Module artifact channel: publish prepared .tm modules to and retrieve from configurable artifact servers

Scope: src/make.tcl or punk::mix dev commandset (publish/retrieve surface - settled in the work), user-config (consent flag + server list, G-006 pattern), src/vendormodules/ + src/vendorlib/ (retrieval targets) Detail: goals/G-067-module-artifact-channel.md

G-068 [proposed] Agent-assisted moduledoc generation workflow for vendored third-party libraries

Scope: goals/G-068-vendored-moduledoc-workflow.md (workflow doc), src/modules/punk/args/moduledoc/ (generated companion modules), src/tests/modules/punk/args/ (probe verification where feasible) Detail: goals/G-068-vendored-moduledoc-workflow.md

G-069 [proposed] Dev-time lint: cross-check punk::args record splitting against tclparser where the binary is available

Scope: lint surface (location settled in the work: punk::args dev helper, dev commandset, or scriptlib/developer script), src/modules/punk/args-999999.0a1.0.tm (split_definition_records as consumed, no new dependency), src/tests/modules/punk/args/ (capability-gated suite) Detail: goals/G-069-splitter-tclparser-lint.md

G-070 [proposed] Pure-Tcl tclparser: parse-command API fallback with behavioural parity against the C library

Scope: src/modules/punk/lib-999999.0a1.0.tm (tclparser_tcl stub + dispatch; new module if size warrants - decided in the work), src/tests/modules/punk/lib/ (parity + fallback suites), TEMP_REFERENCE/ (tclparser reference source, user-provided, read-only) Detail: goals/G-070-pure-tcl-tclparser.md

G-072 [proposed] punk::args compound clause types: named alternates with per-element typing and per-alternate arity (try-class handlers)

Scope: src/modules/punk/args-999999.0a1.0.tm (type-expression parsing, clause allocation, synopsis/help renderers), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (::try as proving consumer; ::if/::switch as touched), src/tests/modules/punk/args/testsuites/args/ Detail: goals/G-072-punkargs-compound-clause-types.md

G-073 [proposed] punk::args unavailable choices: displayed with notes and prefix-reserving, but rejected with a tailored message

Scope: src/modules/punk/args-999999.0a1.0.tm (spec key, choiceword_match pool, choices rendering in arg_error table+string renderers, validation message), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm ('string is' forward-class adoption + per-class virtual id), src/tests/modules/punk/args/testsuites/args/ (new suite + tclcoreparity.test exemption) Detail: goals/G-073-punkargs-unavailable-choices.md

G-075 [proposed] punk::args (package) ids: working lookup and a user-facing package documentation surface

Scope: src/modules/punk/args-999999.0a1.0.tm (id lookup/update_definitions prefix handling, usage/arg_error rendering of package-level ids), src/modules/punk/ns-999999.0a1.0.tm (cmdhelp/help-system surface), src/modules/punk/mix/#modpod-templates-999999.0a1.0/templates/modules/template_module-0.0.4.tm (template block as touched/verified), src/tests/modules/punk/args/testsuites/args/ + src/tests/modules/punk/ns/testsuites/ns/ (new coverage) Detail: goals/G-075-punkargs-package-ids.md

G-076 [active] Adopt upstream tcl9 dead-console fix: shared version gate for watchdog and help tcl warning

Scope: src/modules/punk/lib-999999.0a1.0.tm (punk::lib::check), src/modules/punk/repl-999999.0a1.0.tm (repl::start watchdog arming), src/modules/punk/AGENTS.md, src/tests/modules/punk/lib/testsuites/lib/checkbugs.test Detail: goals/G-076-tcl9-deadconsole-fix-adoption.md

G-077 [proposed] punk executable -e one-liner support: make the tclsh-agent instinct work

Scope: src/vfs/_config/punk_main.tcl (top-level arg dispatch), src/lib/app-punkscript/punkscript.tcl (script subcommand arg forms), src/tests/shell/testsuites/punkexe/scriptexec.test Detail: goals/G-077-punkexe-dash-e-oneliner.md

G-078 [proposed] punk::ansi ANSI->HTML rendering api (developer-surfaced, documented)

Scope: src/modules/punk/ansi-999999.0a1.0.tm (or a new punk::ansi::html module), src/scriptapps/tools/punkargs_punknative.tcl + scratch prototypes (ansi2html_core.tcl, ansicat_gallery.tcl) as reference implementations to be retired into consumers, src/scriptapps/tools/fontprep/ (asset + geometry contract), new testsuite under src/tests/modules/punk/ansi/ Detail: goals/G-078-punkansi-tohtml-api.md

G-079 [proposed] default-colour semantics through renderspace/flattened output

Scope: src/modules/overtype-999999.0a1.0.tm (renderspace/renderline replay-code emission), punk::ansi flatten consumers (ansicat), ansi2html consumer mapping (G-078) Detail: goals/G-079-renderspace-default-colour-semantics.md

G-080 [proposed] deterministic cell-grid html rendering mode (seamless block art)

Scope: the G-078 punk::ansi html api (additional rendering mode); scratch prototypes as baseline Detail: goals/G-080-ansi2html-cellgrid-mode.md

G-081 [proposed] punk::args documentation build pipeline (dev doc.* integration)

Scope: src/modules/punk/mix/commandset/doc-999999.0a1.0.tm (doc.* commandset - new generation subcommands), src/scriptapps/tools/punkargs_to_doctools.tcl + punkargs_punknative.tcl (prototypes to productize), src/scriptapps/tools/fontprep/ (shared doc-set asset in link mode), src/doc tree conventions, src/tests coverage Detail: goals/G-081-argdoc-build-pipeline.md

G-083 [proposed] punk::args argument relations: strict mutual exclusivity and parsekey-group integrity

Scope: src/modules/punk/args-999999.0a1.0.tm (resolve/spec compiler, parse paths incl mash, arg_error/synopsis/usage renderers, errorcode vocabulary), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (lsearch, clock clicks dogfood), src/tests/modules/punk/args/testsuites/args/ + testsuites/dev/ (GAP flips + new characterization) Detail: goals/G-083-punkargs-argument-relations.md

G-084 [proposed] punk::args -parsekey completeness: cross-member -multiple collection, leaders/values support, defined default precedence

Scope: src/modules/punk/args-999999.0a1.0.tm (parse paths, resolve directive handling for @leaders/@values), src/modules/punk/args/moduledoc/tclcore-999999.0a1.0.tm (sites carrying '#todo - fix -parsekey for leaders and values'), src/tests/modules/punk/args/testsuites/args/parsekey.test + testsuites/dev/parsekey-knownbugs.test (GAP/known-bug flips) Detail: goals/G-084-punkargs-parsekey-completeness.md

G-085 [proposed] punk::ns::cmdtrace: source-file vs live-proc line attribution option, and machine-parseable trace output

Scope: src/modules/punk/ns-999999.0a1.0.tm (cmdtrace, cmdtrace* trace callbacks, argdoc), src/tests/modules/punk/ns/testsuites/ns/cmdtrace.test Detail: goals/G-085-cmdtrace-attribution-and-machine-output.md

G-086 [proposed] Light project layout: punkshell-generated minimal projects carrying startup/test module-path semantics

Scope: src/project_layouts/ (new light layout), src/modules/punk/mix/commandset/project-999999.0a1.0.tm (project.new layout selection), layout-seeded test harness + startup preamble (no bootsupport/vfs/build trees in generated output) Detail: goals/G-086-light-project-layout.md