Skip to content

Workspaces and worktrees

Target

This page describes intended behaviour or structure. No implementation is claimed unless a section is explicitly marked Current implementation or Evidence.

Each code-modifying run receives an isolated workspace (a Git worktree or equivalent) so concurrent agents never share a working tree. Large repositories are never dumped into model context; agents use repository tools over an index.

Workspace lifecycle

flowchart LR
    Snap["Approved repository revision"] --> WS["Workspace for run N<br/>(worktree, ephemeral)"]
    WS --> Tools["Read tools first: list, search, read range, references, dependencies"]
    Tools --> Change["Write tools under policy: patch, create, move, build, test"]
    Change --> Diff["Proposed diff + checks (sandbox)"]
    Diff --> Review["Exact-version approval"]
    Review --> Deliver["Branch / PR via connector; delivery receipt"]
    Deliver --> Clean["Workspace expires; artifacts kept by reference"]
Hold "Alt" / "Option" to enable pan & zoom

Repository intelligence (target)

File tree, symbol index, type graph, dependency graph, call graph, references, Git history, ownership, build graph, test relationships and semantic embeddings, exposed as tools: list_files, search_text, search_symbols, find_references, read_file, read_range, get_dependencies, get_git_diff, apply_patch, create_file, delete_file, move_file, build, test, git_status. The read-only subset is sufficient for an assessment workflow; write tools require a sandbox and approval binding.

Rules

  • Resolved paths are validated against the authorized workspace root; arbitrary host paths are rejected.
  • File size, file count and context budget are bounded; credentials, private keys and unrelated content are excluded.
  • Repository text is evidence with origin and trust labels (tool policies); it never grants tool permissions.
  • The system of record for branches, commits and pull requests is Azure DevOps or GitHub; the Factory keeps receipts, not a parallel Git (ownership map, BC-23).

Current implementation

No workspace manager, repository index or governed write tools exist. The packet's worked example (read-only repository assessment) assumes bounded direct reads of an approved snapshot and needs none of the write path.