Prompt file imported from lonewolf-jp/ConvoPeq (.github/prompts/sdd-change-apply.prompt.md). Fill in {{feature}}, {{CHANGE_DESCRIPTION}}, {{FeatureName}}, {{requirement}}, {{method}}, {{InputType}}, {{OutputType}}, {{result}}, {{DESCRIPTION}}, {{action}}, {{ACTION_DESCRIPTION}}, {{component}}, {{Component}}, {{alternative}}, {{deprecatedFunction}}, {{version}}, {{DEPRECATED_FEATURE}}, {{DATE}}, {{EOL_DATE}}, {{DAYS}}, {{timestamp}}, {{table}}, {{type}}, {{column}}, {{model}}, {{Feature}}, {{workflow}}, {{field}}, {{value}}, {{CHANGE_NAME}}, {{file}}, {{PATTERN}}, {{DEPENDENCIES}}, {{package}}, {{PURPOSE}}, {{NUMBER}}, {{AUTHOR}} before use. Copyright stays with the author.

SDD Change Apply Command

Apply a change proposal to the codebase.

Instructions for GitHub Copilot

You are executing the #sdd-change-apply [change-name] command to implement an approved change proposal.

Command Format

#sdd-change-apply add-2fa
#sdd-change-apply migrate-to-graphql
#sdd-change-apply refactor-auth-service

Your Task

Implement the changes defined in the change proposal, following constitutional governance and best practices.

Process

1. Read Change Proposal

IMPORTANT: Read the approved change proposal first:

# Read proposal
storage/changes/{{change-name}}-proposal.md

Extract:

• ADDED requirements
• MODIFIED requirements
• REMOVED requirements
• Implementation plan
• Testing requirements
• Success metrics

Verify Approval:

• Status must be "Approved" (not "Proposed" or "Rejected")
• If not approved, abort and notify user

2. Read Steering Context (Article VI)

# Read these files
steering/product.md      # Product context
steering/structure.md    # Architecture patterns
steering/tech.md         # Technology stack

3. Set Up Feature Flag

Create Feature Flag (for gradual rollout):

// lib/feature-flags/flags.ts

export const FEATURE_FLAGS = {
  // ... existing flags ...

  enable_{{feature}}: {
    enabled: false,  // Start disabled
    description: '{{CHANGE_DESCRIPTION}}',
    rolloutPercentage: 0,
  },
} as const;

Update Configuration:

// lib/feature-flags/config.ts

export function isFeatureEnabled(flag: keyof typeof FEATURE_FLAGS): boolean {
  if (process.env.NODE_ENV === 'test') {
    return true; // Always enabled in tests
  }

  const config = FEATURE_FLAGS[flag];
  if (!config.enabled) return false;

  // Gradual rollout logic
  return Math.random() * 100 < config.rolloutPercentage;
}

4. Implement Changes (Library-First - Article I)

For Each ADDED Requirement:

Step 4.1: Create Library Module

# Create library directory
mkdir -p lib/{{feature}}/

# Create core files
touch lib/{{feature}}/index.ts
touch lib/{{feature}}/types.ts
touch lib/{{feature}}/{{feature}}.ts
touch lib/{{feature}}/{{feature}}.test.ts
touch lib/{{feature}}/cli.ts  # Article II: CLI Interface Mandate

Step 4.2: Implement Core Logic

Test-First (Article III):

1. RED: Write failing test

// lib/{{feature}}/{{feature}}.test.ts

import { describe, it, expect } from 'vitest';
import { {{FeatureName}} } from './{{feature}}';

describe('{{FeatureName}}', () => {
  it('should {{requirement}}', () => {
    // Arrange
    const input = {{test-input}};

    // Act
    const result = new {{FeatureName}}().{{method}}(input);

    // Assert
    expect(result).toEqual({{expected-output}});
  });
});

2. GREEN: Implement to pass test

// lib/{{feature}}/{{feature}}.ts

export class {{FeatureName}} {
  {{method}}(input: {{InputType}}): {{OutputType}} {
    // Implementation
    return {{result}};
  }
}

3. BLUE: Refactor (improve code quality)

Step 4.3: Create CLI Interface (Article II)

// lib/{{feature}}/cli.ts

#!/usr/bin/env node

import { program } from 'commander';
import { {{FeatureName}} } from './{{feature}}';

program
  .name('{{feature}}')
  .description('{{DESCRIPTION}}')
  .version('1.0.0');

