21 - Copilot Spaces and Memory: Persistent Knowledge for the Team

┌─ Spring Boot Backend Auth Space (Esempio reale) ────────────────┐
│                                                                   │
├─ Repository Sources                                              │
│  ├─ src/main/java/dev/federicocalo/portfolio/domain/     (pinned)│
│  ├─ src/main/java/dev/federicocalo/portfolio/application/       │
│  ├─ src/main/resources/db/migration/           (Flyway DDL)     │
│  └─ docs/06_compliance/04_refactoring_architetturale/           │
│                                                                   │
├─ Pull Requests (auto-indexed)                                    │
│  ├─ #247: "feat: JWT proprietaria con refresh token"            │
│  ├─ #251: "fix: SSRF guard per External API"                    │
│  └─ #245: "test: AuthControllerTest @Testcontainers"            │
│                                                                   │
├─ Issues (reference automatica)                                   │
│  ├─ #198: "Security: Implement SUPER_ADMIN role"                │
│  └─ #204: "Feature: API Key management for dataset queries"      │
│                                                                   │
├─ Free-text Notes                                                 │
│  ├─ "JWT Strategy: HS256 via JwtService, refresh hash-in-DB"    │
│  ├─ "Roles hierarchy: GUEST

1. Vai a github.com/settings/copilot/spaces
   (oppure clicca "Copilot" nel menu principale)

2. Clicca "New Space" (pulsante blu in alto a destra)

3. Compila il form:
   Nome Space:           "Spring Boot Backend Auth"
   Descrizione:          "Architecture, JWT strategy, role hierarchy, security"
   Privacy:              "Private" (default, cambiabile a dicembre con Public Spaces)
   Repository (optional): seleziona il repo principale (es. portfolio-backend)

4. Clicca "Create Space"

Nella pagina dello Space:

1. AGGIUNGI REPOSITORY
   - Clicca "Add Repository" → seleziona portfolio-backend
   - GitHub auto-indexes il contenuto
   - Indicizzazione: real-time su push

2. PINNA FILE SPECIFICI (per focus)
   - Naviga: src/main/java/dev/federicocalo/portfolio/...
   - Clicca ⭐ "Pin" accanto ai file chiave:
     ✓ presentation/controller/AuthController.java
     ✓ application/auth/usecase/LoginUseCase.java
     ✓ domain/auth/JwtTokenProvider.java
     ✓ infrastructure/security/JwtService.java
     ✓ src/main/resources/db/migration/V011__auth_tables.sql
   - I file pinnati appaiono come "High Priority" in Copilot

3. AGGIUNGI PULL REQUESTS
   - Sezione "Pull Requests" → "Add PR"
   - Seleziona PR importanti:
     #247: feat(security): JWT proprietaria con refresh token
     #251: fix(security): SSRF guard per external API
   - Copilot indexa titolo, descrizione, commenti, diff

4. AGGIUNGI NOTE LIBERE
   - Sezione "Notes" → "New Note"
   - Titolo: "JWT Architecture & Refresh Token Flow"
   - Contenuto: (copia-incolla)
     """
     ## JWT Strategy
     - Algoritmo: HS256
     - Issuer: federicocalo.dev
     - Expire: 15 minuti (access), 30 giorni (refresh)
     - Refresh token: hash-in-DB, validazione su ogni refresh
     - Scopo: Autenticazione stateless con sessione backend opzionale

     ## Roles Hierarchy
     GUEST < USER < PRO < MODERATOR < ADMIN < SUPER_ADMIN
     - GUEST: No auth, public content only
     - USER: Basic user, newsletter, comments
     - PRO: Premium features, dataset marketplace
     - MODERATOR: Content moderation, user reports
     - ADMIN: Full admin except SUPER_ADMIN operations
     - SUPER_ADMIN: System administration, user role assignment

     ## Security Constraints
     - SSRF guard blocca IP privati, loopback, link-local
     - Rate limiting Bucket4j: 120 req/min API, 6 req/min AI
     - CORS whitelist: federicocalo.dev, localhost dev
     """

5. AGGIUNGI DIAGRAMMI (file upload)
   - Sezione "Attachments" → "Upload"
   - Carica:
     auth-flow-diagram.png (sequence diagram JWT flow)
     role-hierarchy.svg (grafo gerarchico ruoli)
     database-schema.png (auth tables ER diagram)
   - Copilot li analizza via vision quando rilevante

Nella pagina dello Space → Settings:

