Surfaced during #1011 (framework-file delivery fix). Split out per that issue's scope discipline: #1011 is plumbing (how framework files reach the builder); this issue is about the bugfix protocol document itself.
Two related gaps in the bugfix protocol doc
1. Absent from the skeleton
codev-skeleton/protocols/bugfix/ ships no protocol.md (only protocol.json, builder-prompt.md, prompts/). Every other protocol ships its protocol.md in the skeleton. Meanwhile codev/protocols/bugfix/protocol.md exists in this repo (548 lines, tracked) but was never copied into the skeleton.
Consequence: bugfix/builder-prompt.md:28 references codev/protocols/bugfix/protocol.md, which resolves to nothing in a fresh install. #1011 handles that dead pointer by dropping it (its Layer 2 sweep) — safe, because the builder-relevant guidance (300-LOC scope, escalation criteria, mandatory regression test, PR-body structure) already lives in bugfix's phase prompts (investigate.md / fix.md / pr.md), delivered correctly via porch. So this is not a builder-blocking bug — it's doc consistency.
2. Partly stale relative to porch orchestration
codev/protocols/bugfix/protocol.md describes a pre-porch manual architect-builder flow that no longer matches how bugfix runs under porch:
- Manual merge trigger (
afx send architect "Merge it" → builder runs gh pr merge) instead of a porch gate approval.
- A manual architect CMAP /
--type integration review step (porch's verify block handles consultation now).
- A "BUGFIX issues are NOT tracked in
codev/projectlist.md" section — projectlist is deprecated; GitHub Issues are the source of truth.
- Internal inconsistency: branch naming shown as both
bugfix/<N>-description and builder/bugfix-<N>-<slug>.
Decision this issue needs
Pick one:
- (a) De-stale and ship: bring
bugfix/protocol.md in line with porch orchestration and copy it into the skeleton, uniform with the other protocols.
- (b) Intentionally doc-light: decide bugfix is builder-prompt + phase-prompt only (no
protocol.md), and trim/remove the codev/ copy so the two trees agree.
Out of scope
Suggested protocol
Likely MAINTAIN (doc hygiene) once direction (a)/(b) is chosen, or a quick design call first.
Related: #1011.
Scope expansion (added per review of #1011)
3. experiment/protocol.md commits a partial copy of its notes template
experiment/protocol.md has a ## notes.md Template section that quotes part of codev-skeleton/protocols/experiment/templates/notes.md inline (via a relative templates/notes.md reference, "See templates/notes.md for the full template. Key sections:"). This is the same staleness class as the bugfix issue: a committed partial copy of a framework template that will drift from the canonical file.
It is pre-existing and was left untouched by #1011 (which scoped to the absolute-path references the architect enumerated). #1011 introduced the fix pattern for this class: a fresh-at-delivery include placeholder ({{> protocols/<name>/templates/<file>}}) resolved by the spawn layer, so the canonical template stays single-source.
Action: replace the committed partial copy in experiment/protocol.md's ## notes.md Template section with the {{> protocols/experiment/templates/notes.md}} include (or remove the partial copy and rely on the ## Template: notes.md include #1011 already added), so experiment has no committed template duplicate.
Audit other protocol docs for the same relative-path partial-copy pattern while here.
Two related gaps in the
bugfixprotocol doc1. Absent from the skeleton
codev-skeleton/protocols/bugfix/ships noprotocol.md(onlyprotocol.json,builder-prompt.md,prompts/). Every other protocol ships itsprotocol.mdin the skeleton. Meanwhilecodev/protocols/bugfix/protocol.mdexists in this repo (548 lines, tracked) but was never copied into the skeleton.Consequence:
bugfix/builder-prompt.md:28referencescodev/protocols/bugfix/protocol.md, which resolves to nothing in a fresh install. #1011 handles that dead pointer by dropping it (its Layer 2 sweep) — safe, because the builder-relevant guidance (300-LOC scope, escalation criteria, mandatory regression test, PR-body structure) already lives in bugfix's phase prompts (investigate.md/fix.md/pr.md), delivered correctly via porch. So this is not a builder-blocking bug — it's doc consistency.2. Partly stale relative to porch orchestration
codev/protocols/bugfix/protocol.mddescribes a pre-porch manual architect-builder flow that no longer matches how bugfix runs under porch:afx send architect "Merge it"→ builder runsgh pr merge) instead of a porch gate approval.--type integrationreview step (porch's verify block handles consultation now).codev/projectlist.md" section — projectlist is deprecated; GitHub Issues are the source of truth.bugfix/<N>-descriptionandbuilder/bugfix-<N>-<slug>.Decision this issue needs
Pick one:
bugfix/protocol.mdin line with porch orchestration and copy it into the skeleton, uniform with the other protocols.protocol.md), and trim/remove thecodev/copy so the two trees agree.Out of scope
Suggested protocol
Likely MAINTAIN (doc hygiene) once direction (a)/(b) is chosen, or a quick design call first.
Related: #1011.
Scope expansion (added per review of #1011)
3.
experiment/protocol.mdcommits a partial copy of its notes templateexperiment/protocol.mdhas a## notes.md Templatesection that quotes part ofcodev-skeleton/protocols/experiment/templates/notes.mdinline (via a relativetemplates/notes.mdreference, "Seetemplates/notes.mdfor the full template. Key sections:"). This is the same staleness class as the bugfix issue: a committed partial copy of a framework template that will drift from the canonical file.It is pre-existing and was left untouched by #1011 (which scoped to the absolute-path references the architect enumerated). #1011 introduced the fix pattern for this class: a fresh-at-delivery include placeholder (
{{> protocols/<name>/templates/<file>}}) resolved by the spawn layer, so the canonical template stays single-source.Action: replace the committed partial copy in
experiment/protocol.md's## notes.md Templatesection with the{{> protocols/experiment/templates/notes.md}}include (or remove the partial copy and rely on the## Template: notes.mdinclude #1011 already added), so experiment has no committed template duplicate.Audit other protocol docs for the same relative-path partial-copy pattern while here.