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/tools/session-manager/utils.test.ts

@@ -11,29 +11,29 @@ import type { SessionInfo, SessionMessage, SearchResult } from "./types"
 
 describe("session-manager utils", () => {
   test("formatSessionList handles empty array", async () => {
-    // #given
+    // given
     const sessions: string[] = []
 
-    // #when
+    // when
     const result = await formatSessionList(sessions)
 
-    // #then
+    // then
     expect(result).toContain("No sessions found")
   })
 
   test("formatSessionMessages handles empty array", () => {
-    // #given
+    // given
     const messages: SessionMessage[] = []
 
-    // #when
+    // when
     const result = formatSessionMessages(messages)
 
-    // #then
+    // then
     expect(result).toContain("No messages")
   })
 
   test("formatSessionMessages includes message content", () => {
-    // #given
+    // given
     const messages: SessionMessage[] = [
       {
         id: "msg_001",
@@ -43,16 +43,16 @@ describe("session-manager utils", () => {
       },
     ]
 
-    // #when
+    // when
     const result = formatSessionMessages(messages)
 
-    // #then
+    // then
     expect(result).toContain("user")
     expect(result).toContain("Hello world")
   })
 
   test("formatSessionMessages includes todos when requested", () => {
-    // #given
+    // given
     const messages: SessionMessage[] = [
       {
         id: "msg_001",
@@ -66,17 +66,17 @@ describe("session-manager utils", () => {
       { id: "2", content: "Task 2", status: "pending" as const },
     ]
 
-    // #when
+    // when
     const result = formatSessionMessages(messages, true, todos)
 
-    // #then
+    // then
     expect(result).toContain("Todos")
     expect(result).toContain("Task 1")
     expect(result).toContain("Task 2")
   })
 
   test("formatSessionInfo includes all metadata", () => {
-    // #given
+    // given
     const info: SessionInfo = {
       id: "ses_test123",
       message_count: 42,
@@ -89,10 +89,10 @@ describe("session-manager utils", () => {
       transcript_entries: 123,
     }
 
-    // #when
+    // when
     const result = formatSessionInfo(info)
 
-    // #then
+    // then
     expect(result).toContain("ses_test123")
     expect(result).toContain("42")
     expect(result).toContain("build, oracle")
@@ -100,18 +100,18 @@ describe("session-manager utils", () => {
   })
 
   test("formatSearchResults handles empty array", () => {
-    // #given
+    // given
     const results: SearchResult[] = []
 
-    // #when
+    // when
     const result = formatSearchResults(results)
 
-    // #then
+    // then
     expect(result).toContain("No matches")
   })
 
   test("formatSearchResults formats matches correctly", () => {
-    // #given
+    // given
     const results: SearchResult[] = [
       {
         session_id: "ses_test123",
@@ -123,10 +123,10 @@ describe("session-manager utils", () => {
       },
     ]
 
-    // #when
+    // when
     const result = formatSearchResults(results)
 
-    // #then
+    // then
     expect(result).toContain("Found 1 matches")
     expect(result).toContain("ses_test123")
     expect(result).toContain("msg_001")
@@ -135,25 +135,25 @@ describe("session-manager utils", () => {
   })
 
   test("filterSessionsByDate filters correctly", async () => {
-    // #given
+    // given
     const sessionIDs = ["ses_001", "ses_002", "ses_003"]
 
-    // #when
+    // when
     const result = await filterSessionsByDate(sessionIDs)
 
-    // #then
+    // then
     expect(Array.isArray(result)).toBe(true)
   })
 
   test("searchInSession finds matches case-insensitively", async () => {
-    // #given
+    // given
     const sessionID = "ses_nonexistent"
     const query = "test"
 
-    // #when
+    // when
     const results = await searchInSession(sessionID, query, false)
 
-    // #then
+    // then
     expect(Array.isArray(results)).toBe(true)
     expect(results.length).toBe(0)
   })