Skip to content

capability publish's auto-generated PR body always fails registry's spec-alignment gate #858

Description

@enricopiovesan

What's wrong

capability_publish_pr_body() in crates/traverse-cli/src/main.rs hardcodes the PR body's ## Governing Specs section to two traverse-repo spec IDs:

fn capability_publish_pr_body(plan: &CapabilityPublishPlan) -> String {
    format!(
        "## Summary\n\n...\n\n## Governing Specs\n\n- `056-capability-publish`\n- `054-public-scope-registry-ref`\n\n...",
        ...
    )
}

But traverse-framework/registry's own spec-alignment CI gate (scripts/ci/spec_alignment_check.sh) checks the PR body against registry-repo specs whose governs list matches the changed file path -- for any new capabilities/<namespace>/... path, that's 001-registry-foundation, 005-yank-deprecation, 006-public-scope-and-identity, 007-artifact-hosting (verified directly against specs/governance/approved-specs.json). None of the four match either of the two hardcoded IDs, and the section header itself is ## Governing Spec (singular) in registry's convention, not ## Governing Specs (plural) as the CLI writes.

Reproduced twice, independently, this session (traverse-framework/registry#89 and #90): every real capability publish PR opens already-failing on spec-alignment, with zero discoverable connection between the CLI's output and the actual required fix -- an author has to separately discover registry's spec-alignment script, manually rewrite the PR body, and then discover that GitHub Actions won't re-evaluate a pull_request-triggered check against an edited body without a fresh synchronize event (gh pr edit alone doesn't retrigger it; even gh run rerun replays the stale cached event payload -- only an actual new commit works).

Definition of Done

  • capability_publish_pr_body() no longer hardcodes traverse-repo spec IDs as if they satisfy every possible target registry's own governance gate.
  • Some real mechanism for the PR body to declare specs that actually satisfy the target registry's spec-alignment requirements -- options worth considering (pick one, don't guess): (a) a --governing-spec <id> repeatable flag the caller supplies, (b) reading a spec_ref already present in the contract's own provenance field if set, (c) a documented manual-edit-required step in whatever skill/doc walks someone through capability publish (already added to traverse-capability-author's references/registry.md as an interim disclosure, but the CLI itself producing something structurally wrong for every registry it might target is the real bug).
  • Whichever fix lands, verify it against a real registry with a real spec-alignment gate (not just cargo test) -- this bug's whole nature is that it looks fine locally and only surfaces once CI runs on the actual target repo.

Also worth fixing while touching this

Header casing: registry's convention is ## Governing Spec (singular); the CLI emits ## Governing Specs (plural). Minor on its own, but worth aligning if the body-generation logic is being touched anyway.

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent:claudeClaimed by Claude CodebugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions