sentryagent-idp/openspec/changes/engineering-docs/tasks.md

## 1. Setup

- [x] 1.1 Create `docs/engineering/` directory
- [x] 1.2 Create `docs/engineering/README.md` index with numbered document list, reading order guidance, and one-line description of each document

## 2. Company and Product Overview (01-overview.md)

- [x] 2.1 Write company mission and SentryAgent.ai product purpose section
- [x] 2.2 Write AGNTCY alignment explanation — what AGNTCY is, why it matters, what "first-class agent identity" means
- [x] 2.3 Write product features summary table covering all capabilities (agent registry, OAuth 2.0, credentials, audit, SDKs, dashboard, OPA, monitoring)
- [x] 2.4 Write Phase roadmap section (Phase 1 / Phase 2 / Phase 3 scope)
- [x] 2.5 Write Virtual Engineering Team model explanation (CTO → Architect → Developer → QA, Claude as engineering partner)
- [x] 2.6 Write free tier limits table

## 3. System Architecture (02-architecture.md)

- [x] 3.1 Write component diagram (ASCII or Mermaid) showing all major components and their connections
- [x] 3.2 Write HTTP request lifecycle section — client → router → middleware → controller → service → repository → database → response
- [x] 3.3 Write OAuth 2.0 Client Credentials data flow section
- [x] 3.4 Write multi-region deployment topology section

## 4. Technology Stack and ADRs (03-tech-stack.md)

- [x] 4.1 Write ADR entry for Node.js 18 — purpose, rationale, alternatives considered
- [x] 4.2 Write ADR entry for TypeScript 5.3 strict mode — purpose, rationale, consequences of violation
- [x] 4.3 Write ADR entry for Express 4.18 — purpose, rationale, alternatives considered
- [x] 4.4 Write ADR entry for PostgreSQL 14 — purpose, what it stores, rationale
- [x] 4.5 Write ADR entry for Redis 7 — purpose, what it stores (vs PostgreSQL), rationale
- [x] 4.6 Write ADR entry for HashiCorp Vault — purpose, opt-in model, rationale
- [x] 4.7 Write ADR entry for OPA — purpose, how it extends OAuth scopes, rationale
- [x] 4.8 Write ADR entry for React 18 + Vite 5 — purpose, rationale
- [x] 4.9 Write ADR entry for Prometheus + Grafana — purpose, rationale
- [x] 4.10 Write ADR entry for Terraform — purpose, multi-region rationale

## 5. Codebase Structure (04-codebase-structure.md)

- [x] 5.1 Write annotated directory tree covering all top-level directories
- [x] 5.2 Write `src/` subdirectory roles section (controllers, services, repositories, middleware, utils, types, routes)
- [x] 5.3 Write "where to add new code" decision guide — mapping feature type to directory
- [x] 5.4 Write key files section (app.ts, server.ts, types/index.ts, utils/errors.ts, docker-compose.yml, tsconfig.json)
- [x] 5.5 Write DRY enforcement section — mapping the single-location principle to the directory structure

## 6. Service Deep Dives (05-services.md)

- [x] 6.1 Write AgentService deep-dive (purpose, responsibility boundary, public interface, DB schema, error types)
- [x] 6.2 Write OAuth2Service deep-dive (purpose, responsibility boundary, public interface, Redis schema, JWT payload, Vault vs bcrypt path)
- [x] 6.3 Write CredentialService deep-dive (purpose, responsibility boundary, public interface, DB schema, vault_path column explanation)
- [x] 6.4 Write AuditService deep-dive (purpose, responsibility boundary, public interface, DB schema, immutability guarantee, 90-day retention)
- [x] 6.5 Write VaultClient deep-dive (purpose, public methods, opt-in configuration, constant-time comparison rationale)
- [x] 6.6 Write OPA policy engine deep-dive (purpose, policy file locations, how authorization decisions work, how to write and test a new policy)
- [x] 6.7 Write Web Dashboard deep-dive (React structure, authentication flow, main views, local dev instructions)
- [x] 6.8 Write Prometheus/Grafana monitoring deep-dive (metrics endpoint, key metrics, Grafana dashboard, how to add a new metric)

## 7. Code Walkthroughs (06-walkthroughs.md)

- [x] 7.1 Read source files to identify current line numbers for token issuance flow
- [x] 7.2 Write token issuance walkthrough — POST /oauth2/token → router → middleware → OAuth2Controller → OAuth2Service → CredentialRepository → Vault/bcrypt → Redis → JWT sign → AuditService → 200 response, with file:line references and "why" annotations at each step
- [x] 7.3 Read source files to identify current line numbers for agent registration flow
- [x] 7.4 Write agent registration walkthrough — POST /agents → auth middleware → validation → AgentController → AgentService → validators → AgentRepository → PostgreSQL → AuditService → 201 response, with file:line references and "why" annotations
- [x] 7.5 Read source files to identify current line numbers for credential rotation flow
- [x] 7.6 Write credential rotation walkthrough — POST /agents/:id/credentials/:credId/rotate → auth → CredentialController → CredentialService → revoke old → crypto → Vault/bcrypt → CredentialRepository → token revocation → AuditService → 200 response, with file:line references and "why" annotations
- [x] 7.7 Add "last verified against commit X" header to each walkthrough

