docs(session-flow): document override boundary for stage taxonomy and retro rubric

[kyle-sexton]

Summary

session-flow baked a fixed workflow stage taxonomy (workflow's 8 stages) and a fixed 5-dimension retro scoring rubric as universal defaults, but never documented the override boundary. Per the plugin extensibility contract, a consumer must be told how to override without editing the plugin — this closes that documentation gap.

Fix

Make the boundary explicit in the two skills that own the fixed structure, documenting the existing mechanism rather than inventing one:

• workflow/SKILL.md — new Override boundary bullet in "Consumer conventions": the stage set is fixed plugin identity, there is no seam to swap in a different taxonomy, and what adapts (execution, gate commands, review criteria) flows through the conventions already named in that section.
• retro/SKILL.md — new "What this skill does NOT do" bullet: the five scoring dimensions are fixed plugin identity with no swap seam; what adapts is what each dimension scores against (the consumer's conventions, session-type calibration). Placed in SKILL.md rather than context/session.md because the dimensions surface across multiple mode context files, not just session mode.

The honest boundary is "taxonomy/rubric is fixed; only execution, gates, and scoring criteria adapt" — the existing seam is the consumer's own tracked instruction files, already referenced by the adjacent conventions. No behavior change. Version bumped 0.10.1 → 0.10.2 (docs = patch) with a matching CHANGELOG entry.

Verification

Ran the repo-pinned gates on all changed markdown (workflow/SKILL.md, retro/SKILL.md, CHANGELOG.md):

• markdownlint-cli2 v0.23.0 (schema-pinned in .markdownlint-cli2.jsonc), config .markdownlint-cli2.jsonc → Summary: 0 error(s)
• typos config _typos.toml → exit 0, no findings
• editorconfig-checker config .editorconfig-checker.json → exit 0

plugin.json version single-homed (marketplace entry carries no version field).

Related

• Closes session-flow: fixed workflow taxonomy, pre-PR sequence, and retro rubric have no documented override boundary #433

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 21s —— View job

---

PR Review — docs(session-flow): document override boundary

• Gather context and understand the request
• Read changed files
• Review diff against origin/main
• Post review findings

---

This is a documentation-only patch across 4 files. No behavior changes.

Summary

The PR closes a documentation gap in the plugin extensibility contract by explicitly stating what is and isn't configurable in session-flow. The two additions are accurate, well-placed, and consistent with each other and the surrounding prose.

File-by-file notes

plugin.json — 0.10.1 → 0.10.2: correct semver (patch for docs-only). marketplace.json carries no version field so there's no dual-update to maintain.

CHANGELOG.md — entry is accurate, clearly describes the boundary that was documented, and correctly notes "no behavior change."

skills/workflow/SKILL.md L47–50 — the "Override boundary." bullet fits the existing label pattern of "Consumer conventions" (matches Stage execution., Artifact location., Quality gates.). It correctly distinguishes what is fixed (the stage set itself) from what adapts (execution routes, gate commands, review criteria). Placement at the end of that section is natural.

skills/retro/SKILL.md L105–108 — the new bullet follows the sentence pattern of the existing "What this skill does NOT do" bullets. Placement in SKILL.md rather than context/session.md is correct: the dimensions surface across all four mode context files, not just session mode, so this is the only right home for the constraint.

Checklist (REVIEW.md)

Check	Result
Object-level authorization	N/A — docs only
Tenant-scoped data access	N/A
Secrets/credentials in source	None
Injection via string concatenation	N/A
Atomicity across related writes	N/A — no state writes
Audit logging for high-risk actions	N/A

Nit (1)

🟡 retro/SKILL.md L108: "never the dimension set by editing the plugin" is slightly elliptical — a reader might parse "dimension set" as the noun phrase and "by editing the plugin" as the adverbial, but on first read it could momentarily scan as "don't edit the dimension-set of the plugin." The workflow version ("never by editing the plugin") is cleaner. Consider: "…never the dimensions themselves." — but this is very minor given the preceding sentence already makes the constraint explicit.

Verdict

No correctness issues, no security issues, no structural concerns. The boundary statement is accurate, consistently phrased between the two skills, and well-placed in both files. The PR does exactly what it says on the tin.

[kyle-sexton]

Control-tower digest verdict: HOLD (not merge-ready as-is).

1. Version collision: main is already at session-flow 0.10.2 (via fix(session-flow): derive retro HANDOFF_DIR from resolved memory_dir #469). This branch bumps 0.10.1->0.10.2 and inserts a second, different [0.10.2] CHANGELOG entry — now CONFLICTING/DIRTY. Rebase onto main and re-bump to 0.10.3 (plugin.json + CHANGELOG).
2. Linkage overreach: body says 'Closes session-flow: fixed workflow taxonomy, pre-PR sequence, and retro rubric have no documented override boundary #433' but addresses findings 1 and 3 only; finding 2 (workflow/context/pre-pr.md:13-15 — Simplify pass presented as universal pre-PR sequence) is untouched. Either address finding 2 in this PR or narrow the linkage to a partial reference so session-flow: fixed workflow taxonomy, pre-PR sequence, and retro rubric have no documented override boundary #433 stays open for the remainder.

Otherwise clean: prose consistent, no leaked paths, no broken refs.

[claude]

Claude finished @kyle-sexton's task in 1m 38s —— View job

---

PR Review — docs(session-flow): document override boundary

• Gather context and understand the request
• Read current diff against origin/main
• Verify version bump and CHANGELOG state
• Review changed files
• Post review findings

---

Both blocking issues from the prior HOLD verdict are resolved. This PR is clean.

HOLD conditions — resolved

Issue	Status
Version collision (main was already at 0.10.2)	✅ Fixed — branch now bumps to 0.10.3
Linkage overreach (finding 2 in #433 untouched)	✅ Fixed — pre-pr.md now carries Override boundary bullet

File-by-file notes

plugin.json — 0.10.2 → 0.10.3. Main is pinned at 0.10.2; this is a clean non-colliding bump.

CHANGELOG.md — 0.10.3 entry prepended correctly above 0.10.2. Accurate description, "no behavior change" noted.

skills/workflow/SKILL.md L47–50 — "Override boundary." follows the label pattern of the existing Consumer conventions bullets. Correctly separates what is fixed (the stage set) from what adapts (execution routes, gate commands, review criteria).

skills/retro/SKILL.md L105–108 — Fits the "What this skill does NOT do" bullet pattern. Placement in SKILL.md over a mode context file is correct — the dimensions surface across all four mode context files.

skills/workflow/context/pre-pr.md L31–35 — Addresses finding 2 from #433 (simplify pass appeared as a universal, unqualified requirement). The bullet correctly states the sequence is fixed plugin identity, names what adapts (commands, review criteria), and handles the consumer-with-different-process case by pointing them to their own documented workflow. Placement at end of Scope tips is natural — the existing skip-condition for docs-only changes (L29) is immediately above.

Checklist (REVIEW.md)

Check	Result
Object-level authorization	N/A — docs only
Tenant-scoped data access	N/A
Secrets/credentials in source	None
Injection via string concatenation	N/A
Atomicity across related writes	N/A — no state writes
Audit logging for high-risk actions	N/A

Nit (1)

🟡 retro/SKILL.md L108: "never the dimension set by editing the plugin" — "dimension set" can momentarily parse as a noun phrase ("the dimension-set of the plugin"), making the sentence read as two competing noun phrases with no clear verb. The workflow/SKILL.md parallel ("never by editing the plugin") is cleaner. Consider: "…never the dimensions themselves." Not blocking.

Verdict

No correctness issues, no security issues. Both HOLD conditions lifted. The pre-pr.md addition is the key new hunk — it correctly addresses the finding that the simplify pass looked like an unqualified universal requirement, by documenting that the sequence is fixed plugin identity while commands and criteria remain consumer-owned. Closes #433 linkage is now fully justified.

[kyle-sexton]

Cleared the HOLD digest. Merged origin/main (no rebase) and pushed; branch is now MERGEABLE.

1. Version collision. Main shipped session-flow 0.10.2 via #469 (the retro HANDOFF_DIR fix). Resolved the CHANGELOG.md conflict by recovering both intents — kept main's 0.10.2 entry and re-homed this branch's override-boundary entry as 0.10.3, newest-first. Re-bumped plugin.json 0.10.2 → 0.10.3 (patch, docs-only, per the semver delivery convention in docs/MIGRATION-PLAYBOOK.md).

2. Finding 2 (addressed, not narrowed). Added an Override boundary note to skills/workflow/context/pre-pr.md "Scope tips" that names the simplify pass (steps 4–6) directly: the pre-PR sequence is fixed plugin identity with no consumer-config seam; what adapts is the commands and review criteria at each gate, and a consumer whose process genuinely differs runs its own documented workflow — which the workflow skill already recognizes (grounded in retro Phase 2B). This mirrors the framing already added for the stage set and retro rubric, so Closes #433 stays honest and is left as-is.

Gates on all changed markdown: markdownlint-cli2 0 errors, typos clean, editorconfig-checker clean.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 92ef6cf9e7

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f6dc1ade19

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

claude-code-plugins/plugins/session-flow/skills/workflow/context/pre-pr.md

Lines 34 to 36 in f6dc1ad

	at each gate (the intro above); a consumer whose process genuinely differs runs its own
	documented workflow separately, outside this skill — the `pre-pr` mode always loads this fixed
	map and never defers to a consumer-supplied one.

Honor consumer-defined pre-PR workflows

For a consuming repository with a documented pre-PR process that has a different order or mandatory additional gates (for example, security review or approval), /workflow pre-pr now explicitly tells the model to use this fixed checklist and not defer to those rules. Telling the consumer to run a separate workflow is not a configuration seam, so this makes the primary pre-PR command unable to honor the consumer's required process; add a consumer-rule/config resolution path rather than declaring it unsupported.

ℹ️ 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]

Claude finished @kyle-sexton's task in 2m 22s —— View job

---

PR Review — docs(session-flow): document override boundary for stage taxonomy and retro rubric

• Gather context and understand the request
• Read current diff against origin/main
• Review changed files
• Post review findings

---

This is a documentation-only patch across 5 files. No behavior changes. Reviewed at the current HEAD (63f3565), which includes the 923c489 wording fix for the pre-PR consumer-gates concern.

HOLD conditions — all resolved

Prior issue	Status
Version collision (0.10.2 conflict with main)	✅ Resolved — bumped to 0.10.3
Linkage overreach (#433 finding 2 untouched)	✅ Resolved — pre-pr.md override boundary added
Codex P2: consumer gates claimed as unsupported	✅ Resolved — 923c489 explicitly states the skeleton is fixed, gates are not

File-by-file notes

plugin.json — 0.10.2 → 0.10.3. Correct patch bump for a docs-only change. No collision with main.

CHANGELOG.md — 0.10.3 entry prepended correctly above 0.10.2. "No behavior change" noted. Minor under-specification: the entry names "the stage taxonomy (workflow)" as the workflow-skill deliverable, which is accurate for workflow/SKILL.md, but the pre-PR sequence skeleton boundary (skills/workflow/context/pre-pr.md) — added in f6dc1ad and 923c489 after the CHANGELOG entry was first written — isn't mentioned. Both are under the workflow umbrella so this is a nit, not a factual error; see below.

skills/workflow/SKILL.md L47–50 — "Override boundary." matches the existing label pattern (Stage execution., Artifact location., Quality gates.). The distinction between fixed (the stage set) and adaptable (execution routes, gate commands, review criteria) is correct and complete. Clean.

skills/retro/SKILL.md L105–108 — New bullet fits the "What this skill does NOT do" pattern. Placement in SKILL.md rather than any mode context file is correct — the five dimensions surface across all four mode context files. The "What adapts / never the fixed part" structure mirrors the workflow/SKILL.md framing consistently. Minor readability nit at L108; see below.

skills/workflow/context/pre-pr.md L31–38 — The revised boundary note correctly addresses the Codex P2: "the fixed part is the skeleton, not the gates" draws the right line. "applied at the matching step (the intro above)" points to line 4 ("Use the consuming repo's own commands and review criteria at each gate."), which is unambiguous in a 38-line file. The closing sentence — "a consumer whose required ordering genuinely differs runs that structure as its own documented workflow, separately from this skill" — is accurate and terminates the architectural decline correctly.

Checklist (REVIEW.md)

Check	Result
Object-level authorization	N/A — docs only
Tenant-scoped data access	N/A
Secrets/credentials in source	None
Injection via string concatenation	N/A
Atomicity across related writes	N/A — no state writes
Audit logging for high-risk actions	N/A

Nits (2)

🟡 retro/SKILL.md L108: "never the dimension set by editing the plugin" — flagged in both prior reviews. "dimension set" can momentarily parse as a compound noun ("the dimension-set of the plugin") before the reader resolves "by editing the plugin" as the adverbial. The workflow/SKILL.md parallel is cleaner ("never by editing the plugin"). "never the dimensions themselves" would resolve the ambiguity; not blocking.

🟡 CHANGELOG.md L7: The entry says "the stage taxonomy (workflow)" as the workflow deliverable, but the pre-PR sequence skeleton boundary — added in subsequent commits — is absent from the changelog prose. Both touch the workflow skill so the omission isn't wrong, but a reader diffing 0.10.3 who looks at pre-pr.md won't find it in the CHANGELOG. Mention of "the pre-PR sequence skeleton (pre-pr.md)" alongside the stage taxonomy would keep the entry complete; not blocking. Fix this →

Verdict

No correctness issues, no security issues. All prior HOLD conditions lifted. The three boundary statements are accurate, architecturally consistent with each other, and correctly placed in their respective files. The Codex P2 is substantively addressed. PR is clean.

[claude]

Claude finished @kyle-sexton's task in 1m 22s —— View job

---

PR Review — docs(session-flow): document override boundary for stage taxonomy and retro rubric

• Gather context and understand the request
• Read current diff against origin/main
• Review changed files at HEAD (f32876a)
• Post review findings

---

This review covers the final commit f32876a ("tighten retro override-boundary wording, complete changelog"), which directly addresses the two nits flagged across both prior reviews.

What changed in f32876a

skills/retro/SKILL.md L108 — the garden-path reading ("dimension set" scanning as a compound noun) is gone. "never the dimensions themselves" is clean, unambiguous, and matches the parallel structure in workflow/SKILL.md ("never by editing the plugin"). Both prior reviews flagged this; it's resolved.

CHANGELOG.md L7–8 — "the pre-PR sequence skeleton (workflow)" is now alongside "the stage taxonomy" in the 0.10.3 entry. The prior review noted that a reader diffing 0.10.3 would not find pre-pr.md in the changelog; that gap is closed.

Prior nit status

Nit	Status
retro/SKILL.md L108: "dimension set" garden-path ambiguity	✅ Resolved — "the dimensions themselves"
CHANGELOG.md L7: pre-PR sequence skeleton not mentioned	✅ Resolved — added to 0.10.3 entry

One minor observation (non-blocking)

🟡 CHANGELOG.md L7: the constructed phrase is "The stage taxonomy and the pre-PR sequence skeleton (workflow) and the five scoring dimensions (retro)". A reader might momentarily wonder whether "(workflow)" qualifies only "the pre-PR sequence skeleton" or both it and "the stage taxonomy". Removing the second "the" — "the stage taxonomy and pre-PR sequence skeleton (workflow)" — would bind the parenthetical cleanly to both. This is a cosmetic read-once nit; not blocking.

Checklist

Check	Result
Object-level authorization	N/A — docs only
Tenant-scoped data access	N/A
Secrets/credentials in source	None
Injection via string concatenation	N/A
Atomicity across related writes	N/A — no state writes
Audit logging for high-risk actions	N/A

Verdict

All prior HOLD conditions and nits are resolved. The two deliverables in f32876a are exactly right: the wording fix removes the ambiguity without touching surrounding text, and the changelog update completes the audit trail for 0.10.3. PR is clean and ready to merge.

[kyle-sexton]

[claude]

Claude finished @kyle-sexton's task in 1m 22s —— View job

---

PR Review — docs(session-flow): document override boundary for stage taxonomy and retro rubric

• Gather context and understand the request
• Read current diff against origin/main (post-merge)
• Review changed files at HEAD (69ad51d)
• Post review findings

---

The latest commit (69ad51d) is a sync merge from main (1a869ae — chore: sync standards components). It introduces no changes to the PR's five files. The diff against origin/main is identical to what the prior review (f32876a) assessed: 29 additions, 1 deletion, docs-only.

Status of all prior findings

Issue	Status
Version collision (0.10.2 conflict with main)	✅ Resolved — 0.10.3
Linkage overreach (#433 finding 2 untouched)	✅ Resolved — pre-pr.md boundary added
Codex P2: consumer gates claimed as unsupported	✅ Resolved — skeleton vs. gates distinction explicit
Nit: retro/SKILL.md L108 "dimension set" garden-path parse	✅ Resolved — "never the dimensions themselves"
Nit: CHANGELOG.md pre-PR skeleton not mentioned	✅ Resolved — added to 0.10.3 entry

File-by-file (current HEAD)

plugin.json — 0.10.2 → 0.10.3. Correct patch bump for docs-only. No collision with main (0.10.2 is already on main via #469; this branch is cleanly ahead at 0.10.3).

CHANGELOG.md — 0.10.3 entry prepended above 0.10.2. Names all three boundary additions: stage taxonomy (workflow), pre-PR sequence skeleton (workflow), and five scoring dimensions (retro). "No behavior change" correctly noted.

skills/workflow/SKILL.md L47–50 — "Override boundary." matches label pattern of existing Consumer conventions bullets. Fixed/adaptable split is accurate and complete.

skills/retro/SKILL.md L105–108 — Fits the "What this skill does NOT do" pattern. "Never the dimensions themselves" is now unambiguous (nit resolved). Placement in SKILL.md is correct — the five dimensions surface across all four mode context files.

skills/workflow/context/pre-pr.md L31–38 — Override boundary note correctly distinguishes the fixed skeleton (steps + order) from the adaptable gates (commands, review criteria, mandatory CI gates). The Codex P2 concern is directly answered: "the fixed part is the skeleton, not the gates."

Verdict

No correctness issues, no security issues. The sync merge from main is clean. All prior HOLD conditions, nits, and review-thread items are resolved. PR is ready to merge.

[claude]

Claude finished @kyle-sexton's task in 1m 34s —— View job

---

PR Review — docs(session-flow): document override boundary for stage taxonomy and retro rubric

• Gather context and understand the request
• Read current diff against origin/main
• Review changed files at HEAD (fa2655d)
• Post review findings

---

This review covers HEAD fa2655d, which is a sync merge from main (3a87f5f — feat(ci): default-on security review). The merge brought in unrelated changes across other plugins (discovery, planning, review, source-control) and CI; it touches zero session-flow files. The effective diff against origin/main for this PR's five files is identical to what the prior review (69ad51d) assessed.

Merge integrity

Main is at session-flow 0.10.2; this branch is at 0.10.3. No version collision introduced by the merge. The sync is clean.

Prior finding status

Finding	Status
Version collision (0.10.2 conflict with main)	✅ Resolved — 0.10.3
Linkage overreach (#433 finding 2 untouched)	✅ Resolved — pre-pr.md override boundary added
Codex P2: consumer gates claimed as unsupported	✅ Resolved — skeleton vs. gates distinction explicit
Nit: retro/SKILL.md L108 "dimension set" garden-path ambiguity	✅ Resolved — "never the dimensions themselves"
Nit: CHANGELOG.md pre-PR skeleton not mentioned	✅ Resolved — added to 0.10.3 entry
Nit: CHANGELOG.md L7 "(workflow)" parenthetical binding ambiguity (from prior review)	✅ Acceptable as-is — both items are under the workflow umbrella; not a correctness issue

File-by-file (current HEAD)

plugin.json — 0.10.2 → 0.10.3. Correct patch bump for docs-only. No collision with main.

CHANGELOG.md — 0.10.3 entry prepended correctly above 0.10.2. Names all three boundaries (stage taxonomy, pre-PR sequence skeleton, five scoring dimensions). "No behavior change" correctly noted.

skills/workflow/SKILL.md L47–50 — "Override boundary." matches the label pattern of existing Consumer conventions bullets. Fixed/adaptable split is accurate and complete.

skills/retro/SKILL.md L105–108 — Fits the "What this skill does NOT do" pattern. "Never the dimensions themselves" is unambiguous. Placement in SKILL.md is correct — the five dimensions surface across all four mode context files.

skills/workflow/context/pre-pr.md L31–38 — Override boundary note correctly scopes fixed plugin identity to the sequence skeleton (steps + order), while making explicit that a consumer's commands, review criteria, and mandatory gates are honored at the matching step and enforced independently by CI/branch protection.

Checklist (REVIEW.md)

Check	Result
Object-level authorization	N/A — docs only
Tenant-scoped data access	N/A
Secrets/credentials in source	None
Injection via string concatenation	N/A
Atomicity across related writes	N/A — no state writes
Audit logging for high-risk actions	N/A

Verdict

No correctness issues, no security issues. The sync merge is clean; no session-flow files were touched by it. All prior HOLD conditions and nits are resolved. PR is ready to merge.

[claude]

Claude finished @kyle-sexton's task in 1m 19s —— View job

---

Security Review — docs(session-flow): document override boundary for stage taxonomy and retro rubric

• Gather context and understand the request
• Read PR diff
• Review changed files for security issues
• Post findings

---

Scope: 5 files, 29 additions, 1 deletion — documentation only.

Findings

No security issues found.

Rationale

All five changed files are Markdown that serves as AI model instructions. The patch surface contains no security-relevant material:

File	Change	Security surface
plugin.json	Version string 0.10.2 → 0.10.3	None — metadata only
CHANGELOG.md	12-line prose entry	None — no URLs, no code
skills/workflow/SKILL.md	4-line "Override boundary" bullet	None — narrows claimed capability
skills/retro/SKILL.md	4-line "What this skill does NOT do" bullet	None — narrows claimed capability
skills/workflow/context/pre-pr.md	8-line override boundary note	None — narrows claimed capability

Specific checks:

• Prompt injection — the additions are defensive: they constrain what the skill claims to do rather than expanding it. No adversarial or capability-widening content.
• Secret / credential exposure — none in any changed file.
• URL / SSRF surface — no URLs added.
• Shell / command injection — no executable code or tool invocations introduced.
• GitHub Actions — no .github/workflows files touched; no permissions: or action-pin changes.
• Supply-chain / dependency pins — no dependencies added or loosened.
• Plugin isolation — no changes to ${CLAUDE_PLUGIN_ROOT} / ${CLAUDE_PLUGIN_DATA} path references; plugin boundary unchanged.
• Data egress — no new network calls, MCP endpoints, or external tool references.
• Config seam widening — the explicit conclusion of the patch is the opposite: seams that do not exist are now documented as absent, reducing the risk of consumer misuse through undocumented extension points.

PR is clean from a security standpoint.

[kyle-sexton]

Superseded by #746.

This branch's tip (fix/433-session-flow-override-boundary) carries an unsigned merge commit (92ef6cf9, verification reason unknown_key) that the org's required-signatures ruleset permanently blocks — the #631 known-issue class. Per the sanctioned playbook (precedent: #682 superseding #658), rewriting this branch's history is not the fix; instead #746 materializes this PR's net content vs main (verified byte-identical) as a single signed commit on a fresh branch off current main.

Disabling auto-merge and closing in favor of #746.