@senad-d/branchme 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -6,5 +6,7 @@
 - Added strict BranchMe tools: `branch_status`, `change_branch`, `create_branch`, `push_branch`, and `pull_request`.
 - Added argv-style git helpers for repository status, branch validation/creation/switching, clean-worktree preflight, upstream detection, and current-branch push/publish.
 - Added GitHub repository resolution, environment-token and local `.env` token fallback handling, REST pull request creation, response validation, and token redaction.
-- Added unit tests with mocked `pi.exec` and `fetch` for git helpers, GitHub helpers, command behavior, tool schemas, prompt metadata, and extension registration.
-- Updated public documentation for implemented behavior, security boundaries, package structure, and validation commands.
+- Added bounded automatic Git context before each agent run with branch/upstream state, working-tree counts and unstaged paths, authenticated related-open-PR lookup, and recent commits.
+- Expanded `branch_status` into a shared, explicit, read-only context refresh for state that may change during a run.
+- Added unit tests with mocked `pi.exec` and `fetch` for Git context collection and prompt safety, git helpers, GitHub helpers, command behavior, tool schemas, prompt metadata, and extension registration.
+- Updated public documentation for automatic context behavior, authenticated lookup and prompt-insertion security boundaries, package structure, and validation commands.

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-BranchMe is a Pi extension for safe branch workflow automation. It adds an informational `/branchme` command and five agent-callable tools that inspect the current repository, switch to an existing local branch, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
+BranchMe is a Pi extension for safe branch workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and five agent-callable tools that explicitly refresh state, switch to an existing local branch, create a branch from the current `HEAD`, push the current branch, and create a GitHub pull request.
 
 <table align="center">
   <tr>
@@ -29,12 +29,13 @@ BranchMe is a Pi extension for safe branch workflow automation. It adds an infor
   </tr>
 </table>
 
+- **Context-aware:** every agent run starts with bounded branch, working-tree, related-PR, and recent-commit metadata; repository metadata is untrusted data, not instructions.
 - **Current-repository only:** Git and GitHub operations are scoped to the checkout where pi is running.
-- **Commit-safe:** BranchMe never stages files, creates commits, generates commit messages, rebases, merges, resets, or edits files directly.
+- **Commit-safe:** context collection is read-only, and BranchMe never stages files, creates commits, generates commit messages, rebases, merges, resets, or edits files directly.
 - **Strict tools:** tool schemas reject extra properties such as `force`, `stash`, `discard`, `owner`, `repo`, `path`, or `baseRef`.
 - **PR-ready:** create GitHub pull requests from existing local branches after verifying the `headBranch` matches GitHub and the base is visible, with explicit PR fields and `GITHUB_TOKEN` or `GH_TOKEN` from the process environment or a local `.env` fallback.
 
-> **Security:** pi packages run with your full system permissions. BranchMe can run local `git` commands, switch/create branches, push the current branch, and call the GitHub REST API to create pull requests. Read [`SECURITY.md`](SECURITY.md).
+> **Security:** pi packages run with your full system permissions. BranchMe runs local `git` commands, may make an automatic authenticated GitHub request to find a related open pull request, can switch/create branches and push the current branch, and can create GitHub pull requests. Read [`SECURITY.md`](SECURITY.md).
 
 ## Table of Contents
 
@@ -70,19 +71,20 @@ Inside pi:
 /branchme help
 ```
 
-Ask the agent to use BranchMe tools explicitly, for example:
+A normal prompt can use the automatic start-of-run snapshot without a tool call. Ask for an explicit refresh when needed, for example:
 
 ```text