## 8. Development Environment Setup (07-dev-setup.md)

- [x] 8.1 Write prerequisites section (Node.js 18+, Docker Desktop, Git) with install links
- [x] 8.2 Write repository clone and npm install steps
- [x] 8.3 Write .env setup section (copy .env.example, document every variable)
- [x] 8.4 Write Docker Compose startup steps and service health verification
- [x] 8.5 Write database migration steps
- [x] 8.6 Write smoke test section — curl POST /oauth2/token with seed credentials, expected JWT response
- [x] 8.7 Write troubleshooting section (port conflict, migration failure, Node version mismatch, Docker not running, missing .env vars)
- [x] 8.8 Write "running tests locally" section (npm test, npm run test:coverage, npm run test:integration, single file)
- [x] 8.9 Write web dashboard local dev section (cd dashboard, npm install, npm run dev, port confirmation)

## 9. Engineering Workflow (08-workflow.md)

- [x] 9.1 Write OpenSpec spec-first workflow overview — the full sequence from CEO approval to merged code
- [x] 9.2 Write OpenSpec CLI commands reference (openspec new change, openspec status, openspec instructions, openspec list)
- [x] 9.3 Write branching strategy section (feature/* from develop, PR → develop, develop → main requires approvals)
- [x] 9.4 Write TypeScript and code standards section (strict mode, no any, DRY, SOLID, JSDoc) with enforcement consequences
- [x] 9.5 Write PR checklist section (TypeScript, ESLint, unit tests, coverage, integration tests, spec updated, docs updated)
- [x] 9.6 Write virtual engineering team roles for contributors section
- [x] 9.7 Write commit message conventions section (Conventional Commits — feat, fix, docs, test, chore, refactor with examples)

## 10. Testing Strategy (09-testing.md)

- [x] 10.1 Write test types and purposes section (unit vs integration — distinction, when to use each)
- [x] 10.2 Write test framework stack section (Jest 29.7, ts-jest, Supertest 6.3 — role of each)
- [x] 10.3 Write coverage gates section (>80% statements, branches, functions, lines — enforcement)
- [x] 10.4 Write "how to run the test suite" section (npm test, test:coverage, test:integration, single file)
- [x] 10.5 Write unit test writing conventions section with complete real example from codebase (mock setup, describe/it structure, error assertion, mock verification)
- [x] 10.6 Write integration test writing conventions section with complete real example (Supertest app boot, seed data, authenticated request, cleanup)
- [x] 10.7 Write OWASP Top 10 security testing reference section relevant to this codebase

## 11. Deployment and Operations (10-deployment.md)

- [x] 11.1 Write Docker build and run section (multi-stage build explanation, build command, run command with env vars)
- [x] 11.2 Write complete environment variables reference table (all variables, purpose, required/optional, example value)
- [x] 11.3 Write database migrations section (file location, naming convention, run command, writing new migrations)
- [x] 11.4 Write Terraform multi-region deployment section (modules, regions, terraform plan/apply, resources provisioned)
- [x] 11.5 Write Prometheus and Grafana section (/metrics endpoint, key metrics, Grafana access, adding a new metric)
- [x] 11.6 Write operational runbook section (health check, rotate JWT signing key, revoke all tokens for compromised agent, read audit logs for incident)

## 12. SDK Guide (11-sdk-guide.md)

- [x] 12.1 Write SDK architecture overview (all four SDKs, identical API surface, consistency standard)
- [x] 12.2 Write Node.js SDK section (install, AgentIdPClient, 4 service clients, TokenManager, AgentIdPError, complete working example)
- [x] 12.3 Write Python SDK section (install, sync + async clients, TokenManager variants, AgentIdPError, complete sync and async examples)
- [x] 12.4 Write Go SDK section (go get, AgentIdPClient, goroutine-safe TokenManager, context.Context usage, AgentIdPError, complete example)
- [x] 12.5 Write Java SDK section (Maven/Gradle snippet, builder pattern, sync + CompletableFuture async, TokenManager, AgentIdPException, complete example)
- [x] 12.6 Write SDK contribution guide (step-by-step checklist for adding a new endpoint to all four SDKs)

## 13. Final Review and Commit

- [x] 13.1 Review all documents for cross-link accuracy (internal links between documents resolve correctly)
- [x] 13.2 Verify all code examples are complete and runnable (no ellipses, no placeholders)
- [x] 13.3 Verify file:line references in walkthroughs against current source
- [x] 13.4 Verify README.md index links to all 11 documents correctly
- [x] 13.5 Commit `docs/engineering/` to `develop` with message `docs: engineering knowledge base for new hires`