Preserve: land/deploy pipeline design (pre/post wraps around land-and-deploy) - approved 2026-06-23, unbuilt

[mujtaba3B]

Preserving an approved-but-unbuilt design that was living untracked on one machine at spec/plans/land-deploy-pipeline.md. The local copy is being deleted now that it lives here, so this issue is the only copy.

Why it was never committed

The repo's convention is that a plan lands in the same commit as the code it designs (spec/plans/deploy-gate-and-eng-deploy-ceremony.md went in with 212a83e). Nothing this plan designs has landed, so it never rode in with anything, and it sat untracked from 2026-06-23 until now.

What is already superseded

PR #64 (v2.9.0, 2026-07-26) carved out and shipped one slice: the deploy gate (eng/hooks/scripts/deploy-gate.sh, wired at three PreToolUse matchers in eng/hooks/hooks.json) and the /eng:deploy ceremony, with its own narrower plan committed. Do NOT rebuild those from this document.

What is still unbuilt

Verified against eng/skills/ today: there is no pre-land-and-deploy and no post-land-and-deploy. Neither gate below exists. The three extracted concerns (Pencil demotion, deploy-convention audit, branch cleanup) have not moved. The companion spec named in the plan, mutwo-skills/spec/plans/closeout-reshape-and-repo-boundary.md, is tracked in that repo, so the mutwo half is safe.

Decision needed

Is this live backlog or abandoned? If live, the pre/post pipeline plus the Stop-gate enforcement is a real chunk of work and should be broken into issues. If abandoned, close this and the design is still recoverable from the history here.

---

Full plan, verbatim as of the deleted local copy (89 lines)

Land/deploy pipeline: gated pre/post wraps around land-and-deploy

Status: approved design (2026-06-23). Companion spec in mutwo-skills/spec/plans/closeout-reshape-and-repo-boundary.md (the mutwo-side half: boundary, close-out reshape, agent-files split).

Why

gstack's /land-and-deploy is not ours to edit, but we want guaranteed prep before it and reconcile after it, enforced (not relying on the agent remembering). This is also the home for the software/deploy concerns being extracted out of mutwo's close-out (release-docs, Pencil demotion of shipped mockups, branch cleanup, deploy-convention auditing): per the repo boundary, the software-development lifecycle is gstack-extensions' domain.

eng already owns the adjacent machinery: eng/hooks/scripts/ has land-deploy-sentinel.sh, ship-gate-sentinel.sh, merge-clearance.sh, pr-merge-gate.sh. The pipeline builds on these rather than inventing new detection.

The pipeline

pre-land-and-deploy   ->   land-and-deploy (gstack, GATED)   ->   post-land-and-deploy
  (eng, ours)              (untouched)                             (eng, ours)

pre-land-and-deploy (eng skill)

Runs before the deploy. Steps:

1. Thin inventory: HEAD, the staged/working diff. Only what the prep needs.
2. Agent-files refresh (cross-repo, optional): a thin wrapper calls mutwo's /agent-files-refresh. If mutwo-skills is not installed, warn and skip this step (do not error). This updates the personal four-file + README from the session.
3. Version-control the agent files (deployable repos): the four agent files (LOG/INDEX/CLAUDE/PLAYBOOK) are tracked in deployable repos (see the VC change below); pre-land stages and commits them so they ride the deploy PR at release granularity.
4. Tracked release docs: run /document-release for README / CHANGELOG / VERSION so they are in sync before the deploy commit.
5. Write the gate stamp keyed to HEAD (e.g. <git-dir>/pre-land-stamp).

land-and-deploy (gstack, untouched)

Gated: blocked unless the pre-land stamp matches current HEAD.

post-land-and-deploy (eng skill)

Always runs after a deploy (enforced by the Stop gate below). Steps:

1. Thin inventory: the commits/diff that shipped, git state.
2. Release-docs sync: any post-deploy doc reconciliation /document-release owns.
3. Demote shipped mockups (cross-plugin, optional): call the design plugin's demote-shipped skill (Pencil demotion). Design owns Pencil internals; post-land just invokes it post-deploy. Warn+skip if design is absent.
4. Branch cleanup: the extracted cleanup-branches.sh flow (fetch --prune, delete merged branches, return to base).

