Implementing STORY-{ID}: {Title}

User Story:
As a {type}, I want to {capability}, so that {benefit}

Acceptance Criteria: {count}
Story Points: {points}
Dependencies: {list}
Sub-tasks: {count} (from ZenHub)  ← if sub-tasks loaded

I ' ll now plan the implementation...

If zh_available and zh_story_id exists:
  Call helpers.md#Move-Pipeline-with-Context(zh_story_id,  " In Progress " )
  Log:  " ✓ ZenHub: #{issue_number} → In Progress " 

   # If this is the first story starting in this epic, move epic to In Progress too
  Check epic ' s stories in sprint-status:
    If ALL other stories are  " not_started " :
      # This is the first story — move epic to In Progress
      If zh_epic_id exists:
        Call helpers.md#Move-Pipeline-with-Context(zh_epic_id,  " In Progress " )
        Log:  " ✓ ZenHub: Epic #{epic_number} → In Progress (first story started) "

Implementation Checklist (from ZenHub Sub-tasks):
- [ ] #{sub_num_1} {sub_task_title_1}
- [ ] #{sub_num_2} {sub_task_title_2}
- [ ] #{sub_num_3} {sub_task_title_3}
...

If zh_available and sub_task has zh_issue_id:
  Call helpers.md#Move-Pipeline-with-Context(zh_sub_task_id,  " In Progress " )
  ... (after completing the sub-task)
  // sub-task complete: GitHub Close (no need to move to Done pipeline)
  mcp__zenhub__updateIssue({ issueId: zh_sub_task_id, state:  " CLOSED "   })
  Update sprint-status sub_task status →  " done "

TodoWrite:
- [ ] Create password reset token model
- [ ] Add token fields to users table (migration)
- [ ] Implement token generation logic
- [ ] Create request-reset endpoint
- [ ] Create validate-token endpoint
- [ ] Create reset-password endpoint
- [ ] Add email sending for reset link
- [ ] Create frontend reset request page
- [ ] Create frontend reset form page
- [ ] Write backend unit tests
- [ ] Write API integration tests
- [ ] Write frontend component tests
- [ ] Manual testing
- [ ] Validate all acceptance criteria

// services/password-reset.service.js
const crypto = require( ' crypto ' );
const bcrypt = require( ' bcrypt ' );

class PasswordResetService {
  generateResetToken() {
    return crypto.randomBytes(32).toString( ' hex ' );
  }

  async requestReset(email) {
    const user = await User.findByEmail(email);
    if (!user) {
      // Don ' t reveal if email exists
      return { success: true };
    }

    const token = this.generateResetToken();
    const expiry = new Date(Date.now() + 3600000); // 1 hour

    await user.update({
      reset_token: await bcrypt.hash(token, 10),
      reset_token_expiry: expiry
    });

    await EmailService.sendPasswordResetEmail(user.email, token);

    return { success: true };
  }

  async validateToken(token) {
    const user = await User.findByResetToken(token);
    if (!user) {
      return { valid: false, error:  ' Invalid token '   };
    }

    if (user.reset_token_expiry  <   new Date()) {
      return { valid: false, error:  ' Token expired '   };
    }

    return { valid: true, userId: user.id };
  }

  async resetPassword(token, newPassword) {
    const validation = await this.validateToken(token);
    if (!validation.valid) {
      throw new Error(validation.error);
    }

    const user = await User.findById(validation.userId);
    const hashedPassword = await bcrypt.hash(newPassword, 10);

    await user.update({
      password: hashedPassword,
      reset_token: null,
      reset_token_expiry: null
    });

    return { success: true };
  }
}

module.exports = new PasswordResetService();

// routes/auth.routes.js
router.post( ' /request-password-reset ' ,
  validate(requestResetSchema),
  async (req, res, next) = >   {
    try {
      const { email } = req.body;
      await PasswordResetService.requestReset(email);
      res.json({ success: true, message:  ' If email exists, reset link sent '   });
    } catch (error) {
      next(error);
    }
  }
);

router.post( ' /reset-password ' ,
  validate(resetPasswordSchema),
  async (req, res, next) = >   {
    try {
      const { token, newPassword } = req.body;
      await PasswordResetService.resetPassword(token, newPassword);
      res.json({ success: true, message:  ' Password reset successful '   });
    } catch (error) {
      next(error);
    }
  }
);

// components/PasswordResetRequest.jsx
import { useState } from  ' react ' ;
import { requestPasswordReset } from  ' ../api/auth ' ;

