cap-pro 1.0.0

package/cap/references/continuation-format.md

@@ -0,0 +1,249 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up
+
+**{identifier}: {name}** — {one-line description}
+
+`{command to copy-paste}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+## Format Rules
+
+1. **Always show what it is** — name + description, never just a command path
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+4. **`/clear` explanation** — always include, keeps it concise but explains why
+5. **"Also available" not "Other options"** — sounds more app-like
+6. **Visual separators** — `---` above and below to make it stand out
+
+## Variants
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/gsd:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/gsd:list-phase-assumptions 2` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ Next Up
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+<sub>Final plan in Phase 2</sub>
+
+`/gsd:execute-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/gsd:plan-phase 2`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 2` — gather context first
+- `/gsd:research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/gsd:plan-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 3` — gather context first
+- `/gsd:research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+**To plan directly:** `/gsd:plan-phase 3`
+
+**To discuss context first:** `/gsd:discuss-phase 3`
+
+**To research unknowns:** `/gsd:research-phase 3`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/gsd:new-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/gsd:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/gsd:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/gsd:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/cap/references/contract-test-templates.md

@@ -0,0 +1,312 @@
+# Contract Test Templates
+
+Reference document for the cap-validator agent (test mode) when generating contract tests between monorepo apps or microservices. Contract tests verify that producer and consumer agree on API shape, event format, and shared types.
+
+---
+
+## 1. API Contract Tests (Schema Validation)
+
+Verify that API responses match the expected schema. Use when one app consumes another app's API.
+
+### Response schema validation
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import Ajv from 'ajv';
+
+// Define the contract schema (shared between producer and consumer)
+const userSchema = {
+  type: 'object',
+  required: ['id', 'email', 'name', 'created_at'],
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    email: { type: 'string', format: 'email' },
+    name: { type: 'string', minLength: 1 },
+    created_at: { type: 'string', format: 'date-time' },
+    role: { type: 'string', enum: ['user', 'admin', 'moderator'] },
+  },
+  additionalProperties: false,
+};
+
+describe('API Contract: GET /api/users/:id', () => {
+  const ajv = new Ajv({ allErrors: true, formats: { uuid: true, email: true, 'date-time': true } });
+
+  it('response matches user schema', async () => {
+    const response = await fetch(`${API_URL}/api/users/${testUserId}`);
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    const validate = ajv.compile(userSchema);
+    const valid = validate(data);
+    expect(valid).toBe(true);
+    if (!valid) console.error('Schema violations:', validate.errors);
+  });
+
+  it('list response matches array of user schema', async () => {
+    const response = await fetch(`${API_URL}/api/users`);
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(Array.isArray(data)).toBe(true);
+
+    const validate = ajv.compile(userSchema);
+    for (const item of data) {
+      expect(validate(item)).toBe(true);
+    }
+  });
+});
+```
+
+### Request contract validation (producer side)
+
+```typescript
+describe('API Contract: POST /api/bookings (request validation)', () => {
+  it('rejects request missing required fields', async () => {
+    const response = await fetch(`${API_URL}/api/bookings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ /* missing required fields */ }),
+    });
+    expect(response.status).toBe(400);
+    const body = await response.json();
+    expect(body.errors).toBeDefined();
+  });
+
+  it('rejects request with wrong field types', async () => {
+    const response = await fetch(`${API_URL}/api/bookings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        start_time: 'not-a-date',
+        duration: 'not-a-number',
+        resource_id: 123, // should be string
+      }),
+    });
+    expect(response.status).toBe(400);
+  });
+
+  it('accepts valid request matching contract', async () => {
+    const response = await fetch(`${API_URL}/api/bookings`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify({
+        start_time: '2026-04-01T10:00:00Z',
+        duration: 60,
+        resource_id: 'room-a',
+      }),
+    });
+    expect([200, 201]).toContain(response.status);
+  });
+});
+```
+
+### Version compatibility
+
+```typescript
+describe('API Contract: version compatibility', () => {
+  it('v1 response is backward-compatible with v2 consumer', async () => {
+    const response = await fetch(`${API_URL}/api/v1/users/${testUserId}`);
+    const data = await response.json();
+
+    // v2 consumer expects these fields exist
+    expect(data).toHaveProperty('id');
+    expect(data).toHaveProperty('email');
+    // v2 added 'avatar_url' -- should handle absence gracefully
+    const avatarUrl = data.avatar_url ?? null;
+    expect(avatarUrl === null || typeof avatarUrl === 'string').toBe(true);
+  });
+});
+```
+
+---
+
+## 2. Event Contract Tests (Message Format)
+
+Verify that events/messages emitted by one service match the format expected by consumers.
+
+### Event payload validation
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+// Shared event contract
+const bookingCreatedSchema = {
+  type: 'booking.created',
+  version: '1.0',
+  payload: {
+    booking_id: 'string:uuid',
+    user_id: 'string:uuid',
+    resource_id: 'string',
+    start_time: 'string:iso-datetime',
+    end_time: 'string:iso-datetime',
+    status: 'string:enum(pending,confirmed,cancelled)',
+  },
+};
+
+describe('Event Contract: booking.created', () => {
+  it('emitted event matches contract schema', async () => {
+    // Arrange: create a booking (producer action)
+    const booking = await createBooking({
+      user_id: testUserId,
+      resource_id: 'room-a',
+      start_time: '2026-04-01T10:00:00Z',
+      end_time: '2026-04-01T11:00:00Z',
+    });
+
+    // Act: capture the emitted event
+    const event = await captureEvent('booking.created');
+
+    // Assert: event matches contract
+    expect(event.type).toBe('booking.created');
+    expect(event.version).toBe('1.0');
+    expect(event.payload).toBeDefined();
+    expect(typeof event.payload.booking_id).toBe('string');
+    expect(typeof event.payload.user_id).toBe('string');
+    expect(typeof event.payload.resource_id).toBe('string');
+    expect(typeof event.payload.start_time).toBe('string');
+    expect(typeof event.payload.end_time).toBe('string');
+    expect(['pending', 'confirmed', 'cancelled']).toContain(event.payload.status);
+  });
+
+  it('consumer can deserialize event payload', async () => {
+    const rawEvent = JSON.stringify({
+      type: 'booking.created',
+      version: '1.0',
+      payload: {
+        booking_id: '550e8400-e29b-41d4-a716-446655440000',
+        user_id: '123e4567-e89b-12d3-a456-426614174000',
+        resource_id: 'room-a',
+        start_time: '2026-04-01T10:00:00Z',
+        end_time: '2026-04-01T11:00:00Z',
+        status: 'confirmed',
+      },
+    });
+
+    // Consumer deserialization
+    const parsed = JSON.parse(rawEvent);
+    const startTime = new Date(parsed.payload.start_time);
+    expect(startTime.getTime()).toBeGreaterThan(0);
+    expect(parsed.payload.booking_id).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+    );
+  });
+});
+```
+
+### Event ordering and idempotency
+
+```typescript
+describe('Event Contract: idempotency', () => {
+  it('processing same event twice produces same result', async () => {
+    const event = {
+      type: 'booking.created',
+      idempotency_key: 'test-key-001',
+      payload: { booking_id: 'b-001', user_id: 'u-001', resource_id: 'room-a' },
+    };
+
+    const result1 = await processEvent(event);
+    const result2 = await processEvent(event);
+    expect(result1).toEqual(result2);
+  });
+
+  it('events with different versions are handled gracefully', async () => {
+    const eventV2 = {
+      type: 'booking.created',
+      version: '2.0',
+      payload: {
+        booking_id: 'b-002',
+        user_id: 'u-001',
+        resource_id: 'room-a',
+        // v2 adds new field
+        recurring: true,
+      },
+    };
+
+    // v1 consumer should not crash
+    const result = await processEvent(eventV2);
+    expect(result).toBeDefined();
+  });
+});
+```
+
+---
+
+## 3. Shared Type Contract Tests (TypeScript)
+
+When apps share types via a `packages/shared` or similar, test that the types match reality.
+
+### Type-to-runtime validation
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { Booking, User, BookingStatus } from '@myapp/shared';
+
+describe('Shared Type Contract: Booking', () => {
+  it('runtime booking object satisfies Booking type shape', () => {
+    // Simulate what the API actually returns
+    const apiResponse = {
+      id: 'b-001',
+      user_id: 'u-001',
+      resource_id: 'room-a',
+      start_time: '2026-04-01T10:00:00Z',
+      end_time: '2026-04-01T11:00:00Z',
+      status: 'confirmed' as BookingStatus,
+      created_at: '2026-03-31T00:00:00Z',
+    };
+
+    // Runtime checks matching the TypeScript interface
+    const booking: Booking = apiResponse;
+    expect(typeof booking.id).toBe('string');
+    expect(typeof booking.user_id).toBe('string');
+    expect(typeof booking.resource_id).toBe('string');
+    expect(typeof booking.start_time).toBe('string');
+    expect(typeof booking.end_time).toBe('string');
+    expect(['pending', 'confirmed', 'cancelled']).toContain(booking.status);
+  });
+
+  it('required fields are never null in production data', async () => {
+    const bookings = await fetchBookings();
+    for (const booking of bookings) {
+      expect(booking.id).not.toBeNull();
+      expect(booking.user_id).not.toBeNull();
+      expect(booking.start_time).not.toBeNull();
+      expect(booking.end_time).not.toBeNull();
+      expect(booking.status).not.toBeNull();
+    }
+  });
+});
+```
+
+### Cross-package import validation
+
+```typescript
+describe('Shared Type Contract: cross-package imports', () => {
+  it('shared types can be imported by consumer package', async () => {
+    // This test verifies the build/bundling doesn't break type exports
+    const shared = await import('@myapp/shared');
+    expect(shared).toBeDefined();
+    expect(typeof shared.BookingStatusEnum).toBeDefined();
+  });
+
+  it('shared constants match between packages', () => {
+    // Both producer and consumer should use same status values
+    const validStatuses = ['pending', 'confirmed', 'cancelled'];
+    expect(validStatuses).toEqual(expect.arrayContaining(['pending', 'confirmed', 'cancelled']));
+  });
+});
+```
+
+---
+
+## Usage Notes
+
+When generating contract tests:
+
+1. **Define the contract first** -- write the expected schema before writing the test
+2. **Test both sides** -- producer should validate it emits correctly, consumer should validate it can parse
+3. **Version contracts** -- include version in schema, test backward compatibility
+4. **Use fixture data** -- keep test payloads close to real production data shapes
+5. **For monorepos**: put contract definitions in `packages/shared/contracts/`
+6. **For microservices**: each service owns its producer contract, consumers write their own consumer tests
+7. **Test evolution**: when adding fields, verify old consumers still work
+8. **Idempotency**: always test that duplicate message processing is safe

package/cap/references/feature-map-template.md

@@ -0,0 +1,25 @@
+# Feature Map
+
+<!-- @gsd-context Template for FEATURE-MAP.md -- the single source of truth in CAP v2.0. Generated by /cap:init, populated by /cap:brainstorm, updated by /cap:scan. -->
+<!-- @gsd-decision Markdown table format: human-readable, git-diffable, machine-parseable via regex. Each feature is a section with an AC table. -->
+
+**Last scan:** _never_
+
+## Features
+
+_No features defined yet. Run `/cap:brainstorm` to discover features or add them manually below._
+
+<!--
+## Feature Template
+
+### Feature Name
+
+**Group:** Group Name
+**Status:** draft
+**Dependencies:** none
+
+| AC | Description | Status |
+|----|-------------|--------|
+| AC-1 | Imperative description of acceptance criterion | pending |
+| AC-2 | Another acceptance criterion | pending |
+-->