SouveraineOS/docs/substrate/tasks/INDEX.md

Documentation & Task Index

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	2	Project identity and session bootstrap
Active Docs	23	Philosophy, architecture, design records, operations
Active Tasks	29	Current work queue
Skills	2	Specialization units
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.
souveraine-native-audio-privacy.md	delivery	in progress	Original AGPL PulseAudio controls and truthful privacy surfaces; PipeWire retained only for portal video.
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)