export default function PasswordResetRequest() {
  const [email, setEmail] = useState( ' ' );
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState( ' ' );
  const [error, setError] = useState( ' ' );

  const handleSubmit = async (e) = >   {
    e.preventDefault();
    setLoading(true);
    setError( ' ' );
    setMessage( ' ' );

    try {
      await requestPasswordReset(email);
      setMessage( ' Password reset link sent to your email ' );
      setEmail( ' ' );
    } catch (err) {
      setError( ' Failed to request password reset. Please try again. ' );
    } finally {
      setLoading(false);
    }
  };

  return (
     < div className= " password-reset-request " > 
       < h2 > Reset Your Password < /h2 > 
       < form onSubmit={handleSubmit} > 
         < div className= " form-group " > 
           < label htmlFor= " email " > Email Address < /label > 
           < input
            type= " email " 
             id= " email " 
             value={email}
            onChange={(e) = >   setEmail(e.target.value)}
            required
            disabled={loading}
          / > 
         < /div > 

         {error  & &   < div className= " alert alert-error " > {error} < /div > }
        {message  & &   < div className= " alert alert-success " > {message} < /div > }

         < button type= " submit "   disabled={loading} > 
           {loading ?  ' Sending... '   :  ' Send Reset Link ' }
         < /button > 
       < /form > 
     < /div > 
   );
}

// services/password-reset.service.test.js
describe( ' PasswordResetService ' , () = >   {
  describe( ' generateResetToken ' , () = >   {
    it( ' should generate a random token ' , () = >   {
      const token1 = service.generateResetToken();
      const token2 = service.generateResetToken();

      expect(token1).toHaveLength(64);
      expect(token1).not.toEqual(token2);
    });
  });

  describe( ' requestReset ' , () = >   {
    it( ' should send reset email for existing user ' , async () = >   {
      const email =  ' test@example.com ' ;
      await service.requestReset(email);

      const user = await User.findByEmail(email);
      expect(user.reset_token).not.toBeNull();
      expect(user.reset_token_expiry).toBeGreaterThan(new Date());
    });

    it( ' should not reveal non-existent email ' , async () = >   {
      const result = await service.requestReset( ' fake@example.com ' );
      expect(result.success).toBe(true); // Generic response
    });
  });

  describe( ' validateToken ' , () = >   {
    it( ' should validate correct token ' , async () = >   {
      // Setup user with token
      const result = await service.validateToken(validToken);
      expect(result.valid).toBe(true);
    });

    it( ' should reject expired token ' , async () = >   {
      // Setup user with expired token
      const result = await service.validateToken(expiredToken);
      expect(result.valid).toBe(false);
      expect(result.error).toBe( ' Token expired ' );
    });
  });
});

// components/PasswordResetRequest.test.jsx
import { render, screen, fireEvent, waitFor } from  ' @testing-library/react ' ;
import PasswordResetRequest from  ' ./PasswordResetRequest ' ;

describe( ' PasswordResetRequest ' , () = >   {
  it( ' renders reset form ' , () = >   {
    render( < PasswordResetRequest / > );
    expect(screen.getByLabelText(/email/i)).toBeInTheDocument();
    expect(screen.getByText(/send reset link/i)).toBeInTheDocument();
  });

  it( ' submits email and shows success message ' , async () = >   {
    render( < PasswordResetRequest / > );

    const emailInput = screen.getByLabelText(/email/i);
    const submitButton = screen.getByText(/send reset link/i);

    fireEvent.change(emailInput, { target: { value:  ' test@example.com '   } });
    fireEvent.click(submitButton);

    await waitFor(() = >   {
      expect(screen.getByText(/reset link sent/i)).toBeInTheDocument();
    });
  });

  it( ' shows error message on failure ' , async () = >   {
    // Mock API to fail
    render( < PasswordResetRequest / > );

    fireEvent.change(screen.getByLabelText(/email/i), {
      target: { value:  ' test@example.com '   }
    });
    fireEvent.click(screen.getByText(/send reset link/i));

    await waitFor(() = >   {
      expect(screen.getByText(/failed to request/i)).toBeInTheDocument();
    });
  });
});

# Backend
npm test services/password-reset.service.test.js

# Frontend
npm test components/PasswordResetRequest.test.jsx

# All tests
npm test

// tests/integration/password-reset.test.js
describe( ' Password Reset Flow ' , () = >   {
  it( ' should complete full password reset ' , async () = >   {
    // 1. Request reset
    const res1 = await request(app)
      .post( ' /api/auth/request-password-reset ' )
      .send({ email:  ' test@example.com '   });
    expect(res1.status).toBe(200);

    // 2. Get token from database (in real scenario, from email)
    const user = await User.findByEmail( ' test@example.com ' );
    const token = user.reset_token;

    // 3. Validate token
    const res2 = await request(app)
      .get(`/api/auth/validate-reset-token/${token}`);
    expect(res2.body.valid).toBe(true);

    // 4. Reset password
    const newPassword =  ' NewSecure123! ' ;
    const res3 = await request(app)
      .post( ' /api/auth/reset-password ' )
      .send({ token, newPassword });
    expect(res3.status).toBe(200);

    // 5. Verify can login with new password
    const res4 = await request(app)
      .post( ' /api/auth/login ' )
      .send({ email:  ' test@example.com ' , password: newPassword });
    expect(res4.status).toBe(200);
  });
});

