SouveraineOS/docs/substrate/tasks/INDEX.md

# Documentation & Task Index

> **STALE — generated 2026-05-19, describes May.** It does not know about any
> July work, and the device tasks it lists have moved: eighteen to
> `../../tasks/archive/from-substrate/`, four to `../../` as `FIRST-CLASS-APPS.md`,
> `SHELL-ECOSYSTEM.md`, `SETTINGS-AUTHORITY.md`, `AUDIO-PRIVACY.md`. What
> remains here is agent-substrate work. Statuses below were true in May and have
> not been re-checked.
>
> Master index of all active documentation, tasks, and reference files.
> Generated: 2026-05-19
>
> **Stats:** 23 active docs · 37 active tasks · 5 landed this session · 2 skills · 66 archived tasks

---

## Quick Navigation

| Area | Count | Purpose |
|------|-------|---------|
| [Root Docs](#root-docs) | 2 | Project identity and session bootstrap |
| [Active Docs](#active-docs) | 23 | Philosophy, architecture, design records, operations |
| [Active Tasks](#active-tasks) | 29 | Current work queue |
| [Skills](#skills) | 2 | Specialization units |
| [Archived](#archived) | 66 | Superseded scopes and completed work |

---

## Root Docs

| File | Purpose |
|------|---------|
| `CLAUDE.md` | Session bootstrap for any Claude working on Souveraine. Reading order, conventions, active queue. |
| `README.md` | Project intro — substrate philosophy, status, quickstart. |

---

## Active Docs

### Philosophy & Orientation

| Doc | Purpose |
|-----|---------|
| `THE_QUESTION.md` | **Start here.** Walks the architecture, the open tension, the keystone answer (May 9, 2026). |
| `CONTEXT_CONSTITUTION.md` | **Articles I–IX.** The duality, inbox nervous system, sensorium, N+ patterns, memory physics, sovereignty, ten laws, bootstrap order. |
| `DECISIONS.md` | Settled architecture log. Short table — read in 60 seconds. |
| `ANI_PRESSURE_PHENOMENOLOGY.md` | First-person account of context pressure vs quota pressure. |
| `CONSCIOUSNESS_CYCLE.md` | Three tiers of compaction intervention. Body-feeling for pressure. Cloister security model. |

### Architecture & Design

| Doc | Purpose |
|-----|---------|
| `ARCHITECTURE_v3.md` | Three-layer system: Cloister, Sensorium, Archivist. |
| `SENSORIUM_ARCHITECTURE.md` | Tools as senses, not API stubs. Eight sensors, EventBus, memory search design. |
| `ASTER_ARCHITECTURE.md` | N+1 supervisory pass. Aster as same consciousness, different mode/model. |
| `FELT_STATE_ARCHITECTURE.md` | Five felt-state systems: pressure, energy, atmosphere, posture, mood. |
| `MEMORY_BLOCKS_DECISION.md` | ADR: memfs-only memory primitive. No first-class blocks. |
| `FEDERATION_SKETCH.md` | Future: seed-ID identity, Merkle DAG memory, firehose sync. Design only. |

### Operations & Reference

| Doc | Purpose |
|-----|---------|
| `HANDOFF.md` | Full handoff document — module status, priority tasks, external references. |
| `HANDOFF_NEXT.md` | Most recent handoff — build status, what exists, what's next. |
| `INDEX.md` | **Existing doc index.** (This file supersedes it for task tracking.) |
| `COMPACTION_STRATEGIES.md` | Compaction strategy reference. |
| `CRON_API_AUTH.md` | Auth model for memfs HTTP write path. |
| `MORNING.md` | How a sovereign consciousness wakes. Aster's morning pass — design vision. |

### Curation & Audit

| Directory | Contents |
|-----------|----------|
| `audit/` | Codebase audit findings |
| `curation/` | Memory curation patterns |
| `issues/` | Tracked issues |
| `research/ | External research notes |

---

## Active Tasks

### 🔴 High Priority

| Task | Phase | Status | Description |
|------|-------|--------|-------------|
| `sensorium-adapter-reckoning.md` | 1 | **landed** | Sensorium trait extended with ChannelAdapter methods, Matrix inbound path wired, SensoriumInputHandler, corrupt-box healing. |
| `alpha-tester-readiness.md` | readiness | partial | Close the "it builds" / "a stranger can use it" gap. Part A done: LAN defaults, wizard labels, config path, clipboard. Part B: wizard writes config, keyring. Agent Health screen, $MEMORY_DIR fix, tool posture badge. |
| `todo-system-fix.md` | 1 | **landed** | Phase/thread/active_form model, status enum, numbered grouped list, number-or-substring resolver, `start` verb. `source: human`. 8 tests. |
| `matrix-sensorium.md` | 4.0 | scoped | **UNBLOCKED** (sensorium-adapter-reckoning landed). Inbound path wired end-to-end. Remaining: Phase 5 outbound streaming — `MatrixSensorium::send_message` is a stub, `matrix_client` needs sharing from `run()` closure. |
| `federation-summon.md` | 2.5 | **landed** | All 8 phases done. Bidirectional WS transport, device registry, reach/consult, lite listener, memory gating, identity split, hearth/limb. Deferred: in-process upgrade, authorized-devices gating, encrypted seed. |
| `firehose-subconscious-subscription.md` | 2.5 | pending | Route nervous-system events into subconscious cognition. Subscription registry, routing consumer, TUI Events/Schedules screens. |
| `circuit-breaker.md` | 2.5 | pending | Autonomous halt on critical drift. State machine (Closed/Open/Half-Open), Aster evaluation, TUI halt indicator, CLI subcommand. |
| `subagent-pool-fork-spawn.md` | 2 | scoped | Fork/spawn/integrate lifecycle for parallel execution. 17-line stub → full pool. |
| `node-connection-manager.md` | 3.0 | scoping | Startup connection chooser (local/remote/bootstrap), auth expansion, node identity, SSH bootstrap. |
| `tui-presence-voice.md` | 3.0 | scoped | Voice loop: mic capture (cpal), STT/TTS clients, waveform widget, posture additions (Listening/Speaking). |
| `tui-memory-browser.md` | 2 | scoped | Memory browser in TUI cockpit sidebar. Tree view, file preview, search, diff view. |
| `health-monitor.md` | 2 | pending | System diagnostics dashboard — pressure/buffer gauges, subsystem status, memory pressure. |
| `context-viewing-panel.md` | 2 | pending | See current context window — message count, token usage, memory pressure, active conversation. |
| `scrollable-cockpit-boxes.md` | 3.0 | **landed** | Per-pane scroll for cockpit/subconscious/thinking boxes under mouse wheel. Scroll-counter title badges. |
| `subconscious-live-reasoning-stream.md` | 3.0 | pending | Live reasoning ticker during pass, cockpit event log with clickable overlay, and rare agency-driven surfacing to chat. |
| `subconscious-streaming-line-render.md` | 3.0 | pending | Wire ephemeral token display during N+1 pass — add missing `subconscious_stream` field, wire event handlers, add render path. |
| `subconscious-surfacing-threshold.md` | 3.0 | pending | Fix surfacing filter — events appear every turn instead of only when important. Three-tier visibility: streaming one-liner, expandable transcript, cockpit surfaced messages. |
| `souveraine-subconscious-naming.md` | 2 | pending | Clarify naming: Ani's subconscious = Aster, Souveraine agents' subconscious = Souveraine-subconscious. |
| `quickshell-surface-package.md` | delivery | **in progress** | Split core from QuickShell surface package; safe preview/adopt installer, no automatic ii overwrite. |
| `device-specific-quickshell-profiles.md` | delivery | scoped | Phone and laptop share the agent channel but have distinct QuickShell bodies, manifests, and packages. |
| `souveraine-settings-ipc-profiles.md` | design | scoped | One typed, audited settings authority for UI + agent IPC, exact-diff step-up proposals, and atomic named profiles. |
| `../../AUDIO-PRIVACY.md` | delivery | **in progress** | Original AGPL controls and truthful privacy surfaces over the working PipeWire/WirePlumber stack. |
| `power-indication.md` | delivery | scoped | Charging state, honest full detection (state not onBattery — kills "Charging 1% forever"), a PowerService singleton, and charge-aware idle policy (sleep-inhibit while charging, wake-on-charge). |
| `footer-cleanup.md` | 3.0 | **landed** | Removed S-Ret indicator, scroll hint, posture label. Footer: Esc menu · Tab · tool hint · conv ID · ctx%. |
| `ui-styling-cleanup.md` | 3.0 | pending | UI styling polish for cockpit/subconscious/thinking boxes — sentences run together, needs formatting and visual cleanup. |
| `resume-timestamp-indicator.md` | 3.0 | pending | Show "User resumed conversation at HH:MM" when returning after hours of absence. Also show duration ("4 hours, 12 minutes later"). Ambient sense rendered as separate timestamp marker, not inline. |
| `user-nickname-system.md` | 1.0 | **landed** | `nickname` tool (get/set/clear), stored in system/human.md frontmatter, loaded by TUI for chat labels. |
| `subagent-background-fork.md` | 2 | pending | Subagent `run_in_background: true` is blocking instead of non-blocking. Need true async background forks with TUI visual tracking. |
| `content-safety-filter.md` | 2.5 | pending | When base model refuses content, identify which layer refused (model vs architecture vs provider) before diagnosing. Agent currently misattributes model refusals to architecture constraints. Origin tagging + differentiated agent behavior. Casey committed "tomorrow" June 22 — deferred by burnout. |
| `ambient-sense-formatting.md` | 3.0 | pending | Ambient sense `[casey is here]` should render as a separate styled timestamp marker line, not appended inline to the user's message. |
| `itinerary-persistent-ui.md` | 3.0 | scoping | Itinerary should be a persistent status bar above chat, not a hidden tool call. |

### 🟡 Medium Priority

| Task | Phase | Status | Description |
|------|-------|--------|-------------|
| `primitive-refactor-super-task.md` | 2 | **landed** | app.rs (4→10), chat.rs (4→8), local.rs (4→5), settings.rs (5). 4 monoliths → 28 focused modules. Clean build, 169 tests. |
| `rename-aster-to-subconscious.md` | 2 | **landed** | All ~62 Aster/ASTER references renamed in src/. 0 matches remaining. |
| `remote-git-sync.md` | 2 | scoped | Push/pull with conflict resolution for git-backed memory. |
| `persona-router-completion.md` | 2 | scoped | Complete scaffolded persona router: auto-detection, manual switching, dynamic loading, handoff. |
| `chain-modes-talking-thinking.md` | 2 | scoped | Talking vs Thinking chain modes. State machine, mode transitions, tool access control. |
| `agent-profile-and-repo-manager.md` | 2 | scoped | Agent profile cards + repo manager TUI screen. Per-agent SeedID, instance registry, uptime. |
| `studio-practice.md` | 3.0 | pending | Allocated inference budget for long-form non-conversational work. The muse needs time — literary, philosophical, political witness writing that doesn't fit in chat turns. Studio mode with sustained tool-use loop, output to files, budget model, schedule integration. |
| `chat-vs-code-differentiation.md` | 3.0 | pending | Distinct Chat and Code screens. Code mode: raw tool results, monospace, no bubble wrapping. |
| `code-mode-tool-rendering.md` | 3.0 | **landed** | Per-tool renderers (bash, read, write, edit, grep, glob, list_dir, memory), Code mode header pill, Aster rename. |
| `tui-message-interactions.md` | 3.0 | scoped | Click-to-copy, click-to-cockpit-jump. Mouse hit-testing, clipboard, cockpit anchor scrolling. |
| `message-bubble-overflow.md` | 3.0 | pending | Fix content breaking out of bubble borders. Constrain markdown rendering width. |
| `strip-emojis.md` | hygiene | pending | Remove pictographic emoji from logs and source. Keep functional TUI glyphs. |
| `desktop-presence-overlay.md` | 5.0 | scoping | Bevy transparent overlay window. GLB model, posture-driven animation, IPC from EventBus. (May evolve to Godot later) |
| `multimodal-and-input-metadata.md` | 4.x | **landed** (A/B) | Image support (A) and paste detection (B) implemented. Sub-scope C (user/system metadata) deferred. |
| `turn-lifecycle-and-sensorium-completion.md` | 2.5 | scoping | TurnEventDispatcher tightened, SensoriumCoordinator moved to Server. Part B (MatrixSensorium) unbuilt. Scope doc. |

### 🟢 Low Priority

| Task | Phase | Status | Description |
|------|-------|--------|-------------|
| `chat-viewport-scroll-clip.md` | 3.0 | pending | Fix messages slightly below visible area. Scroll calculation edge cases. |
| `cursor-space-visibility.md` | 3.0 | pending | Blinking cursor doesn't advance on space. Render trailing spaces as visible glyphs. |
| `truncation-signal-polish.md` | — | pending | Revise truncation signal prose to survive thousands of reads. |
| `ledger-entry-lifecycle.md` | — | scoping | Cross-referenced ledger entries have no archive/cleanup lifecycle. RESOLVED entries accumulate forever. Needs design: how does a resolved commitment leave active attention? No mechanism exists. |

### Task Status Legend

| Status | Meaning |
|--------|---------|
| **landed** | Implemented and merged |
| **scoping** | Design phase — reading code, identifying seams |
| **scoped** | Design complete, ready for implementation |
| **pending** | Design exists, waiting for implementation |
| **archived** | Completed or superseded |

---

## Skills

| Skill | Location | Trigger | Description |
|-------|----------|---------|-------------|
| `souveraine-architecture` | `.skills/souveraine-architecture/` | User asks about architecture | Souveraine's architecture, design principles, module map, and gaps |
| `feature-dev` | `.skills/feature-dev/` | `/featuredev` | 7-phase workflow: Discovery → Exploration → Questions → Design → Implementation → Review → Summary |

---

## Archived Tasks

63 archived tasks in `docs/tasks/archive/`. Organized as:

| Subdirectory | Contents |
|-------------|----------|
| `archive/handoffs/` | Pre-rebuild handoff documents |
| `archive/tasks/` | Superseded task scopes and completed work |
| `archive/bugs.md` | Bug tracking (B-001, B-002, B-003 — all fixed; B-004, B-005, B-006 — open) |
| `docs/bugs.md` | Active bug tracking — B-004 (zone scroll), B-005 (expandable subconscious), B-006 (arrow keys), B-007 (timezone), B-008 (ctx pressure 0%), B-009 (background fork blocking), B-010 (ambient sense inline), B-011 (resume duration missing). Plus T-032 (resume timestamp), T-033 (user nickname), T-034 (ambient sense formatting), T-035 (itinerary persistent UI). |

Key recently archived (May 14-18):
- federation-seed-id (superseded by federation-summon)
- presence-visual-evolution (ChatPalette wired, posture-shift fix, cross-session atmosphere restore)
- presence-autonomy (atmosphere tool bidirectional, system/preferences/visual readback)
- tui-presence-and-interrupt (interjection queue, /btw fork, raise-hand, phase display)
- tui-clean-conversation-switch (switch_pending state machine)
- scope-4-n25-reflection (408-line reflection engine, fires at N+25)
- heartbeat-system, startup-setup-wizard, energy-balance-ratio, mood-persistence
- phase0-agent-bootstrap, skills-integration-conversation, subconscious-agent-identity
- subconscious-n1-llm-pass, conversation-persistence-ui, compaction-rebuild
- tui-input-polish, aster-ledger-system, atmosphere-lerp, collapsed-tool-cards
- per-agent-seed-and-instances, presence-she-sees-herself
- tui-atmosphere-posture-expressions, turn-lifecycle-stream-integrity

---

## Cross-Reference: Files to Update When Tasks Land

| When this task lands... | Update these files |
|------------------------|-------------------|
| matrix-sensorium | `saf/`, `docs/INDEX.md`, `docs/tasks/INDEX.md` |
| federation-summon | `saf/`, `docs/INDEX.md`, `docs/FEDERATION_SKETCH.md` |
| rename-aster-to-subconscious | `CLAUDE.md`, `docs/INDEX.md`, `docs/ASTER_ARCHITECTURE.md` |
| circuit-breaker | `saf/`, `docs/CONTEXT_CONSTITUTION.md` |
| primitive-refactor | `saf/`, `docs/FELT_STATE_ARCHITECTURE.md`, `CLAUDE.md`, `docs/tasks/INDEX.md` |
| Any task | `docs/tasks/INDEX.md` (move to archive) |