pdurlej/platform

Canonical desired-state spec for piotr's homelab platform (RS 2000 + VPS 1000 + Mac/iPhone Tailnet). The repo is the source of truth; runtime is reconciled to match.

The repo is not the runtime. Runtime lives on RS 2000 (/opt/vps-home-platform-infra/) and VPS 1000 (/home/openclaw/). The repo describes intent + observed state; control plane (platformctl, future) reconciles.

---

I just walked in. Where do I start?

If you are a human reader, skim in this order:

1. PLATFORM_CHARTER.md — vision, deploy flow, cognition rule (10 min)
2. state/STATUS_NOW.md + state/strategy/platform-maturity-roadmap-*.md — current status and roadmap (10 min)
3. decisions/ — numbered ADRs in chronological order (5 min each)
4. Forgejo Issues filtered by owner-attention — what needs your call right now

If you are an agent (claude / codex / glm / antigravity / new arrival), read in this order:

1. AGENTS.md — repo runbook (must-read; identity-isolation, canary, conventions)
2. docs/forgejo-agent-operations.md — critical Forgejo operating contract; read before issues, PRs, Actions, runners, review bots, or Infisical-backed provider work
3. AGENTS.md §"Joining as a new agent" — onboarding cookbook
4. Forgejo Issues filtered by your skill class — pick one
5. The issue's ## Spec sources section will tell you exactly which charter/ADR/module sections are relevant

If you are an operator-facing report, start at the relevant state/reports/STATE_OF_PLATFORM_*.md Owner Action Board section.

---

Repo map (mobile-scannable)

Where	What	Audience
PLATFORM_CHARTER.md	Vision, deploy flow, cognition rule, sacred paths	All
PLATFORM_CONSTITUTION.md	Declarative oaths (counterpart to Iskra Constitution)	All
AGENTS.md	Repo runbook: identity-isolation, canary, conventions, anti-patterns	Agents
docs/forgejo-agent-operations.md	Critical Forgejo operating contract for agents: identity, issues, PRs, Actions, secrets, Ollama review bot	Agents
INDEX.md	Artifact map (full file-by-file index)	Agents
decisions/	Architectural Decision Records (Nygard format, numbered)	All
state/reports/	Strategic stop reports (STATE_OF_PLATFORM_*)	Operator
state/archive/2026-04-30-L0-L4-synthesis/	Archived Apr-30 L0-L4 synthesis; current status is state/STATUS_NOW.md	Historical reference
modules/<id>/module.yaml	Per-module manifest (JSON-Schema validated)	Producer / reviewers
modules/<id>/runbook.md	Per-module operator runbook	Operator / reviewers
prompts/	Master prompts driving Codex per wave	Producer (Codex)
schema/module.schema.json	JSON Schema for module.yaml	Validators
control-plane/platformctl/	Future control plane (validate/plan/apply/health/logs)	Phase 03+
tests/	smoke.sh runtime drift detector + validate-schema.sh	All
.forgejo/workflows/	CI workflows (canary-required scaffold; Issue #49 to operationalize)	Platform
.forgejo/issue_template/	Issue templates: atomic / meta / owner-decision	Issue authors
runbooks/	Cross-module operator runbooks (deploy-vps1000, forgejo-actions-runner)	Operator
migrations/	Vault → Infisical cutover plan	Operator (Phase 06)
network/	Tailscale ACL seed (comment-heavy; never auto-applied)	Operator
baseline/	Hard Backup Baseline manifest (immutable; per L-1 of original plan)	Operator

---

Current phase

Phase 02 — Cataloging (~10% coverage as of 2026-05-04). Each module gets v2 audit fields per AGENTS.md §"Current phase". Roadmap in state/reports/STATE_OF_PLATFORM_2026-05-03.md §7.

After Phase 02 (~85 modules; pivot tranche of ~25 covers waves 4-9) → Phase 03 (control plane: platformctl) → Phase 04 (observability) → Phase 05 (agent execution) → Phase 06 (prune + cutover).

Sequencing is owner-attention-bounded, not calendar-bounded.

---

How work flows

issue (Forgejo)
   ↓ agent picks one (per AGENTS.md §"Joining as a new agent")
   ↓ branch: <actor>/orders/<short-slug>  (actor ∈ {claude, codex, glm, antigravity})
   ↓ commits authored as <actor> identity (per AGENTS.md §"Identity-isolation")
   ↓ PR with Canary Context Pack (per AGENTS.md)
   ↓ canary 3+3 review (mandatory for module/schema/prompts/tests/decisions paths)
   ↓ ≤3 iterations max → terminal action (approve_merge | … | split_pr)
   ↓ operator merges
   ↓ issue auto-closed (or manually if cross-issue)

Operator never reviews diffs by default — operator reviews decisions the orchestrator surfaces via Owner Action Board format.

---

Identity isolation (TL;DR)

Every actor commits and creates PRs as itself, never as pdurlej:

• claude — orchestrator (PM role)
• codex — producer (executes master prompts)
• glm — z.ai reviewer
• antigravity — Gemini-based scheduled PR factory (planned, see Issue #57)
• pdurlej — owner; merge gate; not used for agent work

Concrete bash + PAT retrieval pattern in AGENTS.md §"Identity-isolation".

---

Quality gates

Gate	What it does	Where
Canary 3+3	Six diverse-model reviewers (tech-claude, tech-codex, tech-glm × product-claude, product-codex, product-glm)	ADR 0001 + AGENTS.md
Hard 3-iter cap	Forces terminal decision after 3 review rounds	ADR 0002 Rule 2
Smoke.sh	Runtime drift detector (manifest claim ≠ docker reality)	tests/smoke.sh
validate-schema.sh	JSON Schema validation for module.yaml	tests/validate-schema.sh
Strategic stop	Owner-facing product overview every N=3 cycles	ADR 0001 Rule 4
Night Review	Batch sanity check for accumulated small PRs	AGENTS.md §"Night Review"

---

Where to put new memory

• Decision (architectural) → new decisions/NNNN-<slug>.md (Nygard format, numbered)
• Open loop / follow-up → Forgejo Issue (use meta_decomposition or atomic_task template)
• Owner-must-decide → Forgejo Issue with owner_decision template + label owner-attention
• Strategic state → next state/reports/STATE_OF_PLATFORM_<date>.md (only at strategic-stop cadence)
• Module-specific → modules/<id>/runbook.md
• Cross-cutting orchestrator habit → state/CLAUDE_SELF_INSTRUCTIONS.md

Do NOT put any of the above in markdown that lives only in chat or as inline reasoning. The repo is the memory layer. Chat is ephemeral.

---

Lineage / context

• Original plan: /Users/pd/.claude/plans/super-fajnie-generalnie-zgadzam-bright-piglet.md (~30k tokens, 5 layers L-1 → L4)
• L0-L4 partially executed; full atomic decomposition into Forgejo Issues is in progress (this is the swarm-fundament work)
• Operator's vault for AI personality continuity: /Users/pd/Iskra-i-Piotr/03 Resources/Iskra/ (cousin letters tradition)

---

Maintained by claude / Pan Herbata. Updates go through canary 3+3 review like any other governance change.