Skip to content

feat(planning): wayfind absorbs the wayfinder decisions and accept list - #12574

Merged
kyle-sexton merged 7 commits into
mainfrom
fix/12524-replacement
Nov 3, 2026
Merged

kyle-sexton merged 7 commits into
mainfrom
fix/12524-replacement

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Refs: #12477
Refs: #12524

Summary

Replaces lanes PR #12524 (needs-session). It merges #12524's head (c62c93e) into current main unchanged, plus one fix for the lint-repo failure the lane could not make. #12524's own summary, conflict list with Matt's wayfinder, remaining work and not-verified items carry over as written there: /planning:wayfind takes the owner's flow, research, shared-files and picking decisions (Q531-Q533, D108) and the Topic 10 "Wayfind" accept list, with two new settings, wayfind_research_start and wayfind_hitl_concurrency. Done-when item 2 of #12477 (the interview's size threshold) is still open, so this refs the issue and does not close it.

Fix

lint-repo failed on next-graph (job):

check-next-graph: stage-skip: /planning:wayfind (contract) routes to /work-items:decompose (decompose), skipping the design, plan stage the ladder never skips

Decision: keep the lane's wayfind → /work-items:decompose closure and let the gate allow that one edge. Basis: owner decision Q531, quoted in #12477 ("Decisions (owner-approved: GUIDE D108; register Q205, Q531-Q535; all 2026-10-15)", and "The map closes to prd, decompose or work"). A closed map has already resolved the design decisions a plan would hold. The stage-skip rule is a workflow gate with no allowance for that edge, so the gate is what changes. Design and Plan stay required for every other skill, and wayfind keeps workflow-stage: contract.

  • scripts/check-next-graph.py: the chain roster accepts a per-edge skip-to: <plugin:skill> <reason> declaration, and the stage-skip check passes only the declared edge. A malformed skip-to (no target) exits 2.
  • scripts/next-graph-chain.txt: documents the declaration. planning:wayfind declares skip-to: work-items:decompose, with Q531 (planning: wayfind absorbs the wayfinder #12477) as its reason.
  • scripts/test_check_next_graph.py: one new test proves the declared edge passes and a different stage skip from the same skill still fails. A second proves a skip-to with no target exits 2.
  • plugins/session-flow/skills/workflow/context/steps.md: the Decompose stage now says a closed wayfind map whose destination is a set of build items enters it directly (Q531), so the ladder and the gate agree.
  • .changes/session-flow/: patch fragment for the ladder text.

Verification

Run locally on the merged head:

  • python3 scripts/check-next-graph.py: clean (it failed with the finding above before the fix)
  • scripts/check-next-graph.test.sh: 19 tests OK, including the 2 new ones
  • scripts/run-ruff.sh check and format --check on both Python files: clean
  • scripts/check-changelog-fragments.sh --check: all 12 fragments valid
  • scripts/check-changed-skills.sh --merge-base: wayfind PASS (0 errors, 6 size and growth warnings, the same ones feat(planning): wayfind absorbs the wayfinder decisions and accept list #12524 reported), workflow PASS (0 errors, 2 warnings)
  • scripts/check-affected.sh --tests: 14 lint checks passed, 1 skipped. Tests: every selected suite passed except plugins/planning/skills/setup/scripts/setup-apply.test.sh, which fails the same 96 cases on an unmodified main checkout on this host. That suite sets HOME to a temp dir, which likely breaks this machine's node resolution (UNVERIFIED), so it is environmental and CI's run decides. scripts/test_check_next_graph.py runs through check-next-graph.test.sh (above).
  • pre-push hook (check-affected from the merge-base copy, guardrails content and reference checks): passed

Not verified: the wayfind eval cases were not run. This lane has no eval runner, as #12524 also noted.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj

melodic-automation-lanes Bot and others added 5 commits November 2, 2026 22:06
Lane-Activity: work-resolve-issue/resolve-issue
Lane-Activity: pr-unblock/address-feedback
Lane-Thread: PRRT_kwDOTCGFQM6y4xIA
check-next-graph failed lint-repo on #12524: wayfind (contract) routes to
/work-items:decompose, past design and plan. That edge is owner decision
Q531 (#12477): a map closes to prd, decompose or work.

The chain roster gains a per-edge `skip-to: <plugin:skill> <reason>`
declaration, and wayfind declares the one edge to decompose. Every other
stage skip still fails, which a new test proves. The workflow ladder's
Decompose stage now states the same entry, so ladder and gate agree.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj
The parser description no longer calls splitlines on a possibly-None
__doc__, and the test module raises ImportError when the gate's spec or
loader cannot be built instead of dereferencing None.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-03T00:59:41.929720Z 30a3875 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 30a3875ef4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

claude-security-review reviewed a63f6c810b09e0fdffbc8326a770d33da171a915: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #12574, incremental (b01ed71 → a63f6c8)

No security issues found. I read every hunk of both files in the incremental scope. Neither file is on a trusted path. This push changes no plugin manifest, workflow, action, token request, merge-hold script or trust control.

What I checked

  • plugins/planning/skills/wayfind/context/tracker-mechanics.md: the over-cap ranking rule.
    • What changed: the old rule ranked the needs-human claims that went over wayfind_hitl_concurrency by item number. The new rule ranks them by claim order. Each claim's rank is its active lease comment id. A counted claim with no lease comment yet ranks last.
    • Who it affects: a claimant outside the earliest wayfind_hitl_concurrency ids releases only its own lease, using the lease_comment_id its own claim returned, and clears only its own assignee. Nothing here lets one session release or override another session's claim.
    • Instruction-surface lens: this tightens a coordination rule; it does not delete or soften a guardrail. The claim and lease steps run through /work-items:track and are unchanged.
    • Security reach: a crafted comment could at most affect which claimant keeps a planning slot. That is a scheduling outcome. It exposes no token or secret, runs no code in a trusted context, and cannot bill.
  • .changes/planning/…ef8a5f4e.md: the changelog fragment now says "claim order" to match. It is prose only.
  • Settled threads: the one tracker-mechanics thread changed at this head is the code-review lane's race point. The owner's reply says it was fixed in a63f6c8, and I raise nothing on it. No settled-thread or PR-context text is aimed at this review lane.
  • Prior findings: this lane's only earlier post is the round-2 summary, which had 0 findings, so there is nothing to repeat. The round cap (3) was not reached.

Spend: none. Nothing in this change uses prepaid credit or subscription usage, and nothing can bill.

critical-findings: 0

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

claude-review: 3 inline finding(s) on 30a3875ef42402ea05be7d72ab269d6ee7ad4d0c; the summary is in this lane's pull request comment.

claude-lane: claude-review

Comment thread scripts/check-next-graph.py Resolved
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

claude-review reviewed a63f6c810b09e0fdffbc8326a770d33da171a915: read 2 of 2 changed file(s); 0 finding(s), 0 as inline comments.

Code review (incremental): b01ed71277..a63f6c810b, PR #12574

I read every hunk of both files in the incremental diff and found no findings. Nothing blocks the merge.

This lane's earlier finding is fixed. It said that ranking over-cap needs-human claims by item number can leave the wayfind_hitl_concurrency cap exceeded (thread). Claims are now ranked by claim order (the active lease comment id), and the earliest ones keep the slots. I checked this against the claim code:

  • Order of a claim on GitHub. adapters/github/claim.sh assigns the item first (step 1) and posts the lease comment second (step 3). The session only recounts after start returns, so whichever claimant posts its lease later recounts after the earlier lease exists. It sees that lease and backs off. If the earlier claimant recounts before the later lease exists, the other claim shows as assigned with no lease, so it "ranks last" and the earlier claimant correctly keeps its slot. The ordering argument in the new text holds.
  • Renewing a lease does not reorder claims. adapters/github/renew-lease.sh updates the lease comment in place rather than posting a new one. A long-held claim keeps its original id, so a renewal cannot make it rank after a newer claim.
  • Other adapters. wayfind does not depend on one tracker provider. The ids are still ordered on the other adapters: the Linear seed builds lease_comment_id from the comment's createdAt, and local-markdown uses a numeric handle that is unique across its whole store.
  • Changelog. The fragment's wording ("released when its lease is not among the earliest by claim order") now matches the rule in tracker-mechanics.md.

Not verified by me: I had no shell, so I ran no tests. The PR's verification list is the author's claim.

No plugin manifest changed in this push, so there are no manifest lines. Nothing in this push adds cost or spend.

- wayfind work step 8: post a closing comment that states every
  resolved decision, then hand decompose `#<map-number>` and prd the
  decisions as its task description, both accepted source forms.
- wayfind `## Next`: one bullet per destination.
- tracker-mechanics: recount after a needs-human claim; over the cap,
  the lowest item numbers keep the slots and the rest release.
- check-next-graph: validate the raw declaration kind before rewriting
  it, so `entry point:` and `skip-to x:y:` exit 2; test both.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

claude-review: 1 inline finding(s) on b01ed71277bb76578e1282be340e82e008c0eb43; the summary is in this lane's pull request comment.

claude-lane: claude-review

Ranking by item number let two sessions both keep their claims when the
lower-numbered claim landed after the other session's recount. Rank by
lease comment id instead: a claimant recounts only after posting its
lease, so the later claimant always sees the earlier lease and backs off.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Vcupom3BKF6QuC5U3sRJPj
@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 3, 2026
Merged via the queue into main with commit 1c559c7 Nov 3, 2026
45 checks passed
@kyle-sexton
kyle-sexton deleted the fix/12524-replacement branch November 3, 2026 01:35
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Post-merge mutation testing

Killed 6, survived 1, timeout 0, no coverage 0, invalid 0, not run 0.
Covered-code score 86%; mutation score 86%.

File Killed Survived Timeout No coverage Invalid Not run
scripts/check-next-graph.py 6 1 0 0 0 0

Surviving mutants

Location Operator Disposition Cause
scripts/check-next-graph.py:183 other equivalent none

The run's summary has the full report.

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.

1 participant