pyro-mcp/docs/roadmap/llm-chat-ergonomics/4.6.0-git-tracked-project-sources.md

4.6.0 Git-Tracked Project Sources

Status: Planned

Goal

Make repo-root startup and --project-path robust for messy real checkouts by stopping the default chat-host path from trying to ingest every readable and unreadable file in the working tree.

Public API Changes

Project-aware startup should change its default local source semantics:

• bare pyro mcp serve from inside a Git checkout should seed from Git-tracked files only
• pyro mcp serve --project-path PATH should also use Git-tracked files only when PATH is inside a Git checkout
• --repo-url remains the clean-clone path when the user wants a host-side clone instead of the local checkout
• explicit workspace create --seed-path PATH remains unchanged in this milestone

Implementation Boundaries

• apply the new semantics only to project-aware startup sources, not every explicit directory seed
• do not silently include ignored or untracked junk in the default chat-host path
• preserve explicit diff, export, sync push, and reset behavior
• surface the chosen project source clearly enough that users know what the sandbox started from

Non-Goals

• no generic SCM abstraction layer
• no silent live sync between the host checkout and the guest
• no change to explicit archive seeding semantics in this milestone

Acceptance Scenarios

• starting pyro mcp serve from a repo root no longer fails on unreadable build artifacts or ignored runtime byproducts
• starting from --project-path inside a Git repo behaves the same way
• users can predict that the startup source matches the tracked project state rather than the entire working tree

Required Repo Updates

• README, install docs, integrations docs, and public contract updated to state what local project-aware startup actually includes
• help text updated to distinguish project-aware startup from explicit --seed-path behavior
• at least one guest-backed smoke scenario added for a repo with ignored, generated, and unreadable files