Issues are files that grow
An issue starts almost empty — a title and a few lines of context. As it walks the workflow, each transition appends a new section to its body. By the time the issue reaches done, the file is a self-contained record of every decision and verification that produced the change.
This is the opposite of the ticket-system model where an issue is a static description and the work happens elsewhere — in chat, in PR comments, in a wiki, in some tracker's activity log. Here the file is the activity log. Design checklists, implementation notes, the test plan, the docs links, the shipping refs, the inline review comments — they all accrete into the same markdown file, in the same git repo, under the same diff history.
The engine drives this directly: append_section side-effects on transitions scaffold the next stage's structure with empty checkboxes. The agent fills the boxes and the prose. Validators on the next transition check that the boxes were ticked. By the time you read the file at done, it tells you what the change was, why, what was considered, what was tested, and how it shipped.
Inline comments live at the bottom of each file in an HTML comment block — invisible to grep, cat, and other markdown renderers, but addressable in the web UI per-block. Per-issue structured data (code-review findings, triage rows) lives in a sidecar JSON next to the issue file. Custom frontmatter keys render as a sidebar in the detail view.
issues/Combat/42-fix-heat-overflow.md
# --- frontmatter ---create
---
title: "Fix heat overflow on burst weapons"
status: "done"
system: "Combat"
version: "0.4"
priority: "high"
labels: [bug, combat]
pr: "https://github.com/me/proj/pull/812"
---
# --- body intro ---create
Burst weapons accumulate heat across modules and overflow
the i16 register at sustained fire. Reproducible with the
"long burn" scenario in tests.
# --- appended on idea → in design ---idea → in design
## Idea
- [x] Description with enough context for someone unfamiliar
- [x] Edge cases identified (overflow, underflow, multi-module)
- [x] Scope clear (what is NOT included)
## Design
- [x] Switch heat accumulator to i32, gate at MAX_HEAT
- [x] Per-module heat decay rate
- [x] Test strategy: long-burn fixture + property test
## Acceptance Criteria
- [x] No overflow under 10x sustained fire
- [x] Existing scenarios pass unchanged
# --- appended on backlog → in progress ---backlog → in progress
## Implementation
- [x] Wire i32 accumulator in combat/heat.go
- [x] Migrate save format (backwards-compatible)
- [x] Cover edge cases from the Design section
## Test Plan
- [x] Unit: heat_test.go — long burn, edge cases
- [x] Property test: random weapon mixes, 10k iterations
- [x] Manual: smoke through tutorial mission
# --- appended on in progress → testing ---in progress → testing
## Testing
- [x] All automated tests green on CI
- [x] No regression in existing fixtures
- [x] tests: 10k-iteration property run completed clean
# --- appended on human-testing → documentation ---human-testing → docs
## Documentation
- [x] Updated docs/Combat/heat-model.md
- [x] Added migration note to CHANGELOG
- [x] docs: heat-model section reviewed
# --- appended on documentation → shipping ---docs → shipping
## Shipping
- [x] Committed with ref #42
- [x] Pushed; PR #812 merged
- [x] Tagged v0.4.1, release notes polished
# --- inline comments accrete throughout ---
<!-- issue-viewer-comments
{"id":1,"block":2,"date":"2026-04-12","text":"check legacy save format","status":"done"}
{"id":2,"block":4,"date":"2026-04-14","text":"property test seed?","status":"done"}
-->
