# G-033 `proj` package-mode: visitor binary detects the cwd's project and explores it

Status: proposed
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: as in root GOALS.md index (canonical).

## Context

The earlier intent (recalled 2026-07-07): an installed punkshell binary sitting
in PATH - possibly a downloaded binary, not built from the project - should be
able to detect when the cwd is inside a punkshell project and set up the
appropriate source/dev library resolution for it, so the user can explore that
project interactively via the `shell` subcommand. The project being worked on
might not build a shell-capable binary, or might build no executable at all
(e.g. a modules-only project like a library).

History check: this was **never active** in the full sense. `src` mode is new
(checkin 3d2d098d) and discovers the project root **exe-relative** (backtrack
from the executable's `bin/`) - it assumes the binary belongs to the project.
`dev` mode is likewise exe-relative. `os` mode is the only cwd-relative piece,
and only shallowly (adds `[pwd]` and cwd-relative `modules`/`modules_tcl<N>`
ad-hoc `.tm` sources - no walk-up, no `src/` structure). The comments in
punk_main.tcl name "the info nameofexecutable or info script or pwd relative
paths" as design axes, so the *intent* seeded `os` mode, but cwd project-
structure detection was never built into the boot modes.

Crucially, the cwd-relative detector **already exists at the runtime layer**:
`punk::repo::find_project` walks up from cwd via `is_project_root`, and `dev`
commands (module.templates, module.new, ...) already use it. So the marker
question is answered: `is_project_root` defines a project as a **VCS repo root**
(git or fossil) that is not an excluded location - deliberately NOT relying on
`punkproject.toml` (its own comment notes that file also appears in layout
templates, and tomlish has no punkproject.toml yet but IS a fossil root). This
goal aligns the boot-time package modes with that existing runtime detection.

## Approach

- New explicit token `proj` in the package-mode list (dev/os/src/internal/proj).
  Explicit gate = no `cd` silently rebinds a normal launch; the visitor
  behaviour is opt-in.
- On `proj`: walk up from `[pwd]` to the nearest VCS repo root (the
  `is_project_root` marker) and use that as the project root, then feed it into
  the **existing src-mode path machinery** (which is already parameterised on a
  root variable - adds src/modules, src/modules_tcl<N>, src/bootsupport/modules,
  src/vendormodules to the tm path, src/lib to auto_path, registers #modpod
  modules, sets package prefer latest). The only new part is cwd-relative
  *discovery*; the setup is reused.
- Boot chicken-and-egg: `find_project`/`is_project_root` live in `punk::repo`,
  which is not loadable at the early package-mode phase (punk_main.tcl avoids
  package requires there by design). Options, decision to record: (a) a lean
  inline VCS-root walk-up in punk_main mirroring is_project_root (fossil:
  _FOSSIL_/.fslckout/.fos; git: .git) using only Tcl builtins; (b) defer proj
  setup to a post-boot phase where punk::repo is available. (a) matches how the
  src-mode #modpod scan already inlines logic at boot.
- Composition: decide `proj` + built-vs-source selectors. Natural default:
  `proj` alone implies source-tree resolution (like src) against the detected
  root; `proj-dev` selects built `modules/` output; document the matrix.
- No-project case: `proj` from a non-project cwd warns and proceeds as
  `internal` - never a false rebind.
- Exe-relative `src`/`dev` for a binary that IS in a project bin/ stays
  unchanged; `proj` is the visitor-binary path.

## Alternatives considered

- Automatic cwd-detection with no token - rejected (user decision 2026-07-07):
  silently rebinding the module world on `cd` is surprising; an explicit `proj`
  token is the safer gate.
- A dedicated project-marker file (punkproject.toml) as the sole signal -
  rejected: not universal (tomlish lacks it; it also appears in layout
  templates), and is_project_root already provides a VCS-root marker that works
  today.

## Notes

- The related `dev` machinery (module.templates -> punk::mix::commandset::module
  -> punk::cap `punk.templates` plugin handlers) uses find_project and has
  unpolished plugin issues, plus an 8.6 shell-context zip-modpod-mount failure
  (G-034). This goal deliberately does NOT gate on synchronising with that
  machinery - it only reuses the find_project detection concept.
- Related: G-018 (the installable generic/plain binary this serves), G-031
  (boot core is where proj discovery belongs; the template project_main.tcl
  lacks even src mode - fork drift), G-015 (`script` also benefits: a visitor
  binary running `proj script` against a cwd project), G-027 (if a universal
  project marker is ever seeded, proj could prefer it over the structural VCS
  heuristic).