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

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

@@ -14,22 +14,22 @@
## Feature Board ## Feature Board
| Feature Card | Need | Priority | Decision / Notes | | 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 | | 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 | | 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 | | Board atomization | Break PRD into assignable tasks with dependencies | Must-have | Each user story should map to one or more tasks |
| Short-cycle detector | Detect compaction churn and repeated tool loops | Must-have | Coordinator should track churn score per session | | Short-cycle detector | Detect compaction churn and repeated tool loops | Must-have | Coordinator should track churn score per session |
| Handoff packet | Preserve actionable context across rotations | Must-have | Use a compact structured summary, not a raw transcript | | Handoff packet | Preserve actionable context across rotations | Must-have | Use a compact structured summary, not a raw transcript |
| Auto-resume workers | Let new sessions read mission + board on start | Should-have | Makes overnight autonomy realistic | | Auto-resume workers | Let new sessions read mission + board on start | Should-have | Makes overnight autonomy realistic |
| Mission status view | Show current phase, blockers, and active session | Should-have | Expose through CLI first, dashboard later | | Mission status view | Show current phase, blockers, and active session | Should-have | Expose through CLI first, dashboard later |
| Worktree root convention | Keep worktrees off `/tmp` and on the larger persistent drive | Should-have | Prefer `/src/<repo>-worktrees` for repo worktrees and long-lived agent work | | Worktree root convention | Keep worktrees off `/tmp` and on the larger persistent drive | Should-have | Prefer `/src/<repo>-worktrees` for repo worktrees and long-lived agent work |
| Review gate | Prevent autonomous work from shipping unreviewed | Should-have | Use reviewer tasks before mission close | | Review gate | Prevent autonomous work from shipping unreviewed | Should-have | Use reviewer tasks before mission close |
| Rotation policy config | Configure thresholds per mission/profile | Could-have | Keep v1 simple, add tuning later | | Rotation policy config | Configure thresholds per mission/profile | Could-have | Keep v1 simple, add tuning later |
| Goal decomposition suggestions | Suggest sub-goals from the PRD | Could-have | Good for planning, not necessary for core path | | Goal decomposition suggestions | Suggest sub-goals from the PRD | Could-have | Good for planning, not necessary for core path |
| Cross-channel continuity | Continue a mission across CLI/gateway/remote channels | Could-have | Important later, not required for MVP | | Cross-channel continuity | Continue a mission across CLI/gateway/remote channels | Could-have | Important later, not required for MVP |
| Automatic board sync | Mirror git docs into DB and back | Could-have | Nice-to-have after the file-first flow stabilizes | | Automatic board sync | Mirror git docs into DB and back | Could-have | Nice-to-have after the file-first flow stabilizes |
| Fully autonomous closeout | Let mission finish without human intervention | Won't-have | Keep an operator-visible review step | | Fully autonomous closeout | Let mission finish without human intervention | Won't-have | Keep an operator-visible review step |
--- ---
@@ -52,6 +52,7 @@
**Question:** What should trigger a forced session rotation? **Question:** What should trigger a forced session rotation?
**Candidate signals:** **Candidate signals:**
- repeated compaction - repeated compaction
- repeated prompts for permission - repeated prompts for permission
- identical tool loops - identical tool loops
@@ -65,6 +66,7 @@
**Question:** What should the next session receive? **Question:** What should the next session receive?
**Proposed answer:** **Proposed answer:**
- Mission ID - Mission ID
- PRD path - PRD path
- Active board task - Active board task

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

