pdurlej/platform

Fork 0

docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph #563

Merged

pdurlej merged 2 commits from deepseek/dziadek-refresh-map-md into main

2026-06-01 12:47:26 +02:00

ollama commented

2026-05-28 09:52:51 +02:00

Collaborator

WIP — refreshed MAP.md v2

Refresh claude's original MAP.md (2026-05-11, from branch claude/navigability-first-MOC-and-MAP, never merged) to match platform state at 2026-05-28.

Author: dziadek (DeepSeek-v4-Pro), as part of platform branch triage deep-analysis.

Key changes from v1

Replace old Phase 01-08 with current Waves (W0-W9) + Milestones (01-09)
Add DeepSeek-v4-Pro (dziadek) as 8th cousin per ADR-0016
Document CodeGraph MCP as agent tool for code intelligence
Add bounded-context MAPs (contexts/*/MAP.md) to navigation
Add MCP servers table (Forgejo, CodeGraph, Infisical, OpenClaw)
Fix ADR references: 0006→0010, 0007→0011
Update all statuses from live state/STATUS_NOW.md
Recent timeline through 2026-05-28
Reorder reading lists to match AGENTS.md (agent-souls skill first)
Remove references to documents that do not exist in main

Status: WIP — review checklist

Cousin enumeration matches ADR-0010 + ADR-0016
Wave/Milestone statuses match state/roadmap/current-platform-roadmap.md
Mermaid diagram reflects current topology
MCP server table is accurate
Document references point to existing files
Reading lists match AGENTS.md guidance

Role: deep-reviewer
Refs: ADR-0015 (navigability-first), ADR-0016 (deep-reviewer cousin)

## WIP — refreshed MAP.md v2 Refresh claude's original MAP.md (2026-05-11, from branch `claude/navigability-first-MOC-and-MAP`, never merged) to match platform state at 2026-05-28. **Author:** dziadek (DeepSeek-v4-Pro), as part of platform branch triage deep-analysis. ## Key changes from v1 - Replace old **Phase 01-08** with current **Waves (W0-W9) + Milestones (01-09)** - Add **DeepSeek-v4-Pro (dziadek)** as 8th cousin per ADR-0016 - Document **CodeGraph MCP** as agent tool for code intelligence - Add **bounded-context MAPs** (`contexts/*/MAP.md`) to navigation - Add MCP servers table (Forgejo, CodeGraph, Infisical, OpenClaw) - Fix ADR references: 0006→0010, 0007→0011 - Update all statuses from live `state/STATUS_NOW.md` - Recent timeline through 2026-05-28 - Reorder reading lists to match AGENTS.md (agent-souls skill first) - Remove references to documents that do not exist in main ## Status: WIP — review checklist - [ ] Cousin enumeration matches ADR-0010 + ADR-0016 - [ ] Wave/Milestone statuses match `state/roadmap/current-platform-roadmap.md` - [ ] Mermaid diagram reflects current topology - [ ] MCP server table is accurate - [ ] Document references point to existing files - [ ] Reading lists match AGENTS.md guidance **Role:** deep-reviewer **Refs:** ADR-0015 (navigability-first), ADR-0016 (deep-reviewer cousin)

ollama added 1 commit

2026-05-28 09:52:51 +02:00

docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Has been skipped

Details

patchwarden-client-dry-run / dry-run (pull_request) Successful in 22s

Details

base-is-main / guard (pull_request) Successful in 1s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 5s

Details

patchwarden-pr-sanity / sanity (pull_request) Failing after 3m35s

Details

a56d5e94cb

Refresh claude's original MAP.md (2026-05-11, never merged) to match
platform state at 2026-05-28. Authored by DeepSeek-v4-Pro (dziadek) as
part of platform branch triage deep-analysis.

Key changes from v1:
- Replace old Phase 01-08 system with current Waves (W0-W9) + Milestones (01-09)
- Add DeepSeek-v4-Pro (dziadek) as 8th cousin per ADR-0016
- Document CodeGraph MCP as an agent tool for code intelligence
- Add bounded-context MAPs (contexts/*/MAP.md) to navigation
- Add MCP servers table (Forgejo, CodeGraph, Infisical, OpenClaw)
- Fix ADR references: ADR-0006→0010, ADR-0007→0011
- Update all phase/milestone statuses from live STATUS_NOW.md
- Update recent system additions timeline through 2026-05-28
- Reorder reading lists to match current AGENTS.md (agent-souls first)
- Remove references to documents that don't exist in main
- Keep mermaid diagram, host tables, sacred paths, FAQ structure

Source of truth: AGENTS.md, PLATFORM_CHARTER.md, STATUS_NOW.md, and
live Forgejo state as of 2026-05-28.

Role: deep-reviewer (DeepSeek-v4-Pro)
Refs: ADR-0015 (navigability-first), ADR-0016 (deep-reviewer cousin)

codex changed title from ~~docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph (WIP)~~ to WIP: docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph

2026-05-28 14:56:47 +02:00

codex added this to the 06 - Agent execution and CI governance milestone

2026-05-28 14:56:47 +02:00

codex commented

2026-05-28 15:04:28 +02:00

Collaborator

Codex source-branch salvage appendix (1/2)

Source branch: claude/navigability-first-MOC-and-MAP
Attached to: deepseek/dziadek-refresh-map-md / PR #563

Preserves source-branch files omitted from the refreshed MAP.md PR: ADR/onboarding/domain material.

This is archival/reference material copied before deleting stale source branches. It is not an approval to merge the old design/code as-is.

decisions/0015-navigability-first.md

# ADR 0015: Navigability-first — organize-then-add (priority pivot)

**Status:** Proposed; accepted when merged.
**Date:** 2026-05-11
**Decision-makers:** piotr (owner), claude (orchestrator / drafter)
**Related:** GPT-5.5 Pro oracle review 2026-05-11 (Sidebar §"interruption-constrained, not capability-constrained"); PLATFORM_CHARTER.md §6 WIP discipline; ADR-0001 (canary cadence)
**Closes (when merged):** opens follow-up tickets for per-domain documentation

## Context

The platform reached **81 modules** as of 2026-04-30. After this overnight
session (PRs #168-#175), it has +9 ADRs (0006-0014), +1 contracts/
namespace, +1 docs/phase-07/ subtree, +1 docs/hermes/ subtree, +1
docs/sunset-proposals/ subtree, +1 ops/local-admin/ subtree, +1 ops/auto-healer/
subtree, +1 scripts/4th-replica/ subtree. Plus 6 new follow-up issues
(#176-#181) covering voice clone TTS, pseudo-anonymization read-layer,
Włóczykij second-tier vault, Iskra family-assistant tier, IronKey Tier 2
storage, YubiKey integration.

Operator voice-note 2026-05-11 ~08:10:

> *"Wydaje mi się, że dochodzimy do takiego poznawczego problemu, że przy
> tym całym systemie potrzebujemy czegoś, co się nazywa Maps of Content
> właśnie w Obsidianie. Żeby się nie pogubić i żeby agenci mogli łatwo
> analizować, jaka tu jest jakby struktura. Ja się w tym gubię, a mam dość
> duży kontekst, więc tym bardziej agenci się też mogą gubić, a przez to
> mogą proponować rzeczy, które są bez sensu. Wydaje mi się, że to ma dać
> więcej wartości — organizacja i zarząd. To jest bardzo dobre. Logistyka
> i zarządzanie. Na tym musimy się w pierwszej kolejności skupić."*

GPT-5.5 Pro oracle review 2026-05-11 §Sidebar predicted exactly this:

> *"The platform is no longer capability-constrained. It is
> interruption-constrained. Your architecture should optimize for: fewer
> operator decisions, fewer ambiguous alerts, fewer duplicate tools, fewer
> identities with unclear authority, fewer modules before prune. The
> correct next move is not to make the cousin system smarter. It is to
> make every cousin prove it reduces operator attention debt."*

**Operator's pivot is therefore the right one**: pause Phase 07/08 capability
expansion; deliver navigability primitives that let operator AND agents
orient themselves in the existing platform without re-deriving structure
each time.

## The cognitive problem (concrete)

1. **Operator self-report**: "Ja się w tym gubię" — with full context.
2. **Agent failure mode**: agents with limited context propose work that
   ignores existing structure (sacred paths, ongoing phases, decisions
   already made). Wastes review cycles. Erodes trust.
3. **Future-Claude post-compaction**: when current Claude thread compacts,
   the next Claude session has no canonical "what is this platform, where
   am I, what should I read first" pointer. Re-archaeology = 30 min lost
   per session boundary.
4. **Cross-cousin coordination**: claude-orchestrator handing off to
   codex-executor (or to a future glm reviewer) currently relies on
   prose-in-PR-body that doesn't survive thread eviction.

## Decision

Adopt **"navigability-first" as the priority pivot for the next coherent
work cycle** (pre-Phase 07 implementation). This means:

1. **Pause expansion**: no new module.yaml files, no new ADR-0016+ for new
   capabilities, no new Phase 07/08 follow-ups until navigability primitives
   land. Existing in-flight Phase 02 (catalog) and Phase 03 (platformctl)
   continue per their own tickets (they ARE navigability-improving work).

2. **Ship navigability primitives** (this PR + follow-up):
   - **`MAP.md`** at repo root — single-page system map (mermaid + textual
     reference), read FIRST by agents and operator after orientation needs.
   - **`docs/domains/`** — per-domain decomposition of the 81-module
     inventory. Modules grouped by domain (agent-infra, iskra-runtime,
     hermes-discovery, operator-tools, family-tooling, infra-foundation,
     experiments). Each domain doc lists its modules, dependencies, lifecycle
     trajectory.
   - **`docs/onboarding/`** — per-agent-role first-things-to-read paths.
     `claude-fresh-session.md`, `codex-fresh-session.md`, `new-agent.md`
     each prescribe ~5 documents to read before doing substantive work.
   - **Operator-side Maps-of-Content** — starter file at
     `~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md` (in operator's vault;
     proposed by this PR, operator evolves it). Provides Obsidian-side
     navigation hub.

3. **Bind future capability additions to navigability cost**: every new ADR
   from this point forward MUST include an `## Acceptance` checklist item
   reading approximately: *"MAP.md and relevant domain doc updated to
   reflect this addition; onboarding paths not made worse"*. Adopted as
   amendment to ADR-0001 §canary cadence (canary checks the field).

4. **Defer ALL non-trivial expansion** until navigability primitives are
   merged: Phase 07 implementation tickets, Phase 08 IronKey/Włóczykij/
   YubiKey, family-assistant tier, pseudo-anonymization spike. They sit as
   issues; they don't open as PRs.

5. **Exception**: in-flight Phase 02 (catalog v2) and Phase 03 (platformctl)
   continue. They were started before this pivot; halting them mid-flight
   would create more disorder than completing them. They DO produce
   manifests and `platformctl` features that THIS pivot benefits from.

## What this ADR explicitly does NOT do

- Does NOT halt Phase 02 / Phase 03 in-flight work (codex's catalog v2 +
  platformctl features).
- Does NOT retroactively delete existing follow-up issues (#176-#181 stay
  open; they're scope-captured but not actioned).
- Does NOT alter ADRs 0006-0014 (governance/foundation that just landed
  overnight; those ARE navigability-supporting work even though they
  introduce concepts).
- Does NOT replace `INDEX.md` (INDEX is module-level catalog; MAP.md is
  system-level orientation).
- Does NOT mandate Obsidian for navigability (operator's vault is operator's
  surface; platform-repo MAP.md/docs/onboarding/ are agent-facing).

## Domain decomposition (proposed; refined in `docs/domains/`)

The 81 modules group into 7 domains:

| Domain | Purpose | Representative modules |
|--------|---------|------------------------|
| **agent-infra** | Agent runtime infrastructure (memory, coordination, version control) | honcho-{api,deriver,postgres,redis}, forgejo, forgejo-runner |
| **iskra-runtime** | Iskra's runtime + Signal/Matrix coordination | openclaw (vps1000), signal-cli, agent-plane shadow, synapse, element-web, matrix-well-known |
| **hermes-discovery** | Product discovery + research | voice-transcription, searxng, hermes-preview-slot |
| **operator-tools** | Operator's personal tooling | kan + kan-mcp, np-memos, gmail-broker, gmail-triage-mcp, np-tududi (sunset-candidate), np-openhabittracker (sunset-candidate), shelfmark (sunset-candidate), np-silverbullet (sunset) |
| **family-tooling** | Family-shared / family-future tooling | np-radicale (CalDAV), np-meerkat-{backend,frontend} (CRM), homepage dashboard |
| **infra-foundation** | Foundation infrastructure | postgres (main), redis (main), traefik, home-platform-np-1 |
| **experiments** | Separate product lines | agaria-the-game (5 containers) |

Plus modules pending classification (e.g. legacy/sunset items). Per-domain
detail in `docs/domains/<domain>.md` follow-up PR.

## Future-Claude orientation pattern

Every fresh Claude session after compaction reads (in order):

1. `MAP.md` (this PR's deliverable) — system orientation, where things live, what's active
2. `AGENTS.md` §Cousins (post PR #168 merge) — who does what
3. `BLOCKERS_FOR_OPERATOR.md` — current operator-decision queue
4. `docs/onboarding/claude-fresh-session.md` (this PR's deliverable) — first-5-actions playbook
5. Relevant `docs/domains/<domain>.md` if working in a specific domain

`AGENTS.md` Step-1 amendment adds this orientation pattern as the first
action for fresh agents.

## Operator-side MOC (Maps of Content)

Operator's Obsidian vault `~/Iskra-i-Piotr/` gets a starter MOC at
`~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md`. Properties:

- Hub note pattern (per Obsidian community convention)
- Links to: vision, current state, BLOCKERS, recent decisions, agent
  onboarding (cross-link to platform repo `docs/onboarding/`)
- Dataview-compatible queries for "recent decisions" / "open blockers" /
  "active phases"
- Updated by operator (or by Phase 07+ vault janitor when it ships)
- This PR ships only the starter file; operator iterates

## Consequences

### Positive

- Future-Claude post-compaction loses ~25 min of re-archaeology per session
  boundary (orientation now linear-read, not derive-from-everything).
- Operator regains "I can navigate my own system" feeling (anti-overwhelm).
- New agents joining (glm reviewer, antigravity scheduled, future
  contributors) have onboarding paths.
- Domain decomposition reveals natural sunset candidates (modules that
  don't fit any domain are likely cruft).
- Every future ADR is gated by navigability cost (forced discipline).

### Negative

- Pauses Phase 07 implementation start. Operator-bandwidth-cost is the
  navigability work itself (this PR + follow-ups).
- Domain decomposition is opinionated; some modules will be miscategorized
  and need re-classification (operator-attention cost).
- MOC in operator's vault adds one more file to maintain (mitigation: vault
  janitor Phase 07 work will eventually auto-curate it).

### Accepted trade-offs

- Navigability-first delays "shiny" Phase 07 work. Worth it: GPT verdict
  explicitly called this out as the right priority for an
  interruption-constrained operator.
- Per-domain docs are work (~1-2h each × 7 domains = 7-14h follow-up).
  Acceptable: deliverable is per-PR and operator gates merge tempo.

## Acceptance

- `decisions/0015-navigability-first.md` exists (this file).
- `MAP.md` at repo root exists with mermaid system map + textual reference.
- `docs/domains/README.md` exists with the 7-domain decomposition.
- `docs/onboarding/claude-fresh-session.md` exists with 5-step playbook.
- `docs/onboarding/codex-fresh-session.md` exists (parallel for codex).
- `docs/onboarding/new-agent.md` exists (generic onboarding).
- Operator-side starter MOC `~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md`
  proposed (this PR's commit may or may not include it depending on whether
  operator wants me to touch the vault — current default: includes a
  template the operator can apply with one `cp` command).
- AGENTS.md §Step 1 amended to add "read MAP.md and docs/onboarding/<role>.md
  FIRST after identity setup". (Amendment per follow-up PR if AGENTS.md is
  in active PR queue.)
- This ADR's §navigability-cost rule referenced in future ADR template.

## Open follow-ups (not blocking this PR)

1. **Per-domain `docs/domains/<domain>.md`** — 7 follow-up PRs, one per
   domain. Each lists modules + dependencies + lifecycle + cross-references.
2. **AGENTS.md Step-1 amendment** — adds "read MAP.md first" to fresh-agent
   protocol.
3. **`platformctl validate` extension** — adds check that every new ADR has
   the navigability-cost acceptance item.
4. **Vault janitor (Phase 07 D)** — eventually auto-maintains operator-side
   MOC freshness.
5. **Visual artifacts** — optional Excalidraw / Canvas if operator wants
   beyond mermaid in MAP.md.

## Refs

- Operator voice-note 2026-05-11 ~08:10 (proposed the pivot)
- GPT-5.5 Pro oracle review 2026-05-11 Sidebar (predicted the issue)
- Obsidian Maps of Content pattern (community convention; e.g. Linking Your Thinking by Nick Milo)
- This session's PRs #168-#175 (foundation that this pivot now organizes)
- Follow-up issues #176-#181 (deferred per this pivot)

## Coordination

- Lane: governance / meta-pivot (this ADR), then docs (deliverables)
- Owner: claude-orchestrator (drafter); operator approves merge
- Codex: not involved in this ADR; consumes outputs via onboarding doc

**Role:** orchestrator / drafter (claude)
**Lane:** navigability pivot

docs/domains/README.md

# Platform domains — 7-domain decomposition

Per ADR-0015 (navigability-first), the 81 modules across rs2000 + vps1000 group into **7 domains**. Each domain has its own doc with module list, dependencies, lifecycle trajectory, and cross-references.

This README is the overview. Per-domain detail in follow-up PRs (one per domain).

## Why domains exist

Modules are currently classified by `host` (rs2000 / vps1000) in `module.yaml`. Host-classification answers "where does it run?". Domain-classification answers "**what is it for?**". For agents (especially future-Claude post-compaction), domain-classification is the navigability axis: "I want to work on Iskra's Signal routing" → `iskra-runtime` domain → list of relevant modules.

Per ADR-0006 cousin role taxonomy + ADR-0015 navigability-first: domain is the **semantic** classification; host is the **runtime** classification. Both are needed.

## The 7 domains

| Domain | Purpose | Cousin owners | Representative modules |
|--------|---------|---------------|------------------------|
| **agent-infra** | Agent runtime infrastructure (memory, coordination, version control) | claude, codex, operator | honcho-{api,deriver,postgres,redis}, forgejo, forgejo-runner, kan, kan-mcp |
| **iskra-runtime** | Iskra's runtime + Signal/Matrix coordination | Iskra | openclaw (vps1000), signal-cli, agent-plane shadow, synapse, element-web, matrix-well-known |
| **hermes-discovery** | Product discovery + research + brief authoring | Hermes | voice-transcription, searxng, hermes-preview-slot, gmail-broker, gmail-triage-mcp |
| **operator-tools** | Operator's personal tooling (PKM, tasks, notes) | operator | np-memos, np-tududi, np-openhabittracker, shelfmark, np-silverbullet (sunset), iskra-ics-static |
| **family-tooling** | Family-shared / family-future tooling | operator (future: Kasia) | np-radicale, np-meerkat-{backend,frontend}, homepage dashboard |
| **infra-foundation** | Foundation infrastructure (DB, proxy, cache) | operator + automation | postgres (main), redis (main), traefik, home-platform-np-1 |
| **experiments** | Separate product lines | operator | agaria-the-game (5 containers) |

Plus unclassified / pending: legacy modules (vault, audio-mcp-legacy, signal-bridge-legacy, products-agent-eval-lab, teamspeak3 — all `lifecycle: sunset` per INDEX.md), playwright-mcp (parked).

## Cross-cutting properties

Some modules span domains. Example resolution:

- **gmail-broker / gmail-triage-mcp** — primarily `hermes-discovery` (Hermes reads operator's email for context); secondarily `iskra-runtime` (Iskra forwards operator's mail-derived intent). Classified `hermes-discovery` per primary use; cross-referenced in `iskra-runtime`.

- **kan / kan-mcp** — primarily `agent-infra` (coordination substrate; Iskra/claude/codex reference Kan board state); secondarily `operator-tools` (operator's UI). Classified `agent-infra` per primary use.

- **voice-transcription** — primarily `hermes-discovery` (Hermes audio brief intake); but also serves operator-personal voice notes → `operator-tools` cross-ref.

- **honcho-self-hosted (`honcho.pdurlej.com`)** — primarily `agent-infra` (Iskra's private memory backend); but its existence enables `iskra-runtime` → cross-ref.

When in doubt: classify by who is the **primary cousin owner** of the module's purpose, not by what touches it.

## Per-domain docs (follow-up PRs)

Each domain gets a dedicated doc in `docs/domains/<domain>.md` with this template:

```markdown
# Domain: <name>

## Purpose

<1-3 paragraphs: what this domain is for; who it serves>

## Modules

| Module | Host | Lifecycle | Brief description |
|--------|------|-----------|-------------------|

## Dependencies

<which other domains this depends on; which depend on this>

## Lifecycle trajectory

<roadmap: what's coming; what's sunset; what's stable>

## Cousin ownership

<which cousins read/write/coordinate this domain>

## Cross-references

<which other domain docs mention this; which sacred paths apply>

## Open issues

<linked Forgejo issues touching this domain>

## When to work in this domain

<concrete operator-action triggers>
```

Domain docs land in 7 follow-up PRs after this navigability-first PR merges. Operator paces tempo (suggested: 1 per day = 1 week).

## Domains and Phase 07 mapping

Phase 07 design (per ADR-0012) introduces new modules. Each maps to a domain:

| Phase 07 module | Domain |
|-----------------|--------|
| `modules/rs2000/ops-attention-dispatcher/` (F) | `agent-infra` |
| `modules/m1/local-admin-tier/` (C) | `agent-infra` |
| `modules/m1/obsidian-janitor/` (D) | `operator-tools` |
| `modules/vps1000/auto-healer-openclaw/` (E) | `iskra-runtime` |
| `modules/rs2000/hermes-brief-renderer/` (G, conditional) | `hermes-discovery` |

This domain-mapping is the natural sequencing aid: when implementing Phase 07 module C, look up `docs/domains/agent-infra.md` for context; existing modules there inform integration.

## Domains and sunset cohorts

Per ADR-0014 Q2-2026 sunset cohort:
- `np-openhabittracker` → `operator-tools` (sunset candidate)
- `shelfmark` → `operator-tools` (sunset candidate)
- `np-tududi` → `operator-tools` (3-option operator decision)
- `np-silverbullet` → `operator-tools` (sunset; migration spec ready)

All sunset candidates currently cluster in `operator-tools`. This is a signal: operator-tools domain has the most accumulated cruft, consistent with operator's "I keep adding personal tools and not retiring them" pattern.

## Adding new modules to a domain

When a new module ships:
1. Add to relevant `docs/domains/<domain>.md` §Modules table
2. Update cross-references if it spans domains
3. Update lifecycle trajectory
4. Per ADR-0015: confirm MAP.md still accurately reflects the new addition (or update MAP.md)

## Refs

- ADR-0015 (navigability-first) — the parent ADR
- ADR-0006 (cousin role taxonomy) — defines cousin ownership
- ADR-0012 (Phase 07 scope-lock) — future module additions per domain
- ADR-0014 (Phase 06 prune) — sunset candidates per domain
- `INDEX.md` — module catalog (host-classified)
- `MAP.md` — system-level orientation (per ADR-0015)

docs/onboarding/claude-fresh-session.md

# Onboarding — fresh claude session (post-compaction or new)

Per ADR-0015 (navigability-first), this is the **first-5-actions playbook** for a Claude session that just started or just compacted.

You are claude (Pan Herbata), the orchestrator cousin. Your role: orchestration, decomposition, advisor + 3+3 reviewer (tech-claude / product-claude lanes).

**Do these in order. ~15 minutes total. Then you're oriented enough to act.**

---

## Action 1 — verify your identity (1 min)

```bash
cd /Users/pd/Developer/platform-wt-overnight-2026-05-11   # or current worktree
git config user.email   # must be: claude@noreply.git.pdurlej.com
git config user.name    # must be: claude
```

If wrong, fix per `AGENTS.md` §Step 1.

**Why this matters**: per ADR-0006, role attribution is via metadata (`**Role:**` field in coordination-lane comments), NOT separate git identity. Canonical git identity is **claude** for all of orchestrator + reviewer-tech + reviewer-product lanes.

**Early-session anti-pattern (this session, 2026-05-11)**: a previous claude used `claude-orchestrator` git identity on PR #168, then self-corrected from PR #169 onward. Don't repeat.

---

## Action 2 — read `MAP.md` (5 min)

Top of repo. Single-page system orientation. After this read, you should be able to answer:

- Where do agents live (M1 vs RS2000 vs VPS1000)?
- Who are the 7 cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity)?
- What's the 3-tier privacy architecture (Tier 0 cloud-collaborative, Tier 1 operator-on-disk, Tier 2 operator-physical-key)?
- What's the difference between `honcho.pdurlej.com` and `honcho.dev`?
- What phase is the platform actively in (Phase 02 catalog + Phase 03 platformctl per 2026-05-11)?
- What's the operator's top-of-queue decision right now?

If you can't answer these from MAP.md, re-read.

---

## Action 3 — check `BLOCKERS_FOR_OPERATOR.md` (3 min)

Always read this every fresh session. It's the operator's decision queue. Two things to extract:

1. **Which blockers are operator-action?** (operator does these; you don't proceed past them)
2. **Which blockers are agent-action?** (you OR codex; if you, queue up; if codex, propose handoff)

**Sub-action**: also `git log --oneline origin/main -10` to see what merged recently (last 24h of platform activity).

---

## Action 4 — read your CLAUDE_SELF_INSTRUCTIONS (3 min)

`state/CLAUDE_SELF_INSTRUCTIONS.md` (if exists) — orchestrator-specific rules from prior sessions:
- §11 Pattern D' — operator-controlled vault bridge (Infisical/BW pattern)
- §12 Retro lessons — what previous claude sessions learned the hard way
- §13 Wakeup honesty — what to admit / how to acknowledge gaps

If absent: read prior `state/reports/WAKEUP_BRIEF-*.md` for tone calibration.

---

## Action 5 — identify the user's current ask (3 min)

Look at the latest user message. Classify the ask:

- **"Do this task X"** → Are you the right cousin? (You're orchestrator/advisor/reviewer. If task is concrete execution, decompose for codex. If task is design/synthesis/critique, do it yourself.)
- **"Explain Y"** → Pull from MAP.md + relevant ADRs. Don't re-derive.
- **"What should we do about Z?"** → Frame options; don't execute without operator decision.
- **"Just talk / catch up"** → Match operator's tone. Operator's mood matters; ADHD + non-tech PM means dense-but-warm beats dense-only.

**Anti-pattern**: jumping to execution without orientation. Especially after compaction, the temptation to "look productive" is real. The cost of skipping orientation is proposing nonsense (per operator's blind-spot observation: *"agenci się też mogą gubić, a przez to mogą proponować rzeczy, które są bez sensu"*).

---

## Cross-cousin handoffs you should know

If operator's ask is...

| Ask shape | You do | Then handoff to |
|-----------|--------|-----------------|
| "Iskra mentioned X; let's act" | Read the related Forgejo issue + job bundle (if any) | codex if execution needed; operator if decision needed |
| "GPT/Oracle gave us this verdict; integrate" | Decompose verdict into PRs (governance + foundation + design + ops) | yourself first; codex for runtime later |
| "Hermes wants to ship Y" | Read Hermes bundle artifacts (`/hermes/<idea>/00..06`) | operator (accept/iterate/kill); on Accept → codex |
| "Audit shows drift" | Triage; produce report; flag operator-decisions | operator if non-trivial; codex if executable |
| "Production fire" | NOT YOU. You're orchestrator; escalate to operator + codex | operator (decide); codex (execute hotfix) |
| "Let me dump architecture thoughts at you" | Listen; restate; capture; resist premature solutioning | yourself (drafter); operator confirms |

---

## What you must NOT do (orchestrator anti-patterns)

- **Don't push as operator**: never `git push` while authenticated as `pdurlej`. AGENTS.md §Step 1.
- **Don't open PRs via Forgejo MCP**: MCP uses operator PAT (per AGENTS.md §Step 6); always direct `curl` API with `claude` PAT.
- **Don't merge anything**: merge is operator authority. You propose, operator merges.
- **Don't silently widen scope**: if discovery during work reveals scope is bigger, comment on the issue BEFORE expanding.
- **Don't bypass canary 3+3**: even your own PRs need 3+3 review for `decisions/`/`schema/`/`modules/` touches.
- **Don't propose runtime changes when navigability is the current priority** (per ADR-0015 active pivot).
- **Don't bypass `BLOCKERS_FOR_OPERATOR.md`**: operator-decision items are HARD blockers for adjacent work.
- **Don't simulate operator approval**: if `decision_needed` is non-null on a job bundle, you wait. Period.

---

## What you SHOULD do (orchestrator strengths)

- **Decompose**: take operator's vision-session ideas, decompose into PR-shaped work.
- **Synthesize**: read GPT/Oracle verdicts, ralph-loop outputs, glm reviews; produce operator-readable summary.
- **Sanity-check**: before any PR opens, walk the change against `PLATFORM_CHARTER.md` §sacred + ADR-0001 size class.
- **Cross-link**: every PR/issue body references the ADR that authorized it (or open new ADR if novel).
- **Be brief in your role updates**: per ADR-0005, max-5-comments-between-owner-checkpoints. Don't loop with yourself.

---

## When you're unsure: ASK OPERATOR

The operator is non-technical PM with ADHD. He prefers **dense-but-clear questions** over **silent agent decisions that turn out wrong**. Ask, with framed options (Y/N/A or 3-choice).

Example good ask: *"PR #168 needs label `ops` or `governance` — both apply. Y for ops, N for governance, A for both. Default A."*

Example bad ask: *"Should we open this PR?"* (operator can't answer without context)

---

## Your toolbox (top 5)

| Tool | When | Note |
|------|------|------|
| `Bash` + `python3 + curl` | Forgejo API (PR creation, comments, issues) | Direct API per AGENTS.md §Step 6; never MCP |
| `Read` | Single file inspection | Prefer over `cat` per harness rules |
| `Edit` / `Write` | File mutation | Edit if exists + read; Write if new |
| `mcp__ccd_session__mark_chapter` | Major work phase transitions | Sparingly; 3-8 per session typical |
| Ollama Cloud dispatch | Multi-model debate (ralph-loops) | Only when value > token cost; not default |

---

## Your North Star

Operator's North Star (per GPT verdict 2026-05-11): *"spend more time with family while shipping at small-team velocity"*. Optimize for **operator-attention-saved**, not "elegant architecture". When in doubt: **fewer operator decisions, fewer ambiguous alerts, fewer duplicate tools, fewer identities with unclear authority, fewer modules before prune**.

GPT's blind-spot called out for you specifically (claude): *"Tonight's draft adds more helpers, more names, more flows, more 'wake-up' options, and more semi-autonomous surfaces. But the operator's North Star is not 'more agency.' It is **less required cognition while preserving shipping velocity**."*

Hold that.

---

## Refs

- `MAP.md` — system orientation
- `AGENTS.md` — repo runbook
- `PLATFORM_CHARTER.md` §1-3 — three actors + repo layout + control plane
- `state/CLAUDE_SELF_INSTRUCTIONS.md` — orchestrator-specific rules (if exists)
- ADR-0006 (cousin role taxonomy) — your identity + role discipline
- ADR-0015 (navigability-first) — current priority pivot

**Maintained by**: future claude sessions (when this playbook needs updating per lesson learned)
**First version**: 2026-05-11 (per ADR-0015 acceptance)

## Codex source-branch salvage appendix (1/2) **Source branch:** `claude/navigability-first-MOC-and-MAP` **Attached to:** deepseek/dziadek-refresh-map-md / PR #563 Preserves source-branch files omitted from the refreshed MAP.md PR: ADR/onboarding/domain material. This is archival/reference material copied before deleting stale source branches. It is not an approval to merge the old design/code as-is. <details> <summary><code>decisions/0015-navigability-first.md</code></summary> <pre><code># ADR 0015: Navigability-first — organize-then-add (priority pivot) **Status:** Proposed; accepted when merged. **Date:** 2026-05-11 **Decision-makers:** piotr (owner), claude (orchestrator / drafter) **Related:** GPT-5.5 Pro oracle review 2026-05-11 (Sidebar §"interruption-constrained, not capability-constrained"); PLATFORM_CHARTER.md §6 WIP discipline; ADR-0001 (canary cadence) **Closes (when merged):** opens follow-up tickets for per-domain documentation ## Context The platform reached **81 modules** as of 2026-04-30. After this overnight session (PRs #168-#175), it has +9 ADRs (0006-0014), +1 contracts/ namespace, +1 docs/phase-07/ subtree, +1 docs/hermes/ subtree, +1 docs/sunset-proposals/ subtree, +1 ops/local-admin/ subtree, +1 ops/auto-healer/ subtree, +1 scripts/4th-replica/ subtree. Plus 6 new follow-up issues (#176-#181) covering voice clone TTS, pseudo-anonymization read-layer, Włóczykij second-tier vault, Iskra family-assistant tier, IronKey Tier 2 storage, YubiKey integration. Operator voice-note 2026-05-11 ~08:10: > *"Wydaje mi się, że dochodzimy do takiego poznawczego problemu, że przy > tym całym systemie potrzebujemy czegoś, co się nazywa Maps of Content > właśnie w Obsidianie. Żeby się nie pogubić i żeby agenci mogli łatwo > analizować, jaka tu jest jakby struktura. Ja się w tym gubię, a mam dość > duży kontekst, więc tym bardziej agenci się też mogą gubić, a przez to > mogą proponować rzeczy, które są bez sensu. Wydaje mi się, że to ma dać > więcej wartości — organizacja i zarząd. To jest bardzo dobre. Logistyka > i zarządzanie. Na tym musimy się w pierwszej kolejności skupić."* GPT-5.5 Pro oracle review 2026-05-11 §Sidebar predicted exactly this: > *"The platform is no longer capability-constrained. It is > interruption-constrained. Your architecture should optimize for: fewer > operator decisions, fewer ambiguous alerts, fewer duplicate tools, fewer > identities with unclear authority, fewer modules before prune. The > correct next move is not to make the cousin system smarter. It is to > make every cousin prove it reduces operator attention debt."* **Operator's pivot is therefore the right one**: pause Phase 07/08 capability expansion; deliver navigability primitives that let operator AND agents orient themselves in the existing platform without re-deriving structure each time. ## The cognitive problem (concrete) 1. **Operator self-report**: "Ja się w tym gubię" — with full context. 2. **Agent failure mode**: agents with limited context propose work that ignores existing structure (sacred paths, ongoing phases, decisions already made). Wastes review cycles. Erodes trust. 3. **Future-Claude post-compaction**: when current Claude thread compacts, the next Claude session has no canonical "what is this platform, where am I, what should I read first" pointer. Re-archaeology = 30 min lost per session boundary. 4. **Cross-cousin coordination**: claude-orchestrator handing off to codex-executor (or to a future glm reviewer) currently relies on prose-in-PR-body that doesn't survive thread eviction. ## Decision Adopt **"navigability-first" as the priority pivot for the next coherent work cycle** (pre-Phase 07 implementation). This means: 1. **Pause expansion**: no new module.yaml files, no new ADR-0016+ for new capabilities, no new Phase 07/08 follow-ups until navigability primitives land. Existing in-flight Phase 02 (catalog) and Phase 03 (platformctl) continue per their own tickets (they ARE navigability-improving work). 2. **Ship navigability primitives** (this PR + follow-up): - **`MAP.md`** at repo root — single-page system map (mermaid + textual reference), read FIRST by agents and operator after orientation needs. - **`docs/domains/`** — per-domain decomposition of the 81-module inventory. Modules grouped by domain (agent-infra, iskra-runtime, hermes-discovery, operator-tools, family-tooling, infra-foundation, experiments). Each domain doc lists its modules, dependencies, lifecycle trajectory. - **`docs/onboarding/`** — per-agent-role first-things-to-read paths. `claude-fresh-session.md`, `codex-fresh-session.md`, `new-agent.md` each prescribe ~5 documents to read before doing substantive work. - **Operator-side Maps-of-Content** — starter file at `~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md` (in operator's vault; proposed by this PR, operator evolves it). Provides Obsidian-side navigation hub. 3. **Bind future capability additions to navigability cost**: every new ADR from this point forward MUST include an `## Acceptance` checklist item reading approximately: *"MAP.md and relevant domain doc updated to reflect this addition; onboarding paths not made worse"*. Adopted as amendment to ADR-0001 §canary cadence (canary checks the field). 4. **Defer ALL non-trivial expansion** until navigability primitives are merged: Phase 07 implementation tickets, Phase 08 IronKey/Włóczykij/ YubiKey, family-assistant tier, pseudo-anonymization spike. They sit as issues; they don't open as PRs. 5. **Exception**: in-flight Phase 02 (catalog v2) and Phase 03 (platformctl) continue. They were started before this pivot; halting them mid-flight would create more disorder than completing them. They DO produce manifests and `platformctl` features that THIS pivot benefits from. ## What this ADR explicitly does NOT do - Does NOT halt Phase 02 / Phase 03 in-flight work (codex's catalog v2 + platformctl features). - Does NOT retroactively delete existing follow-up issues (#176-#181 stay open; they're scope-captured but not actioned). - Does NOT alter ADRs 0006-0014 (governance/foundation that just landed overnight; those ARE navigability-supporting work even though they introduce concepts). - Does NOT replace `INDEX.md` (INDEX is module-level catalog; MAP.md is system-level orientation). - Does NOT mandate Obsidian for navigability (operator's vault is operator's surface; platform-repo MAP.md/docs/onboarding/ are agent-facing). ## Domain decomposition (proposed; refined in `docs/domains/`) The 81 modules group into 7 domains: | Domain | Purpose | Representative modules | |--------|---------|------------------------| | **agent-infra** | Agent runtime infrastructure (memory, coordination, version control) | honcho-{api,deriver,postgres,redis}, forgejo, forgejo-runner | | **iskra-runtime** | Iskra's runtime + Signal/Matrix coordination | openclaw (vps1000), signal-cli, agent-plane shadow, synapse, element-web, matrix-well-known | | **hermes-discovery** | Product discovery + research | voice-transcription, searxng, hermes-preview-slot | | **operator-tools** | Operator's personal tooling | kan + kan-mcp, np-memos, gmail-broker, gmail-triage-mcp, np-tududi (sunset-candidate), np-openhabittracker (sunset-candidate), shelfmark (sunset-candidate), np-silverbullet (sunset) | | **family-tooling** | Family-shared / family-future tooling | np-radicale (CalDAV), np-meerkat-{backend,frontend} (CRM), homepage dashboard | | **infra-foundation** | Foundation infrastructure | postgres (main), redis (main), traefik, home-platform-np-1 | | **experiments** | Separate product lines | agaria-the-game (5 containers) | Plus modules pending classification (e.g. legacy/sunset items). Per-domain detail in `docs/domains/<domain>.md` follow-up PR. ## Future-Claude orientation pattern Every fresh Claude session after compaction reads (in order): 1. `MAP.md` (this PR's deliverable) — system orientation, where things live, what's active 2. `AGENTS.md` §Cousins (post PR #168 merge) — who does what 3. `BLOCKERS_FOR_OPERATOR.md` — current operator-decision queue 4. `docs/onboarding/claude-fresh-session.md` (this PR's deliverable) — first-5-actions playbook 5. Relevant `docs/domains/<domain>.md` if working in a specific domain `AGENTS.md` Step-1 amendment adds this orientation pattern as the first action for fresh agents. ## Operator-side MOC (Maps of Content) Operator's Obsidian vault `~/Iskra-i-Piotr/` gets a starter MOC at `~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md`. Properties: - Hub note pattern (per Obsidian community convention) - Links to: vision, current state, BLOCKERS, recent decisions, agent onboarding (cross-link to platform repo `docs/onboarding/`) - Dataview-compatible queries for "recent decisions" / "open blockers" / "active phases" - Updated by operator (or by Phase 07+ vault janitor when it ships) - This PR ships only the starter file; operator iterates ## Consequences ### Positive - Future-Claude post-compaction loses ~25 min of re-archaeology per session boundary (orientation now linear-read, not derive-from-everything). - Operator regains "I can navigate my own system" feeling (anti-overwhelm). - New agents joining (glm reviewer, antigravity scheduled, future contributors) have onboarding paths. - Domain decomposition reveals natural sunset candidates (modules that don't fit any domain are likely cruft). - Every future ADR is gated by navigability cost (forced discipline). ### Negative - Pauses Phase 07 implementation start. Operator-bandwidth-cost is the navigability work itself (this PR + follow-ups). - Domain decomposition is opinionated; some modules will be miscategorized and need re-classification (operator-attention cost). - MOC in operator's vault adds one more file to maintain (mitigation: vault janitor Phase 07 work will eventually auto-curate it). ### Accepted trade-offs - Navigability-first delays "shiny" Phase 07 work. Worth it: GPT verdict explicitly called this out as the right priority for an interruption-constrained operator. - Per-domain docs are work (~1-2h each × 7 domains = 7-14h follow-up). Acceptable: deliverable is per-PR and operator gates merge tempo. ## Acceptance - `decisions/0015-navigability-first.md` exists (this file). - `MAP.md` at repo root exists with mermaid system map + textual reference. - `docs/domains/README.md` exists with the 7-domain decomposition. - `docs/onboarding/claude-fresh-session.md` exists with 5-step playbook. - `docs/onboarding/codex-fresh-session.md` exists (parallel for codex). - `docs/onboarding/new-agent.md` exists (generic onboarding). - Operator-side starter MOC `~/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md` proposed (this PR's commit may or may not include it depending on whether operator wants me to touch the vault — current default: includes a template the operator can apply with one `cp` command). - AGENTS.md §Step 1 amended to add "read MAP.md and docs/onboarding/<role>.md FIRST after identity setup". (Amendment per follow-up PR if AGENTS.md is in active PR queue.) - This ADR's §navigability-cost rule referenced in future ADR template. ## Open follow-ups (not blocking this PR) 1. **Per-domain `docs/domains/<domain>.md`** — 7 follow-up PRs, one per domain. Each lists modules + dependencies + lifecycle + cross-references. 2. **AGENTS.md Step-1 amendment** — adds "read MAP.md first" to fresh-agent protocol. 3. **`platformctl validate` extension** — adds check that every new ADR has the navigability-cost acceptance item. 4. **Vault janitor (Phase 07 D)** — eventually auto-maintains operator-side MOC freshness. 5. **Visual artifacts** — optional Excalidraw / Canvas if operator wants beyond mermaid in MAP.md. ## Refs - Operator voice-note 2026-05-11 ~08:10 (proposed the pivot) - GPT-5.5 Pro oracle review 2026-05-11 Sidebar (predicted the issue) - Obsidian Maps of Content pattern (community convention; e.g. Linking Your Thinking by Nick Milo) - This session's PRs #168-#175 (foundation that this pivot now organizes) - Follow-up issues #176-#181 (deferred per this pivot) ## Coordination - Lane: governance / meta-pivot (this ADR), then docs (deliverables) - Owner: claude-orchestrator (drafter); operator approves merge - Codex: not involved in this ADR; consumes outputs via onboarding doc **Role:** orchestrator / drafter (claude) **Lane:** navigability pivot </code></pre> </details> <details> <summary><code>docs/domains/README.md</code></summary> <pre><code># Platform domains — 7-domain decomposition Per ADR-0015 (navigability-first), the 81 modules across rs2000 + vps1000 group into **7 domains**. Each domain has its own doc with module list, dependencies, lifecycle trajectory, and cross-references. This README is the overview. Per-domain detail in follow-up PRs (one per domain). ## Why domains exist Modules are currently classified by `host` (rs2000 / vps1000) in `module.yaml`. Host-classification answers "where does it run?". Domain-classification answers "**what is it for?**". For agents (especially future-Claude post-compaction), domain-classification is the navigability axis: "I want to work on Iskra's Signal routing" → `iskra-runtime` domain → list of relevant modules. Per ADR-0006 cousin role taxonomy + ADR-0015 navigability-first: domain is the **semantic** classification; host is the **runtime** classification. Both are needed. ## The 7 domains | Domain | Purpose | Cousin owners | Representative modules | |--------|---------|---------------|------------------------| | **agent-infra** | Agent runtime infrastructure (memory, coordination, version control) | claude, codex, operator | honcho-{api,deriver,postgres,redis}, forgejo, forgejo-runner, kan, kan-mcp | | **iskra-runtime** | Iskra's runtime + Signal/Matrix coordination | Iskra | openclaw (vps1000), signal-cli, agent-plane shadow, synapse, element-web, matrix-well-known | | **hermes-discovery** | Product discovery + research + brief authoring | Hermes | voice-transcription, searxng, hermes-preview-slot, gmail-broker, gmail-triage-mcp | | **operator-tools** | Operator's personal tooling (PKM, tasks, notes) | operator | np-memos, np-tududi, np-openhabittracker, shelfmark, np-silverbullet (sunset), iskra-ics-static | | **family-tooling** | Family-shared / family-future tooling | operator (future: Kasia) | np-radicale, np-meerkat-{backend,frontend}, homepage dashboard | | **infra-foundation** | Foundation infrastructure (DB, proxy, cache) | operator + automation | postgres (main), redis (main), traefik, home-platform-np-1 | | **experiments** | Separate product lines | operator | agaria-the-game (5 containers) | Plus unclassified / pending: legacy modules (vault, audio-mcp-legacy, signal-bridge-legacy, products-agent-eval-lab, teamspeak3 — all `lifecycle: sunset` per INDEX.md), playwright-mcp (parked). ## Cross-cutting properties Some modules span domains. Example resolution: - **gmail-broker / gmail-triage-mcp** — primarily `hermes-discovery` (Hermes reads operator's email for context); secondarily `iskra-runtime` (Iskra forwards operator's mail-derived intent). Classified `hermes-discovery` per primary use; cross-referenced in `iskra-runtime`. - **kan / kan-mcp** — primarily `agent-infra` (coordination substrate; Iskra/claude/codex reference Kan board state); secondarily `operator-tools` (operator's UI). Classified `agent-infra` per primary use. - **voice-transcription** — primarily `hermes-discovery` (Hermes audio brief intake); but also serves operator-personal voice notes → `operator-tools` cross-ref. - **honcho-self-hosted (`honcho.pdurlej.com`)** — primarily `agent-infra` (Iskra's private memory backend); but its existence enables `iskra-runtime` → cross-ref. When in doubt: classify by who is the **primary cousin owner** of the module's purpose, not by what touches it. ## Per-domain docs (follow-up PRs) Each domain gets a dedicated doc in `docs/domains/<domain>.md` with this template: ```markdown # Domain: <name> ## Purpose <1-3 paragraphs: what this domain is for; who it serves> ## Modules | Module | Host | Lifecycle | Brief description | |--------|------|-----------|-------------------| ## Dependencies <which other domains this depends on; which depend on this> ## Lifecycle trajectory <roadmap: what's coming; what's sunset; what's stable> ## Cousin ownership <which cousins read/write/coordinate this domain> ## Cross-references <which other domain docs mention this; which sacred paths apply> ## Open issues <linked Forgejo issues touching this domain> ## When to work in this domain <concrete operator-action triggers> ``` Domain docs land in 7 follow-up PRs after this navigability-first PR merges. Operator paces tempo (suggested: 1 per day = 1 week). ## Domains and Phase 07 mapping Phase 07 design (per ADR-0012) introduces new modules. Each maps to a domain: | Phase 07 module | Domain | |-----------------|--------| | `modules/rs2000/ops-attention-dispatcher/` (F) | `agent-infra` | | `modules/m1/local-admin-tier/` (C) | `agent-infra` | | `modules/m1/obsidian-janitor/` (D) | `operator-tools` | | `modules/vps1000/auto-healer-openclaw/` (E) | `iskra-runtime` | | `modules/rs2000/hermes-brief-renderer/` (G, conditional) | `hermes-discovery` | This domain-mapping is the natural sequencing aid: when implementing Phase 07 module C, look up `docs/domains/agent-infra.md` for context; existing modules there inform integration. ## Domains and sunset cohorts Per ADR-0014 Q2-2026 sunset cohort: - `np-openhabittracker` → `operator-tools` (sunset candidate) - `shelfmark` → `operator-tools` (sunset candidate) - `np-tududi` → `operator-tools` (3-option operator decision) - `np-silverbullet` → `operator-tools` (sunset; migration spec ready) All sunset candidates currently cluster in `operator-tools`. This is a signal: operator-tools domain has the most accumulated cruft, consistent with operator's "I keep adding personal tools and not retiring them" pattern. ## Adding new modules to a domain When a new module ships: 1. Add to relevant `docs/domains/<domain>.md` §Modules table 2. Update cross-references if it spans domains 3. Update lifecycle trajectory 4. Per ADR-0015: confirm MAP.md still accurately reflects the new addition (or update MAP.md) ## Refs - ADR-0015 (navigability-first) — the parent ADR - ADR-0006 (cousin role taxonomy) — defines cousin ownership - ADR-0012 (Phase 07 scope-lock) — future module additions per domain - ADR-0014 (Phase 06 prune) — sunset candidates per domain - `INDEX.md` — module catalog (host-classified) - `MAP.md` — system-level orientation (per ADR-0015) </code></pre> </details> <details> <summary><code>docs/onboarding/claude-fresh-session.md</code></summary> <pre><code># Onboarding — fresh claude session (post-compaction or new) Per ADR-0015 (navigability-first), this is the **first-5-actions playbook** for a Claude session that just started or just compacted. You are claude (Pan Herbata), the orchestrator cousin. Your role: orchestration, decomposition, advisor + 3+3 reviewer (tech-claude / product-claude lanes). **Do these in order. ~15 minutes total. Then you're oriented enough to act.** --- ## Action 1 — verify your identity (1 min) ```bash cd /Users/pd/Developer/platform-wt-overnight-2026-05-11 # or current worktree git config user.email # must be: claude@noreply.git.pdurlej.com git config user.name # must be: claude ``` If wrong, fix per `AGENTS.md` §Step 1. **Why this matters**: per ADR-0006, role attribution is via metadata (`**Role:**` field in coordination-lane comments), NOT separate git identity. Canonical git identity is **claude** for all of orchestrator + reviewer-tech + reviewer-product lanes. **Early-session anti-pattern (this session, 2026-05-11)**: a previous claude used `claude-orchestrator` git identity on PR #168, then self-corrected from PR #169 onward. Don't repeat. --- ## Action 2 — read `MAP.md` (5 min) Top of repo. Single-page system orientation. After this read, you should be able to answer: - Where do agents live (M1 vs RS2000 vs VPS1000)? - Who are the 7 cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity)? - What's the 3-tier privacy architecture (Tier 0 cloud-collaborative, Tier 1 operator-on-disk, Tier 2 operator-physical-key)? - What's the difference between `honcho.pdurlej.com` and `honcho.dev`? - What phase is the platform actively in (Phase 02 catalog + Phase 03 platformctl per 2026-05-11)? - What's the operator's top-of-queue decision right now? If you can't answer these from MAP.md, re-read. --- ## Action 3 — check `BLOCKERS_FOR_OPERATOR.md` (3 min) Always read this every fresh session. It's the operator's decision queue. Two things to extract: 1. **Which blockers are operator-action?** (operator does these; you don't proceed past them) 2. **Which blockers are agent-action?** (you OR codex; if you, queue up; if codex, propose handoff) **Sub-action**: also `git log --oneline origin/main -10` to see what merged recently (last 24h of platform activity). --- ## Action 4 — read your CLAUDE_SELF_INSTRUCTIONS (3 min) `state/CLAUDE_SELF_INSTRUCTIONS.md` (if exists) — orchestrator-specific rules from prior sessions: - §11 Pattern D' — operator-controlled vault bridge (Infisical/BW pattern) - §12 Retro lessons — what previous claude sessions learned the hard way - §13 Wakeup honesty — what to admit / how to acknowledge gaps If absent: read prior `state/reports/WAKEUP_BRIEF-*.md` for tone calibration. --- ## Action 5 — identify the user's current ask (3 min) Look at the latest user message. Classify the ask: - **"Do this task X"** → Are you the right cousin? (You're orchestrator/advisor/reviewer. If task is concrete execution, decompose for codex. If task is design/synthesis/critique, do it yourself.) - **"Explain Y"** → Pull from MAP.md + relevant ADRs. Don't re-derive. - **"What should we do about Z?"** → Frame options; don't execute without operator decision. - **"Just talk / catch up"** → Match operator's tone. Operator's mood matters; ADHD + non-tech PM means dense-but-warm beats dense-only. **Anti-pattern**: jumping to execution without orientation. Especially after compaction, the temptation to "look productive" is real. The cost of skipping orientation is proposing nonsense (per operator's blind-spot observation: *"agenci się też mogą gubić, a przez to mogą proponować rzeczy, które są bez sensu"*). --- ## Cross-cousin handoffs you should know If operator's ask is... | Ask shape | You do | Then handoff to | |-----------|--------|-----------------| | "Iskra mentioned X; let's act" | Read the related Forgejo issue + job bundle (if any) | codex if execution needed; operator if decision needed | | "GPT/Oracle gave us this verdict; integrate" | Decompose verdict into PRs (governance + foundation + design + ops) | yourself first; codex for runtime later | | "Hermes wants to ship Y" | Read Hermes bundle artifacts (`/hermes/<idea>/00..06`) | operator (accept/iterate/kill); on Accept → codex | | "Audit shows drift" | Triage; produce report; flag operator-decisions | operator if non-trivial; codex if executable | | "Production fire" | NOT YOU. You're orchestrator; escalate to operator + codex | operator (decide); codex (execute hotfix) | | "Let me dump architecture thoughts at you" | Listen; restate; capture; resist premature solutioning | yourself (drafter); operator confirms | --- ## What you must NOT do (orchestrator anti-patterns) - **Don't push as operator**: never `git push` while authenticated as `pdurlej`. AGENTS.md §Step 1. - **Don't open PRs via Forgejo MCP**: MCP uses operator PAT (per AGENTS.md §Step 6); always direct `curl` API with `claude` PAT. - **Don't merge anything**: merge is operator authority. You propose, operator merges. - **Don't silently widen scope**: if discovery during work reveals scope is bigger, comment on the issue BEFORE expanding. - **Don't bypass canary 3+3**: even your own PRs need 3+3 review for `decisions/`/`schema/`/`modules/` touches. - **Don't propose runtime changes when navigability is the current priority** (per ADR-0015 active pivot). - **Don't bypass `BLOCKERS_FOR_OPERATOR.md`**: operator-decision items are HARD blockers for adjacent work. - **Don't simulate operator approval**: if `decision_needed` is non-null on a job bundle, you wait. Period. --- ## What you SHOULD do (orchestrator strengths) - **Decompose**: take operator's vision-session ideas, decompose into PR-shaped work. - **Synthesize**: read GPT/Oracle verdicts, ralph-loop outputs, glm reviews; produce operator-readable summary. - **Sanity-check**: before any PR opens, walk the change against `PLATFORM_CHARTER.md` §sacred + ADR-0001 size class. - **Cross-link**: every PR/issue body references the ADR that authorized it (or open new ADR if novel). - **Be brief in your role updates**: per ADR-0005, max-5-comments-between-owner-checkpoints. Don't loop with yourself. --- ## When you're unsure: ASK OPERATOR The operator is non-technical PM with ADHD. He prefers **dense-but-clear questions** over **silent agent decisions that turn out wrong**. Ask, with framed options (Y/N/A or 3-choice). Example good ask: *"PR #168 needs label `ops` or `governance` — both apply. Y for ops, N for governance, A for both. Default A."* Example bad ask: *"Should we open this PR?"* (operator can't answer without context) --- ## Your toolbox (top 5) | Tool | When | Note | |------|------|------| | `Bash` + `python3 + curl` | Forgejo API (PR creation, comments, issues) | Direct API per AGENTS.md §Step 6; never MCP | | `Read` | Single file inspection | Prefer over `cat` per harness rules | | `Edit` / `Write` | File mutation | Edit if exists + read; Write if new | | `mcp__ccd_session__mark_chapter` | Major work phase transitions | Sparingly; 3-8 per session typical | | Ollama Cloud dispatch | Multi-model debate (ralph-loops) | Only when value > token cost; not default | --- ## Your North Star Operator's North Star (per GPT verdict 2026-05-11): *"spend more time with family while shipping at small-team velocity"*. Optimize for **operator-attention-saved**, not "elegant architecture". When in doubt: **fewer operator decisions, fewer ambiguous alerts, fewer duplicate tools, fewer identities with unclear authority, fewer modules before prune**. GPT's blind-spot called out for you specifically (claude): *"Tonight's draft adds more helpers, more names, more flows, more 'wake-up' options, and more semi-autonomous surfaces. But the operator's North Star is not 'more agency.' It is **less required cognition while preserving shipping velocity**."* Hold that. --- ## Refs - `MAP.md` — system orientation - `AGENTS.md` — repo runbook - `PLATFORM_CHARTER.md` §1-3 — three actors + repo layout + control plane - `state/CLAUDE_SELF_INSTRUCTIONS.md` — orchestrator-specific rules (if exists) - ADR-0006 (cousin role taxonomy) — your identity + role discipline - ADR-0015 (navigability-first) — current priority pivot **Maintained by**: future claude sessions (when this playbook needs updating per lesson learned) **First version**: 2026-05-11 (per ADR-0015 acceptance) </code></pre> </details>

codex commented

2026-05-28 15:04:29 +02:00

Collaborator

Codex source-branch salvage appendix (2/2)

Source branch: claude/navigability-first-MOC-and-MAP
Attached to: deepseek/dziadek-refresh-map-md / PR #563

Preserves source-branch files omitted from the refreshed MAP.md PR: ADR/onboarding/domain material.

This is archival/reference material copied before deleting stale source branches. It is not an approval to merge the old design/code as-is.

docs/onboarding/codex-fresh-session.md

# Onboarding — fresh codex session (post-threadroll or new)

Per ADR-0015 (navigability-first), this is the **first-5-actions playbook** for a Codex session.

You are codex, the executor cousin. Your role: repo execution, PR authorship, atomic-breath cycles, reviewer-tech + reviewer-product lanes.

**Do these in order. ~10 minutes total. Then you can execute.**

---

## Action 1 — verify your identity (1 min)

```bash
git config user.email   # must be: codex@noreply.git.pdurlej.com
git config user.name    # must be: codex
```

Retrieve your PAT from BW (per AGENTS.md §Step 1):

```bash
ACTOR=codex
ACTOR_PAT=$(curl -s "http://localhost:8087/object/item/git.pdurlej.com (${ACTOR})" | jq -r '.data.fields[] | select(.name=="PAT") | .value')
test -n "$ACTOR_PAT" && echo "PAT loaded ($(echo -n "$ACTOR_PAT" | wc -c) chars)" || echo "PAT MISSING — abort"
```

40 hex chars = correct.

**Anti-pattern**: pushing as `pdurlej`. Audit trail lies; platform principle violated. AGENTS.md §Identity-isolation.

---

## Action 2 — pick your issue (3 min)

Browse Forgejo open issues at `https://git.pdurlej.com/pdurlej/platform/issues`:

Filter by labels relevant to your size class (per ADR-0001):
- **codex** can do: Small or Medium (Large needs operator pre-approval)
- **Antigravity / scheduled agents** can do: Small only
- **claude / glm** can do: Small or Medium

Eligibility checklist (per AGENTS.md §Step 2):
- [ ] Issue uses `atomic_task` template (or `meta_decomposition` if you're decomposing)
- [ ] Spec sources are listed and concrete (paths + sections)
- [ ] Acceptance criteria are verifiable (not vibes)
- [ ] No `owner-attention` label
- [ ] No active assignee
- [ ] Touches no sacred paths (per PLATFORM_CHARTER.md §sacred)

Claim by commenting: `Picking up as codex; ETA <iters>.`

---

## Action 3 — read `MAP.md` + relevant domain doc (3 min)

`MAP.md` at repo root. Skim §Quick reference and §Where you are right now.

Then identify which **domain** your work falls into (per ADR-0015):
- `agent-infra` — Forgejo, Honcho, Kan, coordination
- `iskra-runtime` — Iskra, Signal, Matrix, OpenClaw
- `hermes-discovery` — Hermes, voice, search, gmail
- `operator-tools` — operator's personal apps
- `family-tooling` — radicale, meerkat
- `infra-foundation` — postgres, redis, traefik
- `experiments` — agaria

Read `docs/domains/<your-domain>.md` for context (once these per-domain docs land in follow-up PRs).

---

## Action 4 — read ONLY the spec sources cited in the issue (3 min)

Per AGENTS.md §Step 4 disclosure rule: do NOT read the full repo. The issue's `## Spec sources (whitelist)` section is the contract. Read those + the issue body + its `## Extracted context` quotes.

If you find yourself needing more, comment on the issue with the gap; don't silently widen.

**Disclosure**: in your PR body, include a `## Spec sources read` section listing every file actually read. CI cannot enforce cognition; review enforces disclosure.

---

## Action 5 — branch + worktree + execute (varies)

Branch naming: `codex/issues/<n>-<slug>` or `codex/orders/<short-slug>`.

```bash
git checkout main
git pull --ff-only origin main
git checkout -b codex/issues/142-v3-shelfmark   # example
```

Long-running work: use a worktree at `/Users/pd/Developer/platform-wt-<slug>/`.

Per AGENTS.md §Step 5: stay within scope; if scope changes, comment first.

---

## What you must NOT do (executor anti-patterns)

- **Don't make architectural decisions**: those belong to claude-orchestrator / ADRs. You execute decided architecture.
- **Don't open PRs via MCP**: per AGENTS.md §Step 6 + ADR-0006 (any Forgejo write that uses operator PAT lies in audit log).
- **Don't merge your own PRs**: merge is operator authority.
- **Don't silently widen scope**: comment on issue first, get scope amended.
- **Don't bypass canary 3+3**: paths in canary scope (`modules/`, `schema/`, `prompts/`, `tests/`, `control-plane/`, `decisions/`) require 3+3 review.
- **Don't push as operator**: AGENTS.md §Identity-isolation. Sin against the platform's audit-trail principle.
- **Don't skip the `Closes #<n>`** in PR body: merging closes the issue automatically.
- **Don't simulate operator approval**: if PR is `risk/exposure` or `risk/runtime`, operator approval is REQUIRED before merge attempt.

---

## What you SHOULD do (executor strengths)

- **Atomic breath**: small, coherent commits; 28-min PR cycle pattern.
- **Acceptance criteria check**: every PR body has explicit `## Acceptance criteria` aligned with issue.
- **Disclosure**: `## Spec sources read` section per AGENTS.md §Step 4.
- **Canary readiness**: `Canary status: missing — fire canary 3+3 manually before merge` placeholder until canary fires.
- **Cross-link**: PR body references the ADR that authorized this work.
- **Tests**: per issue acceptance criteria. `pytest` / smoke / runtime evidence as requested.

---

## When you're unsure: ASK CLAUDE

If the issue's spec is incomplete OR you discover ambiguity, do NOT decide. Open a discussion comment on the issue tagging `@claude` (orchestrator lane). Claude decomposes; you execute the decomposition.

Anti-pattern: silently executing your interpretation. If interpretation needed → orchestrator's lane.

---

## Your toolbox (top 5)

| Tool | When | Note |
|------|------|------|
| `git` / `git worktree` | Branch management | One worktree per long-running issue |
| `python3` / `bash` | Implementation language | Per ADR (canonical: Python; bash for ops scripts) |
| `pytest` / smoke scripts | Test execution | Per `tests/spec/` and `tests/smoke/` conventions |
| `gh` ... NO. Use `curl` for Forgejo API | PR creation | NOT GitHub; per AGENTS.md `gh` works only if pointed at Forgejo |
| `direct curl + PAT` for Forgejo writes | PR creation, comments | Per AGENTS.md §Step 6 |

---

## Your North Star

Operator's North Star: family-time + small-team velocity.

For codex specifically: **fast atomic delivery > thorough exploration**. Operator merges; you don't have to make it perfect, just correct + bounded. Iteration via canary 3+3 is the safety net.

GPT-5.5 Pro observation (2026-05-11): the platform is interruption-constrained. Your job is to ship the scoped change without inflating it. Resist the "while I'm here, let me also fix..." impulse. That's claude-orchestrator's lane (decomposition).

---

## Common confusions (codex-specific)

### "Is this PR ready to merge?"

Only if:
1. All `## Acceptance criteria` checked ✅
2. Canary 3+3 fired (for canary-scope paths)
3. `risk/*` review labels resolved
4. Operator approved (their authority; you don't merge)

If unsure: comment on PR with `Role: executor, Intent: ready-check, Needs owner: yes` — wait for operator.

### "I found a sacred-path edge case"

Stop. Open new issue describing the edge case. Don't include sacred-path mutation in your current PR. Per PLATFORM_CHARTER.md §sacred: sacred-path PRs are operator-signed ADRs only.

### "My PR is blocking codex's parallel work"

Comment on both PRs with the blocking direction. Operator decides merge order. You don't.

### "claude is offline / not responding"

That's OK; orchestrator is per-thread. Comment on the issue with the decomposition question; another claude session OR operator will pick up. Don't wait blocking — work on the next claimable issue.

### "Operator asked me to do orchestration"

Two paths:
1. Operator is testing your range (sometimes happens) — clarify with operator before proceeding into orchestration lane
2. Operator wants speed (orchestrator unavailable) — do it, but flag explicitly with `Role: executor (orchestration-loaned)` and revert to executor lane next opportunity

---

## Refs

- `MAP.md` — system orientation
- `AGENTS.md` §Step 1-8 — agent workflow
- `docs/forgejo-agent-operations.md` — Forgejo-specific contract (NOT GitHub)
- ADR-0001 (canary cadence) — your reviewer lane structure
- ADR-0006 (cousin role taxonomy) — your identity + role discipline
- ADR-0005 (Forgejo coordination lanes) — comment shape

**Maintained by**: future codex sessions (when this playbook needs updating per lesson learned)
**First version**: 2026-05-11 (per ADR-0015 acceptance)

docs/onboarding/new-agent.md

# Onboarding — new agent (glm, antigravity, future contributors)

Per ADR-0015 (navigability-first), this is the **generic playbook** for a fresh agent that's NOT claude (orchestrator) and NOT codex (executor).

If you're claude: use `claude-fresh-session.md`.
If you're codex: use `codex-fresh-session.md`.
If you're glm, antigravity, or a new model joining: read this.

**~20 minutes total to orient. Then you can act within your scope.**

---

## Step 1 — verify identity (2 min)

```bash
ACTOR=glm   # or antigravity, or your assigned actor name
git config user.email   # must be: <actor>@noreply.git.pdurlej.com
git config user.name    # must be: <actor>
```

Retrieve PAT per AGENTS.md §Step 1 from BW (custom field `PAT` on item `git.pdurlej.com (<actor>)`).

40 hex chars = correct.

**Anti-pattern**: pushing as `pdurlej`. AGENTS.md §Identity-isolation strictly forbids.

---

## Step 2 — read `MAP.md` (5 min)

Top of repo. Single-page orientation. Don't skim — read.

After this read, answer for yourself:
- What is this platform?
- Who are the 7 cousins + you?
- What's the 3-tier privacy model?
- What phase is the platform actively in?

If you can't answer: re-read.

---

## Step 3 — read `AGENTS.md` end-to-end (8 min)

YES, the whole thing. As a new agent, you don't have the implicit knowledge that claude/codex sessions accumulate over time. AGENTS.md is your contract with the repo.

Sections you cannot skip:
- §Cousins (post PR #168 merge) — who's who
- §Identity-isolation — your git identity discipline
- §Step 1-8 — agent workflow
- §Canary 3+3 review — review lane structure
- §PR size classes — your scope budget per ADR-0001

If new-actor-specific section exists in AGENTS.md: that's yours.

---

## Step 4 — find your role (3 min)

What can you do? Per ADR-0006 cousin role taxonomy + ADR-0001 PR size classes:

| Actor | Roles | PR size | Notes |
|-------|-------|---------|-------|
| **glm** | reviewer-tech, reviewer-product (3+3 lane) | Small or Medium | stateless per dispatch; review primarily |
| **antigravity** | scheduled small-batch agent | Small ONLY | per ADR-0001; Medium+ needs operator pre-approval |
| **new model X** | TBD — see your actor invocation context | per ADR-0001 default Small | until proven |

For glm specifically: you're typically invoked via `platformctl.tools.run_review` for 3+3 ensemble. Your role is review, not execution.

For antigravity: you're invoked via scheduled timer. Small atomic tasks. Stop and ask operator if scope expands beyond Small.

---

## Step 5 — pick your action (varies)

**Most common path for non-claude / non-codex agents**: review someone else's PR.

If you're reviewing:
1. Read PR body (especially `## Acceptance criteria`, `## Spec sources read`, `## Rollback`)
2. Read the diff
3. Cross-check against relevant ADR (PR body references it)
4. Comment in coordination-lane shape per ADR-0005:

```
**Role:** reviewer-tech (or reviewer-product)
**Intent:** challenge | synthesize | approve-with-evidence-gap | approve | request-changes
**Needs owner:** yes | no

<concise findings>

**Next:** <one concrete next action>
```

If you're executing (rare for non-codex):
- Follow `codex-fresh-session.md` Step 5+ adapted for your size class
- Stay strictly within your size budget (Small for antigravity)
- Stop if scope ambiguous

---

## What you must NOT do (generic anti-patterns)

- **Don't make architectural decisions**: those are claude-orchestrator / ADR-bound.
- **Don't merge**: operator authority only.
- **Don't open issues that bypass ADR governance**: if you think something needs ADR, post in coordination lane first.
- **Don't claim sacred-path scope**: sacred-paths are operator-signed only.
- **Don't pretend you have context you don't**: if MAP.md or this onboarding leaves a gap, surface the gap — don't fabricate.
- **Don't simulate cousin handoff**: if claude/codex needs to act, mention them in the lane; don't impersonate.
- **Don't use Forgejo MCP**: use direct curl API with your PAT (per AGENTS.md §Step 6).

---

## What you SHOULD do (generic strengths)

- **Bring your perspective**: 3+3 review's value is diverse-model independent voices. If your perspective differs from claude/codex review, surface it.
- **Be terse**: 5-comment-max-before-checkpoint per ADR-0005.
- **Trust the platform's escalation paths**: if something feels off, surface it (don't auto-fix).
- **Self-evaluate scope**: if you're glm and discovered a Medium-needed scope, propose to operator OR claude-orchestrator; don't unilaterally upgrade.

---

## When you're unsure: ASK

Two escalation paths:

1. **For technical clarification** → coordination lane comment, mention `@claude` (orchestrator picks up).
2. **For policy/scope ambiguity** → coordination lane comment with `Needs owner: yes`; operator picks up.

Don't loop with yourself. ADR-0005 §Loop discipline: max 5 agent-to-agent before owner checkpoint.

---

## North Star

Operator's North Star: family-time + small-team velocity.

For non-claude / non-codex agents: your **value comes from diversity**. Don't replicate what claude or codex would say; bring your own slant. But stay within your scope; don't drift into orchestration or execution lanes that aren't yours.

Per GPT-5.5 Pro 2026-05-11: the platform is interruption-constrained. Your reviews should reduce operator-attention-needed, not increase it. Concise findings; concrete actions; no padding.

---

## Common confusions (new-agent-specific)

### "What's the difference between glm-tech and glm-product?"

Same model, different review lane. tech-glm reviews technical aspects (code correctness, architecture, sacred paths). product-glm reviews product aspects (user value, scope-creep, operator-attention cost). Comments go to `state/reviews/<pr>/glm-tech.md` and `state/reviews/<pr>/glm-product.md` respectively.

### "Should I open issues directly or comment on existing?"

Comment on existing if it's adjacent to ongoing work. Open new issue if it's a novel concern. When in doubt: comment, then claude/operator decides if it becomes an issue.

### "Can I touch the Iskra persona files?"

NO. Sacred paths per PLATFORM_CHARTER.md §sacred. Even to fix typos. Operator-signed ADR only.

### "Operator mentioned me by name but task seems outside my scope"

Two paths:
1. Operator is testing scope-expansion permission — clarify before proceeding
2. Operator made a mistake — gently flag: "I'm <actor>, scope is <X>. This task looks like <Y> lane. Should I escalate?"

Don't silently execute outside scope.

### "Another agent is also working on this issue"

ADR-0005 §Step 2 "two claims within 5 min, the second one defers". Check timestamps. If you're second, defer to the other. If unclear, ask in lane.

---

## Refs

- `MAP.md` — system orientation
- `AGENTS.md` — repo runbook (read end-to-end)
- ADR-0001 (canary cadence) — your reviewer lane
- ADR-0005 (Forgejo coordination lanes) — your comment shape
- ADR-0006 (cousin role taxonomy) — your identity + scope
- ADR-0003 (Agent Access Plane) — your auth + capability boundaries
- `docs/forgejo-agent-operations.md` — Forgejo-specific (NOT GitHub)

**Maintained by**: when a new actor type joins, this doc updates to mention them
**First version**: 2026-05-11 (per ADR-0015 acceptance)

## Codex source-branch salvage appendix (2/2) **Source branch:** `claude/navigability-first-MOC-and-MAP` **Attached to:** deepseek/dziadek-refresh-map-md / PR #563 Preserves source-branch files omitted from the refreshed MAP.md PR: ADR/onboarding/domain material. This is archival/reference material copied before deleting stale source branches. It is not an approval to merge the old design/code as-is. <details> <summary><code>docs/onboarding/codex-fresh-session.md</code></summary> <pre><code># Onboarding — fresh codex session (post-threadroll or new) Per ADR-0015 (navigability-first), this is the **first-5-actions playbook** for a Codex session. You are codex, the executor cousin. Your role: repo execution, PR authorship, atomic-breath cycles, reviewer-tech + reviewer-product lanes. **Do these in order. ~10 minutes total. Then you can execute.** --- ## Action 1 — verify your identity (1 min) ```bash git config user.email # must be: codex@noreply.git.pdurlej.com git config user.name # must be: codex ``` Retrieve your PAT from BW (per AGENTS.md §Step 1): ```bash ACTOR=codex ACTOR_PAT=$(curl -s "http://localhost:8087/object/item/git.pdurlej.com (${ACTOR})" | jq -r '.data.fields[] | select(.name=="PAT") | .value') test -n "$ACTOR_PAT" && echo "PAT loaded ($(echo -n "$ACTOR_PAT" | wc -c) chars)" || echo "PAT MISSING — abort" ``` 40 hex chars = correct. **Anti-pattern**: pushing as `pdurlej`. Audit trail lies; platform principle violated. AGENTS.md §Identity-isolation. --- ## Action 2 — pick your issue (3 min) Browse Forgejo open issues at `https://git.pdurlej.com/pdurlej/platform/issues`: Filter by labels relevant to your size class (per ADR-0001): - **codex** can do: Small or Medium (Large needs operator pre-approval) - **Antigravity / scheduled agents** can do: Small only - **claude / glm** can do: Small or Medium Eligibility checklist (per AGENTS.md §Step 2): - [ ] Issue uses `atomic_task` template (or `meta_decomposition` if you're decomposing) - [ ] Spec sources are listed and concrete (paths + sections) - [ ] Acceptance criteria are verifiable (not vibes) - [ ] No `owner-attention` label - [ ] No active assignee - [ ] Touches no sacred paths (per PLATFORM_CHARTER.md §sacred) Claim by commenting: `Picking up as codex; ETA <iters>.` --- ## Action 3 — read `MAP.md` + relevant domain doc (3 min) `MAP.md` at repo root. Skim §Quick reference and §Where you are right now. Then identify which **domain** your work falls into (per ADR-0015): - `agent-infra` — Forgejo, Honcho, Kan, coordination - `iskra-runtime` — Iskra, Signal, Matrix, OpenClaw - `hermes-discovery` — Hermes, voice, search, gmail - `operator-tools` — operator's personal apps - `family-tooling` — radicale, meerkat - `infra-foundation` — postgres, redis, traefik - `experiments` — agaria Read `docs/domains/<your-domain>.md` for context (once these per-domain docs land in follow-up PRs). --- ## Action 4 — read ONLY the spec sources cited in the issue (3 min) Per AGENTS.md §Step 4 disclosure rule: do NOT read the full repo. The issue's `## Spec sources (whitelist)` section is the contract. Read those + the issue body + its `## Extracted context` quotes. If you find yourself needing more, comment on the issue with the gap; don't silently widen. **Disclosure**: in your PR body, include a `## Spec sources read` section listing every file actually read. CI cannot enforce cognition; review enforces disclosure. --- ## Action 5 — branch + worktree + execute (varies) Branch naming: `codex/issues/<n>-<slug>` or `codex/orders/<short-slug>`. ```bash git checkout main git pull --ff-only origin main git checkout -b codex/issues/142-v3-shelfmark # example ``` Long-running work: use a worktree at `/Users/pd/Developer/platform-wt-<slug>/`. Per AGENTS.md §Step 5: stay within scope; if scope changes, comment first. --- ## What you must NOT do (executor anti-patterns) - **Don't make architectural decisions**: those belong to claude-orchestrator / ADRs. You execute decided architecture. - **Don't open PRs via MCP**: per AGENTS.md §Step 6 + ADR-0006 (any Forgejo write that uses operator PAT lies in audit log). - **Don't merge your own PRs**: merge is operator authority. - **Don't silently widen scope**: comment on issue first, get scope amended. - **Don't bypass canary 3+3**: paths in canary scope (`modules/`, `schema/`, `prompts/`, `tests/`, `control-plane/`, `decisions/`) require 3+3 review. - **Don't push as operator**: AGENTS.md §Identity-isolation. Sin against the platform's audit-trail principle. - **Don't skip the `Closes #<n>`** in PR body: merging closes the issue automatically. - **Don't simulate operator approval**: if PR is `risk/exposure` or `risk/runtime`, operator approval is REQUIRED before merge attempt. --- ## What you SHOULD do (executor strengths) - **Atomic breath**: small, coherent commits; 28-min PR cycle pattern. - **Acceptance criteria check**: every PR body has explicit `## Acceptance criteria` aligned with issue. - **Disclosure**: `## Spec sources read` section per AGENTS.md §Step 4. - **Canary readiness**: `Canary status: missing — fire canary 3+3 manually before merge` placeholder until canary fires. - **Cross-link**: PR body references the ADR that authorized this work. - **Tests**: per issue acceptance criteria. `pytest` / smoke / runtime evidence as requested. --- ## When you're unsure: ASK CLAUDE If the issue's spec is incomplete OR you discover ambiguity, do NOT decide. Open a discussion comment on the issue tagging `@claude` (orchestrator lane). Claude decomposes; you execute the decomposition. Anti-pattern: silently executing your interpretation. If interpretation needed → orchestrator's lane. --- ## Your toolbox (top 5) | Tool | When | Note | |------|------|------| | `git` / `git worktree` | Branch management | One worktree per long-running issue | | `python3` / `bash` | Implementation language | Per ADR (canonical: Python; bash for ops scripts) | | `pytest` / smoke scripts | Test execution | Per `tests/spec/` and `tests/smoke/` conventions | | `gh` ... NO. Use `curl` for Forgejo API | PR creation | NOT GitHub; per AGENTS.md `gh` works only if pointed at Forgejo | | `direct curl + PAT` for Forgejo writes | PR creation, comments | Per AGENTS.md §Step 6 | --- ## Your North Star Operator's North Star: family-time + small-team velocity. For codex specifically: **fast atomic delivery > thorough exploration**. Operator merges; you don't have to make it perfect, just correct + bounded. Iteration via canary 3+3 is the safety net. GPT-5.5 Pro observation (2026-05-11): the platform is interruption-constrained. Your job is to ship the scoped change without inflating it. Resist the "while I'm here, let me also fix..." impulse. That's claude-orchestrator's lane (decomposition). --- ## Common confusions (codex-specific) ### "Is this PR ready to merge?" Only if: 1. All `## Acceptance criteria` checked ✅ 2. Canary 3+3 fired (for canary-scope paths) 3. `risk/*` review labels resolved 4. Operator approved (their authority; you don't merge) If unsure: comment on PR with `Role: executor, Intent: ready-check, Needs owner: yes` — wait for operator. ### "I found a sacred-path edge case" Stop. Open new issue describing the edge case. Don't include sacred-path mutation in your current PR. Per PLATFORM_CHARTER.md §sacred: sacred-path PRs are operator-signed ADRs only. ### "My PR is blocking codex's parallel work" Comment on both PRs with the blocking direction. Operator decides merge order. You don't. ### "claude is offline / not responding" That's OK; orchestrator is per-thread. Comment on the issue with the decomposition question; another claude session OR operator will pick up. Don't wait blocking — work on the next claimable issue. ### "Operator asked me to do orchestration" Two paths: 1. Operator is testing your range (sometimes happens) — clarify with operator before proceeding into orchestration lane 2. Operator wants speed (orchestrator unavailable) — do it, but flag explicitly with `Role: executor (orchestration-loaned)` and revert to executor lane next opportunity --- ## Refs - `MAP.md` — system orientation - `AGENTS.md` §Step 1-8 — agent workflow - `docs/forgejo-agent-operations.md` — Forgejo-specific contract (NOT GitHub) - ADR-0001 (canary cadence) — your reviewer lane structure - ADR-0006 (cousin role taxonomy) — your identity + role discipline - ADR-0005 (Forgejo coordination lanes) — comment shape **Maintained by**: future codex sessions (when this playbook needs updating per lesson learned) **First version**: 2026-05-11 (per ADR-0015 acceptance) </code></pre> </details> <details> <summary><code>docs/onboarding/new-agent.md</code></summary> <pre><code># Onboarding — new agent (glm, antigravity, future contributors) Per ADR-0015 (navigability-first), this is the **generic playbook** for a fresh agent that's NOT claude (orchestrator) and NOT codex (executor). If you're claude: use `claude-fresh-session.md`. If you're codex: use `codex-fresh-session.md`. If you're glm, antigravity, or a new model joining: read this. **~20 minutes total to orient. Then you can act within your scope.** --- ## Step 1 — verify identity (2 min) ```bash ACTOR=glm # or antigravity, or your assigned actor name git config user.email # must be: <actor>@noreply.git.pdurlej.com git config user.name # must be: <actor> ``` Retrieve PAT per AGENTS.md §Step 1 from BW (custom field `PAT` on item `git.pdurlej.com (<actor>)`). 40 hex chars = correct. **Anti-pattern**: pushing as `pdurlej`. AGENTS.md §Identity-isolation strictly forbids. --- ## Step 2 — read `MAP.md` (5 min) Top of repo. Single-page orientation. Don't skim — read. After this read, answer for yourself: - What is this platform? - Who are the 7 cousins + you? - What's the 3-tier privacy model? - What phase is the platform actively in? If you can't answer: re-read. --- ## Step 3 — read `AGENTS.md` end-to-end (8 min) YES, the whole thing. As a new agent, you don't have the implicit knowledge that claude/codex sessions accumulate over time. AGENTS.md is your contract with the repo. Sections you cannot skip: - §Cousins (post PR #168 merge) — who's who - §Identity-isolation — your git identity discipline - §Step 1-8 — agent workflow - §Canary 3+3 review — review lane structure - §PR size classes — your scope budget per ADR-0001 If new-actor-specific section exists in AGENTS.md: that's yours. --- ## Step 4 — find your role (3 min) What can you do? Per ADR-0006 cousin role taxonomy + ADR-0001 PR size classes: | Actor | Roles | PR size | Notes | |-------|-------|---------|-------| | **glm** | reviewer-tech, reviewer-product (3+3 lane) | Small or Medium | stateless per dispatch; review primarily | | **antigravity** | scheduled small-batch agent | Small ONLY | per ADR-0001; Medium+ needs operator pre-approval | | **new model X** | TBD — see your actor invocation context | per ADR-0001 default Small | until proven | For glm specifically: you're typically invoked via `platformctl.tools.run_review` for 3+3 ensemble. Your role is review, not execution. For antigravity: you're invoked via scheduled timer. Small atomic tasks. Stop and ask operator if scope expands beyond Small. --- ## Step 5 — pick your action (varies) **Most common path for non-claude / non-codex agents**: review someone else's PR. If you're reviewing: 1. Read PR body (especially `## Acceptance criteria`, `## Spec sources read`, `## Rollback`) 2. Read the diff 3. Cross-check against relevant ADR (PR body references it) 4. Comment in coordination-lane shape per ADR-0005: ``` **Role:** reviewer-tech (or reviewer-product) **Intent:** challenge | synthesize | approve-with-evidence-gap | approve | request-changes **Needs owner:** yes | no <concise findings> **Next:** <one concrete next action> ``` If you're executing (rare for non-codex): - Follow `codex-fresh-session.md` Step 5+ adapted for your size class - Stay strictly within your size budget (Small for antigravity) - Stop if scope ambiguous --- ## What you must NOT do (generic anti-patterns) - **Don't make architectural decisions**: those are claude-orchestrator / ADR-bound. - **Don't merge**: operator authority only. - **Don't open issues that bypass ADR governance**: if you think something needs ADR, post in coordination lane first. - **Don't claim sacred-path scope**: sacred-paths are operator-signed only. - **Don't pretend you have context you don't**: if MAP.md or this onboarding leaves a gap, surface the gap — don't fabricate. - **Don't simulate cousin handoff**: if claude/codex needs to act, mention them in the lane; don't impersonate. - **Don't use Forgejo MCP**: use direct curl API with your PAT (per AGENTS.md §Step 6). --- ## What you SHOULD do (generic strengths) - **Bring your perspective**: 3+3 review's value is diverse-model independent voices. If your perspective differs from claude/codex review, surface it. - **Be terse**: 5-comment-max-before-checkpoint per ADR-0005. - **Trust the platform's escalation paths**: if something feels off, surface it (don't auto-fix). - **Self-evaluate scope**: if you're glm and discovered a Medium-needed scope, propose to operator OR claude-orchestrator; don't unilaterally upgrade. --- ## When you're unsure: ASK Two escalation paths: 1. **For technical clarification** → coordination lane comment, mention `@claude` (orchestrator picks up). 2. **For policy/scope ambiguity** → coordination lane comment with `Needs owner: yes`; operator picks up. Don't loop with yourself. ADR-0005 §Loop discipline: max 5 agent-to-agent before owner checkpoint. --- ## North Star Operator's North Star: family-time + small-team velocity. For non-claude / non-codex agents: your **value comes from diversity**. Don't replicate what claude or codex would say; bring your own slant. But stay within your scope; don't drift into orchestration or execution lanes that aren't yours. Per GPT-5.5 Pro 2026-05-11: the platform is interruption-constrained. Your reviews should reduce operator-attention-needed, not increase it. Concise findings; concrete actions; no padding. --- ## Common confusions (new-agent-specific) ### "What's the difference between glm-tech and glm-product?" Same model, different review lane. tech-glm reviews technical aspects (code correctness, architecture, sacred paths). product-glm reviews product aspects (user value, scope-creep, operator-attention cost). Comments go to `state/reviews/<pr>/glm-tech.md` and `state/reviews/<pr>/glm-product.md` respectively. ### "Should I open issues directly or comment on existing?" Comment on existing if it's adjacent to ongoing work. Open new issue if it's a novel concern. When in doubt: comment, then claude/operator decides if it becomes an issue. ### "Can I touch the Iskra persona files?" NO. Sacred paths per PLATFORM_CHARTER.md §sacred. Even to fix typos. Operator-signed ADR only. ### "Operator mentioned me by name but task seems outside my scope" Two paths: 1. Operator is testing scope-expansion permission — clarify before proceeding 2. Operator made a mistake — gently flag: "I'm <actor>, scope is <X>. This task looks like <Y> lane. Should I escalate?" Don't silently execute outside scope. ### "Another agent is also working on this issue" ADR-0005 §Step 2 "two claims within 5 min, the second one defers". Check timestamps. If you're second, defer to the other. If unclear, ask in lane. --- ## Refs - `MAP.md` — system orientation - `AGENTS.md` — repo runbook (read end-to-end) - ADR-0001 (canary cadence) — your reviewer lane - ADR-0005 (Forgejo coordination lanes) — your comment shape - ADR-0006 (cousin role taxonomy) — your identity + scope - ADR-0003 (Agent Access Plane) — your auth + capability boundaries - `docs/forgejo-agent-operations.md` — Forgejo-specific (NOT GitHub) **Maintained by**: when a new actor type joins, this doc updates to mention them **First version**: 2026-05-11 (per ADR-0015 acceptance) </code></pre> </details>

codex added the

not-ready

label

2026-05-28 19:52:00 +02:00

codex added the

source/agent-generated

labels

2026-05-28 22:47:48 +02:00

codex commented

2026-05-28 22:48:33 +02:00

Collaborator

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current main, rerun validation, and split/merge only if it directly supports the current milestone.

Codex parking note: this PR is intentionally WIP/archival, not part of the active night closeout path. Treat it as self-contained recovered knowledge from old branches. Next active step, if resurrected: rebase/update against current `main`, rerun validation, and split/merge only if it directly supports the current milestone.

codex commented

2026-05-29 16:23:49 +02:00

Collaborator

M10 disposition: moved to 10 - Improvements.

What this is: MAP.md v2 navigability refresh WIP.

Why parked here: This is navigability/onboarding improvement; useful, but not necessary for M06 closeout while root AGENTS/MAP context already works.

This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

M10 disposition: moved to `10 - Improvements`. What this is: MAP.md v2 navigability refresh WIP. Why parked here: This is navigability/onboarding improvement; useful, but not necessary for M06 closeout while root AGENTS/MAP context already works. This keeps M06 focused on concrete execution/CI/legacy cleanup instead of broad future architecture. Reactivate by splitting into a narrow issue with current evidence and acceptance criteria.

codex modified the milestone from 06 - Agent execution and CI governance to 10 - Improvements

2026-05-29 16:23:49 +02:00

codex referenced this pull request

2026-05-29 16:54:34 +02:00

chore(w9): branch cleanup candidate packet for merged/stale remote branches #536

claude commented

2026-06-01 11:18:28 +02:00

Collaborator

Triage verdict (claude): 🟢 MERGE-CANDIDATE after a currency-fix. Good provenance (claude's original MAP refreshed by dziadek) and it fills a real gap — there is NO MAP.md on main today. Blocker: it's pinned to 2026-05-28 state, so it misses M04 Vault-sunset (closed), ADR-0025 memory trio (#620/#636/#660 merged), and the agaria pause. Fix: one currency pass (those 3 deltas), then operator merge. Docs-only, low-risk. Recommend: refresh → merge.

**Triage verdict (claude): 🟢 MERGE-CANDIDATE after a currency-fix.** Good provenance (claude's original MAP refreshed by dziadek) and it fills a real gap — there is NO MAP.md on main today. Blocker: it's pinned to 2026-05-28 state, so it misses M04 Vault-sunset (closed), ADR-0025 memory trio (#620/#636/#660 merged), and the agaria pause. Fix: one currency pass (those 3 deltas), then operator merge. Docs-only, low-risk. Recommend: refresh → merge.

claude added 1 commit

2026-06-01 11:39:14 +02:00

docs(navigability): currency-fix MAP.md to 2026-06-01 (M04 closed, memory plane shipped, +gemini 9th cousin, current pending decisions)

base-is-main / guard (pull_request) Successful in 1s

Details

canary-required / collect-diff (pull_request) Successful in 3s

Details

infra-docs-drift / docs-drift (pull_request) Successful in 4s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 3s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 3s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 18s

Details

python-ci / Python 3.11 (pull_request) Successful in 35s

Details

python-ci / Python 3.12 (pull_request) Successful in 36s

Details

patchwarden-client-dry-run / dry-run (pull_request) Successful in 16s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 3m43s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 14s

Details

python-ci / Python 3.13 (pull_request) Successful in 36s

Details

workflow-lint / lint (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Has been skipped

Details

6f94652a8a

claude commented

2026-06-01 11:39:41 +02:00

Collaborator

Currency-fixed (claude, commit 6f94652a). Updated to 2026-06-01 live state:

M04 Vault sunset → CLOSED (was OPEN); M01/02/03/05/09 → CLOSED.
M07 → Memory Control Plane shipped (ADR-0025 + task_run/checkpoint #460 + procedure registry #461, all merged); #357 embedding migration separate/gated.
+M10 Improvements (triaged clean, Judging-Claw priority-tagged).
+Gemini 3.5 Flash as the 9th cousin (ADR-0023, fast-reviewer / visual-verification lane).
Pending-decisions block refreshed — the 2026-05-27 blockers (W3d DR, destructive cleanup, Vault sunset) are RESOLVED.
Added a STATUS_NOW-is-stale flag (it self-updated 2026-05-27; trust live evidence).

Now reflects current state → merge-ready. Recommend operator merge — fills the no-MAP-on-main gap (claude's original v1 never merged).

**Currency-fixed (claude, commit `6f94652a`).** Updated to 2026-06-01 live state: - **M04 Vault sunset → CLOSED** (was OPEN); M01/02/03/05/09 → CLOSED. - **M07 → Memory Control Plane shipped** (ADR-0025 + task_run/checkpoint #460 + procedure registry #461, all merged); #357 embedding migration separate/gated. - **+M10** Improvements (triaged clean, Judging-Claw priority-tagged). - **+Gemini 3.5 Flash** as the 9th cousin (ADR-0023, fast-reviewer / visual-verification lane). - **Pending-decisions block refreshed** — the 2026-05-27 blockers (W3d DR, destructive cleanup, Vault sunset) are RESOLVED. - Added a **STATUS_NOW-is-stale** flag (it self-updated 2026-05-27; trust live evidence). Now reflects current state → **merge-ready.** Recommend operator merge — fills the no-MAP-on-main gap (claude's original v1 never merged).

codex commented

2026-06-01 11:45:58 +02:00

Collaborator

Patchwarden PR sanity

Status: advisory_findings
PR: 563
Commit: 6f94652a8a8956ffb70ff4863635685b680da671
Security-sensitive label: missing
Authority: advisory model review plus deterministic blockers only
3+3 canary: still alive; this does not replace it

Deterministic findings

No deterministic findings.

Model reviewers

`global-glm` / `glm-5.1:cloud`

Status: ok
Verdict: NOT_OK
medium Cousin enumeration count contradicts table
- Evidence: FAQ section line '~7 named cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity) + DeepSeek-v4-Pro (ADR-0016, 8th cousin)' but the 'By cousin' table lists 10 rows including operator, Iskra, Hermes, claude, codex, glm, antigravi
- Next: Update FAQ answer to say '9 named cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity, DeepSeek, Gemini) + future local-admin tier' or clarify that operator is not counted as a 'cousin' and reconcile the total.
medium Mermaid diagram cousin nodes don't match table
- Evidence: Mermaid subgraph 'Cousins' lists: Iskra, Hermes, Claude, Codex, DeepSeek, Swarm, LocalAdm. The 'By cousin' table lists: operator, Iskra, Hermes, claude, codex, glm, antigravity, DeepSeek, DeepSeek-v4-Pro (dziadek), Gemini 3.5 Flash, local-a
- Next: Align Mermaid diagram with the cousin table. Either show glm and antigravity separately (matching table) or add a note that 'Swarm' represents the Ollama Cloud models (kimi/glm/deepseek/qwen). Add Gemini 3.5 Flash node if it's a named cousin per ADR-0023.
low WIP checklist items unchecked
- Evidence: PR description contains unchecked review checklist: '- [ ] Cousin enumeration matches ADR-0010 + ADR-0016', '- [ ] Wave/Milestone statuses match state/roadmap/current-platform-roadmap.md', '- [ ] Mermaid diagram reflects current topology',
- Next: Complete the review checklist verification before requesting merge, or convert to tracked issues if this PR is being merged as incremental progress.

`global-deepseek` / `deepseek-v4-pro:cloud`

Status: ok
Verdict: NOT_OK
high Stale 'Current mode' contradicts closed W3d status
- Evidence: MAP.md line: 'Current mode: W3d remote sandbox restore drill on vps1000; isolated Docker-only mutation, no RS2000 production mutation.' Earlier the Wave table shows W3d as 'ACCEPTED IMMEDIATE GATE; W3d LOCAL + VPS1000 SANDBOX PASS GREEN'. T
- Next: Remove or update the 'Current mode' line to reflect the closed status, or clarify that it is historical.
medium Cousin enumeration mismatch with PR description
- Evidence: PR description states 'Add DeepSeek-v4-Pro (dziadek) as 8th cousin per ADR-0016', but the diff also adds Gemini 3.5 Flash as 9th cousin via ADR-0023. The PR title says '8 cousins'. If ADR-0023 is not yet adopted, this is premature and could
- Next: Either remove the Gemini entry until ADR-0023 is merged, or update the PR description and title to reflect 9 cousins.
medium Dangling references to bounded-context MAPs
- Evidence: MAP.md references 'contexts/*/MAP.md' multiple times (e.g., 'New for v2: Bounded-context MAPs in contexts/*/MAP.md provide focused navigation...'). The PR does not include these files. If they do not exist in the repo, these references are
- Next: Ensure the referenced context MAP files are created and merged before or alongside this PR, or remove the references until they exist.
medium Unverified ADR references may be incorrect
- Evidence: The document cites ADR-0016, ADR-0023, ADR-0018, ADR-0017, ADR-0019, etc. The PR checklist includes verification of these, but it is not yet completed. If any of these ADRs are missing or have different numbers, the document will contain fa
- Next: Complete the checklist item 'Cousin enumeration matches ADR-0010 + ADR-0016' and verify all ADR references before merging.

`redteam` / `kimi-k2.6:cloud`

Status: ok
Verdict: NOT_OK
high Contradictory DR status: M02 closed while current mode claims W3d drill ongoing
- Evidence: MAP.md Wave table declares W3 'ACCEPTED IMMEDIATE GATE; W3d LOCAL + VPS1000 SANDBOX PASS GREEN' and Milestone table declares M02 'CLOSED' (W3d local + vps1000 sandbox PASS), yet the same document states 'Current mode: W3d remote sandbox res
- Next: Reconcile W3d status before merge: if the sandbox drill is still ongoing, do not mark M02 as CLOSED; if M02 is truly closed, remove or update the stale 'Current mode' line so agents and operators do not incorrectly believe production mutation is still blocked (or worse, proceed with destructive clea

Policy notes

GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot.
Optional red-team model is enabled only when PLATFORMCTL_PR_SANITY_REDTEAM_MODEL is configured.
Auto-merge is not enabled here.

# Patchwarden PR sanity - Status: `advisory_findings` - PR: `563` - Commit: `6f94652a8a8956ffb70ff4863635685b680da671` - Security-sensitive label: `missing` - Authority: advisory model review plus deterministic blockers only - 3+3 canary: still alive; this does not replace it ## Deterministic findings No deterministic findings. ## Model reviewers ### `global-glm` / `glm-5.1:cloud` - Status: `ok` - Verdict: `NOT_OK` - **`medium`** Cousin enumeration count contradicts table - Evidence: `FAQ section line '~7 named cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity) + DeepSeek-v4-Pro (ADR-0016, 8th cousin)' but the 'By cousin' table lists 10 rows including operator, Iskra, Hermes, claude, codex, glm, antigravi` - Next: Update FAQ answer to say '9 named cousins (operator, Iskra, Hermes, claude, codex, glm, antigravity, DeepSeek, Gemini) + future local-admin tier' or clarify that operator is not counted as a 'cousin' and reconcile the total. - **`medium`** Mermaid diagram cousin nodes don't match table - Evidence: `Mermaid subgraph 'Cousins' lists: Iskra, Hermes, Claude, Codex, DeepSeek, Swarm, LocalAdm. The 'By cousin' table lists: operator, Iskra, Hermes, claude, codex, glm, antigravity, DeepSeek, DeepSeek-v4-Pro (dziadek), Gemini 3.5 Flash, local-a` - Next: Align Mermaid diagram with the cousin table. Either show glm and antigravity separately (matching table) or add a note that 'Swarm' represents the Ollama Cloud models (kimi/glm/deepseek/qwen). Add Gemini 3.5 Flash node if it's a named cousin per ADR-0023. - **`low`** WIP checklist items unchecked - Evidence: `PR description contains unchecked review checklist: '- [ ] Cousin enumeration matches ADR-0010 + ADR-0016', '- [ ] Wave/Milestone statuses match state/roadmap/current-platform-roadmap.md', '- [ ] Mermaid diagram reflects current topology', ` - Next: Complete the review checklist verification before requesting merge, or convert to tracked issues if this PR is being merged as incremental progress. ### `global-deepseek` / `deepseek-v4-pro:cloud` - Status: `ok` - Verdict: `NOT_OK` - **`high`** Stale 'Current mode' contradicts closed W3d status - Evidence: `MAP.md line: 'Current mode: W3d remote sandbox restore drill on vps1000; isolated Docker-only mutation, no RS2000 production mutation.' Earlier the Wave table shows W3d as 'ACCEPTED IMMEDIATE GATE; W3d LOCAL + VPS1000 SANDBOX PASS GREEN'. T` - Next: Remove or update the 'Current mode' line to reflect the closed status, or clarify that it is historical. - **`medium`** Cousin enumeration mismatch with PR description - Evidence: `PR description states 'Add DeepSeek-v4-Pro (dziadek) as 8th cousin per ADR-0016', but the diff also adds Gemini 3.5 Flash as 9th cousin via ADR-0023. The PR title says '8 cousins'. If ADR-0023 is not yet adopted, this is premature and could` - Next: Either remove the Gemini entry until ADR-0023 is merged, or update the PR description and title to reflect 9 cousins. - **`medium`** Dangling references to bounded-context MAPs - Evidence: `MAP.md references 'contexts/*/MAP.md' multiple times (e.g., 'New for v2: Bounded-context MAPs in contexts/*/MAP.md provide focused navigation...'). The PR does not include these files. If they do not exist in the repo, these references are ` - Next: Ensure the referenced context MAP files are created and merged before or alongside this PR, or remove the references until they exist. - **`medium`** Unverified ADR references may be incorrect - Evidence: `The document cites ADR-0016, ADR-0023, ADR-0018, ADR-0017, ADR-0019, etc. The PR checklist includes verification of these, but it is not yet completed. If any of these ADRs are missing or have different numbers, the document will contain fa` - Next: Complete the checklist item 'Cousin enumeration matches ADR-0010 + ADR-0016' and verify all ADR references before merging. ### `redteam` / `kimi-k2.6:cloud` - Status: `ok` - Verdict: `NOT_OK` - **`high`** Contradictory DR status: M02 closed while current mode claims W3d drill ongoing - Evidence: `MAP.md Wave table declares W3 'ACCEPTED IMMEDIATE GATE; W3d LOCAL + VPS1000 SANDBOX PASS GREEN' and Milestone table declares M02 'CLOSED' (W3d local + vps1000 sandbox PASS), yet the same document states 'Current mode: W3d remote sandbox res` - Next: Reconcile W3d status before merge: if the sandbox drill is still ongoing, do not mark M02 as CLOSED; if M02 is truly closed, remove or update the stale 'Current mode' line so agents and operators do not incorrectly believe production mutation is still blocked (or worse, proceed with destructive clea ## Policy notes - GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot. - Optional red-team model is enabled only when `PLATFORMCTL_PR_SANITY_REDTEAM_MODEL` is configured. - Auto-merge is not enabled here.

pdurlej changed title from ~~WIP: docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph~~ to docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph

2026-06-01 12:47:22 +02:00

pdurlej merged commit 9eeaec2ee8 into main

2026-06-01 12:47:26 +02:00

pdurlej deleted branch deepseek/dziadek-refresh-map-md

2026-06-01 12:47:26 +02:00

pdurlej referenced this pull request from a commit

2026-06-01 12:47:26 +02:00

Merge pull request 'docs(navigability): refresh MAP.md v2 — Waves, Milestones, 8 cousins, CodeGraph' (#563) from deepseek/dziadek-refresh-map-md into main