ship

---

name: ship description: Review and finalize (REVIEWER + DOCUMENTER phases) - runs adversarial code review, commits changes, completes task, and submits reflection to update pattern trust scores. argument-hint: [task-identifier]

Combines REVIEWER (adversarial code review) and DOCUMENTER (commit, complete, reflect).

YOU CANNOT SKIP ANY OF THESE for APPROVE or CONDITIONAL outcomes. If REJECT, stop after review, set frontmatter to phase: rework, and return to /apex:implement.

You can find active tasks in ./.apex/tasks/ or run with: /apex:ship [identifier] Load task file and begin review.

Contract rules:

• Final report MUST map changes to AC-* and confirm no out-of-scope work
• If scope/ACs changed during implement, ensure amendments are recorded with rationale and version bump

Review for security vulnerabilities. Return YAML with id, severity, confidence, location, issue, evidence, mitigations_found.

Review for performance issues. Return YAML findings.

Review for architecture violations and pattern consistency. Return YAML findings.

Review for test coverage gaps. Return YAML findings.

Review for maintainability and code quality. Return YAML findings.

WAIT for ALL 5 agents to complete before Phase 2.

Challenge EVERY finding for:

• Code accuracy (did Phase 1 read correctly?)
• Pattern applicability (does framework prevent this?)
• Evidence quality (Strong/Medium/Weak)
• ROI Analysis:
  • fix_effort: trivial | minor | moderate | significant | major
  • benefit_type: security | reliability | performance | maintainability | correctness
  • roi_score: 0.0-1.0 (benefit / effort ratio)
  • override_decision: pull_forward | keep | push_back
  • override_reason: [Why changing priority]

Return: challenge_result (UPHELD|DOWNGRADED|DISMISSED), evidence_quality, recommended_confidence, roi_analysis

Use git history to find justifications for seemingly problematic patterns. Return: Context justifications for historical code choices.

WAIT for both agents to complete.

If task modified API or CLI:

• API documentation files
• CLI command documentation
• Usage examples in docs

If task modified data structures:

• Type definition docs
• Schema documentation
• Migration notes if breaking change

Search strategy:

Copy# Find docs that might reference changed files
for file in [modified_files]; do
  grep -r "$(basename $file .ts)" docs/ README.md CLAUDE.md
done

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com" git log -1 --oneline # Capture commit SHA

Copy</commands>

<checkpoint>Commit SHA captured for evidence.</checkpoint>
</step>

<step id="7" title="apex_task_complete">
<call>
```javascript
apex_task_complete({
  id: taskId,
  outcome: "success" | "partial" | "failure",
  key_learning: "Main lesson from this task",
  patterns_used: ["PAT:ID:FROM:PLAN"]  // Only patterns from plan
})

ReflectionDraft - use as basis for apex_reflect

Without apex_reflect:

• Pattern trust scores don't update
• Learnings aren't captured
• Future tasks don't benefit

claims (advanced, for new patterns/anti-patterns/learnings):

Copyapex_reflect({
  task: { id: taskId, title: taskTitle },
  outcome: "success",
  claims: {
    // Patterns used from plan (updates trust scores)
    patterns_used: [{
      pattern_id: "PAT:ID",
      evidence: [{
        kind: "git_lines",
        file: "src/auth.ts",
        sha: "HEAD",  // or commit SHA
        start: 45,
        end: 78
      }]
    }],

    // Trust score updates (required for patterns_used)
    trust_updates: [{
      pattern_id: "PAT:ID",
      outcome: "worked-perfectly"
    }],

    // NEW patterns discovered during implementation
    new_patterns: [{
      title: "Error Boundary Pattern",
      summary: "Wrap async operations with consistent error handling",
      snippets: [{
        snippet_id: "error-boundary-1",
        source_ref: {
          kind: "git_lines",
          file: "src/utils/errors.ts",
          sha: "HEAD",
          start: 10,
          end: 35
        }
      }],
      evidence: []
    }],

    // Anti-patterns to AVOID
    anti_patterns: [{
      title: "Direct Database Access in Handler",
      reason: "Bypasses transaction management and audit logging",
      evidence: [{
        kind: "git_lines",
        file: "src/handlers/user.ts",
        sha: "HEAD",
        start: 100,
        end: 110
      }]
    }],

    // General learnings
    learnings: [{
      assertion: "JWT refresh tokens require httpOnly cookies for security",
      evidence: [{
        kind: "git_lines",
        file: "src/auth/tokens.ts",
        sha: "HEAD",
        start: 50,
        end: 65
      }]
    }]
  }
})

Copy<ship>
<metadata>
  <timestamp>[ISO]</timestamp>
  <outcome>success|partial|failure</outcome>
  <commit-sha>[SHA]</commit-sha>
</metadata>

<review-summary>
  <phase1-findings count="X">
    <by-severity critical="N" high="N" medium="N" low="N"/>
    <by-agent security="N" performance="N" architecture="N" testing="N" quality="N"/>
  </phase1-findings>
  <phase2-challenges>
    <upheld>N</upheld>
    <downgraded>N</downgraded>
    <dismissed>N</dismissed>
  </phase2-challenges>
  <false-positive-rate>[X%]</false-positive-rate>
</review-summary>

<contract-verification>
  <contract-version>[N]</contract-version>
  <amendments-audited>[List amendments or "none"]</amendments-audited>
  <acceptance-criteria-verification>
    <criterion id="AC-1" status="met|not-met">[Evidence or exception]</criterion>
  </acceptance-criteria-verification>
  <out-of-scope-check>[Confirm no out-of-scope work slipped in]</out-of-scope-check>
</contract-verification>

<action-items>
  <fix-now>
    <item id="[ID]" severity="[S]" confidence="[C]" location="[file:line]">
      [Issue and fix]
    </item>
  </fix-now>
  <should-fix>[Deferred items]</should-fix>
  <accepted>[Accepted risks with justification]</accepted>
  <dismissed>[False positives with reasons]</dismissed>
</action-items>

<commit>
  <sha>[Full SHA]</sha>
  <message>[Commit message]</message>
  <files>[List of files]</files>
</commit>

<reflection>
  <patterns-reported>
    <pattern id="PAT:X:Y" outcome="[outcome]"/>
  </patterns-reported>
  <key-learning>[Main lesson]</key-learning>
  <apex-reflect-status>submitted|failed</apex-reflect-status>
</reflection>

<final-summary>
  <what-was-built>[Concise description]</what-was-built>
  <patterns-applied count="N">[List]</patterns-applied>
  <test-status passed="X" failed="Y"/>
  <documentation-updated>[What docs changed]</documentation-updated>
</final-summary>
</ship>

📊 Metrics:

• Complexity: [X]/10
• Files modified: [N]
• Files created: [N]
• Tests: [passed]/[total]

💬 Summary: [Concise description of what was built]

📚 Patterns:

• Applied: [N] patterns
• Reflection: ✅ Submitted

✅ Acceptance Criteria:

• AC-* coverage: [met|not met with exceptions]

🔍 Review:

• Phase 1 findings: [N]
• Dismissed as false positives: [N] ([X]%)
• Action items: [N] (all resolved)

⏭️ Next: Task complete. No further action required.

• Phase 1 review agents launched and returned?
• Phase 2 challenge agents launched and returned (with ROI analysis)?
• Documentation checklist completed?
• Contract verification completed (AC mapping + out-of-scope check)?
• Git commit created? (verify with git log -1)
• apex_task_complete called? (received ReflectionDraft?)
• apex_reflect called? (received ok: true?)

If ANY unchecked → GO BACK AND COMPLETE IT.