docs: improve the spec-driven loop (stack maintenance, re-entry, stacked-PR upkeep)

[gregorydemay]

Purpose

Tighten the spec-driven build loop in CLAUDE.md (and the implementer agent) based on gaps that surfaced while running the DEFI-2853 stack.

Changes

1. PR-stack maintenance is the orchestrator's job. When a PR is added to / removed from / reordered in a stack, the orchestrator refreshes the "📚 PR stack" section of every other PR (and the spec's Delivery sequence); the implementer only maintains its own PR's section (implementer.md clarified).
2. Re-run comments and CI after any push. Step 3 now says: after any push (a fix, a main-merge, a rebase) re-run both the CI check and the unresolved-comment check — never one without the other. (A maintenance push that re-triggered CI also re-triggers bot review.)
3. "Ready for review" is a pause, not the end. Step 4 now states the STOP is non-terminal: while a PR stays open it keeps accruing activity (human review, bot re-review, a merge), so any new commit/comment re-enters the loop at step 3.
4. Stacked-PR upkeep when a base merges. Added the recurring procedure: retarget the dependent to the new parent, merge it in + resolve conflicts, re-green, and refresh its stack section.

Why

Detection of unresolved comments was already specified in the loop, but the loop terminated at "ready" and a later maintenance push only re-checked CI — so comments that landed afterward went unseen. These edits make re-entry explicit and codify the stacked-PR upkeep we'd been doing ad hoc.

[Copilot]

Pull request overview

Clarifies ownership of “📚 PR stack” maintenance across stacked PRs by explicitly assigning cross-stack refresh duties to the orchestrator (in CLAUDE.md) while scoping the implementer agent to only maintain the current PR’s stack section (in .claude/agents/implementer.md).

Changes:

• Add orchestrator responsibility to refresh other PRs’ “📚 PR stack” sections (and the spec’s Delivery / PR sequence) whenever the stack changes.
• Update implementer guidance to maintain only its own PR’s “📚 PR stack” section, deferring cross-PR consistency to the orchestrator.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
CLAUDE.md	Adds explicit orchestrator instruction to keep stacked-PR metadata consistent across the stack and in the spec’s delivery sequence.
.claude/agents/implementer.md	Clarifies implementer scope: maintain stack section only for the PR it is building; orchestrator handles cross-stack updates.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to 735d3cd.

Security Overview

• 🔎 Scanned files: 2 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/a2241de7-cf71-4864-8711-25a8fbfe66c5?scanId=c093b588-481b-4f17-aa44-456f7aaa40c4&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Refactor	► .claude/agents/implementer.md     Clarify responsibilities for maintaining PR stack sections ► CLAUDE.md     Add details on handling stacked PRs and updating stack sections     Update descriptions related to PR checks and loop termination conditions

[github-actions]

canbench 🏋 (dir: canister) fe86539 2026-06-22 14:41:15 UTC

✅ canister/canbench_results.yml is up to date
📦 canbench_results_benchmark.csv available in artifacts

---------------------------------------------------

Summary:
  instructions:
    status:   No significant changes 👍
    counts:   [total 12 | regressed 0 | improved 0 | new 0 | unchanged 12]
    change:   [max +282.01K | p75 +51 | median 0 | p25 0 | min -1.75K]
    change %: [max +0.52% | p75 0.00% | median 0.00% | p25 0.00% | min -0.00%]

  heap_increase:
    status:   No significant changes 👍
    counts:   [total 12 | regressed 0 | improved 0 | new 0 | unchanged 12]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

  stable_memory_increase:
    status:   No significant changes 👍
    counts:   [total 12 | regressed 0 | improved 0 | new 0 | unchanged 12]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

---------------------------------------------------
CSV results saved to canbench_results.csv