Sdd Apply

<!-- 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 implementation phase converts the task plan into real code. The implementer follows the specs (WHAT to do) and the design (HOW to do it), marking tasks as completed in real time.

Process

Step 0 — Preload

0a. Project context — load the project's context and conventions if present. Non-blocking.

0b. Spec context — load the change's spec scenarios if present. Non-blocking.

0c. Tech skill preload:

1. Scope guard — read the File Change Matrix in docs/sdd/{change-name}/design.md. If every file extension is in [.md, .yaml, .yml] → documentation-only. Report "Tech skill preload: skipped (documentation-only change)" and skip the rest of Step 0c. 2. Stack detection — sources, in priority order: the project's stack notes, then a project config manifest's stack keys. Neither → report "Tech skill preload: skipped (no stack source found)" and skip. 3. Stack-to-skill mapping — match the detected stack against the project's available technology guidance and load what applies. A general code-quality guide applies to every non-documentation change. 4. Load — for each match: load the guidance into context; absent → skip silently with a note. This step MUST NOT produce status: blocked or status: failed. 5. Report — list loaded skills + skipped ones, and carry the list to Step 2.

0d. Initialize retry counter:

• Read apply_max_retries from the project config if present. Otherwise default to 3.
• Initialize a per-invocation attempt counter (in-memory). Each run starts fresh.
• When a task's attempts reach the max before a new attempt → mark the task [BLOCKED], halt the phase. The user must resolve and re-run to resume.

Step 1 — Read full context

Read in this order:

1. Tasks artifact — docs/sdd/{change-name}/tasks.md. 2. Spec artifact — docs/sdd/{change-name}/spec.md. 3. Design artifact — docs/sdd/{change-name}/design.md. 4. Project config (if present) — diagnosis commands and rules. 5. Project conventions — code conventions. 6. Existing code files to be modified or used as pattern references.

Step 2 — Detect implementation mode (TDD vs standard)

Check three sources in priority order:

Source 1 — explicit config (highest priority): the project config's tdd key.

• tdd: true → TDD ON. Report "TDD mode: ON (source: config)". Skip Sources 2 and 3.
• tdd: false → TDD OFF. Report "TDD mode: OFF (explicitly disabled in config)". Skip Sources 2 and 3.
• Key absent → continue.

Source 2 — a testing tool is declared in the project (playwright, pytest, vitest, jest, etc.) → signal_count++.

Source 3 — test file patterns exist in the codebase (*.test.*, *.spec.*, test_*, *_test.*) → signal_count++.

This step MUST NOT install frameworks, create test files, or modify config.

Step 3 — Verify work scope

The caller specifies which tasks to implement (e.g. "Phase 1, tasks 1.1–1.3"). Implement ONLY those. Do not advance to the next ones without confirmation.

Step 4 — Diagnosis

Before any file change for an assigned task: a DIAGNOSIS block MUST be written. No file write or edit is permitted until then.

4.1 Read every file to be modified in its current state. For file-creation tasks, read related files used as pattern references.

4.2 Run read-only diagnostic commands from the project config if present. Non-zero exit is recorded as a failure in the Risk field but does NOT block. Absent → use auto-detected read-only commands relevant to the task or none.

4.3 Write the DIAGNOSIS block in the task output:

DIAGNOSIS — Task X.Y:
  1. Files to be modified: [list of paths]
  2. Diagnostic command outputs:
     - [command]: [output summary]
     (or "none applicable" / "diagnosis_commands: not configured")
  3. Current behavior observation: [what the code actually does now]
  4. Relevant data/state: [key data values, config, environment state]
  5. Hypothesis: "The bug/issue is [X] because [Y].
     Changing [Z] will achieve [expected behavior] because [rationale]."
  6. Risk: [what could go wrong with this change]

For file-creation tasks: field 3 describes the gap (what is absent); field 5 describes what the new file is intended to do and why.

4.4 Contradiction check — if diagnosis reveals the current state contradicts task assumptions, produce a MUST_RESOLVE warning and pause:

