> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_08_file_and_git.md).

# Session 08: File And Git

**Session ID**: `phase19-session08-file-and-git` **Packages**: apps/server, apps/web, apps/hooks **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Implement file intent protection and Git workbench execution as the first concrete executor families.

***

## Scope

### In Scope (MVP)

* Active write/edit file intents with owner hero, operation, path label, TTL, related task, conflict state, and resolution action
* File conflict prevented events linked to queue items, guarded actions, and reassignment or override decisions
* Git proposal previews and execution for changes, stage, unstage, commit, push, stash, revert, switch branch, dirty state, conflicts, and git-risk guards
* Per-agent attribution where current file-access or tool-use data supports it
* Tests for conflict checks, lock TTL, Git previews, execution results, and attribution rendering

### Out of Scope

* Terminal command execution
* Broad raw path, diff, or command body display outside scoped drawers

***

## Prerequisites

* [ ] Sessions 05 through 07 complete
* [ ] Current file access, guarded action, Git docs, and hook data inspected

***

## Deliverables

1. File intent manager and conflict-check routes
2. Git workbench manager and guarded execution wiring
3. File intent lane and Git summary in Orchestration
4. Server, hook, and web tests for conflicts and Git decisions

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 08: File And Git
* Implementation Targets 5 and 13 for file conflict protection and Git/Codex workbench cross-links
* Balls-To-The-Wall Track B `fileIntentManager` and `gitWorkbenchManager` routes
* Execution Family Order item 3 for file intents/conflict checks and Git workbench execution

Key EXAMPLES links:

* [File access conflict flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-file-access.sh#L76-L116)
* [File conflict routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L55-L81)
* [File intent WebSocket events](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/websocket-events.txt#L38-L41)
* [Git panel guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L224-L232)
* [Git routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L42-L54)
* [Git guard](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-git-guard.sh#L1-L98)

***

## Success Criteria

* [ ] Conflicting writes/edits surface as actionable warnings tied to owners and tasks
* [ ] Git proposals can be approved or rejected and record execution results
* [ ] Dirty, conflict, and file-intent states update live in the panel
* [ ] Broad UI uses repo-relative labels and avoids absolute path leakage


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_08_file_and_git.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.