@@ -57,36 +57,36 @@ Design references:
## Milestones ## Milestones
| # | ID | Name | Status | Branch | Started | Completed | | # | 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 | — | — | — | | 2 | MC-02 | Mission runtime model | not-started | — | — | — |
| 3 | MC-03 | Board atomization and task linkage | not-started | — | — | — | | 3 | MC-03 | Board atomization and task linkage | not-started | — | — | — |
| 4 | MC-04 | Short-cycle detector and rotation engine | not-started | — | — | — | | 4 | MC-04 | Short-cycle detector and rotation engine | not-started | — | — | — |
| 5 | MC-05 | Handoff generation and re-entry | not-started | — | — | — | | 5 | MC-05 | Handoff generation and re-entry | not-started | — | — | — |
| 6 | MC-06 | Operator surface and E2E validation | not-started | — | — | — | | 6 | MC-06 | Operator surface and E2E validation | not-started | — | — | — |
--- ---
## Budget ## Budget
| Milestone | Est. tokens | Parallelizable? | | Milestone | Est. tokens | Parallelizable? |
| --- | --- | --- | | --------- | ----------- | ------------------ |
| MC-01 | 16K | No | | MC-01 | 16K | No |
| MC-02 | 20K | No | | MC-02 | 20K | No |
| MC-03 | 24K | Mostly after MC-01 | | MC-03 | 24K | Mostly after MC-01 |
| MC-04 | 20K | After MC-02 | | MC-04 | 20K | After MC-02 |
| MC-05 | 18K | After MC-04 | | MC-05 | 18K | After MC-04 |
| MC-06 | 26K | After MC-04/05 | | MC-06 | 26K | After MC-04/05 |
| **Total** | **~124K** | | | **Total** | **~124K** | |
--- ---
## Session History ## Session History
| Session | Date | Runtime | Outcome | | Session | Date | Runtime | Outcome |
| --- | --- | --- | --- | | ------- | ---------- | ------- | ------------------------------------------------------------------------ |
| S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted | | S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted |
--- ---

25
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. **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:** **Acceptance Criteria:**
- [ ] `prdy` can emit a PRD with goals, non-goals, and requirements. - [ ] `prdy` can emit a PRD with goals, non-goals, and requirements.
- [ ] The PRD is linked to a mission ID. - [ ] The PRD is linked to a mission ID.
- [ ] The mission manifest references the PRD path. - [ ] 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. **Description:** As an orchestrator, I want to split a PRD into board tasks so that work can be assigned to specialists.
**Acceptance Criteria:** **Acceptance Criteria:**
- [ ] Each user story can become one or more tasks. - [ ] Each user story can become one or more tasks.
- [ ] Tasks have assignees, dependencies, and estimates. - [ ] Tasks have assignees, dependencies, and estimates.
- [ ] Tasks are machine-readable and durable. - [ ] 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. **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:** **Acceptance Criteria:**
- [ ] The coordinator detects compaction pressure or repeated loops. - [ ] The coordinator detects compaction pressure or repeated loops.
- [ ] The coordinator writes a handoff summary before rotation. - [ ] The coordinator writes a handoff summary before rotation.
- [ ] A new session can resume from the handoff packet. - [ ] 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. **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:** **Acceptance Criteria:**
- [ ] Startup loads the active mission manifest. - [ ] Startup loads the active mission manifest.
- [ ] Startup loads the current board/task row. - [ ] Startup loads the current board/task row.
- [ ] Startup exposes the next action clearly in the prompt. - [ ] 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. **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:** **Acceptance Criteria:**
- [ ] Mission state shows current phase and progress. - [ ] Mission state shows current phase and progress.
- [ ] Board state shows task status by assignee. - [ ] Board state shows task status by assignee.
- [ ] Short-cycle/rotation events are visible. - [ ] Short-cycle/rotation events are visible.
@@ -140,16 +145,16 @@ 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. This is the feature discussion board that should drive the mission design.
| Card | Need | Why it matters | Proposed decision | | 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 | | 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 | | 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 | | Session watchdog | Detect churn/short-cycling | Keeps overnight runs productive | Add short-cycle scoring and forced rotation |
| Structured handoff | Preserve context across session changes | Minimizes restart loss | Use a compact JSON/MD handoff packet | | Structured handoff | Preserve context across session changes | Minimizes restart loss | Use a compact JSON/MD handoff packet |
| Worker auto-read | Let agents resume without human re-prompting | Reduces operator overhead | Load mission + board on session start | | Worker auto-read | Let agents resume without human re-prompting | Reduces operator overhead | Load mission + board on session start |
| Status surface | Show progress and blockers clearly | Operators need confidence | Expose mission state via CLI and dashboard | | Status surface | Show progress and blockers clearly | Operators need confidence | Expose mission state via CLI and dashboard |
| Review gate | Keep quality high on autonomous work | Prevents silent regressions | Require review tasks before close | | Review gate | Keep quality high on autonomous work | Prevents silent regressions | Require review tasks before close |
| Recoverability | Resume after failure or restart | Mission should outlive a process | Persist session and handoff history | | Recoverability | Resume after failure or restart | Mission should outlive a process | Persist session and handoff history |
--- ---

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