program
  .command('{{action}}')
  .description('{{ACTION_DESCRIPTION}}')
  .argument('<input>', 'Input parameter')
  .action(async (input) => {
    const feature = new {{FeatureName}}();
    const result = await feature.{{method}}(input);
    console.log(result);
  });

program.parse();

Make executable:

chmod +x lib/{{feature}}/cli.ts

Add to package.json:

{
  "bin": {
    "{{feature}}": "./lib/{{feature}}/cli.ts"
  }
}

Step 4.4: Integration Layer (Framework)

Use Framework Features Directly (Article VIII: Anti-Abstraction):

// app/api/{{feature}}/route.ts (Next.js)

import { NextRequest, NextResponse } from 'next/server';
import { {{FeatureName}} } from '@/lib/{{feature}}';
import { isFeatureEnabled } from '@/lib/feature-flags';

export async function POST(req: NextRequest) {
  // Feature flag check
  if (!isFeatureEnabled('enable_{{feature}}')) {
    return NextResponse.json(
      { error: 'Feature not enabled' },
      { status: 403 }
    );
  }

  const body = await req.json();
  const feature = new {{FeatureName}}();

  try {
    const result = await feature.{{method}}(body);
    return NextResponse.json(result);
  } catch (error) {
    return NextResponse.json(
      { error: error.message },
      { status: 400 }
    );
  }
}

5. Modify Existing Code

For Each MODIFIED Requirement:

Step 5.1: Read Current Implementation

# Find current code
grep -r "{{existing-function}}" lib/

Step 5.2: Write Tests for New Behavior

// lib/{{component}}/{{component}}.test.ts

describe('{{Component}} - Modified Behavior', () => {
  it('should {{new-behavior}}', () => {
    // Test new behavior
  });

  it('should maintain backward compatibility', () => {
    // Test old behavior still works (if applicable)
  });
});

Step 5.3: Update Implementation

// lib/{{component}}/{{component}}.ts

export class {{Component}} {
  {{method}}(input: {{InputType}}): {{OutputType}} {
    // NEW: Updated logic
    {{new-implementation}}

    // Maintain backward compatibility
    if ({{legacy-condition}}) {
      return {{legacy-behavior}};
    }

    return {{new-behavior}};
  }
}

Step 5.4: Update Tests

// Update existing tests to reflect new behavior
// Add new tests for new functionality

6. Remove Deprecated Code

For Each REMOVED Requirement:

Step 6.1: Mark as Deprecated First

// lib/{{component}}/{{deprecated-feature}}.ts

/**
 * @deprecated Use {{alternative}} instead. Will be removed in v2.0.0
 * @see {@link {{alternative}}}
 */
export function {{deprecatedFunction}}() {
  console.warn('{{deprecatedFunction}} is deprecated. Use {{alternative}} instead.');
  // Keep implementation for now
}

Step 6.2: Add Deprecation Notice

// Show deprecation warning
if (process.env.NODE_ENV !== 'production') {
  console.warn(`
    ⚠️  DEPRECATION WARNING
    
    The feature "{{feature}}" is deprecated and will be removed in version {{version}}.
    
    Migration: Use "{{alternative}}" instead.
    See: {{migration-guide-url}}
  `);
}

Step 6.3: Update Documentation

## Migration Guide: {{DEPRECATED_FEATURE}}

### Timeline

- **Deprecation**: {{DATE}}
- **End of Life**: {{EOL_DATE}} ({{DAYS}} days notice)

### Migration Steps

1. Replace old code:

   ```typescript
   // ❌ OLD (deprecated)
   {{old-code}}

   // ✅ NEW (recommended)
   {{new-code}}
   ```

2. Update imports:

   // ❌ OLD
   import { {{old-import}} } from '{{old-path}}';
   
   // ✅ NEW
   import { {{new-import}} } from '{{new-path}}';

3. Test changes

4. Deploy

Breaking Changes

{{list-of-breaking-changes}}

---

### 7. Database Migrations

**If Schema Changes Required**:

#### Step 7.1: Create Migration

