feat(session-flow): suggest /export at session-end moments (0.34.0)

[kyle-sexton]

No linked issue

Summary

Closes the one durability gap the session-flow artifact layer leaves open: the conversation itself, whose transcript is retention-swept (cleanupPeriodDays, default 30 days) and has no durable home. Three skills now offer a presence-gated, one-line suggestion to run the built-in /export at their natural decision points. The interview Brief that locked this contract was committed, review-hardened (two automated review rounds), then pruned per the topic-docs convention; it remains in this branch's history.

Fix

• clean-stop: the durability sweep names the conversation as a machine-local, non-durable item and offers /export <memory_dir>/exports/<TS>-<topic>.txt, with an off-machine caveat for its machine-loss case (the export destination dies with the disk too).
• handoff: the prompt-only path (the one case with zero file artifact) gains the same offer; the transcript is that handoff's only record.
• retro: offers the export after the chain-coverage report; a session worth retrospecting is worth keeping.
• All three are offer-only (nothing invokes the built-in, which has no headless form; nothing records whether the user ran it), phrased with the native-references presence gate (never asserting the command exists), and require the memory root's self-ignore guard before the path is offered.
• topic-docs convention 2.5.2: exports joins the reserved first-level names under the memory root (README tier row, reserved list, implementers table, schema memory_dir description, changelog), preventing topic-slug collisions.
• Native-surfaces registry: new export (builtin-command) × session-flow:clean-stop row, verdict complementary, with live-probe evidence; canonical-pairs candidate added; docs/NATIVE-SURFACES.md regenerated (9 rows).
• session-flow 0.33.0 with a changelog entry carrying the deferred questions (sharing/redaction; a SessionEnd-hook lane for cloud sessions).
• Final commit prunes docs/topics/export-session-flow/ per the contract-slice convention.

Verification

• scripts/check-contract-slice-prune.sh --check-diff origin/main exit 0 on the final change set (the gate that failed on the Brief-only commits).
• overlap.py generate wrote the 9-row view; overlap.py self-check exit 0 (one pre-existing advisory about 2.1.232-era extraction rows, untouched by this change).
• markdownlint-cli2 0 issues across all 7 changed markdown files; typos clean; both JSON files parse; plugin.json validates against the manifest schema; no em dashes introduced in any SKILL.md.
• All four Codex review findings from the Brief round were verified against the cited conventions, fixed, replied to, and resolved.

Related

N/A

[claude]

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

---

Claude finished the code review

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:code-review skill per custom instructions
• Verify cross-references and claims against the actual codebase
• Post inline findings (none warranted — see below)
• Final summary

Review scope

Single file, docs-only: docs/topics/export-session-flow/PLAN.md (new, +56/-0) — the ## Brief section of a docs/topics/ planning contract (per plugins/planning/reference/topic-docs.md), with ## Plan intentionally left empty for /planning:plan. No code, no automation, no runtime behavior in this diff.

What I checked

Beyond reading the Brief itself, I cross-checked its factual claims against the repo it describes, since this document becomes a binding contract for a later implementation PR:

