GitHub Issue Dependencies

This is a mechanical relationship helper, not a semantic lifecycle owner and not a standalone Human Handoff.

Authorized callers:

• $to-specs — native Spec dependency mutations after it has established semantic ownership and cycle safety. This includes same-Wayfinder-lineage Spec prerequisites and every Spec prerequisite where either endpoint is intentionally Independent;
• $to-tickets — native direct-decomposition hierarchy plus dependency edges it already owns;
• $project-delivery-management — native blocked by / blocking mutations only after it has established cross-Wayfinder semantic ownership, lowest-accurate placement, and cycle safety. Both dependency endpoints must be Wayfinder-managed.

Do not let this helper decide whether a dependency is semantically required, where it belongs, which lifecycle owns it, or whether a Spec is Wayfinder-managed versus Independent.

Native gh flags

As of gh CLI v2.94.0 (June 2026), gh issue create supports:

• --parent <number> — creates the new issue as a native sub-issue of <number>;
• --blocked-by <numbers> — marks the new issue as blocked by the given issue number(s)/URL(s), comma-separated for multiple;
• --blocking <numbers> — marks the new issue as blocking the given issue number(s)/URL(s);
• --type <name> — sets the issue type, if your tracker uses GitHub's issue types.

All four flags can be combined in one call.

$to-tickets hierarchy invariant

Only $to-tickets may use this helper to establish direct-decomposition parentage during ticket publication/reconciliation.

Resolve <native_parent_issue_number> from the artifact directly decomposed by $to-tickets:

• ordinary Spec ticketing → the Spec issue number;
• Spec Review remediation → the Spec Review issue number.

Do not substitute an upstream provenance issue for the direct decomposition parent. In particular, a remediation ticket's originating Parent Spec remains lifecycle/branch provenance and is not its native GitHub parent.

Example:

gh issue create \
  --title "..." \
  --body "..." \
  --parent <native_parent_issue_number> \
  --blocked-by <blocker_1_number>,<blocker_2_number> \
  --label ready-for-agent

$to-specs and $project-delivery-management must not use --parent, --remove-parent, --add-sub-issue, or --remove-sub-issue when reconciling dependency edges.

Before relying on this

Confirm the installed gh version supports the required relationship flags:

gh --version   # needs >= 2.94.0

If an authorized caller needs a native operation the installed CLI cannot perform, return the tool/version blocker to that caller. Do not silently replace native relationships with text or raw GraphQL from this helper unless the owning lifecycle explicitly defines that fallback.

Deterministic execution rule

The commands and flags in this helper are the prescribed mechanics for authorized native issue relationships. Use them directly.

Do not browse GitHub documentation, search the web, probe REST or GraphQL alternatives, try raw gh api relationship mutations, or experiment with alternate command forms while executing a lifecycle transition.

If the required gh version or prescribed flag is unavailable, unsupported, or fails because the local CLI/API contract has drifted, return that exact blocker to the lifecycle owner. Do not discover or invent a fallback during the lifecycle run.

Editing relationships on an already-published issue

Use gh issue edit directly for existing issue relationships.

Parent/sub-issue operations — $to-tickets only

Set or change an issue's native parent:

gh issue edit <issue_number> --parent <native_parent_issue_number>

Remove its native parent:

gh issue edit <issue_number> --remove-parent

When operating from the parent side:

gh issue edit <parent_issue_number> --add-sub-issue <child_issue_number>
gh issue edit <parent_issue_number> --remove-sub-issue <child_issue_number>

Dependency operations — authorized semantic owner required

Add or remove dependency relationships:

gh issue edit <issue_number> --add-blocked-by <blocker_numbers_or_urls>
gh issue edit <issue_number> --remove-blocked-by <blocker_numbers_or_urls>
gh issue edit <issue_number> --add-blocking <blocked_issue_numbers_or_urls>
gh issue edit <issue_number> --remove-blocking <blocked_issue_numbers_or_urls>

The relationship flags accept comma-separated issue numbers or URLs where multiple relationships are supported.

For $to-specs, mutate only the exact Spec dependency edge it semantically owns: either both Specs share the same Wayfinder lineage, or at least one endpoint is intentionally Independent under the repository Spec-governance rules. For $project-delivery-management, mutate only the exact cross-Wayfinder edge it authorized between two Wayfinder-managed endpoints. Neither caller may add/remove neighboring dependencies, hierarchy, labels, Project fields, or lifecycle state in the same helper call.

Verification

A zero exit status is not sufficient proof.

After every native relationship mutation, the caller must re-read the affected issue relationship and require the requested result:

• add → exact relationship exists;
• remove → exact relationship is absent;
• parent change → exact direct parent matches.

If verification fails, return the mutation/verification failure to the semantic owner. Do not compensate by writing text-based duplicate relationship state.