-Use branch_status, then create a branch named feature/update-docs with create_branch.
+Refresh the repository state with branch_status, then create a branch named feature/update-docs with create_branch.
 ```
 
 A typical BranchMe flow is:
 
-1. Inspect state with `branch_status`.
-2. Switch with `change_branch` or create from current `HEAD` with `create_branch`.
-3. Make edits and commit outside BranchMe.
-4. Push the current branch with `push_branch`.
-5. After `push_branch` completes and GitHub can see the branches, create a pull request with `pull_request`.
+1. Use the automatic snapshot to understand state at the start of the agent run.
+2. Use `branch_status` when you explicitly need fresh state, especially after a Git mutation in the same run.
+3. Switch with `change_branch` or create from current `HEAD` with `create_branch`.
+4. Make edits and commit outside BranchMe.
+5. Push the current branch with `push_branch`.
+6. After `push_branch` completes and GitHub can see the branches, create a pull request with `pull_request`.
 
 BranchMe is tool-based. The slash command is informational only and never changes branches, pushes, commits, stages, edits files, or opens pull requests.
 
@@ -98,6 +100,8 @@ BranchMe is tool-based. The slash command is informational only and never change
 | Git | `pi install git:github.com/senad-d/branchme@<tag>` | Pin a tag or commit. |
 | Local checkout | `pi --no-extensions -e .` | Develop or test this repository in isolation. |
 
+Once loaded, BranchMe collects automatic Git context before each agent run. This happens for ordinary prompts; there is no `/branchme context` command and no additional tool to enable it.
+
 Source checkout:
 
 ```bash
@@ -135,7 +139,7 @@ git remote set-url origin git@github.com:OWNER/REPO.git
 export GITHUB_REPOSITORY=OWNER/REPO
 ```
 
-For `pull_request`, set a token in the process environment before starting pi:
+For automatic related-PR lookup and `pull_request`, set a token in the process environment before starting pi:
 
 ```bash
 export GITHUB_TOKEN=github_pat_...
@@ -160,15 +164,15 @@ Run `pull_request` only after `push_branch` has completed; `pull_request` prefli
 
 ## Configuration
 
-BranchMe has no project config file. It reads process environment variables for GitHub pull request creation and optional repository boundary checks, with a local `.env` token fallback when no process token is set. Token lookup checks `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`; if neither is set, BranchMe reads `.env` from the verified git root and checks `GITHUB_TOKEN`, then `GH_TOKEN`.
+BranchMe has no project config file. It reads process environment variables for automatic related-PR lookup, GitHub pull request creation, and optional repository boundary checks, with a local `.env` token fallback when no process token is set. Token lookup checks `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`; if neither is set, BranchMe reads `.env` from the verified git root and checks `GITHUB_TOKEN`, then `GH_TOKEN`.
 
 | Variable | Meaning |
 | --- | --- |
-| `GITHUB_TOKEN` | Preferred token for `pull_request`; process environment first, then local `.env` fallback. |
-| `GH_TOKEN` | Fallback token for `pull_request`; process environment first, then local `.env` fallback. |
+| `GITHUB_TOKEN` | Preferred token for automatic related-PR lookup and `pull_request`; process environment first, then local `.env` fallback. |
+| `GH_TOKEN` | Fallback token for automatic related-PR lookup and `pull_request`; process environment first, then local `.env` fallback. |
 | `GITHUB_REPOSITORY=owner/repo` | Optional CI fallback and boundary check for the current GitHub repository; process environment only. |
 
-BranchMe reads only `GITHUB_TOKEN` and `GH_TOKEN` from a small regular `.env` file; it rejects directories, symlinks, special files, and oversized files. BranchMe does not import other `.env` keys, read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from errors, tool content, and tool details.
+BranchMe reads only `GITHUB_TOKEN` and `GH_TOKEN` from a small regular `.env` file; it rejects directories, symlinks, special files, and oversized files. BranchMe does not import other `.env` keys, read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from automatic context, errors, tool content, and tool details.
 
 If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, `pull_request` fails closed.
 
@@ -191,7 +195,7 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 
 | Tool | Schema | Behavior |
 | --- | --- | --- |
