fix(ce-commit-push-pr): construct retrospective stacks

[tmchow]

Summary

Stack intent now works for completed work, not only branches already registered with gh stack. When no topology exists, ce-commit-push-pr derives the smallest useful linear dependency layers and constructs them before the ordinary single-branch commit flow. It proceeds when one safe topology is clear and asks before ambiguous review boundaries, hunk-level splits, or published-history rewrites.

Existing managed-stack submission and the ce-babysit-pr handoff remain unchanged.

Design decisions

• Inspect the complete committed and working change set; do not impose a numeric layer cap.
• Keep automatic splits to whole-file groups or existing commit boundaries.
• Reuse the existing fresh-base safeguards for the bottom layer, while every upstack branch starts from its immediate parent.
• Verify manager order and complete top-layer content before submission.

Validation

• bun run test — 2,908 passed, 0 failed.
• bun run release:validate — release metadata is in sync.
• bun run plugin:validate — strict marketplace and plugin validation passed.
• Four dry-run behavioral evals covered a clear two-layer split, ambiguous sibling commits, published mixed history, and a justified four-layer stack.
• An isolated local clone completed gh stack init → bottom commit → gh stack add → top commit → gh stack view --json without pushing.

New concepts

Retrospective stack construction

A PR stack can be designed after implementation by partitioning completed work into dependency-ordered review units. The bottom PR provides a coherent foundation; each later PR adds one independently reviewable outcome on its immediate parent.

This skill derives boundaries from the complete change set rather than a fixed PR count. It does not use retrospective stacking when the work is one logical change or when only artificial, hunk-level slices are possible.

Security Disclosure

This changes skill guidance for local git and gh stack mutations. Automatic construction is limited to safe local topology; published-history rewrites require explicit confirmation. No credential, permission, dependency, or executable-code changes.

Agent Disclosure

• Model: Codex · GPT-5

[cursor]

PR Summary

Medium Risk
Changes agent guidance for local git branch/commit/rewrite operations and stack submission; safeguards require confirmation for ambiguous splits and published-history rewrites, but mistaken automation could still mutate local history.

Overview
/ce-commit-push-pr stack mode now covers completed work on a single branch, not only repos that already have a gh stack topology. When stack intent is on and no managed stack exists, the skill derives the smallest useful linear review layers (whole-file groups or existing commit boundaries), builds them with gh stack init / gh stack add before ordinary Step 3, and defers gh stack submit and per-PR metadata to Step 5 only.

references/stack-submit.md adds a full Retrospective construction section: bottom-layer base rules (default branch vs feature branch, recovery refs, stash/restore for uncommitted splits), confirmation gates for ambiguous topologies, hunk splits, and published-history rewrites (mode:pipeline surfaces residuals instead of guessing), plus post-submit gh pr edit "<pr-url>" per new PR using PR-mode description composition. pr_teaching_archive on blocks submit until the user reruns with archive:off.

SKILL.md, docs, and pr-description-writing.md are aligned with the two-phase flow (construction vs submit), Step 3 skip when layers are already committed, and removal of per-layer base:<ref> for description base resolution. Contract tests in commit-push-pr-contract.test.ts are expanded to lock in the new stack behavior.

^{Reviewed by Cursor Bugbot for commit 195b100. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 13a8b1cb6b

ℹ️ 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: 2018e86363

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

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e7c4691. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e7c4691a75

ℹ️ 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: cf78c27b86

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