npm run test:coverage

# Target: ≥80% coverage
# Focus on critical paths and business logic

Acceptance Criteria Checklist:
- [ ] User can request password reset from login page
      → Test manually: Click  " Forgot Password " , enter email, submit

- [ ] System sends email with reset link within 1 minute
      → Check email inbox, verify link received

- [ ] Reset link contains secure, expiring token (1-hour validity)
      → Verify token in database, check expiry timestamp

- [ ] User can set new password meeting strength requirements
      → Test with weak password (should fail)
      → Test with strong password (should succeed)

- [ ] System validates password confirmation matches
      → Test with mismatched passwords (should fail)

- [ ] Expired tokens show clear error message
      → Manually expire token in DB, try to use it

- [ ] Successful reset shows confirmation and redirects to login
      → Complete flow, verify redirect

- [ ] User can login with new password immediately
      → Login with new password

- [ ] Old password no longer works after reset
      → Try to login with old password (should fail)

Task Branches:
  task/STORY-008-fix-lint-rules → story (squash merged) ✓
  task/STORY-008-update-deps → story (squash merged) ✓
  [direct commit] Add missing test cases ✓

Call Create-PR-and-Merge(
  source: story_branch,
  target: epic_branch,
  title:  " feat: STORY-{ID} {title} " ,
  body:  " ## Summary\n- {changes}\n\n## Acceptance Criteria\n- [x] All criteria met\n\nCloses STORY-{ID} " ,
  merge_strategy:  " merge "     # preserve story commit history
)

If zh_available and zh_story_id exists:
  Call helpers.md#Move-Pipeline-with-Context(zh_story_id,  " Review/QA " )
  Log:  " ✓ ZenHub: #{issue_number} → Review/QA "

PR Review and Merge Instructions:

1. Review PR: {pr_url}
2. After PR is approved and merged (story → epic):
   - GitHub Close: Automatic close via  " Closes # "   keyword in PR
   - sprint-status.yaml: Update pr_status to  " merged " , status to  " done " 

 3. When ALL stories in this epic are closed:
   - Create epic → main PR:
     gh pr create --base main --head {epic_branch} \
       --title  " feat: {epic_name} "   --body  " ... " 
    - Merge with merge commit (preserve epic history)
   - GitHub Close: Epic #{epic_number}

## Progress Tracking

**Status History:**
- {date}: Created
- {date}: Started (branch: {story_branch})
- {date}: Code complete, PR created
- {date}: PR merged → Closed

**Branch:** {story_branch}
**PR:** {pr_url}
**Actual Effort:** {points} points

✓ Story Development Complete!

STORY-{ID}: {Title}
Status: Dev Complete → PR Open
Story Points: {points}
Actual Effort: {points} points

Implementation:
- Files created/modified: {count}
- Tests: {count} tests, {coverage}% coverage
- All acceptance criteria validated ✓

Branch Hierarchy:
main
└── {epic_branch}
    └── {story_branch}  ← PR open
        ├── task/{slug-1} (squash merged) ✓   # if task branches used
        └── task/{slug-2} (squash merged) ✓

PR: {pr_url} (story → epic, merge commit)

Sub-tasks: {completed}/{total} done     (if sub-tasks exist)

ZenHub Pipeline History:        (if zh_available)
  Sprint Backlog → In Progress → Review/QA
  Epic: #{epic_number} In Progress

Next Steps:
1. Review and merge PR: {pr_url}
2. After merge: Automatic close via GitHub  " Closes # "   keyword
3. Continue with next story or create epic → main PR

Story STORY-{ID} PR open for review!

Sprint Progress: {completed}/{total} points

Pending PR: {pr_url} (story → epic)

Next stories in Sprint:
- STORY-{next}: {title} ({points} points)

Run /dev-story STORY-{next} to continue
Or run /sprint-status to see full sprint progress

✓ All stories in Epic complete!

All story PRs merged to {epic_branch}:
- STORY-{A}: ✓ merged
- STORY-{B}: ✓ merged

Next: Create epic → main PR
  gh pr create --base main --head {epic_branch} --title  " feat: {epic_name} " 
   After merge: GitHub Close Epic #{epic_number}

✓ Sprint Complete!

Velocity: {points} points

Next: Start Sprint 2 or run sprint retrospective

✓ Story Complete!

Project complete! Single story implemented and tested.

Next: Deploy to production or continue with enhancements