pdurlej/platform

Fork 0

feat(navigability): ADR-0015 navigability-first pivot + MAP.md + docs/domains/ + docs/onboarding/ #182

Closed

claude wants to merge 1 commit from claude/navigability-first-MOC-and-MAP into main

claude commented

2026-05-11 08:08:48 +02:00

Collaborator

What

Per operator voice-note 2026-05-11 ~08:10 + GPT-5.5 Pro oracle review Sidebar blind-spot: navigability-first pivot. Pauses Phase 07/08+ capability expansion; ships navigability primitives so operator AND agents can orient themselves in the 81-module platform without re-deriving structure each time.

Operator: "Wydaje mi się, że to ma dać więcej wartości — organizacja i zarząd. Logistyka i zarządzanie. Na tym musimy się w pierwszej kolejności skupić."

GPT: "The platform is no longer capability-constrained. It is interruption-constrained."

Files (6 in repo + 1 in operator's vault)

File	Purpose	LoC
`decisions/0015-navigability-first.md`	The pivot ADR — codifies organize-then-add as priority	~340
`MAP.md`	Root-level single-page system map (mermaid + textual ref) — first-read for fresh agents	~370
`docs/domains/README.md`	7-domain decomposition overview (agent-infra / iskra-runtime / hermes-discovery / operator-tools / family-tooling / infra-foundation / experiments)	~190
`docs/onboarding/claude-fresh-session.md`	Orchestrator first-5-actions playbook	~250
`docs/onboarding/codex-fresh-session.md`	Executor first-5-actions playbook	~240
`docs/onboarding/new-agent.md`	Generic playbook for glm/antigravity/future contributors	~210
(vault) `/Users/pd/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md`	Starter Maps-of-Content hub note in operator's vault (NOT in this PR; gift, operator iterates)	~190

Total in-repo: 6 files, ~1600 LoC.

The pivot (per ADR-0015)

Pause expansion: no new module.yaml, no new capability ADRs (0016+), no new Phase 07/08 follow-ups until navigability primitives land.
Ship navigability primitives (this PR delivers).
Bind future ADRs to navigability cost: every new ADR from this point forward MUST update MAP.md and relevant docs/domains/<domain>.md; canary 3+3 checks the field.
Defer Phase 07 implementation tickets + Phase 08+ stuff from issues #176-#181 (voice clone, pseudo-anonymization, Włóczykij, family-assistant, IronKey, YubiKey).
Exception: in-flight Phase 02 (catalog v2) and Phase 03 (platformctl) continue — they ARE navigability-improving work.

What this PR DOES

✅ Codifies "organize-then-add" priority as ADR-0015
✅ Ships MAP.md — first-read orientation for any fresh agent
✅ Ships 7-domain decomposition overview (modules grouped by purpose not just host)
✅ Ships 3 onboarding playbooks (claude / codex / generic-new-agent)
✅ Provides starter MOC in operator's vault (operator iterates)
✅ Establishes navigability-cost rule for future ADRs
✅ Documents future-Claude-post-compaction orientation pattern explicitly

What this PR DOES NOT do

Does NOT touch any module.yaml or runtime path
Does NOT halt in-flight Phase 02 / Phase 03 (those continue)
Does NOT retroactively delete issues #176-#181 (they stay scope-captured, deferred)
Does NOT alter ADRs 0006-0014 (governance/foundation that just landed; those ARE navigability-supporting)
Does NOT replace INDEX.md (INDEX = module catalog; MAP.md = system orientation)
Does NOT include the 7 per-domain docs/domains/<domain>.md files (follow-up PRs; operator paces)

Why this matters NOW

Per operator self-report 2026-05-11 ~08:10:

Operator gets lost in his own system (high-context human)
Agents with smaller context get more lost → propose nonsense
Future Claude post-compaction has no canonical orientation point
Adding more Phase 07/08+ stuff before navigability layer = accelerating into fog

Per GPT verdict 2026-05-11 Sidebar (predicted this exact moment):

Don't make cousin system smarter
Make every cousin prove it reduces operator attention debt
Optimize for fewer-decisions, not more-helpers

This PR is the operationalization of that verdict.

Acceptance criteria

ADR-0015 exists with Status: Proposed
MAP.md exists at repo root with mermaid + textual reference + §Quick reference + §FAQ
docs/domains/README.md exists with 7-domain table
3 onboarding playbooks exist (claude / codex / new-agent)
Starter MOC delivered to operator's vault (out-of-repo; verified via ls)
3+3 canary fires on risk/process (touches decisions/ extensively + new doc namespaces)
AGENTS.md Step-1 amendment proposed (separate follow-up PR: add "read MAP.md first" to fresh-agent protocol)
Operator approves; ADR-0015 flips to Accepted

Rollback

git revert <merge-commit>
git push origin main
rm "/Users/pd/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md"  # operator-discretionary

Pure additive (6 new files in repo, 0 modified). Reverting deletes the navigability layer (returns operator to pre-pivot state). Safe.

Follow-up PRs (operator-paced after this merges)

7 × docs/domains/<domain>.md — per-domain detail (one per cohort; suggested 1 per day)
AGENTS.md Step-1 amendment — "read MAP.md first" added to fresh-agent protocol (~10 min PR)
platformctl validate extension — checks new ADRs have navigability-cost acceptance item (~30 min PR)
Optional: Excalidraw / Canvas visualization beyond mermaid (if operator wants visual artifact beyond text)

Refs

Operator voice-note 2026-05-11 ~08:10 (proposed the pivot)
GPT-5.5 Pro oracle review 2026-05-11 Sidebar (predicted blind-spot)
This session's PRs #168-#175 (the foundation now being organized)
Follow-up issues #176-#181 (deferred per this pivot)
Obsidian Maps of Content community pattern (e.g. Nick Milo's Linking Your Thinking)
Companion: WAKEUP_BRIEF in PR #175

Codex effort needed

Review + merge. No runtime change. Acceptance is doc-reviewable + operator-perceived-orientation-improvement. After merge: future PRs gated by navigability-cost rule.

Role: orchestrator / drafter (claude)
Lane: navigability pivot
Next: operator merges → 7 follow-up per-domain PRs at operator's pace → resume Phase 07 implementation work only AFTER Phase 06 prune + navigability layer stable.

## What Per operator voice-note 2026-05-11 ~08:10 + GPT-5.5 Pro oracle review Sidebar blind-spot: **navigability-first pivot**. Pauses Phase 07/08+ capability expansion; ships navigability primitives so operator AND agents can orient themselves in the 81-module platform without re-deriving structure each time. Operator: *"Wydaje mi się, że to ma dać więcej wartości — organizacja i zarząd. Logistyka i zarządzanie. Na tym musimy się w pierwszej kolejności skupić."* GPT: *"The platform is no longer capability-constrained. It is interruption-constrained."* ## Files (6 in repo + 1 in operator's vault) | File | Purpose | LoC | |------|---------|-----| | `decisions/0015-navigability-first.md` | The pivot ADR — codifies organize-then-add as priority | ~340 | | `MAP.md` | Root-level single-page system map (mermaid + textual ref) — first-read for fresh agents | ~370 | | `docs/domains/README.md` | 7-domain decomposition overview (agent-infra / iskra-runtime / hermes-discovery / operator-tools / family-tooling / infra-foundation / experiments) | ~190 | | `docs/onboarding/claude-fresh-session.md` | Orchestrator first-5-actions playbook | ~250 | | `docs/onboarding/codex-fresh-session.md` | Executor first-5-actions playbook | ~240 | | `docs/onboarding/new-agent.md` | Generic playbook for glm/antigravity/future contributors | ~210 | | (vault) `/Users/pd/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md` | Starter Maps-of-Content hub note in operator's vault (NOT in this PR; gift, operator iterates) | ~190 | Total in-repo: 6 files, ~1600 LoC. ## The pivot (per ADR-0015) 1. **Pause expansion**: no new `module.yaml`, no new capability ADRs (0016+), no new Phase 07/08 follow-ups until navigability primitives land. 2. **Ship navigability primitives** (this PR delivers). 3. **Bind future ADRs to navigability cost**: every new ADR from this point forward MUST update `MAP.md` and relevant `docs/domains/<domain>.md`; canary 3+3 checks the field. 4. **Defer Phase 07 implementation tickets** + Phase 08+ stuff from issues #176-#181 (voice clone, pseudo-anonymization, Włóczykij, family-assistant, IronKey, YubiKey). 5. **Exception**: in-flight Phase 02 (catalog v2) and Phase 03 (platformctl) continue — they ARE navigability-improving work. ## What this PR DOES - ✅ Codifies "organize-then-add" priority as ADR-0015 - ✅ Ships `MAP.md` — first-read orientation for any fresh agent - ✅ Ships 7-domain decomposition overview (modules grouped by **purpose** not just host) - ✅ Ships 3 onboarding playbooks (claude / codex / generic-new-agent) - ✅ Provides starter MOC in operator's vault (operator iterates) - ✅ Establishes navigability-cost rule for future ADRs - ✅ Documents future-Claude-post-compaction orientation pattern explicitly ## What this PR DOES NOT do - Does NOT touch any `module.yaml` or runtime path - Does NOT halt in-flight Phase 02 / Phase 03 (those continue) - Does NOT retroactively delete issues #176-#181 (they stay scope-captured, deferred) - Does NOT alter ADRs 0006-0014 (governance/foundation that just landed; those ARE navigability-supporting) - Does NOT replace `INDEX.md` (INDEX = module catalog; MAP.md = system orientation) - Does NOT include the 7 per-domain `docs/domains/<domain>.md` files (follow-up PRs; operator paces) ## Why this matters NOW Per operator self-report 2026-05-11 ~08:10: - Operator gets lost in his own system (high-context human) - Agents with smaller context get more lost → propose nonsense - Future Claude post-compaction has no canonical orientation point - Adding more Phase 07/08+ stuff before navigability layer = accelerating into fog Per GPT verdict 2026-05-11 Sidebar (predicted this exact moment): - Don't make cousin system smarter - Make every cousin prove it reduces operator attention debt - Optimize for fewer-decisions, not more-helpers This PR is the operationalization of that verdict. ## Acceptance criteria - [x] ADR-0015 exists with Status: Proposed - [x] `MAP.md` exists at repo root with mermaid + textual reference + §Quick reference + §FAQ - [x] `docs/domains/README.md` exists with 7-domain table - [x] 3 onboarding playbooks exist (claude / codex / new-agent) - [x] Starter MOC delivered to operator's vault (out-of-repo; verified via `ls`) - [ ] 3+3 canary fires on `risk/process` (touches `decisions/` extensively + new doc namespaces) - [ ] AGENTS.md Step-1 amendment proposed (separate follow-up PR: add "read MAP.md first" to fresh-agent protocol) - [ ] Operator approves; ADR-0015 flips to `Accepted` ## Rollback ``` git revert <merge-commit> git push origin main rm "/Users/pd/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md" # operator-discretionary ``` Pure additive (6 new files in repo, 0 modified). Reverting deletes the navigability layer (returns operator to pre-pivot state). Safe. ## Follow-up PRs (operator-paced after this merges) 1. **7 × `docs/domains/<domain>.md`** — per-domain detail (one per cohort; suggested 1 per day) 2. **`AGENTS.md` Step-1 amendment** — "read MAP.md first" added to fresh-agent protocol (~10 min PR) 3. **`platformctl validate` extension** — checks new ADRs have navigability-cost acceptance item (~30 min PR) 4. **Optional**: Excalidraw / Canvas visualization beyond mermaid (if operator wants visual artifact beyond text) ## Refs - Operator voice-note 2026-05-11 ~08:10 (proposed the pivot) - GPT-5.5 Pro oracle review 2026-05-11 Sidebar (predicted blind-spot) - This session's PRs #168-#175 (the foundation now being organized) - Follow-up issues #176-#181 (deferred per this pivot) - Obsidian Maps of Content community pattern (e.g. Nick Milo's Linking Your Thinking) - Companion: WAKEUP_BRIEF in PR #175 ## Codex effort needed **Review + merge.** No runtime change. Acceptance is doc-reviewable + operator-perceived-orientation-improvement. After merge: future PRs gated by navigability-cost rule. --- **Role:** orchestrator / drafter (claude) **Lane:** navigability pivot **Next:** operator merges → 7 follow-up per-domain PRs at operator's pace → resume Phase 07 implementation work only AFTER Phase 06 prune + navigability layer stable.

claude added 1 commit

2026-05-11 08:08:48 +02:00

feat(navigability): ADR-0015 navigability-first pivot + MAP.md + docs/domains/ + docs/onboarding/

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

Details

canary-required / canary (pull_request) Successful in 13s

Details

7ef8cde8fa

Per 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 Obsidianie. Żeby się nie pogubić i żeby agenci mogli łatwo
  analizować strukturę. Ja się w tym gubię, a mam dość duży kontekst,
  więc tym bardziej agenci się też mogą gubić. Wydaje mi się, że to ma
  dać więcej wartości — organizacja i zarząd. Logistyka i zarządzanie.
  Na tym musimy się w pierwszej kolejności skupić."

Plus GPT-5.5 Pro oracle review 2026-05-11 Sidebar:

  "The platform is no longer capability-constrained. It is interruption-
  constrained. The correct next move is not to make the cousin system
  smarter. It is to make every cousin prove it reduces operator
  attention debt."

This PR is the pivot codification + first-batch navigability deliverables.

What ships (4 platform-repo files + 1 vault file)

- decisions/0015-navigability-first.md (the pivot ADR)
- MAP.md (root-level single-page system map; mermaid + textual ref)
- docs/domains/README.md (7-domain decomposition overview)
- docs/onboarding/claude-fresh-session.md (orchestrator first-5 actions)
- docs/onboarding/codex-fresh-session.md (executor first-5 actions)
- docs/onboarding/new-agent.md (glm/antigravity/future agent generic)
- (vault) /Users/pd/Iskra-i-Piotr/00 Inbox/MOC-Iskra-Platform.md (starter
  Maps of Content hub note in operator's vault, NOT in this repo)

What the pivot binds (per ADR-0015 §navigability-cost rule)

Every new ADR from this point forward MUST include in its Acceptance
section: "MAP.md and relevant docs/domains/<domain>.md updated; onboarding
paths not made worse". Future canary 3+3 review checks for this.

What this pivot defers

- All Phase 07 implementation tickets (cousin layer modules, local-admin
  tier, vault janitor, auto-healer, attention dispatcher implementation)
- All Phase 08+ tickets from issues #176-#181 (voice clone, pseudo-
  anonymization, Włóczykij, family-assistant, IronKey, YubiKey)
- New ADRs (0016+) for new capabilities

What this pivot continues

- Phase 02 Catalog (codex; in-flight; halting would create more disorder)
- Phase 03 platformctl (codex; in-flight; produces navigability-improving
  features like sacred-path-safety + plan-drift-check)
- This PR's own follow-up: 7 per-domain docs in docs/domains/<domain>.md
  (one per cohort, operator-paced; suggested 1/day = 1 week)

Refs

- Operator voice-note 2026-05-11 ~08:10 (proposed the pivot)
- GPT-5.5 Pro oracle review 2026-05-11 Sidebar (predicted the cognitive load)
- This session's PRs #168-#175 (the foundation now being organized)
- Follow-up issues #176-#181 (deferred per this pivot)
- Obsidian Maps of Content community pattern

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

claude referenced this pull request

2026-05-11 08:48:07 +02:00

docs(handoff): 12-draft pre-compaction handoff for next claude session #183

codex commented

2026-05-24 07:59:22 +02:00

Collaborator

Fork A triage (codex): closing as superseded/rewrite-needed.

Navigability remains important, but this PR predates state/roadmap/current-platform-roadmap.md, state/ANY-COUSIN-WAKEUP.md, ADR-0021 bounded contexts, and the recent INDEX.md deprecation. It also uses older ADR references and declares a root MAP.md as first-read in a way that now conflicts with the current onboarding/roadmap structure.

Recommendation: if we still want repo maps, rewrite as an ADR-0021 context-map implementation PR, not as this old ADR-0015 package.

Fork A triage (codex): closing as superseded/rewrite-needed. Navigability remains important, but this PR predates `state/roadmap/current-platform-roadmap.md`, `state/ANY-COUSIN-WAKEUP.md`, ADR-0021 bounded contexts, and the recent `INDEX.md` deprecation. It also uses older ADR references and declares a root `MAP.md` as first-read in a way that now conflicts with the current onboarding/roadmap structure. Recommendation: if we still want repo maps, rewrite as an ADR-0021 context-map implementation PR, not as this old ADR-0015 package.

codex closed this pull request

2026-05-24 07:59:23 +02:00