Inspect repository files and changes through Git components #940

Story

As a Sidekick coordinating development in xmd repl, I want to inspect a repository through Git components, so I can find relevant files and review changes without recursively opening unrelated worktrees or constructing shell commands.

Common path

Before delegating a change, Sidekick asks for the selected repository's tracked paths and reads only the relevant files. After implementation, it asks for changed paths, inspects the relevant diff, and reads a file from the exact commit under review.

The observations are XMD values that can be captured, passed into role components, and inspected in the REPL's saved history.

Current gap

A live Codex Sidekick verification on main at 7ee526665dcadd9ec79dca9f8b6a4726903d9a4f successfully used Git.Switch, Git.Add and Git.Commit. Its runtime syntax reference exposed those components and Git.Push, but no Git component for tracked-file discovery, changed paths/diffs, or reading a file from a specified commit.

The separate development exercise behind draft PR #938 used broad file discovery while orchestrating Architect, Planner and Implementor conversations. Git-aware discovery would let Sidekick choose relevant repository files before reading their contents.

There is existing infrastructure to reuse: GitQuery provides contextual revision, root, object-format and commit-file reads; the completed #103 supplies structured diff parsing in @executablemd/code-review-agent. Neither is currently the authored Git inspection surface described here.

Required behavior

• List tracked repository paths with a way to narrow discovery before returning contents. Untracked files and unrelated nested checkouts are distinguishable rather than silently mixed into the tracked list.
• Inspect changed paths and diffs with explicit comparison semantics: the working tree, staged changes, or specified commits. A user can tell what was compared.
• Read a specified repository-relative file from a specified commit. The answer comes from that commit, even if today's working copy differs.
• Return useful structured values for path/status information and a usable diff representation; allow callers to restrict the paths or portions they need. Large answers expose their bounds or continuation instead of silently omitting content.
• Discover the operations and representative examples through the syntax reference available to Sidekick.
• Use the selected repository and the host's existing permission and journal rules. Reads do not stage, switch, commit, push or launch a delegated agent.
• Saved observations reconstruct without rerunning Git merely to inspect history. A new live observation may report new repository state.

Component names, props, result shapes, comparison defaults and output bounds need an Architect/Product Owner interface review before implementation. This story records the product outcome rather than freezing those spellings.

Acceptance and evidence

Use a small real repository fixture containing a tracked file, an unrelated untracked file, staged and unstaged edits, two commits with different file contents, and an unrelated checkout.

Demonstrate that:

• tracked-path discovery returns the intended repository's tracked paths and excludes unrelated checkout content;
• staged, unstaged and commit-to-commit comparisons return the correct changed paths and changes;
• reading the earlier commit returns its original contents after the working file changes;
• path filtering and output bounds let the caller inspect a useful subset;
• an invalid revision, absent path or non-repository fails clearly rather than returning a misleading empty success;
• history inspection restores the recorded answer without another Git process, and these observations leave HEAD, index and files unchanged.

Then guide a real Sidekick through discovery, diff inspection and an exact-commit file read using these components, checking the entry journal to distinguish component operations from shell execution or delegated-agent work. Native tools remain allowed for delegated coding agents; this verification establishes that the XMD route works.

Relationships and scope

Supports REPL Quest #827, Sidekick #883, reusable role components #896 and orchestration in #938. Coordinate with #939 for cross-entry binding persistence and #934 for shared query syntax; do not invent a private query language here.

#103 is completed diff-parsing work to reuse, not an open duplicate. #816 concerns GitHub pull-request reads, while this story concerns local repository inspection.

Exclude general adversarial-workflow orchestration, Git mutation changes, disabling delegated agents' tools, automatic commits/pushes, and a general-purpose shell component.