• plugins/session-flow/skills/orient/SKILL.md does state the "built-ins are not Skill-invocable" doctrine the Constraints section cites (line 18) — confirmed at SKILL.md#L32-L33.
• reconcile's "never deep-parse the sibling JSONL" claim (line 19) is accurate — confirmed at reconcile/SKILL.md#L150.
• All three target files named in Acceptance Criteria (clean-stop, handoff, retro SKILL.md) exist under plugins/session-flow/skills/.
• .work/ is in fact self-gitignored at the repo root (.gitignore line "Topic memory tier — never committed"), backing the "exports cannot reach commits" claim (line 9).
• The native-overlap registry (docs/native-surfaces/records.json) currently has no /export row, matching the constraint that this row is "owed before skill edits merge" (line 24).
• The arbiter: USER-RESERVED / arbiter: implementation vocabulary in Deferred Questions matches precedent used in sibling docs/topics/*/PLAN.md files (interview-batch-rounds, shadowed-skill-renames).

No internal contradictions, no broken references, and no acceptance criterion that conflicts with another. I did not independently re-run the check-open-questions.sh gate or markdownlint/typos claimed in the PR's Verification section (the ledger file they'd need is an untracked .work/ artifact not in this diff) — those are the author's claimed verification, not something I re-verified.

Findings

None. This is a well-grounded, internally consistent contract-lock document with no meaningful code-review surface — the high-signal bar for this lane (correctness bugs, broken cross-references, contradictory constraints) turned up nothing to flag.
· branch claude/export-session-flow-discussion-u790a7

[github-actions]

Claude has reviewed this PR 4 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ec2684675b

ℹ️ 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 4m 2s —— View job

---

Claude finished the code review

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:code-review skill per custom instructions
• Verify Codex's findings against the actual codebase
• Post inline findings (none warranted — see below)
• Final summary

Review scope

This push (ec26846 → 0341f09) is a follow-up to the earlier lock commit, addressing all four chatgpt-codex-connector findings from the prior round. Still a single docs-only file: docs/topics/export-session-flow/PLAN.md. No code, no automation, no runtime behavior.

What changed and what I checked

I diffed ec26846..0341f09 on the file and cross-checked each of Codex's four findings against the current text and the source docs they cite:

1. [P1] Off-machine preservation for clean-stop — AC line 29 now requires clean-stop's suggestion variant to note the destination is machine-local and recommend an off-machine copy. Confirmed against plugins/session-flow/skills/clean-stop/SKILL.md (lines 14–27) that "the machine may disappear" is clean-stop's sole documented trigger, so the new note's premise always holds when clean-stop runs — reasonable given the Brief's constraint that this feature stays suggestion-only (no automation, nothing verified per line 9); an enforced off-machine copy would contradict that constraint.
2. [P1] Self-ignore guard before suggesting export — new Constraints line 21 and AC line 35 require the guard to run before the export path is offered. Wording matches docs/conventions/topic-docs/README.md lines 397–404 (self-ignore guard: verify/create .gitignore with * at the resolved memory root) — accurately grounded.
3. [P2] Reserve the exports concern directory — new Constraints line 22 and AC line 34 add exports to the reserved first-level names and correspondingly relax the "no file outside plugins/session-flow/" scope restriction (line 37) to permit that convention edit. Confirmed the current reserved list (docs/conventions/topic-docs/README.md lines 457–458) is exactly handoffs, reviews, running-retros, overengineering — exports is indeed absent today, so this constraint is accurate and the scope carve-out is now internally consistent.
4. [P2] Deferred-question arbiter format — the two remaining entries now lead with Q2 — / Q3 — and keep arbiter: USER-RESERVED, matching the format in plugins/planning/skills/interview/context/loop.md (lines 215, 281, 309). The third former entry (wording/placement of suggestion text) was moved out of Deferred questions into Captured assumptions with an explicit "not a deferred decision" note (line 43) rather than being force-fit into the Q<N>/arbiter shape — a reasonable resolution since it was never a decision needing an arbiter.

I did not independently re-run markdownlint-cli2 or typos (neither tool is available in this sandbox, and installing them requires network access this lane doesn't have) — that verification remains author-claimed, as noted in the prior review round.

Findings

None. All four prior findings are addressed with accurate, cross-checked grounding, and I found no new internal contradictions or broken references introduced by this revision.
· branch claude/export-session-flow-discussion-u790a7

[claude]

Claude finished @kyle-sexton's task in 3m 23s —— View job

---

Claude finished the code review

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:code-review skill per custom instructions
• Verify findings against the actual codebase
• Post inline findings
• Final summary

Review scope

This push (0341f09 → 697598f) adds the actual implementation behind the previously-reviewed Brief: 11 files, +105/-9, across docs/, plugins/claude-ops/, and plugins/session-flow/. Security-lane concerns are out of scope here (claude-security-review.yml exists in this repo), so this review is correctness/maintainability only.

Findings

1. [P1] plugins/session-flow/skills/handoff/SKILL.md — the diff deletes the prompt-only path's Redaction pass swept the prompt (secrets/tokens/credentials/PII replaced with shape markers) checklist item and replaces it in place with the new export-suggestion bullet, instead of adding the new bullet alongside it. Confirmed via git diff origin/main...HEAD -- plugins/session-flow/skills/handoff/SKILL.md: it's a single hunk that removes exactly that line. The sibling full-file+prompt path checklist item (line 208, "Redaction pass swept the file AND the prompt…") is untouched, and the underlying mandate still lives in reference/save-point.md ("Redaction pass — mandatory on BOTH paths"), so behavior may be unaffected if the engine doc is followed regardless — but this file's own instruction is "Tick each item in the response so the user can verify the exit shape. Missing any tick = handoff incomplete," and that self-check for redaction on the prompt-only path is now gone. Nothing in the PR description, session-flow CHANGELOG, or the export-session-flow Brief calls out an intentional removal of a redaction checklist item — this looks like an accidental overwrite from editing the checklist in place. Posted inline at handoff/SKILL.md:242 with a suggested fix.

What I checked and found consistent

• docs/NATIVE-SURFACES.md and docs/native-surfaces/records.json: the new export × session-flow:clean-stop row is internally consistent (verdict, evidence, observation, recheck trigger all agree), and the summary table count (Built-in CLI commands | 1 | 0 | complementary 1) matches the single new row added.
• docs/conventions/topic-docs/README.md, CHANGELOG.md, topic-docs.schema.json: the exports reserved-name addition is applied consistently across the tier table, the reserved-names spec list, the schema description, and the Implementers table — no location was missed.
• plugins/session-flow/.claude-plugin/plugin.json version bump (0.33.0 → 0.34.0) matches the new ## [0.34.0] CHANGELOG entry.
• The three skill-suggestion additions (clean-stop, handoff's full-file path is unaffected, retro) are offer-only, presence-gated, and require the self-ignore guard before offering the path — consistent with the four Codex findings from the Brief round that the author states were addressed, and I didn't find a case where the offer bypasses the guard.
• I did not independently re-run markdownlint-cli2, typos, overlap.py self-check, or the JSON-manifest-schema validation claimed in the PR's Verification section — those remain author-claimed. I did spot-check that the two touched .json files (records.json, canonical-pairs.json) are structurally well-formed by inspection of the diff context (bracket/brace balance), but did not run a parser.
  · branch claude/export-session-flow-discussion-u790a7

[claude]

Claude finished @kyle-sexton's task in 51s —— View job

---

Security review complete

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:security-review skill per custom instructions
• Post findings
• Final summary

Scope

Reviewed the full diff (git diff origin/main...HEAD, 11 files, +105/-9) against HEAD 697598f. All eleven changed files are docs/config/skill-instruction content: docs/NATIVE-SURFACES.md, docs/conventions/topic-docs/{CHANGELOG.md,README.md,topic-docs.schema.json}, docs/native-surfaces/records.json, plugins/claude-ops/skills/audit-native-overlap/reference/canonical-pairs.json, plugins/session-flow/.claude-plugin/plugin.json (version bump only), plugins/session-flow/CHANGELOG.md, and plugins/session-flow/skills/{clean-stop,handoff,retro}/SKILL.md. No source code, no GitHub Actions workflow files, no scripts.

Skip-gate determination

Per the /review:security-review skip gate, this PR has no security-relevant surface:

• No permissions: changes, no workflow files, no CI config.
• No new automation that executes commands, writes files, or handles secrets/tokens/credentials. The three SKILL.md edits are natural-language instructions that offer a one-line /export <memory_dir>/exports/<TS>-<topic>.txt suggestion for the user to type; nothing in this diff invokes /export programmatically, constructs a shell command from untrusted input, or executes anything — the skill text explicitly states "Offer only, never run."
• The new destination convention is gated behind the existing self-ignore guard (.gitignore with * at the memory root) before the path is ever offered, consistent with how the repo already treats .work/ as non-durable, non-committed scratch space.
• plugin.json change is a version bump only (0.33.0 → 0.34.0); no manifest permission or capability changes.
• JSON edits (records.json, canonical-pairs.json, topic-docs.schema.json) are additive data/documentation entries, not executable config.

No injection surfaces, no authz/access-control changes, no credential handling, no supply-chain/pin changes. Nothing to report.

Result

No security findings. This PR is out of scope for the security-review lane's high-signal bar — docs-only, offer-only feature with no runtime or automated execution path.
· branch claude/export-session-flow-discussion-u790a7

[github-actions]

Last security-reviewed head: 7122ec52ceff4a0e63e3f62148150d1257b0e5eb. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[claude]

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

---

Claude finished the security review

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:security-review skill per custom instructions
• Verify findings against the actual codebase
• Post inline findings
• Final summary

Review scope

Per /review:security-review's criteria, reviewed all 13 files changed in this PR (docs-only + SKILL.md prompt files; no application code, no GitHub Actions workflows). Focus: logic flaws, trust-boundary gaps, and unsafe handling of secrets/tokens/credentials/PII — the lane's stated high-signal bar.

Findings

[IMPORTANT] handoff/SKILL.md: prompt-only path lost its redaction-pass audit checklist item — posted inline at handoff/SKILL.md#L242-L247.

Diffing against origin/main, the prompt-only checklist's Redaction pass swept the prompt (secrets/tokens/credentials/PII replaced with shape markers) tick was removed and replaced by the new export-offer tick, rather than the new item being added alongside it. The full-file path still ticks redaction at line 208, so the prompt-only path — the one path whose emitted resume prompt is the only artifact, copy/pasted by the operator into a new session and potentially onto other machines — is now the only path with no local audit checkbox for redaction. This skill explicitly frames the checklist as the enforcement surface ("Tick each item in the response so the user can verify the exit shape. Missing any tick = handoff incomplete," line 172). The shared engine doc (reference/save-point.md) still describes the redaction pass as mandatory on both paths, so this looks like an accidental collateral edit rather than an intended behavior change — but removing the operator-visible tick removes the auditable guarantee that a secret/token/credential/PII sweep actually ran before the prompt was emitted. Recommend restoring the redaction-pass tick as its own line alongside the new export-offer tick.

Everything else in the diff (the clean-stop and retro additions, the exports reserved-name convention change, the native-surfaces registry rows, and the version/changelog bumps) is additive, presence-gated, offer-only (never auto-invokes the built-in /export), and consistently requires the memory-root self-ignore guard before any export path is offered — no other security-relevant issues found.
· branch claude/export-session-flow-discussion-u790a7

[claude]

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

---

Claude finished the code review

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:code-review skill per custom instructions
• Verify findings against the actual codebase
• Post inline findings (none warranted — see below)
• Final summary

Review scope

This push (697598f → 7122ec5) is a follow-up to the previously-reviewed implementation, adding two commits: a1ea8f5 (claude-ops version bump for the canonical-pairs.json change) and 7122ec5 (fix for the redaction-checklist finding from the prior review round). Full PR diff against origin/main is unchanged in scope from the last review: 13 files, +115/-9, across docs/, plugins/claude-ops/, and plugins/session-flow/.

What I checked

The prior P1 finding is fixed correctly. Two earlier review rounds (mine and Codex's, at 697598f) flagged that plugins/session-flow/skills/handoff/SKILL.md's prompt-only checklist had its Redaction pass swept the prompt (...) bullet overwritten by the new export-offer bullet instead of gaining it alongside. Commit 7122ec5 restores the deleted bullet as handoff/SKILL.md:242, with the export-offer bullet immediately following at line 243. Both are now independently tickable, matching the full-file path's equivalent line at line 208. Confirmed via git diff a1ea8f5..7122ec5 — a single-line insertion, no other changes.

Re-verified the rest of the diff for regressions or new issues:

• plugins/session-flow/skills/{clean-stop,handoff,retro}/SKILL.md: all three export-offer additions are self-consistent — same "resolves in your session" presence-gate phrasing, same self-ignore-guard-before-offer ordering, same offer-only/no-invoke framing, each tailored correctly to its skill's own trigger (durability sweep, prompt-only close, post-chain-coverage report respectively).
• docs/conventions/topic-docs/{README.md,topic-docs.schema.json,CHANGELOG.md}: the exports reserved-name addition is threaded through all four locations (tier table, reserved-names list, Implementers table, schema description) — no location missed, consistent with how overengineering was added previously.
• docs/NATIVE-SURFACES.md / docs/native-surfaces/records.json: the new export × session-flow:clean-stop row and the generated markdown table are consistent with each other (verdict, evidence, observation, recheck trigger all agree), and the summary count (Built-in CLI commands | 1 | 0 | complementary 1) matches.
• plugins/claude-ops/skills/audit-native-overlap/reference/canonical-pairs.json + plugins/claude-ops/CHANGELOG.md + plugins/claude-ops/.claude-plugin/plugin.json: the candidate-pair addition and version bump (0.38.3 → 0.38.4) are consistent with each other.
• plugins/session-flow/.claude-plugin/plugin.json (0.33.0 → 0.34.0) matches the new ## [0.34.0] CHANGELOG entry and the PR title.
• Checked for em dashes newly introduced in the touched SKILL.md files specifically (per .claude/rules/vendor-docs-are-not-style.md and the PR's own verification claim) — none found in the added lines. docs/NATIVE-SURFACES.md/CHANGELOG prose does use em dashes, consistent with pre-existing style in those non-instruction-surface docs, so not a violation of that rule's scope (SKILL.md, plugin READMEs, AGENTS.md, CLAUDE.md, .claude/rules/**).

I did not independently re-run markdownlint-cli2, typos, overlap.py self-check, or JSON-schema validation (markdownlint-cli2 is not present in this sandbox, network install isn't available) — those remain author-claimed, as in the prior review round.

Findings

None. The previously-flagged P1 is correctly resolved, and the two new commits introduce no regressions or new issues.
· branch claude/export-session-flow-discussion-u790a7

[claude]

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

---

Security review complete

• Gather context (PR diff, CLAUDE.md, changed files)
• Invoke /review:security-review skill per custom instructions
• Post findings
• Final summary

Scope

Reviewed the full diff (git diff origin/main...HEAD, 13 files, +115/-9) against HEAD 7122ec5. This head adds two commits on top of the previously-reviewed 697598f:

• a1ea8f5 — version bump + changelog entry for plugins/claude-ops (0.38.3 → 0.38.4), documenting the export × session-flow:clean-stop candidate pair addition to canonical-pairs.json.
• 7122ec5 — restores the plugins/session-flow/skills/handoff/SKILL.md prompt-only path's "Redaction pass swept the prompt (secrets/tokens/credentials/PII replaced with shape markers)" checklist bullet, which the earlier findings from this lane's own prior run (and Codex-adjacent duplicate) had flagged as accidentally overwritten by the new export-offer bullet. Confirmed both bullets now coexist as independent checklist items, matching the full-file path's equivalent line.

All 13 changed files remain docs/config/skill-instruction content: docs/NATIVE-SURFACES.md, docs/conventions/topic-docs/{CHANGELOG.md,README.md,topic-docs.schema.json}, docs/native-surfaces/records.json, plugins/claude-ops/{.claude-plugin/plugin.json,CHANGELOG.md}, plugins/claude-ops/skills/audit-native-overlap/reference/canonical-pairs.json, plugins/session-flow/{.claude-plugin/plugin.json,CHANGELOG.md}, plugins/session-flow/skills/{clean-stop,handoff,retro}/SKILL.md. No source code, no GitHub Actions workflow files, no scripts.

Skip-gate determination

Per the /review:security-review skip gate, this PR has no security-relevant surface:

• No permissions: changes, no workflow files, no CI config — git diff origin/main...HEAD -- '.github/**' is empty.
• No new automation that executes commands, writes files, or handles secrets/tokens/credentials. The three SKILL.md edits are natural-language instructions offering a one-line /export <memory_dir>/exports/<TS>-<topic>.txt suggestion for the user to type; nothing invokes /export programmatically or constructs a shell command from untrusted input.
• The claude-ops commit (a1ea8f5) is a version bump + changelog prose entry only — no manifest permission or capability changes.
• The handoff redaction-bullet restore (7122ec5) strengthens the security posture (restores an operator-visible audit checkpoint for secret/token/PII redaction on the prompt-only handoff path) rather than introducing any new risk.
• JSON edits (records.json, canonical-pairs.json, topic-docs.schema.json) remain additive data/documentation entries, not executable config.

No injection surfaces, no authz/access-control changes, no credential handling, no supply-chain/pin changes introduced by this push.

Result

No security findings. This PR remains out of scope for the security-review lane's high-signal bar — docs-only, offer-only feature with no runtime or automated execution path. The redaction-checklist regression flagged in the prior code-review pass on this branch has been fixed in 7122ec5.
· branch claude/export-session-flow-discussion-u790a7