Sdd Tasks

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

The task plan converts the design into an executable work list. Each task is atomic (one single thing), concrete (has a file path), and verifiable (can be marked as done).

It is the input for the implementation phase. Without an approved tasks file, nothing gets implemented.

Process

Step 0 — Load project context + Spec context preload

Load the project's context and the change's spec scenarios if present. Both are non-blocking.

Step 1 — Read prior artifacts

I must read:

• The design artifact (the file matrix and approach):
• Read docs/sdd/{change-name}/design.md for full content.
• If the disk file is absent (legacy change): search prior work for sdd/{change-name}/design and retrieve it.
• If neither exists: design content passed inline from the caller.
• The spec artifact (the success criteria):
• Read docs/sdd/{change-name}/spec.md for full content.
• If the disk file is absent (legacy change): search prior work for sdd/{change-name}/spec and retrieve it.
• If neither exists: spec content passed inline from the caller.
• The proposal artifact — specifically the ## Supersedes section:
• Read docs/sdd/{change-name}/proposal.md for full content.
• If the disk file is absent (legacy change): search prior work for sdd/{change-name}/proposal and retrieve it.
• If neither exists: proposal content passed inline from the caller.

Step 2 — Analyze dependencies between tasks

I identify the natural implementation order:

• Types/interfaces before their usage
• Providers/services before their consumers
• Schema/migration before the code that uses them
• Unit tests alongside the code (not at the end)
• Removals and replacements BEFORE additions (see Step 3 below)

Step 3 — Generate removal tasks from Supersedes section

Step 3a — Check Supersedes

1. Read ## Supersedes from proposal.md. 2. If section is absent (older archived change): log INFO: no Supersedes section in proposal.md — skipping removal task generation and proceed to Step 4 with standard phase organization. 3. If section states "None — purely additive change": skip removal task generation; proceed to Step 4. 4. If section has REMOVED or REPLACED items: proceed to Step 3b.

Step 3b — Generate removal/replacement tasks

For each REMOVED item in Supersedes:

• Generate one task titled Remove: [feature name] with:
• File paths to delete or modify
• Acceptance criterion: "File deleted AND no runtime errors in related flows"
• Spec reference: linked spec requirement name (if spec exists for this removal)

For each REPLACED item in Supersedes:

• Generate two tasks in dependency order:

1. Remove old: [old feature name] — delete/unregister the old implementation 2. Implement new: [new feature name] — add the replacement (link to spec requirement)

• Note explicit dependency: task 2 cannot start until task 1 is complete.

Step 3c — Phase 1 organization

All removal and replacement tasks (from Step 3b) MUST be grouped into Phase 1: Removals and Replacements. Standard addition/implementation tasks start from Phase 2 or later. Phase 2 MUST NOT begin until Phase 1 is complete — enforce this with an explicit sequencing note in tasks.md.

Removal task format:

### Phase 1: Removals and Replacements

- [ ] 1.1 Remove: [feature name] from `path/to/file`
  Linked spec: [Requirement name from spec, or "N/A — no spec for this removal"]
  Files: `path/to/file` (DELETE), `path/to/other.ts` (remove registration/import)
  Acceptance: File deleted AND related flows continue without runtime errors

- [ ] 1.2 Remove old: [old feature name] from `path/to/old-file`
  Linked spec: [Requirement: Replacement requirement name]
  Files: `path/to/old-file` (DELETE or MODIFY)
  Acceptance: Old implementation fully removed; no lingering imports or references

- [ ] 1.3 Implement new: [new feature name] in `path/to/new-file`
  Linked spec: [Requirement: new feature requirement]
  Depends on: 1.2
  Files: `path/to/new-file` (CREATE or MODIFY)
  Acceptance: New implementation active; spec scenarios pass

---
⚠️ Phase 2 MUST NOT begin until all Phase 1 tasks are complete.
---

Step 4 — Organize addition tasks into phases

I group addition/implementation tasks into logical phases after Phase 1 (or Phase 1 if no removals):

Phase 1 — Removals and Replacements [if Supersedes has items] OR Foundation [if purely additive]
Phase 2 — Foundation: types, interfaces, schemas, configuration [if Phase 1 is Removals]
Phase N — Core: main business logic
Phase N+1 — Integration: connect with the rest of the system
Phase N+2 — Testing: tests for previous phases
Phase N+3 — Cleanup: remove temporary code, update docs

(I adapt phase names to the context of the change)

Each addition task MUST include a Linked spec: sub-line immediately below the task:

- [ ] 2.1 Create `src/...` with ...
  Linked spec: Requirement: [name]

Cleanup, documentation, and housekeeping tasks use Linked spec: N/A — documentation task.

Step 4c — NFR consider-prompt

Before finalizing phases, consider non-functional surface: loading states, a11y (accessibility), responsive layout, error-states. Emit explicit tasks for each that applies. If the change has NO UI/runtime surface (pure doc/config change), record NFR: N/A — no UI/runtime surface (doc/config change) and proceed.

Step 5 — Create tasks.md

Step 4a — Warning Classification Rules

While analyzing each task, I MUST identify ambiguities, risks, or open decisions that could affect implementation. For each one found, I classify it as one of:

• `MUST_RESOLVE` — A warning that blocks implementation until the user provides an explicit answer. Use this when:
• The task involves a business rule decision that has multiple valid interpretations
• The task depends on an external system behavior that is ambiguous (e.g., which field to use in an API response)
• The task cannot be implemented correctly without knowing the user's intent
• Example reason: "business rule decision — external system behavior is ambiguous"