The two gates (eng hooks)

Both enforce the pipeline without editing land-and-deploy.

Pre-gate (PreToolUse on the Skill tool)

When the invoked skill is land-and-deploy, check the pre-land stamp against current HEAD. No stamp, or stale vs HEAD, -> block with "run /pre-land-and-deploy first." Reuse land-deploy-sentinel.sh for skill detection.

Post-gate (PostToolUse + Stop)

• PostToolUse on Skill(land-and-deploy) writes a land-ran stamp (the sentinel already detects this).
• Stop hook blocks session end if land-ran is set for this session but post-land-and-deploy has not run. This is what makes post-land "always called after." Mirrors the existing qa-status Stop gate.

Edge: a failed/aborted land-and-deploy should not force post-land; gate on a successful land signal (define via the sentinel's success detection).

Extracted concerns landing here

Pencil demotion -> design plugin

New design skill, design/skills/demote-shipped/ (or folded into pencil-mockup): finds NEW NEW frames in touched .pen files, cross-references what actually shipped (post-deploy), removes the prefix + orange dashed stroke for frames in production. Owns Pencil internals (get_editor_state, stroke removal). Invoked by post-land.

Deploy-convention audit -> eng

The DEPLOY.md / deploy.json / deploy-script presence+validity check extracted from mutwo's agent-files-architect. eng owns it (likely alongside setup-deploy or as part of the deploy pipeline). It flags "repo deploys (signal: X) but missing artifact Y; bootstrap from the sms-hero reference." mutwo's architect no longer carries any deploy-convention knowledge beyond treating the generated CLAUDE.md ## Deploy Configuration block as opaque.

Branch cleanup -> eng

Move cleanup-branches.sh and its bats tests into eng; post-land runs it. Consequence: non-code repos (no eng/post-land) no longer get automatic branch pruning, accepted.

Agent-file version-control change (deployable repos only)

In deployable repos, un-gitignore LOG/INDEX/CLAUDE/PLAYBOOK so pre-land can commit them into the deploy PR. Because mutwo's close-out is check-only (never commits), pre-land is the sole committer, so version control happens at release granularity with no docs-only PR churn. Non-deployable repos keep the files local-only. The ~/dev/CLAUDE.md universal local-only rule gets a carve-out (companion spec). "Deployable repo" is detected by the same deploy signal the deploy-convention audit uses; keep that signal definition single-sourced here.

Deliverables (gstack side)

• New eng skills: eng/skills/pre-land-and-deploy/, eng/skills/post-land-and-deploy/.
• New eng hooks: pre-gate (PreToolUse/Skill block), post-gate (PostToolUse stamp + Stop enforcement), wired in eng/hooks/hooks.json, with bats tests. Reuse land-deploy-sentinel.sh.
• New design skill: design/skills/demote-shipped/ (Pencil demotion).
• eng deploy-convention audit (new skill or folded into existing deploy skill).
• The thin wrapper in pre-land that calls mutwo /agent-files-refresh with warn+skip.
• Per-repo VC mechanics for the agent files in deployable repos (gitignore carve-out; single-sourced deploy signal).
• gstack-extensions/CLAUDE.md "What this repo is": SDLC boundary + litmus + cross-ref to mutwo (gated edit; also in the companion spec).

Open items / assumptions

• pre/post-land live in the eng plugin (Engineer Ernie owns ship/land/deploy/review). Confirm vs a dedicated deploy sub-area.
• The Stop-gate "successful land" signal needs a concrete definition from land-deploy-sentinel.sh (so a failed deploy does not trap the session).
• The agent-files-refresh wrapper is the only gstack->mutwo dependency; it must degrade to warn+skip cleanly so gstack works standalone.
• Marketplace mechanics: new skills need bin/install re-run and the update-check preamble; new hooks follow the "${CLAUDE_PLUGIN_ROOT}" + BASH_SOURCE path rules in gstack-extensions/CLAUDE.md.