mosaicstack/stack
1
0
Fork 0
Code Issues 21 Pull Requests Actions Packages Projects Releases 14 Wiki Activity

docs: note new-session trigger for mission toolset reload
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details

Browse Source
This commit is contained in:
Jason Woltje
2026-05-07 13:31:43 -05:00
committed by Mos worker
parent b31699de81
commit 647fd9a835
6 changed files with 175 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/mission-control/BOARD.md
View File

@@ -15,7 +15,7 @@
## Feature Board
| Feature Card | Need | Priority | Decision / Notes |
| --- | --- | --- | --- |
| ------------------------------ | ------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------- |
| Canonical mission manifest | One durable root object for goal, PRD, board, session | Must-have | Mission manifest becomes the anchor for all downstream state |
| PRD generator integration | PRD should be generated from a feature idea and saved in docs | Must-have | Use Mosaic PRDy format and keep the file human-reviewable |
| Board atomization | Break PRD into assignable tasks with dependencies | Must-have | Each user story should map to one or more tasks |
@@ -52,6 +52,7 @@
**Question:** What should trigger a forced session rotation?
**Candidate signals:**
- repeated compaction
- repeated prompts for permission
- identical tool loops
@@ -65,6 +66,7 @@
**Question:** What should the next session receive?
**Proposed answer:**
- Mission ID
- PRD path
- Active board task

8
docs/mission-control/MISSION-MANIFEST.md
View File

@@ -58,8 +58,8 @@ Design references:
## Milestones
| # | ID | Name | Status | Branch | Started | Completed |
| --- | --- | --- | --- | --- | --- | --- |
| 1 | MC-01 | PRD + mission schema foundation | in-progress | docs/mission-control-* | 2026-05-06 | — |
| --- | ----- | ---------------------------------------- | ----------- | ----------------------- | ---------- | --------- |
| 1 | MC-01 | PRD + mission schema foundation | in-progress | docs/mission-control-\* | 2026-05-06 | — |
| 2 | MC-02 | Mission runtime model | not-started | — | — | — |
| 3 | MC-03 | Board atomization and task linkage | not-started | — | — | — |
| 4 | MC-04 | Short-cycle detector and rotation engine | not-started | — | — | — |
@@ -71,7 +71,7 @@ Design references:
## Budget
| Milestone | Est. tokens | Parallelizable? |
| --- | --- | --- |
| --------- | ----------- | ------------------ |
| MC-01 | 16K | No |
| MC-02 | 20K | No |
| MC-03 | 24K | Mostly after MC-01 |
@@ -85,7 +85,7 @@ Design references:
## Session History
| Session | Date | Runtime | Outcome |
| --- | --- | --- | --- |
| ------- | ---------- | ------- | ------------------------------------------------------------------------ |
| S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted |
---

7
docs/mission-control/PRD.md
View File

@@ -57,6 +57,7 @@ This feature unifies those layers into one durable workflow so a mission can sur
**Description:** As an orchestrator, I want to turn a feature idea into a PRD and mission so that agents can work from a durable spec instead of a chat transcript.
**Acceptance Criteria:**
- [ ] `prdy` can emit a PRD with goals, non-goals, and requirements.
- [ ] The PRD is linked to a mission ID.
- [ ] The mission manifest references the PRD path.
@@ -67,6 +68,7 @@ This feature unifies those layers into one durable workflow so a mission can sur
**Description:** As an orchestrator, I want to split a PRD into board tasks so that work can be assigned to specialists.
**Acceptance Criteria:**
- [ ] Each user story can become one or more tasks.
- [ ] Tasks have assignees, dependencies, and estimates.
- [ ] Tasks are machine-readable and durable.
@@ -77,6 +79,7 @@ This feature unifies those layers into one durable workflow so a mission can sur
**Description:** As a coordinator, I want to restart or rotate a session when it short-cycles so that the mission continues with minimal loss.
**Acceptance Criteria:**
- [ ] The coordinator detects compaction pressure or repeated loops.
- [ ] The coordinator writes a handoff summary before rotation.
- [ ] A new session can resume from the handoff packet.
@@ -87,6 +90,7 @@ This feature unifies those layers into one durable workflow so a mission can sur
**Description:** As a worker agent, I want to read the mission and board at startup so I can do the next useful thing without waiting for a human prompt.
**Acceptance Criteria:**
- [ ] Startup loads the active mission manifest.
- [ ] Startup loads the current board/task row.
- [ ] Startup exposes the next action clearly in the prompt.
@@ -97,6 +101,7 @@ This feature unifies those layers into one durable workflow so a mission can sur
**Description:** As an operator, I want a single view of mission health so that I can see progress, blocked tasks, and session churn.
**Acceptance Criteria:**
- [ ] Mission state shows current phase and progress.
- [ ] Board state shows task status by assignee.
- [ ] Short-cycle/rotation events are visible.
@@ -141,7 +146,7 @@ FR-14. The system must keep durable history for rotation and handoff events.
This is the feature discussion board that should drive the mission design.
| Card | Need | Why it matters | Proposed decision |
| --- | --- | --- | --- |
| ------------------------ | -------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| Canonical mission record | One source of truth for goal/state | Prevents drift between chat, docs, and queue | Make mission manifest the durable root object |
| PRD → board derivation | Break feature ideas into executable work | Lets the plan be assigned and tracked | Keep PRD as the spec, generate board tasks from user stories |
| Session watchdog | Detect churn/short-cycling | Keeps overnight runs productive | Add short-cycle scoring and forced rotation |