-| `branch_status` | `{}` | Read-only git status: repo root, current branch or detached state, upstream, dirty state, ahead/behind counts, and GitHub repository when resolvable. |
+| `branch_status` | `{}` | Explicitly refreshes the same bounded context used at agent start: repo root in structured details, branch/detached state, upstream and ahead/behind counts, working-tree counts and unstaged/untracked paths, related open PR, and recent commits. It is read-only. |
 | `change_branch` | `{ "branchName": string }` | Validates `branchName`, requires `refs/heads/<branchName>` to exist locally, rejects dirty worktrees, and runs `git switch <branchName>`. |
 | `create_branch` | `{ "branchName": string }` | Validates `branchName`, rejects existing local branches, and runs `git switch -c <branchName>` from current `HEAD`. |
 | `push_branch` | `{}` | Pushes the current branch to its configured upstream remote with an explicit `HEAD:<upstream-branch-ref>` refspec, or publishes it with `git push --set-upstream origin <currentBranch>` when no upstream exists. |
@@ -203,6 +207,24 @@ All schemas reject additional properties. `change_branch` never accepts `baseRef
 
 ## Workflow and Boundaries
 
+### Automatic context and freshness
+
+Before each agent run, BranchMe appends an **Automatic Git Context** snapshot to the existing system prompt. The snapshot contains these fields in order:
+
+- current branch or detached `HEAD`, plus upstream and ahead/behind counts when available;
+- working-tree state and staged, unstaged, and untracked counts;
+- up to 20 unstaged or untracked change entries with Git status, path, and original path for renames/copies;
+- related open PR status and, when found, its number, title, repository, head/base branches, URL, state, and draft flag;
+- up to 5 recent commits with short hash, date, and subject.
+
+Collection defaults are a 5-second timeout per local Git command, a 4-second related-PR lookup timeout, at most 512 characters per metadata value, and at most 4,000 characters for the rendered snapshot. GitHub response bodies are limited to 64 KiB. The formatter can further shorten values or omit entries to stay within the total limit.
+
+The snapshot is fresh at agent start but is not live. A branch switch, commit, file change, push, or other mutation later in the same run can make it stale. `branch_status` performs an explicit current-state refresh through the same shared collector and remains read-only; it does not mutate files, Git state, or GitHub state.
+
+Related-PR metadata does not come from Git alone. When repository, branch, and credentials resolve, automatic collection and explicit `branch_status` may make an authenticated `GET /repos/{owner}/{repo}/pulls?state=open&head={owner}:{branch}&per_page=1` request. Without a token there is no unauthenticated fallback or GitHub request; the PR field is reported as unavailable while local Git context remains usable.
+
+Repository paths, commit subjects, branch names, and PR titles are treated as untrusted metadata. BranchMe redacts token values, escapes control characters, quotes and bounds values before prompt insertion, and never captures diffs or file contents. Staged files contribute only to the staged count; the path list is limited to unstaged and untracked entries.
+
 Use BranchMe from pi prompts or automation that drives pi with explicit tool calls:
 
 ```text
@@ -214,6 +236,7 @@ After push_branch completes, create a draft pull request from feature/docs-refre
 
 BranchMe operates only on the repository where pi is running:
 
+- Automatic collection and `branch_status` run bounded, read-only Git commands from the verified git root.
 - Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root.
 - `change_branch` switches only to existing local branches and has no `force`, `stash`, `discard`, remote, or path input.
 - `create_branch` creates from the current `HEAD` only and has no `baseRef` input.
@@ -269,6 +292,7 @@ Ensure the token and Git credentials have permission for the branch and pull req
 | Branch does not exist locally | Create a local branch first; `change_branch` does not checkout remote branches. |
 | Dirty worktree before branch switch | Commit, stash, or discard changes outside BranchMe before using `change_branch`. |
 | Push fails | Confirm the current branch is correct and your normal Git remote credentials can push. |
+| Related PR is unavailable | Set `GITHUB_TOKEN` or `GH_TOKEN` before starting pi if related-PR context is wanted. Without a token, BranchMe keeps local context and intentionally makes no unauthenticated GitHub request. |
 | PR auth fails | Set `GITHUB_TOKEN` or `GH_TOKEN` before starting pi, or copy `.env.example` to `.env` and fill in one token. |
 | PR branch does not exist locally | Create or fetch/check out the local `headBranch` and `baseBranch` branches first; BranchMe does not use remote-only or cross-repository PR refs. |
 | PR branch is not visible or is stale on GitHub | Run `push_branch`, wait for it to complete, then retry `pull_request`; do not batch `push_branch` and `pull_request` in the same assistant tool call. |
@@ -288,7 +312,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, unit tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 

package/SECURITY.md

@@ -19,19 +19,24 @@ Implemented git mutations are limited to:
 - `create_branch`: `git switch -c <branchName>` from current `HEAD` after branch-name validation and existing-branch checks.
 - `push_branch`: `git push <upstreamRemote> HEAD:<upstreamBranchRef>` for the current branch when an upstream exists, or `git push --set-upstream origin <currentBranch>` when no upstream exists.
 
+Before each agent run, BranchMe also runs bounded, read-only Git commands to collect branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged or untracked path entries, and up to 5 recent commits. The same collector runs when `branch_status` explicitly refreshes context. Collection does not run `switch`, `push`, `add`, `commit`, or any other mutation, and it never reads diffs or file contents.
+
 Branch switching can update working-tree files as normal Git checkout behavior. Mutating branch operations for the same repository are serialized to avoid same-turn branch races. `pull_request` also uses the same repository queue around PR preflight and creation so it can wait behind an already-started same-repository push. BranchMe rejects dirty worktrees before `change_branch` and does not force checkout, stash, stage files, create commits, reset, rebase, merge, or edit files directly.
 
 ## Network behavior
 
-BranchMe makes network requests only for `pull_request`, which calls the GitHub REST API:
+BranchMe's GitHub helpers use these REST API requests:
 
 ```text
+GET  https://api.github.com/repos/{owner}/{repo}/pulls?state=open&head={owner}:{currentBranch}&per_page=1
 GET  https://api.github.com/repos/{owner}/{repo}/branches/{headBranch}
 GET  https://api.github.com/repos/{owner}/{repo}/branches/{baseBranch}
 POST https://api.github.com/repos/{owner}/{repo}/pulls
 ```
 
-The branch preflight requests have no body. BranchMe uses the `headBranch` preflight response to compare GitHub's branch commit with the local branch commit before creating the PR. The PR request body contains only the explicit PR fields supplied to the tool: title, head branch, base branch, body, and draft flag.
+The first request is an automatic network boundary: it can run before each agent run and whenever `branch_status` explicitly refreshes context. It is a bounded, read-only lookup for one open pull request whose head is the current local branch (`per_page=1`), with a default 4-second timeout and a 64 KiB response-body limit. It is skipped when repository/branch resolution or authentication is unavailable, so BranchMe never makes an unauthenticated fallback request. Timeout, HTTP, network, malformed, and oversized-response failures become a safe unavailable state without exposing response bodies or raw network errors. Git alone is not used or claimed to provide PR metadata.
+
+The branch preflight requests have no body. BranchMe uses the `headBranch` preflight response to compare GitHub's branch commit with the local branch commit before creating the PR. The PR request body contains only the explicit PR fields supplied to the tool: title, head branch, base branch, body, and draft flag. All GitHub response reads are bounded.
 
 ## Repository boundary
 
@@ -40,22 +45,28 @@ BranchMe operates on the current repository only.
 - The GitHub repository is inferred from local `origin` and/or `GITHUB_REPOSITORY`.
 - Tool inputs never accept filesystem paths, `owner`, `repo`, or owner-prefixed `owner:branch` PR refs.
 - `change_branch` accepts only `branchName` and never creates branches, checks out remote branches, forces, stashes, or discards changes.
