{ "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": "9af4b1e5-d801-4904-99ca-a581f49c1190", "key": "SYNC", "title": "Inventory sync that survives a vendor outage", "field": "Integrations", "summary": "Build a vendor inventory connector with stable identity mapping, resumable ingestion, reconciliation, and tenant-safe operations.", "context": "A fictional retailer receives stock from two vendor warehouses. The vendor API paginates snapshots and emits change events, but retries and deleted products have caused unexplained stock drift. Work against a local vendor simulator.", "stack": [ "TypeScript", "NestJS", "PostgreSQL", "BullMQ" ], "prerequisites": [ "Create a local vendor API simulator with cursor pages and stock events.", "Use synthetic tenants, SKUs, and warehouse records; no vendor account is required." ], "developerValue": "Practice external contracts, cursor recovery, mapping conflicts, and reconciliation under partial failure.", "companyValue": "Inspect whether integration changes protect inventory correctness and give operators a clear recovery path.", "delivery": "A simulated vendor connector, reconciliation workflow, drift report, and outage runbook.", "phases": [ { "id": "contract", "title": "Understand vendor identity and data", "goal": "Validate external records before affecting stock." }, { "id": "ingest", "title": "Ingest changes safely", "goal": "Handle cursors, duplicates, disorder, and API limits." }, { "id": "reconcile", "title": "Recover and operate", "goal": "Find drift and apply only reviewable corrections." } ], "tickets": [ { "id": "854ce9ea-1654-4aae-ab14-3f7d75fce74e", "key": "SYNC-101", "title": "Validate vendor stock records at the adapter boundary", "type": "TASK", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 75, "phaseId": "contract", "dependsOn": [], "scenario": "The vendor sent quantity as an empty string and the importer stored zero, hiding a data problem. Validate a versioned stock response before mapping it into internal records.", "acceptanceCriteria": [ "Records require vendor item ID, warehouse ID, nonnegative integer quantity, revision, and updated timestamp.", "Missing, empty, fractional, or out-of-range quantities are rejected with a safe record reference.", "Unknown optional vendor fields do not silently become internal domain fields." ], "implementationNotes": [ "Keep vendor DTOs separate from internal stock types." ], "verification": [ "Accept a valid zero-stock record and a positive quantity record.", "Reject empty-string, negative, fractional, and unsafe-integer quantities without writing stock." ], "deliverables": [ "Vendor response schema and malformed-record fixtures" ], "rollout": "Start validation in the simulator; malformed records go to an inspection queue rather than defaulting to zero.", "skills": [ "Contract validation", "Adapter design", "Data quality" ], "fieldMix": [ { "field": "Integrations", "percentage": 70 }, { "field": "Data engineering", "percentage": 30 } ], "patterns": [ { "pattern": "adapter", "activity": "REFACTOR", "focus": "Keep vendor payloads outside the internal stock model; compare a small mapping function with an object adapter while preserving boundary validation." } ] }, { "id": "bcb2fe8b-ff54-40c6-b6bf-1468ee55df3d", "key": "SYNC-102", "title": "Map vendor items without assuming SKUs are globally unique", "type": "BUG", "priority": "HIGH", "difficulty": "INTERMEDIATE", "estimateMinutes": 105, "phaseId": "contract", "dependsOn": [ "SYNC-101" ], "scenario": "Two tenants both sell SKU CABLE-2M, and a mapping lookup updates the wrong stock row. Scope vendor mappings by tenant, connector, warehouse, and vendor item identity.", "acceptanceCriteria": [ "Mapping lookup always requires server-derived tenant and connector scope.", "Unique constraints prevent duplicate mapping identities within that scope.", "Unmapped or ambiguous items are quarantined and do not update a guessed SKU." ], "implementationNotes": [ "Treat display SKU as mutable metadata, not a durable identity." ], "verification": [ "Map identical SKU text for two tenants and verify each stock update stays in its own tenant.", "Supply an unmapped vendor item and confirm no stock mutation and an inspectable mapping issue." ], "deliverables": [ "Scoped mapping repository and cross-tenant tests" ], "rollout": "Backfill explicit mapping identities before enabling updates; pause connectors with unresolved mapping conflicts.", "skills": [ "Tenant isolation", "Identity mapping", "Database constraints" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Security", "percentage": 30 }, { "field": "Database engineering", "percentage": 30 } ], "patterns": [] }, { "id": "ca2c6355-27d0-40d7-8994-e119b6a2b16c", "key": "SYNC-103", "title": "Resume a paginated snapshot from the last committed page", "type": "STORY", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 180, "phaseId": "ingest", "dependsOn": [ "SYNC-102" ], "scenario": "The importer crashes on page four and restarts from page one, occasionally skipping records because the cursor is saved before page writes finish. Couple the checkpoint to the page commit.", "acceptanceCriteria": [ "A page and its next cursor commit atomically within one tenant-scoped transaction.", "Replaying a committed page is idempotent by snapshot and record identity.", "Expired cursors leave the current attempt incomplete and start a separately identified snapshot rather than mixing pages." ], "implementationNotes": [ "Store snapshot identity alongside opaque vendor cursors.", "Do not infer cursor order from cursor text." ], "verification": [ "Inject a failure between page writes and checkpoint and verify neither commits.", "Resume after a successful page commit and assert no missing or duplicate stock records." ], "deliverables": [ "Transactional snapshot checkpointing and restart scenarios" ], "rollout": "Run an initial snapshot in shadow storage; activate only a fully completed snapshot version.", "skills": [ "Transactions", "Cursor pagination", "Idempotency", "Recovery" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Database engineering", "percentage": 40 }, { "field": "Data engineering", "percentage": 20 } ], "patterns": [] }, { "id": "3ba6809f-2a69-4df8-8e25-a9b5877861dc", "key": "SYNC-104", "title": "Ignore stale stock events while retaining their delivery record", "type": "BUG", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "ingest", "dependsOn": [ "SYNC-102" ], "scenario": "Stock revision 42 sets quantity to 7, then delayed revision 41 resets it to 12. Compare vendor revisions atomically and record the stale delivery without changing current stock.", "acceptanceCriteria": [ "A higher revision replaces the current quantity and records its source event.", "Equal revisions with equal content are idempotent; equal revisions with different content create a conflict.", "Lower revisions remain in delivery history and cannot overwrite current stock." ], "implementationNotes": [ "Define revision ordering in the adapter contract; timestamps alone are insufficient." ], "verification": [ "Apply revisions 41, 42, and 41 and verify final quantity from 42.", "Race two updates and send conflicting content under one revision; verify monotonic state and a visible conflict." ], "deliverables": [ "Revision-guarded stock updates and out-of-order fixtures" ], "rollout": "Enable revision checks before consuming events; quarantine vendors that cannot supply the required ordering contract.", "skills": [ "Concurrency control", "Event ordering", "Conflict detection" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Data engineering", "percentage": 30 }, { "field": "Database engineering", "percentage": 20 } ], "patterns": [] }, { "id": "e91bf85f-97e9-48d6-8c52-4a5d90d2eae6", "key": "SYNC-105", "title": "Stop concurrent refreshes from multiplying vendor requests", "type": "BUG", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 120, "phaseId": "ingest", "dependsOn": [ "SYNC-103" ], "scenario": "Five scheduled jobs refresh the same connector after a restart and exceed the vendor limit. Add one active refresh identity per connector and bounded Retry-After handling.", "acceptanceCriteria": [ "Concurrent refresh triggers converge on one active connector job.", "429 responses follow capped Retry-After behavior within an overall refresh deadline.", "A failing connector does not prevent another tenant connector from progressing." ], "implementationNotes": [ "Use deterministic job IDs and an injected clock in timing tests.", "Do not hold a database transaction during vendor waits." ], "verification": [ "Submit five identical triggers and assert one vendor page sequence.", "Throttle one connector and verify another completes while the first stops at its deadline." ], "deliverables": [ "Refresh coordination and rate-limit simulator scenarios" ], "rollout": "Set conservative per-connector concurrency and expose pause/resume; rollback by pausing ingestion without clearing checkpoints.", "skills": [ "Job deduplication", "Rate limits", "Failure isolation" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Distributed systems", "percentage": 30 }, { "field": "Site reliability", "percentage": 20 } ], "patterns": [] }, { "id": "4f2bc903-76a1-431d-8fd8-4f17d986a5e8", "key": "SYNC-106", "title": "Distinguish a discontinued item from an item missing on one page", "type": "STORY", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 210, "phaseId": "ingest", "dependsOn": [ "SYNC-103", "SYNC-104" ], "scenario": "A transient missing page made hundreds of products look deleted. Apply absence-based tombstones only after a complete authoritative snapshot, while preserving explicit deletion events.", "acceptanceCriteria": [ "An incomplete snapshot cannot discontinue items through absence.", "A completed snapshot marks only previously mapped items absent from that exact vendor scope as candidates for discontinuation.", "A newer explicit stock event received during snapshot ingestion is not overwritten by an older absence decision." ], "implementationNotes": [ "Record the snapshot consistency boundary and event watermark.", "If the simulator cannot guarantee a consistency boundary, surface uncertainty and require review." ], "verification": [ "Fail the final page and verify no absence-based tombstones are applied.", "Deliver a newer event during snapshot ingestion and confirm finalization preserves it or reports a review conflict." ], "deliverables": [ "Snapshot finalization policy and deletion/event race tests" ], "rollout": "Generate discontinuation proposals first; enable automatic tombstones only for connectors with the documented snapshot guarantee.", "skills": [ "Snapshot consistency", "Reconciliation", "Deletion semantics", "Race conditions" ], "fieldMix": [ { "field": "Integrations", "percentage": 50 }, { "field": "Data engineering", "percentage": 30 }, { "field": "Distributed systems", "percentage": 20 } ], "patterns": [] }, { "id": "2c17e828-e912-4dcc-b5ce-891313768eb8", "key": "SYNC-107", "title": "Produce a stock drift report before applying corrections", "type": "STORY", "priority": "MEDIUM", "difficulty": "FOUNDATIONAL", "estimateMinutes": 90, "phaseId": "reconcile", "dependsOn": [ "SYNC-103" ], "scenario": "Operations sees different stock in the vendor portal and local app but has no item-level comparison. Add a read-only report against a completed synthetic snapshot.", "acceptanceCriteria": [ "The report lists local quantity, vendor quantity, revision, warehouse, and difference for each mapped item.", "Equal items can be hidden without changing discrepancy totals.", "Unmapped items and incomplete snapshots are labeled separately from confirmed quantity drift." ], "implementationNotes": [ "Include tenant and connector labels only within authorized operator scope." ], "verification": [ "Compare a fixture with one equal, one mismatched, and one unmapped item.", "Attempt a report from an incomplete snapshot and verify no discrepancy is presented as a confirmed correction." ], "deliverables": [ "Read-only reconciliation report and comparison fixture" ], "rollout": "Expose reports before correction actions; disable report generation when snapshot authority cannot be established.", "skills": [ "Reconciliation", "Reporting", "Data comparison" ], "fieldMix": [ { "field": "Integrations", "percentage": 60 }, { "field": "Data engineering", "percentage": 40 } ], "patterns": [] }, { "id": "795e6091-2e95-4d73-8dfd-b2b26b4b8677", "key": "SYNC-108", "title": "Apply an approved reconciliation plan only if stock is unchanged", "type": "STORY", "priority": "HIGH", "difficulty": "EXPERT", "estimateMinutes": 210, "phaseId": "reconcile", "dependsOn": [ "SYNC-106", "SYNC-107" ], "scenario": "An operator reviews a drift report, but a fresh vendor event arrives before Apply. Bind corrections to the reviewed before-state so approval cannot overwrite a newer update.", "acceptanceCriteria": [ "A plan records each item before revision, proposed quantity, source snapshot, and a canonical plan digest.", "Application verifies permission, plan digest, and every current before revision in one transaction.", "Any stale item blocks the plan with a conflict; approved applications record an append-only actor audit." ], "implementationNotes": [ "Choose all-or-nothing application for this bounded exercise.", "Recovery creates a new reviewed plan; it does not rewrite the old approval." ], "verification": [ "Apply an unchanged plan and verify exact proposed quantities and one audit record.", "Advance one item revision before apply and confirm no item in the plan changes." ], "deliverables": [ "Reviewable correction plan and stale-approval tests" ], "rollout": "Allow only explicitly authorized operators to apply plans; keep a read-only report mode available if conflicts spike.", "skills": [ "Optimistic concurrency", "Authorization", "Transactional updates", "Audit logs" ], "fieldMix": [ { "field": "Integrations", "percentage": 40 }, { "field": "Database engineering", "percentage": 40 }, { "field": "Security", "percentage": 20 } ], "patterns": [] }, { "id": "174bf1d8-95a2-4a3e-8901-b4656b383292", "key": "SYNC-109", "title": "Surface a stale connector without logging vendor payloads", "type": "TASK", "priority": "MEDIUM", "difficulty": "INTERMEDIATE", "estimateMinutes": 105, "phaseId": "reconcile", "dependsOn": [ "SYNC-105" ], "scenario": "A connector has not completed a refresh for six hours, yet its status is green because the last HTTP request succeeded. Define freshness from completed ingestion checkpoints.", "acceptanceCriteria": [ "Status exposes last complete snapshot, latest accepted event, current attempt, and safe failure category separately.", "A configured freshness threshold marks stale data without claiming the connector is healthy from HTTP success alone.", "Metrics and logs exclude tokens, raw payloads, and customer-specific product descriptions." ], "implementationNotes": [ "Use UTC and an injected clock for freshness.", "Keep metrics cardinality bounded; item IDs belong in scoped diagnostics." ], "verification": [ "Advance the clock past the threshold after a partial refresh and verify stale status.", "Cause a vendor error containing a token marker and confirm it is absent from all normal diagnostics." ], "deliverables": [ "Connector health projection and safe diagnostic tests" ], "rollout": "Publish status before enabling notifications; reset health only after a complete qualifying ingestion checkpoint.", "skills": [ "Observability", "Freshness semantics", "Secret handling" ], "fieldMix": [ { "field": "Site reliability", "percentage": 50 }, { "field": "Integrations", "percentage": 50 } ], "patterns": [] }, { "id": "83537e61-dbf2-43cf-a340-d7d5a6ea6f20", "key": "SYNC-110", "title": "Rehearse recovery from a vendor schema change", "type": "TASK", "priority": "HIGH", "difficulty": "ADVANCED", "estimateMinutes": 150, "phaseId": "reconcile", "dependsOn": [ "SYNC-108", "SYNC-109" ], "scenario": "The vendor replaces quantity with availableQuantity in its next API version. Demonstrate that the connector fails visibly, can resume with a new adapter, and preserves the old run history.", "acceptanceCriteria": [ "Unexpected required-field changes stop affected ingestion without defaulting stock values.", "A versioned adapter can be selected per connector after contract fixtures pass.", "Recovery resumes from a compatible checkpoint or starts a new snapshot with an explicit reason." ], "implementationNotes": [ "Keep both schema fixtures local and versioned.", "Do not reinterpret an old cursor under an incompatible API version." ], "verification": [ "Switch the simulator schema mid-run and confirm no corrupt stock or silent success.", "Upgrade the adapter, reconcile a complete new snapshot, and reproduce the documented recovery path." ], "deliverables": [ "Schema-change contract cases and connector recovery runbook" ], "rollout": "Canary the new adapter on one synthetic connector; revert adapter selection and pause writes if contract errors recur.", "skills": [ "API evolution", "Contract testing", "Incident recovery" ], "fieldMix": [ { "field": "Integrations", "percentage": 60 }, { "field": "Quality engineering", "percentage": 20 }, { "field": "Site reliability", "percentage": 20 } ], "patterns": [] } ] } ] }