# pvtcoms

Private, serverless, P2P, **anonymous, post-quantum** encrypted messenger. Plan: [`BUILD_PLAN.md`](./BUILD_PLAN.md)
(v1 scope), [`DESIGN.md`](./DESIGN.md) (full reference), [`THREAT_MODEL.md`](./THREAT_MODEL.md), [`README.md`](./README.md).

## Pipeline

**Flow**: `BACKLOG -> CODE -> TEST -> PROMOTE -> COMMIT -> DEPLOY -> VERIFY`

**Stack**: Rust (core: crypto/transport/protocol/storage) — pre-code; Android/Kotlin-Compose + Desktop/Tauri planned; iOS/Swift deferred to v2. Tests: `cargo test`.

### Commands

```bash
python3 scripts/docs/backlog_ops.py add "Title" --category feature  # capture request
python3 scripts/docs/backlog_ops.py start SR-ID                      # begin work
python3 scripts/docs/backlog_ops.py done SR-ID                       # mark complete
python3 scripts/docs/backlog_ops.py promote                          # push to CHANGELOG + bump version
python3 scripts/docs/backlog_ops.py list                             # view all items
python3 scripts/docs/version_bump.py show                            # check version sync
python3 scripts/docs/version_bump.py minor                           # bump minor version
python3 scripts/docs/detect_error_patterns.py                        # scan for bug patterns
python3 scripts/docs/detect_error_patterns.py --analyze "error msg"  # reactive error analysis
python3 scripts/docs/enforce_coding_standards.py --files f1.rs f2.rs # check specific files
python3 scripts/docs/check_freshness.py                              # doc staleness report
python3 scripts/docs/check_spec.py --generate SR-ID "Title"          # create spec template
python3 scripts/docs/ai_review.py                                    # AI code review (optional)
```

### Rules

- Do NOT commit untested code — test gate will BLOCK the commit
- Do NOT deploy without committing first
- Do NOT skip rebuilding when source is baked into build artifacts
- **Security-critical**: never roll your own crypto; never log plaintext/keys/tokens/IPs; zeroize secrets; fail closed (no Tor→clearnet fallback); no telemetry. See `.claude/rules/coding-standards.md` + `THREAT_MODEL.md`.
- 22 hooks enforce these rules automatically (see `.claude/rules/pipeline.md` for details)
- Run `dependency-governance` skill to audit stack health once `Cargo.toml` exists

**Rules files** (all in `.claude/rules/`, always apply): `pipeline.md` (flow + hooks), `coding-standards.md` (security-critical MUST/NEVER), `coding-guardrails.md` (pre/during/post-code discipline), `context-router.md` (on-demand doc loading), `doc-maintenance.md` (code→doc impact + freshness).

### Router (front door for every request)

Before touching code, BACKLOG.md, or docs: **read `.claude/sub-skills/router.md`** and apply its decision tree. The router decides whether to invoke a sub-skill (grill, to-prd, to-issues, tdd, diagnose, prototype, triage) or proceed directly with `backlog_ops.py add`. Trivial changes skip every sub-skill.

When the context budget is ≥75%, the router delegates to a subagent instead of loading the sub-skill inline — keeps the main session lean. Log every routing decision via `sub_skill_dispatcher.py log`.

### CONTEXT.md (project glossary)

The project's domain glossary lives in `CONTEXT.md` at the repo root. Sub-skills (grill, to-prd, tdd, diagnose) use this vocabulary so tests, PRDs, and SR titles stay consistent. Update it inline as terms resolve — never batch.

### Documentation

Docs live in `docs/` with YAML frontmatter for freshness tracking.

| Doc | Tier | Purpose |
|-----|------|---------|
| `docs/ARCHITECTURE.md` | 0 | System design and component overview |
| `docs/DEVELOPMENT.md` | 0 | Getting started, commands, env vars |
| `docs/ADR/` | 0 | Architecture Decision Records |
| `docs/TESTING.md` | 1 | Test strategy, commands, coverage |
| `docs/KEY_PATTERNS.md` | 1 | Master pattern index with severity levels |
| `docs/context/` | 1 | Quick reference packs (crypto, transport, delivery, onboarding, core, testing) |
| `docs/DEPLOYMENT.md` | 2 | Build, distribution, signing, reproducible builds |
| `docs/SECURITY.md` | 2 | Developer security checklist (boundary: `THREAT_MODEL.md`) |
| `docs/RUNBOOK.md` | 2 | Build/release ops, incident response |
| `docs/standards/` | 2 | Prescriptive MUST/NEVER coding rules |
| `docs/patterns/` | 2 | Detailed implementation patterns (core, testing) |
| `docs/specs/` | 3 | Feature specifications (auto-generated) |
| `docs/PRDs/` | 3 | Product Requirements Documents (from `to-prd` sub-skill) |
| `docs/reports/` | 3 | Audit and analysis reports |
| `docs/releases/` | 3 | Version-specific release notes |

Project-level plan docs at root: `README.md`, `BUILD_PLAN.md` (v1 scope), `DESIGN.md` (full reference), `THREAT_MODEL.md`.

Check doc freshness: `python3 scripts/docs/check_freshness.py`
Check version sync: `python3 scripts/docs/version_bump.py show`