-- If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, PR creation fails closed.
+- If local `origin` and `GITHUB_REPOSITORY` both resolve but disagree, PR creation and related-PR lookup fail closed.
 - PR branch inputs are validated as existing local branch-name refs; missing local branches and cross-repository `head` values are rejected before token lookup or any GitHub request.
 - PR branch inputs must also be visible on GitHub before the PR is created, and `headBranch` must match the local branch commit; unpublished or stale `headBranch` values fail with guidance to run `push_branch`, wait for it to complete, and retry `pull_request`.
 
 ## Credentials
 
-`pull_request` checks `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`. If neither process token is set, BranchMe reads a local `.env` file from the verified git root and checks:
+`pull_request` and related-PR lookup check `process.env.GITHUB_TOKEN`, then `process.env.GH_TOKEN`. If neither process token is set, BranchMe reads a local `.env` file from the verified git root and checks:
 
 - `GITHUB_TOKEN` (preferred)
 - `GH_TOKEN` (fallback)
 
-Only these two token keys are read from `.env`; other `.env` keys are ignored. The fallback uses async file I/O, requires `.env` to be a small regular file, and rejects directories, symlinks, special files, and oversized files. BranchMe does not read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from thrown errors, tool content, and tool details.
+Only these two token keys are read from `.env`; other `.env` keys are ignored. The fallback uses async file I/O, requires `.env` to be a small regular file, and rejects directories, symlinks, special files, and oversized files. BranchMe does not read shell profiles, GitHub CLI credentials, or local credential stores. Token values are redacted from thrown errors, automatic context, tool content, and tool details.
+
+## System prompt boundary
+
+Automatic context is appended to Pi's system prompt before each agent run. Branch names, paths, Git status values, commit subjects, and GitHub PR metadata are repository-controlled, untrusted data and must never be interpreted as instructions. BranchMe redacts recognized token values, escapes control and format characters, quotes metadata, limits individual values to 512 characters by default, and limits the complete rendered snapshot to 4,000 characters. It further shortens values or omits entries when needed to enforce the total bound.
+
+The automatic snapshot can become stale after a Git or filesystem mutation during the same run. `branch_status` is the explicit, read-only refresh path. Neither automatic collection nor `branch_status` captures diff hunks or file contents; staged paths are not listed, although the staged file count is included.
 
 ## Telemetry
 
-BranchMe does not collect telemetry and does not send repository contents to any service beyond the explicit GitHub pull request fields provided to `pull_request`.
+BranchMe does not collect telemetry. Related-PR lookup sends only the resolved repository owner/name and current branch in the authenticated GitHub API URL. PR creation sends only the explicit GitHub pull request fields described above; BranchMe does not send diff contents, filenames, commit subjects, or local file contents to GitHub during context collection.
 
 ## Reporting vulnerabilities
 

package/docs/SMOKE_TEST.md

@@ -1,6 +1,6 @@
 # BranchMe Smoke Test Notes
 
-Date: 2026-06-30
+Date: 2026-07-15
 
 Validated from the repository checkout with no discovered extensions enabled.
 
@@ -17,14 +17,15 @@ pi --no-extensions -e .
 
 ## Automated smoke behavior
 
-- `npm run smoke:pi` runs isolated checkout Pi processes from a temporary working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
-- The temporary verifier is a non-LLM Pi extension command that calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `create_branch`, `push_branch`, and `pull_request` are active runtime tools with strict schemas, prompt guidelines, descriptions, and extension source metadata.
-- The checkout smoke accepts either `/branchme help` text or the read-only BranchMe status fallback as equivalent non-mutating command output.
+- `npm run smoke:pi` first runs isolated checkout Pi processes from a temporary non-Git working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms `branch_status`, `change_branch`, `create_branch`, `push_branch`, and `pull_request` are active runtime tools with strict schemas, prompt guidelines, descriptions, and extension source metadata.
+- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback.
+- The checkout command smoke accepts either `/branchme help` text or the read-only BranchMe status fallback as equivalent non-mutating command output.
 - `npm run smoke:pi:packed` creates an npm tarball under a temporary directory, installs that tarball into a separate temporary package with `npm install --omit=dev`, and runs pi against the installed package instead of the source checkout.
 - `npm run smoke:pi:packed` is the release gate for packaged runtime imports and required packaged files; `npm run release:check` and `node scripts/publish-npm.mjs` run it before publish, while everyday `npm run validate` keeps the faster checkout smoke.
 - Both smoke runs disable discovered extensions, skills, prompt templates, themes, context files, persistent sessions, telemetry, startup network checks, and GitHub token environment variables.
 - Both smoke runs are credential-free, allow documented credential variable names in help text, reject credential value patterns, do not call BranchMe mutation tools, and do not contact GitHub.
-- Pi's documented `getAllTools()` metadata currently exposes parameter schemas and prompt guidelines, but not `promptSnippet`, and the ExtensionAPI does not expose a safe non-LLM tool invocation method. The checkout runtime smoke therefore gates real Pi tool registration metadata; isolated `branch_status` execution remains covered by mocked unit tests and real-git helper tests until Pi exposes a direct runtime invocation API.
+- Pi's documented `getAllTools()` metadata currently exposes parameter schemas and prompt guidelines, but not `promptSnippet`. The deterministic local smoke model exercises `branch_status` through Pi's normal model tool-call loop without provider or GitHub network access.
 - Set `BRANCHME_SKIP_PI_SMOKE=1` to skip intentionally, or `BRANCHME_PI_BIN=/path/to/pi` to test a specific Pi binary for the checkout smoke.
 - If no Pi binary is available, the checkout smoke script prints an explicit skip message; default CI installs the Pi dev dependency, so `npm run validate` exercises the real Pi loading path.
 
@@ -32,6 +33,7 @@ pi --no-extensions -e .
 
 - `npm run validate` passed.
 - `npm run smoke:pi` loaded BranchMe through Pi, verified all five BranchMe tools through the real `pi.getAllTools()` runtime surface, and confirmed non-mutating BranchMe command output.
+- The isolated Git-context prompt smoke observed the `before_agent_start` snapshot, answered branch and dirty-tree state without a tool call, refreshed a verifier-created local change through one real `branch_status` call, returned safe unavailable context without credentials or outside Git, and attempted no network request.
 - `npm run smoke:pi:packed` packed BranchMe outside the repository, installed the artifact in a temporary production workspace, loaded the installed package through Pi, and confirmed non-mutating BranchMe command output.
 - `npm run check:pack` confirmed the package contents are limited to public docs, images, source, license, package metadata, `.env.example`, and `tsconfig.json`.
 - The isolated Pi smoke command loaded BranchMe and displayed BranchMe help or status output instead of template behavior.

package/docs/STRUCTURE.md

