feat(tsugu): thin core — single prepare/*, non-containment landings advanced, accepted-prefixes, 3→4 migration (schema 4)#39
Merged
Conversation
…cepted-prefixes, merge-method shrink)
…xtra-prefix slug artifact)
…advanced.md pointer
…ontinue implicit, promote orthogonal
…ed pointer (spec review §B2)
…; move forced-squash to advanced.md
…ep, accepted-branch rename + SKILL.md pointer sync
…per-branch legacy)
… verbs, driver default)
…ed-prefix derivation, stale policy-and-intake + broken template path
Final whole-branch review (Codex P1×3 + Claude):
- migrations.md 3→4: the schema-4 stamp was numbered step 2 (inside E1), before
the E2 collapse and E3 legacy handling — an interrupted run could stamp "done"
with that work unfinished. Moved the stamp to a final E4 step after E2/E3;
renumbered the legacy cases 4a/4b/4c → 3a/3b/3c.
- migrations.md E3: derive the removed-prefix set from the pre-collapse
## Branch Prefixes (every removed work prefix, incl. custom like research/*)
instead of hardcoding investigate/review, so custom-prefix branches don't
escape discovery. Narrowed the trailing "live branches not migrated centrally"
sentence (it contradicted E3) to "content on live branches is unchanged 3→4".
- policy-and-intake.md: schema field-doc current 3→4; chain 1→2→3→4; dropped
investigate/review from the Private-Git-Space boundary example.
- templates/policy.md: the rendered .tsugu/policy.md pointed at a bare relative
references/advanced.md (broken in a user repo); now names the skill's advanced
reference with the ${CLAUDE_PLUGIN_ROOT} path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…list collapse; SKILL.md chain 1→2→3→4 (final-review round 2) Codex round 2 of the final review: - P1 re-entrancy: migrations.md E2 wrote the collapsed ## Branch Prefixes before E3 ran — an interruption between them lost the custom-prefix list E3 needs, stranding branches. Now: on confirmation, record the removed work prefixes into ## Legacy Work Prefixes FIRST, run E3 against that recorded set (## Branch Prefixes stays intact), and only THEN collapse the list (new step 3d), before the E4 stamp. A re-run recovers the removed set either way. - P2: SKILL.md re-run-decision step 3 still said a schema-1 repo runs 1→2→3; now 1→2→3→4 (and the example commit message 2→3 → 3→4). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR implements Tsugu spec 007 by moving to a thin-core / schema 4 model: Tsugu’s default work queue is only prepare/*, repo-native “handoff” branches are reframed as Accepted Prefixes, and non-containment landings (squash/rebase/force-push) are relocated into a new advanced reference while keeping core behavior focused on containment-derived settlement.
Changes:
- Updates Tsugu schema from 3 → 4, including terminology shifts (
Handoff Prefixes→Accepted Prefixes, reject → drop, etc.) and new defaults (prepare/*,feature/* bugfix/* chore/*). - Introduces
references/advanced.mdand re-points core docs to treat history-rewriting landings as advanced behavior. - Documents an interactive, re-entrant 3→4 migration path with optional prefix-collapse and per-branch legacy handling.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/tsugu/skills/tsugu/templates/policy.md | Updates schema stamp, defaults, and points merge-method guidance to advanced reference. |
| plugins/tsugu/skills/tsugu/templates/packet.md | Renames “handoff” packet section to “accepted” terminology. |
| plugins/tsugu/skills/tsugu/SKILL.md | Core spec updated for schema 4: single prepare/*, accepted prefixes, converge dispositions, scheduling guidance. |
| plugins/tsugu/skills/tsugu/references/policy-and-intake.md | Aligns policy field semantics and defaults with schema 4 terminology and behavior. |
| plugins/tsugu/skills/tsugu/references/notes-and-packet.md | Updates narrative/packet documentation to use accepted-branch framing. |
| plugins/tsugu/skills/tsugu/references/migrations.md | Adds detailed, restart-safe migration 3→4 and updates schema chain references. |
| plugins/tsugu/skills/tsugu/references/git-recipes.md | Updates git recipes to use accepted prefixes and exclude-mode settlement rules; adds legacy-prefix sweep guidance. |
| plugins/tsugu/skills/tsugu/references/advanced.md | New advanced reference covering non-containment landings and extra work-prefix artifact semantics. |
| plugins/tsugu/skills/tsugu/README.md | Updates user-facing overview to schema 4 model and links spec 007. |
| plugins/tsugu/commands/prepare.md | Updates prepare command description and scheduling/provisioning guidance. |
| plugins/tsugu/commands/init.md | Updates init command description and schema migration chain. |
| CLAUDE.md | Updates repo-level plugin summary to reflect Tsugu schema 4 and new mental model. |
| .claude-plugin/marketplace.json | Bumps tsugu plugin version 0.3.0 → 0.4.0 and updates marketplace description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+76
to
+80
| - **(a) the general deleted-ref narrative backstop** — for a *deleted* handoff / | ||
| public ref (the forge auto-deletes on merge), so landed work doesn't read as | ||
| in-progress; and | ||
| - **(b) the retain-handoff / disable-auto-delete recommendation** — `exclude` mode | ||
| settles via the **public branch's** containment, so that ref must survive too. |
Owner
Author
There was a problem hiding this comment.
Fixed in 26cf555 (handoff→accepted terminology / exclude-mode branch clarification).
Comment on lines
+82
to
+84
| Advanced only adds the **rewrite-specific** elaboration on top of these — the | ||
| deleted-ref backstop and the retain-handoff recommendation themselves are core, | ||
| shared with `exclude`. |
Owner
Author
There was a problem hiding this comment.
Fixed in 26cf555 (handoff→accepted terminology / exclude-mode branch clarification).
Comment on lines
+34
to
+36
| Disable the forge's auto-delete-head-branch for tsugu branches so the slug | ||
| pairing survives the merge — `exclude` mode settles via the public branch's | ||
| containment, so that ref must survive too. |
Owner
Author
There was a problem hiding this comment.
Fixed in 26cf555 (handoff→accepted terminology / exclude-mode branch clarification).
… exclude-mode branch PR #39 Copilot review (5 inline, all T1 terminology/clarity): - SKILL.md: "its own handoff" → "its own accepted branch"; "orphaned handoff" → "orphaned accepted branch". - advanced.md: "deleted handoff / public ref" → "accepted / public ref"; "retain-handoff" → "retain-the-ref" (the recommendation names the ref, not the old handoff term). - templates/policy.md: "auto-delete-head-branch for tsugu branches" was ambiguous (could read as prepare/*); clarified to "the slug-paired accepted / public branch (not prepare/*)" for exclude-mode settlement. (migrations.md's 2→3 section keeps "handoff" as historical schema-2/3 vocabulary, same as its ## Handoff Prefixes references.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Comment on lines
+118
to
+121
| For the **`exclude`-mode** retain case: the repo **should disable the forge's | ||
| auto-delete-head-branch for tsugu accepted branches**, so the slug pairing | ||
| survives the merge and carries the "awaiting merge" state until the human's | ||
| completion tail deletes both branches. This is a recommendation, not a hard gate. |
Owner
Author
There was a problem hiding this comment.
Fixed in fbc7ce6 — reworded: in exclude mode the accepted/public ref is retained to carry the settlement evidence (settlement = the public branch's containment), and once it merges the item is settled, not awaiting. Thanks for the precise catch.
…e, not 'awaiting merge' PR #39 Copilot round 2 (1 comment, policy-and-intake.md): in exclude mode the work branch never merges, so once the public branch merges the item is SETTLED (settlement = the public branch's containment), not awaiting. Reworded: the accepted/public ref is retained to carry the settlement evidence until the completion tail confirms the landing — not to hold a pending state. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| - **Pending pairs by slug, not commits.** The accepted branch shares the work branch's slug; ref names are write-once identity, so the pending state survives anything the forge does to commits (PR-branch rebases, squashes, force-pushes). Containment in refs *outside* the configured accepted prefixes carries no derived meaning. | ||
| - **Core assumes merge commits.** Tsugu **recommends merge commits — do not squash-merge tsugu-managed branches**; preserved history is what makes settlement containment-derivable. In `exclude` mode the work branch itself never merges (accepted changes land **by path** on a fresh public branch), so settlement reads off the **public branch's** containment — the item becomes **settled** the moment that tip is contained (partition row 1). Because that disposition can only be read *while the slug-paired public/accepted ref survives*, **recommend disabling the forge's auto-delete-head-branch for tsugu accepted/public branches**. *A landing that rewrites history (squash, rebase-before-merge, force-push) breaks containment-derived settlement; see `references/advanced.md`.* | ||
| - **Narrative backstop (the accepted/public ref is deleted anyway).** If the forge deletes that ref on merge (e.g. an `exclude`-mode landing where auto-delete fired), the work branch is neither contained nor slug-paired, so the table calls it **in-progress** — and a scheduled `prepare` must not resume landed work. The work branch's `context.md` reads "handed off — may have landed" (written at the converge decision); `prepare`'s **judgment** reads that and **leaves the branch for `converge`** rather than resuming it. The partition still classifies it in-progress; judgment, not a status field, declines to work it — *narrative informs judgment, never classification*. | ||
| - **Out-of-band PR closure = rejection.** If the human closes the PR and deletes the accepted branch, the slug pairing dissolves and the work resurfaces — **surfaced at the next `converge` for re-decision, never auto-resumed by a scheduled `prepare`**. |
Owner
Author
There was a problem hiding this comment.
Addressed in 42edb3f. These are two distinct concepts, so rather than rename to drop (which would conflate them) I removed the ambiguous "rejection" label and made the distinction explicit: this is an out-of-band, forge-side PR closure that dissolves the slug pairing — separate from the converge-time drop disposition. Good catch on the ambiguity.
…op disposition PR #39 Copilot round 3 (1 comment, SKILL.md:110): the bare label "Out-of-band PR closure = rejection" reads as inconsistent with the schema-4 drop disposition. These are genuinely distinct concepts (forge-side PR closure that dissolves the slug pairing vs the converge-time drop disposition), so renaming to "drop" would conflate them. Instead removed the ambiguous "rejection" label and stated the distinction explicitly: "Out-of-band PR closure (a forge-side decline, outside converge) — distinct from the drop disposition". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements spec 007 (
docs/superpowers/specs/007-tsugu-thin-core-design.md) — the Tsugu thin-core / schema 4 simplification from #38. Narrows the core mental model to "Tsugu preparesprepare/*branches; humans decide what converges" and relocates the heaviest path to an advanced reference. Relocate, not remove — no capability dropped; the default surface shrinks.Closes #38.
The changes
prepare/*work prefix. Dropsinvestigate/* review/*from the default; built-in subagents work inside theprepare/*branch; investigation/review status lives incontext.mdnarrative.references/advanced.md(new). Core assumes merge commits (settlement = containment). Any history-rewriting landing (squash / rebase-before-merge / force-push) moves to advanced; core keeps a one-line pointer + the exclude-mode-shared deleted-ref backstop / retain-handoff lines.## Accepted Prefixes(list, defaultfeature/* bugfix/* chore/*); handoff reframed as the accept-time event, not a Tsugu-owned namespace.continueimplicit;promoteorthogonal; the no-status-field invariant preserved.## Handoff Prefixes; propose prefix-collapse on confirmation; disjointness re-check; per-branch legacy handling (ancestry-checked delete-or-record / recreate-at-hash / stop-and-ask); re-entrant (removed set persisted to## Legacy Work Prefixes, list-collapse deferred, schema stamp written last after E2/E3).prepare's default driver runs on the provisioned machine (source config + MCP/forge credentials, typically the homelab), not a generic cloud/schedule; unprovisioned cloud runs degrade to git-native. No-self-wake unchanged.Kept in core (not advanced): exclude mode, multi-agent forward-compat, omni-repo recursion.
tsugubumped 0.3.0 → 0.4.0 (top-levelmetadata.versionuntouched).Review
Spec, plan, and this branch each went through the review-loop local gate (Claude subagent + headless Codex). Implementation executed task-by-task via subagent-driven development with per-task spec-compliance reviews on the content-heavy files (advanced.md, SKILL.md A–F, migrations 3→4) and a whole-branch final review — final verdict: "No findings. Ready for PR." Codex also simulated the merge against the updated
main.🤖 Generated with Claude Code