{ "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": "f5ebda46-c420-4558-b7d0-a26edd8ce981", "key": "BSDKGEN", "title": "Deterministic SDK publishing pipeline", "field": "Developer tooling", "summary": "Turn a public API schema into reviewable client changes and reproducible packages.", "context": "A fictional partner platform publishes TypeScript clients. Generator upgrades create noisy diffs, occasional runtime mismatches, and uncertainty about which schema was packaged.", "stack": [ "TypeScript", "OpenAPI", "Node.js" ], "prerequisites": [ "Create a small public API schema and two local mock server versions; use a temporary local package registry or archive files." ], "developerValue": "Practice reproducible generation, compatibility reviews, and package provenance.", "companyValue": "Reduce partner integration surprises with reviewable clients and recoverable releases.", "delivery": "Deliver the local generation and packaging workflow with a compatibility report; publish nothing externally.", "phases": [ { "id": "contract", "title": "Pin inputs", "goal": "Specify schema and generator provenance." }, { "id": "generate", "title": "Generate predictably", "goal": "Produce usable stable clients and visible changes." }, { "id": "release", "title": "Verify packages", "goal": "Exercise installation, compatibility, and recovery locally." } ], "tickets": [ { "id": "48cef14f-82f7-4b7c-8ee6-981252d26c8e", "key": "BSDKGEN-101", "title": "Record the exact inputs behind a generated client", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 60, "phaseId": "contract", "dependsOn": [], "scenario": "A checked-in client cannot be traced to its schema revision.", "acceptanceCriteria": [ "Record schema digest, generator version, and options.", "Keep the manifest stable across machines.", "Fail when a required input is missing." ], "implementationNotes": [ "Avoid absolute paths and timestamps in generated content." ], "verification": [ "Compare manifests from two directories.", "Remove the schema and verify a clear failure." ], "deliverables": [ "Generation manifest." ], "rollout": "Introduce manifests before enforcing them; keep the previous complete client.", "skills": [ "Reproducibility" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 100 } ], "patterns": [] }, { "id": "33bc9c96-18c2-499b-b065-3083d2541de9", "key": "BSDKGEN-102", "title": "Normalize schema ordering without changing semantics", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "contract", "dependsOn": [ "BSDKGEN-101" ], "scenario": "Reordered schema properties create hundreds of irrelevant review lines.", "acceptanceCriteria": [ "Sort unordered maps deterministically.", "Preserve ordered examples and tuple definitions.", "Keep references resolvable after normalization." ], "implementationNotes": [ "Do not remove descriptions or validation constraints." ], "verification": [ "Compare equivalent reordered schemas.", "Detect a changed enum or required field." ], "deliverables": [ "Schema normalizer." ], "rollout": "Review semantic diffs before replacing the stored schema.", "skills": [ "OpenAPI", "Canonicalization" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "650ea7d7-627c-42ab-bf79-76976235ef3d", "key": "BSDKGEN-103", "title": "Separate transport code from generated resource methods", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "generate", "dependsOn": [ "BSDKGEN-102" ], "scenario": "Regeneration overwrites the timeout behavior partners configured manually.", "acceptanceCriteria": [ "Inject a stable transport interface.", "Regenerate resource methods without overwriting custom transport.", "Pass abort signals and request identifiers consistently." ], "implementationNotes": [ "Keep credentials out of generated examples." ], "verification": [ "Regenerate twice and compare output.", "Cancel a delayed mock request and verify transport cancellation." ], "deliverables": [ "Transport boundary and generated client." ], "rollout": "Retain the existing adapter until contract tests pass.", "skills": [ "Code generation", "HTTP" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 50 }, { "field": "API design", "percentage": 30 }, { "field": "Networking", "percentage": 20 } ], "patterns": [] }, { "id": "f3477d20-0a1a-44a1-b930-533e8aef70e1", "key": "BSDKGEN-104", "title": "Represent nullable and optional fields distinctly in clients", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "generate", "dependsOn": [ "BSDKGEN-103" ], "scenario": "An omitted patch field is serialized as null and clears a partner record.", "acceptanceCriteria": [ "Model omitted and explicit null independently.", "Omit undefined values during serialization.", "Preserve null only where the schema allows it." ], "implementationNotes": [ "Avoid broad type assertions that erase schema distinctions." ], "verification": [ "Patch one field without clearing another.", "Reject null for a non-nullable field." ], "deliverables": [ "Serialization correction." ], "rollout": "Release as a reviewed compatibility fix; restore the prior artifact if unrelated payloads change.", "skills": [ "TypeScript", "Serialization" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [] }, { "id": "3cc72489-0624-4f17-8ba9-0f5d2989018d", "key": "BSDKGEN-105", "title": "Generate errors that preserve safe machine-readable details", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "generate", "dependsOn": [ "BSDKGEN-103" ], "scenario": "Client users currently parse human error messages to detect conflicts.", "acceptanceCriteria": [ "Expose status, problem type, and safe request ID.", "Handle non-JSON failures without crashing the parser.", "Exclude authorization headers from error objects." ], "implementationNotes": [ "Bound retained response-body bytes." ], "verification": [ "Parse a conflict and a text gateway error.", "Verify oversized and secret-bearing responses stay bounded and sanitized." ], "deliverables": [ "Typed error mapping." ], "rollout": "Keep message text compatible where practical; document structured fields.", "skills": [ "Error design", "SDK design" ], "fieldMix": [ { "field": "API design", "percentage": 50 }, { "field": "Developer tooling", "percentage": 30 }, { "field": "Security", "percentage": 20 } ], "patterns": [] }, { "id": "5e7621d9-2d9f-45bd-8f8e-b67be8982649", "key": "BSDKGEN-106", "title": "Detect breaking schema changes before rebuilding packages", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 240, "phaseId": "generate", "dependsOn": [ "BSDKGEN-102" ], "scenario": "A required request property was added without a major-version discussion.", "acceptanceCriteria": [ "Classify request and response changes separately.", "Flag removed operations and narrowed accepted values.", "Require an explicit reviewed explanation for allowed exceptions." ], "implementationNotes": [ "Do not treat every additive response field as breaking." ], "verification": [ "Detect a required-input addition.", "Accept a documented additive field and reject an expired exception." ], "deliverables": [ "Compatibility diff command." ], "rollout": "Run advisory first; enforce after reviewing known baseline exceptions.", "skills": [ "Compatibility", "API contracts" ], "fieldMix": [ { "field": "API design", "percentage": 60 }, { "field": "Developer tooling", "percentage": 40 } ], "patterns": [] }, { "id": "c3bbb58d-d67e-4e1c-8150-8335516b6f87", "key": "BSDKGEN-107", "title": "Test a packaged client from a clean consumer directory", "type": "TASK", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "release", "dependsOn": [ "BSDKGEN-104", "BSDKGEN-105" ], "scenario": "The client works in the monorepo but its published archive omits runtime files.", "acceptanceCriteria": [ "Install the local archive outside the workspace.", "Exercise ESM imports and declared type exports.", "Verify the archive excludes fixtures and credentials." ], "implementationNotes": [ "Use local archives; no public publication or real account required." ], "verification": [ "Run a request against the mock server.", "Remove an exported file and detect the package failure." ], "deliverables": [ "Clean-consumer smoke check." ], "rollout": "Gate local release candidates on archive validation.", "skills": [ "Packaging", "Module systems" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [] }, { "id": "98ecf16d-c77e-4b54-8d17-87427bb62b9f", "key": "BSDKGEN-108", "title": "Make generated examples compile against their advertised version", "type": "CHORE", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "release", "dependsOn": [ "BSDKGEN-107" ], "scenario": "Documentation snippets refer to methods removed two releases ago.", "acceptanceCriteria": [ "Compile examples using the packaged client.", "Pin examples to a release identifier.", "Show credential placeholders without usable secrets." ], "implementationNotes": [ "Examples must call the local mock service only." ], "verification": [ "Run the basic read and paginated examples.", "Detect a snippet using a removed method." ], "deliverables": [ "Executable example suite." ], "rollout": "Update examples together with packages; retain versioned previous examples.", "skills": [ "Documentation", "TypeScript" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 80 }, { "field": "Quality engineering", "percentage": 20 } ], "patterns": [] }, { "id": "3d0d4b21-53eb-47d2-986a-cad9952baf22", "key": "BSDKGEN-109", "title": "Design a release matrix for old servers and new clients", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 360, "phaseId": "release", "dependsOn": [ "BSDKGEN-106", "BSDKGEN-107" ], "scenario": "Partners upgrade clients and servers at different times, so latest-against-latest testing leaves a compatibility gap.", "acceptanceCriteria": [ "Declare supported client/server pairs and exclusions.", "Run representative operations against each local server version.", "Document unknown behavior rather than marking untested pairs supported." ], "implementationNotes": [ "Bound the matrix to two client and two server versions." ], "verification": [ "Exercise a supported mixed-version pair.", "Expose an incompatible removed operation as an expected documented failure." ], "deliverables": [ "Compatibility matrix and release recommendation." ], "rollout": "Promote only tested pairs; preserve previous client artifacts and migration instructions.", "skills": [ "Release engineering", "Compatibility" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 40 }, { "field": "API design", "percentage": 30 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [] }, { "id": "5ec76d10-0d6c-4c24-9300-67a6fc8070c6", "key": "BSDKGEN-110", "title": "Rehearse replacing a defective SDK archive locally", "type": "TASK", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "release", "dependsOn": [ "BSDKGEN-109" ], "scenario": "A release candidate accidentally retries non-idempotent requests, and maintainers need a recovery procedure.", "acceptanceCriteria": [ "Mark the defective local version as withdrawn in the index.", "Publish a distinct corrected local version without rewriting archives.", "Verify consumers can pin the last known usable version." ], "implementationNotes": [ "Never overwrite a versioned artifact." ], "verification": [ "Install the corrected package and previous usable package.", "Ensure the withdrawn version remains identifiable for diagnosis." ], "deliverables": [ "Local recovery rehearsal." ], "rollout": "Document withdrawal and pinning before external publication is ever considered.", "skills": [ "Artifact integrity", "Release operations" ], "fieldMix": [ { "field": "Developer tooling", "percentage": 60 }, { "field": "Platform engineering", "percentage": 40 } ], "patterns": [] } ] } ] }