{ "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": "f23c3a94-95e0-4d93-9654-9475fc67ceec", "key": "PPOLICY", "title": "Untangle partner pricing without changing issued quotes", "field": "Backend", "summary": "Evolve a quoting module as partner contracts diverge, while keeping calculations reproducible and abstractions proportional to the problem.", "context": "A fictional equipment-rental service supports direct customers and two reseller contracts. Pricing now lives in a long conditional with subclasses left over from a discontinued campaign. Build a local TypeScript quoting module and synthetic fixtures; no starter repository, real charges, tax advice, or payment connection is supplied. Amounts use integer cents and the exercise supports USD only.", "stack": [ "TypeScript", "Node.js", "Vitest" ], "prerequisites": [ "Pure functions", "Object composition", "Integer arithmetic" ], "developerValue": "Practice choosing, testing, and removing object-design abstractions around versioned business rules and tenant isolation.", "companyValue": "Review changes that let a team introduce a contract without silently changing existing quotes, together with the maintenance costs of the chosen design.", "delivery": "Ten linked tickets in three phases. Create the declared local fixtures and module; deliver reproducible quotes, a migration comparison, and a short design decision record.", "phases": [ { "id": "baseline", "title": "Pin down the contract", "goal": "Make quote inputs and current calculations explicit." }, { "id": "variation", "title": "Support controlled variation", "goal": "Introduce contract differences without mutable rule leakage." }, { "id": "simplify", "title": "Migrate and simplify", "goal": "Keep version boundaries stable and remove unsupported complexity." } ], "tickets": [ { "id": "3fc1c4b6-77ab-4198-a325-cfeeb4fd4539", "key": "PPOLICY-101", "title": "Capture the reseller examples before splitting the pricing branch", "type": "TASK", "priority": "HIGH", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "baseline", "dependsOn": [], "scenario": "Support cannot explain why a reseller receives a different total after a harmless-looking cleanup. Recreate a small baseline: direct pricing uses list price; reseller A gets 10% off; reseller B gets 15% off only from ten units. Round the final discount down to whole cents.", "acceptanceCriteria": [ "Record input, contract identity, quantity, list amount, discount, and final amount for each example.", "Cover quantities 1, 9, 10, and 11 plus a list amount that produces a fractional-cent discount.", "Document whether a function table or Strategy interface would make the current three rules easier to change; either is acceptable with reasons." ], "implementationNotes": [ "Keep the baseline independent of the replacement implementation; reject non-integer quantities and negative list amounts." ], "verification": [ "Check manually calculated expected totals against the baseline fixtures.", "Introduce an off-by-one tier boundary and confirm the relevant fixture fails." ], "deliverables": [ "Characterization fixtures and a one-page abstraction decision" ], "rollout": "Use this baseline as the comparison gate for later local changes; retain the original calculations until all differences are explained.", "skills": [ "Characterization testing", "Domain modeling", "Tradeoff analysis" ], "fieldMix": [ { "field": "Backend", "percentage": 60 }, { "field": "Quality engineering", "percentage": 40 } ], "patterns": [ { "pattern": "strategy", "activity": "COMPARE", "focus": "Compare a small function table with interchangeable pricing strategies before adding an interface to three fixed contract rules." } ] }, { "id": "34c7f9de-da05-47bf-8864-da3084479aac", "key": "PPOLICY-102", "title": "Stop incomplete quote requests reaching the calculator", "type": "BUG", "priority": "HIGH", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "baseline", "dependsOn": [ "PPOLICY-101" ], "scenario": "The batch caller sometimes omits the pricing revision and the web caller sends quantity as text. Both currently reach calculation through a partially populated options object.", "acceptanceCriteria": [ "A quote request requires tenant, contract revision, nonempty product identity, positive integer quantity, and a nonnegative integer unit price.", "Construction fails with field-level errors before any pricing rule runs.", "Compare a staged Builder with a validated constructor or factory; select the smallest interface that cannot expose an incomplete request." ], "implementationNotes": [ "Do not silently fill the contract revision from a mutable global default; runtime input validation remains necessary with TypeScript." ], "verification": [ "Construct equivalent valid requests from the synthetic batch and web inputs.", "Reject missing revision, quantity 'ten', and quantity zero while asserting the calculator was not called." ], "deliverables": [ "Validated request construction API and invalid-input fixtures" ], "rollout": "Route the two local callers through validation together; keep error mapping compatible with their declared response contracts.", "skills": [ "Input validation", "API design", "Type modeling" ], "fieldMix": [ { "field": "Backend", "percentage": 60 }, { "field": "API design", "percentage": 40 } ], "patterns": [ { "pattern": "builder", "activity": "COMPARE", "focus": "Assess whether staged construction adds value for quote inputs, or a validated immutable constructor provides the same guarantees more clearly." } ] }, { "id": "5c0ee958-87db-4c38-816f-b7134ef73970", "key": "PPOLICY-103", "title": "Add a capped volume contract without editing the existing rules", "type": "STORY", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "baseline", "dependsOn": [ "PPOLICY-101", "PPOLICY-102" ], "scenario": "Reseller C needs 20% off from twenty units, capped at 5,000 cents per quote. The current conditional is also used by the other resellers, whose issued quotes must remain reproducible.", "acceptanceCriteria": [ "Select a pricing rule by explicit contract and revision, returning a typed error for an unknown combination.", "Implement the threshold and cap while preserving every existing baseline result.", "Return a stable rule identity and a breakdown showing the uncapped discount and applied cap." ], "implementationNotes": [ "Use composition or a function-valued Strategy; adding a class hierarchy is not required. Keep rule evaluation free of I/O." ], "verification": [ "Exercise quantities 19 and 20 with discounts below, at, and above 5,000 cents.", "Request a retired or unknown revision and confirm no fallback contract is used." ], "deliverables": [ "Capped pricing rule, selector, and regression fixtures" ], "rollout": "Enable reseller C only in the synthetic scenario set; keep the previous selector available for baseline replay.", "skills": [ "Strategy selection", "Pure functions", "Compatibility" ], "fieldMix": [ { "field": "Backend", "percentage": 70 }, { "field": "System design", "percentage": 30 } ], "patterns": [ { "pattern": "strategy", "activity": "APPLY", "focus": "Isolate the capped volume calculation behind the same contract used by existing rules, without adding reseller-specific branches to the caller." } ] }, { "id": "b1ac5413-b296-4a2f-9f36-40377947fecc", "key": "PPOLICY-104", "title": "Share quote assembly between the portal and nightly import", "type": "CHORE", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 150, "phaseId": "variation", "dependsOn": [ "PPOLICY-103" ], "scenario": "The portal and nightly CSV import each construct their own rule selector. A contract was enabled in the portal but missing from the import, producing different errors for the same customer.", "acceptanceCriteria": [ "Both callers resolve the same contract revisions through one composition boundary.", "Caller-specific input parsing stays outside pricing rule creation.", "Compare an overridable Factory Method in a shared import workflow with an injected creation function; document the chosen extension boundary." ], "implementationNotes": [ "Do not introduce dynamic module loading or a dependency-injection container for this local module." ], "verification": [ "Feed equivalent portal and CSV inputs and compare rule identities, amounts, and unknown-contract errors.", "Inject a selector construction failure and confirm neither caller emits a partial quote." ], "deliverables": [ "Shared assembly boundary and caller contract tests" ], "rollout": "Migrate one local caller at a time with parity tests; revert caller wiring if an unexplained difference appears.", "skills": [ "Composition roots", "Refactoring", "Contract testing" ], "fieldMix": [ { "field": "Backend", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [ { "pattern": "factory-method", "activity": "COMPARE", "focus": "Choose between an overridable creation step and an injected factory function for two workflows that must build the same pricing components." } ] }, { "id": "b7f2c7d6-2fb4-4933-9e64-c2d8f49f0baf", "key": "PPOLICY-105", "title": "Keep calculation and explanation revisions in the same contract family", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 210, "phaseId": "variation", "dependsOn": [ "PPOLICY-104" ], "scenario": "A quote calculated with reseller C revision 2 displays revision 1 explanation text, which omits the cap. Separate registries allow a valid calculator to be paired with an incompatible explainer.", "acceptanceCriteria": [ "Resolve calculator and structured explainer as one contract family with a shared revision identity.", "Reject a family whose members declare different revisions before serving a quote.", "Compare an Abstract Factory with one immutable family record; preserve independent tests for calculation and explanation." ], "implementationNotes": [ "Explanation output must use the actual calculation breakdown rather than recalculating the discount or parsing a display string." ], "verification": [ "Generate explanations for capped and uncapped quotes and reconcile every reported amount.", "Deliberately pair revision 2 calculation with revision 1 explanation and assert assembly rejection." ], "deliverables": [ "Contract-family resolver, mismatch fixture, and design comparison" ], "rollout": "Run family validation at local startup; keep the prior complete family available rather than rolling back individual members.", "skills": [ "Abstract factories", "Version compatibility", "Invariant testing" ], "fieldMix": [ { "field": "Backend", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [ { "pattern": "abstract-factory", "activity": "COMPARE", "focus": "Keep the calculator and explainer revision-compatible as a family while evaluating whether a factory interface adds value beyond an immutable record." } ] }, { "id": "d6d7cee3-4c58-45eb-80fc-7ee46fc8ee80", "key": "PPOLICY-106", "title": "Remove the rounding hook that bypasses the quote cap", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "variation", "dependsOn": [ "PPOLICY-105" ], "scenario": "An inherited calculate method calls a reseller override after the cap check. That override recomputes the discount, so the supposed fixed algorithm no longer enforces its own invariant.", "acceptanceCriteria": [ "Make the order explicit: validate, evaluate the selected rule, apply its declared cap, then derive the final amount and explanation.", "No extension point can change the applied amount after the final invariant check.", "Replace the unsafe Template Method hook with a narrower composed operation or justify a sealed algorithm with constrained inputs." ], "implementationNotes": [ "Preserve published rule revision behavior where valid; represent the defective synthetic revision explicitly instead of rewriting issued quote fixtures." ], "verification": [ "Reproduce the subclass cap bypass and show the corrected pipeline respects the cap.", "Supply an extension returning a negative or over-subtotal discount and verify a typed failure." ], "deliverables": [ "Pipeline refactor and cap-bypass regression" ], "rollout": "Compare old and corrected revision outputs in a local replay; activate a new revision only after listing intentional differences.", "skills": [ "Inheritance refactoring", "Domain invariants", "Regression analysis" ], "fieldMix": [ { "field": "Backend", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [ { "pattern": "template-method", "activity": "REFACTOR", "focus": "Constrain or replace the inherited algorithm hooks so a reseller extension cannot undo a discount cap after validation." }, { "pattern": "strategy", "activity": "APPLY", "focus": "Move the variable discount calculation into a narrow composed operation whose result is checked by the common quoting pipeline." } ] }, { "id": "5004cd3b-3768-48f3-8d0c-1d8293ccadf8", "key": "PPOLICY-107", "title": "Keep a cloned contract draft from changing the live tier table", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "variation", "dependsOn": [ "PPOLICY-103" ], "scenario": "A sales-operations preview shallow-copies a contract and changes a nested tier. The original contract shares the array and immediately starts quoting the draft rate.", "acceptanceCriteria": [ "A draft receives its own identity, source revision reference, and independently editable tier values.", "Editing, reordering, or deleting a draft tier cannot affect the published contract or another draft.", "Reject unsupported values during cloning instead of silently dropping them through JSON serialization." ], "implementationNotes": [ "Limit the prototype to a declared data-only contract schema; do not clone provider handles, functions, or process state." ], "verification": [ "Clone two drafts, mutate nested data in one, and compare all three contract snapshots.", "Attempt to clone an invalid tier boundary and confirm no partial draft is returned." ], "deliverables": [ "Schema-aware prototype copy and aliasing regression fixtures" ], "rollout": "Use the new copy path for synthetic previews; existing published fixture revisions remain immutable.", "skills": [ "Copy semantics", "Immutability", "Schema validation" ], "fieldMix": [ { "field": "Backend", "percentage": 70 }, { "field": "Quality engineering", "percentage": 30 } ], "patterns": [ { "pattern": "prototype", "activity": "REFACTOR", "focus": "Replace a shallow contract clone with a schema-aware draft copy that preserves provenance while preventing shared mutable tier arrays." } ] }, { "id": "31acf123-bf3f-4788-aed6-44e052a52718", "key": "PPOLICY-108", "title": "Remove the process-wide current-partner setting", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "simplify", "dependsOn": [ "PPOLICY-104", "PPOLICY-107" ], "scenario": "The quote singleton stores currentPartner before resolving a contract. Two overlapping synthetic requests can change that value between validation and calculation, applying one tenant's negotiated rate to another.", "acceptanceCriteria": [ "Tenant and contract identity travel explicitly through each quote operation.", "Remove mutable request state from the Singleton; shared immutable rule definitions may remain cached.", "Any remaining cache uses tenant, contract, and revision in its identity and cannot expose another tenant's rule configuration." ], "implementationNotes": [ "Do not serialize all requests behind a global lock to hide the leak; preserve independent concurrent execution." ], "verification": [ "Interleave requests for two tenants at a controlled barrier and assert both receive their own rate.", "Repeat the test after a failed request and a cache hit to detect stale tenant state." ], "deliverables": [ "Explicit request context and tenant-isolation concurrency regression" ], "rollout": "Switch the local composition root to stateless quotation; discard the old mutable cache on rollback or restart.", "skills": [ "Tenant isolation", "Dependency injection", "Concurrency" ], "fieldMix": [ { "field": "Backend", "percentage": 50 }, { "field": "Security", "percentage": 50 } ], "patterns": [ { "pattern": "singleton", "activity": "REMOVE", "focus": "Remove a globally mutable partner context that leaks negotiated rules across overlapping requests, while allowing immutable shared definitions." } ] }, { "id": "87cb58d7-9f09-4be8-ad06-e8c1fbdf547c", "key": "PPOLICY-109", "title": "Pin a quote to one rule family during a revision switch", "type": "STORY", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 240, "phaseId": "simplify", "dependsOn": [ "PPOLICY-105", "PPOLICY-106", "PPOLICY-108" ], "scenario": "A local replay switches a partner from revision 2 to 3 while quotes are in progress. Resolving the calculator at request start and the explainer at response time can produce a mixed-revision quote even after family validation.", "acceptanceCriteria": [ "Resolve and retain one immutable family snapshot for the complete quote operation.", "Switches affect only newly started operations; stored quotes retain inputs, family revision, and sufficient breakdown for deterministic replay.", "A malformed replacement family is rejected without displacing the last valid selection, and rollback selects a previous complete family." ], "implementationNotes": [ "Use an in-process deterministic scheduler for the exercise; a distributed configuration service is outside scope." ], "verification": [ "Pause a quote between calculation and explanation, switch revisions, and verify each concurrent quote is internally consistent.", "Reject an incompatible family, perform a rollback, and replay an earlier quote against its pinned revision." ], "deliverables": [ "Atomic family selection, interleaving tests, and revision-switch runbook" ], "rollout": "Exercise old/new/rollback sequences against synthetic requests; report differences by explicit revision without modifying prior quote records.", "skills": [ "Versioned configuration", "Concurrency", "Deterministic replay" ], "fieldMix": [ { "field": "Backend", "percentage": 50 }, { "field": "System design", "percentage": 30 }, { "field": "Quality engineering", "percentage": 20 } ], "patterns": [ { "pattern": "abstract-factory", "activity": "REFACTOR", "focus": "Make family resolution yield a stable snapshot so a revision switch cannot mix products created at different moments in the same operation." } ] }, { "id": "ba578554-b3c6-4040-8f0c-a517b10aa52a", "key": "PPOLICY-110", "title": "Retire the campaign subclass ladder after the migration", "type": "CHORE", "priority": "MEDIUM", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "simplify", "dependsOn": [ "PPOLICY-106", "PPOLICY-109" ], "scenario": "Five subclass layers still exist for a campaign that ended in the synthetic history. Only one leaf is constructible, but changing an error message requires following overridden methods through every layer.", "acceptanceCriteria": [ "Map reachable construction paths and separate archived-revision replay requirements from unused extension points.", "Remove unused Factory Method and Template Method layers while preserving supported quote and error contracts.", "Show the before/after change surface for adding a new rule, and retain an abstraction only where it supports a stated variation." ], "implementationNotes": [ "Keep archived calculations callable through explicit revision lookup; deleting old classes must not make existing fixture quotes unreplayable." ], "verification": [ "Run the complete quote matrix and replay fixtures after simplifying the hierarchy.", "Request an unsupported campaign revision and confirm the same explicit failure, with no fallback to a current rule." ], "deliverables": [ "Hierarchy simplification, construction-path inventory, and maintenance comparison" ], "rollout": "Remove dead paths in a separate local change after parity is established; revert the simplification if any supported revision becomes inaccessible.", "skills": [ "Legacy refactoring", "Dead-code analysis", "Compatibility" ], "fieldMix": [ { "field": "Backend", "percentage": 60 }, { "field": "System design", "percentage": 40 } ], "patterns": [ { "pattern": "factory-method", "activity": "REMOVE", "focus": "Remove unused overridable creation layers once supported rule revisions have one explicit composition path." }, { "pattern": "template-method", "activity": "REMOVE", "focus": "Collapse campaign inheritance hooks that no longer represent a live variation while preserving archived quote replay." } ] } ] } ] }