@@ -15,12 +15,12 @@
Goal: create the durable doc structure and the minimal mission metadata needed to keep PRD, board, and mission aligned. 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 | | 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-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-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. | | 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. |
| MC-01-04 | not-started | Write `docs/mission-control/TASKS.md` with the atomized execution plan and dependency graph. | — | sonnet | docs/mission-control-tasks | MC-01-03 | 4K | Board-backed execution plan. | | MC-01-04 | not-started | Write `docs/mission-control/TASKS.md` with the atomized execution plan and dependency graph. | — | sonnet | docs/mission-control-tasks | MC-01-03 | 4K | Board-backed execution plan. |
**Milestone 1 estimate:** ~16K tokens **Milestone 1 estimate:** ~16K tokens
@@ -30,13 +30,13 @@ 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. Goal: make missions first-class runtime objects that can survive session restarts and compaction.
| id | status | description | issue | agent | branch | depends_on | estimate | notes | | 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-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-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-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-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 **Milestone 2 estimate:** ~20K tokens
@@ -46,13 +46,13 @@ 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. Goal: derive assignable tasks from the PRD and keep them linked to mission state.
| id | status | description | issue | agent | branch | depends_on | estimate | notes | | 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-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-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. | | 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. |
| MC-03-04 | not-started | Add review-task support so a mission cannot close without a reviewer step. | — | sonnet | feat/mission-control-review-gate | MC-03-03 | 4K | Preserves quality. | | MC-03-04 | not-started | Add review-task support so a mission cannot close without a reviewer step. | — | sonnet | feat/mission-control-review-gate | MC-03-03 | 4K | Preserves quality. |
| MC-03-05 | not-started | Add tests proving the board stays traceable back to the PRD user stories. | — | haiku | feat/mission-control-trace-tests | MC-03-02, MC-03-03 | 4K | Traceability is the point. | | MC-03-05 | not-started | Add tests proving the board stays traceable back to the PRD user stories. | — | haiku | feat/mission-control-trace-tests | MC-03-02, MC-03-03 | 4K | Traceability is the point. |
**Milestone 3 estimate:** ~24K tokens **Milestone 3 estimate:** ~24K tokens
@@ -62,12 +62,12 @@ 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. 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 | | 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-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-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. | | 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. |
| MC-04-04 | not-started | Add tests for rotation triggers and for avoiding premature rotation. | — | haiku | feat/mission-control-rotation-tests | MC-04-03 | 4K | Prevent flapping. | | MC-04-04 | not-started | Add tests for rotation triggers and for avoiding premature rotation. | — | haiku | feat/mission-control-rotation-tests | MC-04-03 | 4K | Prevent flapping. |
**Milestone 4 estimate:** ~20K tokens **Milestone 4 estimate:** ~20K tokens
@@ -77,12 +77,12 @@ 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. 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 | | 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-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-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. | | 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. |
| MC-05-04 | not-started | Add tests proving a rotated session can continue the mission without manual re-prompting. | — | haiku | feat/mission-control-handoff-tests | MC-05-02, MC-05-03 | 4K | Resume quality is the key metric. | | MC-05-04 | not-started | Add tests proving a rotated session can continue the mission without manual re-prompting. | — | haiku | feat/mission-control-handoff-tests | MC-05-02, MC-05-03 | 4K | Resume quality is the key metric. |
**Milestone 5 estimate:** ~18K tokens **Milestone 5 estimate:** ~18K tokens
@@ -92,13 +92,13 @@ 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. Goal: expose the whole workflow through commands and verify it end-to-end.
| id | status | description | issue | agent | branch | depends_on | estimate | notes | | 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-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-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. | | 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. |
| MC-06-04 | not-started | Add final docs for operators explaining how PRD, mission, and board fit together. | — | haiku | feat/mission-control-ops-docs | MC-06-03 | 4K | Make it usable by humans. | | MC-06-04 | not-started | Add final docs for operators explaining how PRD, mission, and board fit together. | — | haiku | feat/mission-control-ops-docs | MC-06-03 | 4K | Make it usable by humans. |
| MC-06-05 | not-started | Consolidate review findings and close the mission with a release note. | — | sonnet | chore/mission-control-close | MC-06-04 | 3K | Only after the E2E passes. | | MC-06-05 | not-started | Consolidate review findings and close the mission with a release note. | — | sonnet | chore/mission-control-close | MC-06-04 | 3K | Only after the E2E passes. |
**Milestone 6 estimate:** ~26K tokens **Milestone 6 estimate:** ~26K tokens

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

