sync.md: `gh issue create --json` regression of #653 + validate.sh/sync.md disagree on github-mapping.md frontmatter

[zhudongming]

Summary

Two issues found while running /pm:epic-sync end-to-end on a fresh install:

1. Bug A — gh issue create --json regression (previously fixed in Wrong usage of gh issue create #653, still present in sync.md)
2. Bug B (new) — validate.sh and sync.md disagree on whether github-mapping.md should have frontmatter

Cross-reference: the original gh sub-issue create --body-file / --json flag mismatch is already tracked in #1022 (and #1022 proposes the cleanest fix: keep gh issue create + use gh sub-issue add to link). I'm leaving that one out of this report to avoid duplication.

Environment

• gh 2.92.0 (2026-04-28, official cli.github.com apt repo)
• gh-sub-issue v0.5.1 (auto-installed by init.sh)
• ccpm main (cloned 2026-05-06)
• Ubuntu 22.04

---

Bug A — gh issue create --json flag does not exist (regression of #653)

Location: references/sync.md lines ~38-44 (epic creation) and ~61-66 (task creation)

The documented command is:

epic_number=$(gh issue create \
  --repo "$REPO" \
  --title "Epic: <name>" \
  --body-file /tmp/epic-body.md \
  --label "epic,epic:<name>,feature" \
  --json number -q .number)

gh issue create does not accept --json (verified via gh issue create --help on 2.92.0). Running it produces:

unknown flag: --json

The issue is not created.

This was originally reported and closed in #653 but sync.md still has --json number -q .number on the create call.

Suggested fix: capture stdout (which is the issue URL) and grep the number:

epic_url=$(gh issue create \
  --repo "$REPO" \
  --title "Epic: <name>" \
  --body-file /tmp/epic-body.md \
  --label "epic,epic:<name>,feature")
epic_number=$(echo "$epic_url" | grep -oE '[0-9]+$')

(Same pattern for the per-task gh issue create call.)

---

Bug B — validate.sh flags github-mapping.md for missing frontmatter, but sync.md specifies it without frontmatter

Location: references/scripts/validate.sh (frontmatter validator) vs. references/sync.md lines ~98-104

sync.md Step 6 instructs the agent to write:

# GitHub Issue Mapping
Epic: #<N> - https://github.com/<repo>/issues/<N>
Tasks:
- #<N>: <title> - https://github.com/<repo>/issues/<N>
Synced: <datetime>

— no frontmatter. But after a successful sync, validate.sh then reports:

⚠️ Missing frontmatter: github-mapping.md
📊 Validation Summary:
  Errors: 0
  Warnings: 0
  Invalid files: 1

The two specs are inconsistent. Suggested fix (one of):

• (a) Exclude github-mapping.md (and any other ccpm-system-generated file) from the frontmatter check in validate.sh, OR
• (b) Update sync.md Step 6 to include a minimal frontmatter (e.g. kind: github-mapping + synced: <datetime>) and have validate.sh accept it.

(a) is less work and feels more correct — github-mapping.md is a system-generated index, not user content.

---

Reproducer

After init.sh and creating a PRD/epic/3 tasks following conventions.md:

# Bug A reproduction
sed '1,/^---$/d; 1,/^---$/d' .claude/epics/<name>/epic.md > /tmp/epic-body.md
gh issue create --repo "$REPO" --title "Epic: x" --body-file /tmp/epic-body.md \
  --label "epic" --json number -q .number
# → unknown flag: --json

# Bug B reproduction
# Create github-mapping.md per sync.md Step 6 (no frontmatter), then:
bash references/scripts/validate.sh
# → ⚠️ Missing frontmatter: github-mapping.md

Notes

I worked around all bugs to get an end-to-end sync working in a sandbox repo. The parallel: true / depends_on: [...] / conflicts_with: [...] schema and the parallel-stream design are excellent — the bugs above are the only thing preventing the documented /pm:epic-sync flow from running unattended on a fresh install.

Happy to send a PR for either of the two if you'd accept it.