docs/drafthorse/framework/conventions.md is mid-rewrite. Conventions go from 13 bullets to 7 by folding related entries into super-conventions. This issue closes that rewrite. It blocks the wider spec-alignment sweep.
Settled so far
New or rewritten:
- Building is difficult, so execution is easy — DraftHorse as a builder's spec.
- Stepping stones — the step mechanism as one convention, absorbing Steps are universal and Conditions carry routing, with the open-mechanism consequences (loop back, span, dormant, support, handover) as sub-bullets.
- The error step — two modes: Hard bail and clean up (unrecoverable → clean up the run's mess, end the skill, user repairs across following turns then re-runs or finds the skill no longer needed) and Claim the remainder (recoverable, named in advance → the error step resolves it and the run completes). Absorbs the old claims the remainder.
- References all data, no work — absorbs inline vs external, naming not explaining, cite at the moment of use.
Untouched: Single source of truth, Sharp Prose, Dynamic Improvement.
Removed, homed elsewhere: A handover fits its parent step, standalone Naming not Explaining, standalone Cite references and Inline vs external.
Remaining work
- Write the prose for the new convention drafted in shorthand at
conventions.md:14-21 — a document must be executable by an agent with no DraftHorse knowledge, leaning on existing markdown notation, consistent shape, separation of concerns, and self-documenting structure.
- Add the sub-point drafted in shorthand at
conventions.md:66 to References all data, no work — citations are always markdown links or harness tools.
- Migrate three entries out of conventions and into the spec as instructions, each needing a verified home before deletion:
- Conditions are checkable and exhaustive →
steps.md (appears already covered around :77).
- Gates are compound →
steps.md (appears already covered around :112).
- Skill Description is invocation-shaped →
surfaces.md (unverified).
- Confirm the handover constraint survives the removal of A handover fits its parent step. The old bullet carried "the finished condition reads the state the handover leaves behind, no handed-back outcome"; Stepping stones states this more weakly, so
handover.md must be its home.
- Resolve the duplication between the Stepping stones sub-bullets and the Step Usage Patterns catalogue in
steps.md:141-155. One fact, one home.
- Delete the archived
<!-- +DRAFT: Preserve --> and <!-- Remove --> blocks once their content is confirmed landed.
Also in flight on steps.md
docs/drafthorse/framework/steps.md carries a proposed replacement for the whole ### Dispositions section, left inline as an HTML comment. It aligns the dispositions with the two-mode error step, drops the "default posture for destructive errors" mis-scoping, states "raise an issue" once instead of three times, and bars working steps from carrying dispositions of their own. Review and apply or discard as part of this work.
steps.md:125 also has an unfinished edit — unclosed parenthesis and a stray quote mark.
docs/drafthorse/framework/conventions.mdis mid-rewrite. Conventions go from 13 bullets to 7 by folding related entries into super-conventions. This issue closes that rewrite. It blocks the wider spec-alignment sweep.Settled so far
New or rewritten:
Untouched: Single source of truth, Sharp Prose, Dynamic Improvement.
Removed, homed elsewhere: A handover fits its parent step, standalone Naming not Explaining, standalone Cite references and Inline vs external.
Remaining work
conventions.md:14-21— a document must be executable by an agent with no DraftHorse knowledge, leaning on existing markdown notation, consistent shape, separation of concerns, and self-documenting structure.conventions.md:66to References all data, no work — citations are always markdown links or harness tools.steps.md(appears already covered around:77).steps.md(appears already covered around:112).surfaces.md(unverified).handover.mdmust be its home.steps.md:141-155. One fact, one home.<!-- +DRAFT: Preserve -->and<!-- Remove -->blocks once their content is confirmed landed.Also in flight on steps.md
docs/drafthorse/framework/steps.mdcarries a proposed replacement for the whole### Dispositionssection, left inline as an HTML comment. It aligns the dispositions with the two-mode error step, drops the "default posture for destructive errors" mis-scoping, states "raise an issue" once instead of three times, and bars working steps from carrying dispositions of their own. Review and apply or discard as part of this work.steps.md:125also has an unfinished edit — unclosed parenthesis and a stray quote mark.