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

[kyle-sexton]

Plugin: session-flow · Categories: hardcoded opinion (1), externalization gap (2) — low/borderline
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• plugins/session-flow/skills/workflow/context/steps.md:1-92 — fixed 8-stage list
• plugins/session-flow/skills/workflow/context/pre-pr.md:13-15 — "Simplify" + "review the simplify diff" pass presented as the universal pre-PR sequence (mirrors the house /simplify workflow)
• plugins/session-flow/skills/retro/context/session.md:229-257 — fixed 5-dimension scoring rubric with fixed anchors (:233-245)

Why flagged

Stage taxonomy and score rubric are baked doctrine presented as the universal default; neither skill states "to use your own stages/dimensions, do X". Heavily mitigated — stage execution routes to the consumer's own skills and degrades inline (workflow/SKILL.md:30-34), gate commands and review criteria come from the consumer, cross-plugin refs are correctly gated. The residual fixed structure is defensible as plugin identity but the non-override is undocumented, against the extensibility contract's "document how a consumer overrides without editing the plugin".

Fix direction

Add one line in workflow's "Consumer conventions" and in retro pointing at the seam to supply their own stage set / scoring dimensions (tracked consumer-project file per extensibility seam 2) — even if the answer is "the taxonomy is fixed; only execution/criteria adapt", make the boundary explicit.

[kyle-sexton]

This was generated by AI during triage.

Triage → T2 planning complete · confidence: high (advisor-reviewed). Verified the status quo — fixed structure, adaptive execution/criteria — is the current behavior, so making the boundary explicit needs no product decision. Documentation-only. Labeling status: ready.

Plan — make the override boundary explicit (documentation only)

Behavioral contract

Zero behavior change. No override mechanism added; no fixed-vs-overridable decision made. The plugin's current behavior already IS the resolution: the stage taxonomy and retro rubric are fixed plugin identity (the "map"), while execution and gate/review criteria adapt to the consumer. #433's ask — "even if the answer is the taxonomy is fixed, make that boundary explicit" — is satisfied by stating the status quo where the structures are defined.

Verified: the plugin has no seam to swap the stage set or scoring dimensions. Only consumer-adaptation points are stage-execution routing (with inline degrade), artifact location, and quality-gate contents. The fixed 5-dimension schema is additionally load-bearing for cross-session score comparability (context/trends.md + the score-history table depend on it) — a positive reason it's fixed. No evidence anywhere the taxonomy/rubric were meant to be overridable ("workflow… defines the stages"; "this skill navigates; stages execute elsewhere").

Change 1 — skills/workflow/SKILL.md, Consumer conventions

Add a fourth bullet alongside Stage execution / Artifact location / Quality gates:

• Stage taxonomy is fixed (this skill's map). The stage set and its order — the numbered stages in context/steps.md, the optional contract stage, and the pre-PR gate sequence in context/pre-pr.md — are the map this skill provides, not a per-consumer list to re-shape. Only execution (Stage execution, above) and gate/review contents (Quality gates, above) adapt to the consuming repo; the taxonomy itself does not. A consumer running a genuinely different stage set does so through its own documented workflow, which this plugin already recognizes in place of this map — not by re-shaping the map through the seams above.

(Grounded: skills/retro/context/session.md Phase 2B already checks adherence against "the sibling workflow skill, or the consuming repo's own documented workflow if it defines one" — that is the real bring-your-own path, not the execution/gate seams.)

Change 2 — skills/retro/context/session.md, Session health score (Phase 5)

Add a boundary note where the dimension table + Scoring anchors are defined:

Fixed rubric. The five dimensions and their anchor bands are the rubric's identity, not consumer-tunable — the cross-session score history (${CLAUDE_PLUGIN_DATA}/scores/) and trends mode depend on a stable schema to stay comparable. What adapts to the consumer is the baseline each dimension scores against: convention/alignment compliance derives from the consuming repo's own instruction files (Phase 2), and Technical quality calibrates to the detected session type. The dimension set and anchor bands do not change per consumer.

Acceptance criteria

• No executable behavior changes: no new args/paths/scripts/routing; prose-only diff in the two files.
• The workflow bullet lands in Consumer conventions, names the fixed structure (steps.md stages + pre-pr.md gate order) AND its adaptive counterpart (execution + gate contents), and does NOT claim the execution/gate seams can reshape the stage set.
• The retro note lands at Phase 5, names the fixed structure (5 dimensions + anchor bands) AND its adaptive counterpart (per-consumer convention baseline + session-type calibration).
• Both statements read as documenting existing behavior — verifiable against current source with no code change.
• Voice matches surrounding style; no cross-file duplication.

Note: fix targets the current repo source; cached copy examined was 0.10.1.