KeiSeiKit-1.0/skills/new-project/phase-4-merge-ceremony.md

Phase 4 — Merge Ceremony

Per-branch verdict, ledger bookkeeping, integration into the project branch. One AskUserQuestion per sub-agent branch (therefore the skill's AskUserQuestion floor rises with fanout).

4a — Validate bundles first

For every SUB_AGENTS[i] where status ∈ {done, failed}:

kei-ledger validate "$agent_branch"

This verifies all 6 required artefacts exist under .claude/agents/<id>/: spec.md, plan.md, progress.json, chatlog.md, handoffs.md, review.md.

If any agent is MISSING artefacts — mark its verdict as "reject-bundle" and skip the per-branch click below. The final report lists them.

4b — Per-branch merge click (AskUserQuestion, ONE per branch)

For each sub-agent whose bundle is complete, emit:

{
  "questions": [
    {
      "question": "Merge verdict for <agent_id> on <agent_branch> (status=<s>, summary=<first 60 chars>)?",
      "header": "Verdict",
      "multiSelect": false,
      "options": [
        {"label": "merge --no-ff",   "description": "Preserve the sub-branch history — default for substantive work"},
        {"label": "squash",          "description": "Collapse into one commit on project branch — for small / fixup work"},
        {"label": "reject",          "description": "Do not merge — kei-ledger rejected; branch stays for audit"},
        {"label": "defer",           "description": "Leave for later — no merge, no rejection; re-enter skill next session"}
      ]
    }
  ]
}

Execute per click:

• merge --no-ff →

  git checkout "$PROJECT_BRANCH"
  git merge --no-ff "$agent_branch" -m "merge($agent_id): $summary"
  kei-ledger merged "$agent_id"
  

• squash →

  git checkout "$PROJECT_BRANCH"
  git merge --squash "$agent_branch"
  git commit -m "feat($agent_id): $summary (squashed)"
  kei-ledger merged "$agent_id"
  

• reject →

  kei-ledger fail "$agent_id" --reason "rejected at merge ceremony"
  # Update status table — ledger has no explicit 'rejected' from 'done',
  # so we log rejection via a `fail` with reason; the row stays as audit
  # evidence. (If the agent was already in 'failed' — leave as is.)
  

• defer → no git action, no ledger state change; record in MERGE_PLAN as deferred so the final report reminds the user.

4c — Final integration checkpoint

After every sub-branch has a verdict:

git checkout "$PROJECT_BRANCH"
git log --oneline -20
kei-ledger tree "$LEDGER_ID"

Emit a final NO-DOWNGRADE click if any sub-branch was rejected or deferred — never silently close the project:

{
  "questions": [
    {
      "question": "Project state has <N> rejected + <M> deferred branches. Next step?",
      "header": "Close",
      "multiSelect": false,
      "options": [
        {"label": "open PR as-is",          "description": "Push project branch, open PR — rejected work is audit-logged only"},
        {"label": "retry rejected",         "description": "Return to Phase 2c with the rejected sub-agents as fresh spawns"},
        {"label": "close and re-enter later", "description": "Leave project branch local; re-enter skill next session"}
      ]
    }
  ]
}

Verify-criterion

• kei-ledger list --status running returns zero rows whose parent_branch == $PROJECT_BRANCH.
• Every SUB_AGENTS[i] has exactly one entry in MERGE_PLAN — one of merge, squash, reject, defer, reject-bundle.
• For every merge / squash verdict, kei-ledger list --status merged contains a matching row.
• Final report cites each verdict explicitly and does NOT gloss over rejected / deferred branches.