KeplerOps · Brad-Edwards · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026 · Mar 7, 2026
@@ -0,0 +1,92 @@
+# Ground Control — Implementation Issues
+
+This directory contains all implementation issues organized by phase. Each issue file is designed to be imported into GitHub Issues. Issues are cross-referenced to user stories, use cases, and design documents.
+
+## Phase Summary
+
+| Phase | Name | Issues | PRD Alignment | Priority |
+|---|---|---|---|---|
+| **0** | Project Bootstrap & Engineering Foundation | 001–025 (+006b, 023b) | Pre-v0.1 | P0 |
+| **1** | Core Data Model & Persistence | 026–040 | v0.1 | P0 |
+| **2** | API Foundation & Auth | 041–055 | v0.1 | P0 |
+| **3** | Authorization & Identity | 056–063 | v0.1–v0.2 | P0 |
+| **4** | Core Business Logic | 064–077 | v0.1 | P0 |
+| **5** | Event System & Workflow | 078–084 | v0.2 | P0–P1 |
+| **6** | Frameworks & Templates | 085–092 | v0.3 | P0–P1 |
+| **7** | Agent System | 093–099 | v0.4 | P0–P1 |
+| **8** | Reporting & Search | 100–103 | v0.5 | P0–P1 |
+| **9** | Frontend | 104–113 | v0.1–v0.5 | P0–P1 |
+| **10** | Plugin System | 114–116 | v1.0 | P0–P1 |
+| **11** | Production Readiness | 117–127 | v1.0 | P0–P1 |
+
+**Total: 127 issues across 12 phases**
+
+## Cross-Cutting Concerns
+
+These issues establish patterns used throughout the entire codebase:
+
+| Concern | Issue(s) | Description |
+|---|---|---|
+| **Coding Standards** | #003, #007, #008, #009 | Ruff, mypy, ESLint, pre-commit |
+| **Architecture as Code** | #002, #024 | ADRs, C4 models, import-linter |
+| **Policy as Code** | #025, #057 | Authorization policies as testable artifacts |
+| **Formal Verification** | #023, #023b | icontract, Hypothesis (Python); Coq/Rocq proofs for critical invariants |
+| **Structured Logging** | #018 | structlog, JSON, context propagation |
+| **Exception Handling** | #017 | Typed hierarchy, HTTP mapping, scrubbing |
+| **Audit Logging** | #039 | Append-only, hash-chained, tamper-proof |
+| **Configuration** | #019 | pydantic-settings, fail-fast validation |
+| **Base Schemas** | #020 | API envelope, pagination, error format |
+| **CI/CD Security** | #012–#016 | SonarQube, SAST, DAST, OpenANT, deps |
+| **MCP Dev Tooling** | #006b | rocq-mcp (Coq proofs), AWS MCP (infra), custom ops MCP (deferred) |
+
+## Design Document References
+
+| Document | Path | Key Issues |
+|---|---|---|
+| PRD | `docs/PRD.md` | All issues |
+| Architecture | `docs/architecture/ARCHITECTURE.md` | #001–#025, #041, #078 |
+| Data Model | `docs/architecture/DATA_MODEL.md` | #026–#040 |
+| API Spec | `docs/api/API_SPEC.md` | #041–#055, #093–#099 |
+| User Stories | `docs/user-stories/USER_STORIES.md` | #044–#050, #064–#077 |
+| Use Cases | `docs/user-stories/USE_CASES.md` | #044–#050, #064–#077 |
+| Deployment | `docs/deployment/DEPLOYMENT.md` | #006, #119–#124 |
+| Coding Standards | `docs/CODING_STANDARDS.md` | #001–#025 |
+
+## User Story Coverage
+
+| Epic | User Stories | Primary Issues |
+|---|---|---|
+| Risk Management | US-1.1–US-1.5 | #029, #044, #064–#067, #106 |
+| Control Management | US-2.1–US-2.3 | #030–#032, #045, #068–#069, #107 |
+| Assessment & Testing | US-3.1–US-3.5 | #033–#034, #046, #070–#072, #108 |
+| Evidence Management | US-4.1–US-4.4 | #035, #047, #073–#075, #109 |
+| Findings & Remediation | US-5.1–US-5.3 | #036–#037, #048, #076, #110 |
+| Reporting | US-6.1–US-6.3 | #101–#103, #112 |
+| Administration | US-7.1–US-7.5 | #026–#028, #038, #051–#063, #111 |
+| Agent System | US-8.1–US-8.4 | #093–#099 |
+
+## Technology Decisions
+
+| Decision | Choice | Issue |
+|---|---|---|
+| Backend Language | Python 3.12+ | #004 |
+| API Framework | FastAPI | #041 |
+| Database | PostgreSQL 16+ | #021 |
+| ORM | SQLAlchemy 2.0 + Alembic | #021, #022 |
+| Frontend | React + TypeScript + Vite | #005, #104 |
+| UI Components | Shadcn/ui + Tailwind CSS | #104 |
+| Search | Meilisearch | #100 |
+| Cache/Queue | Redis/Valkey | #079 |
+| Object Storage | S3-compatible (MinIO) | #035, #073 |
+| CI/CD | GitHub Actions | #008–#016 |
+| Linting | Ruff (Python), ESLint (TS) | #003, #008 |
+| Type Checking | mypy (Python), tsc (TS) | #003, #009 |
+| Testing | pytest, vitest, Playwright | #010, #126 |
+| Code Quality | SonarQube/SonarCloud | #012 |
+| SAST | Semgrep + Bandit | #013 |
+| DAST | OWASP ZAP | #014 |
+| AI Security | OpenANT (Knostic) | #015 |
+| Formal Verification | Hypothesis (Python), Coq/Rocq (proofs) | #023, #023b |
+| MCP Servers | rocq-mcp, AWS MCP (official) | #006b |
+| Containerization | Docker + Docker Compose | #011, #119 |
+| Orchestration | Kubernetes (Helm) | #120 |
@@ -0,0 +1,87 @@
+---
+title: "Establish repository structure and monorepo layout"
+labels: [foundation, architecture, devex]
+phase: 0
+priority: P0
+---
+
+## Description
+
+Define and create the canonical directory layout for the Ground Control monorepo. This structure must cleanly separate the Python backend, React frontend, shared schemas, deployment artifacts, documentation, and plugin SDK — while keeping everything in a single repository for atomic commits and unified CI.
+
+## References
+
+- PRD: Section 10 (Release Roadmap — v0.1 Foundation)
+- Architecture: Section 7 (Technology Stack Summary)
+- Deployment: Section 2 (Docker Compose)
+
+## Proposed Structure
+
+```
+Ground-Control/
+├── .github/
+│   ├── workflows/          # CI/CD pipelines
+│   ├── ISSUE_TEMPLATE/
+│   └── PULL_REQUEST_TEMPLATE.md
+├── backend/
+│   ├── src/
+│   │   └── ground_control/
+│   │       ├── __init__.py
+│   │       ├── main.py           # FastAPI app entry
+│   │       ├── config.py         # pydantic-settings
+│   │       ├── api/              # Route handlers (v1/)
+│   │       ├── domain/           # Domain models & services
+│   │       ├── infrastructure/   # DB, S3, cache, search adapters
+│   │       ├── schemas/          # Pydantic request/response schemas
+│   │       ├── middleware/       # Tenant, auth, logging, request-id
+│   │       ├── events/           # Domain event bus
+│   │       ├── exceptions/       # Shared exception hierarchy
+│   │       ├── logging/          # Structured logging setup
+│   │       └── plugins/          # Plugin runtime
+│   ├── tests/
+│   ├── migrations/               # Alembic
+│   ├── pyproject.toml
+│   └── alembic.ini
+├── frontend/
+│   ├── src/
+│   ├── public/
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── vite.config.ts
+├── sdks/
+│   ├── python/                   # Agent SDK (Python)
+│   └── typescript/               # Agent SDK (TypeScript)
+├── plugins/
+│   ├── frameworks/               # Built-in framework definitions
+│   └── integrations/             # Built-in integration plugins
+├── deploy/
+│   ├── docker/
+│   │   ├── Dockerfile
+│   │   ├── Dockerfile.frontend
+│   │   └── docker-compose.yml
+│   ├── helm/
+│   └── terraform/
+├── docs/                         # Existing design docs
+├── architecture/                 # C4/Structurizr models, ADRs
+│   ├── adrs/
+│   ├── c4/
+│   └── policies/                 # Policy-as-code (Rego/YAML)
+├── .editorconfig
+├── .pre-commit-config.yaml
+├── CLAUDE.md
+└── README.md
+```
+
+## Acceptance Criteria
+
+- [ ] Directory structure created with placeholder `__init__.py` and `.gitkeep` files
+- [ ] Root `README.md` updated to describe structure
+- [ ] `CLAUDE.md` created with project conventions for AI-assisted development
+- [ ] `.gitignore` covers Python (`__pycache__`, `.venv`, `.mypy_cache`), Node (`node_modules`, `dist`), IDE files, `.env`
+- [ ] All existing `docs/` content remains intact and accessible
+
+## Technical Notes
+
+- Use a flat `src/ground_control/` layout (not nested `src/src/`) for clean imports
+- Backend package name: `ground_control` (underscore, PEP 8)
+- Keep `deploy/` separate from app code for clean Docker contexts
@@ -0,0 +1,38 @@
+---
+title: "Establish Architecture Decision Records (ADR) framework"
+labels: [foundation, architecture, documentation]
+phase: 0
+priority: P0
+---
+
+## Description
+
+Set up a lightweight ADR process to document significant architectural decisions. Each ADR captures context, decision, consequences, and status. ADRs are stored as Markdown files in `architecture/adrs/` and versioned alongside code.
+
+Create initial ADRs for the foundational decisions already captured in design docs.
+
+## References
+
+- Architecture: All sections (captures decisions needing ADRs)
+- PRD: Section 10 (Roadmap implies phased decisions)
+
+## Acceptance Criteria
+
+- [ ] ADR template created at `architecture/adrs/000-template.md`
+- [ ] ADR index (`architecture/adrs/README.md`) with table of all ADRs
+- [ ] Initial ADRs created:
+  - `001-python-fastapi-backend.md` — Why Python 3.12+ / FastAPI
+  - `002-postgresql-primary-database.md` — Why PostgreSQL 16+
+  - `003-api-first-design.md` — REST-first with optional GraphQL
+  - `004-plugin-architecture.md` — Plugin extensibility approach
+  - `005-event-driven-architecture.md` — Domain event bus design
+  - `006-multi-tenancy-strategy.md` — Shared schema default, configurable
+  - `007-agent-first-design.md` — AI agents as first-class actors
+  - `008-clean-architecture.md` — Layered architecture (API → Domain → Infrastructure)
+- [ ] Each ADR follows format: Title, Status, Context, Decision, Consequences
+
+## Technical Notes
+
+- Use [MADR](https://adr.github.io/madr/) format (Markdown Any Decision Records)
+- Status values: `proposed`, `accepted`, `deprecated`, `superseded`
+- ADRs are immutable once accepted; superseding creates a new ADR
@@ -0,0 +1,55 @@
+---
+title: "Define and enforce coding standards and style guide"
+labels: [foundation, devex, quality]
+phase: 0
+priority: P0
+---
+
+## Description
+
+Establish coding standards for both the Python backend and TypeScript frontend. Document conventions in a `CONTRIBUTING.md` and enforce via tooling (linters, formatters, pre-commit hooks). Standards cover naming, typing, imports, error handling, logging patterns, and testing conventions.
+
+## References
+
+- Architecture: Section 7 (Technology Stack — Python 3.12+, TypeScript, FastAPI)
+- PRD: Section 7 (Non-Functional Requirements — maintainability)
+
+## Acceptance Criteria
+
+### Python Backend
+
+- [ ] `ruff` configured for linting + formatting (replaces flake8, isort, black)
+  - Line length: 100
+  - Target: Python 3.12
+  - Rules: pycodestyle (E), pyflakes (F), isort (I), pep8-naming (N), bugbear (B), type annotations (ANN), security (S)
+- [ ] `mypy` configured for strict type checking
+  - `strict = true` in `pyproject.toml`
+  - Disallow untyped defs, no implicit optional
+- [ ] Naming conventions documented:
+  - Modules: `snake_case`
+  - Classes: `PascalCase`
+  - Functions/methods: `snake_case`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Private: `_leading_underscore`
+- [ ] Import ordering: stdlib → third-party → local (enforced by ruff)
+- [ ] Docstring format: Google style (enforced by ruff D rules)
+- [ ] Type hints required on all public functions and methods
+
+### TypeScript Frontend
+
+- [ ] ESLint configured with `@typescript-eslint` strict rules
+- [ ] Prettier configured (single quotes, trailing commas, 100 line length)
+- [ ] TypeScript `strict: true` in `tsconfig.json`
+- [ ] React-specific: `eslint-plugin-react-hooks`, `eslint-plugin-jsx-a11y`
+
+### Shared
+
+- [ ] `.editorconfig` for consistent whitespace (2 spaces for TS/YAML, 4 spaces for Python)
+- [ ] `CONTRIBUTING.md` documenting all standards
+- [ ] Standards are an ADR: `architecture/adrs/009-coding-standards.md`
+
+## Technical Notes
+
+- Prefer `ruff` over individual tools — single fast binary for Python linting and formatting
+- `mypy` strict mode catches many bugs at type-check time; use `# type: ignore[code]` sparingly with justification
+- All new code must pass type checking before merge
@@ -0,0 +1,42 @@
+---
+title: "Scaffold Python backend project with pyproject.toml"
+labels: [foundation, backend, devex]
+phase: 0
+priority: P0
+---
+
+## Description
+
+Create the Python backend project structure with `pyproject.toml` as the single source of truth for dependencies, build config, and tool settings. Set up the virtual environment tooling, dependency management, and basic project metadata.
+
+## References
+
+- Architecture: Section 7 (Python 3.12+, FastAPI, SQLAlchemy 2.0, Pydantic)
+- Issue #001 (Repository Structure)
+
+## Acceptance Criteria
+
+- [ ] `backend/pyproject.toml` created with:
+  - Project metadata (name=`ground-control`, version, description, license=Apache-2.0)
+  - Python `requires-python = ">=3.12"`
+  - Core dependencies: `fastapi`, `uvicorn[standard]`, `pydantic>=2.0`, `pydantic-settings`, `sqlalchemy[asyncio]>=2.0`, `asyncpg`, `alembic`, `redis`, `boto3`, `meilisearch`, `python-jose[cryptography]`, `passlib[argon2]`, `structlog`, `httpx`, `icontract`
+  - Dev dependencies: `pytest`, `pytest-asyncio`, `pytest-cov`, `hypothesis`, `crosshair-tool`, `mypy`, `ruff`, `pre-commit`, `factory-boy`, `respx`, `deal`
+  - Ruff config section
+  - Mypy config section
+  - Pytest config section (asyncio_mode = "auto", testpaths = ["tests"])
+- [ ] `backend/src/ground_control/__init__.py` with `__version__`
+- [ ] `backend/src/ground_control/py.typed` marker file (PEP 561)
+- [ ] `backend/tests/__init__.py` and `backend/tests/conftest.py`
+- [ ] `Makefile` or `justfile` at repo root with common commands:
+  - `make install` — create venv, install deps
+  - `make lint` — run ruff check + mypy
+  - `make format` — run ruff format
+  - `make test` — run pytest
+  - `make dev` — start development server
+- [ ] Can run `pip install -e ".[dev]"` and import `ground_control`
+
+## Technical Notes
+
+- Use `uv` as the package installer for speed (document as recommended, `pip` as fallback)
+- Pin major versions of critical dependencies; use compatible release (`~=`) for minors
+- Separate `[project.optional-dependencies]` groups: `dev`, `test`, `docs`