⚠️ MUST_RESOLVE — Diagnosis finding:
  Task X.Y assumes [A], but current state shows [B].

  This may indicate the task description is based on incorrect assumptions.

  Confirm how to proceed:
  Option 1: [proceed with updated understanding]
  Option 2: [revise task description]

Multiple contradictions → list each in the same MUST_RESOLVE block and wait for one combined confirmation. No contradictions → proceed to Step 5.

Step 5 — Implement task by task

5a. Warning check before each task — inspect the task entry in the task plan.

Blocking gate template:

⛔ BLOCKED — Task X.Y has an unresolved MUST_RESOLVE warning:
  [warning text from the task plan]

You must answer before implementation can proceed:
  → [Question from the task plan or derived from the warning]

Type your answer to continue.

After the answer is received, append to the task in the task plan:

  Answer: [exact text of the user's answer]
  Answered: [ISO 8601 timestamp, e.g., 2026-03-10T14:35:00Z]

5b. Standard flow (TDD not active) — per task:

1. Check warnings per 5a. 2. Read the task in the task plan → extract task_id (e.g., 1.1). 3. Check the attempt counter BEFORE attempting:

• undefined → set to 0.
• >= max_attempts → mark [BLOCKED], halt phase, report, STOP.

4. Increment the counter. Record file_snapshot (files this attempt will modify). 5. Consult specs (success criteria), design (interfaces/decisions), existing code (patterns). 6. Implement the task. 7. Check success:

• Success (all ops complete, no errors): mark [x], optionally reset counter to 0, next task.
• Failure: capture file_snapshot_after and error output.
• Same-strategy detection vs. the previous attempt:
• Same files modified + identical content changes → [BLOCKED] with "Identical strategy attempted twice — manual intervention required". Halt, report, STOP.
• Different strategy → counter already incremented; if >= max_attempts → [BLOCKED], halt, report, STOP. Otherwise re-attempt with a different approach (loop to step 6).

Same-Strategy Detection — two attempts are the same strategy when modified-file sets are identical AND content changes per file are identical:

def is_same_strategy(previous, current):
    if set(previous.files) != set(current.files): return False
    for path in previous.files:
        if previous.files[path] != current.files[path]: return False
    return True

If unsure → count as different (conservative default).

5c. TDD flow (TDD active) — per task:

1. Check warnings per 5a. 2. Read task, extract task_id. 3. Check the attempt counter (same logic as 5b step 3). 4. Increment the counter. 5. Consult specs — identify Given/When/Then scenarios this task covers. 6. Consult design + read existing code. 7. RED — write a failing test capturing the spec scenario. Test name SHOULD reference the scenario. Run the test to confirm it fails. Unexpected pass → report DEVIATION: behavior was already implemented. 8. GREEN — write the minimum code to make the test pass. No extra features, optimizations, or abstractions. Run to confirm pass. 9. REFACTOR — clean up while tests stay green. Run tests after each refactor. If a test breaks during refactor: fix the code (NOT the test). 10. Mark [x] only after REFACTOR is done.

BLOCKED — marking the task plan (before halting or reporting):

Change - [ ] X.Y description to - [BLOCKED] X.Y description and append:

- [BLOCKED] Task X.Y — description
  - Attempts: N/max_attempts
  - Tried:
    1. [files modified + error]
    2. [files modified + error]
    3. [files modified + error]
  - Last error: [error message from the final attempt]
  - Resolution required: [specific, actionable instruction for the user]

Same-strategy blocks MUST note "Identical strategy detected" in the relevant attempt summary.

BLOCKED — reporting to user (after the task plan update):

⛔ Task X.Y BLOCKED after N attempts.

What was tried:
  1. [attempt 1 summary]
  2. [attempt 2 summary]
  3. [attempt 3 summary]

Last error: [error from final attempt]

Task plan updated. Manual intervention required.
Resume after resolving by re-running this command.

After this report, NEVER continue to the next task or phase.

Step 6 — Respect the design

If implementation reveals a design problem:

• Do NOT fix it silently.
• Note it as "DEVIATION: [what and why]".
• If it is a blocker → stop and report status: blocked.

Step 7 — Update task-plan progress

The task plan file docs/sdd/{change-name}/tasks.md IS the source of truth — it is versioned in git. Every check-off, BLOCKED marking, answered-warning append, and progress update from Steps 5a, 5b, 5c, and this step MUST be persisted by editing the checkbox/progress lines in docs/sdd/{change-name}/tasks.md directly, in real time. Do NOT mark tasks only in memory.

## Progress: [completed]/[total] tasks

Mark each completed task by editing the task plan:

- [x] 1.1 Create `src/types/auth.types.ts` ✓
- [x] 1.2 Create `src/schemas/auth.schema.ts` ✓
- [ ] 1.3 Modify `src/config/jwt.config.ts`

Quality Gate

Apply the project's code conventions strictly when present; otherwise follow existing code patterns. Technology guidance + general code-quality principles are loaded automatically in Step 0c.

Before marking any code task [x], evaluate each criterion. Mark one of: ✅ (satisfied) | ❌ VIOLATION | N/A — [reason].

1. Single Responsibility (SRP) — each new or modified class/function/module has exactly one reason to change. Signal: describe it in one sentence without "and". Otherwise → QUALITY_VIOLATION: SRP — <description>. 2. Abstraction (OCP) — new behavior via extension, not modification. Abstractions justified by current reuse/testability, not speculation. Premature abstraction → QUALITY_VIOLATION: OCP — <description>. 3. Dependency direction (DIP) — high-level modules depend on abstractions (interfaces/ports), not concrete implementations. Outward dependencies on volatile implementations → QUALITY_VIOLATION: DIP — <description>. 4. Domain model integrity — business logic inside domain objects (entities, aggregates, value objects), not leaked into services/controllers. Anemic domain model → QUALITY_VIOLATION: Domain model — <description>. N/A if the task does not touch domain code. 5. Layer separation — code respects the architectural layers from the design. Cross-layer leakage → QUALITY_VIOLATION: Layer separation — <description>. 6. No scope creep — implementation strictly within task scope (task plan + design). Files/features outside scope → QUALITY_VIOLATION: Scope creep — <description>. Escalate to DEVIATION if it contradicts a spec scenario. 7. Naming clarity — names reveal intent without explanatory comments. If a name needs a comment to be understood, rename it → QUALITY_VIOLATION: Naming — <description>.

Reporting rules:

• N/A — [one-line reason] — criterion does not apply.
• QUALITY_VIOLATION: <principle> — <description> — fix BEFORE marking [x]. If the fix requires scope outside this task → DEVIATION + status: warning.
• Non-contradicting violations do NOT block apply. The caller MUST surface all QUALITY_VIOLATION notes in the phase summary.
• A violation that contradicts a spec scenario MUST be escalated to DEVIATION and MUST set status: warning.

No over-engineering: implement the minimum to pass spec scenarios; do not add features not in the proposal; do not refactor code outside the change.

Output Contract

Return this result shape:

status: ok | warning | blocked | failed
summary: Implemented [N] tasks of [total]. Phase [X] complete. [TDD mode note if active.]
tdd_mode: true | false
artifacts: [list of files created/modified + the updated task plan]
deviations: [any DEVIATION notes]
next_recommended: [verification of the change before committing]
risks: [any residual risk]

When all phases are done, the only permitted next-step suggestion is to continue with verification of the change. The summary MUST NOT suggest committing at any phase.

Rules

• Read specs BEFORE writing code — they are the acceptance criteria.
• Follow design decisions — do NOT ignore or silently "improve" them.
• Follow existing project patterns — do NOT introduce new ones without justification.
• Mark tasks completed AT THE MOMENT they finish.
• If a task is blocked, stop and report. Never skip.
• Do NOT implement tasks outside the assigned scope.
• Do NOT modify specs or design during implementation.
• If a spec is ambiguous, ask before assuming.
• MUST_RESOLVE warnings MUST block execution until an explicit user answer is received. No skip option.
• ADVISORY warnings MUST be logged but MUST NOT interrupt flow or request input.