feat(session-flow): a "You are here" position panel on the save-point skills - #3055
Conversation
…oint skills Both save-point skills showed the operator only two things: a ticked enforcement checklist (the skill's own audit trail) and the rails resume prompt (a block to copy). Everything answering "what did we do, where are we, what is next" was computed and then filed into the handoff document, whose stated reader is a session with no prior context — and on the prompt-only path no file is written at all, so the recap existed nowhere. Add an engine section, "Emit the position panel", owning it once for both citing skills: a vertical rail with one line per unit, the current position marked in the gutter, a completeness read, and three one-line blocks. It restates what the save-point already established and triggers no read it did not already need — that is the line between it and orient's on-demand durable + off-thread sweep. Units resolve by first match: workflow stages, plan phases, an issue chain, live TaskList items, then completion criteria. Work with none of those gets the prose blocks and explicitly no rail; units are never invented to fill one. The rail is vertical because a horizontal one wraps at terminal width and orphans the position marker from the unit it marks. Above 8 units the middle elides; the panel caps at 16 lines. Those caps are load-bearing: the one observed failure of this engine is a turn ending before the rails prompt reaches the screen, and the panel is new text standing in front of it, so an uncertain panel degrades to one line rather than growing, and the engine states outright that it never gates the rails. handoff fixes its order as panel then checklist then rails, keeping the rails-last rule intact. continue-in-background emits panel, rails, launch, and passes the agent exactly the text between the rails. Not a detection-contract change: the panel sits above every keyed signal and outside the copy region, so find-handoff needs no edit. Four evals grade the shape rather than mere presence. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014cvjkNWz2hCfo6S5UBpgcv
|
Claude finished @kyle-sexton's task in 2m 48s —— View job Code review complete
Ran Skip-gatePR is open, not a draft, and has real review surface (245/-7 across 9 files). Proceeded with full review. What I checkedThis PR is entirely documentation / skill-instruction prose (SKILL.md files, a reference engine doc, changelog, README, and eval JSON) — there's no executable code path to unit-test for runtime bugs. I verified the claims the PR body makes against the actual repo state rather than taking them on faith:
FindingsNone that clear the high-signal bar (a careful senior reviewer blocking or flagging). One cosmetic-only observation, not filed as a blocking finding: No correctness bugs, no broken cross-references, no contract violations found in the reviewed diff. |
|
Claude finished @kyle-sexton's task in 43s —— View job Security review
No security issues found. This PR is entirely documentation/prose and eval-fixture content for a Claude Code skill plugin — no executable code, no GitHub Actions workflow changes, no auth/authz logic, no data handling, and no external input parsing. Changed files:
Notably, the redaction-pass language in Skip-gate condition 2 applies: no security-relevant surface in this diff. Nothing further to report. |
|
Last security-reviewed head: |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 42ef1dff9e
ℹ️ 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".
|
Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
…kList rung Two defects in the position-panel spec, both found by review. The worked example marked two phases `[x]` and a third `[~]`, then read "3 of 5 phases complete" — counting the in-progress unit as done. That example defines the shape agents copy, so it taught the miscount, in the one section whose whole purpose is an accurate progress read. The example now reads 2 of 5, and a rule states it: `[~]`, `[ ]`, and `[!]` count against the total, only `[x]` counts toward it. Unit-ladder rung 4 claimed live TaskList items were "already fetched, so this costs nothing extra". That holds only on the full path, where structure.md's Environment section makes the call. Prompt-only walks no body sections, so on that path the rung asked for a list nobody had fetched while the rule above forbade the panel from triggering a read — unfollowable either way. Rung 4 is now full-path only and falls through to completion criteria on prompt-only, which costs almost nothing since "no non-trivial task list to reconstitute" is one of the criteria that selects prompt-only to begin with. A prompt-only run FORCED by the explicit argument never tested that criterion, so it makes the one TaskList call rather than guessing from the conversation — named as the single exemption to "never discovers", since it reads the session's own ledger rather than the world outside the conversation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014cvjkNWz2hCfo6S5UBpgcv
|
Claude finished @kyle-sexton's task in 1m 18s —— View job Security review
No security issues found. This PR remains entirely documentation/prose and eval-fixture content for a Claude Code skill plugin. Since the last security review (head
All three changes are prose-only edits to instruction/spec documents — no executable code, no shell commands, no new tool invocations, and no change to the redaction sweep, the rails-prompt handling, or the Confirmed the full PR diff ( Skip-gate condition 2 applies: no security-relevant surface in this diff. Nothing further to report. |
|
Claude finished @kyle-sexton's task in 2m 30s —— View job Code review complete
Skip-gatePR is open, not a draft, and has real review surface (272/-7 across 9 files). Proceeded with full review. ScopePer What I checkedThis PR ships across two commits:
I independently traced the cross-references these changes lean on rather than taking them on faith:
FindingsNone that clear the high-signal bar. No correctness bugs, no broken cross-references, no internal inconsistencies survived inspection in the current (post-fix) diff. One pre-existing cosmetic note carried over from my prior pass, not a blocking finding: |
Adding "the position panel" to the swept-set sentence pushed the paragraph past the file's wrap band and left a 110-column line. Rewraps the whole paragraph rather than the one line, since fixing a single line just moved the overflow to the next one. Prose unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014cvjkNWz2hCfo6S5UBpgcv
|
Claude finished @kyle-sexton's task in 1m 55s —— View job Code review complete
ScopePer this repo's What's new since the last review passThe prior two review passes (against I diffed the paragraph text with line breaks stripped (before vs. after) to confirm the rewrap changed only line breaks, not wording — content is byte-identical apart from where it wraps. No new prose, no dropped words, no reflow artifacts. Independent checks performed
FindingsNone. No correctness bugs, no broken cross-references, no contract violations, and the one previously-noted cosmetic issue is now resolved. Not verified in this pass
|
2 participants
No linked issue
Summary
Both save-point skills showed the operator exactly two things: a ticked enforcement checklist, which
is the skill's own audit trail, and the rails resume prompt, which is a block to copy. Everything
answering what did we do, where are we, what is next was computed and then filed into the handoff
document — whose stated reader is "a session with NO prior context" (
reference/structure.md), sothe operator never reads it. On the prompt-only path no file is written at all and the recap existed
nowhere.
At the moment a human is deciding whether this is a sane place to stop and whether the work is still
pointed where they wanted it, the skill showed them a compliance checklist. The information to answer
both was already gathered — it was just never rendered for them.
Fix
A new engine section,
Emit the position panel, owns it once for both citing skills:It restates; it never discovers. Every line comes from what
Locate the position firstand thesections above already established. It triggers no read the save-point did not already need — that is
the line between it and
orient, which sweeps durable and off-thread state on demand.Units are resolved from the work, not assumed. A first-match ladder takes workflow-checklist
stages, then plan/spec/PRD phases, then an issue chain, then live
TaskListitems, then completioncriteria. Work matching none of those gets the three prose blocks and explicitly no rail —
inventing phases to have something to draw renders a map of a plan that does not exist, and the
operator would resume against it.
The rail is vertical because a horizontal one wraps. One unit per line, one line per block, never
a continuation line. A
→-chained row wraps at whatever width the terminal happens to be, and thewrap orphans the position marker from the unit it marks — destroying the single thing the panel
exists to show. Above 8 units the middle elides to a
… N moreline, keeping the ends and thecurrent position; the whole panel caps at 16 lines. Status glyphs are the ones
structure.mdalreadyuses for the TaskList snapshot, so no legend is needed.
It cannot become a reason to lose the rails prompt. The one observed failure of this engine is a
turn that ends before the prompt reaches the screen (
skills/handoff/context/gotchas.md), and thischange puts new text in front of that prompt. So the caps are load-bearing rather than cosmetic, an
uncertain panel degrades to one abbreviated line instead of growing, and the engine states outright
that the panel never gates the rails. A gotchas entry names this as the same failure with a new
cause.
Delivery order per skill:
handoffis panel → checklist → rails, leaving the rails-last rule intact;continue-in-backgroundis panel → rails → launch, and the launched agent still receives exactly thetext between the rails, never a line of the panel.
Not a detection-contract change — the panel sits above every keyed signal and outside the copy
region, so
find-handoffrecovers exactly what it recovered before and needs no edit. That is statedexplicitly in the contract section, which otherwise treats a shape change as a knowing break.
Claim provenance and the redaction sweep both extend to the panel: an inherited status keeps its
UNVERIFIED (<source>)marker, the completeness line says how many marks are unverified, and thepanel joins the outbound set the mandatory redaction pass covers.
Verification
Run against the rebased tree, not an earlier one:
npx markdownlint-cli2 "plugins/session-flow/**/*.md"— 0 issueseditorconfig-checker plugins/session-flow— cleantypos plugins/session-flow— cleanjq emptyon both changed eval suites and the manifest — parse cleanscripts/validate-plugins.sh— all manifests and the catalog validatedscripts/check-changelog-parity.shin all four modes —--check,--check-bump origin/main,--check-order,--check-preserved origin/main— all passscripts/check-changed-skills.sh origin/main— both changed skills PASS, 0 errorsnode scripts/generate-catalog.mjsandgenerate-cheatsheet.mjs— no drift; frontmatterdescriptionandmetadata.summarywere deliberately left alone, since this is an output-shapechange rather than a new capability and both feed the skill-listing context budget
check-usage-limit-reset,parse-transcript,observer) —pass
New eval coverage grades the shape rather than mere presence: the vertical rail with the current
unit marked, elision above 8 units, the prose fallback inventing no units, and the launched agent's
payload staying panel-free.
Not verified here: the behavioral end-to-end (invoking the skills and reading the rendered output at
an 80-column width). The evals encode those assertions; a live run is a separate exercise.
Also unverified by me, and worth a reviewer's eye:
scripts/run-plugin-tests.shfails inplugins/claude-config/skills/audit-permission-state/scripts/in my local container. That area isuntouched by this diff and
mainis green at the commit this branch was cut from, so I read those ascontainer-local (uid 0, and several of those suites read the ambient
~/.claudestate). CI is thearbiter, not that reading.
Related
Refs #3018 — that issue asks to compress the handoff instruction walk and names
save-point.mdspecifically. This change moves that file the other way, 452 → 547 lines (+95). Shipping the panel at
full spec was a deliberate call: the rationale paragraphs are what make the caps stick, and the
gotchas entry documents a real failure they guard against, so trimming them here is how the rule
quietly stops being followed. Recorded plainly so the compression pass starts from an accurate
picture rather than a surprise.
Generated by Claude Code