{ "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": "a2a00730-a060-4d04-babd-f76268a10ce7", "key": "PPROVIDER", "title": "Evolve a notification boundary with predictable failure behavior", "field": "Integrations", "summary": "Support two incompatible notification providers while keeping domain decisions, instrumentation, and overload behavior explicit.", "context": "A fictional maintenance scheduler sends appointment notices through two providers. Their request shapes, error codes, and acknowledgement semantics differ. Build two local scripted provider doubles and a TypeScript application module; use synthetic recipients, block external network access, and never send real notifications. No provider accounts, starter repository, or production delivery qualification is supplied.", "stack": [ "TypeScript", "Node.js", "Vitest", "Local HTTP stubs" ], "prerequisites": [ "HTTP contracts", "Asynchronous cancellation", "Dependency injection" ], "developerValue": "Practice placing provider boundaries, comparing wrappers and coordinators, and testing ordering, cancellation, and resource limits under controlled faults.", "companyValue": "Review whether a provider change can be made without rewriting scheduling rules, leaking recipient data, or turning one provider failure into wider exhaustion.", "delivery": "Ten tickets over three phases. Create local provider doubles and contract fixtures, evolve the integration layer, and supply a fault replay plus an operational handoff.", "phases": [ { "id": "boundary", "title": "Define the provider boundary", "goal": "Separate scheduling intentions from transport details." }, { "id": "composition", "title": "Compose cross-cutting behavior", "goal": "Keep orchestration and wrapper ordering visible and testable." }, { "id": "resilience", "title": "Contain provider failure", "goal": "Bound outstanding work and verify recovery without duplicate delivery." } ], "tickets": [ { "id": "7912caf4-7c81-42e0-81bd-143826fc60f0", "key": "PPROVIDER-101", "title": "Normalize the second provider's acknowledgement without inventing delivery", "type": "STORY", "priority": "HIGH", "difficulty": "FOUNDATIONAL", "estimateMinutes": 120, "phaseId": "boundary", "dependsOn": [], "scenario": "Provider A returns accepted plus a request ID; provider B returns queued with a nested reference. The existing mapper calls both delivered, even though neither acknowledgement confirms a recipient received the notice.", "acceptanceCriteria": [ "Define a shared result contract for accepted, rejected, and unknown outcomes with provider identity and an optional provider reference.", "Map both declared acknowledgement shapes to accepted while preserving their references; never map acknowledgement alone to delivered.", "Malformed success payloads and unknown response codes return a typed integration error without exposing raw recipient data." ], "implementationNotes": [ "Use an Adapter for each local stub; preserve unsupported semantics explicitly rather than forcing every response into a success boolean." ], "verification": [ "Map representative A and B acknowledgements and compare the shared contract.", "Return a success status with a missing required reference and an undocumented state; assert explicit failure." ], "deliverables": [ "Provider adapters, shared result contract, and mapping fixtures" ], "rollout": "Run both adapters against local scripted responses before selecting B for synthetic requests; retain A's mapping for regression comparison.", "skills": [ "Adapter contracts", "Response validation", "Error modeling" ], "fieldMix": [ { "field": "Integrations", "percentage": 70 }, { "field": "API design", "percentage": 30 } ], "patterns": [ { "pattern": "adapter", "activity": "APPLY", "focus": "Translate incompatible acknowledgement payloads into a shared contract without overstating queued or accepted messages as delivered." } ] }, { "id": "ed6c44e0-a42c-4e6e-92af-aba377ad8812", "key": "PPROVIDER-102", "title": "Keep provider SDK types out of appointment rules", "type": "CHORE", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "boundary", "dependsOn": [ "PPROVIDER-101" ], "scenario": "Rescheduling logic imports provider B's request object and recognizes its numeric error codes. A provider SDK change now forces changes in domain tests that never make a network request.", "acceptanceCriteria": [ "Appointment logic depends on a small notification port using domain-owned request and result types.", "Place provider-specific mapping, serialization, and error interpretation in adapters selected at the composition boundary.", "Run appointment decisions against an in-memory port double with no provider package imports or transport initialization." ], "implementationNotes": [ "Keep this a module boundary in one process; the exercise does not justify splitting the application into services." ], "verification": [ "Replace A with B through composition wiring and run the same appointment behavior cases.", "Make the port return rejected and unknown outcomes and verify the domain does not treat either as successful acceptance." ], "deliverables": [ "Domain notification port and provider-free appointment tests" ], "rollout": "Migrate one appointment use case to the port, compare results, then migrate the remaining local caller; revert adapter wiring if parity fails.", "skills": [ "Dependency inversion", "Module boundaries", "Contract testing" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "System design", "percentage": 50 } ], "patterns": [ { "pattern": "ports-and-adapters", "activity": "APPLY", "focus": "Move vendor request types and error codes behind a domain-owned notification port so scheduling rules can run without initializing transport code." } ] }, { "id": "2f77f80b-4e74-4a0e-b7fd-2487d2a646d2", "key": "PPROVIDER-103", "title": "Validate notice inputs before choosing a provider", "type": "BUG", "priority": "HIGH", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "boundary", "dependsOn": [ "PPROVIDER-102" ], "scenario": "An invalid synthetic recipient passes provider selection and fails differently for A and B. Another path checks the notification preference only after the stub has already accepted the request.", "acceptanceCriteria": [ "Validate appointment identity, synthetic recipient format, and declared notice preference before any adapter call.", "Define the order and short-circuit behavior of validation stages, returning stable reason codes.", "Compare a Chain of Responsibility with an explicit sequence of validation functions; a skipped preference check must be structurally impossible." ], "implementationNotes": [ "Use only synthetic .invalid addresses; do not contact any external address or interpret this exercise as a compliance certification." ], "verification": [ "Accept valid synthetic input and assert each required check runs before one provider call.", "Reject malformed recipient and disabled preference with a provider-call count of zero; verify the documented first error when both fail." ], "deliverables": [ "Ordered preflight validation and no-send regression fixtures" ], "rollout": "Apply the shared validation path to both local providers together; leave explicit rejection visible to the scheduler.", "skills": [ "Validation pipelines", "Side-effect boundaries", "Error contracts" ], "fieldMix": [ { "field": "Integrations", "percentage": 60 }, { "field": "Privacy engineering", "percentage": 40 } ], "patterns": [ { "pattern": "chain-of-responsibility", "activity": "COMPARE", "focus": "Choose an ordered, short-circuiting validation structure that guarantees notice preferences are checked before any provider side effect." } ] }, { "id": "bf3f66cd-0c09-4618-a3c9-0fab79a98327", "key": "PPROVIDER-104", "title": "Decouple notice format from the selected transport", "type": "STORY", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "composition", "dependsOn": [ "PPROVIDER-102", "PPROVIDER-103" ], "scenario": "ReminderEmailProviderA and CancellationEmailProviderA have matching ProviderB subclasses. Adding a third notice type is multiplying classes even though formatting and transport are independent choices.", "acceptanceCriteria": [ "Separate notice-content construction from provider transport, with two notice types runnable through both local providers.", "Document required transport capabilities and reject incompatible content before sending; do not silently drop a cancellation reason.", "Compare a Bridge between notice abstraction and transport with two composed functions, avoiding one subclass for every combination." ], "implementationNotes": [ "Use plain text only in the exercise; user-provided content remains data and is never executed as a template or command." ], "verification": [ "Exercise all four type/provider combinations and compare semantic content after adaptation.", "Configure a transport without a required capability and assert rejection before any stub call." ], "deliverables": [ "Independent content/transport composition and capability matrix tests" ], "rollout": "Replace combination classes after all four fixtures pass; keep the declared provider contract stable while moving formatting code.", "skills": [ "Composition", "Capability contracts", "Design comparison" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "System design", "percentage": 50 } ], "patterns": [ { "pattern": "bridge", "activity": "COMPARE", "focus": "Separate independently varying notice content and provider transport so their combinations do not require a growing subclass matrix." } ] }, { "id": "c1c9aece-fc81-4906-8d9d-b34aafde8214", "key": "PPROVIDER-105", "title": "Record one bounded telemetry event around each provider attempt", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "composition", "dependsOn": [ "PPROVIDER-102" ], "scenario": "Adapter A logs full payloads while B logs nothing on exceptions. The team cannot compare local attempt outcomes without exposing synthetic recipient and notice content in generic logs.", "acceptanceCriteria": [ "Wrap provider attempts with a common duration and outcome recorder that emits exactly one completion event per attempt.", "Limit event fields to operation identity, provider, outcome category, elapsed duration, and declared adapter version; omit recipient, body, and credentials.", "A telemetry sink failure cannot change the provider result or mask an adapter exception." ], "implementationNotes": [ "Use a Decorator or explicit higher-order function; inject clock and event sink for deterministic tests, and avoid high-cardinality recipient labels." ], "verification": [ "Run accepted, rejected, thrown-error, and cancellation cases and assert one correctly categorized event each.", "Make the sink throw and inspect all event payloads for synthetic secret and recipient markers." ], "deliverables": [ "Attempt telemetry wrapper and privacy/failure regression fixtures" ], "rollout": "Enable the wrapper on local stubs first; disable the sink independently while preserving attempt behavior and correlation identities.", "skills": [ "Instrumentation", "Data minimization", "Exception handling" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Site reliability", "percentage": 30 }, { "field": "Privacy engineering", "percentage": 30 } ], "patterns": [ { "pattern": "decorator", "activity": "APPLY", "focus": "Add consistent attempt instrumentation around interchangeable adapters without embedding logging behavior in each provider mapping." } ] }, { "id": "4c2d743d-33f2-4e00-9d4e-1d8077af8ebf", "key": "PPROVIDER-106", "title": "Replace the scheduler's six-call notification sequence with one bounded operation", "type": "CHORE", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "composition", "dependsOn": [ "PPROVIDER-103", "PPROVIDER-104", "PPROVIDER-105" ], "scenario": "Every scheduling handler must validate, format, select an adapter, initialize telemetry, call send, and map the result in the right order. One handler skips validation and another catches all failures as accepted.", "acceptanceCriteria": [ "Expose one application operation that coordinates the declared preflight, content, adapter, and result steps.", "Return typed accepted, rejected, and unknown outcomes without concealing which stage failed.", "Keep policy and transport modules independently testable; the Facade must not absorb appointment rules, template storage, or unrelated administration." ], "implementationNotes": [ "This operation makes at most one provider attempt. Automatic failover and retries are excluded until duplicate-acceptance behavior is defined." ], "verification": [ "Call the operation from reminder and cancellation flows and compare stage order and result handling.", "Fail every stage in turn and assert later side effects do not run; preserve an unknown outcome after ambiguous transport completion." ], "deliverables": [ "Notification Facade and stage-failure test matrix" ], "rollout": "Move the two local scheduling handlers behind the operation with parity fixtures; revert one caller only if its behavior remains explicit.", "skills": [ "Application boundaries", "Error propagation", "Orchestration testing" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Backend", "percentage": 30 }, { "field": "System design", "percentage": 20 } ], "patterns": [ { "pattern": "facade", "activity": "APPLY", "focus": "Offer scheduling callers one explicit notification operation while preserving distinct validation, content, and transport responsibilities underneath." } ] }, { "id": "0d91053c-96ea-4cf9-86e4-141a14223b6a", "key": "PPROVIDER-107", "title": "Remove the transparent send proxy that retries an ambiguous timeout", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "composition", "dependsOn": [ "PPROVIDER-106" ], "scenario": "A transparent Proxy automatically repeats any timed-out call. The local stub can accept a notice and drop the response, so the hidden retry records two accepted deliveries while the application sees one success.", "acceptanceCriteria": [ "Remove hidden retry behavior from the send proxy and expose ambiguous completion as unknown.", "If a retry is explicitly requested, preserve the original operation identity and require a declared provider deduplication contract; otherwise refuse the retry.", "Record attempt identities separately from operation identity so the handoff can explain what was tried without claiming recipient delivery." ], "implementationNotes": [ "Keep the exercise local and deterministic; a timeout does not prove a provider rejected the operation, and selecting the other provider is not a safe default." ], "verification": [ "Have the stub accept then lose its response; assert one attempt and an unknown outcome with hidden retries disabled.", "Try an explicit retry against a stub lacking deduplication support and confirm it is refused; test convergence on a deduplicating stub." ], "deliverables": [ "Proxy simplification, explicit retry contract, and ambiguous-timeout reproduction" ], "rollout": "Disable automatic retry in the local composition first; review stored unknown operations before any explicit retry experiment.", "skills": [ "Idempotency", "Failure semantics", "Abstraction review" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Distributed systems", "percentage": 50 } ], "patterns": [ { "pattern": "proxy", "activity": "REMOVE", "focus": "Remove transparent retry behavior that changes send semantics after ambiguous completion, exposing retry decisions and operation identity to the application." } ] }, { "id": "d67a0795-d5ed-4ed5-9924-b73324cc2fc6", "key": "PPROVIDER-108", "title": "Pause a failing provider and admit one recovery probe", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "resilience", "dependsOn": [ "PPROVIDER-105", "PPROVIDER-107" ], "scenario": "Provider B returns transport failures for every synthetic request. Callers continue spending the full timeout on each attempt even though the service needs a short recovery window.", "acceptanceCriteria": [ "Open the circuit after three consecutive declared transport failures, reject further attempts locally for thirty simulated seconds, and then admit one recovery probe.", "A successful probe closes the circuit; a failed probe reopens it. Validation errors and provider business rejections do not count as transport failures.", "Track circuits independently per provider, return a distinct circuit-open outcome, and never report rejected local attempts as provider calls." ], "implementationNotes": [ "Use an injected monotonic clock and explicit transition logic; no real-time sleeps, external service, or automatic cross-provider failover is required." ], "verification": [ "Advance the fake clock through closed, open, and half-open states and assert allowed call counts.", "Race several requests at the recovery boundary and confirm exactly one probe; verify A remains usable while B is open." ], "deliverables": [ "Circuit Breaker state transitions and deterministic recovery tests" ], "rollout": "Enable the breaker around B's local stub first, observe transitions, and preserve unknown-operation records when resetting circuit state.", "skills": [ "Circuit breakers", "State transitions", "Deterministic timing" ], "fieldMix": [ { "field": "Site reliability", "percentage": 50 }, { "field": "Integrations", "percentage": 30 }, { "field": "Distributed systems", "percentage": 20 } ], "patterns": [ { "pattern": "circuit-breaker", "activity": "APPLY", "focus": "Stop repeated attempts to a failing provider with explicit failure classification and a single controlled recovery probe." } ] }, { "id": "1f51b94e-fafe-4b4a-b2ee-a30b8d36398f", "key": "PPROVIDER-109", "title": "Keep one slow provider from occupying every notification slot", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "resilience", "dependsOn": [ "PPROVIDER-107" ], "scenario": "Twenty stalled B requests consume the module's shared work pool. A's immediate responses cannot start, and callers keep adding pending requests until memory grows.", "acceptanceCriteria": [ "Give each provider at most three active attempts and five queued operations, with a typed overload result when its queue is full.", "Queued cancellations remove work before execution; every completion or failure releases its slot exactly once.", "A stalled B provider cannot consume A's admission capacity, and queue wait contributes to the caller's overall deadline." ], "implementationNotes": [ "Use bounded in-process queues and local promise gates; do not add an external broker or unbounded task buffers." ], "verification": [ "Saturate B, submit A work, and verify A starts promptly while B's active and queued counts stay within bounds.", "Cancel queued work, throw inside an attempt, and resolve an attempt twice through a faulty stub; verify no slot leak or over-release." ], "deliverables": [ "Per-provider Bulkhead and overload/cancellation regression harness" ], "rollout": "Start with the declared local limits and record saturation behavior; reject new work explicitly while draining queues before a configuration change.", "skills": [ "Concurrency limits", "Backpressure", "Resource lifecycle" ], "fieldMix": [ { "field": "Performance engineering", "percentage": 40 }, { "field": "Site reliability", "percentage": 40 }, { "field": "Integrations", "percentage": 20 } ], "patterns": [ { "pattern": "bulkhead", "activity": "APPLY", "focus": "Partition active and queued capacity by provider so stalled requests cannot exhaust another provider's execution slots or grow an unbounded queue." } ] }, { "id": "9f938194-3082-4ed3-b244-f68ef3b23f9b", "key": "PPROVIDER-110", "title": "Prove wrapper order preserves deadlines, probe limits, and attempt counts", "type": "TASK", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 240, "phaseId": "resilience", "dependsOn": [ "PPROVIDER-108", "PPROVIDER-109" ], "scenario": "The breaker, queue, telemetry, and adapter work in isolation, but a half-open probe can expire while queued and leave the circuit stuck. Another wrapper order records circuit-open rejections as actual provider attempts.", "acceptanceCriteria": [ "Document wrapper order and distinguish operation admission, queue wait, probe reservation, and physical provider attempt.", "An overall deadline or cancellation releases queue capacity and any unused probe reservation, with no adapter call after cancellation commits.", "Telemetry reconciles submitted, locally rejected, cancelled, and actually attempted operations; terminal outcomes and slot release occur once under every tested interleaving." ], "implementationNotes": [ "Use a deterministic fake scheduler and clock. Change composition boundaries where needed rather than adding retries that could duplicate an accepted notice." ], "verification": [ "Exercise a half-open probe queued behind slow work, then cancel it and verify a later eligible request can probe.", "Race deadline expiry with adapter completion and circuit opening; assert exact attempt counts, bounded slots, and one terminal outcome." ], "deliverables": [ "Reviewed composition order, interleaving matrix, and local failure-recovery runbook" ], "rollout": "Run the full fault replay against both local providers before selecting the new composition; preserve a configuration switch and unknown-operation list for rollback analysis.", "skills": [ "Composition semantics", "Concurrency testing", "Operational reasoning" ], "fieldMix": [ { "field": "System design", "percentage": 40 }, { "field": "Site reliability", "percentage": 30 }, { "field": "Integrations", "percentage": 30 } ], "patterns": [ { "pattern": "decorator", "activity": "REFACTOR", "focus": "Make wrapper ordering explicit so instrumentation describes real attempts and cancellation is respected across queue, breaker, and adapter boundaries." }, { "pattern": "circuit-breaker", "activity": "REFACTOR", "focus": "Release unused half-open probe reservations when queued operations expire or are cancelled, preserving a path to later recovery." }, { "pattern": "bulkhead", "activity": "REFACTOR", "focus": "Coordinate queue admission and slot release with the overall operation deadline without leaking capacity during concurrent completion and cancellation." } ] } ] } ] }