@@ -6,9 +6,10 @@ BranchMe is a TypeScript Pi extension package for current-repository git branch,
 
 ```text
 src/
-├── extension.ts                  # extension entry point; registers command and tools only
-├── constants.ts                  # command/tool names, timeouts, GitHub API constants
+├── extension.ts                  # extension entry point; registers command, tools, and context hook
+├── constants.ts                  # names plus Git, context, timeout, API, and output bounds
 ├── types.ts                      # serializable tool details and helper result types
+├── git-context.ts                # shared collector/formatter and before_agent_start prompt hook
 ├── commands/
 │   └── branchme-command.ts       # /branchme status/help command; informational only
 ├── tools/
@@ -21,27 +22,34 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and only calls `registerBranchMeCommand(pi)` and `registerBranchMeTools(pi)`.
-2. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
-3. `src/tools/branchme-tools.ts` owns TypeBox schemas, prompt metadata, tool content, and safe structured details.
-4. `src/git.ts` owns current-repository git behavior: root detection, branch/upstream/status inspection, branch validation, branch creation, existing-local-branch switching, clean-worktree preflight, current-branch push/publish, and the per-repository workflow queue.
-5. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` process-env and hardened git-root `.env` fallback resolution, PR branch-name syntax validation, GitHub branch visibility/commit preflight, PR REST calls, response validation, and redacted errors.
-6. `src/redaction.ts` owns shared credential redaction for Git and GitHub messages.
-7. `src/types.ts` keeps serializable details shared by helpers and tools.
-8. `src/ui/branchme-panel.ts` renders a compact status panel and clips lines to terminal width.
+1. `src/extension.ts` stays small and registers the command, five tools, and one `before_agent_start` context hook.
+2. `src/git-context.ts` owns the shared read-only collector, escaped/bounded formatter, automatic system-prompt append, and the current-state output used by `branch_status`.
+3. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
+4. `src/tools/branchme-tools.ts` owns TypeBox schemas, prompt metadata, tool content, and safe structured details. `branch_status` delegates to the shared context collector for an explicit refresh.
+5. `src/git.ts` owns current-repository git behavior: root detection, branch/upstream/ahead-behind inspection, working-tree parsing, recent-commit collection, branch validation, branch creation, existing-local-branch switching, clean-worktree preflight, current-branch push/publish, and the per-repository workflow queue.
+6. `src/github.ts` owns GitHub `owner/repo` parsing, repository boundary checks, `GITHUB_TOKEN`/`GH_TOKEN` process-env and hardened git-root `.env` fallback resolution, authenticated related-open-PR lookup, PR branch-name syntax validation, GitHub branch visibility/commit preflight, PR REST calls, bounded response validation, and redacted errors.
+7. `src/redaction.ts` owns shared credential redaction for Git, GitHub, and prompt-bound metadata.
+8. `src/types.ts` keeps serializable details shared by helpers, context, and tools.
+9. `src/ui/branchme-panel.ts` renders a compact status panel and clips lines to terminal width.
 
 ## Pi extension conventions
 
 - No long-lived processes, watchers, timers, sockets, or background jobs start in the extension factory.
-- Slash commands are informational; tools perform branch, push, and PR actions.
+- A single `before_agent_start` handler synchronously collects a fresh snapshot for each agent run and appends it to the existing system prompt; failures degrade to bounded unavailable context rather than blocking startup.
+- Slash commands are informational; tools perform branch, push, and PR actions. There is no context command or sixth tool.
 - Every tool uses a strict TypeBox object schema with `additionalProperties: false`.
 - Every tool defines a description, `promptSnippet`, and tool-specific `promptGuidelines` that explicitly name the tool.
 - Git commands use `pi.exec("git", args, { cwd, signal, timeout })` with argv arrays; repository mutations run from the verified git root and same-repository mutation/PR windows are serialized per repository.
 - Tool details avoid token values and unbounded raw command/API output.
+- Automatic and explicit context include branch/upstream/ahead-behind state, working-tree counts, up to 20 unstaged/untracked entries, related open PR state, and up to 5 recent commits. Metadata values default to 512 characters and rendered context to 4,000 characters.
 - Pi core packages, including `@earendil-works/pi-tui` for key/width utilities, remain in `peerDependencies` with `"*"`.
 
 ## Security-sensitive areas
 
+- Automatic context and `branch_status` share bounded, read-only collection. They run no mutations and capture repository metadata only—never diffs or file contents.
+- Repository-controlled paths, branch names, commit subjects, and PR fields are escaped, quoted, redacted, bounded, and labeled untrusted before system-prompt insertion.
+- Related-PR lookup may issue an authenticated `GET /pulls` before every agent run and on explicit refresh. It has a 4-second timeout and 64 KiB response limit, and makes no unauthenticated fallback request.
+- The start-of-run snapshot may be stale after a mutation in that same run; `branch_status` is the explicit read-only refresh.
 - `change_branch` mutates local HEAD and working-tree files only through `git switch <branchName>` for existing local branches after a clean-worktree preflight.
 - `create_branch` mutates local branch/HEAD only with `git switch -c`.
 - `push_branch` mutates remote refs only for the current branch and uses an explicit upstream remote/refspec instead of bare `git push` when an upstream exists.
