Skip to content

🐛 Add shutdown protocol to pr-logbook skill - #106

Merged
hcross merged 1 commit into
mainfrom
fix/issue-104-pr-logbook-shutdown-protocol
May 14, 2026
Merged

🐛 Add shutdown protocol to pr-logbook skill#106
hcross merged 1 commit into
mainfrom
fix/issue-104-pr-logbook-shutdown-protocol

Conversation

@hcross

@hcross hcross commented May 14, 2026

Copy link
Copy Markdown
Owner

Implements #104. Adds a Shutdown protocol section to the pr-logbook skill so the agent exits cleanly after completing a task and responds immediately to shutdown_request signals instead of idling in a poll-without-consume loop.

How to read this PR?

Single logical change, three mirrored files. Read in this order:

  1. community-config/skills/pr-logbook/SKILL.md — the source of truth. Two additions at the bottom: a one-paragraph Idle behavior note and a Shutdown protocol section with the exact JSON payload the agent must send. provenance.version bumped 1.1.31.1.4 per the version-bump rule in §"Cross-cutting: skill / agent source version bumps".
  2. .claude/skills/pr-logbook/SKILL.md and .gemini/skills/pr-logbook/SKILL.md — byte-identical mirrors of the community-config source.

Non-obvious design decision: the shutdown text is prescriptive only. It does not implement a watchdog. The curator's report (#104) proposed a runtime mitigation at the team-orchestration layer; that work is tracked separately under the auto-fix effort referenced by #42. This PR closes the skill-text half of the gap.

How to test this PR?

# 1. Sanity-check the three mirrors are byte-identical for the new sections.
diff <(sed -n '/^## Shutdown protocol/,$p' community-config/skills/pr-logbook/SKILL.md) \
     <(sed -n '/^## Shutdown protocol/,$p' .claude/skills/pr-logbook/SKILL.md)
diff <(sed -n '/^## Shutdown protocol/,$p' community-config/skills/pr-logbook/SKILL.md) \
     <(sed -n '/^## Shutdown protocol/,$p' .gemini/skills/pr-logbook/SKILL.md)
# Expected: no output (identical).

# 2. Verify the version bump.
task check-skill-versions
# Expected: pass.

Failure mode covered: forgetting to bump provenance.version while editing a SKILL.md source — scripts/check-skill-versions.sh rejects the diff.

Detailed description (for agents)

Modified: community-config/skills/pr-logbook/SKILL.md, .claude/skills/pr-logbook/SKILL.md, .gemini/skills/pr-logbook/SKILL.md (3 files, +57 / −3 in commit a65e963).

Each file gains the same two sections at the end:

  • ## Idle behavior — restates the one-sentence availability-confirmation rule established by Friction cluster: teammate-redundant-idle-confirmation (1 report) #96, kept here so the shutdown contract sits next to the related guidance.
  • ## Shutdown protocol — defines the contract:
    • On receipt of a shutdown_request message, respond with {"type": "shutdown_response", "request_id": "<id>", "approve": true} and stop. No deferral, no summarising, no waiting on in-flight ops.
    • After completing a task: TaskUpdate → completion message → stop. Do not re-enter a wait loop.

provenance.version in the community-config source is bumped 1.1.31.1.4 (PATCH — friction-driven wording fix, no contract change). The .claude/ and .gemini/ mirrors carry the same version string.

Post-merge action (per skill §7): close #104 with state_reason: completed. The logbook entry was appended as a comment on #104 itself (the upstream feedback issue), so no separate logbook issue exists to close.

@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.

Cold-start review — PR #106

Independent audit, no authoring context. (Posted as COMMENT because GitHub blocks self-approval; intended verdict is Approve.)

Correctness

The change adds a ## Shutdown protocol section to the three pr-logbook/SKILL.md files (community-config/, .claude/, .gemini/). The new section:

  • Specifies the exact shutdown_response JSON payload (type, request_id, approve: true) — verifiable at community-config/skills/pr-logbook/SKILL.md:223-227.
  • States the hard-stop semantics: no deferral, no summarising, no waiting on in-flight ops.
  • Adds a post-completion rule: TaskUpdate → completion message → stop, no re-entering the wait loop.

This directly addresses the failure mode described in #104 (agent kept sending idle notifications without consuming shutdown_request). The mitigation is prescriptive only, which is consistent with the PR body's note that the runtime watchdog is tracked separately under #42.

Convention compliance

  • Gitmoji title: 🐛 Add shutdown protocol to pr-logbook skill — conforms to AGENTS.md §"Commit Convention".
  • PR body structure: all four required sections present (intro, How to read, How to test, Detailed description). ✅
  • Logbook linkage: PR body states the logbook entry was appended as a comment on #104 itself. Acceptable interpretation — the friction-cluster issue serves dual duty as feedback and logbook anchor.
  • Version bump: provenance.version 1.1.31.1.4 in the community-config source (PATCH for wording-only change). Mirrors carry the same string. ✅
  • Three mirrors byte-identical for the new section: verified locally via the diff commands from the PR's test plan — MIRRORS_OK. ✅
  • Branch name: fix/issue-104-pr-logbook-shutdown-protocol — conforms to fix/ prefix convention.

Test coverage

Documentation-only change; no executable surface to cover with tests. The PR's test plan provides two verification steps (mirror diff + task check-skill-versions); both are appropriate for a SKILL.md edit. Mirror diff confirmed clean locally.

Linter findings

  • lint-markdown.sh community-config/skills/pr-logbook/SKILL.md → exit 0, no output. Clean.
  • BASE_REF=origin/main lint-skill.sh community-config/skills/pr-logbook/SKILL.md → exit 0, no output. Frontmatter fields present, version bumped vs base. Clean.

Nit (non-blocking)

The "Detailed description" claims "Each file gains the same two sections at the end: ## Idle behavior and ## Shutdown protocol." The diff actually adds only ## Shutdown protocol; ## Idle behavior was already present from #96 (visible in the @@ -216,3 +216,21 @@ hunk, which appends after the existing Idle-behavior block). Minor description-vs-reality drift, not worth a re-push.

Verdict

Approve. The change is tight, well-scoped, conforms to project conventions, and closes the skill-text half of the gap reported in #104. Mirrors are consistent and linters are clean.

@hcross
hcross merged commit ec093f1 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: teammate-unresponsive-idle-loop (1 report)

1 participant