punkshell/goals/G-016-projects-work-git-discovery.md

G-016 projects.work discovers git-based projects alongside fossil

Status: proposed Scope: src/modules/punk/mix/commandset/project-999999.0a1.0.tm, src/modules/punk/repo-999999.0a1.0.tm Acceptance: as in root GOALS.md index (canonical).

Context

dev projects.work <glob> (punk::mix::commandset::project::collection::work) answers "where are my projects checked out" by opening the central fossil config-db, globbing repository database filenames, and listing the known checkout directories per repo - with optional per-checkout file-state detail. This makes it the natural mechanism for agents to locate sibling projects (e.g. the tomlish project space referenced by G-014) instead of recursively scanning the filesystem.

The gap: it is fossil-only. Git-based projects are invisible to it, and git has no equivalent of fossil's central config-db - there is no built-in registry of clones on a machine. So git discovery needs a defined enumeration source of its own before the listing can be extended.

Approach

Enumeration-source candidates (implementation decision, to be recorded here when made):

• Configured search roots: a punk::config setting (natural G-014 consumer) listing parent directories to scan one or two levels deep for .git dirs. Bounded scan, no registry maintenance, but discovery limited to declared roots.
• Punk-maintained registry: record project paths when punk tooling creates/opens them (and offer a scan-once command to seed it). Fast lookups, works for arbitrary locations, but can go stale.
• Hybrid: registry seeded/refreshed by an explicit scan of configured roots.

Result-shape considerations:

• Each row identifies its VCS. Fossil rows keep their current columns (repo db filename, project name/code, checkout dirs, dup-set annotations); what the git analogue of "project name" is (dir name, remote URL tail, configured name) is part of the design work.
• A dual git+fossil workdir (like the shellspy repo itself) is one project row with both VCSs indicated, not two rows.
• Fossil supports multiple checkouts per repo db; git worktrees are the analogous multi-workdir case and should at least not break the listing.

Alternatives considered

• Filesystem-wide scanning at query time - rejected: unbounded cost and exactly the behaviour this mechanism is meant to replace for agents.
• Relying on external tools' state (e.g. IDE/zoxide/gh caches) - rejected: non-portable, not present on all machines, opaque formats.

Notes

• Depends on nothing, but its value to agents is realised through G-015 (reliable piped invocation) 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.