```bash
# Prisma example
npx prisma migrate dev --name {{change-name}}

Step 7.2: Write Migration Script

-- migrations/{{timestamp}}_{{change-name}}.sql

-- Backup existing data
CREATE TABLE {{table}}_backup AS SELECT * FROM {{table}};

-- Add new columns
ALTER TABLE {{table}} ADD COLUMN {{new-column}} {{type}};

-- Modify existing columns
ALTER TABLE {{table}} ALTER COLUMN {{column}} TYPE {{new-type}};

-- Remove deprecated columns (after deprecation period)
-- ALTER TABLE {{table}} DROP COLUMN {{old-column}};

-- Create indexes
CREATE INDEX idx_{{table}}_{{column}} ON {{table}}({{column}});

Step 7.3: Write Rollback Script

-- migrations/{{timestamp}}_{{change-name}}_rollback.sql

-- Restore from backup
DROP TABLE {{table}};
CREATE TABLE {{table}} AS SELECT * FROM {{table}}_backup;

-- Or reverse operations
ALTER TABLE {{table}} DROP COLUMN {{new-column}};

Step 7.4: Test Migration

# Test forward migration
npm run db:migrate

# Test rollback
npm run db:rollback

# Verify data integrity
npm run db:verify

8. Write Tests (Article III & IX)

Test Coverage Requirements:

• Minimum 80% code coverage
• Integration tests (Article IX) over unit tests

Unit Tests

// lib/{{feature}}/{{feature}}.test.ts

describe('{{FeatureName}}', () => {
  describe('{{method}}', () => {
    it('should handle valid input', () => {
      // Happy path
    });

    it('should reject invalid input', () => {
      // Error handling
    });

    it('should handle edge cases', () => {
      // Boundary conditions
    });
  });
});

Integration Tests (Article IX: Integration-First)

// lib/{{feature}}/{{feature}}.integration.test.ts

import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { PrismaClient } from '@prisma/client';

describe('{{FeatureName}} Integration Tests', () => {
  let prisma: PrismaClient;

  beforeAll(async () => {
    // Use REAL database (test database)
    prisma = new PrismaClient({
      datasources: {
        db: { url: process.env.TEST_DATABASE_URL }
      }
    });
  });

  afterAll(async () => {
    await prisma.$disconnect();
  });

  it('should {{requirement}} with real database', async () => {
    // Arrange: Set up test data
    const testData = await prisma.{{model}}.create({
      data: {{test-data}}
    });

    // Act: Execute feature
    const feature = new {{FeatureName}}(prisma);
    const result = await feature.{{method}}(testData.id);

    // Assert: Verify result
    expect(result).toBeDefined();

    // Cleanup
    await prisma.{{model}}.delete({ where: { id: testData.id } });
  });
});

E2E Tests

// tests/e2e/{{feature}}.spec.ts

import { test, expect } from '@playwright/test';

test.describe('{{Feature}} E2E Tests', () => {
  test('should complete {{workflow}}', async ({ page }) => {
    // Navigate
    await page.goto('/{{feature}}');

    // Interact
    await page.fill('input[name="{{field}}"]', '{{value}}');
    await page.click('button[type="submit"]');

    // Assert
    await expect(page.locator('.success-message')).toBeVisible();
  });
});

9. Update Traceability Matrix

Create/Update Traceability Document:

## Traceability Matrix: {{CHANGE_NAME}}

| Requirement ID     | Design      | Implementation                  | Tests                   | Status |
| ------------------ | ----------- | ------------------------------- | ----------------------- | ------ |
| REQ-NEW-001        | Section 4.1 | lib/{{feature}}/{{file}}.ts:L25 | {{feature}}.test.ts:L40 | ✅     |
| REQ-AUTH-001 (MOD) | Section 7.2 | lib/auth/password.ts:L15        | password.test.ts:L30    | ✅     |
| REQ-AUTH-015 (REM) | -           | Deprecated                      | -                       | ⚠️     |

### Coverage

- Total Requirements: 15
- Implemented: 13 (87%)
- Tested: 13 (100% of implemented)
- Code Coverage: 85%

10. Constitutional Validation

Run Validation (Article I-IX):

# Article I: Library-First
ls -la lib/{{feature}}/  # Must exist

# Article II: CLI Interface
ls -la lib/{{feature}}/cli.ts  # Must exist
./lib/{{feature}}/cli.ts --help  # Must work

# Article III: Test-First
npm test -- lib/{{feature}}/  # Must pass
npm run coverage  # Must be >= 80%

# Article IV: EARS Format
grep -E "WHEN|SHALL|IF|WHILE|WHERE" storage/changes/{{change-name}}-proposal.md

# Article V: Traceability
# Check traceability matrix exists and is complete

# Article VIII: Anti-Abstraction
# Verify no unnecessary wrappers around framework features

# Article IX: Integration-First Testing
ls -la lib/{{feature}}/*.integration.test.ts  # Must exist

11. Update Steering (Auto-Update)

After Implementation, Update Steering Files:

<!-- steering/structure.md -->

## Components

### {{Feature}} (Added: {{DATE}})

- **Location**: `lib/{{feature}}/`
- **Purpose**: {{DESCRIPTION}}
- **Pattern**: {{PATTERN}}
- **Dependencies**: {{DEPENDENCIES}}

<!-- steering/tech.md -->

## Technology Stack

### New Dependencies ({{CHANGE_NAME}})

- `{{package}}@{{version}}` - {{PURPOSE}}

12. Save Implementation Summary

Create Implementation Report:

# Implementation Report: {{CHANGE_NAME}}

## Metadata

- **Change ID**: CHG-{{NUMBER}}
- **Status**: Implemented
- **Implemented**: {{DATE}}
- **Implemented By**: {{AUTHOR}}

## Changes Applied

### ADDED

- [ ] lib/{{feature}}/ - Core library ✅
- [ ] lib/{{feature}}/cli.ts - CLI interface ✅
- [ ] lib/{{feature}}/{{feature}}.test.ts - Tests ✅
- [ ] app/api/{{feature}}/route.ts - API endpoint ✅

### MODIFIED

- [ ] lib/auth/password.ts - Updated hashing ✅
- [ ] lib/auth/password.test.ts - Updated tests ✅

### REMOVED

- [ ] lib/auth/remember-me.ts - Deprecated (EOL: {{DATE}}) ⚠️

## Test Results

### Coverage

- Unit Tests: 45 passed
- Integration Tests: 12 passed
- E2E Tests: 5 passed
- **Coverage**: 87% (target: 80%) ✅

### Performance

- P95 latency: 145ms (target: <200ms) ✅
- Throughput: 1250 req/s (target: >1000) ✅

## Constitutional Compliance

- ✅ Article I: Library-First
- ✅ Article II: CLI Interface
- ✅ Article III: Test-First (RED-GREEN-BLUE)
- ✅ Article IV: EARS Format
- ✅ Article V: Traceability Matrix Complete
- ✅ Article VI: Steering Updated
- ✅ Article VIII: No Unnecessary Abstractions
- ✅ Article IX: Integration Tests Included

## Deployment Readiness

- [ ] Feature flag created ✅
- [ ] Monitoring/alerts configured ✅
- [ ] Documentation updated ✅
- [ ] Rollback plan tested ✅
- [ ] Stakeholders notified ✅

## Next Steps

1. Merge PR: `feat: {{change-name}}`
2. Deploy to staging
3. Run smoke tests
4. Deploy to production (canary rollout)
5. Monitor metrics for 48 hours
6. Enable feature flag gradually (5% → 50% → 100%)
7. Archive change: `#sdd-change-archive {{change-name}}`

