id: 943e9b22-141a-4cd2-8c55-5eda2ba0b398 title: 'skill has two sources: --skill const vs skill/skill.md diverged; help/contract openings confusable' state: closed labels:
- dogfood
- pri assignees: [] milestone: null created: 2026-09-08T05:04:38Z updated: 2026-09-08T05:58:05Z
INCIDENT: an agent burned ~12 tool calls convinced f0rge --skill printed generic help. Current binary is fine (--skill=549B/10ln contract, root=150B/5ln help — distinct, verified md5==target/release). But digging found a REAL design smell: two documents both present as "the skill" and they have drifted:
- cmd/skill.rs SKILL_TEXT (549B): id/number/frontmatter/ci-verdict/never-delete/usage/json
- skill/skill.md (588B): tree mapping (issue<->issues/...), "never parse prose; always use --json", "empty is [] or {}; errors: 1 line + code" — none in the const; const rules also absent from .md No test pins them together. Root help "f0rge: local forge" and contract "f0rge v1: local gh-like forge" open almost identically — laterally confusable by models. FIX (boring, budgets hold, no new deps): ONE source of truth for the skill text — either derive skill/skill.md from SKILL_TEXT or vice versa, and add a golden test asserting they are identical (after frontmatter). Make the two openings non-confusable: root help stays a command map; contract opens with a hard self-identifier line (e.g. "f0rge v1: CONTRACT (not help)") asserting its purpose. Cross-refs #19 (one source of truth for -h) — same family; coordinate. Acceptance: skill.md == SKILL_TEXT body (test), openings mutually exclusive, budgets byte-counted (root <=300B/12ln, skill <=900B/30ln, -h <=250B/8ln).