# Progress Logging Protocol

## Overview

All `erp-kit-app-*` skills log to an append-only audit trail at `.erp-kit/progress.jsonl`. This records conversations, decisions, and agent activity across sessions.

The log is NOT the source of truth for progress — the produced docs and code are. The log answers "what happened and why."

## Before First Log

Run this once per session to load the schema into context:

```bash
npx erp-kit app progress schema
```

Use the output to construct valid payloads. Do not guess the shape.

## CLI Commands

### Log an event

```bash
npx erp-kit app progress log --json '<ProgressInput JSON>'
```

### Validate without writing

```bash
npx erp-kit app progress log --dry-run --json '<ProgressInput JSON>'
```

## When to Log

Log at natural checkpoints — moments where the skill is already pausing to take action. Bundle all conversation since the last checkpoint into the `conversation` array.

| Checkpoint | Event type | When |
|---|---|---|
| Skill invocation | `step.start` | First thing after skill is invoked |
| User decision | `decision` | User approves, corrects, or chooses |
| Subagent launch | `agent.dispatch` | Before dispatching a subagent |
| Subagent return | `agent.result` | After subagent completes |
| File write | `artifact.create` | After creating/modifying/deleting a file |
| Validation | `validation` | After running `erp-kit app check`, build, lint, etc. |
| Skill completion | `step.complete` | Last thing before skill finishes |
| Failure | `error` | When something fails |
| Free-form | `note` | Anything else (e.g., session pause) |

## Entry Format

Every entry requires:

- `v` — Schema version, always `1`
- `sessionId` — Your AI session ID
- `prompt` — The user's original prompt (the request that triggered this skill)
- `event` — Event type from the table above
- `data` — Event-specific payload (see schema)
- `conversation` — Array of `{role, message}` since last checkpoint (optional, defaults to `[]`)

The CLI auto-adds `timestamp` and `git` context.

## Example

```bash
npx erp-kit app progress log --json '{
  "v": 1,
  "sessionId": "claude-abc123",
  "prompt": "Create screens for manufacturing flows",
  "event": "decision",
  "conversation": [
    {"role": "agent", "message": "Flat list or collapsible tree for BOM?"},
    {"role": "user", "message": "Collapsible tree"}
  ],
  "data": {
    "question": "BOM list view style",
    "choice": "Collapsible tree",
    "alternatives": ["Flat list with indent"],
    "rationale": "Better UX for multi-level BOMs"
  }
}'
```