refactor: major codebase cleanup - BDD comments, file splitting, bug fixes (#1350)

* style(tests): normalize BDD comments from '// #given' to '// given'

- Replace 4,668 Python-style BDD comments across 107 test files
- Patterns changed: // #given -> // given, // #when -> // when, // #then -> // then
- Also handles no-space variants: //#given -> // given

* fix(rules-injector): prefer output.metadata.filePath over output.title

- Extract file path resolution to dedicated output-path.ts module
- Prefer metadata.filePath which contains actual file path
- Fall back to output.title only when metadata unavailable
- Fixes issue where rules weren't injected when tool output title was a label

* feat(slashcommand): add optional user_message parameter

- Add user_message optional parameter for command arguments
- Model can now call: command='publish' user_message='patch'
- Improves error messages with clearer format guidance
- Helps LLMs understand correct parameter usage

* feat(hooks): restore compaction-context-injector hook

- Restore hook deleted in cbbc7bd0 for session compaction context
- Injects 7 mandatory sections: User Requests, Final Goal, Work Completed,
  Remaining Tasks, Active Working Context, MUST NOT Do, Agent Verification State
- Re-register in hooks/index.ts and main plugin entry

* refactor(background-agent): split manager.ts into focused modules

- Extract constants.ts for TTL values and internal types (52 lines)
- Extract state.ts for TaskStateManager class (204 lines)
- Extract spawner.ts for task creation logic (244 lines)
- Extract result-handler.ts for completion handling (265 lines)
- Reduce manager.ts from 1377 to 755 lines (45% reduction)
- Maintain backward compatible exports

* refactor(agents): split prometheus-prompt.ts into subdirectory

- Move 1196-line prometheus-prompt.ts to prometheus/ subdirectory
- Organize prompt sections into separate files for maintainability
- Update agents/index.ts exports

* refactor(delegate-task): split tools.ts into focused modules

- Extract categories.ts for category definitions and routing
- Extract executor.ts for task execution logic
- Extract helpers.ts for utility functions
- Extract prompt-builder.ts for prompt construction
- Reduce tools.ts complexity with cleaner separation of concerns

* refactor(builtin-skills): split skills.ts into individual skill files

- Move each skill to dedicated file in skills/ subdirectory
- Create barrel export for backward compatibility
- Improve maintainability with focused skill modules

* chore: update import paths and lockfile

- Update prometheus import path after refactor
- Update bun.lock

* fix(tests): complete BDD comment normalization

- Fix remaining #when/#then patterns missed by initial sed
- Affected: state.test.ts, events.test.ts

---------

Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com>

src/hooks/stop-continuation-guard/index.test.ts

@@ -14,64 +14,64 @@ describe("stop-continuation-guard", () => {
   }
 
   test("should mark session as stopped", () => {
-    // #given - a guard hook with no stopped sessions
+    // given - a guard hook with no stopped sessions
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const sessionID = "test-session-1"
 
-    // #when - we stop continuation for the session
+    // when - we stop continuation for the session
     guard.stop(sessionID)
 
-    // #then - session should be marked as stopped
+    // then - session should be marked as stopped
     expect(guard.isStopped(sessionID)).toBe(true)
   })
 
   test("should return false for non-stopped sessions", () => {
-    // #given - a guard hook with no stopped sessions
+    // given - a guard hook with no stopped sessions
     const guard = createStopContinuationGuardHook(createMockPluginInput())
 
-    // #when - we check a session that was never stopped
+    // when - we check a session that was never stopped
 
-    // #then - it should return false
+    // then - it should return false
     expect(guard.isStopped("non-existent-session")).toBe(false)
   })
 
   test("should clear stopped state for a session", () => {
-    // #given - a session that was stopped
+    // given - a session that was stopped
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const sessionID = "test-session-2"
     guard.stop(sessionID)
 
-    // #when - we clear the session
+    // when - we clear the session
     guard.clear(sessionID)
 
-    // #then - session should no longer be stopped
+    // then - session should no longer be stopped
     expect(guard.isStopped(sessionID)).toBe(false)
   })
 
   test("should handle multiple sessions independently", () => {
-    // #given - multiple sessions with different stop states
+    // given - multiple sessions with different stop states
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const session1 = "session-1"
     const session2 = "session-2"
     const session3 = "session-3"
 
-    // #when - we stop some sessions but not others
+    // when - we stop some sessions but not others
     guard.stop(session1)
     guard.stop(session2)
 
-    // #then - each session has its own state
+    // then - each session has its own state
     expect(guard.isStopped(session1)).toBe(true)
     expect(guard.isStopped(session2)).toBe(true)
     expect(guard.isStopped(session3)).toBe(false)
   })
 
   test("should clear session on session.deleted event", async () => {
-    // #given - a session that was stopped
+    // given - a session that was stopped
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const sessionID = "test-session-3"
     guard.stop(sessionID)
 
-    // #when - session is deleted
+    // when - session is deleted
     await guard.event({
       event: {
         type: "session.deleted",
@@ -79,19 +79,19 @@ describe("stop-continuation-guard", () => {
       },
     })
 
-    // #then - session should no longer be stopped (cleaned up)
+    // then - session should no longer be stopped (cleaned up)
     expect(guard.isStopped(sessionID)).toBe(false)
   })
 
   test("should not affect other sessions on session.deleted", async () => {
-    // #given - multiple stopped sessions
+    // given - multiple stopped sessions
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const session1 = "session-keep"
     const session2 = "session-delete"
     guard.stop(session1)
     guard.stop(session2)
 
-    // #when - one session is deleted
+    // when - one session is deleted
     await guard.event({
       event: {
         type: "session.deleted",
@@ -99,46 +99,46 @@ describe("stop-continuation-guard", () => {
       },
     })
 
-    // #then - other session should remain stopped
+    // then - other session should remain stopped
     expect(guard.isStopped(session1)).toBe(true)
     expect(guard.isStopped(session2)).toBe(false)
   })
 
   test("should clear stopped state on new user message (chat.message)", async () => {
-    // #given - a session that was stopped
+    // given - a session that was stopped
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const sessionID = "test-session-4"
     guard.stop(sessionID)
     expect(guard.isStopped(sessionID)).toBe(true)
 
-    // #when - user sends a new message
+    // when - user sends a new message
     await guard["chat.message"]({ sessionID })
 
-    // #then - stop state should be cleared (one-time only)
+    // then - stop state should be cleared (one-time only)
     expect(guard.isStopped(sessionID)).toBe(false)
   })
 
   test("should not affect non-stopped sessions on chat.message", async () => {
-    // #given - a session that was never stopped
+    // given - a session that was never stopped
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     const sessionID = "test-session-5"
 
-    // #when - user sends a message (session was never stopped)
+    // when - user sends a message (session was never stopped)
     await guard["chat.message"]({ sessionID })
 
-    // #then - should not throw and session remains not stopped
+    // then - should not throw and session remains not stopped
     expect(guard.isStopped(sessionID)).toBe(false)
   })
 
   test("should handle undefined sessionID in chat.message", async () => {
-    // #given - a guard with a stopped session
+    // given - a guard with a stopped session
     const guard = createStopContinuationGuardHook(createMockPluginInput())
     guard.stop("some-session")
 
-    // #when - chat.message is called without sessionID
+    // when - chat.message is called without sessionID
     await guard["chat.message"]({ sessionID: undefined })
 
-    // #then - should not throw and stopped session remains stopped
+    // then - should not throw and stopped session remains stopped
     expect(guard.isStopped("some-session")).toBe(true)
   })
 })