history-log

A continuous, append-only diary of state-transition events, complementing the periodic hand-curated snapshots (HANDOFF-NNN.md) written by the handoff skill. This rule applies cross-cuttingly to every skill that produces a state-transition event; it does not require editing any of those skill files.

Where entries go

.handoff/HISTORY.md, one line per event, in this exact format:

YYYY-MM-DD HH:MM  <event-tag>  <one-line outcome>

Example:

2026-07-05 14:31  openspec-propose       change "add-history-log" created (2 req, 4 tasks)
2026-07-05 14:42  openspec-apply-change  task 1.2 done: rules/history-log.md created
2026-07-05 14:55  spec-verify            PASSED
2026-07-05 15:10  spec-loop              iter 3/25 (task mode) → verify PASSED, task 2.1 done
2026-07-05 15:14  spec-loop              iter 4/25 (fix mode) → verify FAILED (check-target-ownership)
2026-07-05 15:40  openspec-archive-change change "add-history-log" archived
2026-07-05 16:00  handoff-save           HANDOFF-007.md created
2026-07-05 16:02  plan-mode              entry E02 approved → in-progress

The timestamp MUST come from an actual clock read (e.g. date "+%Y-%m-%d %H:%M" in a shell tool call). Never guess, estimate, or invent the timestamp — this is the same anti-invention discipline rules/prompt-loop.md already requires elsewhere.

When to append — the enumerated event set

Append exactly one line for each of these state-transition events, and no others:

• openspec-propose creates a new change
• openspec-apply-change marks a task done in tasks.md
• spec-verify completes a run (outcome PASSED or FAILED, naming the failing check when it fails)
• spec-loop completes one iteration, task or fix mode, with its verify outcome (bounded by that run's MAX_ITERATIONS — one line per iteration, never more)
• openspec-archive-change archives a change
• handoff Workflow B (SAVE) creates a new HANDOFF-NNN.md
• plan-mode records a plan entry changing state, written entry <id> <old> → <new> (for example entry E02 approved → in-progress). Rewording an entry or drafting a new one is not a state transition and gets no line.

This set is closed. Adding another event requires modifying openspec/specs/history-log/spec.md, not editing this rule on its own.

What does NOT get a line

Do not append a line per tool call (Read, Grep, Bash, Edit, ...), and do not append a line for any event outside the enumerated set above. A history that logs every tool call is noise nobody will read; the value of this file is that every line is a state transition worth knowing about.

No edits required to the triggering skills

This rule is the only place this behavior lives. spec-verify, openspec-apply-change, spec-loop, openspec-archive-change, and openspec-propose do not need their own SKILL.md files modified to produce history entries — an agent running any of those skills follows this rule directly, the same way generated-file-header.md applies to any skill writing a targets: file without editing that skill's instructions.

Lazy, backward-compatible creation

Before appending, check whether .handoff/HISTORY.md exists.

• If .handoff/ exists but HISTORY.md does not (true for any project that ran handoff init before this rule existed), create an empty .handoff/HISTORY.md first, then append the line. This needs no manual migration step from the user.
• If .handoff/ does not exist at all, do nothing — do not create .handoff/ or HISTORY.md as a side effect of this rule. This rule never bootstraps handoff itself; only handoff Workflow A does that.