@@ -61,11 +69,12 @@ src/
 ```text
 test/
 ├── command.test.mjs      # /branchme parsing, help, fallback, panel width
+├── git-context.test.mjs  # collection, prompt hook, formatting, safety, and output bounds
 ├── git.test.mjs          # git helper command construction and failures
-├── git-integration.test.mjs # isolated real-git branch helper coverage
-├── github.test.mjs       # GitHub parsing, token resolution, fetch wrapper, redaction
+├── git-integration.test.mjs # isolated real-git context and branch helper coverage
+├── github.test.mjs       # GitHub parsing, token resolution, related-PR lookup, redaction
 ├── preparation.test.mjs  # package/docs/source metadata checks
-├── tools.test.mjs        # extension registration, schemas, prompt metadata, tool behavior
+├── tools.test.mjs        # extension registration, schemas, shared refresh, tool behavior
 └── tui-capture.test.mjs  # generated text capture for TUI/help visual baselines
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Minimal Pi extension for current-repository git branch, push, and pull request workflows.",
   "license": "MIT",
@@ -50,9 +50,9 @@
     "format:check": "node scripts/check-format.mjs",
     "test": "node --test test/*.test.mjs",
     "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
-    "smoke:pi": "node scripts/smoke-pi-runtime.mjs",
+    "smoke:pi": "node scripts/smoke-pi-runtime.mjs && node scripts/smoke-pi-git-context.mjs",
     "smoke:pi:packed": "node scripts/smoke-pi-installed-package.mjs",
-    "check": "node --check scripts/check-format.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/publish-npm.mjs && node --check scripts/smoke-pi-installed-package.mjs && node --check scripts/smoke-pi-runtime.mjs",
+    "check": "node --check scripts/check-format.mjs && node --check scripts/check-package-contents.mjs && node --check scripts/publish-npm.mjs && node --check scripts/smoke-pi-git-context.mjs && node --check scripts/smoke-pi-installed-package.mjs && node --check scripts/smoke-pi-runtime.mjs",
     "pack:dry-run": "npm pack --dry-run --json",
     "check:pack": "node scripts/check-package-contents.mjs",
     "validate": "npm run typecheck && npm run format:check && npm run test && npm run smoke:pi && npm run check && npm run check:pack",

package/src/constants.ts

@@ -18,6 +18,12 @@ export const BRANCHME_TOOL_NAMES = [
 export const GIT_STATUS_TIMEOUT_MS = 5_000;
 export const GIT_MUTATION_TIMEOUT_MS = 30_000;
 export const GIT_PUSH_TIMEOUT_MS = 120_000;
+export const GITHUB_RELATED_PR_TIMEOUT_MS = 4_000;
+
+export const GIT_CONTEXT_RECENT_COMMIT_LIMIT = 5;
+export const GIT_CONTEXT_CHANGE_LIMIT = 20;
+export const GIT_CONTEXT_VALUE_LIMIT_CHARS = 512;
+export const GIT_CONTEXT_SUMMARY_LIMIT_CHARS = 4_000;
 
 export const GITHUB_API_BASE_URL = "https://api.github.com";
 export const GITHUB_API_VERSION = "2022-11-28";

package/src/extension.ts

@@ -1,10 +1,12 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerBranchMeCommand } from "./commands/branchme-command.ts";
+import { registerGitContextAwareness } from "./git-context.ts";
 import { registerBranchMeTools } from "./tools/branchme-tools.ts";
 
 export function branchMeExtension(pi: ExtensionAPI): void {
   registerBranchMeCommand(pi);
   registerBranchMeTools(pi);
+  registerGitContextAwareness(pi);
 }
 
 export default branchMeExtension;