docs(kyberforge): body-discipline.md and the ADR's cited dispatch exemplar cannot both be satisfied #109
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Defame1297/holocron#109
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
references/body-discipline.mdrequires every reference file to be wired with the literal conditional formIf <condition>, read `references/<file>.md`and calls a generic pointer a Vale error.plugins/kyberforge/.apm/skills/apm-workflow/SKILL.md:33-41— which ADR-0020 names by name as the dispatch-pattern exemplar, and whichskill-author/references/contract.md:123cites for its 421-word body dispatching to ~3,000 words of references — uses a bare dispatch table plus one generic line: "Read only the reference file matching the requested action."An author cannot satisfy both. Following the rule means stating every condition twice — once as a table row, once as a literal conditional — in a body whose whole purpose is to be short.
How it surfaced
gitea-workflow's retrofit (#99) hit this directly. Its 227-word body ended up carrying both forms:SKILL.md:31-35— a dispatch table mapping three invocation shapes to three reference filesSKILL.md:37-41— the same three mappings again as literal conditionalsIt chose the redundant superset because the gate is hot and a Vale error blocks. That is the rational choice under the current rules, and it will recur in every retrofit — the contradiction reliably produces duplication in exactly the files the contract is trying to keep lean.
Options
apm-workflowdoes and what the ADR points at.Recommend 1: make the literal-conditional requirement apply only where there is no dispatch table, and say so in
body-discipline.md. That aligns the rule with the exemplar the ADR already endorses, and removes a duplication the ADR would otherwise flag as capability restatement.Files
plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md— the ruleplugins/kyberforge/.apm/skills/apm-workflow/SKILL.md:33-41— the exemplar that contradicts itplugins/kyberforge/.apm/skills/*/assets/vale/styles/Kyberforge/Note
apm-workflowis itself still a #99 retrofit target (description 817 chars). Resolving this first would avoid that retrofit having to guess which convention to follow — and whichever way it goes, the exemplar and the rule should agree afterwards.Related
Found during the
giteawave of #99. See also #107 (resolver under-reports boundary coverage).Resolved with option 1. Two corrections to the issue as filed, both worth recording because they change the size of the fix.
There is no Vale conflict
The issue says the rule "calls a generic pointer a Vale error" and lists a Vale rule under
Kyberforge/as one of the three files to change. Checked: the rule isPaddingPhrase.yml, and it is far narrower than the prose suggests.That matches "see references/ for more info" and nothing else. It does not match
apm-workflow's closing line, "Read only the reference file matching the requested action." The linter and the exemplar never disagreed.The contradiction was entirely in the prose rule at
body-discipline.md:31-34— "the literal conditional form, never a generic pointer" — which an LLM auditor reads and applies literally, exactly asgitea-workflow's retrofit did. So the fix is one file, not three, and no Vale rule changes.What changed
plugins/kyberforge/.apm/skills/skill-audit/references/body-discipline.md:references/rule now carries an explicit exemption: a dispatch table satisfies the wiring requirement on its own. A row already pairs a condition with a target, which is what the literal form encodes. Where a body dispatches, audit the table for condition/target completeness and stop. The literal form is what a body needs when it loads a reference without a table — a mid-procedure deepening, an escape hatch, an error path.apm-workflow's actual wiring (three-column table closed by one line) and says in terms: that is the endorsed shape, do not flag it.Collateral fixed
gitea-workflowcarried the redundant superset this issue predicted — a three-row dispatch table atSKILL.md:29-33and the same three mappings restated as literal conditionals at:35-39. The three restatements are gone, replaced by the one-lineapm-workflowform. Body drops from 227 to 148 words.skill-size-checkexits 0, Vale prefilter passes.On the sequencing note
The issue observes that
apm-workflowis itself a #99 retrofit target and that resolving this first spares its retrofit a guess. That still holds — it is wave 4, and this is now settled before it starts, which is why this was done mid-wave-3 rather than after. The change is strictly relaxing: anything written against the old, stricter rule still passes the new one, so no in-flight work was invalidated.