• `ADVISORY` — A warning that is logged for awareness but does not block implementation. Use this when:
• The concern is a performance consideration that does not affect functional correctness
• The concern is a style or naming preference with no impact on task completion
• The concern is informational and the implementer can safely proceed without further input
• Example reason: "performance consideration — does not affect correctness"
• Example reason: "style or naming preference — no impact on current task"

Each warning classification MUST include a reason statement explaining why it belongs in its category.

Step 4b — Record warnings in tasks.md

Every warning identified in Step 4a MUST be recorded inline with the affected task in tasks.md, using the following formats:

MUST_RESOLVE format:

- [ ] X.Y Task description [WARNING: MUST_RESOLVE]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "business rule decision — external system field ambiguous"]
  Question: [clarifying question derived from the warning]

ADVISORY format:

- [ ] X.Y Task description [WARNING: ADVISORY]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "performance consideration — does not affect correctness"]

Placement rules:

• Warnings appear immediately below their task entry, indented with two spaces
• A task may have at most one warning entry (combine multiple concerns into one if needed)
• Tasks without warnings have no indented block below them

Example task with MUST_RESOLVE warning:

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>` [WARNING: MUST_RESOLVE]
  Warning: Stripe invoice field for failure date is ambiguous — `status_transitions.marked_uncollectible_at` vs `status_transitions.voided_at` may both apply depending on invoice state.
  Reason: business rule decision — external system behavior is ambiguous
  Question: Which Stripe invoice field should be used to record the payment failure date?

I persist the task plan (disk-primary, two steps, disk FIRST):

First write docs/sdd/{change-name}/tasks.md with the full tasks markdown, then persist a pointer + summary keyed to sdd/{change-name}/tasks (type architecture, scoped to the project), with content = "path: docs/sdd/{change-name}/tasks.md\n\n{1-3 sentence summary}".

If the persistence layer is not reachable: still write the disk artifact (the source of truth); skip the pointer only.

Content format:

# Task Plan: [change-name]

Date: [YYYY-MM-DD]
Design: sdd/[name]/design

## Progress: 0/[total] tasks

## Phase 1: [Phase Name]

- [ ] 1.1 Create `src/types/auth.types.ts` with interfaces `LoginRequest`, `LoginResponse`, `JwtPayload`
- [ ] 1.2 Create `src/schemas/auth.schema.ts` with Zod schemas for login validation
- [ ] 1.3 Modify `src/config/jwt.config.ts` — add `refreshSecret` and `refreshExpiresIn`

## Phase 2: [Phase Name]

- [ ] 2.1 Create `src/services/auth.service.ts` with methods `login()`, `logout()`, `refreshToken()`
  Linked spec: Requirement: [name of spec requirement this task implements]
- [ ] 2.2 Modify `src/repositories/user.repository.ts` — add `findByEmail()` method
  Linked spec: Requirement: [name of spec requirement this task implements]
- [ ] 2.3 Create `src/middleware/auth.middleware.ts` for JWT validation on protected routes
  Linked spec: Requirement: [name of spec requirement this task implements]

## Phase 3: [Phase Name]

- [ ] 3.1 Create `src/controllers/auth.controller.ts` with endpoints POST /login, POST /logout, POST /refresh
- [ ] 3.2 Modify `src/routes/index.ts` — register auth routes
- [ ] 3.3 Modify `src/app.ts` — integrate auth middleware on protected routes

## Phase 4: Testing

- [ ] 4.1 Create `tests/unit/auth.service.spec.ts` — unit tests for AuthService
- [ ] 4.2 Create `tests/integration/auth.controller.spec.ts` — endpoint tests
- [ ] 4.3 Verify scenario coverage from spec (review sdd/[name]/spec)

## Phase 5: Cleanup

- [ ] 5.1 Update `README.md` — document new endpoints
  Linked spec: N/A — documentation task
- [ ] 5.2 Update `ai-context/architecture.md` if there were structural changes
  Linked spec: N/A — documentation task

---

## Implementation Notes

[Design decisions the implementer must keep in mind:]

- [important note 1]
- [important note 2]

## Blockers

[Tasks that cannot start until something external is ready:]

- [blocker]: [what resolves it]

[If none: "None."]

Format of a well-written task

Well written

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>`

Poorly written

- [ ] Add payment logic

Rule: Each task must answer "which file and what specific change?"

Output Contract

Return ONLY this JSON block. Do NOT add free-form text, command suggestions, or implementation steps after it.

{
  "status": "ok|warning|blocked",
  "summary": "Plan for [change-name]: [N] phases, [M] total tasks. Estimate: [Low/Medium/High].",
  "artifacts": ["sdd/{change-name}/tasks"],
  "next_recommended": ["sdd-apply"],
  "risks": ["[blocker if any]"]
}

The caller will present next_recommended to the user as sdd-apply (hyphen-separated, with command prefix). Do not format it yourself.

Rules

• HARD STOP: My only output is tasks.md + the JSON block. I NEVER implement any task, write code, or modify project files beyond creating tasks.md
• Each task MUST have a concrete file path
• Each task MUST be atomic (single responsibility)
• Each task MUST be verifiable (can be marked done with certainty)
• Tests go with their code, not all at the end
• Phase order respects technical dependencies
• Documentation and memory tasks (ai-context) go in the last phase
• I do NOT include tasks that go beyond the proposal's scope
• If I detect that the design is incomplete to generate tasks, I report it as a blocker
• EVERY task (not just removals) MUST carry a Linked spec: line. Addition tasks MUST reference the Requirement(s) they implement. Cleanup, documentation, and housekeeping tasks MUST use Linked spec: N/A — documentation task. A missing Linked spec: field (as opposed to an explicit N/A) is invalid — an auditor MUST be able to grep every task entry and find the field present.