# End-of-task Checkpoint Contract

ITHZ-MCP uses a two-profile model:

- `read-only`: startup, search and context-pack tools.
- `write-enabled`: explicit end-of-task memory writes.

The read-only profile remains the safe default. It does not expose write tools.

## Startup

At the beginning of a new agent thread:

1. Read `project.md`.
2. Call `ithz_context_status`.
3. Call `ithz_archive_get_context_pack` for the task.
4. Inspect candidate files and evidence gaps from the pack.

## End of Task

At the end of a non-trivial task, the agent should record:

- task summary;
- decisions;
- gates/tests;
- risks or must-not-break items;
- next steps;
- documentation impact;
- memory impact;
- optional prompt/response summary;
- optional read-only Git metadata.

CLI:

```powershell
python -m ithz_mcp archive-finalize-task `
  --project . `
  --task "short task name" `
  --summary task_summary.md `
  --docs-impact updated `
  --memory-impact handoff-created `
  --gate "Gate: run-ci-fast passed" `
  --decision "Decision: keep write tools explicit" `
  --next "Next step: real host smoke" `
  --snapshot `
  --snapshot-mode auto
```

This appends events into `project.ithz`, refreshes derived indexes and can create a snapshot. In `auto` mode, large archives defer snapshot creation rather than timing out at the end of the task; the checkpoint append still completes. For MCP hosts, large memory zones can return a quick `queued=true` response and finish the native archive write in a local background worker, avoiding host request timeouts without changing the single `project.ithz` memory model.

## Project Intake

When a new project starts with existing workflow Markdown, mine durable facts into `project.ithz`:

```powershell
python -m ithz_mcp archive-ingest-project-memory `
  --project . `
  --source AI_PROJECT_BRIEF.md `
  --source WORKFLOW_RULES.md `
  --source DECISIONS_LOG.md `
  --note "Initial workflow import"
```

The intake extracts durable workflow, decision, gate, risk, deployment and next-step facts. It does not store the full raw files as chat memory.

## Safety

- Raw prompt/response capture is never automatic.
- Summary mode stores summaries and hashes, not raw full chat.
- Secret-like source files are skipped.
- Secret-like payloads are redacted or blocked.
- Local-only prompt memory is skipped by team sync.
- `project.md` remains the bootstrap.
- `project.ithz` is the memory zone.
- ITHZ-MCP complements Git; it does not replace Git.
