# src — Source Tree Root

## Purpose

The source tree root contains all editable source code, build scripts, test suites, VFS payloads, vendor dependencies, and documentation. This is the primary development area.

## Ownership

- The `src/` tree is where agents perform development work.
- Generated/output directories at the project root (`modules/`, `lib/`, `lib_tcl8/`, `lib_tcl9/`, `modules_tcl8/`, `modules_tcl9/`) are build targets — agents must not directly modify them.
- VFS payloads, runtime mappings, vendored dependencies, generated docs, and entry-point scripts have child AGENTS.md files with local ownership rules.

## Local Contracts

- `make.tcl` is the primary build entry point: `tclsh src/make.tcl <command>`.
- The build system handles bootstrap loading, version assignment, module/library packaging, and VFS packaging.
- Shell launcher entry points include `tclsh src/make.tcl shell`, built launchers under the project `bin/` directory, scripts sourced from `src/scriptapps/`, and executable entry scripts under `src/vfs/_config/`.
- Tcl 8.6+ is required and Tcl 9.0 is supported; gate 9.0-specific behavior behind version checks or existing `punk::lib::compat` helpers.
- Primary target is Windows (`win32-x86_64`); Linux, macOS, and FreeBSD are secondary targets.
- Tcl linting is available only through the VS Code Tcl lint plugin configured by `tclint.toml`; do not try to run `tclint` or `tcllint` as shell commands.
- Lint coverage is `.tcl` and `.tm`; extend config if new Tcl-related extensions appear.
- Shared Tcl source formatting defaults are a 400-character line cap, no more than 10 consecutive blank lines, 4-space indentation, and no tabs except inside string literals.
- Source priority for editable modules: `src/modules/` > `src/modules_tcl<major>/` > bootsupport > VFS > built > installed.
- Source priority for editable libraries: `src/lib/` > `src/lib_tcl<major>/` > vendorlib > VFS > built > installed.
- Treat `pkgIndex.tcl` as a loader map unless the task is about package loading or registration.
- Prefer vendored dependencies under `src/vendor*` before fetching new dependencies.
- Guard optional compiled extensions such as `twapi` or `tdom` with fallback behavior or actionable messages.

### File Resolution Policy

Use the strongest available anchor first and do not broaden scope until that anchor is checked.

Treat active-editor anchors in source-derived or generated trees as ambiguous unless the user explicitly named that path. In particular, confirm the intended target before editing files opened under `src/bootsupport/`, root `modules/`, root `lib/`, `modules_tcl8/`, `modules_tcl9/`, `lib_tcl8/`, or `lib_tcl9/`; for generic module/library work, the usual target is `src/modules/`, `src/modules_tcl<major>/`, `src/lib/`, or `src/lib_tcl<major>/`.

Anchor order:

1. Exact path named by the user.
2. Active editor file, when the environment provides one.
3. Exact proc, symbol, or identifier named by the user.
4. Repository naming and source-precedence rules.

Proc inspection order:

1. Read the exact file named by the user, if provided.
2. Otherwise read the active editor file, if provided and relevant.
3. Otherwise search once for the exact proc name.
4. Prefer editable source under `src/modules/`, `src/modules_tcl<major>/`, `src/lib/`, or `src/lib_tcl<major>/`.
5. If multiple matches exist, prefer the generic source tree unless version-specific behavior is relevant or only a version-specific definition exists.
6. If the best hit is `pkgIndex.tcl`, use it to resolve the implementation file.
7. Once the owning source file is identified, continue locally from that file.

Recovery after a wrong path guess:

- Re-check the user-provided path.
- Re-check the active editor file, if available.
- Re-check repo naming conventions.
- Use one exact symbol search instead of probing more filename variants.

## Work Guidance