1. AGGIUNGI TEAM MEMBERS
   - Clicca "Share Space" → "Add People"
   - Seleziona: @frontend-team, @backend-team, @qa-team
   - Permessi: "Read" (default, loro non possono editare)
   - Oppure assegna "Edit" se trusted maintainer

2. GENERA LINK PUBBLICO (dicembre 2025)
   - After dicembre 9: attiva "Public Spaces"
   - Genera link non-discoverable (e.g., /spaces/uuid-xxx)
   - Condividi con OSS community, contractor, auditor

3. VISIBILITÀ
   - Private (default): Solo invitati
   - Public (dicembre): Visibile via link, non su GitHub Spaces directory
   - Future: Discovery directory (roadmap GitHub)

## Passo 1: Individua i tuoi Knowledge Bases
Vai a github.com/settings/copilot/knowledge-bases
Lista tutti i KB che hai creato

## Passo 2: Clicca "Convert to Space" (dal 17 ottobre)
Per ogni Knowledge Base:
  1. Apri il KB
  2. Clicca "Convert to Space" (nuova UI button)
  3. Seleziona il repository principale
  4. Rivedi i file pinned (GitHub proverà a mappare i file caricati)
  5. Clicca "Create Space"

## Passo 3: Verifica il Space
  1. Nuovo Space appare in Copilot Spaces
  2. Controlla che tutti i file key siano pinned
  3. Aggiungi note aggiuntive se necessario
  4. Verifica che PR/Issues siano correttamente indexate

## Passo 4: Decommissiona il Knowledge Base
  1. Torna al KB originale
  2. Clicca "Delete" (non più usato)
  3. Dichiara il nuovo Space come canonical reference

## Timeline (Consigliato)
- Oct 17-24: Converti il 50% dei KB (test veloce)
- Oct 25-31: Converti il 50% rimanente + verifica finale
- Nov 1: Knowledge Bases scompaiono, Spaces sono la nuova norma

Nella pagina dello Space → Settings:

1. Visibilità: Cambia da "Private" a "Public"
   - GitHub genera un UUID link: /spaces/abc123def456
   - Non appare su https://github.com/spaces (no directory listing)
   - Chiunque abbia il link può visualizzare (view-only by default)

2. Condividi il link
   - Con community: posta su Twitter/Reddit/Dev.to
   - Con contractor: email the link per onboarding
   - Con auditor: per review architetturale

3. Permessi di View-Only
   - I visitatori possono leggere il contesto
   - NON possono modificare, pinare, o aggiungere file
   - Il team che possiede lo Space rimane gestore esclusivo

Esempio link: https://github.com/spaces/abc123-portfolio-backend-auth

Nella pagina dello Space → Share → "Invite People":

1. Digita username GitHub (e.g., @john-doe)
2. Seleziona permessi: "View" (default) oppure "Edit"
3. Clicca "Send Invite"
4. L'utente riceve notifica + link privato allo Space
5. Lui è l'unico che può accedere (no link pubblico)

Scenari di utilizzo:
- Contractor che lavora su una feature: invite con "Edit" + repo specifico pinnato
- Client esterno che rivede l'architettura: invite con "View"
- Auditor di sicurezza: invite con "View" + access a decision records & security notes

1. Naviga a github.com/portfolio-backend/blob/main/src/main/java/...JwtService.java
2. Nel file viewer, clicca il menu "..." (three dots)
3. Seleziona "Add to Space"
4. Scegli quale Space (dropdown)
5. Clicca "Add"
6. Il file è ora pinnato; Copilot lo vede istantaneamente

Vantaggi:
- Non serve uscire dal file viewer
- Workflow naturale mentre navigate il codebase
- Gli altri team member vedono subito il file pinnato

Scenario 1: USER-LEVEL MEMORY

In Copilot Chat (qualsiasi progetto), scrivi:
> Remember: I prefer immutability. Always create new objects, never mutate.
> Remember: I want TypeScript strict mode enabled.
> Remember: Test-driven development. Write tests first.

Copilot risponde:
"✓ Remembered: immutability preference
 ✓ Remembered: TypeScript strict mode
 ✓ Remembered: TDD approach"

Ora, in ogni progetto futuro, Copilot appliche questi principi.

---

Scenario 2: REPOSITORY-LEVEL MEMORY

In Copilot Chat (questo repo), scrivi:
> For this repository, remember:
> - Clean Architecture: 4-layer (domain > application > infrastructure > presentation)
> - No circular dependencies allowed
> - Use case classes end with "UseCase" (LoginUseCase.java)
> - Target 80% test coverage
> - Rate limiting via Bucket4j
> - JWT: HS256 via JwtService, refresh token hash-in-DB