14
docs/mission-control/TASKS.md
View File

@@ -16,7 +16,7 @@
Goal: create the durable doc structure and the minimal mission metadata needed to keep PRD, board, and mission aligned.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | -------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------- | ------------------ | -------- | ------------------------------------------- |
| MC-01-01 | not-started | Write `docs/mission-control/PRD.md` with goals, non-goals, functional requirements, and success metrics. | — | sonnet | docs/mission-control-prd | — | 5K | Human-readable PRD becomes the spec anchor. |
| MC-01-02 | not-started | Write `docs/mission-control/BOARD.md` as a decision board for scope, priority, and open questions. | — | haiku | docs/mission-control-board | MC-01-01 | 3K | Keeps discussion separate from the spec. |
| MC-01-03 | not-started | Write `docs/mission-control/MISSION-MANIFEST.md` linking PRD, board, tasks, and mission identity. | — | sonnet | docs/mission-control-manifest | MC-01-01, MC-01-02 | 4K | Durable mission root object. |
@@ -31,12 +31,12 @@ Goal: create the durable doc structure and the minimal mission metadata needed t
Goal: make missions first-class runtime objects that can survive session restarts and compaction.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----- | -------------------------------------- | ---------------------------------- | -------- | ------------------------------------------ | ---------------------------------------------------- |
| MC-02-01 | not-started | Define mission schema in the data layer: mission ID, goal, phase, PRD path, board path, active session ID, last handoff, and churn score. | — | codex | feat/mission-control-schema | MC-01-03 | 6K | This is the durable root state. |
| MC-02-02 | not-started | Add mission read/write services to `packages/coord` so the coordinator can load and persist mission state. | — | codex | feat/mission-control-coord-store | MC-02-01 | 6K | Keep storage simple and explicit. |
| MC-02-03 | not-started | Add mission status reporting to `mosaic mission` and `mosaic coord status`. | — | codex | feat/mission-control-status-cli | MC-02-02 | 4K | Operators need one obvious status command. |
| MC-02-04 | not-started | Add tests for mission persistence and recovery after restart. | — | haiku | feat/mission-control-persistence-tests | MC-02-02 | 4K | Verify mission survives process churn. |
|| MC-02-05 | done | Add a worktree-root convention to the mission runtime notes and startup guidance so agents prefer `/src/<repo>-worktrees` over `/tmp`. | — | haiku | docs/mission-control-worktree-root | MC-01-03 | 3K | Keep long-lived work on the larger persistent drive. |
| | MC-02-05 | done | Add a worktree-root convention to the mission runtime notes and startup guidance so agents prefer `/src/<repo>-worktrees` over `/tmp`. | — | haiku | docs/mission-control-worktree-root | MC-01-03 | 3K | Keep long-lived work on the larger persistent drive. |
**Milestone 2 estimate:** ~20K tokens
@@ -47,7 +47,7 @@ Goal: make missions first-class runtime objects that can survive session restart
Goal: derive assignable tasks from the PRD and keep them linked to mission state.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | ------------------------------------------------------------------------------------------- | ----- | ------ | -------------------------------- | ------------------ | -------- | ------------------------------------------- |
| MC-03-01 | not-started | Add a PRD-to-task decomposition rule set: every user story maps to one or more board tasks. | — | sonnet | feat/mission-control-decompose | MC-01-01 | 5K | Start simple and deterministic. |
| MC-03-02 | not-started | Implement board generation from the PRD in a machine-readable format. | — | codex | feat/mission-control-board-gen | MC-03-01 | 6K | Output should be usable by the coordinator. |
| MC-03-03 | not-started | Add dependency validation so tasks cannot start before parent tasks complete. | — | codex | feat/mission-control-deps | MC-03-02 | 5K | Enforces ordering. |
@@ -63,7 +63,7 @@ Goal: derive assignable tasks from the PRD and keep them linked to mission state
Goal: detect when a session is stuck and rotate to a fresh session before quality falls off.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------------- | ---------- | -------- | ---------------------------------------------- |
| MC-04-01 | not-started | Define churn signals: repeated compaction, identical tool loops, repeated permission prompts, and no progress across several turns. | — | sonnet | feat/mission-control-churn-signals | MC-02-01 | 4K | Keep the rules explicit. |
| MC-04-02 | not-started | Implement churn scoring in the coordinator with configurable thresholds. | — | codex | feat/mission-control-churn-score | MC-04-01 | 6K | Weighted score makes tuning easier. |
| MC-04-03 | not-started | Implement automatic session rotation when churn crosses the threshold. | — | codex | feat/mission-control-rotate-session | MC-04-02 | 6K | The session is disposable; the mission is not. |
@@ -78,7 +78,7 @@ Goal: detect when a session is stuck and rotate to a fresh session before qualit
Goal: preserve the best context from the old session and inject it into the new session cleanly.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------------------- | ------------------ | -------- | ---------------------------------------- |
| MC-05-01 | not-started | Define the handoff packet schema: mission ID, session ID, completed work, blockers, next 3 actions, and constraints. | — | sonnet | feat/mission-control-handoff-schema | MC-02-01 | 4K | Keep it compact and structured. |
| MC-05-02 | not-started | Implement handoff packet writing during rotation. | — | codex | feat/mission-control-handoff-write | MC-05-01, MC-04-03 | 5K | Persist before the old session exits. |
| MC-05-03 | not-started | Implement handoff packet loading at session startup. | — | codex | feat/mission-control-handoff-load | MC-05-01, MC-04-03 | 5K | New session should know the next action. |
@@ -93,7 +93,7 @@ Goal: preserve the best context from the old session and inject it into the new
Goal: expose the whole workflow through commands and verify it end-to-end.
| id | status | description | issue | agent | branch | depends_on | estimate | notes |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| -------- | ----------- | --------------------------------------------------------------------------------------------------------- | ----- | ------ | -------------------------------- | ------------------ | -------- | -------------------------------------------- |
| MC-06-01 | not-started | Add a CLI command to inspect the active mission, PRD path, board path, task statuses, and latest handoff. | — | codex | feat/mission-control-inspect-cli | MC-02-03, MC-05-03 | 5K | One place to inspect the whole stack. |
| MC-06-02 | not-started | Add a compact dashboard or TUI summary view for mission health. | — | codex | feat/mission-control-summary-ui | MC-06-01 | 6K | Nice to have, but not before the core works. |
| MC-06-03 | not-started | Build an E2E harness that simulates compaction / rotation and verifies the mission can continue. | — | sonnet | feat/mission-control-e2e-harness | MC-04-03, MC-05-03 | 8K | This is the proof that the design works. |