@@ -14,45 +14,45 @@
### What Mosaic has that Hermes needs ### What Mosaic has that Hermes needs
| Mosaic Component | What it does | Natural Hermes home | Why | | 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` (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` (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. | | `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. |
| `packages/coord` (status.ts) | Mission health, task progress, next task | **Hermes toolset: `mission`** (same) | Status readout fits naturally as a tool-call. No gateway needed. | | `packages/coord` (status.ts) | Mission health, task progress, next task | **Hermes toolset: `mission`** (same) | Status readout fits naturally as a tool-call. No gateway needed. |
| `packages/prdy` | PRD generation wizard | **Hermes skill: `prdy`** | PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit. | | `packages/prdy` | PRD generation wizard | **Hermes skill: `prdy`** | PRD generation is a prompt + template problem, not infrastructure. A Hermes skill with templates is the right fit. |
| `plugins/mosaic-framework` | before_agent_start + subagent_spawning hooks | **Hermes system prompt injection** | Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile. | | `plugins/mosaic-framework` | before_agent_start + subagent_spawning hooks | **Hermes system prompt injection** | Hermes already injects system context via skills and config. The framework preamble and worktree rules become standard Hermes skills loaded by the orchestrator profile. |
| `plugins/macp` | OpenClaw ACP bridge (spawn codex/claude) | **Already covered by `delegate_task` + ACP** | Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes. | | `plugins/macp` | OpenClaw ACP bridge (spawn codex/claude) | **Already covered by `delegate_task` + ACP** | Hermes already has ACP support and delegate_task. The MACP bridge is redundant when running natively in Hermes. |
| Churn detection (planned) | Detect compaction loops, repeated tool calls, no progress | **Hermes middleware** | This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside. | | Churn detection (planned) | Detect compaction loops, repeated tool calls, no progress | **Hermes middleware** | This needs to live inside Hermes's turn loop where it can observe tool-call patterns. Mosaic can't see this from outside. |
| Handoff packet (planned) | Structured context summary for session rotation | **Hermes toolset: `mission`** | Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff. | | Handoff packet (planned) | Structured context summary for session rotation | **Hermes toolset: `mission`** | Handoff is a serialization of mission + session state. Hermes owns the session, so it should own the handoff. |
### What Hermes already has that replaces Mosaic infrastructure ### What Hermes already has that replaces Mosaic infrastructure
| Mosaic concept | Hermes equivalent | Notes | | 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. | | 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. | | 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. | | MACP ACP bridge | `delegate_task` + ACP tools | Same capability, already native. |
| Session identity | Hermes session IDs + process_registry | Hermes already tracks session identity, PIDs, and background processes. | | Session identity | Hermes session IDs + process_registry | Hermes already tracks session identity, PIDs, and background processes. |
| Task execution board | Hermes Kanban | Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments. | | Task execution board | Hermes Kanban | Fully functional SQLite-backed Kanban with dispatcher, triage, events, comments. |
| Worker spawning | Hermes dispatcher + cron | Kanban dispatcher + cron already handle this. | | Worker spawning | Hermes dispatcher + cron | Kanban dispatcher + cron already handle this. |
| Context injection | Hermes skills + system prompt | Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does. | | Context injection | Hermes skills + system prompt | Skills are loaded at session start and injected into context. Exactly what mosaic-framework plugin does. |
| File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. | | File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. |
### What Mosaic keeps as its own entity ### What Mosaic keeps as its own entity
| Component | Why it stays in Mosaic | | Component | Why it stays in Mosaic |
|---|---| | --------------------- | --------------------------------------------------- |
| `apps/gateway` | NestJS API surface — Mosaic's web platform offering | | `apps/gateway` | NestJS API surface — Mosaic's web platform offering |
| `apps/web` | Next.js dashboard — Mosaic's UI offering | | `apps/web` | Next.js dashboard — Mosaic's UI offering |
| `packages/types` | Shared TS contracts for Mosaic gateway plugins | | `packages/types` | Shared TS contracts for Mosaic gateway plugins |
| `packages/db` | Drizzle ORM + PG — Mosaic's data layer | | `packages/db` | Drizzle ORM + PG — Mosaic's data layer |
| `packages/auth` | BetterAuth — Mosaic's auth system | | `packages/auth` | BetterAuth — Mosaic's auth system |
| `packages/brain` | PG-backed data layer for Mosaic web app | | `packages/brain` | PG-backed data layer for Mosaic web app |
| `packages/queue` | Valkey task queue for Mosaic gateway | | `packages/queue` | Valkey task queue for Mosaic gateway |
| `plugins/discord` | OpenClaw Discord plugin | | `plugins/discord` | OpenClaw Discord plugin |
| `plugins/telegram` | OpenClaw Telegram plugin | | `plugins/telegram` | OpenClaw Telegram plugin |
| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface | | `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface |
--- ---
@@ -61,7 +61,7 @@
### New files under `/opt/hermes/tools/` ### New files under `/opt/hermes/tools/`
``` ```
mission_tools.py — Tool-call surface (mission_create, mission_status, mission_tools.py — Tool-call surface (mission_create, mission_status,
mission_next_task, mission_update_task, mission_handoff, mission_next_task, mission_update_task, mission_handoff,
mission_resume) mission_resume)
mission_state.py — State management (read/write mission.json, parse TASKS.md, mission_state.py — State management (read/write mission.json, parse TASKS.md,
@@ -73,14 +73,14 @@ mission_handoff.py — Handoff packet generation and loading
### Tool-calls exposed to the agent ### Tool-calls exposed to the agent
| Tool | What it does | When the agent calls it | | 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_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_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 | | `mission_next_task` | Find the next `not-started` task whose dependencies are met, return its full spec | When the agent needs work to do |
| `mission_update_task` | Update a task row status in TASKS.md | When completing or blocking a task | | `mission_update_task` | Update a task row status in TASKS.md | When completing or blocking a task |
| `mission_handoff` | Generate a handoff packet from current session context + mission state | Before session rotation or at session end | | `mission_handoff` | Generate a handoff packet from current session context + mission state | Before session rotation or at session end |
| `mission_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation | | `mission_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation |
### Toolset registration ### Toolset registration
@@ -89,7 +89,6 @@ The `mission` toolset follows the same pattern as `kanban`:
1. **Gating**: Tools are available when: 1. **Gating**: Tools are available when:
- The profile has `mission` in its toolsets config, OR - The profile has `mission` in its toolsets config, OR
- A `HERMES_MISSION_DIR` env var is set (cron/dispatcher spawned workers) - 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`: 2. **File conventions**: The toolset reads/writes the same file formats as Mosaic `packages/coord`:
- `.mosaic/orchestrator/mission.json` — mission state - `.mosaic/orchestrator/mission.json` — mission state
- `docs/TASKS.md` — task table - `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 - Repeated permission denials
When churn score exceeds threshold: When churn score exceeds threshold:
1. `mission_handoff` is called automatically 1. `mission_handoff` is called automatically
2. Session is rotated (fresh context window) 2. Session is rotated (fresh context window)
3. `mission_resume` is called in the new session 3. `mission_resume` is called in the new session
@@ -120,58 +120,58 @@ This is new infrastructure that only Hermes can provide (Mosaic runs outside the
### Phase 1: Core state management (Python port of coord) ### Phase 1: Core state management (Python port of coord)
| Task | Files | Estimate | | Task | Files | Estimate |
|---|---|---| | -------------------------------------------------- | ----------------------------- | -------- |
| 1.1 Port mission.json read/write to Python | `mission_state.py` | 2h | | 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.2 Port TASKS.md parser to Python | `mission_state.py` | 2h |
| 1.3 Port MISSION-MANIFEST.md reader to Python | `mission_state.py` | 1h | | 1.3 Port MISSION-MANIFEST.md reader to Python | `mission_state.py` | 1h |
| 1.4 Implement `mission_create` tool-call | `mission_tools.py` | 1h | | 1.4 Implement `mission_create` tool-call | `mission_tools.py` | 1h |
| 1.5 Implement `mission_status` tool-call | `mission_tools.py` | 1h | | 1.5 Implement `mission_status` tool-call | `mission_tools.py` | 1h |
| 1.6 Implement `mission_next_task` tool-call | `mission_tools.py` | 1h | | 1.6 Implement `mission_next_task` tool-call | `mission_tools.py` | 1h |
| 1.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h | | 1.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h |
| 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m | | 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m |
| 1.9 Add `mission` to orchestrator profile toolsets | `config.yaml` | 10m | | 1.9 Add `mission` to orchestrator profile toolsets | `config.yaml` | 10m |
| 1.10 Write unit tests for mission_state | `tests/test_mission_state.py` | 2h | | 1.10 Write unit tests for mission_state | `tests/test_mission_state.py` | 2h |
| 1.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h | | 1.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h |
**Phase 1 estimate:** ~13h **Phase 1 estimate:** ~13h
### Phase 2: Handoff and session continuity ### Phase 2: Handoff and session continuity
| Task | Files | Estimate | | Task | Files | Estimate |
|---|---|---| | ------------------------------------------------- | ---------------------------------------- | -------- |
| 2.1 Define handoff packet schema (JSON) | `mission_handoff.py` | 1h | | 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.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 | | 2.3 Implement `mission_resume` tool-call | `mission_handoff.py`, `mission_tools.py` | 2h |
| 2.4 Wire handoff into session start (auto-resume) | agent loop hook | 2h | | 2.4 Wire handoff into session start (auto-resume) | agent loop hook | 2h |
| 2.5 Write tests for handoff round-trip | `tests/test_mission_handoff.py` | 1h | | 2.5 Write tests for handoff round-trip | `tests/test_mission_handoff.py` | 1h |
**Phase 2 estimate:** ~8h **Phase 2 estimate:** ~8h
### Phase 3: Churn detection ### Phase 3: Churn detection
| Task | Files | Estimate | | Task | Files | Estimate |
|---|---|---| | -------------------------------------------------------------- | ----------------------------- | -------- |
| 3.1 Define churn signal weights and thresholds | `mission_churn.py` | 1h | | 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.2 Implement tool-loop detector (consecutive identical calls) | `mission_churn.py` | 2h |
| 3.3 Implement compaction pressure detector | `mission_churn.py` | 1h | | 3.3 Implement compaction pressure detector | `mission_churn.py` | 1h |
| 3.4 Implement progress scorer (file state delta) | `mission_churn.py` | 2h | | 3.4 Implement progress scorer (file state delta) | `mission_churn.py` | 2h |
| 3.5 Wire churn scoring into agent turn loop | agent loop middleware | 2h | | 3.5 Wire churn scoring into agent turn loop | agent loop middleware | 2h |
| 3.6 Implement auto-rotation trigger | agent loop + handoff | 2h | | 3.6 Implement auto-rotation trigger | agent loop + handoff | 2h |
| 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h | | 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h |
**Phase 3 estimate:** ~11h **Phase 3 estimate:** ~11h
### Phase 4: Kanban bridge + CLI surface ### Phase 4: Kanban bridge + CLI surface
| Task | Files | Estimate | | Task | Files | Estimate |
|---|---|---| | ---------------------------------------------------- | ------------------------ | -------- |
| 4.1 Implement TASKS.md → Kanban sync (one-way first) | `mission_kanban_sync.py` | 2h | | 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.2 Add `hermes mission` CLI subcommand | `mission_cli.py` | 2h |
| 4.3 Add `hermes mission status` command | `mission_cli.py` | 1h | | 4.3 Add `hermes mission status` command | `mission_cli.py` | 1h |
| 4.4 Add `hermes mission init` command | `mission_cli.py` | 1h | | 4.4 Add `hermes mission init` command | `mission_cli.py` | 1h |
| 4.5 Add `hermes mission handoff` command | `mission_cli.py` | 1h | | 4.5 Add `hermes mission handoff` command | `mission_cli.py` | 1h |
| 4.6 Add `hermes mission resume` command | `mission_cli.py` | 1h | | 4.6 Add `hermes mission resume` command | `mission_cli.py` | 1h |
**Phase 4 estimate:** ~8h **Phase 4 estimate:** ~8h

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 ```markdown
## Distress Signal ## Distress Signal
- Blocked task: t_xxx - Blocked task: t_xxx
- Worker: <profile_name> - Worker: <profile_name>
- Branch: <git_branch_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>) - State: committed | uncommitted | stashed(<stash_name>)
## Scope Guard ## Scope Guard
DO NOT touch: anything outside diagnosing and remediating the blocker described above DO NOT touch: anything outside diagnosing and remediating the blocker described above
Only fix: assign, split, reassign, or unblock the source task 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` - Mission packet recovery contract: `/opt/hermes/docs/mission-toolset-heartbeat.md`
- Hermes mission implementation plan: `/opt/hermes/docs/plans/mission-toolset-implementation.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. - 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 ## Watchers to implement