Copilot risponde:
"✓ Remembered for portfolio-backend:
 - Architecture: Clean 4-layer
 - No cycles
 - UseCase naming
 - 80% coverage
 - Bucket4j rate limiting
 - JWT strategy"

Solo quando lavori in portfolio-backend, questi constraint si applicano.
Su altri repo, il memory è indipendente.

---

Scenario 3: QUERY CHE ATTIVA MEMORY

Adesso chiedi:
> Implementa il controller per la autenticazione
> Scrivi i test prima

Copilot ricorda:
1. TDD approach (da user memory) → write tests first
2. Clean Architecture (da repo memory) → controller in presentation layer
3. UseCase suffix (da repo memory) → LoginUseCase in application layer
4. 80% coverage target (da repo memory) → comprehensive test cases
5. JWT strategy (da repo memory) → JWT handling specifico

La risposta è personalizzata su TUTTI questi preferenze memorizzate.

Giorno 1: Pomeriggio - Copilot Chat VS Code
> @copilot, remember: For portfolio-backend, use Clean Architecture strictly

Giorno 2: Mattina - Copilot Code Review GitHub
Apri una PR: "#252: Add UserController"
Copilot automaticamente commenta:
"✓ I see Clean Architecture is in effect.
 Suggestion: UserController should be in 'presentation/controller'.
 I also remember: 80% test coverage target. This PR has 45 tests for X changes - on track."

Giorno 3: Sera - Copilot CLI (se lanciato)
$ copilot explain src/main/java/.../UserController.java
Copilot automaticamente applica le Clean Architecture rules e commenta.

=> Memory è sincronizzato ovunque tu sia in GitHub ecosystem.

┌─ MEMORIA PERSONALE (Memory) ─────────────────┐
│ Domanda: "Voglio che Copilot ricordi sempre…?"      │
│ Risposta: SÌ (memoria personale)                     │
│ Esempi:                                              │
│  - "Preferisco records Java per DTOs"                │
│  - "TypeScript strict mode sempre"                   │
│  - "TDD: test first, implementation secondo"         │
│  - "Niente mutation, immutabilità sempre"            │
│  - "Usa English per i commenti nel codice"           │
│ → Usare: Memory (user-level)                         │
└──────────────────────────────────────────────┘

┌─ MEMORIA TEAM/PROGETTO (Spaces) ──────────────┐
│ Domanda: "Vuoi che il team lo conosca…?"            │
│ Risposta: SÌ (contesto condiviso)                    │
│ Esempi:                                              │
│  - "Usiamo Clean Architecture 4-layer"               │
│  - "Spring Boot 3.4, Java 21, PostgreSQL"            │
│  - "Rate limiting Bucket4j, JWT HS256"               │
│  - "Decision records in docs/"                       │
│  - "PR template: #issue, description, test plan"     │
│ → Usare: Spaces (team-level)                         │
└──────────────────────────────────────────────┘

┌─ CONTESTO REPOSITORY-SPECIFICO ─────────────┐
│ Domanda: "Vale solo per questo repo…?"               │
│ Risposta: SÌ                                         │
│ Esempi:                                              │
│  - "Questo repo: Clean Arch 4-layer"                 │
│  - "Questo repo: 80% test coverage"                  │
│  - "Questo repo: UI TypeScript strict"               │
│ → Usare: Memory (repository-scoped)                  │
│ + Spaces (per contesto vivo: PR, issues)             │
└──────────────────────────────────────────────┘

# Copilot Chat → set user-level memory

> Remember:
> - Immutability first: create new objects, never mutate
> - TypeScript strict mode always
> - Java: prefer records for DTOs (immutable)
> - TDD: write tests first
> - No deep nesting: max 4 levels
> - Functions <50 lines, files <800 lines
> - Explicit error handling everywhere
> - No hardcoded values: use constants or config
> - Code review before commit: readability, naming, structure
> - Performance: think caching, lazy loading, bundling

Copilot risponde:
"✓ User memory set for Federico Calò
 - Immutability enforcement
 - TypeScript strict
 - Java records for DTOs
 - TDD approach
 - Code size limits (4 nesting, 50 line functions, 800 line files)
 - Error handling
 - Constants not hardcoding
 - Pre-commit review
 - Performance mindset"

Da qui in poi, TUTTI i comandi di Copilot (chat, code generation, refactoring, test generation)
useranno questi principi.

# In Copilot Chat, con la directory backend/ aperta

