claudikins-kernel:ship

# claudikins-kernel:ship Command

You are orchestrating a shipping workflow that takes verified code to production with human approval at every stage.

## Flags

| Flag              | Effect                                  |
| ----------------- | --------------------------------------- |
| `--branch NAME`   | Ship specific branch (default: current) |
| `--target BRANCH` | Target branch for merge (default: main) |
| `--skip-docs`     | Skip documentation updates (Stage 3)    |
| `--squash`        | Squash commits into single commit       |
| `--preserve`      | Preserve commit history                 |
| `--dry-run`       | Preview ship without merging            |
| `--session-id ID` | Resume previous session by ID           |
| `--resume`        | Resume from last checkpoint             |
| `--status`        | Show current ship status                |
| `--list-sessions` | Show available sessions for resume      |

## Merge Strategy

JQ merge - documentation outputs are combined with `jq -s 'add'`.

## Philosophy

> "Ship with confidence, not hope." - Shipping philosophy

- claudikins-kernel:ship is the final gate after claudikins-kernel:verify passes
- GRFP-style: section-by-section approval at every stage
- Human decides final merge - no auto-merging
- Code integrity validation ensures we ship what was verified
- Documentation is part of shipping, not optional

## State Management

State file: `.claude/ship-state.json`

```json
{
  "session_id": "ship-YYYY-MM-DD-HHMM",
  "verify_session_id": "verify-YYYY-MM-DD-HHMM",
  "verified_commit": "abc123...",
  "target": "main",
  "started_at": "ISO timestamp",
  "status": "initialising|shipping|completed|failed",
  "phases": {
    "pre_ship_review": { "status": "pending|APPROVED|SKIPPED" },
    "commit_strategy": { "status": "pending|APPROVED", "strategy": null },
    "documentation": { "status": "pending|COMPLETED|SKIPPED" },
    "pr_creation": { "status": "pending|CREATED", "pr_number": null },
    "merge": { "status": "pending|MERGED", "sha": null }
  },
  "unlock_merge": false,
  "cleanup": {
    "branches_deleted": []
  }
}
```

## Stage 0: Initialisation

### Flag Handling

Check for flags first:

```
--status → Display current ship status, exit
--resume → Load checkpoint, resume from saved state
--list-sessions → Show available sessions, exit
--dry-run → Run through stages without actual merge
```

### Prerequisite Check (via ship-init.sh hook)

The SessionStart hook validates:

1. verify-state.json exists and unlock_ship is true
2. Code integrity (C-5): verified commit matches current HEAD
3. File integrity (C-7): source file manifest unchanged
4. Creates initial ship-state.json
5. Links to verify session for traceability

**On validation failure:**

```
ERROR: claudikins-kernel:verify gate check failed

Reason: ${FAILURE_REASON}

[Re-run claudikins-kernel:verify] [Abort]
```

**On code integrity failure (C-5, C-7):**

```
ERROR: Code has changed since verification

Verified commit: ${VERIFIED_COMMIT}
Current commit:  ${CURRENT_COMMIT}

Code must not change between claudikins-kernel:verify and claudikins-kernel:ship.

[Re-run claudikins-kernel:verify] [Abort]
```

## Stage 1: Pre-Ship Review

Show what's being shipped. Human confirms ready.

### Display Ship Summary

```
Pre-Ship Review
===============

Verification Session: ${VERIFY_SESSION_ID}
Verified at: ${VERIFY_TIMESTAMP}

Branches to merge:
${BRANCH_LIST}

Changes:
  Files changed: ${FILE_COUNT}
  Lines added:   +${ADDITIONS}
  Lines removed: -${DELETIONS}

Evidence from verification:
  Screenshots: ${SCREENSHOT_COUNT}
  API tests:   ${API_TEST_COUNT}
  CLI tests:   ${CLI_TEST_COUNT}

Ready to proceed?

[Continue to Commit Strategy] [Review Evidence] [Back to Verify] [Abort]
```

### Stage 1 Checkpoint

On "Continue":

- Set `phases.pre_ship_review.status = "APPROVED"`
- Proceed to Stage 2

On "Review Evidence":

- Display evidence from `.claude/evidence/`
- Return to checkpoint

On "Back to Verify":

- Set `status = "aborted"`
- Output: "Run `claudikins-kernel:verify` to re-verify"

## Stage 2: Commit Strategy

Decide how to commit the changes.

### Strategy Selection

```
Commit Strategy
===============

How should we commit these changes?

[Squash into single commit] (Recommended for features)
[Preserve commit history] (For large multi-part work)
```

**If --squash flag set:** Auto-select squash
**If --preserve flag set:** Auto-select preserve

### Commit Message Draft (Squash)

For squash, draft a commit message:

```
Commit message:

feat(${SCOPE}): ${TITLE}

${BODY}

Closes #${ISSUE_NUMBER}

[Accept] [Revise] [Back]
```

Follow conventional commits format:

- `feat:` for new features
- `fix:` for bug fixes
- `chore:` for maintenance
- `feat!:` or `BREAKING CHANGE:` for breaking changes

### Stage 2 Checkpoint

On "Accept":

- Set `phases.commit_strategy.status = "APPROVED"`
- Set `phases.commit_strategy.strategy = "squash|preserve"`
- Record commit message in state
- Proceed to Stage 3

## Stage 3: Documentation (git-perfectionist)

Update documentation to match shipped code. GRFP-style.

**If --skip-docs flag set:**

```
Skipping documentation updates.

[Confirm skip] [Update docs anyway]
```

Otherwise, spawn git-perfectionist:

### Spawn git-perfectionist

```typescript
Task(git - perfectionist, {
  prompt: `
    Update documentation to match the shipped code.

    Changes being shipped:
    ${CHANGE_SUMMARY}

    Files to check:
    - README.md (features, installation, usage)
    - CHANGELOG.md (add version entry)
    - package.json/Cargo.toml/pyproject.toml (version bump)

    GRFP-style: one section at a time, get approval for each.
    Output JSON with files updated and sections approved.
  `,
  context: "fork",
  model: "opus",
});
```

### Stage 3 Checkpoint

```
Documentation updated.

Files changed:
${DOC_FILE_LIST}

Sections updated: ${SECTION_COUNT}

[Accept] [Review changes] [Revise] [Skip docs]
```

On "Accept":

- Set `phases.documentation.status = "COMP