Skip to content

Verify forward issue references in Phase 4 before pushing - #179

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/verify-forward-issue-references
Nov 17, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
feature/verify-forward-issue-references

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

  • A paragraph is added to the template's Phase 4, right after the existing Closes #N and closing-keyword checks. It covers the reverse case: a PR body that promises an issue that has not been filed yet ("a follow-up issue has been filed"). Generated loops are told to file every promised follow-up issue before writing the body, cite it by number (filed as #N), and run gh issue view <N> on every #N the body mentions, not only the ones after a closing keyword.
  • Filing the issue first makes the failure impossible rather than just detectable. The observed instance (Dans-Plugins/Medieval-Factions PR #2019) was a dispatch interrupted between writing the body and filing the issue.
  • No new placeholder is introduced, no fence is added, no phase is renumbered, and no Step changes, so README's "What it does" list is unaffected.
  • A RESEARCH.md §7 Implementations entry is added.

Closes #133

Retrofit note: this adds a rule to the template, so every existing <slug>-dev-loop skill generated before this change lacks it. That includes create-dev-loop-dev-loop (template-version 44756ec) and medieval-factions-dev-loop, where the gap was first observed (its #49). Each probably needs a retrofit pass. Only the operator can see the full list of installed skills.

Skipped issues: all other open issues were deferred to keep this PR to one change. #173 (remaining half) and #106 need CLAUDE.md edits, which require separate authorization. #109 and #114 are human-gated verification questions. The remaining template-rule issues and #141/#143 are independent template changes left for later cycles.

Research grounding

RESEARCH.md §7 (LLM triage is a filter, not a decision-maker): its implication is that skip reasoning must be auditable rather than silent. PR #29 added "Record skip reasons", but a skip reason that points at a not-yet-filed issue can't be audited. This change ties the promise to an artifact that already exists. It is also related to §4 (re-state scope at boundaries), the basis of the existing Closes #N check (PR #26).

Doc sync check

  • README.md's "What it does" Step list still matches create-dev-loop.md's Steps 1:1 (no Step changed)
  • No {{placeholder}} added or changed
  • RESEARCH.md updated (an Implementations entry under §7)

Test plan

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

dmccoystephenson and others added 2 commits November 16, 2026 01:25
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (one intrinsic pass, anchored on CI run 43831124541 and check_docs.py):

  • Scope: PASS — 2 files, +3 lines: one Phase 4 paragraph in create-dev-loop.md (Phase 4 verifies backward 'Closes #N' references but not forward 'a follow-up issue has been filed' promises #133) and its RESEARCH.md §7 Implementations entry. No unrelated churn.
  • Tests-new: PASS (n/a) — no executable code changed; scripts/check_docs.py is untouched.
  • Tests-fix: n/a — a template-rule addition, not a bug fix in code.
  • Sibling structure: PASS — no new files.
  • Sibling renames: PASS — nothing renamed.
  • Docs: PASS — README "What it does" is unaffected (no Step changed); CONTRIBUTING.md, SECURITY.md, and the PR/issue templates restate nothing about Phase 4 reference checks.
  • Issue resolution: PASS — Phase 4 verifies backward 'Closes #N' references but not forward 'a follow-up issue has been filed' promises #133 asks for a forward-reference check right after the Closes #N guard, with file-first ordering. Both are in the added paragraph.
  • CI: PASS — doc-consistency is green on the PR head.
  • Placeholder parity: PASS — no double-brace token added; check_docs.py reported "Doc consistency check passed."
  • README Step parity: PASS — no Step added, removed, or renamed.
  • Fence escaping: PASS — no fence added.
  • Phase numbering: PASS — no phase renumbered.
  • Version comments: PASS (n/a) — the header is untouched.
  • Research grounding: PASS — the body cites §7 (and §4); a §7 Implementations entry was added.
  • No back-ported specifics: PASS — the observed-instance repo name appears only in the PR body, not in the template.
  • gardener interface: PASS (n/a) — Steps 3, 5, and 6 are unchanged.
  • Retrofit note: PASS — the body names create-dev-loop-dev-loop and medieval-factions-dev-loop.
  • Behavioral validation: FAIL / UNVERIFIED — /create-dev-loop was not run against a real repo, because the headless dispatch can't create a GitHub repo or write outside the checkout ([self-audit] The repo's own validation anchor is structurally unrunnable in a headless dispatch, so template changes can never merge autonomously #109). create-dev-loop.md template changes therefore can't be auto-merged and are handed to a human.

Judgment call for the reviewer: the paragraph says "run gh issue view <N> on every #N the body mentions". A body that cites many historical PRs/issues (as this one does) turns that into several lookups per PR. That cost was accepted because a wrong or missing number is the exact failure the rule targets.

Summary: mechanically clean and CI green; behavioral validation of the template change is outstanding, so the PR is left open for human review rather than merged.

This review comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 08929ae into main Nov 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Phase 4 verifies backward 'Closes #N' references but not forward 'a follow-up issue has been filed' promises

1 participant