{ "policy": { "version": 5, "patterns": { "version": 1, "method": "CURATED_PRACTICE_TOPIC", "notice": "Pattern topics identify design choices to practice. Read the ticket's acceptance criteria and justify the simplest suitable approach. Tags are not capability or ownership evidence; an untagged ticket has no curated pattern topic assigned." }, "fieldMix": { "version": 1, "method": "CURATED_ESTIMATE", "notice": "Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence." }, "contentStatus": "PRACTICE_BRIEF", "assessmentStatus": "NOT_QUALIFIED", "evidenceUse": "NONE", "aiPolicy": "AI tools are welcome during implementation. Record assumptions, review the result, and verify its behavior.", "notice": "Fictional engineering practice briefs. Starter repositories, fixtures, automated grading, and verified ownership are not included.", "outcomeEvidence": "Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.", "ownershipEvidence": "Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence." }, "patternTopics": [ { "id": "factory-method", "label": "Factory Method", "group": "Creational" }, { "id": "abstract-factory", "label": "Abstract Factory", "group": "Creational" }, { "id": "builder", "label": "Builder", "group": "Creational" }, { "id": "prototype", "label": "Prototype", "group": "Creational" }, { "id": "singleton", "label": "Singleton", "group": "Creational" }, { "id": "adapter", "label": "Adapter", "group": "Structural" }, { "id": "bridge", "label": "Bridge", "group": "Structural" }, { "id": "composite", "label": "Composite", "group": "Structural" }, { "id": "decorator", "label": "Decorator", "group": "Structural" }, { "id": "facade", "label": "Facade", "group": "Structural" }, { "id": "flyweight", "label": "Flyweight", "group": "Structural" }, { "id": "proxy", "label": "Proxy", "group": "Structural" }, { "id": "chain-of-responsibility", "label": "Chain of Responsibility", "group": "Behavioral" }, { "id": "command", "label": "Command", "group": "Behavioral" }, { "id": "interpreter", "label": "Interpreter", "group": "Behavioral" }, { "id": "iterator", "label": "Iterator", "group": "Behavioral" }, { "id": "mediator", "label": "Mediator", "group": "Behavioral" }, { "id": "memento", "label": "Memento", "group": "Behavioral" }, { "id": "observer", "label": "Observer", "group": "Behavioral" }, { "id": "state", "label": "State", "group": "Behavioral" }, { "id": "strategy", "label": "Strategy", "group": "Behavioral" }, { "id": "template-method", "label": "Template Method", "group": "Behavioral" }, { "id": "visitor", "label": "Visitor", "group": "Behavioral" }, { "id": "ports-and-adapters", "label": "Ports and Adapters", "group": "Architectural" }, { "id": "cqrs", "label": "CQRS", "group": "Architectural" }, { "id": "strangler-fig", "label": "Strangler Fig", "group": "Architectural" }, { "id": "saga", "label": "Saga", "group": "Distributed and reliability" }, { "id": "transactional-outbox", "label": "Transactional Outbox", "group": "Distributed and reliability" }, { "id": "circuit-breaker", "label": "Circuit Breaker", "group": "Distributed and reliability" }, { "id": "bulkhead", "label": "Bulkhead", "group": "Distributed and reliability" } ], "projects": [ { "id": "7dedf604-7124-4e19-9376-9b04b468e3ad", "key": "BAPIVER", "title": "Public API version transition", "field": "API design", "summary": "Evolve a partner API with explicit compatibility, deprecation, and client migration contracts.", "context": "A fictional inventory platform must replace a legacy availability response. Existing partners upgrade on different schedules, and the team needs a versioned transition.", "stack": [ "TypeScript", "OpenAPI", "HTTP" ], "prerequisites": [ "Create two local API versions and synthetic partner clients with different upgrade schedules; no real partner traffic." ], "developerValue": "Practice public-contract design, compatible evolution, and client lifecycle management.", "companyValue": "Provide a predictable migration that keeps supported integrations inspectable and recoverable.", "delivery": "Deliver local versioned contracts, compatibility checks, and a deprecation packet.", "phases": [ { "id": "design", "title": "Design version semantics", "goal": "Identify changes and supported compatibility." }, { "id": "implement", "title": "Implement coexistence", "goal": "Serve explicit contracts and safe migration behavior." }, { "id": "retire", "title": "Manage deprecation", "goal": "Verify client migration and retirement conditions." } ], "tickets": [ { "id": "3aac7642-5850-464f-9bcd-ffecd89b2df8", "key": "BAPIVER-101", "title": "Inventory breaking and additive availability-contract changes", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "design", "dependsOn": [], "scenario": "The proposed response renames fields and changes unknown stock from null to zero.", "acceptanceCriteria": [ "Classify each request and response change.", "Preserve unknown versus zero semantics.", "Identify supported legacy behavior explicitly." ], "implementationNotes": [ "Use actual local contract examples rather than general compatibility slogans." ], "verification": [ "Classify an optional additive field.", "Flag a meaning-changing null-to-zero conversion." ], "deliverables": [ "Contract change inventory." ], "rollout": "Review the inventory before choosing a versioning approach.", "skills": [ "API compatibility" ], "fieldMix": [ { "field": "API design", "percentage": 100 } ], "patterns": [] }, { "id": "67ed328e-e997-4276-bec3-a7b036f2fcac", "key": "BAPIVER-102", "title": "Define version selection and unsupported-version errors", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "design", "dependsOn": [ "BAPIVER-101" ], "scenario": "Clients cannot tell which contract a request will receive.", "acceptanceCriteria": [ "Choose one explicit version selection rule.", "Document a deterministic default only if retained intentionally.", "Return structured errors for unsupported versions." ], "implementationNotes": [ "Keep routes under /api/v1 and /api/v2 in the scenario." ], "verification": [ "Request each supported version.", "Request an unknown version and inspect its documented problem response." ], "deliverables": [ "Version selection contract." ], "rollout": "Introduce explicit selection before changing existing defaults.", "skills": [ "REST design" ], "fieldMix": [ { "field": "API design", "percentage": 100 } ], "patterns": [] }, { "id": "bd1370bd-be60-4017-9812-eb8426573d40", "key": "BAPIVER-103", "title": "Keep legacy and new projections over one domain authority", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "implement", "dependsOn": [ "BAPIVER-102" ], "scenario": "Separate version handlers duplicate inventory rules and begin disagreeing.", "acceptanceCriteria": [ "Share domain availability calculation.", "Map into distinct immutable transport schemas.", "Preserve version-specific unknown-state semantics." ], "implementationNotes": [ "Controllers cannot bypass tenant-scoped service reads." ], "verification": [ "Project one domain result into both versions.", "Deny cross-tenant reads through either route." ], "deliverables": [ "Versioned projection boundary." ], "rollout": "Ship the new projection alongside the old; retain identical domain invariants.", "skills": [ "Architecture", "Authorization" ], "fieldMix": [ { "field": "API design", "percentage": 50 }, { "field": "System design", "percentage": 30 }, { "field": "Backend", "percentage": 20 } ], "patterns": [] }, { "id": "d68e7df7-a9c4-455a-a0a5-640ea6289750", "key": "BAPIVER-104", "title": "Use Problem Details for versioned validation failures", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "implement", "dependsOn": [ "BAPIVER-103" ], "scenario": "Partners parse changing human messages to detect invalid warehouse filters.", "acceptanceCriteria": [ "Publish stable problem types and field paths.", "Keep instance and request identifiers safe.", "Version any materially changed error semantics." ], "implementationNotes": [ "Exclude stack traces and internal database details." ], "verification": [ "Validate a malformed filter in both versions.", "Verify cross-tenant denial reveals no private identifiers." ], "deliverables": [ "Error contract examples." ], "rollout": "Add structured fields compatibly and document client handling.", "skills": [ "Error design" ], "fieldMix": [ { "field": "API design", "percentage": 80 }, { "field": "Security", "percentage": 20 } ], "patterns": [] }, { "id": "6c06777e-2b8a-4462-8e8b-0f4833141baf", "key": "BAPIVER-105", "title": "Preserve idempotency semantics across client version upgrades", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "implement", "dependsOn": [ "BAPIVER-103", "BAPIVER-104" ], "scenario": "A client retries an inventory reservation with the same key after upgrading its API version.", "acceptanceCriteria": [ "Define whether keys bind to normalized domain intent or transport version.", "Reject conflicting reuse consistently.", "Prevent duplicate domain effects across supported routes." ], "implementationNotes": [ "Document the chosen scope rather than silently translating incompatible requests." ], "verification": [ "Replay equivalent supported requests under the chosen policy.", "Reject a changed reservation under the same key." ], "deliverables": [ "Cross-version idempotency contract." ], "rollout": "Retain original operation facts during migration.", "skills": [ "Idempotency", "Compatibility" ], "fieldMix": [ { "field": "API design", "percentage": 50 }, { "field": "Distributed systems", "percentage": 30 }, { "field": "Backend", "percentage": 20 } ], "patterns": [] }, { "id": "bd22832d-4482-41ea-868c-73c4a7d5db6a", "key": "BAPIVER-106", "title": "Generate SDK migration examples from packaged client versions", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "implement", "dependsOn": [ "BAPIVER-104", "BAPIVER-105" ], "scenario": "Migration documentation uses methods not present in the released client archive.", "acceptanceCriteria": [ "Compile old and new examples against local packaged clients.", "Show equivalent availability and error handling.", "Document changed optional and nullable fields." ], "implementationNotes": [ "Use local archives and mock servers only." ], "verification": [ "Run both documented examples.", "Detect a snippet importing a removed method." ], "deliverables": [ "Executable SDK migration examples." ], "rollout": "Publish examples with the matching contract revision.", "skills": [ "SDK lifecycle", "Documentation" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "9b9473c4-4dc7-4c27-9c67-994466dca3d8", "key": "BAPIVER-107", "title": "Expose deprecation signals without breaking successful responses", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "retire", "dependsOn": [ "BAPIVER-106" ], "scenario": "Partners need machine-readable notice that the old version has a planned sunset.", "acceptanceCriteria": [ "Document deprecation metadata and dates.", "Keep response behavior compatible during support.", "Link a versioned migration guide." ], "implementationNotes": [ "Dates are fictional scenario inputs and must be labeled in fixtures." ], "verification": [ "Read a legacy response with deprecation metadata.", "Verify the new version does not carry an incorrect retirement notice." ], "deliverables": [ "Deprecation response contract." ], "rollout": "Enable notice before any retirement gate.", "skills": [ "API lifecycle" ], "fieldMix": [ { "field": "API design", "percentage": 100 } ], "patterns": [] }, { "id": "14dd8cba-1d1a-45dd-851e-d365f318015b", "key": "BAPIVER-108", "title": "Measure version adoption using bounded non-sensitive metadata", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "retire", "dependsOn": [ "BAPIVER-107" ], "scenario": "The team wants to know whether supported clients still use the old version without collecting request bodies.", "acceptanceCriteria": [ "Count requests by declared client class and API version.", "Track unknown client versions separately.", "Exclude tokens, payloads, and personal identifiers." ], "implementationNotes": [ "Do not equate no observed traffic with confirmed migration." ], "verification": [ "Report synthetic mixed-version traffic.", "Show an inactive client as unknown rather than migrated." ], "deliverables": [ "Adoption report." ], "rollout": "Use counts as one input to retirement review; preserve explicit client support records.", "skills": [ "Observability", "Privacy" ], "fieldMix": [ { "field": "API design", "percentage": 40 }, { "field": "Privacy engineering", "percentage": 30 }, { "field": "Site reliability", "percentage": 30 } ], "patterns": [] }, { "id": "70a1e47b-b7fc-4969-966f-e9e9785b45e5", "key": "BAPIVER-109", "title": "Decide retirement with client obligations and rollback constraints", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 300, "phaseId": "retire", "dependsOn": [ "BAPIVER-105", "BAPIVER-108" ], "scenario": "The old API has little traffic but one supported partner still relies on its unknown-stock behavior.", "acceptanceCriteria": [ "Define retirement criteria beyond traffic volume.", "Compare support cost, partner migration risk, and data compatibility.", "Rehearse restoring legacy routing after a failed retirement." ], "implementationNotes": [ "Keep unsupported assumptions visible; no actual partner notifications are sent." ], "verification": [ "Retire a fully migrated synthetic client set.", "Block retirement when a supported dependency remains unresolved." ], "deliverables": [ "API retirement decision record." ], "rollout": "Use a staged local retirement and retain tested legacy artifacts through the rollback window.", "skills": [ "API strategy", "Tradeoff analysis" ], "fieldMix": [ { "field": "API design", "percentage": 60 }, { "field": "System design", "percentage": 20 }, { "field": "Site reliability", "percentage": 20 } ], "patterns": [] }, { "id": "16bca313-38b5-4c15-b9b1-399deaedc2c1", "key": "BAPIVER-110", "title": "Write the partner migration checklist with observable completion", "type": "CHORE", "priority": "LOW", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "retire", "dependsOn": [ "BAPIVER-109" ], "scenario": "A checklist saying 'upgrade the SDK' misses changed error and unknown-state handling.", "acceptanceCriteria": [ "List client-code, error, and data-semantic changes.", "Include local verification commands.", "Define completion through exercised operations." ], "implementationNotes": [ "Do not claim a partner migrated without recorded confirmation." ], "verification": [ "Migrate the synthetic client using the checklist.", "Catch a client still treating unknown stock as zero." ], "deliverables": [ "Partner migration guide." ], "rollout": "Version the guide and retain legacy instructions for supported clients.", "skills": [ "Technical writing" ], "fieldMix": [ { "field": "API design", "percentage": 70 }, { "field": "Developer tooling", "percentage": 30 } ], "patterns": [] } ] } ] }