From 647fd9a8356a9fd1191f212f60e2c4c400106f5c Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 7 May 2026 13:31:43 -0500 Subject: [PATCH] docs: note new-session trigger for mission toolset reload --- docs/mission-control/BOARD.md | 34 ++-- docs/mission-control/MISSION-MANIFEST.md | 40 ++--- docs/mission-control/PRD.md | 25 +-- docs/mission-control/TASKS.md | 78 ++++----- .../2026-05-06-hermes-mosaic-alignment.md | 160 +++++++++--------- .../2026-05-07-coordination-resilience.md | 3 + 6 files changed, 175 insertions(+), 165 deletions(-) diff --git a/docs/mission-control/BOARD.md b/docs/mission-control/BOARD.md index 241efd9..a0f1539 100644 --- a/docs/mission-control/BOARD.md +++ b/docs/mission-control/BOARD.md @@ -14,22 +14,22 @@ ## 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 | -| 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 | -| 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 | -| Worktree root convention | Keep worktrees off `/tmp` and on the larger persistent drive | Should-have | Prefer `/src/-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 | -| 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 | -| 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 | -| Fully autonomous closeout | Let mission finish without human intervention | Won't-have | Keep an operator-visible review step | +| 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 | +| 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 | +| 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 | +| Worktree root convention | Keep worktrees off `/tmp` and on the larger persistent drive | Should-have | Prefer `/src/-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 | +| 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 | +| 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 | +| 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? **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 diff --git a/docs/mission-control/MISSION-MANIFEST.md b/docs/mission-control/MISSION-MANIFEST.md index 1d7a21b..54a3029 100644 --- a/docs/mission-control/MISSION-MANIFEST.md +++ b/docs/mission-control/MISSION-MANIFEST.md @@ -57,36 +57,36 @@ Design references: ## Milestones -| # | ID | Name | Status | Branch | Started | Completed | -| --- | --- | --- | --- | --- | --- | --- | -| 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 | — | — | — | -| 5 | MC-05 | Handoff generation and re-entry | not-started | — | — | — | -| 6 | MC-06 | Operator surface and E2E validation | not-started | — | — | — | +| # | ID | Name | Status | Branch | Started | Completed | +| --- | ----- | ---------------------------------------- | ----------- | ----------------------- | ---------- | --------- | +| 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 | — | — | — | +| 5 | MC-05 | Handoff generation and re-entry | not-started | — | — | — | +| 6 | MC-06 | Operator surface and E2E validation | not-started | — | — | — | --- ## Budget -| Milestone | Est. tokens | Parallelizable? | -| --- | --- | --- | -| MC-01 | 16K | No | -| MC-02 | 20K | No | -| MC-03 | 24K | Mostly after MC-01 | -| MC-04 | 20K | After MC-02 | -| MC-05 | 18K | After MC-04 | -| MC-06 | 26K | After MC-04/05 | -| **Total** | **~124K** | | +| Milestone | Est. tokens | Parallelizable? | +| --------- | ----------- | ------------------ | +| MC-01 | 16K | No | +| MC-02 | 20K | No | +| MC-03 | 24K | Mostly after MC-01 | +| MC-04 | 20K | After MC-02 | +| MC-05 | 18K | After MC-04 | +| MC-06 | 26K | After MC-04/05 | +| **Total** | **~124K** | | --- ## Session History -| Session | Date | Runtime | Outcome | -| --- | --- | --- | --- | -| S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted | +| Session | Date | Runtime | Outcome | +| ------- | ---------- | ------- | ------------------------------------------------------------------------ | +| S1 | 2026-05-06 | hermes | PRD, board, task plan, mission manifest, and worktree convention drafted | --- diff --git a/docs/mission-control/PRD.md b/docs/mission-control/PRD.md index 43b2cb1..4f6dc1f 100644 --- a/docs/mission-control/PRD.md +++ b/docs/mission-control/PRD.md @@ -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. @@ -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. -| 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 | -| 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 | -| 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 | -| Recoverability | Resume after failure or restart | Mission should outlive a process | Persist session and handoff history | +| 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 | +| 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 | +| 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 | +| Recoverability | Resume after failure or restart | Mission should outlive a process | Persist session and handoff history | --- diff --git a/docs/mission-control/TASKS.md b/docs/mission-control/TASKS.md index 06f2201..e9e8b0e 100644 --- a/docs/mission-control/TASKS.md +++ b/docs/mission-control/TASKS.md @@ -15,12 +15,12 @@ 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. | -| 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. | +| 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. | +| 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 @@ -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. -| 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/-worktrees` over `/tmp`. | — | haiku | docs/mission-control-worktree-root | MC-01-03 | 3K | Keep long-lived work on the larger persistent drive. | +| 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/-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 @@ -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. -| 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. | -| 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. | +| 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. | +| 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. | **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. -| 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. | -| 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. | +| 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. | +| 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 @@ -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. -| 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. | -| 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. | +| 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. | +| 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 @@ -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. -| 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. | -| 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. | +| 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. | +| 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. | **Milestone 6 estimate:** ~26K tokens diff --git a/docs/plans/2026-05-06-hermes-mosaic-alignment.md b/docs/plans/2026-05-06-hermes-mosaic-alignment.md index 3379d37..65f18a9 100644 --- a/docs/plans/2026-05-06-hermes-mosaic-alignment.md +++ b/docs/plans/2026-05-06-hermes-mosaic-alignment.md @@ -14,45 +14,45 @@ ### 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. | -| `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. | -| `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. | -| 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. | +| 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. | +| `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. | +| `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. | +| 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. | ### 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. | -| 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. | -| 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. | -| File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. | +| 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. | +| 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. | +| 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. | +| File checkpoints | Hermes checkpoint_manager | Already tracks file mutations with shadow git. | ### 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 | -| `packages/db` | Drizzle ORM + PG — Mosaic's data layer | -| `packages/auth` | BetterAuth — Mosaic's auth system | -| `packages/brain` | PG-backed data layer for Mosaic web app | -| `packages/queue` | Valkey task queue for Mosaic gateway | -| `plugins/discord` | OpenClaw Discord plugin | -| `plugins/telegram` | OpenClaw Telegram plugin | -| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface | +| 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 | +| `packages/db` | Drizzle ORM + PG — Mosaic's data layer | +| `packages/auth` | BetterAuth — Mosaic's auth system | +| `packages/brain` | PG-backed data layer for Mosaic web app | +| `packages/queue` | Valkey task queue for Mosaic gateway | +| `plugins/discord` | OpenClaw Discord plugin | +| `plugins/telegram` | OpenClaw Telegram plugin | +| `packages/mosaic` CLI | The `mosaic` CLI — Mosaic's own command surface | --- @@ -61,7 +61,7 @@ ### 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_resume) 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 | 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 | -| `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_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation | +| 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 | +| `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_resume` | Load a handoff packet and inject it as context for the new session | At session start after rotation | ### Toolset registration @@ -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 @@ -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) -| 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 | -| 1.4 Implement `mission_create` 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.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h | -| 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m | -| 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.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h | +| 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 | +| 1.4 Implement `mission_create` 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.7 Implement `mission_update_task` tool-call | `mission_tools.py` | 1h | +| 1.8 Register `mission` toolset in Hermes registry | `tools/registry.py` | 30m | +| 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.11 Write unit tests for TASKS.md parser | `tests/test_tasks_parser.py` | 1h | **Phase 1 estimate:** ~13h ### 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 | -| 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 | +| 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 | +| 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 | **Phase 2 estimate:** ~8h ### 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 | -| 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.6 Implement auto-rotation trigger | agent loop + handoff | 2h | -| 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h | +| 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 | +| 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.6 Implement auto-rotation trigger | agent loop + handoff | 2h | +| 3.7 Write tests for churn scoring | `tests/test_mission_churn.py` | 1h | **Phase 3 estimate:** ~11h ### 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 | -| 4.4 Add `hermes mission init` 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 | +| 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 | +| 4.4 Add `hermes mission init` 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 | **Phase 4 estimate:** ~8h diff --git a/docs/plans/2026-05-07-coordination-resilience.md b/docs/plans/2026-05-07-coordination-resilience.md index bf3be68..c787541 100644 --- a/docs/plans/2026-05-07-coordination-resilience.md +++ b/docs/plans/2026-05-07-coordination-resilience.md @@ -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: - Branch: @@ -127,6 +128,7 @@ This watcher prevents stale tasks from clogging the board and keeps the dispatch - State: committed | uncommitted | stashed() ## 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