{title}

<!-- Aim for 900–1600 tokens. If larger, add `oversized` to frontmatter `warnings` and continue. Never over-specify "how" — use boundaries + examples instead. Cohesive cross-layer stories (DB+BE+UI) stay in ONE file. IMPORTANT: Remove all HTML comments when filling this template. --> <intent-contract>

Intent

<!-- What is broken or missing, and why it matters. Then the high-level approach — the "what", not the "how". -->

Problem: ONE_TO_TWO_SENTENCES

Approach: ONE_TO_TWO_SENTENCES

Boundaries & Constraints

<!-- Three tiers: Always = invariant rules. Block If = decisions that cannot be made unattended. Never = out of scope + forbidden approaches. -->

Always: INVARIANT_RULES

Block If: DECISIONS_REQUIRING_HUMAN_INPUT

<!-- Agent: if any of these trigger during execution, HALT with status blocked and the blocking condition. -->

Never: NON_GOALS_AND_FORBIDDEN_APPROACHES

I/O & Edge-Case Matrix

<!-- If no meaningful I/O scenarios exist, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->

Scenario	Input / State	Expected Output / Behavior	Error Handling
HAPPY_PATH	INPUT	OUTCOME	No error expected
ERROR_CASE	INPUT	OUTCOME	ERROR_HANDLING

</intent-contract>

Code Map

<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->

• FILE -- ROLE_OR_RELEVANCE
• FILE -- ROLE_OR_RELEVANCE

Tasks & Acceptance

<!-- Tasks: backtick-quoted file path -- action -- rationale. Prefer one task per file; group tightly-coupled changes when splitting would be artificial. --> <!-- If an I/O Matrix is present, include a task to unit-test its edge cases. --> <!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->

Execution:

• FILE -- ACTION -- RATIONALE

Acceptance Criteria:

• Given PRECONDITION, when ACTION, then EXPECTED_RESULT

Spec Change Log

<!-- Append-only. Populated by step-04 during review loops. Do not modify or delete existing entries. Each entry records: what finding triggered the change, what was amended, what known-bad state the amendment avoids, and any KEEP instructions (what worked well and must survive re-derivation). Empty until the first bad_spec loopback. -->

Review Triage Log

<!-- Append-only. Populated by step-04 on EVERY review pass, including loopbacks and blocked exits. Each entry records triage decision counts for intent_gap, bad_spec, patch, defer, and reject, with per-category severity breakdowns using low/medium/high, plus the findings addressed in that pass. Empty until the first review pass. -->

Design Notes

<!-- If the approach is straightforward, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". --> <!-- Design rationale and golden examples only when non-obvious. Keep examples to 5–10 lines. -->

DESIGN_RATIONALE_AND_EXAMPLES

Verification

<!-- If no build, test, or lint commands apply, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". --> <!-- How the agent confirms its own work. Prefer CLI commands. When no CLI check applies, state what to inspect manually. -->

Commands:

• COMMAND -- expected: SUCCESS_CRITERIA

Manual checks (if no CLI):

• WHAT_TO_INSPECT_AND_EXPECTED_STATE