Skip to content

🐛 Specify logbook closing lifecycle in AGENTS.md and pr-logbook skill - #105

Merged
hcross merged 1 commit into
mainfrom
fix/issue-103-logbook-closing-lifecycle
May 14, 2026
Merged

🐛 Specify logbook closing lifecycle in AGENTS.md and pr-logbook skill#105
hcross merged 1 commit into
mainfrom
fix/issue-103-logbook-closing-lifecycle

Conversation

@hcross

@hcross hcross commented May 14, 2026

Copy link
Copy Markdown
Owner

Implements #103. Codifies who closes a logbook issue and when, so the lane does not silently accumulate stale open issues after merge.

How to read this PR?

Single commit, four files, all documentation:

  1. AGENTS.md — three-line clause added to the Logbook Issues section stating that the logbook issue must be closed (state_reason: completed) once its PR is merged and any linked feature issue is closed. This is the human-facing rule.
  2. community-config/skills/pr-logbook/SKILL.md — canonical source. New §7 "Post-merge cleanup" describes the close procedure (gh CLI + GitHub MCP variants) and the §4-path exception. provenance.version bumped per community-config/FORMAT.md.
  3. .claude/skills/pr-logbook/SKILL.md and .gemini/skills/pr-logbook/SKILL.md — vendor mirrors of the canonical source, kept in lockstep.

The §4-path exception matters: when the PR closes an upstream feature issue (the path #95 introduced), the logbook entry lives as a comment on that issue, so closing the feature issue covers it — no separate close needed.

How to test this PR?

git fetch origin
git switch fix/issue-103-logbook-closing-lifecycle
git diff main...HEAD --stat   # expect 4 files, +57/−3
grep -n "Once the PR is merged" AGENTS.md
grep -n "Post-merge cleanup" community-config/skills/pr-logbook/SKILL.md
grep -n "Post-merge cleanup" .claude/skills/pr-logbook/SKILL.md
grep -n "Post-merge cleanup" .gemini/skills/pr-logbook/SKILL.md
task check-skill-versions   # confirms the provenance.version bump on the canonical source

Expected: each grep returns one hit per file; the version check passes (the canonical pr-logbook SKILL.md carries the bump in the same diff).

Detailed description (for agents)

  • AGENTS.md — three new lines at the end of Logbook Issues establishing the close rule. Wording deliberately matches the §7 SKILL phrasing so the two sources stay synonymous.
  • community-config/skills/pr-logbook/SKILL.md — new §7 "Post-merge cleanup". Two-step procedure: (1) close the logbook issue with gh issue close <n> --reason completed or the GitHub MCP issue_write tool with state: "closed" and state_reason: "completed"; (2) if the PR also closed a feature issue (via Closes #N / Fixes #N / Resolves #N), verify GitHub's auto-close fired rather than assume. Includes the §4-path exception: skip step 1 when the logbook entry was a comment on an existing feature issue. provenance.version bumped (PATCH — friction-driven clarification, no contract break).
  • .claude/skills/pr-logbook/SKILL.md and .gemini/skills/pr-logbook/SKILL.md — identical §7 added; vendor mirrors track the canonical source so each harness reads the same contract.

This PR itself follows the §4-path: the logbook entry was posted as a comment on the upstream issue (#103) and the logbook label was applied there. Post-merge action (eating its own dogfood for §7): close #103 with state_reason: completed once this PR merges.

@hcross hcross left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Independent review — cold start

(Posted as COMMENT because GitHub refuses self-approval; the verdict below is functionally Approve — no blocking issues.)

Correctness

The change does what the PR body claims: adds a closing-lifecycle rule for logbook issues to both the human-facing contract (AGENTS.md) and the operational procedure (pr-logbook/SKILL.md).

  • AGENTS.md — three-line clause added directly under the existing Logbook Issues section. Correct insertion point.
  • Canonical community-config/skills/pr-logbook/SKILL.md — new §7 Post-merge cleanup placed after §6 Pre-push sanity checks and before the cross-cutting version-bump section. Consistent with the existing numbered-step model.
  • The §4-path exception is logically sound: when the logbook entry was appended as a comment on an upstream feature issue (the path codified by #95), closing the feature issue subsumes the logbook-close obligation. No duplicated work, no orphan issues.
  • Both gh issue close --reason completed and the GitHub MCP issue_write variants (state: "closed" + state_reason: "completed") are documented — matches the dual-tooling pattern used elsewhere in the skill.

Convention compliance

  • Commit title uses Gitmoji 🐛 — matches AGENTS.md §Commit Convention.
  • PR body follows the four-section template (intro / read / test / detailed). Two-sentence intro respected.
  • Branch name fix/issue-103-logbook-closing-lifecycle matches the documented fix/ prefix.
  • Vendor mirrors .claude/skills/pr-logbook/SKILL.md and .gemini/skills/pr-logbook/SKILL.md updated in lockstep with the canonical source — verified by diff (identical §7 block, identical version bump).
  • provenance.version bumped 1.1.2 → 1.1.3 across all three SKILL.md files. PATCH is the right level for an additive clarification with no contract break.
  • Linked issue: #103 exists, carries the logbook label, and the PR body explicitly notes the §4-path treatment (dogfooded — logbook entry posted as a comment on #103).

Test coverage

Documentation-only change; no executable surface to test. The task check-skill-versions invocation in the test plan is the right verification — it confirms the canonical SKILL bump is in the same diff.

Linter findings

  • lint-markdown.sh AGENTS.md community-config/skills/pr-logbook/SKILL.md → exit 0, no output.
  • lint-skill.sh community-config/skills/pr-logbook/SKILL.md → exit 0, no output.

Verdict

Approve. Minimal, internally consistent across the three mirrors, lands the rule in the two correct surfaces (contract + procedure), correctly carves out the §4 exception. No blocking issues.

One forward-looking, non-blocking observation: once #42 (auto-fix mode) lands, the §7 close step is a natural candidate for automation by the pr-logbook agent after squash-merge — worth tracking as a follow-up.

@hcross
hcross merged commit acec3f5 into main May 14, 2026
5 checks 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.

Friction cluster: agents-md-logbook-lifecycle (1 report)

1 participant