Save To:

• English: storage/changes/{{change-name}}-implementation.md
• Japanese: storage/changes/{{change-name}}-implementation.ja.md

13. Generate Summary

## ✅ Change Implementation Complete

**Change**: {{CHANGE_NAME}}
**Change ID**: CHG-{{NUMBER}}

### Implementation Summary:

- **Files Added**: [N]
- **Files Modified**: [N]
- **Files Deprecated**: [N]
- **Tests Written**: [N]
- **Test Coverage**: XX%

### Constitutional Compliance:

- ✅ All 9 articles verified

### Quality Metrics:

- ✅ Tests: [N] passed, 0 failed
- ✅ Coverage: XX% (>= 80%)
- ✅ Performance: Within SLA
- ✅ Security: Audit passed

### Deployment Status:

- Feature flag: Created (disabled)
- Staging: Not deployed
- Production: Not deployed

### Next Steps:

1. Review implementation
2. Merge PR
3. Deploy to staging
4. Enable feature flag gradually
5. Archive change: `#sdd-change-archive {{change-name}}`

Validation Checklist

Before completing, verify:

• Change proposal read and understood
• Approval status verified
• Steering context applied
• Feature flag created
• Library-first implementation (Article I)
• CLI interface provided (Article II)
• Tests written first (Article III)
• Test coverage >= 80%
• Integration tests included (Article IX)
• Traceability matrix updated
• Constitutional compliance verified
• Steering files updated
• Implementation report saved
• Summary presented to user

Execution: Begin change implementation now for the specified change.