> For this repository (portfolio-backend), remember:
>
> ## Architecture
> - Clean Architecture 4-layer (domain > application > infrastructure > presentation)
> - Zero circular dependencies
> - Domain layer: business rules, entities, ports (no framework)
> - Application layer: use cases, DTOs, orchestration
> - Infrastructure layer: persistence, external integrations
> - Presentation layer: controllers, REST API, request/response marshaling
>
> ## Code Standards
> - Use case classes: *UseCase suffix (LoginUseCase, PublishArticleUseCase)
> - DTOs: records (immutable)
> - Repositories: interface in domain, impl in infrastructure
> - No service layer (use cases replace it)
> - DTOs use @Builder or records
>
> ## Testing
> - Target: 80%+ coverage
> - JUnit 5 + Mockito
> - Testcontainers for integration (PostgreSQL, Redis)
> - Test naming: testXxxWithYyyExpectZzz
>
> ## Dependencies
> - Spring Boot 3.4.1
> - Java 21
> - PostgreSQL 16 (database)
> - Redis Stack 7 (cache)
> - Bucket4j (rate limiting)
> - Resilience4j (circuit breaker, retry)
> - Spring Security + JWT (HS256)
> - Spring Data JPA + Flyway
>
> ## Security
> - JWT: HS256 via JwtService
> - Refresh token: hash-in-DB (not in JWT)
> - Roles: GUEST - SSRF guard: block private IPs, loopback, link-local
> - Rate limit: 120 req/min API, 6 req/min AI
> - CORS whitelist: federicocalo.dev + localhost
>
> ## Performance Targets
> - API response: <100ms p99
> - Database queries: indexed on common lookups
> - Caching: Spring Cache @Cacheable (1h TTL typical)
> - No N+1 queries
>
> ## Database
> - PostgreSQL 16
> - Flyway migrations (src/main/resources/db/migration/)
> - Migration naming: V###__description.sql
> - No data mutation migration (data fixtures only)
>
> ## External Integrations
> - Stripe SDK: checkout sessions, webhooks (5 event types)
> - Email: self-hosted Postfix+Resend (EmailService)
> - Python ML: fallback provider chain (Cloudflare → Ollama)

Copilot risponde:
"✓ Repository memory set for portfolio-backend:
 - Clean Architecture enforced
 - UseCase naming standard
 - 80% coverage target
 - JUnit 5 + Mockito
 - Spring Boot 3.4.1 with Security/JWT
 - PostgreSQL + Redis
 - Bucket4j rate limiting
 - API <100ms p99 target"

D'ora in poi, quando lavori su portfolio-backend, Copilot applica questi constraint.
Se generi un controller, lo metterà in presentation/. Se scrivi test, userà JUnit 5.

# In Copilot Chat, con la directory frontend/ aperta

> For this repository (portfolio-frontend), remember:
>
> ## Framework & Stack
> - Angular 21 with @angular/ssr (Server-Side Rendering)
> - TypeScript 5.9 (strict mode)
> - Standalone components (no modules)
> - OnPush change detection everywhere
> - Signals for state management (no RxJS except HTTP)
> - CSS scoped to component (no global styles)
>
> ## Component Structure
> - One component per file
> - File naming: kebab-case (user-profile.component.ts)
> - Component class: PascalCase (UserProfileComponent)
> - Selector: app-user-profile (app- prefix)
> - Template: inline (unless >100 lines, then separate .html)
> - Styles: inline (unless >50 lines, then separate .css)
>
> ## Routing
> - Lazy-loaded routes (RenderMode.Server for SSR)
> - Route guards for auth (canActivate)
> - 1014 prerendered routes for SEO
>
> ## Testing
> - Jasmine + Karma
> - Target: 80% coverage (currently 2.7%, improving)
> - Test naming: should...when...
> - Mock services with jasmine.createSpyObj
>
> ## I18n
> - XLF translation format
> - 18 languages: IT, EN (compiled), 16 (fallback)
> - i18n keys on every new component (mandatory)
> - Extract with ng extract-i18n
>
> ## Performance Targets
> - FCP <1.5s, LCP <2.5s, TTI <3.5s
> - Bundle <3 MB (initial), <40 kB per lazy route
> - Lighthouse score 90+ (all categories)
> - Image lazy loading + WebP format
>
> ## Accessibility
> - WCAG 2.1 AA compliance
> - Semantic HTML5
> - ARIA labels where needed
> - Keyboard navigation support
> - Focus indicators visible
>
> ## SEO
> - Meta tags (title, description, og:*)
> - JSON-LD structured data
> - Sitemap with 18 language versions
> - Canonical URLs

