Skip to content

feat(lifecycle): claim guard, backfill exclusion, and parent-only handoff for sub-issues#280

Merged
aagnone3 merged 2 commits into
mainfrom
claude/agents-sub-issue-recommendation-2b8829
Jul 22, 2026
Merged

feat(lifecycle): claim guard, backfill exclusion, and parent-only handoff for sub-issues#280
aagnone3 merged 2 commits into
mainfrom
claude/agents-sub-issue-recommendation-2b8829

Conversation

@aagnone3

@aagnone3 aagnone3 commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Closes #269

Scope note: this PR was reworked after #283 (from the parallel #265 issue lineage) merged the gate-level redirect first, under the sub_issue verdict with reconciler-owned de-boarding. #280 now unifies on that merged design and ships only the complementary pieces #283 does not cover.

Summary

  • Claim guard: --claim on an OPEN sub-issue refuses with a structured sub_issue_claim error naming the parent, before any assignment or board write. Without this, a claim on a sub-issue still writes board state and relies on the reconciler to clean up afterward.
  • Backfill exclusion: --backfill reads parentage for all add-candidates in one batched GraphQL query (mirroring the blocked-counts pattern) and skips any issue with a non-null parent, reported under skipped_sub_issues. This prevents add-then-archive churn with reconciler rule 6. An unreadable parent lookup fails that candidate toward not adding and breaks the advisory high-water prefix so a re-run reconsiders it; rc==0 malformed GraphQL bodies degrade like a total failure instead of raising.
  • Handoff prose: the wf-grooming planning ready boundary now requires completion reports to name the parent as the sole /wf-development entry point and forbids recommending a sub-issue as where development begins; sub-issue ordering is expressed only as blocked-by structure inside the parent.

Testing

  • 8 new unittest cases (172 total, all passing): claim refusal with no board write, claim-guard precedence over self-assigned and conflicting-assignee paths, backfill skip/parentless-add, single and total parent-lookup failure, high-water guard when a skip follows a failure, malformed-body degradation. Category assertions (error code, verdict enum, structured fields), not prose spellings.
  • bun test 428 pass / 0 fail; typecheck, skills:check (20 vendored copies in sync), docs gates all green.
  • Verb-level gate wiring is already pinned on main by feat(lifecycle): sub-issue board hygiene — parent-aware gates + reconciler-owned de-boarding #283's ParentAwareVerbThreadingTest; not duplicated here.

Post-Deploy Monitoring & Validation

  • What to monitor/search
    • Backfill JSON reports: skipped_sub_issues populated on repos with decomposed parents; failed[].error mentioning parent lookup.
  • Validation checks (queries/commands)
    • python3 plugins/agentic-engineering/scripts/lifecycle_board.py --claim <open-sub> → structured sub_issue_claim refusal, no board write.
    • python3 plugins/agentic-engineering/scripts/lifecycle_board.py --backfill → sub-issues listed under skipped_sub_issues, never added.
  • Expected healthy behavior
    • Backfill runs stop producing reconciler rule-6 archive churn for sub-issues.
  • Failure signal(s) / rollback trigger
    • Parentless issues wrongly skipped, or whole backfill runs reporting all-failed → revert the PR (additive change, no data migration).
  • Validation window & owner
    • Window: next backfill/claim activity. Owner: @aagnone3.

Compound Engineered 🤖 Generated with Claude Code

aagnone3 added a commit that referenced this pull request Jul 22, 2026
@aagnone3
test(lifecycle): pin verb-level parent wiring and backfill guard inva…
c44666b 
…riants

Review fixes for PR #280: add verb_gate/verb_groom_entry wiring tests
for the parent payload key, claim-guard precedence tests over assignee
checks, a backfill test that a skip never advances the high-water mark
past an earlier failure, and degrade malformed rc==0 GraphQL bodies in
_batched_parent_numbers like a total failure instead of raising.
@aagnone3 aagnone3 mentioned this pull request Jul 22, 2026
Open
@aagnone3

aagnone3 commented Jul 22, 2026

Copy link
Copy Markdown
Collaborator Author

Final compounding check
Head: c44666b
Result: captured
Artifacts: plugins/agentic-engineering/skills/wf-setup/references/lifecycle.md; plugins/agentic-engineering/skills/wf-development/references/workflows-work.md; plugins/agentic-engineering/skills/wf-grooming/references/workflows-plan.md; plugins/agentic-engineering/skills/wf-grooming/references/workflows-groom.md; plugins/agentic-engineering/skills/wf-grooming/references/workflows-brainstorm.md; plugins/agentic-engineering/skills/wf-setup/references/lifecycle-bootstrap.md
Reason: The durable lesson (sub-issues carry no independent lifecycle; the parent is the sole grooming/planning/development entry point, enforced by the closed route_to_parent verdict) is shared workflow policy whose owner is the wf-* skill prose amended in this same PR; regression behavior is pinned by category-asserting tests in plugins/agentic-engineering/tests/lifecycle_board_test.py.

@aagnone3
feat(lifecycle): claim guard, backfill exclusion, and parent-only han…
39d472d 
…doff for sub-issues

Complements the sub_issue gate verdict and reconciler rule 6 shipped in
PR #283: --claim refuses an OPEN sub-issue with a structured
sub_issue_claim error before any board write; --backfill reads candidate
parentage in one batched GraphQL query and skips parented issues
(reported as skipped_sub_issues) instead of add-then-archive churn; the
planning ready boundary now requires handoffs to name the parent as the
sole wf-development entry point.
@aagnone3
aagnone3 force-pushed the claude/agents-sub-issue-recommendation-2b8829 branch from c44666b to 39d472d Compare July 22, 2026 08:52
@aagnone3 aagnone3 changed the title feat(lifecycle): parent-aware gates redirect sub-issue invocations to the parent feat(lifecycle): claim guard, backfill exclusion, and parent-only handoff for sub-issues Jul 22, 2026
@aagnone3

aagnone3 commented Jul 22, 2026

Copy link
Copy Markdown
Collaborator Author

Final compounding check
Head: b6d126a
Result: captured
Artifacts: plugins/agentic-engineering/skills/wf-setup/references/lifecycle.md (sub_issue_claim claim semantics); plugins/agentic-engineering/skills/wf-setup/references/lifecycle-bootstrap.md (skipped_sub_issues in the backfill report); plugins/agentic-engineering/skills/wf-grooming/references/workflows-plan.md (parent as the sole wf-development entry point)
Reason: The durable lessons of this PR's deltas (an OPEN sub-issue is never claimable; backfill excludes parented candidates and fails unreadable lookups toward not-adding; grooming handoffs name the parent, never a sub-issue) are captured in the maintained wf-* skill prose amended in this same PR, complementing the sub_issue verdict documentation merged in PR #283; behavior is pinned by category-asserting tests in plugins/agentic-engineering/tests/lifecycle_board_test.py.

@aagnone3
aagnone3 merged commit 38f88a8 into main Jul 22, 2026
6 checks passed
@aagnone3
aagnone3 deleted the claude/agents-sub-issue-recommendation-2b8829 branch July 22, 2026 09:07
@github-actions github-actions Bot mentioned this pull request Jul 22, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Parent-aware lifecycle gates: redirect sub-issue invocations to the parent

1 participant

@aagnone3