# SHIP Protocol Specification v1.0

## Success Heuristics for Intelligent Programming

**Version:** 1.0.0
**Status:** DRAFT
**Date:** 2025-12-05
**Authors:** VibeAtlas Team
**License:** MIT
**Website:** https://ship.vibeatlas.dev

---

## Abstract

The SHIP Protocol (Success Heuristics for Intelligent Programming) defines a vendor-neutral standard for measuring, predicting, and improving the reliability of AI-assisted software development. Unlike existing solutions that focus on usage metrics or cost optimization, SHIP provides the first comprehensive framework for **confidence scoring**, **attention management**, and **predictive reliability** in AI coding tools.

SHIP addresses the critical industry problem: **70% of AI coding tasks fail**, yet no standard exists for measuring or preventing these failures. Trust in AI coding tools has dropped from 43% (2024) to 33% (2025). SHIP provides the reliability infrastructure the industry needs.

---

## Table of Contents

1. [Introduction](#1-introduction)
2. [Terminology](#2-terminology)
3. [Design Principles](#3-design-principles)
4. [Protocol Architecture](#4-protocol-architecture)
5. [The SHIP Score](#5-the-ship-score)
6. [Layer 1: Confidence](#6-layer-1-confidence)
7. [Layer 2: Focus](#7-layer-2-focus)
8. [Layer 3: Context](#8-layer-3-context)
9. [Layer 4: Efficiency](#9-layer-4-efficiency)
10. [Message Formats](#10-message-formats)
11. [Operations](#11-operations)
12. [Error Handling](#12-error-handling)
13. [Security Considerations](#13-security-considerations)
14. [Conformance](#14-conformance)
15. [Ecosystem](#15-ecosystem)
16. [Versioning](#16-versioning)
17. [Examples](#17-examples)
18. [Appendices](#appendices)

---

## 1. Introduction

### 1.1 Purpose

The SHIP Protocol provides a standardized framework for:

- **Measuring** AI coding task reliability with a single, universal score
- **Predicting** task success before execution begins
- **Managing** AI attention to ensure focus on relevant context
- **Optimizing** context for maximum reliability and efficiency
- **Learning** from outcomes to continuously improve predictions

### 1.2 The Problem

Current AI coding tools suffer from:

| Problem | Industry Data |
|---------|---------------|
| High failure rate | 70% of AI coding tasks fail |
| Declining trust | 43% → 33% trust (2024-2025) |
| "Almost right" frustration | 66% of developers cite this |
| Security vulnerabilities | 48% of AI code fails security tests |
| No reliability metrics | Usage tracked, not success |

### 1.3 The Solution

SHIP Protocol provides:

| Solution | Benefit |
|----------|---------|
| **SHIP Score** | Single 0-100 metric for reliability |
| **Confidence Layer** | Predict success before execution |
| **Focus Layer** | Ensure AI attends to right context |
| **Context Layer** | Optimize information sent to AI |
| **Efficiency Layer** | Track resource usage and costs |

### 1.4 Goals

1. **Reliability First**: Make task success the primary metric
2. **Predictive**: Know confidence before AI generates code
3. **Universal**: Work with any AI tool (Copilot, Claude, Cursor, etc.)
4. **Measurable**: Provide concrete, comparable metrics
5. **Open**: MIT-licensed, vendor-neutral, community-governed

### 1.5 Non-Goals

- Replacing AI coding tools (SHIP is infrastructure, not competition)
- Defining how AI generates code (tool-agnostic)
- User interface specifications (implementation-specific)

---

## 2. Terminology

### 2.1 RFC 2119 Keywords

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

### 2.2 Definitions

**SHIP Score**: A 0-100 metric representing overall task reliability. Higher is better.

**Task**: A discrete unit of work requested from an AI coding assistant.

**Provider**: A service implementing SHIP Protocol to assess and improve task reliability.

**Consumer**: An AI coding tool or integration requesting SHIP assessment.

**Confidence**: The predicted probability of task success (0.0-1.0).

**Focus**: The quality of attention distribution across context elements.

**Context**: Information provided to the AI for task completion.

**First-SHIP Rate**: Percentage of tasks succeeding on first attempt.

**SHIP-Ready**: A task with SHIP Score ≥ 90, indicating high probability of success.

---

## 3. Design Principles

### 3.1 Reliability Over Efficiency

SHIP prioritizes task success over cost savings. A reliable task that costs more tokens is preferable to an unreliable task that saves tokens.

```
Priority Order:
1. Reliability (Will it work?)
2. Focus (Is attention correct?)
3. Context (Is information complete?)
4. Efficiency (Is it cost-effective?)
```

### 3.2 Predictive Over Reactive

SHIP predicts problems before they occur, rather than detecting them after. The goal is **prevention**, not post-mortem analysis.

### 3.3 Transparency Over Black Box

Every SHIP Score MUST be explainable. Developers SHOULD be able to understand why a score is high or low and what actions would improve it.

### 3.4 Universal Over Proprietary

SHIP is designed to work with ANY AI coding tool. No vendor lock-in.

### 3.5 Progressive Enhancement

SHIP SHOULD enhance existing workflows without requiring wholesale changes. Minimal integration, maximum value.

---

## 4. Protocol Architecture

### 4.1 Layer Model

```
┌─────────────────────────────────────────────────────────┐
│                    SHIP PROTOCOL v1.0                   │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Layer 1: CONFIDENCE (Primary)                  │   │
│  │  ├── Task completion probability                │   │
│  │  ├── Risk factor analysis                       │   │
│  │  ├── Historical pattern matching                │   │
│  │  └── Success prediction                         │   │
│  └─────────────────────────────────────────────────┘   │
│                          │                              │
│                          ▼                              │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Layer 2: FOCUS (Primary)                       │   │
│  │  ├── Attention scoring                          │   │
│  │  ├── Semantic anchoring                         │   │
│  │  ├── Priority ordering                          │   │
│  │  └── Distraction filtering                      │   │
│  └─────────────────────────────────────────────────┘   │
│                          │                              │
│                          ▼                              │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Layer 3: CONTEXT (Secondary)                   │   │
│  │  ├── Relevance scoring                          │   │
│  │  ├── Completeness assessment                    │   │
│  │  ├── Freshness validation                       │   │
│  │  └── Dependency resolution                      │   │
│  └─────────────────────────────────────────────────┘   │
│                          │                              │
│                          ▼                              │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Layer 4: EFFICIENCY (Tertiary)                 │   │
│  │  ├── Token optimization                         │   │
│  │  ├── Cost tracking                              │   │
│  │  ├── Latency measurement                        │   │
│  │  └── Resource utilization                       │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 4.2 Data Flow

```
┌──────────────┐    ShipRequest     ┌──────────────┐
│   Consumer   │ ──────────────────>│   Provider   │
│  (AI Tool)   │                    │  (VibeAtlas) │
│              │    ShipResponse    │              │
│  • Copilot   │ <──────────────────│  • Scoring   │
│  • Cursor    │                    │  • Analysis  │
│  • Claude    │   ShipFeedback     │  • Learning  │
│              │ ──────────────────>│              │
└──────────────┘                    └──────────────┘
```

### 4.3 Communication

- **Transport**: HTTP/1.1, HTTP/2, or WebSocket
- **Format**: JSON (application/json)
- **Version Header**: `SHIP-Version: 1.0`
- **Encoding**: UTF-8

---

## 5. The SHIP Score

### 5.1 Definition

The SHIP Score is a single 0-100 integer representing overall task reliability. It is calculated from four component scores:

```
SHIP Score = (Confidence × 0.40) + (Focus × 0.30) + (Context × 0.20) + (Efficiency × 0.10)
```

Where each component is normalized to 0-100.

### 5.2 Score Interpretation

| Score Range | Label | Meaning | Action |
|-------------|-------|---------|--------|
| 95-100 | **SHIP Elite** | Exceptional reliability | Ship with confidence |
| 90-94 | **SHIP Ready** | High reliability | Ship with confidence |
| 80-89 | **Review** | Good reliability, minor risks | Quick review recommended |
| 70-79 | **Caution** | Moderate reliability | Detailed review required |
| 50-69 | **Warning** | Low reliability | Consider decomposition |
| 0-49 | **Stop** | High failure risk | Do not proceed |

### 5.3 Score Components

#### 5.3.1 Confidence Score (40% weight)

Measures predicted probability of task success.

```json
{
  "confidence_score": 92,
  "completion_probability": 0.92,
  "risk_factors": [
    {"factor": "complex async flow", "severity": 0.15}
  ],
  "patterns_matched": 5,
  "historical_success_rate": 0.94
}
```

#### 5.3.2 Focus Score (30% weight)

Measures quality of attention distribution.

```json
{
  "focus_score": 87,
  "attention_utilization": 0.89,
  "semantic_coverage": 0.91,
  "distraction_rate": 0.08
}
```

#### 5.3.3 Context Score (20% weight)

Measures quality and completeness of provided context.

```json
{
  "context_score": 94,
  "relevance": 0.95,
  "completeness": 0.92,
  "freshness": 0.98
}
```

#### 5.3.4 Efficiency Score (10% weight)

Measures resource optimization.

```json
{
  "efficiency_score": 78,
  "token_savings": 0.42,
  "cost_reduction": 0.38,
  "latency_ms": 145
}
```

### 5.4 Score Display

Providers MUST support these display formats:

#### 5.4.1 Full Display

```
┌─────────────────────────────────────────────┐
│          SHIP SCORE: 91                     │
│  ████████████████████████████████░░░  91%   │
├─────────────────────────────────────────────┤
│  Confidence:    92  ████████████████████░   │
│  Focus:         87  ███████████████████░░   │
│  Context:       94  ████████████████████░   │
│  Efficiency:    78  ███████████████░░░░░░   │
├─────────────────────────────────────────────┤
│  Status: SHIP-Ready                         │
│  First-SHIP Probability: 89%                │
└─────────────────────────────────────────────┘
```

#### 5.4.2 Compact Display

```
SHIP: 91 [████████████████████████████░░░] Ready
```

#### 5.4.3 Badge Format

For shields.io and similar services:

```
https://ship.vibeatlas.dev/badge/{project-id}
```

Returns: `SHIP Score: 91 | Ready`

---

## 6. Layer 1: Confidence

### 6.1 Purpose

The Confidence Layer predicts task success probability before AI execution. This is the PRIMARY differentiator of SHIP Protocol.

### 6.2 Confidence Assessment

#### 6.2.1 Completion Probability

A value between 0.0 and 1.0 representing the predicted likelihood of task success.

```typescript
interface CompletionProbability {
  /** Probability of success (0.0-1.0) */
  value: number;

  /** How confident we are in this prediction */
  confidence_interval: {
    lower: number;
    upper: number;
  };

  /** Factors that influenced the prediction */
  factors: PredictionFactor[];
}
```

#### 6.2.2 Risk Factors

Identified risks that could cause task failure.

```typescript
interface RiskFactor {
  /** Risk identifier */
  id: string;

  /** Human-readable description */
  description: string;

  /** Severity (0.0-1.0) */
  severity: number;

  /** Category of risk */
  category: 'complexity' | 'context' | 'ambiguity' | 'dependency' | 'security';

  /** Suggested mitigation */
  mitigation?: string;
}
```

#### 6.2.3 Pattern Matching

Historical patterns that match the current task.

```typescript
interface PatternMatch {
  /** Pattern identifier */
  pattern_id: string;

  /** Similarity score (0.0-1.0) */
  similarity: number;

  /** Historical success rate for this pattern */
  success_rate: number;

  /** Number of historical occurrences */
  sample_size: number;
}
```

### 6.3 Confidence Levels

| Level | Probability | Description |
|-------|-------------|-------------|
| **Very High** | ≥ 0.95 | Extremely likely to succeed |
| **High** | 0.85-0.94 | Likely to succeed |
| **Medium** | 0.70-0.84 | May require iteration |
| **Low** | 0.50-0.69 | Consider alternatives |
| **Very Low** | < 0.50 | Likely to fail |

### 6.4 Retry Strategies

When tasks fail, SHIP recommends retry strategies:

| Strategy | When to Use |
|----------|-------------|
| **none** | Success or unrecoverable failure |
| **incremental** | Minor issues, try with small adjustments |
| **decompose** | Complex task, break into subtasks |
| **clarify** | Ambiguous requirements, seek clarification |
| **augment** | Missing context, add more information |

---

## 7. Layer 2: Focus

### 7.1 Purpose

The Focus Layer ensures AI attention is distributed optimally across context elements. Poor focus leads to "almost right" code that frustrates developers.

### 7.2 Attention Management

#### 7.2.1 Focus Priority

Ordered list of context elements by importance.

```typescript
interface FocusPriority {
  /** Context element identifier */
  element_id: string;

  /** File path (if applicable) */
  file?: string;

  /** Line range (if applicable) */
  lines?: string;

  /** Priority rank (1 = highest) */
  rank: number;

  /** Attention weight (0.0-1.0) */
  weight: number;

  /** Why this element is important */
  reason: string;
}
```

#### 7.2.2 Semantic Anchors

Key concepts the AI should focus on.

```typescript
interface SemanticAnchor {
  /** Concept identifier */
  concept: string;

  /** Importance weight (0.0-1.0) */
  weight: number;

  /** Locations where this concept appears */
  locations: Location[];

  /** Related concepts */
  related?: string[];
}
```

#### 7.2.3 Distraction Signals

Elements that should be deprioritized or ignored.

```typescript
interface DistractionSignal {
  /** Pattern to match */
  pattern: string;

  /** Type of pattern */
  type: 'file' | 'content' | 'semantic';

  /** Why this is a distraction */
  reason: string;

  /** Action to take */
  action: 'ignore' | 'deprioritize' | 'summarize';
}
```

### 7.3 Focus Metrics

| Metric | Description | Target |
|--------|-------------|--------|
| **Attention Utilization** | % of context AI actually used | ≥ 80% |
| **Semantic Coverage** | % of anchors addressed | ≥ 90% |
| **Distraction Rate** | % of attention on irrelevant content | ≤ 10% |
| **Focus Depth** | Concentration on primary context | ≥ 0.6 |

---

## 8. Layer 3: Context

### 8.1 Purpose

The Context Layer ensures the AI has the right information to complete the task. Context quality directly impacts reliability.

### 8.2 Context Assessment

#### 8.2.1 Relevance Scoring

How relevant each context element is to the task.

```typescript
interface RelevanceScore {
  /** Element identifier */
  element_id: string;

  /** Relevance score (0.0-1.0) */
  score: number;

  /** Why this score */
  reasoning: string;

  /** Dependencies this element provides */
  provides: string[];

  /** Dependencies this element requires */
  requires: string[];
}
```

#### 8.2.2 Completeness Assessment

Whether all required context is present.

```typescript
interface CompletenessAssessment {
  /** Overall completeness (0.0-1.0) */
  score: number;

  /** Required elements that are present */
  present: string[];

  /** Required elements that are missing */
  missing: string[];

  /** Recommendations for missing elements */
  recommendations: string[];
}
```

#### 8.2.3 Freshness Validation

Whether context is up-to-date.

```typescript
interface FreshnessValidation {
  /** Overall freshness (0.0-1.0) */
  score: number;

  /** Stale elements */
  stale: {
    element_id: string;
    last_modified: string;
    staleness_reason: string;
  }[];

  /** Refresh recommendations */
  refresh_needed: string[];
}
```

### 8.3 Context Metrics

| Metric | Description | Target |
|--------|-------------|--------|
| **Relevance** | % of context that's useful | ≥ 85% |
| **Completeness** | % of required context present | ≥ 95% |
| **Freshness** | % of context that's current | ≥ 90% |
| **Redundancy** | % of duplicate/overlapping content | ≤ 15% |

---

## 9. Layer 4: Efficiency

### 9.1 Purpose

The Efficiency Layer optimizes resource usage while maintaining reliability. Efficiency is important but NEVER at the expense of reliability.

### 9.2 Efficiency Metrics

```typescript
interface EfficiencyMetrics {
  /** Original token count */
  original_tokens: number;

  /** Optimized token count */
  optimized_tokens: number;

  /** Tokens saved */
  tokens_saved: number;

  /** Percentage saved */
  savings_percentage: number;

  /** Estimated cost saved (USD) */
  cost_saved_usd: number;

  /** Processing latency (ms) */
  latency_ms: number;

  /** CO2 saved (grams) */
  co2_saved_grams?: number;
}
```

### 9.3 Efficiency Targets

| Metric | Target | Note |
|--------|--------|------|
| **Token Savings** | ≥ 30% | Without reducing reliability |
| **Processing Latency** | ≤ 200ms p95 | For real-time use |
| **Cost Reduction** | ≥ 25% | Average across tasks |

### 9.4 Efficiency Constraints

Efficiency optimizations MUST NOT:
- Reduce Confidence Score below 80
- Remove context required for task success
- Eliminate security-relevant context
- Break dependencies between context elements

---

## 10. Message Formats

### 10.1 Common Fields

All SHIP messages MUST include:

```json
{
  "ship_version": "1.0",
  "message_type": "ShipRequest | ShipResponse | ShipFeedback | ShipError",
  "message_id": "uuid-v4",
  "timestamp": "ISO-8601 datetime"
}
```

### 10.2 ShipRequest

Request a SHIP assessment for a task.

```json
{
  "ship_version": "1.0",
  "message_type": "ShipRequest",
  "message_id": "req-550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-05T10:30:00.000Z",

  "task": {
    "description": "Add error handling to the fetchUser function",
    "type": "modification",
    "target_file": "src/api/users.ts",
    "success_criteria": [
      "Handle network errors gracefully",
      "Return typed error responses",
      "Log errors for debugging"
    ]
  },

  "context": {
    "files": [
      {
        "path": "src/api/users.ts",
        "content": "export async function fetchUser(id: string) {...}",
        "language": "typescript"
      },
      {
        "path": "src/types/errors.ts",
        "content": "export interface ApiError {...}",
        "language": "typescript"
      }
    ],
    "metadata": {
      "project_type": "typescript",
      "framework": "express",
      "ai_tool": "copilot"
    }
  },

  "options": {
    "confidence_threshold": 0.85,
    "include_focus_directives": true,
    "include_efficiency_metrics": true,
    "learning_enabled": true
  }
}
```

### 10.3 ShipResponse

Response with SHIP assessment.

```json
{
  "ship_version": "1.0",
  "message_type": "ShipResponse",
  "message_id": "resp-550e8400-e29b-41d4-a716-446655440001",
  "request_id": "req-550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-05T10:30:00.150Z",

  "ship_score": 91,
  "ship_status": "ready",
  "ship_label": "SHIP-Ready",

  "confidence": {
    "score": 92,
    "completion_probability": 0.92,
    "confidence_level": "high",
    "risk_factors": [
      {
        "id": "rf-001",
        "description": "Async error handling has multiple patterns",
        "severity": 0.15,
        "category": "complexity",
        "mitigation": "Use try-catch with typed errors"
      }
    ],
    "patterns_matched": [
      {
        "pattern_id": "error-handling-async",
        "similarity": 0.89,
        "success_rate": 0.94,
        "sample_size": 1247
      }
    ],
    "recommended_retry_strategy": "none"
  },

  "focus": {
    "score": 87,
    "priorities": [
      {
        "element_id": "users.ts:fetchUser",
        "file": "src/api/users.ts",
        "lines": "15-30",
        "rank": 1,
        "weight": 0.6,
        "reason": "Primary function to modify"
      },
      {
        "element_id": "errors.ts:ApiError",
        "file": "src/types/errors.ts",
        "lines": "1-15",
        "rank": 2,
        "weight": 0.25,
        "reason": "Error type definitions needed"
      }
    ],
    "semantic_anchors": [
      {
        "concept": "async error handling",
        "weight": 0.8,
        "locations": [{"file": "src/api/users.ts", "line": 15}]
      },
      {
        "concept": "typed responses",
        "weight": 0.6,
        "locations": [{"file": "src/types/errors.ts", "line": 1}]
      }
    ],
    "distractions_filtered": 12,
    "attention_utilization": 0.89,
    "semantic_coverage": 0.91
  },

  "context": {
    "score": 94,
    "relevance": 0.95,
    "completeness": 0.92,
    "freshness": 0.98,
    "optimized_files": [
      {
        "path": "src/api/users.ts",
        "original_tokens": 450,
        "optimized_tokens": 380,
        "relevance_score": 1.0
      }
    ],
    "missing_context": [],
    "recommendations": []
  },

  "efficiency": {
    "score": 78,
    "original_tokens": 2500,
    "optimized_tokens": 1450,
    "tokens_saved": 1050,
    "savings_percentage": 42,
    "cost_saved_usd": 0.021,
    "latency_ms": 145,
    "co2_saved_grams": 0.4
  },

  "metadata": {
    "provider": "vibeatlas",
    "provider_version": "1.0.0",
    "model_version": "ship-v1-2025-12",
    "processing_time_ms": 145
  }
}
```

### 10.4 ShipFeedback

Report task outcome for learning.

```json
{
  "ship_version": "1.0",
  "message_type": "ShipFeedback",
  "message_id": "fb-550e8400-e29b-41d4-a716-446655440002",
  "request_id": "req-550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-05T10:35:00.000Z",

  "outcome": {
    "task_completed": true,
    "first_attempt_success": true,
    "total_attempts": 1,
    "time_to_completion_ms": 45000,
    "user_satisfaction": 5
  },

  "attention_feedback": {
    "attention_helpful": true,
    "missed_context": [],
    "unnecessary_context": ["README.md"],
    "attention_utilization": 0.92
  },

  "errors_encountered": [],

  "learning_signals": {
    "reinforce_patterns": ["error-handling-async"],
    "correct_patterns": []
  }
}
```

### 10.5 ShipError

Error response.

```json
{
  "ship_version": "1.0",
  "message_type": "ShipError",
  "message_id": "err-550e8400-e29b-41d4-a716-446655440003",
  "request_id": "req-550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-05T10:30:00.100Z",

  "error": {
    "code": "INVALID_CONTEXT",
    "message": "Context files array cannot be empty",
    "details": {
      "field": "context.files",
      "constraint": "minItems: 1"
    }
  }
}
```

---

## 11. Operations

### 11.1 Assess Task

Assess a task's SHIP Score before execution.

**Endpoint:** `POST /ship/assess`
**Request:** ShipRequest
**Response:** ShipResponse or ShipError

### 11.2 Submit Feedback

Report task outcome for learning.

**Endpoint:** `POST /ship/feedback`
**Request:** ShipFeedback
**Response:** `204 No Content` or ShipError

### 11.3 Get Provider Info

Retrieve provider capabilities.

**Endpoint:** `GET /ship/info`
**Response:**

```json
{
  "provider": "vibeatlas",
  "ship_version": "1.0",
  "capabilities": {
    "confidence_scoring": true,
    "focus_management": true,
    "context_optimization": true,
    "efficiency_tracking": true,
    "learning_enabled": true
  },
  "supported_languages": ["typescript", "javascript", "python", "go", "rust"],
  "supported_ai_tools": ["copilot", "cursor", "claude", "continue", "cody"],
  "rate_limits": {
    "requests_per_minute": 60,
    "requests_per_hour": 1000
  }
}
```

### 11.4 Get Badge

Retrieve SHIP badge for display.

**Endpoint:** `GET /ship/badge/{project_id}`
**Response:** SVG badge image

---

## 12. Error Handling

### 12.1 Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `INVALID_REQUEST` | 400 | Malformed request |
| `INVALID_CONTEXT` | 400 | Context validation failed |
| `MISSING_FIELD` | 400 | Required field missing |
| `UNAUTHORIZED` | 401 | Authentication failed |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `NOT_FOUND` | 404 | Resource not found |
| `RATE_LIMITED` | 429 | Rate limit exceeded |
| `INTERNAL_ERROR` | 500 | Server error |
| `TIMEOUT` | 504 | Processing timeout |

### 12.2 Retry Strategy

Consumers SHOULD implement exponential backoff:

- 1st retry: 1 second
- 2nd retry: 2 seconds
- 3rd retry: 4 seconds
- Maximum retries: 3

---

## 13. Security Considerations

### 13.1 Authentication

Providers MUST support at least one authentication method:

- **API Keys** (REQUIRED): `Authorization: Bearer {api_key}`
- **OAuth 2.0** (OPTIONAL): Standard OAuth flows
- **JWT** (OPTIONAL): Short-lived tokens

### 13.2 Data Privacy

1. Providers MUST NOT store code content without explicit consent
2. Providers MUST support data deletion requests (GDPR compliance)
3. Providers SHOULD offer local-only processing options
4. All transmission MUST use HTTPS/TLS 1.2+

### 13.3 Secret Detection

Providers MUST scan context for secrets and either:
- Redact secrets before processing
- Warn users about detected secrets
- Refuse to process context containing secrets

---

## 14. Conformance

### 14.1 Provider Conformance Levels

#### Level 1: Basic

Provider MUST:
- Return valid ShipResponse for any valid ShipRequest
- Calculate accurate SHIP Score
- Support `/ship/assess` endpoint
- Use HTTPS

#### Level 2: Standard

Provider MUST meet Level 1 AND:
- Provide Confidence Layer assessment
- Provide Focus Layer assessment
- Support `/ship/feedback` endpoint
- Support badge generation

#### Level 3: Full

Provider MUST meet Level 2 AND:
- Provide Context Layer assessment
- Provide Efficiency Layer assessment
- Support learning from feedback
- Provide explainable scores

### 14.2 Certification

Providers may apply for SHIP Certification by:

1. Running the SHIP Conformance Test Suite
2. Passing all required tests for target level
3. Submitting results to ship.vibeatlas.dev/certify

Certified providers receive:
- Official SHIP Certified badge
- Listing on ship.vibeatlas.dev/providers
- Access to SHIP trademark for marketing

### 14.3 Consumer Conformance

Consumers SHOULD:
- Display SHIP Score prominently
- Show score breakdown on request
- Submit feedback for task outcomes
- Respect provider rate limits

---

## 15. Ecosystem

### 15.1 Badges

#### README Badge

```markdown
[![SHIP Score](https://ship.vibeatlas.dev/badge/your-project)](https://ship.vibeatlas.dev/your-project)
```

#### Status Badges

| Badge | Score Range |
|-------|-------------|
| ![SHIP Elite](https://img.shields.io/badge/SHIP-Elite-gold) | 95-100 |
| ![SHIP Ready](https://img.shields.io/badge/SHIP-Ready-green) | 90-94 |
| ![SHIP Review](https://img.shields.io/badge/SHIP-Review-yellow) | 80-89 |
| ![SHIP Caution](https://img.shields.io/badge/SHIP-Caution-orange) | 70-79 |
| ![SHIP Warning](https://img.shields.io/badge/SHIP-Warning-red) | 50-69 |

### 15.2 CLI Tool

```bash
# Install
npm install -g @ship-protocol/cli

# Assess a task
ship assess --file src/main.ts --task "Add error handling"

# Check project score
ship score

# Submit feedback
ship feedback --request-id req-123 --success true
```

### 15.3 GitHub Action

```yaml
name: SHIP Check
on: [pull_request]

jobs:
  ship:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ship-protocol/ship-action@v1
        with:
          threshold: 85
          fail-on-low-score: true
```

### 15.4 VS Code Extension

```json
{
  "contributes": {
    "commands": [
      {
        "command": "ship.assessTask",
        "title": "SHIP: Assess Current Task"
      },
      {
        "command": "ship.showScore",
        "title": "SHIP: Show Score"
      }
    ]
  }
}
```

### 15.5 Leaderboards

Public leaderboards for:
- **Tools**: AI tools ranked by average SHIP Score
- **Projects**: Open source projects by SHIP Score
- **Organizations**: Companies by First-SHIP Rate

Leaderboard inclusion is opt-in.

---

## 16. Versioning

### 16.1 Protocol Versioning

SHIP follows Semantic Versioning:

- **Major** (1.x.x): Breaking changes
- **Minor** (x.1.x): New features (backward compatible)
- **Patch** (x.x.1): Bug fixes

### 16.2 Version Negotiation

- Consumers MUST send `ship_version` in requests
- Providers MUST return error for unsupported versions
- Providers SHOULD support at least 2 major versions

### 16.3 Deprecation Policy

- Features deprecated with 6 months notice
- Deprecated features supported for 12 months minimum
- Migration guides provided for all breaking changes

---

## 17. Examples

### 17.1 Simple Assessment

```bash
curl -X POST https://api.ship.vibeatlas.dev/ship/assess \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "SHIP-Version: 1.0" \
  -d '{
    "ship_version": "1.0",
    "message_type": "ShipRequest",
    "message_id": "example-001",
    "timestamp": "2025-12-05T10:30:00Z",
    "task": {
      "description": "Add logging to this function"
    },
    "context": {
      "files": [
        {
          "path": "main.ts",
          "content": "function hello() { return \"world\"; }",
          "language": "typescript"
        }
      ]
    }
  }'
```

### 17.2 Response

```json
{
  "ship_version": "1.0",
  "message_type": "ShipResponse",
  "message_id": "resp-example-001",
  "request_id": "example-001",
  "timestamp": "2025-12-05T10:30:00.100Z",

  "ship_score": 94,
  "ship_status": "ready",
  "ship_label": "SHIP-Ready",

  "confidence": {
    "score": 96,
    "completion_probability": 0.96,
    "confidence_level": "very_high"
  },

  "focus": {
    "score": 92,
    "attention_utilization": 0.95
  },

  "context": {
    "score": 95,
    "relevance": 0.98
  },

  "efficiency": {
    "score": 88,
    "tokens_saved": 0
  }
}
```

---

## Appendices

### Appendix A: JSON Schema

Full JSON schemas available at:
https://ship.vibeatlas.dev/schemas/v1.0/

### Appendix B: TypeScript Types

Full TypeScript definitions available at:
https://github.com/vibeatlas/ship-protocol/tree/main/types

### Appendix C: OpenAPI Specification

Full OpenAPI 3.0 spec available at:
https://ship.vibeatlas.dev/openapi.yaml

### Appendix D: Reference Implementation

Reference implementation available at:
https://github.com/vibeatlas/ship-protocol-reference

### Appendix E: Conformance Test Suite

Conformance tests available at:
https://github.com/vibeatlas/ship-conformance

### Appendix F: Change Log

**v1.0.0** (2025-12-05):
- Initial release
- Four-layer architecture (Confidence, Focus, Context, Efficiency)
- SHIP Score calculation
- Badge and certification system
- CLI and GitHub Action support

---

## Acknowledgments

SHIP Protocol was developed by the VibeAtlas team with input from the developer community. Special thanks to:

- The OpenTelemetry project for observability patterns
- The GraphQL Foundation for specification structure inspiration
- Early adopters who provided feedback during development

---

## License

Copyright 2025 VibeAtlas

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification and associated documentation files (the "Specification"), to deal in the Specification without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification.

THE SPECIFICATION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

---

## Contact

- **Website**: https://ship.vibeatlas.dev
- **GitHub**: https://github.com/vibeatlas/ship-protocol
- **Issues**: https://github.com/vibeatlas/ship-protocol/issues
- **Discord**: https://discord.gg/ship-protocol
- **Twitter**: @SHIPProtocol
- **Email**: ship@vibeatlas.dev

---

**Ship with confidence. Every time.**