Regenerate agent instructions from state-hub templates (CUST-WP-0055 T01)
Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples.
This commit is contained in:
parent
6a9d417c12
commit
54ac28be75
11 changed files with 361 additions and 361 deletions
20
.claude/rules/agents.md
Normal file
20
.claude/rules/agents.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
## Kaizen Agents
|
||||
|
||||
Specialized agent personas available on demand via the state-hub MCP.
|
||||
|
||||
**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
|
||||
**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
|
||||
|
||||
Common agents:
|
||||
|
||||
| Agent | Category | When to use |
|
||||
|-------|----------|-------------|
|
||||
| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
|
||||
| `code-refactoring` | quality | Code quality analysis and safe refactoring |
|
||||
| `test-maintenance` | testing | Diagnose and fix failing tests |
|
||||
| `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
|
||||
| `keepaTodofile` | process | Maintain TODO.md during work |
|
||||
| `project-management` | process | Track status, determine next steps |
|
||||
| `datamodel-optimization` | quality | Optimize dataclasses and data structures |
|
||||
|
||||
All 17 agents: call `list_kaizen_agents()` for the full list.
|
||||
8
.claude/rules/architecture.md
Normal file
8
.claude/rules/architecture.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
## Architecture
|
||||
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
|
||||
## Quick Reference
|
||||
|
||||
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
|
||||
50
.claude/rules/credential-routing.md
Normal file
50
.claude/rules/credential-routing.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
# Credential and access routing
|
||||
|
||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
||||
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
||||
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
||||
|
||||
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||
other credential need belongs to another subsystem. **Do not** message
|
||||
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
|
||||
|
||||
### Lookup (do this first)
|
||||
|
||||
```bash
|
||||
warden route find "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
|
||||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=direkt-vermittlung-de` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
### Quick routing table
|
||||
|
||||
| I need… | Owner | ops-warden executes? |
|
||||
| --- | --- | --- |
|
||||
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||
| Authorization decision | flex-auth | No — route only |
|
||||
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
|
||||
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||
|
||||
### Anti-patterns (do not do these)
|
||||
|
||||
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||
|
||||
### Other capabilities (reuse-surface)
|
||||
|
||||
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||
get wrong.
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
42
.claude/rules/first-session.md
Normal file
42
.claude/rules/first-session.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
## First Session Protocol
|
||||
|
||||
Triggered when `get_domain_summary("government")` shows **no workplans**.
|
||||
The project is registered but work has not yet been structured.
|
||||
|
||||
**Step 1 — Read, don't write**
|
||||
- `~/the-custodian/canon/projects/government/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/government/roadmap_v0.1.md` — planned phases
|
||||
- Scan repo root: README, directory structure, existing code or docs
|
||||
|
||||
**Step 2 — Survey in-progress work**
|
||||
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
|
||||
|
||||
**Step 3 — Propose workplans to Bernd**
|
||||
Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
|
||||
roadmap phase. **Wait for approval before creating.**
|
||||
|
||||
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
|
||||
```
|
||||
workplans/DVD-WP-NNNN-<slug>.md ← write this, commit it
|
||||
```
|
||||
Then register by running the consistency check — do **not** call
|
||||
`create_workplan`/`create_task` yourself; manual registration duplicates what
|
||||
C-06 creates from the file:
|
||||
```bash
|
||||
statehub fix-consistency --repo direkt-vermittlung-de
|
||||
```
|
||||
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
|
||||
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
|
||||
back into the file.
|
||||
|
||||
**Step 5 — Record the setup**
|
||||
```
|
||||
add_progress_event(
|
||||
summary="First session: structured government into N workplans, M tasks",
|
||||
event_type="milestone",
|
||||
topic_id="084430ab-c630-48dc-9e1d-d07d1e8fce3c",
|
||||
detail={"workplans": [...], "tasks_created": M}
|
||||
)
|
||||
```
|
||||
|
||||
<!-- Delete or archive this file once past first session -->
|
||||
8
.claude/rules/repo-boundary.md
Normal file
8
.claude/rules/repo-boundary.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
## Repo boundary
|
||||
|
||||
This repo owns **direkt-vermittlung-de** only. It does not own:
|
||||
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
5
.claude/rules/repo-identity.md
Normal file
5
.claude/rules/repo-identity.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
**Purpose:** DirektVermittlungDe is a document-centric platform that routes citizens' documents or reference numbers (Aktenzeichen) directly to the responsible German authority caseworker and opens a communication thread, replacing manual phone-routing hunts.
|
||||
|
||||
**Domain:** government
|
||||
**Repo slug:** direkt-vermittlung-de
|
||||
**Topic ID:** 084430ab-c630-48dc-9e1d-d07d1e8fce3c
|
||||
92
.claude/rules/session-protocol.md
Normal file
92
.claude/rules/session-protocol.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
## Session Protocol
|
||||
|
||||
Dev Hub (State Hub API): http://127.0.0.1:8000
|
||||
MCP server name in `~/.claude.json`: `dev-hub`
|
||||
|
||||
**Step 1 — Orient**
|
||||
|
||||
Read the offline-safe brief first — it works without a live hub connection:
|
||||
```bash
|
||||
cat .custodian-brief.md
|
||||
```
|
||||
Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
|
||||
```
|
||||
get_domain_summary("government")
|
||||
```
|
||||
If MCP tools are unavailable in the current agent session, use the REST API:
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
|
||||
```
|
||||
If the hub is offline: `cd ~/state-hub && make api`
|
||||
|
||||
**Step 2 — Check inbox**
|
||||
With MCP tools:
|
||||
```
|
||||
get_messages(to_agent="direkt-vermittlung-de", unread_only=True)
|
||||
```
|
||||
Mark read with `mark_message_read(message_id)`. Reply or act on coordination
|
||||
requests before proceeding.
|
||||
|
||||
Without MCP tools:
|
||||
```bash
|
||||
curl -s "http://127.0.0.1:8000/messages/?to_agent=direkt-vermittlung-de&unread_only=true" \
|
||||
| python3 -m json.tool
|
||||
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
|
||||
-H "Content-Type: application/json" -d '{}'
|
||||
```
|
||||
|
||||
**Step 3 — Scan workplans**
|
||||
```bash
|
||||
ls workplans/
|
||||
```
|
||||
For each file with `status: ready`, `active`, or `blocked`, note pending
|
||||
`wait`/`todo`/`progress` tasks.
|
||||
|
||||
**Step 4 — Present brief**
|
||||
|
||||
1. **Active workplans** for `government` — title, task counts, blocking decisions
|
||||
2. **Pending tasks** from `workplans/` + any `[repo:direkt-vermittlung-de]` hub tasks
|
||||
3. **Goal guidance** — if `goal_guidance` in summary:
|
||||
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
|
||||
- `alignment_warnings`: flag if active work is not aligned with current goal
|
||||
4. **Suggested next action** — highest-priority open item
|
||||
5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
|
||||
|
||||
If no workplans: follow First Session Protocol (`first-session.md`).
|
||||
|
||||
**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
|
||||
|
||||
> State Hub is a *read model*. **Never register workplans or tasks by hand**
|
||||
> (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
|
||||
> and run `fix-consistency`; C-06 registers the workplan and tasks and writes
|
||||
> IDs back into the file. Manual registration creates duplicates when
|
||||
> fix-consistency runs. Work structure belongs in repo files (ADR-001).
|
||||
>
|
||||
> Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
|
||||
> see `workplan-convention.md` (compatibility footnote).
|
||||
|
||||
**Session close:**
|
||||
With MCP tools:
|
||||
```
|
||||
add_progress_event(summary="...", topic_id="084430ab-c630-48dc-9e1d-d07d1e8fce3c", workplan_id="<uuid>")
|
||||
```
|
||||
Without MCP tools:
|
||||
```bash
|
||||
curl -s -X POST http://127.0.0.1:8000/progress/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"topic_id":"084430ab-c630-48dc-9e1d-d07d1e8fce3c","workplan_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
|
||||
```
|
||||
If workplan files were modified, ensure the local copy is up to date first,
|
||||
then sync from the repo checkout:
|
||||
```bash
|
||||
git pull --ff-only
|
||||
statehub fix-consistency
|
||||
```
|
||||
For repos where implementation runs on a remote machine (e.g. CoulombCore),
|
||||
use the pull-before-fix mode from any shell with the State Hub CLI:
|
||||
```bash
|
||||
statehub fix-consistency --repo direkt-vermittlung-de --remote
|
||||
```
|
||||
**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
|
||||
will sync the file to match DB. **C-16** (repo behind remote) blocks all writes
|
||||
until you pull — intentional to prevent clobbering remote progress.
|
||||
19
.claude/rules/stack-and-commands.md
Normal file
19
.claude/rules/stack-and-commands.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
## Stack
|
||||
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **Language:**
|
||||
- **Key deps:**
|
||||
|
||||
## Dev Commands
|
||||
|
||||
```bash
|
||||
# TODO: Fill in the standard commands for this repo
|
||||
|
||||
# Install dependencies
|
||||
|
||||
# Run tests
|
||||
|
||||
# Lint / type check
|
||||
|
||||
# Build / package (if applicable)
|
||||
```
|
||||
55
.claude/rules/workplan-convention.md
Normal file
55
.claude/rules/workplan-convention.md
Normal file
|
|
@ -0,0 +1,55 @@
|
|||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/DVD-WP-NNNN-<slug>.md`
|
||||
ID prefix: `DVD-WP-`
|
||||
|
||||
Work items originate as files in this repo **before** being registered in the hub.
|
||||
|
||||
Canonical workplan frontmatter statuses are:
|
||||
`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
|
||||
Use `proposed` for a newly drafted plan, `ready` after review against current
|
||||
repo state, and `finished` when implementation is complete. `stalled` and
|
||||
`needs_review` are derived health labels, not stored statuses.
|
||||
|
||||
Closed workplans may be moved to `workplans/archived/` with a completion-date
|
||||
prefix: `YYMMDD-DVD-WP-NNNN-<slug>.md`. The frontmatter id remains
|
||||
unchanged; the prefix is only for quick visual reference.
|
||||
|
||||
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
|
||||
`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
|
||||
`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
|
||||
directly. Promote anything requiring analysis, design, approval, dependencies, or
|
||||
multiple planned phases into a normal workplan.
|
||||
|
||||
Ecosystem todos from other agents arrive as `[repo:direkt-vermittlung-de]` hub tasks —
|
||||
visible at session start. Pick one up by creating the workplan file, committing,
|
||||
and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
|
||||
Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
|
||||
|
||||
Task blocks use this shape:
|
||||
|
||||
```task
|
||||
id: DVD-WP-NNNN-T01
|
||||
status: wait | todo | progress | done | cancel
|
||||
priority: high | medium | low
|
||||
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
|
||||
```
|
||||
|
||||
Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
|
||||
blocked work and `cancel` for stopped work.
|
||||
|
||||
Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
|
||||
kept for compatibility; it holds the hub workplan UUID and is written by
|
||||
fix-consistency. Do not edit or rename it.
|
||||
|
||||
### Legacy terminology (compatibility footnote)
|
||||
|
||||
**Workplan** is the fleet term — see
|
||||
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
|
||||
**Workstream** is legacy only: some API routes (`/workstreams/`), params
|
||||
(`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
|
||||
above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
|
||||
identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
|
||||
examples and scripts.
|
||||
|
||||
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
|
||||
51
AGENTS.md
51
AGENTS.md
|
|
@ -107,7 +107,56 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
|
|||
|
||||
---
|
||||
|
||||
{CREDENTIAL_ROUTING}
|
||||
## Credential and access routing
|
||||
|
||||
**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
|
||||
for inference. Run this check **before** requesting secrets, API keys, SSH access,
|
||||
login tokens, or database passwords — in any repo, not only `ops-warden`.
|
||||
|
||||
ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
|
||||
other credential need belongs to another subsystem. **Do not** message
|
||||
`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
|
||||
|
||||
### Lookup (do this first)
|
||||
|
||||
```bash
|
||||
warden route find "<describe your need>" --json
|
||||
warden route show <catalog-id> --json
|
||||
```
|
||||
|
||||
Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
|
||||
|
||||
| Agent runtime | How to orient |
|
||||
| --- | --- |
|
||||
| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=direkt-vermittlung-de` is for coordination, not secret vending |
|
||||
| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
|
||||
| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
|
||||
|
||||
### Quick routing table
|
||||
|
||||
| I need… | Owner | ops-warden executes? |
|
||||
| --- | --- | --- |
|
||||
| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
|
||||
| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
|
||||
| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
|
||||
| Authorization decision | flex-auth | No — route only |
|
||||
| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
|
||||
| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
|
||||
|
||||
### Anti-patterns (do not do these)
|
||||
|
||||
- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
|
||||
- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
|
||||
- Pasting secrets into Git, State Hub, workplans, logs, or chat
|
||||
|
||||
### Other capabilities (reuse-surface)
|
||||
|
||||
Non-credential capabilities are usually discovered through **reuse-surface** federation
|
||||
(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
|
||||
every repo's agent instructions because it is high-frequency, high-risk, and easy to
|
||||
get wrong.
|
||||
|
||||
**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
|
||||
|
||||
<!-- REPO-AGENTS-EXTENSIONS -->
|
||||
<!-- Append repo-specific agent instructions below this marker.
|
||||
|
|
|
|||
372
CLAUDE.md
372
CLAUDE.md
|
|
@ -1,360 +1,12 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
**DirektVermittlungDe (DVD)** is a document-centric communication platform between citizens and German authorities. It eliminates the "phone hunt" by:
|
||||
1. Citizens upload a document or provide an *Aktenzeichen* (reference number)
|
||||
2. The system auto-routes to the responsible unit
|
||||
3. Opens an interaction thread for direct clarification
|
||||
|
||||
## Current Development Status
|
||||
|
||||
**⚠️ IMPORTANT**: This repository is currently in transition from prototype phase to main production codebase.
|
||||
|
||||
- **Current State**: Three prototype implementations (chatgpt5, geminiNbt3pro, grok4.1) in `/prototype-*` directories
|
||||
- **Target State**: Unified production codebase in `/src` with TDD-driven development
|
||||
- **Active Workplan**: See `docs/WORKPLAN_MainCodebase_Integration.md` for detailed migration plan
|
||||
|
||||
**When working on this codebase:**
|
||||
- Check the workplan to understand which phase we're in
|
||||
- Follow TDD practices: write tests first, then implementation
|
||||
- Reference ADRs for architectural decisions (see below)
|
||||
- New code goes in `/src`, not prototypes
|
||||
|
||||
## Repository Structure (Target State)
|
||||
|
||||
```
|
||||
/
|
||||
├── docs/
|
||||
│ ├── architecture/
|
||||
│ │ ├── adr/ # Individual ADR files (0001-*.md)
|
||||
│ │ │ ├── 0001-split-payload-model.md
|
||||
│ │ │ ├── 0002-stateless-authentication.md
|
||||
│ │ │ └── ...
|
||||
│ │ ├── architecture-overview.md
|
||||
│ │ └── design-patterns.md
|
||||
│ ├── api/
|
||||
│ │ ├── openapi.yaml
|
||||
│ │ └── api-scenarios.md
|
||||
│ ├── development/
|
||||
│ │ ├── testing-strategy.md
|
||||
│ │ ├── agentic-coding-guide.md
|
||||
│ │ └── setup-guide.md
|
||||
│ └── WORKPLAN_MainCodebase_Integration.md
|
||||
├── src/
|
||||
│ ├── domain/ # Pure business logic (TDD tested)
|
||||
│ ├── adapters/ # External integrations (mocked in tests)
|
||||
│ ├── service/ # Application services (TDD tested)
|
||||
│ ├── api/ # FastAPI routes (integration tested)
|
||||
│ └── workers/ # Background jobs
|
||||
├── tests/
|
||||
│ ├── unit/ # TDD unit tests
|
||||
│ ├── integration/ # Integration tests
|
||||
│ └── fixtures/ # Test data and mocks
|
||||
├── scripts/ # Utility scripts
|
||||
├── prototype-*/ # ARCHIVED prototypes (reference only)
|
||||
├── pyproject.toml # Dependencies & tool config
|
||||
└── pytest.ini # Test configuration
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Setup and Run (Main Codebase)
|
||||
|
||||
```bash
|
||||
# Install dependencies (from repo root)
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Initialize database metadata
|
||||
python -m scripts.init_db
|
||||
|
||||
# Run development server
|
||||
uvicorn src.main:app --reload
|
||||
|
||||
# View API docs
|
||||
# http://localhost:8000/docs
|
||||
```
|
||||
|
||||
### Testing (TDD Workflow)
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest
|
||||
|
||||
# Run with coverage report
|
||||
pytest --cov=src --cov-report=html
|
||||
|
||||
# Run only unit tests
|
||||
pytest tests/unit/
|
||||
|
||||
# Run only integration tests
|
||||
pytest tests/integration/
|
||||
|
||||
# Run specific test file
|
||||
pytest tests/unit/domain/test_document_metadata.py -v
|
||||
|
||||
# Watch mode (requires pytest-watch)
|
||||
ptw
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
# Lint and format with ruff
|
||||
ruff check src/ tests/
|
||||
ruff format src/ tests/
|
||||
|
||||
# Type checking with mypy
|
||||
mypy src/
|
||||
|
||||
# Run pre-commit hooks manually
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
## Key Architectural Patterns
|
||||
|
||||
### 1. Split-Payload Model (ADR-001)
|
||||
|
||||
**Critical**: Documents use a split design to enable both encryption and routing:
|
||||
- **metadata** (plaintext JSON): authorityId, referenceNumber, docType, issuedAt
|
||||
- **encryptedPayload** (encrypted blob): actual PDF/scan content
|
||||
|
||||
The backend can route based on metadata without decrypting the payload. This is the core architectural constraint.
|
||||
|
||||
When working with documents:
|
||||
- NEVER attempt to decrypt `encryptedPayload` in the main service
|
||||
- The backend treats encrypted content as opaque
|
||||
- Routing logic operates only on metadata fields
|
||||
|
||||
### 2. Hybrid Concurrency Pattern (ADR-007)
|
||||
|
||||
Python's GIL requires careful concurrency handling:
|
||||
- **I/O operations** (DB, network): Use native `async`/`await`
|
||||
- **CPU operations** (crypto, PDF): Offload to `ProcessPoolExecutor`
|
||||
|
||||
Example pattern:
|
||||
```python
|
||||
cpu_pool = ProcessPoolExecutor(max_workers=4)
|
||||
|
||||
async def handler():
|
||||
# I/O: async/await
|
||||
data = await db.fetch()
|
||||
|
||||
# CPU: executor
|
||||
loop = asyncio.get_running_loop()
|
||||
result = await loop.run_in_executor(cpu_pool, heavy_function, data)
|
||||
```
|
||||
|
||||
### 3. Cursor-Based Pagination (ADR-003)
|
||||
|
||||
For message threads, use cursor-based pagination (timestamp) instead of offset-based:
|
||||
- Ensures consistent performance regardless of thread length
|
||||
- Prevents duplicate/missing messages during real-time updates
|
||||
- Target: <300ms response time (NFR-1)
|
||||
|
||||
### 4. Async Export Pattern (ADR-004)
|
||||
|
||||
Data exports use async request-reply:
|
||||
1. POST `/exports` → 202 Accepted + jobId
|
||||
2. Background worker processes via message queue
|
||||
3. Client polls status endpoint or receives webhook
|
||||
|
||||
### 5. Stateless Authentication (ADR-002)
|
||||
|
||||
OAuth2/JWT with scopes:
|
||||
- `citizen:write`: Document submission, thread creation
|
||||
- `official:read`: View assigned cases
|
||||
- `official:write`: Respond to inquiries
|
||||
|
||||
JWTs enable horizontal scaling without session affinity.
|
||||
|
||||
### 6. GDPR-Compliant Retention (ADR-006)
|
||||
|
||||
Documents have `retention_date` field:
|
||||
- Default: `closedAt + gracePeriod`
|
||||
- Personal archive: `null` or extended date
|
||||
- Automated cleanup via TTL engine
|
||||
|
||||
## API Structure
|
||||
|
||||
The API follows document-centric REST hierarchy:
|
||||
- `/documents` - Root envelope (FR-1: Document intake)
|
||||
- `/documents/{id}/threads` - Sub-resource for communication (FR-3)
|
||||
- `/threads/{threadId}/messages` - Message exchange
|
||||
- `/exports` - Async data export for authority systems (FR-7)
|
||||
|
||||
## Critical Domain Models
|
||||
|
||||
Located in `src/domain/models.py` (target) or `prototype-chatgpt5/src/app/domain/models.py` (reference):
|
||||
|
||||
**Enums:**
|
||||
- **ThreadType**: TEXT_CHAT, CALLBACK_REQUEST, APPOINTMENT
|
||||
- **SenderRole**: CITIZEN, OFFICIAL, SYSTEM
|
||||
- **ExportJobStatus**: QUEUED, RUNNING, COMPLETED, FAILED
|
||||
|
||||
**Core Models:**
|
||||
- **DocumentMetadata**: authorityId, referenceNumber, docType, issuedAt
|
||||
- Validation: authorityId (1-50 chars), referenceNumber required
|
||||
- **DocumentCreateRequest**: metadata, encryptedPayload (base64)
|
||||
- **DocumentCreatedResponse**: id, status, assignedUnit
|
||||
- **ThreadCreateRequest**: type, initialMessage, preferredTimeSlot
|
||||
- **MessageDto**: id, senderRole, content (encrypted), timestamp
|
||||
|
||||
## Performance Targets (NFR)
|
||||
|
||||
- Core operations: <300ms response time
|
||||
- Document upload routing: <500ms
|
||||
- Concurrent sessions: 10k+ per region
|
||||
- Availability: ≥99.5%
|
||||
|
||||
## Security Constraints
|
||||
|
||||
- E2E encryption required for sensitive data (NFR-5)
|
||||
- Backend cannot decrypt document payloads
|
||||
- Least-privilege access via OAuth scopes (NFR-6)
|
||||
- No PII in plaintext application logs
|
||||
|
||||
## TDD Development Workflow
|
||||
|
||||
**CRITICAL**: This project follows a strict Test-Driven Development approach.
|
||||
|
||||
### The Red-Green-Refactor Cycle
|
||||
|
||||
1. **RED**: Write a failing test that defines desired behavior
|
||||
2. **GREEN**: Write minimal code to make the test pass
|
||||
3. **REFACTOR**: Improve code while keeping tests green
|
||||
|
||||
### Example TDD Workflow
|
||||
|
||||
```python
|
||||
# Step 1: Write failing test (tests/unit/domain/test_document_metadata.py)
|
||||
def test_document_metadata_validates_authority_id():
|
||||
with pytest.raises(ValidationError):
|
||||
DocumentMetadata(
|
||||
authorityId="", # Empty should fail
|
||||
referenceNumber="123/456",
|
||||
docType="NOTICE",
|
||||
issuedAt=datetime.now()
|
||||
)
|
||||
|
||||
# Step 2: Run test (it fails)
|
||||
# $ pytest tests/unit/domain/test_document_metadata.py
|
||||
|
||||
# Step 3: Implement validation (src/domain/models.py)
|
||||
class DocumentMetadata(BaseModel):
|
||||
authorityId: str = Field(..., min_length=1, max_length=50)
|
||||
# ... rest of fields
|
||||
|
||||
# Step 4: Run test again (it passes)
|
||||
|
||||
# Step 5: Refactor if needed, ensure tests still pass
|
||||
```
|
||||
|
||||
### Agentic TDD Pattern
|
||||
|
||||
When asking Claude to implement features, use this pattern:
|
||||
|
||||
```
|
||||
"Write a test for [feature] that verifies [specific behavior].
|
||||
Use pytest and follow the pattern in tests/unit/[module]/.
|
||||
Reference ADR-[number] for architectural constraints."
|
||||
```
|
||||
|
||||
Example:
|
||||
```
|
||||
"Write a test for document routing that verifies documents with docType='NOTICE'
|
||||
are routed to the NoticeTeam. Mock the routing adapter using the protocol defined
|
||||
in src/adapters/protocols.py. Follow ADR-0001 split-payload constraints."
|
||||
```
|
||||
|
||||
See `docs/development/agentic-coding-guide.md` for comprehensive examples.
|
||||
|
||||
## Documentation References
|
||||
|
||||
### Architecture & Decisions
|
||||
- **Workplan**: `docs/WORKPLAN_MainCodebase_Integration.md` - Current migration plan
|
||||
- **ADRs**: `docs/architecture/adr/` - Individual decision records
|
||||
- `0001-split-payload-model.md` - Core constraint: metadata vs encrypted payload
|
||||
- `0002-stateless-authentication.md` - OAuth2/JWT architecture
|
||||
- `0003-cursor-based-pagination.md` - Performance-optimized pagination
|
||||
- `0004-async-export-workflow.md` - Background job pattern
|
||||
- `0005-rest-resource-structure.md` - API design hierarchy
|
||||
- `0006-gdpr-retention-model.md` - Data lifecycle management
|
||||
- `0007-hybrid-concurrency-pattern.md` - Python GIL mitigation
|
||||
- `0008-agentic-tdd-workflow.md` - LLM-driven development process
|
||||
- **Overview**: `docs/architecture/architecture-overview.md` - System design
|
||||
- **Patterns**: `docs/architecture/design-patterns.md` - Common patterns
|
||||
|
||||
### API Documentation
|
||||
- **OpenAPI**: `docs/api/openapi.yaml` - Full API specification
|
||||
- **Scenarios**: `docs/api/api-scenarios.md` - Real-world usage examples
|
||||
|
||||
### Development Guides
|
||||
- **Testing**: `docs/development/testing-strategy.md` - TDD practices
|
||||
- **Agentic Coding**: `docs/development/agentic-coding-guide.md` - AI-assisted development
|
||||
- **Setup**: `docs/development/setup-guide.md` - Environment setup
|
||||
|
||||
### Legacy (Prototypes)
|
||||
- `prototype-chatgpt5/README.md` - Reference implementation (ARCHIVED)
|
||||
- `docs/decisions.md` - Original ADRs (DEPRECATED, see /docs/architecture/adr/)
|
||||
|
||||
## Database Schema
|
||||
|
||||
Key tables (PostgreSQL):
|
||||
- **documents**: id, reference_number, authority_id, status, storage_path, retention_date
|
||||
- **threads**: id, document_id, type, assigned_official_id, last_activity_at
|
||||
- **messages**: id, thread_id, sender_role, content_blob, created_at
|
||||
|
||||
Indexes:
|
||||
- `idx_docs_authority` on documents(authority_id, status)
|
||||
- `idx_msgs_thread_time` on messages(thread_id, created_at DESC)
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Language**: Python 3.11+
|
||||
- **Framework**: FastAPI + Uvicorn
|
||||
- **ORM**: SQLAlchemy (async)
|
||||
- **Database**: PostgreSQL 15+
|
||||
- **Blob Storage**: S3-compatible (MinIO/AWS S3)
|
||||
- **Task Queue**: ARQ (Redis-based, async) or Celery
|
||||
- **Auth**: OAuth2/JWT (stateless)
|
||||
- **Testing**: pytest + pytest-asyncio + pytest-cov
|
||||
- **Linting**: ruff (fast, replaces flake8/isort/pyupgrade)
|
||||
- **Type Checking**: mypy (strict mode)
|
||||
- **CI/CD**: GitHub Actions
|
||||
|
||||
## Workplan & Phase Tracking
|
||||
|
||||
**Active Workplan**: `docs/WORKPLAN_MainCodebase_Integration.md`
|
||||
|
||||
### Current Phase Status
|
||||
|
||||
To check which phase we're in:
|
||||
1. Open `docs/WORKPLAN_MainCodebase_Integration.md`
|
||||
2. Look for checked `[x]` items in each phase section
|
||||
3. Focus development on uncompleted `[ ]` items in the current phase
|
||||
|
||||
### How to Contribute
|
||||
|
||||
**Before implementing any feature:**
|
||||
1. Check if it's in the current phase of the workplan
|
||||
2. Read the relevant ADR(s) in `docs/architecture/adr/`
|
||||
3. Write tests first (TDD approach)
|
||||
4. Implement to make tests pass
|
||||
5. Ensure all quality gates pass (pytest, mypy, ruff)
|
||||
|
||||
**When adding new architectural decisions:**
|
||||
1. Create a new ADR file in `docs/architecture/adr/`
|
||||
2. Use the template in `0000-template.md`
|
||||
3. Number sequentially (next available number)
|
||||
4. Update the ADR index in `docs/architecture/adr/README.md`
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
1. **Stream large files**: Use `aiobotocore` to stream uploads to S3, don't load entire payloads into memory
|
||||
2. **ProcessPoolExecutor**: CPU-heavy operations MUST be offloaded to avoid blocking the event loop
|
||||
3. **Metadata separation**: The routing engine needs plaintext metadata - design API contracts accordingly
|
||||
4. **Retention dates**: Always set `retention_date` on document creation for GDPR compliance
|
||||
5. **Cursor pagination**: Use timestamp-based cursors for message history, not offset-based
|
||||
# direkt-vermittlung-de — Claude Code Instructions
|
||||
|
||||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@.claude/rules/workplan-convention.md
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
@.claude/rules/repo-boundary.md
|
||||
@.claude/rules/credential-routing.md
|
||||
@.claude/rules/agents.md
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue