Charon/docs/plans/instruction_compliance_spec.md

# Instruction Compliance Audit Report

**Date:** December 20, 2025
**Auditor:** GitHub Copilot (Claude Opus 4.5)
**Scope:** Charon codebase vs `.github/instructions/*.instructions.md`

---

## Executive Summary

### Overall Compliance Status: **PARTIAL** (78% Compliant)

The Charon codebase demonstrates strong compliance with most instruction files, particularly in Docker/containerization practices and Go coding standards. However, several gaps exist in TypeScript standards, documentation requirements, and some CI/CD best practices that require remediation.

| Instruction File | Status | Compliance % |
|-----------------|--------|--------------|
| containerization-docker-best-practices | ✅ Compliant | 92% |
| github-actions-ci-cd-best-practices | ⚠️ Partial | 85% |
| go.instructions | ✅ Compliant | 88% |
| typescript-5-es2022 | ⚠️ Partial | 75% |
| security-and-owasp | ✅ Compliant | 90% |
| performance-optimization | ⚠️ Partial | 72% |
| markdown.instructions | ⚠️ Partial | 65% |

---

## Per-Instruction Analysis

### 1. Containerization & Docker Best Practices

**File:** `.github/instructions/containerization-docker-best-practices.instructions.md`
**Status:** ✅ Compliant (92%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Multi-stage builds | 5 build stages (frontend-builder, backend-builder, caddy-builder, crowdsec-builder, final) | [Dockerfile](../../Dockerfile#L1-L50) |
| Minimal base images | Uses `alpine:3.23`, `node:24-alpine`, `golang:1.25-alpine` | [Dockerfile](../../Dockerfile#L15-L30) |
| Non-root user | ❌ **GAP** - No `USER` directive in final stage | [Dockerfile](../../Dockerfile#L180-L220) |
| `.dockerignore` comprehensive | Excellent coverage with 150+ exclusion patterns | [.dockerignore](../../.dockerignore) |
| Layer optimization | Combined `RUN` commands, `--mount=type=cache` for build caches | [Dockerfile](../../Dockerfile#L40-L80) |
| Build arguments for versioning | `VERSION`, `BUILD_DATE`, `VCS_REF` args used | [Dockerfile](../../Dockerfile#L3-L7) |
| OCI labels | Full OCI metadata labels present | [Dockerfile](../../Dockerfile#L200-L210) |
| HEALTHCHECK instruction | ❌ **GAP** - No HEALTHCHECK in Dockerfile | [Dockerfile](../../Dockerfile) |
| Environment variables | Proper defaults with `ENV` directives | [Dockerfile](../../Dockerfile#L175-L185) |
| Secrets management | No secrets in image layers | ✅ |

#### Gaps Identified

1. **Missing Non-Root USER** (HIGH)
   - Location: [Dockerfile](../../Dockerfile#L220)
   - Issue: Final image runs as root
   - Remediation: Add `USER nonroot` or create/use dedicated user

2. **Missing HEALTHCHECK** (MEDIUM)
   - Location: [Dockerfile](../../Dockerfile)
   - Issue: No HEALTHCHECK instruction for orchestration systems
   - Remediation: Add `HEALTHCHECK --interval=30s CMD curl -f http://localhost:8080/api/v1/health || exit 1`

3. **Docker Compose version deprecated** (LOW)
   - Location: [docker-compose.yml#L1](../../docker-compose.yml#L1)
   - Issue: `version: '3.9'` is deprecated in Docker Compose V2
   - Remediation: Remove `version` key entirely

---

### 2. GitHub Actions CI/CD Best Practices

**File:** `.github/instructions/github-actions-ci-cd-best-practices.instructions.md`
**Status:** ⚠️ Partial (85%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Descriptive workflow names | Clear names like "Docker Build, Publish & Test" | All workflow files |
| Action version pinning (SHA) | Most actions pinned to full SHA | [docker-publish.yml#L28](../../.github/workflows/docker-publish.yml#L28) |
| Explicit permissions | `permissions` blocks in most workflows | [codeql.yml#L12-L16](../../.github/workflows/codeql.yml#L12-L16) |
| Caching strategy | GHA cache with `cache-from`/`cache-to` | [docker-publish.yml#L95](../../.github/workflows/docker-publish.yml#L95) |
| Matrix strategies | Used for multi-language CodeQL analysis | [codeql.yml#L25-L28](../../.github/workflows/codeql.yml#L25-L28) |
| Test reporting | Test summaries in `$GITHUB_STEP_SUMMARY` | [quality-checks.yml#L35-L50](../../.github/workflows/quality-checks.yml#L35-L50) |
| Secret handling | Uses `secrets.GITHUB_TOKEN` properly | All workflows |
| Timeout configuration | `timeout-minutes: 30` on long jobs | [docker-publish.yml#L22](../../.github/workflows/docker-publish.yml#L22) |

#### Gaps Identified

1. **Inconsistent action version pinning** (MEDIUM)
   - Location: Multiple workflows
   - Issue: Some actions use `@v6` tags instead of full SHA
   - Files: `actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8` (good) vs some others
   - Remediation: Pin all actions to full SHA for security

2. **Missing `concurrency` in some workflows** (LOW)
   - Location: [quality-checks.yml](../../.github/workflows/quality-checks.yml)
   - Issue: No concurrency group to prevent duplicate runs
   - Remediation: Add `concurrency: { group: ${{ github.workflow }}-${{ github.ref }}, cancel-in-progress: true }`

3. **Hardcoded Go version strings** (LOW)
   - Location: [quality-checks.yml#L17](../../.github/workflows/quality-checks.yml#L17)
   - Issue: Go version `'1.25.5'` duplicated across workflows
   - Remediation: Use workflow-level env variable or reusable workflow

4. **Missing OIDC for cloud auth** (LOW)
   - Location: N/A
   - Issue: Not currently using OIDC for cloud authentication
   - Note: Currently uses GITHUB_TOKEN which is acceptable for GHCR

---

### 3. Go Development Instructions

**File:** `.github/instructions/go.instructions.md`
**Status:** ✅ Compliant (88%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Package naming | Lowercase, single-word packages | `handlers`, `services`, `models` |
| Error wrapping with `%w` | Consistent use of `fmt.Errorf(...: %w, err)` | Multiple files (10+ matches) |
| Context-based logging | Uses `logger.Log().WithError(err)` | [main.go#L70](../../backend/cmd/api/main.go#L70) |
| Table-driven tests | Extensively used in test files | Handler test files |
| Module management | Proper `go.mod` and `go.sum` | [backend/go.mod](../../backend/go.mod) |
| Package documentation | `// Package main is the entry point...` | [main.go#L1](../../backend/cmd/api/main.go#L1) |
| Dependency injection | Handlers accept services via constructors | [auth_handler.go#L19-L25](../../backend/internal/api/handlers/auth_handler.go#L19-L25) |
| Early returns | Used for error handling | Throughout codebase |

#### Gaps Identified

1. **Mixed use of `interface{}` and `any`** (MEDIUM)
   - Location: Multiple files
   - Issue: `map[string]interface{}` used instead of `map[string]any`
   - Files: `cerberus.go#L107`, `console_enroll.go#L163`, `database/errors.go#L40`
   - Remediation: Prefer `any` over `interface{}` (Go 1.18+ standard)

2. **Some packages lack documentation** (LOW)
   - Location: Some internal packages
   - Issue: Missing package-level documentation comments
   - Remediation: Add `// Package X provides...` comments

3. **Inconsistent error variable naming** (LOW)
   - Location: Various handlers
   - Issue: Some use `e` or `err2` instead of consistent `err`
   - Remediation: Standardize to `err` throughout

---

### 4. TypeScript Development Instructions

**File:** `.github/instructions/typescript-5-es2022.instructions.md`
**Status:** ⚠️ Partial (75%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Strict mode enabled | `"strict": true` | [tsconfig.json#L17](../../frontend/tsconfig.json#L17) |
| ESNext module | `"module": "ESNext"` | [tsconfig.json#L7](../../frontend/tsconfig.json#L7) |
| Kebab-case filenames | `user-session.ts` pattern not strictly followed | Mixed |
| React JSX support | `"jsx": "react-jsx"` | [tsconfig.json#L14](../../frontend/tsconfig.json#L14) |
| Lazy loading | `lazy(() => import(...))` pattern used | [App.tsx#L14-L35](../../frontend/src/App.tsx#L14-L35) |
| TypeScript strict checks | `noUnusedLocals`, `noUnusedParameters` | [tsconfig.json#L18-L19](../../frontend/tsconfig.json#L18-L19) |

#### Gaps Identified

1. **Target ES2020 instead of ES2022** (MEDIUM)
   - Location: [tsconfig.json#L3](../../frontend/tsconfig.json#L3)
   - Issue: Instructions specify ES2022, project uses ES2020
   - Remediation: Update `"target": "ES2022"` and `"lib": ["ES2022", ...]`

2. **Inconsistent file naming** (LOW)
   - Location: [frontend/src/api/](../../frontend/src/api/)
   - Issue: Mix of PascalCase and camelCase (`accessLists.ts`, `App.tsx`)
   - Instruction: Use kebab-case (e.g., `access-lists.ts`)
   - Remediation: Rename files to kebab-case or document exception

3. **Missing JSDoc on public APIs** (MEDIUM)
   - Location: [frontend/src/api/client.ts](../../frontend/src/api/client.ts)
   - Issue: Exported functions lack JSDoc documentation
   - Remediation: Add JSDoc comments to exported functions

4. **Axios timeout could use retry/backoff** (LOW)
   - Location: [frontend/src/api/client.ts#L6](../../frontend/src/api/client.ts#L6)
   - Issue: 30s timeout but no retry/backoff mechanism
   - Instruction: "Apply retries, backoff, and cancellation to network calls"
   - Remediation: Add axios-retry or similar

---

### 5. Security and OWASP Guidelines

**File:** `.github/instructions/security-and-owasp.instructions.md`
**Status:** ✅ Compliant (90%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Secure cookie handling | HttpOnly, SameSite, Secure flags | [auth_handler.go#L52-L68](../../backend/internal/api/handlers/auth_handler.go#L52-L68) |
| Input validation | Gin binding with `binding:"required,email"` | [auth_handler.go#L77-L80](../../backend/internal/api/handlers/auth_handler.go#L77-L80) |
| Password hashing | Uses bcrypt via `user.SetPassword()` | [main.go#L92](../../backend/cmd/api/main.go#L92) |
| HTTPS enforcement | Secure flag based on scheme detection | [auth_handler.go#L54](../../backend/internal/api/handlers/auth_handler.go#L54) |
| No hardcoded secrets | Secrets from environment variables | [docker-compose.yml](../../docker-compose.yml) |
| Rate limiting | `caddy-ratelimit` plugin included | [Dockerfile#L82](../../Dockerfile#L82) |
| WAF integration | Coraza WAF module included | [Dockerfile#L81](../../Dockerfile#L81) |
| Security headers | SecurityHeaders handler and presets | [security_headers_handler.go](../../backend/internal/api/handlers/security_headers_handler.go) |

#### Gaps Identified

1. **Account lockout threshold not configurable** (LOW)
   - Location: [auth_handler.go](../../backend/internal/api/handlers/auth_handler.go)
   - Issue: Lockout policy may be hardcoded
   - Remediation: Make lockout thresholds configurable via environment

2. **Missing Content-Security-Policy in Dockerfile** (LOW)
   - Location: [Dockerfile](../../Dockerfile)
   - Issue: CSP not set at container level (handled by Caddy instead)
   - Status: Acceptable - CSP configured in Caddy config

---

### 6. Performance Optimization Best Practices

**File:** `.github/instructions/performance-optimization.instructions.md`
**Status:** ⚠️ Partial (72%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Lazy loading (frontend) | React.lazy() for code splitting | [App.tsx#L14-L35](../../frontend/src/App.tsx#L14-L35) |
| Build caching (Docker) | `--mount=type=cache` for Go and npm | [Dockerfile#L50-L55](../../Dockerfile#L50-L55) |
| Database indexing | ❌ Not verified in models | Needs investigation |
| Query optimization | Uses GORM with preloads | Various handlers |
| Asset minification | Vite production builds | `npm run build` |
| Connection pooling | SQLite single connection | [database.go](../../backend/internal/database/database.go) |

#### Gaps Identified

1. **Missing database indexes on frequently queried columns** (MEDIUM)
   - Location: Model definitions
   - Issue: Need to verify indexes on `email`, `domain`, etc.
   - Remediation: Add GORM index tags to model fields

2. **No query result caching** (MEDIUM)
   - Location: Handler layer
   - Issue: Database queries not cached for read-heavy operations
   - Remediation: Consider adding Redis/in-memory cache for hot data

3. **Frontend bundle analysis not in CI** (LOW)
   - Location: CI/CD workflows
   - Issue: No automated bundle size tracking
   - Remediation: Add `source-map-explorer` or `webpack-bundle-analyzer` to CI

4. **Missing N+1 query prevention checks** (MEDIUM)
   - Location: GORM queries
   - Issue: No automated detection of N+1 query patterns
   - Remediation: Add GORM hooks or tests for query optimization

---

### 7. Markdown Documentation Standards

**File:** `.github/instructions/markdown.instructions.md`
**Status:** ⚠️ Partial (65%)

#### Compliant Areas

| Requirement | Evidence | File Reference |
|------------|----------|----------------|
| Fenced code blocks | Used with language specifiers | All docs |
| Proper heading hierarchy | H2, H3 used correctly | [getting-started.md](../../docs/getting-started.md) |
| Link syntax | Standard markdown links | Throughout docs |
| List formatting | Consistent bullet/numbered lists | Throughout docs |

#### Gaps Identified

1. **Missing YAML front matter** (HIGH)
   - Location: All documentation files
   - Issue: Instructions require front matter with `post_title`, `author1`, etc.
   - Files: [getting-started.md](../../docs/getting-started.md), [security.md](../../docs/security.md)
   - Remediation: Add required YAML front matter to all docs

2. **H1 headings present in some docs** (MEDIUM)
   - Location: [getting-started.md#L1](../../docs/getting-started.md#L1)
   - Issue: Instructions say "Do not use an H1 heading, as this will be generated"
   - Remediation: Replace H1 with H2 headings

3. **Line length exceeds 400 characters** (LOW)
   - Location: Various docs
   - Issue: Some paragraphs are very long single lines
   - Remediation: Add line breaks at ~80-100 characters

4. **Missing alt text on some images** (LOW)
   - Location: Various docs
   - Issue: Some images may lack descriptive alt text
   - Remediation: Audit and add alt text to all images

---

## Prioritized Remediation Plan

### Phase 1: Critical (Security Issues) - Estimated: 2-4 hours

| ID | Issue | Priority | File | Effort |
|----|-------|----------|------|--------|
| P1-1 | Add non-root USER to Dockerfile | HIGH | Dockerfile | 30 min |
| P1-2 | Add HEALTHCHECK to Dockerfile | MEDIUM | Dockerfile | 15 min |
| P1-3 | Pin all GitHub Actions to SHA | MEDIUM | .github/workflows/*.yml | 1 hour |

**Remediation Details:**

```dockerfile
# P1-1: Add to Dockerfile before ENTRYPOINT
RUN addgroup -S charon && adduser -S charon -G charon
RUN chown -R charon:charon /app /app/data /config
USER charon

# P1-2: Add HEALTHCHECK
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8080/api/v1/health || exit 1
```

---

### Phase 2: High (Breaking Standards) - Estimated: 4-6 hours

| ID | Issue | Priority | File | Effort |
|----|-------|----------|------|--------|
| P2-1 | Update tsconfig.json target to ES2022 | MEDIUM | frontend/tsconfig.json | 15 min |
| P2-2 | Replace `interface{}` with `any` | MEDIUM | backend/**/*.go | 2 hours |
| P2-3 | Add JSDoc to exported TypeScript APIs | MEDIUM | frontend/src/api/*.ts | 2 hours |
| P2-4 | Add database indexes to models | MEDIUM | backend/internal/models/*.go | 1 hour |

**Remediation Details:**

```jsonc
// P2-1: Update tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    // ... rest unchanged
  }
}
```

```go
// P2-2: Replace interface{} with any
// Before: map[string]interface{}
// After:  map[string]any
```

---

### Phase 3: Medium (Best Practice Improvements) - Estimated: 6-8 hours

| ID | Issue | Priority | File | Effort |
|----|-------|----------|------|--------|
| P3-1 | Add concurrency to workflows | LOW | .github/workflows/*.yml | 1 hour |
| P3-2 | Remove deprecated `version` from docker-compose | LOW | docker-compose*.yml | 15 min |
| P3-3 | Add query caching for hot paths | MEDIUM | backend/internal/services/ | 4 hours |
| P3-4 | Add axios-retry to frontend client | LOW | frontend/src/api/client.ts | 1 hour |
| P3-5 | Rename TypeScript files to kebab-case | LOW | frontend/src/**/*.ts | 2 hours |

**Remediation Details:**

```yaml
# P3-1: Add to quality-checks.yml
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

---

### Phase 4: Low (Documentation/Polish) - Estimated: 4-6 hours

| ID | Issue | Priority | File | Effort |
|----|-------|----------|------|--------|
| P4-1 | Add YAML front matter to all docs | HIGH | docs/*.md | 2 hours |
| P4-2 | Replace H1 with H2 in docs | MEDIUM | docs/*.md | 1 hour |
| P4-3 | Add line breaks to long paragraphs | LOW | docs/*.md | 1 hour |
| P4-4 | Add package documentation comments | LOW | backend/internal/**/ | 2 hours |
| P4-5 | Add bundle size tracking to CI | LOW | .github/workflows/ | 1 hour |

**Front matter template for P4-1:**

```yaml
---
post_title: Getting Started with Charon
author1: Charon Team
post_slug: getting-started
summary: Quick start guide for setting up Charon
post_date: 2024-12-20
---
```

---

## Effort Estimates Summary

| Phase | Description | Estimated Hours | Risk |
|-------|-------------|-----------------|------|
| Phase 1 | Critical Security | 2-4 hours | Low |
| Phase 2 | Breaking Standards | 4-6 hours | Medium |
| Phase 3 | Best Practices | 6-8 hours | Low |
| Phase 4 | Documentation | 4-6 hours | Low |
| **Total** | | **16-24 hours** | |

---

## Implementation Notes

### Testing Requirements

1. **Phase 1**: Run Docker build, integration tests, and verify healthcheck
2. **Phase 2**: Run full test suite (`npm test`, `go test ./...`), verify ES2022 compatibility
3. **Phase 3**: Validate caching behavior, retry logic, workflow execution
4. **Phase 4**: Run markdownlint, verify doc builds

### Rollback Strategy

- Create feature branches for each phase
- Use CI/CD to validate before merge
- Phase 1 can be tested in isolation with local Docker builds

### Dependencies

- Phase 2-2 requires Go 1.18+ (already using 1.25)
- Phase 3-3 may require Redis if external caching chosen
- Phase 4-1 requires understanding of documentation build system

---

## Appendix A: Files Reviewed

### Docker/Container

- `Dockerfile`
- `docker-compose.yml`
- `docker-compose.dev.yml`
- `docker-compose.local.yml`
- `.dockerignore`

### CI/CD Workflows

- `.github/workflows/docker-publish.yml`
- `.github/workflows/quality-checks.yml`
- `.github/workflows/codeql.yml`
- `.github/workflows/release-goreleaser.yml`

### Backend Go

- `backend/cmd/api/main.go`
- `backend/internal/api/handlers/auth_handler.go`
- `backend/internal/api/handlers/*.go` (directory listing)

### Frontend TypeScript

- `frontend/src/App.tsx`
- `frontend/src/api/client.ts`
- `frontend/src/components/Layout.tsx`
- `frontend/tsconfig.json`

### Documentation

- `docs/getting-started.md`
- `docs/security.md`
- `docs/plans/*.md` (directory listing)

---

## Appendix B: Instruction File References

| Instruction File | Lines | Key Requirements |
|-----------------|-------|------------------|
| containerization-docker-best-practices | ~600 | Multi-stage, minimal images, non-root |
| github-actions-ci-cd-best-practices | ~800 | SHA pinning, permissions, caching |
| go.instructions | ~400 | Error wrapping, package naming, testing |
| typescript-5-es2022 | ~150 | ES2022 target, strict mode, JSDoc |
| security-and-owasp | ~100 | Secure cookies, input validation |
| performance-optimization | ~700 | Caching, lazy loading, indexing |
| markdown.instructions | ~60 | Front matter, heading hierarchy |

---

*End of Compliance Audit Report*