18
docs/plans/2026-05-06-hermes-mosaic-alignment.md
View File

@@ -15,7 +15,7 @@
### What Mosaic has that Hermes needs
| Mosaic Component | What it does | Natural Hermes home | Why |
|---|---|---|---|
| -------------------------------- | --------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packages/coord` (mission.ts) | Mission CRUD, session tracking, milestone state | **Hermes toolset: `mission`** | Mission state is session-scoped, not gateway-scoped. Hermes sessions already have identity, process tracking, and context windows. |
| `packages/coord` (tasks-file.ts) | Parse/write TASKS.md tables | **Hermes toolset: `mission`** (same) | Hermes already reads/writes files. The TASKS.md parser is ~300 lines of pure string manipulation — trivial Python port. |
| `packages/coord` (runner.ts) | Spawn claude/codex workers with continuation prompts | **Already covered by `delegate_task`** | Hermes delegate_task already does isolated subagent spawning with restricted toolsets. The runner's "find next task and build continuation prompt" logic moves into a tool-call. |
@@ -29,7 +29,7 @@
### What Hermes already has that replaces Mosaic infrastructure
| Mosaic concept | Hermes equivalent | Notes |
|---|---|---|
| -------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Gateway (NestJS) | Hermes gateway | Hermes already has a gateway with WebSocket, Discord, Telegram, CLI. No need for a second one. |
| Pi SDK agent runtime | Hermes agent loop | Hermes IS the agent runtime. OpenClaw's Pi SDK is a different runtime that Mosaic targets. |
| MACP ACP bridge | `delegate_task` + ACP tools | Same capability, already native. |
@@ -42,7 +42,7 @@
### What Mosaic keeps as its own entity
| Component | Why it stays in Mosaic |
|---|---|
| --------------------- | --------------------------------------------------- |
| `apps/gateway` | NestJS API surface — Mosaic's web platform offering |
| `apps/web` | Next.js dashboard — Mosaic's UI offering |
| `packages/types` | Shared TS contracts for Mosaic gateway plugins |
@@ -74,7 +74,7 @@ mission_handoff.py — Handoff packet generation and loading
### Tool-calls exposed to the agent
| Tool | What it does | When the agent calls it |
|---|---|---|
| --------------------- | --------------------------------------------------------------------------------- | ------------------------------------------- |
| `mission_create` | Initialize mission.json + TASKS.md + MISSION-MANIFEST.md in a project dir | When starting a new mission |
| `mission_status` | Read current mission state, milestone progress, next task, active session | At session start, or when checking progress |
| `mission_next_task` | Find the next `not-started` task whose dependencies are met, return its full spec | When the agent needs work to do |
@@ -89,7 +89,6 @@ The `mission` toolset follows the same pattern as `kanban`:
1. **Gating**: Tools are available when:
- The profile has `mission` in its toolsets config, OR
- A `HERMES_MISSION_DIR` env var is set (cron/dispatcher spawned workers)
2. **File conventions**: The toolset reads/writes the same file formats as Mosaic `packages/coord`:
- `.mosaic/orchestrator/mission.json` — mission state
- `docs/TASKS.md` — task table
@@ -108,6 +107,7 @@ Churn detection lives in Hermes's turn loop, NOT as a tool-call. It observes:
- Repeated permission denials
When churn score exceeds threshold:
1. `mission_handoff` is called automatically
2. Session is rotated (fresh context window)
3. `mission_resume` is called in the new session
@@ -121,7 +121,7 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
### Phase 1: Core state management (Python port of coord)
| Task | Files | Estimate |
|---|---|---|
| -------------------------------------------------- | ----------------------------- | -------- |
| 1.1 Port mission.json read/write to Python | `mission_state.py` | 2h |
| 1.2 Port TASKS.md parser to Python | `mission_state.py` | 2h |
| 1.3 Port MISSION-MANIFEST.md reader to Python | `mission_state.py` | 1h |
@@ -139,7 +139,7 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
### Phase 2: Handoff and session continuity
| Task | Files | Estimate |
|---|---|---|
| ------------------------------------------------- | ---------------------------------------- | -------- |
| 2.1 Define handoff packet schema (JSON) | `mission_handoff.py` | 1h |
| 2.2 Implement `mission_handoff` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
| 2.3 Implement `mission_resume` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
@@ -151,7 +151,7 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
### Phase 3: Churn detection
| Task | Files | Estimate |
|---|---|---|
| -------------------------------------------------------------- | ----------------------------- | -------- |
| 3.1 Define churn signal weights and thresholds | `mission_churn.py` | 1h |
| 3.2 Implement tool-loop detector (consecutive identical calls) | `mission_churn.py` | 2h |
| 3.3 Implement compaction pressure detector | `mission_churn.py` | 1h |
@@ -165,7 +165,7 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
### Phase 4: Kanban bridge + CLI surface
| Task | Files | Estimate |
|---|---|---|
| ---------------------------------------------------- | ------------------------ | -------- |
| 4.1 Implement TASKS.md → Kanban sync (one-way first) | `mission_kanban_sync.py` | 2h |
| 4.2 Add `hermes mission` CLI subcommand | `mission_cli.py` | 2h |
| 4.3 Add `hermes mission status` command | `mission_cli.py` | 1h |

3
docs/plans/2026-05-07-coordination-resilience.md
View File

@@ -116,6 +116,7 @@ This watcher prevents stale tasks from clogging the board and keeps the dispatch
```markdown
## Distress Signal
- Blocked task: t_xxx
- Worker: <profile_name>
- Branch: <git_branch_name>
@@ -127,6 +128,7 @@ This watcher prevents stale tasks from clogging the board and keeps the dispatch
- State: committed | uncommitted | stashed(<stash_name>)
## Scope Guard
DO NOT touch: anything outside diagnosing and remediating the blocker described above
Only fix: assign, split, reassign, or unblock the source task
```
@@ -163,6 +165,7 @@ Never reassign rate-limited work back to the same provider if the failure was pr
- Mission packet recovery contract: `/opt/hermes/docs/mission-toolset-heartbeat.md`
- Hermes mission implementation plan: `/opt/hermes/docs/plans/mission-toolset-implementation.md`
- The same packet-first resume rule applies: inspect the latest packet before re-reading mission files.
- New-session trigger: when a profile config changes, start a fresh session or `/reset` so the updated toolset is actually loaded.
## Watchers to implement