- Run `tclsh src/make.tcl packages` once after cloning to populate generated module and library assets.
- Use `tclsh src/make.tcl project` for full builds.
- Use `tclsh src/make.tcl modules` to build just the module packages.
- Use `tclsh src/make.tcl libs` to build just the library packages.
- Use `tclsh src/make.tcl packages` to build both modules and libraries.
- Use `tclsh src/make.tcl vendorupdate` to refresh vendormodules from config. It warns (non-fatal) for each source project whose fossil/git checkout is dirty - vendored artifacts built from a dirty tree have no committed provenance; commit in the source project to clear the warning (enforcement policy tracked by goal G-026).
- All build/promotion commands (`project`, `packages`, `modules`, `libs`, `vfs`, `vfslibs`, `bin`, `bootsupport`, `vfscommonupdate`) warn similarly when this project's own `src/` has uncommitted fossil/git changes (dirt outside `src/` is ignored). Warn-only by default; pass `-dirty-abort` to make the check aborting. For evaluating uncommitted source without a build, prefer `<builtexe> src` / `<builtexe> src shell`. The check is `punkboot::utils::vcs_dirty_warnings` (optional scope argument) loaded guardedly from bootsupport - if the snapshot is stale/missing the check degrades to a skip notice (but `-dirty-abort` then aborts rather than silently losing the requested strictness).
- Provenance warnings (dirty-src gate + vendorupdate source-project check) print with a plain column-0 `PROVENANCE-WARNING:` token (grep for it in captured build output) and are recapped at the end of the run via make.tcl's wrapped `::exit`. Interactive terminal runs get a 3-second ctrl-c grace countdown before a dirty build proceeds; piped/agent runs skip it. `tclsh src/make.tcl check` reports the current src provenance status and what the build commands would do.
- Use `tclsh src/make.tcl vfscommonupdate` to rebuild `_vfscommon.vfs`. The REPLACE confirmation prompts on an interactive terminal; unattended/agent runs must pass `-confirm 0` (with the default `-confirm 1` and a piped/closed stdin, make.tcl aborts fast with guidance instead of reading stdin - do not pipe `y`).
- `tclsh src/make.tcl workflow` prints an embedded ASCII data-flow overview of the build/release workflow (release-ready command sequence, source→outputs folder flow, kit assembly, keyed notes). The text lives in `::punkboot::workflow_text` in `src/make.tcl` - embedded rather than a data file so it travels with the make.tcl copies seeded into generated projects. **Update contract (agents):** whenever build data flow changes - a make.tcl subcommand added/removed/repurposed, a source or output folder added or rerouted, a propagation target added, a gate (staleness/provenance/confirm) or deploy behaviour changed - update the workflow text in the same change-set. Keep it plain ASCII, max line width 100, and preserve the RELEASE SEQUENCE / DIAGRAM / KEY-NOTES / MAINTENANCE structure; verify by running `tclsh src/make.tcl workflow` (and once under `PUNKBOOT_PLAIN=1`). Adding/changing a subcommand also means: SUMMARIES + HELPTEXTS + SUBOPTS (+ SUBGROUPS) in `::punkboot::argdoc`, `known_commands`, the plain `punkboot_gethelp` text, and a project-version bump (make.tcl interface is product surface per root AGENTS.md). Layout make.tcl copies pick the change up via `make.tcl bootsupport` - do not hand-sync them.
- make.tcl subcommands and flags are punk::args-declared (G-030): `tclsh src/make.tcl help ?subcommand?` or `<subcommand> -help` shows tabled usage; invalid arguments produce punk::args usage errors. The dispatch degrades to plain scan/help when the bootsupport punk::args (or its rendering stack) is stale or unavailable; `PUNKBOOT_PLAIN=1` forces the degraded mode for troubleshooting. The `::punkboot::argdoc` definitions are constructed (string-built) and use the G-045 authoring mechanisms — block-form help values + `@normalize`, explicit `@form -synopsis` — see src/modules/AGENTS.md "punk::args definition authoring ergonomics" before editing them or authoring similar definitions.
- Uncommitted `make.tcl`-generated outputs may be batched into one commit, regardless of how many `make.tcl` invocations produced them. This covers punkcheck-managed build outputs that are VCS-tracked: `src/bootsupport/`, `_vfscommon.vfs/modules` + `/lib`, and declared per-kit `*.vfs/lib_tcl<N>/<pkg>` subfolders. (Root `modules/`, `lib/`, `modules_tcl<N>/`, `lib_tcl<N>/` are gitignored and never committed.) Each module's old→new version rename is atomic; a regeneration reflects one build-output refresh, not independent hand-edits. This is a carve-out from generic "split aggressively" commit guidance for punkcheck-managed build outputs only — it does not cover user-curated VFS content (`_config/`, per-kit `*.vfs/` outside declared `lib_tcl<N>` subfolders, `_aside/`, `mkzipfix.vfs`, `_vfscommon.vfs/doc`), which commits separately per its own concerns.
- Use `punk make.tcl project` or `punk902z make.tcl project` inside Punk shell when building binaries through Punk. Driving make.tcl from a built punk executable is supported for informational/update subcommands and for kit builds of *other* kits — the kit whose deployed executable is running the build is skipped with a warning (it cannot be replaced while running, and the pre-deploy process sweep must not kill the build itself; the sweep also excludes the build's own pid in all cases). Rebuild that kit from tclsh or a different kit.
- **Punk-exe-hosted make.tcl runs in a pre-loaded interp, not a virgin one** — the kit's script-mode boot has already loaded much of the punk stack (punk, punk::lib, punk::repl, punk::console, punk::du, flagfilter, struct::set ...) and set process state (app-punkscript forces `::tcl_interactive 0` for script semantics; libunknown/packagepreference are active). Consequences make.tcl must (and now does) handle explicitly: `package require` of an already-provided package is a no-op, so anything make.tcl breaks in the interp (the accelerator-reload block forgets+destroys sha1/md5/struct::* — it re-requires what was loaded), and anything computed at package-load time (punk::repl's `::tcl_interactive` probe — the shell branch recomputes it before `repl::start`), must be restored deliberately rather than relying on later loads to re-fire. Also note the copies that run in this mode are the *kit's* pre-loaded modules, not the bootsupport snapshots make.tcl's paths would otherwise prefer — silent provenance mixing when versions diverge. When adding interp-surgery or load-time-state assumptions to make.tcl, test under both `tclsh src/make.tcl ...` and `<punkexe> src/make.tcl ...`.
- Binary images are platform-specific; build on each target platform rather than expecting a cross-platform flag.
- Remove `_build/` artifacts only when a clean/resync is needed, then rerun the relevant `make.tcl` command. Avoid partial cleans that break boot modules.
- Superseded module intermediates are pruned automatically so payload wrapping inherits clean trees:
  - `punk::mix::cli::lib::prune_superseded_target_modules` runs inside `build_modules_from_source_to_base` after each module install/skip (covers root `modules/`, `modules_tcl8/`, `modules_tcl9/`), and from `make.tcl bootsupport` for non-glob `include_modules.config` entries (glob entries may intentionally track multiple versions and are never pruned).
  - `punk::mix::cli::lib::prune_sourcevanished_targets` mirror-prunes recorded `.tm` targets whose recorded source files no longer exist: project-layout bootsupport copies (installer `punkboot-bootsupport`) and root `modules*/` vendormodule copies (installer `make.tcl`).
  - Every deletion is recorded as a punkcheck DELETE event in the owning `.punkcheck`, so change detection stays consistent. Files without a qualifying punkcheck install record (e.g placed manually) are never deleted — they are reported to stderr and must be removed by hand if unwanted.
  - Install records carry virtual `module_name`/`module_version` SOURCE entries (punkcheck `targetset_addsource_virtual`, punkcheck >= 0.3.0) identifying which product of a source fileset a target is — needed because successive versions are typically built from the same physical source files. Prune trusts this identity; for legacy records it falls back to requiring the candidate's recorded sources to share the keep-version's source folder(s) and module-name prefix.
  - The make.tcl call sites are guarded with `info commands` checks: after changing this tooling itself, the first `make.tcl modules` + `make.tcl bootsupport` pass builds/propagates the new tooling (prune skipped with a stderr note) and the next pass prunes.
