feat!: breaking changes v1.5.0 — remove phone field + narrow order status enum

[zsobpeter-code]

feat: remove phone field and delivered status enum (v1.5.0)

[coderifts]

🔴 BLOCK | Risk: 57/100 | 3 breaking changes

❌ Decision: BLOCK • 🟡 Risk: 57/100 • ❌ Breaking: 3 • 🔍 Patterns: 5

🟡 CodeRifts — Risk Score: 57/100 (Moderate)

🏷️ Suggested version bump: MAJOR 🔴 — 3 breaking changes detected

📌 Current version is v1.4.0 → next version should be v2.0.0

❌ Why This PR Is Blocked

This PR is blocked because a HIGH pattern (ENUM_NARROWING) was detected.

✅ How to Unblock

• Review the ENUM_NARROWING pattern and assess its impact on existing consumers
• Consider versioning this change under a new API path
• Split this PR — merge non-breaking changes separately

🔬 Decision Audit — Ω_API V3

Component	Value	Evidence	Note
Ω_API	46.17	—	Final score
Decision	BLOCK	—	(reflex override)
Confidence	48%	—	15 components
S_contract	92.9	🟢 high	τ_repo: 25
D_contract	66	⚪ unavailable	response_field_removed ×10, response_field_removed ×10
P_break	78.9%	🟡 medium
S_blast	36	🔴 low	raw blast radius
S_propagation	22	🔴 low	heuristic V2
S_agent	23	🟢 high	TOOL_RESULT_SHAPE_DRIFT ×15, SHARED_STATE_SCHEMA_DRIFT ×8
S_runtime	65	🔴 low	heuristic V1
S_resilience	0	🔴 low	heuristic V3
S_evolution	0	⚪ unavailable	< 5 analyses in repo
ECI	57	⚪ unavailable
M_eff	27	⚪ unavailable
A_consumer	54	🔴 low	heuristic V2
V_api	unavailable	⚪ unavailable	< 5 analyses in repo

Reflex triggers:

• TOOL_RESULT_SHAPE_DRIFT ∧ tool_calling_enabled → BLOCK
• ENUM_NARROWING (breaking enum contract) → BLOCK
• tool_result_shape_drift ∧ agent_workflow → REQUIRE_APPROVAL

Pattern config hash: 198282b

### Risk Assessment

Dimension	Score	Detail
💰 Revenue Impact	12/25	Affects /users (high — heuristic)
⚡ Blast Radius	9/25	2 public endpoint(s) affected, 3 breaking changes in single PR
📱 App Compatibility	12/25	Breaks iOS 3.2, Android 4.0
🔒 Security	5/25	OAuth scope changed

📊 API Stability Grade: C (moderate risk)
🔄 Rollback risk (estimated): 🟡 Moderate revert effort
⏱️ Review effort: ~30 min
🚀 Deployment: Standard deployment

📦 Generator, AI-spec & SDK impact (2)

🔧 Generator Impact Analysis

Detected generators:

Generator	Config	Output Surfaces	Risk Multiplier
OpenAPI Generator	openapitools.json	typescript-axios, java	1.5x

⚠️ Risk amplified: 1.5x — Breaking changes in this repo cascade into 2 auto-generated surfaces. Each affected surface requires SDK regeneration, testing, and release.

💡 Tip: Consider running openapi-generator validate before merging.

📦 SDK Surface Impact

2 generated SDKs detected in this repository:

SDK	Generator	Affected Models	Affected Methods	Severity
TypeScript	OpenAPI Generator	3	0	🟠 Medium
Java	OpenAPI Generator	3	0	🟠 Medium

Total SDK impact: 6 models and 0 methods across 2 SDKs need regeneration.

⚠️ After merging, regenerate all affected SDKs and publish new versions before consumers update.

🔍 Top Detected Patterns

Pattern	Severity	Consequence
ENUM_NARROWING	🟠 HIGH	Consumers sending removed values will receive validation errors.
ENUM_NARROWING	🟠 HIGH	Consumers sending removed values will receive validation errors.
ENUM_NARROWING	🟠 HIGH	Consumers sending removed values will receive validation errors.

Showing top 3 of 5 detected patterns by severity.

🔴 3 Breaking Changes Found

#	Change	Endpoint	Risk	Intent	Confidence	Lifecycle	Details
1	🔴 Field removed from response	POST /users	⚡ Public	🏗️ Structural	🟡 Medium	🆕	add
2	🔴 Field removed from response	GET /users/{id}	⚡ Public	🏗️ Structural	🟡 Medium	🆕	add
3	🔴 request-property-enum-value-removed	Unknown endpoint	⚡ Public	⚙️ Behavioral	🟢 High	🪦	Enum value 'delivered' removed from 'status' in schema 'Order'

Change intent breakdown: 2 structural · 1 behavioral
Detection confidence: 1 high · 2 medium (avg 65/100)

🤖 Agent Impact

Change	Agent Risk	Impact
response-body-scope-add	🟡 MEDIUM	API contract changed at /users — agents depending on this behavior may fail
response-body-scope-add	🟡 MEDIUM	API contract changed at /users/{id} — agents depending on this behavior may fail
request-property-enum-value-removed	🟡 MEDIUM	API contract changed at unknown — agents depending on this behavior may fail

