# Team Workflow With Git

## Product Model

ITHZ-MCP uses a two-file project memory model:

```text
project.md   = normal text bootstrap for humans and agents
project.ithz = deterministic agent memory zone
Git          = code-history transport
ITHZ-MCP     = semantic memory reader/writer/merge layer
```

Markdown is the bootstrap. ITHZ is the memory zone.

ITHZ-MCP does not replace Git. Git still owns source history, branches,
commits, pull, push and code review. ITHZ-MCP stores and merges agent work
memory: decisions, gates, risks, claims, prompt summaries, checkpoints,
workflow profiles and next steps.

## What Installation Adds

When `install-project` runs inside a Git repository, it should prepare the
repository for team use:

```powershell
python -m ithz_mcp install-project --apply
```

The installer creates or validates:

```text
project.md
project.ithz
.gitattributes
```

If `.gitattributes` already exists, the installer preserves it and appends only
the ITHZ rule if missing:

```gitattributes
*.ithz merge=ithz diff=ithz binary
```

The installer also configures the local Git driver in this checkout:

```text
merge.ithz.name = ITHZ semantic merge driver
merge.ithz.driver = python -m ithz_mcp git-merge-ithz --base %O --ours %A --theirs %B --out %A
diff.ithz.textconv = python -m ithz_mcp git-diff-ithz --archive
```

This local config is stored in `.git/config`. It is not committed, so each team
member must install ITHZ-MCP or run the driver setup locally.

```powershell
python -m ithz_mcp install-git-drivers --repo .
python -m ithz_mcp git-driver-status --repo .
```

ITHZ-MCP does not run `git add`, `git commit`, `git push`, `git reset` or
`git checkout` automatically.

## Normal Team Workflow

For ordinary work, a developer can use the usual Git flow:

```powershell
git pull
python -m ithz_mcp archive-get-context-pack --project . --query "current task"
# work
python -m ithz_mcp archive-finalize-task --project . --task "..." --summary-text "..."
git add project.md project.ithz .gitattributes
git commit -m "Update project and agent memory"
git push
```

`project.md` is normal text. Git merges it like any other Markdown file.

`project.ithz` is a binary archive. Git transports it, but ITHZ-MCP performs
the semantic merge when two team members changed it in parallel.

## How Git Calls The ITHZ Driver

Git uses two pieces of configuration:

- `.gitattributes` says that `*.ithz` files use the driver named `ithz`;
- `.git/config` says which command the `ithz` driver runs.

When a pull, merge or rebase sees parallel changes to `project.ithz`, Git invokes
the merge driver with three files:

```powershell
python -m ithz_mcp git-merge-ithz --base %O --ours %A --theirs %B --out %A
```

The placeholders come from Git:

```text
%O = common base archive
%A = our working-tree archive and expected output path
%B = their archive
```

The merge driver reads logical memory layers inside the archives instead of
trying to merge raw binary bytes.

## Parallel Work Example

Starting state:

```text
base project.ithz:
  ctx_100
  decision_20
  gate_15
```

Developer A adds:

```text
ctx_101_gobi
prompt_summary_45
decision_21
```

Developer B adds:

```text
ctx_102_peter
gate_16
risk_08
```

The merged archive should contain both sets of independent memory:

```text
merged project.ithz:
  ctx_100
  decision_20
  gate_15
  ctx_101_gobi
  prompt_summary_45
  decision_21
  ctx_102_peter
  gate_16
  risk_08
```

The intended rule is union of independent append-only objects, not "ours wins"
or "theirs wins".

## What Auto-Merges

The driver may auto-merge:

- independent context commits;
- independent task checkpoints;
- independent decisions;
- independent gates and test results;
- independent risks and must-not-break rules;
- independent claims and blocked claims;
- independent reviewer notes;
- independent replication-pack records;
- independent prompt or response summaries;
- independent workflow profiles, such as `gobi` and `colleague`;
- non-conflicting branches, tags and refs;
- rebuilt derived indexes and snapshots.

Stable object identity matters. Records should have deterministic IDs, content
hashes, author or workflow profile metadata, and enough provenance for the merge
driver to distinguish duplicates from conflicts.

## What Becomes `merge_needed`

The driver must refuse unclear or unsafe merges. It should return `merge_needed`
and write a merge report when it finds:

- the same context commit ID with different content;
- a historical event modified or removed;
- a historical prompt record modified;
- the same workflow profile changed incompatibly on both sides;
- the same ref moved to two incompatible heads;
- an invalid or corrupted archive;
- native safe verify failure;
- secret-like payload;
- private or local-only prompt memory that cannot be safely represented;
- a conflict in `project.md`, which remains Git's normal text-merge problem.

The merge report is the handoff for a human or agent review. The driver should
not invent a semantic decision when the memory facts disagree.

## Private And Secret Memory

Prompt memory can include sensitive material, so team merge follows conservative
rules:

- `full-local-only` prompt memory is skipped from team merge output;
- secret-like payloads block the merge instead of being copied;
- redacted prompt summaries may merge when their hashes and provenance are valid;
- private workflow notes remain local unless explicitly recorded as team-safe.

## What To Commit

Usually commit:

```text
project.md
project.ithz
.gitattributes
```

Do not commit local installer scratch data, locks or host-specific generated
files unless a workflow explicitly says so:

```text
.ithz-install/
project.ithz.lock
.mcp.json
.antigravity/
.claude/
.cursor/
```

Host configs are usually machine-local because paths and available MCP hosts
differ between developers.

## Teammate Onboarding Checklist

For a teammate joining an existing project:

```powershell
git clone <repo>
cd <repo-or-subproject>
python -m ithz_mcp install-project --apply
python -m ithz_mcp git-driver-status --repo .
python -m ithz_mcp archive-get-context-pack --project . --query "current status"
```

If `project.ithz` already came from Git, `install-project` should verify and
reuse it. It should append this developer's workflow or prompt-memory summaries
only through explicit redacted intake and should not replace the archive.

## Troubleshooting

If Git reports a plain binary conflict for `project.ithz`, check:

```powershell
git check-attr merge diff -- project.ithz
python -m ithz_mcp git-driver-status --repo .
```

Expected attributes:

```text
project.ithz: merge: ithz
project.ithz: diff: ithz
```

If attributes are present but the driver command is missing, run:

```powershell
python -m ithz_mcp install-git-drivers --repo .
```

If the merge driver returns `merge_needed`, inspect the generated report and do
not choose "ours" or "theirs" blindly. The report should explain whether the
problem is rewritten history, incompatible refs, same-profile divergence,
invalid archive data or secret-like memory.
