# Comment Workflow

> Sync source: `docs/COMMENT-WORKFLOW.md`, `src/core/format/ooxml/`

For files that already have content, propose changes as **suggestion comments** instead of overwriting text. Each proposal lives in a comment and stays visible until explicitly approved.

## Flow

1. `edit` the existing file to open its draft (auto-acquires the lock)
2. Attach a suggestion comment to the changed spot
3. `list-comments` to inspect pending suggestions
4. `approve` to apply one suggestion into the draft (comment removed)
5. `accept` to write the file

## DOCX example

```
officecli(action="edit", filePath="/path/to/report.docx", content="# Updated draft")
officecli(action="comment", filePath="/path/to/report.docx",
  commentId="c1", author="AI Agent", commentText="Tighten summary",
  suggestedText="Revised paragraph text",
  rangeStartParagraph=0, rangeStartOffset=0, rangeEndParagraph=0, rangeEndOffset=10)
officecli(action="list-comments", filePath="/path/to/report.docx")
officecli(action="approve", filePath="/path/to/report.docx", commentId="c1")
officecli(action="accept", filePath="/path/to/report.docx")
```

## Supported formats

| Format | Comments | Track changes |
| --- | --- | --- |
| DOCX | yes (range anchor) | yes, via `track-insert` / `track-delete` (`w:ins`/`w:del`) |
| XLSX | yes (`cellRef` anchor, value suggestions) | no — use `comment` with `suggestedText` |
| PPTX | yes (`slide` anchor) | no — use `comment` with `suggestedText` |

## API

### Add comment

```
officecli(action="comment", filePath="...", commentId="c1", author="AI Agent", commentText="...")
```

Anchor per format:

- **DOCX (range-based)**: `rangeStartParagraph`, `rangeStartOffset`, `rangeEndParagraph`, `rangeEndOffset`
- **XLSX (cell-based)**: `cellRef` (e.g. `"B4"`)
- **PPTX (slide-based)**: `slide` (index)

Optional: `suggestedText` makes the comment an approvable suggestion; `targetText` anchors the comment near matching text.

### Approve

```
officecli(action="approve", filePath="...", commentId="c1")
```

Applies the suggestion's `suggestedText` into the draft and removes the comment. `approve` only accepts comments that carry `suggestedText`; approving a plain note is an error.

### Track changes (DOCX only)

```
officecli(action="track-insert", filePath="...", commentId="c1", author="AI Agent", content="inserted text", paragraph=0, offset=5)
officecli(action="track-delete", filePath="...", commentId="c1", author="AI Agent", content="deleted text", paragraph=0, offset=5)
```

Returns an error for XLSX/PPTX (no track-changes representation in those formats) — use `comment` with `suggestedText` there.

### List / review

```
officecli(action="list-comments", filePath="...")   # → { count, comments: [...] }
officecli(action="review", filePath="...")          # → comments + track changes (DOCX)
```

Comments survive Office round-trips, so a user can review/resolve them in Word/Excel/PowerPoint.

## Lock states

- **acquired** — a session is editing the draft
- **in-review** — a user is reviewing in Office
- **stale** — lock timeout exceeded; eligible for `force-release`

## Limitations

- Suggestions and track changes live in the draft until `accept`.
- `approve` applies text substitution at the anchor point; it does not reflow surrounding content.