🤖 Agent impact analysis identifies how breaking changes affect AI agents, MCP tools, and automated workflows. Learn more

🔧 Suggested migration snippets

🤖 How to update your agent

The following breaking changes affect AI agent workflows. Platform-specific starter code below — substitute the real field types and auth scopes from your schema:

Tool result shape changed (TOOL_RESULT_SHAPE_DRIFT)

Affects POST /users

Grok (result_adapter):

function normalize_users_result(data) {
  const out = { ...data };
  if (!Object.prototype.hasOwnProperty.call(out, 'field')) {
    out['field'] = Object.prototype.hasOwnProperty.call(out, 'field')
      ? out['field'] : null;
  }
  return out;
}

Claude (tool_result_adapter):

def normalize_users_result(data: dict) -> dict:
    out = dict(data)
    if 'field' not in out:
        out['field'] = out.get('field', None)
    return out

Copilot (prompt_file_update):

# .github/prompts/users-result-normalizer.prompt.md
Normalize users results before downstream use.
If field is missing and field exists,
map: field <- field
If both missing, set field = null.

Shared state schema changed (SHARED_STATE_SCHEMA_DRIFT)

Affects POST /users

Grok (state_normalizer):

function normalizeSharedState(state) {
  return { ...state,
    'field': state['field'] ?? state['field'] ?? null
  };
}

Claude (state_normalizer):

def normalize_shared_state(state: dict) -> dict:
    out = dict(state)
    if 'field' not in out:
        out['field'] = out.get('field', null)
    return out

Copilot (agent_profile_update):

Shared state contract:
preferred: field compatibility: field
On read: use field first, then field, then null.
On write: populate both during migration window.

📝 API Changelog

Breaking

• Removed field phone from POST /users response
• Removed field phone from GET /users/{id} response
• Breaking change in Enum value 'delivered' removed from 'status' in schema 'Order' — request-property-enum-value-removed

Added

• New optional field field in POST /users request

💡 Recommendations

• 📱 Mobile app update needed — Breaks iOS 3.2, Android 4.0
• 🔒 Security review required — OAuth scope changed
• 💰 Estimated migration impact — ~5 eng. day(s), ~$15,000

💾 Migration & Impact Assessment

Rollback risk (estimated): 🟡 Moderate revert effort
Review estimate: ⏱️ ~30 min

Icon	Trigger	Action needed
💾	New required field field in POST /users	Ensure database column exists with a default value for existing rows

✅ Pre-merge checklist

• Verify API documentation is updated
• Notify downstream consumers of breaking changes
• Update API client SDKs if applicable
• Check mobile app compatibility
• Run database migration before deploying
• Verify migration is backward-compatible (can roll back)

💰 Economic Impact Estimate

├── Migration cost: $18,000 (120 eng-hours × $150/hr)
├── Testing cost: $27,000 (180 eng-hours × $150/hr)
├── Rollback risk: $54,000 (if rollback needed)
├── Downstream consumers: 1 service
└── Total estimated impact: $45,000

📐 Heuristic estimate from configurable assumptions (engineer rate, migration hours, consumer count). Tune the 'cost' section in '.coderifts.yml' for your team. Estimate, not a precise quote.

ℹ️ CodeRifts detected this before merge. Monthly cost: $49. Estimated impact prevented: $45,000.

Change Impact Graph

flowchart LR
  API["API contract<br/>BLOCK · 3 breaking · $45,000"]
  C0["response-body-scope-add"] --> API
  C1["response-body-scope-add"] --> API
  C2["request-property-enum-value-removed"] --> API
  API -->|"3 impacted, MEDIUM"| AGENTS["AI agents"]
  API -->|"3 models"| SDK_TypeScript["TypeScript SDK"]
  API -->|"3 models"| SDK_Java["Java SDK"]

Loading

_{The API contract (hub), the breaking changes feeding it, and the consumers it fans out to. Full machine-readable graph via POST /api/v1/change-impact-graph.}

⏰ Deprecation Calendar

Endpoint	Deprecated Since	Scheduled Removal	Status
POST /payments/refund	—	2026-04-01 (-81d)	🔴 Overdue

👥 No CODEOWNERS file found. Consider adding one to auto-assign reviewers for API changes:

# .github/CODEOWNERS
# Auto-generated from .coderifts.yml domains
api/openapi.yaml  @payments-team @backend-team

📍 No URL versioning detected. Consider adopting URL versioning (e.g. /v1/, /v2/) to manage breaking changes safely.

📏 API Design Lint — 2 warnings

Rule	Endpoint	Details
⚠️ Path naming	/users	Plural /users — most paths use singular convention
⚠️ Path naming	/users/{id}	Plural /users — most paths use singular convention

⌛ Deprecation Lifecycle

Currently deprecated (not removed in this PR):

• POST /payments/refund — sunset: 2026-04-01 (-82 days remaining) → use POST /payments/v2/refund

⚠️ Generated Spec Drift Warning