Copilot risponde:
"✓ Repository memory set for portfolio-frontend:
 - Angular 21 SSR + TypeScript strict
 - Standalone components + OnPush
 - Signals for state
 - Lazy routing
 - 18-language i18n
 - 80% test coverage target
 - Lighthouse 90+
 - WCAG 2.1 AA"

Space Name: "Portfolio Backend - Authentication & Security"
Privacy: Private (team-only, no public for security reasons)

Contents:
1. Repository Links
   ✓ portfolio-backend (full)
   ✓ Pinned: src/main/java/dev/.../auth/
   ✓ Pinned: src/main/resources/db/migration/V0{11-20}*auth*

2. Pull Requests
   ✓ #247: feat(security): JWT proprietaria con refresh token
   ✓ #251: fix(security): SSRF guard per external API
   ✓ #245: test(auth): AuthControllerTest @Testcontainers

3. Issues
   ✓ #198: Security: Implement SUPER_ADMIN role
   ✓ #204: Feature: API Key management
   ✓ #156: Security audit: rate limiting

4. Free-Text Notes
   ### JWT Architecture
   - Algoritmo: HS256
   - Issuer: federicocalo.dev
   - Access token: 15 minuti
   - Refresh token: 30 giorni (hash-in-DB)

   ### Roles Hierarchy
   GUEST

Mattina (9:00): Standup backend
- Copilot Chat aperto
- User memory attivo: immutability, TDD, clean architecture
- Repo memory (portfolio-backend) attivo: Clean Architecture 4-layer, JWT, 80% coverage
- Copilot Spaces "Portfolio Auth" in sidebar
=> Federico chiede: "Implementa il controller per user registration"
   Copilot automaticamente:
   - Mette il controller in presentation/
   - Crea la use case in application/ (RegisterUserUseCase)
   - Scaffolda il domain entity e port
   - Scrive i test prima (TDD)
   - Applica Clean Arch (no circular deps)
   - Implementa error handling esplicito
   - Applica rate limiting Bucket4j
   - Usa records per RegistrationRequest/Response DTOs

Pomeriggio (14:00): Code review
- Apre una PR #256
- Copilot Code Review (powered by Memory)
- Commento automatico:
  "✓ Clean Architecture respected (controller → usecase → domain)
   ✓ Tests present (TDD observed)
   ✓ 87 tests (+5 new) = 80.2% coverage target on track
   ✓ Rate limiting applied (Bucket4j)
   ✓ Error handling comprehensive
   🔍 Suggestion: Consider caching password check failures (rate limit brute-force)"

Sera (18:00): Onboarding contractor
- Condividi lo Space "Portfolio Auth" con contractor (individual share, dicembre)
- Contractor può leggere tutta l'architettura
- Copilot sa che contractor ha accesso: limitato a specifico file pinnato
- Team rimane proprietario dello Space

# Procedure (expected aprile 2026)

1. Vai a GitHub Settings → Copilot → Data Residency
2. Seleziona: "European Union (Ireland)"
3. Conferma che sei una persona/organizzazione EU
4. GitHub migra Memory + Chat history (potrebbe richiedere 24-48 ore)

## Verifica
- Impostazione è salvata in Settings
- Nuovi Copilot prompts sono stored in ireland-1
- Precedente data rimane in us-east-1 (migrazione in corso)

## Note
- Se cambi regione, Memory non viene cancellato
- Solo il NEW data storage location cambia
- Performance could differ slightly (latency ireland vs usa)

$ copilot explain ./src/main/java/auth/JwtService.java

# Copilot legge il file e applica Memory:
# - User memory: immutability, TDD, clean arch
# - Repo memory (portfolio-backend): Clean Architecture 4-layer, JWT specifics
# - Genera spiegazione che rispetta tutti questi constraint

Output:
"JwtService: Provides HS256 JWT generation and validation.

Key methods:
- generateAccessToken(): Creates 15-min JWT
- generateRefreshToken(): Creates 30-day refresh (hash-in-DB, not JWT)
- validateToken(): Validates signature and expiry

Architecture: Application layer service, injected into AuthController.
Immutability: Token claims are final/immutable.
Testing: Full coverage in JwtServiceTest with Mockito.

Note: Remember your memory says 'no circular dependencies' - this class
is imported by AuthController (presentation) correctly."

---

$ copilot generate-code --context "portfolio-backend" --type "usecase"
Enter description: "User password reset with email confirmation"

# Genera un UseCase seguendo Memory:

---

$ copilot review my-branch

# Analizza commit su my-branch applicando Memory:
# - Clean Architecture rules
# - Test coverage target
# - Security constraints
# - Performance targets