d42c653eea
- engineering-docs → archive/2026-03-29-engineering-docs (63/63 tasks complete) - phase-2-production-ready → archive/2026-03-29-phase-2-production-ready (89/89 tasks complete) - openspec/specs/ synced with all Phase 1 + Phase 2 + engineering-docs capabilities (22 specs total) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.5 KiB
2.5 KiB
ADDED Requirements
Requirement: Annotated code walkthrough documents
The system SHALL include a document (docs/engineering/06-walkthroughs.md) containing three annotated end-to-end walkthroughs of the system's critical flows, with file:line references to actual source code.
Scenario: Token issuance walkthrough complete
- WHEN a new engineer reads the token issuance walkthrough
- THEN they SHALL be guided step by step from: HTTP POST /oauth2/token → Express router → auth middleware → OAuth2Controller → OAuth2Service → CredentialRepository → Vault/bcrypt credential check → Redis token cache check → JWT signing (src/utils/jwt.ts) → AuditService.logEvent → HTTP 200 response
- AND every step SHALL reference the actual file and line number where it occurs
Scenario: Agent registration walkthrough complete
- WHEN a new engineer reads the agent registration walkthrough
- THEN they SHALL be guided step by step from: HTTP POST /agents → auth middleware → validation middleware → AgentController → AgentService.createAgent → input validation (src/utils/validators.ts) → AgentRepository.create → PostgreSQL INSERT → AuditService.logEvent → HTTP 201 response with agent object
- AND every step SHALL reference the actual file and line number
Scenario: Credential rotation walkthrough complete
- WHEN a new engineer reads the credential rotation walkthrough
- THEN they SHALL be guided step by step from: HTTP POST /agents/:id/credentials/:credId/rotate → auth middleware → CredentialController → CredentialService.rotateCredential → old credential revocation → new secret generation (src/utils/crypto.ts) → Vault write or bcrypt hash → CredentialRepository.update → token revocation for old credentials → AuditService.logEvent → HTTP 200 response
- AND every step SHALL reference the actual file and line number
Scenario: Walkthroughs include version reference
- WHEN a new engineer reads any walkthrough
- THEN the document SHALL include a header stating the commit hash it was last verified against, so engineers know if the walkthrough may have drifted from the current code
Scenario: Each walkthrough annotates why, not just what
- WHEN a new engineer reads a walkthrough step
- THEN each step SHALL explain not just what the code does but WHY — e.g., why Redis is checked before signing a new JWT, why constant-time comparison is used for credential verification, why audit logging happens after persistence not before