The OpenAPI spec api/openapi.yaml appears to be generated by OpenAPI Generator but was modified directly in this PR.

Drift confidence: 40% (medium)

Detected signals:

• 🔧 Generator config was not changed in this PR
• ✏️ Source annotations/code were not modified

Risk: Manual changes to generated specs will be overwritten on next generation. This can cause:

• Silent loss of the changes in this PR
• Merge conflicts when regenerating
• Inconsistency between source code and API contract

Recommended actions:

1. Update the source (code annotations, config, or source spec) instead of editing the generated output
2. Regenerate the spec from the updated source
3. If this is an intentional override, add the file to .openapi-generator-ignore or generator_drift.ignore_files in .coderifts.yml

📖 Documentation Coverage

Overall coverage: 92% ↔️ (0 from base)

Schema	Score	Grade	Delta	Top Gap
api/openapi.yaml	92%	🟢 A (Excellent)	↔️ 0	Examples (44%)

📋 Raw diff details

• response.body.scope.add — paths./users.post.responses.201.content.application/json.schema (api/openapi.yaml)
• response.body.scope.add — paths./users/{id}.get.responses.200.content.application/json.schema (api/openapi.yaml)
• request-property-enum-value-removed — schemas.Order.status (api/openapi.yaml)
• request.body.scope.add — paths./users.post.requestBody.content.application/json.schema (api/openapi.yaml)

👥 Breaking change in users domain — notify @backend-team

📝 Documentation Drift

⚠️ 3 breaking changes detected but no documentation files were updated in this PR.

Consider updating: README.md, API docs, or CHANGELOG before merging.

🏛️ Governance Health: A (95/100)

📋 Policy

Rule	Condition	Action	Status
block-endpoint-removal	endpoint_removed	BLOCK	✅ not triggered
warn-high-risk	risk_score >= 80	WARN	✅ not triggered

Effective action: ALLOW

⚠️ Schema Overlap Warning

Other open PRs also modify the same OpenAPI spec files. Merging this PR may cause conflicts or inconsistent changes in:

PR	Spec File	Status
#2 — feat: migrate payment API to v2 schema	api/openapi.yaml	Open (111 days)
#3 — Update openapi.yaml	api/openapi.yaml	Open (100 days)
#1 — fix: update API schema for v2 migration	api/openapi.yaml	Open (116 days)

💡 Tip: Coordinate with these PR authors before merging. Consider rebasing after one PR is merged.

📋 Action Items

• Review all breaking changes above
• Update MCP manifest if agent-facing endpoints changed
• Prepare consumer-facing changelog
• Define rollout plan before merge

---

📊 API surface: 9 endpoints · 29 fields · 9 schemas
⚙️ Configure in .coderifts.yml · 🔗 CodeRifts

---

🎋 A few cracks appear
🎋 In the contract we once kept
🎋 Review before merge

---

☁️ You're on the Free plan. Pro features (risk scoring, governance, deprecation enforcement) are included during the beta. Lock in Pro pricing →

⏱️ PR Review Insights

This PR

Metric	Value	Benchmark
Time to First Review	Awaiting review	—
Review Rounds	0	🟢 Normal
PR Size	+2 / -11	🟢 Small

🌐 Cross-Repo Impact

This PR affects downstream consumers:

Consumer Repo	Criticality	Risk
coderifts/example	🔴 Critical	Breaking changes may cascade

1 downstream repo affected. Notify consumer teams before merging.

✅ Pre-merge Checklist

Before merging this PR, verify:

• Backward compatibility reviewed for all breaking changes
• Changelog prepared for downstream consumers
• Rollout plan defined (monitor closely after deploy)
• Database migration tested if schema changes detected
• SDK regeneration scheduled (5 generated SDKs affected)
• Consumer team notified (1 downstream repo registered)

🧬 Lesion Simulator

Pre-release resilience test: 9 micro-injuries tested.

Lesion	Target	Decision	Severity
ENDPOINT_REMOVAL	GET /users/{id}	🔴 BLOCK	HIGH
ENDPOINT_REMOVAL	POST /users	🔴 BLOCK	HIGH
ENDPOINT_REMOVAL	GET /orders	🔴 BLOCK	HIGH
AUTH_REMOVAL	Security removed from GET /users/{id}	🟡 REQUIRE_APPROVAL	LOW
AUTH_REMOVAL	Security removed from POST /users	🟡 REQUIRE_APPROVAL	LOW
AUTH_REMOVAL	Security removed from GET /orders	🟡 REQUIRE_APPROVAL	LOW
REQUIRED_FIELD_ADDED	Added required field '_lesion_required_field' to POST /users	🟡 REQUIRE_APPROVAL	LOW
REQUIRED_FIELD_ADDED	Added required field '_lesion_required_field' to POST /orders	🟡 REQUIRE_APPROVAL	LOW
REQUIRED_FIELD_ADDED	Added required field '_lesion_required_field' to POST /payments/charge	🟡 REQUIRE_APPROVAL	LOW

Resilience Score: 0/100 (F)
3 critical lesions detected. This API is fragile — small changes cause major downstream impact.