What happened
add-epic --notes "<rationale>" exits 0 and reports success, but no notes field is ever written to .conductor/state.json. The epic schema has no such field:
$ jq -r '.epics[0] | keys[]' .conductor/state.json
id lane links planPath priority reconcileNeeded role status title
I created 6 epics this session passing substantial --notes (deferred-design rationale, hard constraints, triggers to revisit). All of it was accepted and dropped. I only caught it because I verified the write afterward:
$ jq -r '.epics[] | select(.id=="pattern-confidence-scoring") | .notes | length'
0
An unknown flag on update-epic is rejected loudly, which is the right behavior:
$ node conductor.mjs update-epic <id> --plan foo.md
conductor: update-epic: unknown flag(s) --plan (known: --external-id, --external-url, ...)
So add-epic accepting --notes and discarding it is inconsistent with update-epic's own strictness.
Why it matters
The failure is silent and the data is unrecoverable. For a later/planned epic — registered specifically so a future session remembers why — the rationale is the entire payload. An epic id alone doesn't survive the loss of the conversation that produced it, which is exactly what registering it was meant to prevent.
It also defeats a documented workflow. This repo's CLAUDE.md instructs recording backlog with rationale via /pm:epic add … --status later.
Repro
node conductor.mjs add-epic --id probe --title "Probe" --lane openspec --priority P3 --status later --notes "this text vanishes"
jq -r '.epics[] | select(.id=="probe") | .notes // "NO NOTES FIELD"' .conductor/state.json
# -> NO NOTES FIELD (exit was 0, output said "added epic 'probe'")
Suggested fix, in order of preference
- Support it — add a
notes field to the epic schema, settable on add-epic and update-epic, rendered in PROJECT.md for planned/later epics (where the rationale matters most).
- Or reject it — make
add-epic strict about unknown flags exactly as update-epic already is. Loudly failing is far better than silently dropping.
- Or a supported
planPath setter — planPath exists in the schema but no CLI verb sets it, so pointing an epic at a rationale doc isn't possible either. update-epic --plan <path> would cover this cleanly.
Related gap: PROJECT.md renders only the id for later epics, so even a descriptive title doesn't surface — there's currently no supported way to make an epic's reasoning visible to a future session.
Workaround used
Wrote the rationale to a versioned doc (docs/deferred/pattern-confidence-scoring.md) and cross-referenced it from CLAUDE.md, the docs index, and the two docs that would lead someone to it. Durable, but it means the conductor entry is a bare stub whose context lives entirely outside it.
Engine 0.25.0.
What happened
add-epic --notes "<rationale>"exits 0 and reports success, but nonotesfield is ever written to.conductor/state.json. The epic schema has no such field:I created 6 epics this session passing substantial
--notes(deferred-design rationale, hard constraints, triggers to revisit). All of it was accepted and dropped. I only caught it because I verified the write afterward:An unknown flag on
update-epicis rejected loudly, which is the right behavior:So
add-epicaccepting--notesand discarding it is inconsistent withupdate-epic's own strictness.Why it matters
The failure is silent and the data is unrecoverable. For a
later/plannedepic — registered specifically so a future session remembers why — the rationale is the entire payload. An epic id alone doesn't survive the loss of the conversation that produced it, which is exactly what registering it was meant to prevent.It also defeats a documented workflow. This repo's CLAUDE.md instructs recording backlog with rationale via
/pm:epic add … --status later.Repro
Suggested fix, in order of preference
notesfield to the epic schema, settable onadd-epicandupdate-epic, rendered inPROJECT.mdforplanned/laterepics (where the rationale matters most).add-epicstrict about unknown flags exactly asupdate-epicalready is. Loudly failing is far better than silently dropping.planPathsetter —planPathexists in the schema but no CLI verb sets it, so pointing an epic at a rationale doc isn't possible either.update-epic --plan <path>would cover this cleanly.Related gap:
PROJECT.mdrenders only the id forlaterepics, so even a descriptivetitledoesn't surface — there's currently no supported way to make an epic's reasoning visible to a future session.Workaround used
Wrote the rationale to a versioned doc (
docs/deferred/pattern-confidence-scoring.md) and cross-referenced it from CLAUDE.md, the docs index, and the two docs that would lead someone to it. Durable, but it means the conductor entry is a bare stub whose context lives entirely outside it.Engine 0.25.0.