- Use `tcl::tm::path add <dir>` to surface project modules when writing focused tooling.
- Review VS Code Tcl lint diagnostics before submitting new agent-produced Tcl code, but do not use lint tooling to reformat existing code.
- When touching VFS payloads, describe regeneration steps in durable docs if the workflow changes.
- When a tool summary reports cleanup issues such as `git diff --check` whitespace errors, verify against exact command output and exit code before running secondary scans or reporting the issue.
- `make.tcl` performs version-aware bootsupport staleness detection: major bumps abort, minor bumps prompt (y/N; `-confirm 0` proceeds without prompting, non-interactive stdin without it aborts fast), patch bumps warn-and-proceed. See `src/bootsupport/AGENTS.md` "Bootsupport Staleness Handling" for the full contract and the version-bump discipline agents must follow.
- Project-level version bumps are governed by the root `AGENTS.md` "Project Versioning" section. Any `src/` change that ships user-visible shell behaviour requires a `punkproject.toml` version bump and a `CHANGELOG.md` entry as part of the DOX closeout pass. Run `tclsh src/make.tcl projectversion` to verify.

## Verification

- VS Code Tcl lint diagnostics are reviewed for modified Tcl files when available.
- Relevant tests pass, either `tclsh src/tests/runtests.tcl` or a specific `tclsh src/tests/modules/<modulehierarchypath>/tests/all.tcl`.
- `tclsh src/make.tcl packages` is verified when touching build-critical code.
- `tclsh src/make.tcl project` completes without errors when changing build, runtime, or VFS behavior.
- Documentation/comments are updated for new behavior, flags, workflow, or ownership rules.
- Diffs are reviewed so no stray whitespace or debugging output remains.

## Child DOX Index

- `modules/` — Main editable module source (see modules/AGENTS.md)
- `modules/punk/` — Core punk namespace modules (see modules/punk/AGENTS.md)
- `modules/test/` — Installed-module test packages (see modules/test/AGENTS.md)
- `modules_tcl8/` — Tcl 8 specific modules (see modules_tcl8/AGENTS.md)
- `modules_tcl9/` — Tcl 9 specific modules (see modules_tcl9/AGENTS.md)
- `lib/` — Editable library source (see lib/AGENTS.md)
- `lib_tcl8/` — Tcl 8 specific libraries
- `lib_tcl9/` — Tcl 9 specific libraries
- `bootsupport/` — Early-load bootstrap modules (see bootsupport/AGENTS.md)
- `tests/` — Source-tree test harness and tests (see tests/AGENTS.md)
- `vfs/` — Virtual file system images for builds (see vfs/AGENTS.md)
- `scriptapps/` — Entry-point scripts for Punk apps (see scriptapps/AGENTS.md)
- `vendormodules/` — Third-party bundled modules (see vendormodules/AGENTS.md)
- `vendorlib/` — Third-party bundled libraries (see vendorlib/AGENTS.md)
- `vendorlib_tcl8/` — Tcl 8 specific vendor libraries
- `vendorlib_tcl9/` — Tcl 9 specific vendor libraries
- `runtime/` — Build runtimes and VFS config (see runtime/AGENTS.md)
- `doc/` — Generated documentation (see doc/AGENTS.md)
- `testansi/` — Sample ANSI art files (do not modify)