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/comment-checker/cli.test.ts

@@ -2,18 +2,18 @@ import { describe, test, expect, beforeEach, mock } from "bun:test"
 
 describe("comment-checker CLI path resolution", () => {
   describe("lazy initialization", () => {
-    // #given module is imported
-    // #when COMMENT_CHECKER_CLI_PATH is accessed
-    // #then findCommentCheckerPathSync should NOT have been called during import
+    // given module is imported
+    // when COMMENT_CHECKER_CLI_PATH is accessed
+    // then findCommentCheckerPathSync should NOT have been called during import
     
     test("getCommentCheckerPathSync should be lazy - not called on module import", async () => {
-      // #given a fresh module import
+      // given a fresh module import
       // We need to verify that importing the module doesn't immediately call findCommentCheckerPathSync
       
-      // #when we import the module
+      // when we import the module
       const cliModule = await import("./cli")
       
-      // #then getCommentCheckerPathSync should exist and be callable
+      // then getCommentCheckerPathSync should exist and be callable
       expect(typeof cliModule.getCommentCheckerPathSync).toBe("function")
       
       // The key test: calling getCommentCheckerPathSync should work
@@ -24,33 +24,33 @@ describe("comment-checker CLI path resolution", () => {
     })
 
     test("getCommentCheckerPathSync should cache result after first call", async () => {
-      // #given getCommentCheckerPathSync is called once
+      // given getCommentCheckerPathSync is called once
       const cliModule = await import("./cli")
       const firstResult = cliModule.getCommentCheckerPathSync()
       
-      // #when called again
+      // when called again
       const secondResult = cliModule.getCommentCheckerPathSync()
       
-      // #then should return same cached result
+      // then should return same cached result
       expect(secondResult).toBe(firstResult)
     })
 
     test("COMMENT_CHECKER_CLI_PATH export should not exist (removed for lazy loading)", async () => {
-      // #given the cli module
+      // given the cli module
       const cliModule = await import("./cli")
       
-      // #when checking for COMMENT_CHECKER_CLI_PATH
-      // #then it should not exist (replaced with lazy getter)
+      // when checking for COMMENT_CHECKER_CLI_PATH
+      // then it should not exist (replaced with lazy getter)
       expect("COMMENT_CHECKER_CLI_PATH" in cliModule).toBe(false)
     })
   })
 
   describe("runCommentChecker", () => {
     test("should use getCommentCheckerPathSync for fallback path resolution", async () => {
-      // #given runCommentChecker is called without explicit path
+      // given runCommentChecker is called without explicit path
       const { runCommentChecker } = await import("./cli")
       
-      // #when called with input containing no comments
+      // when called with input containing no comments
       const result = await runCommentChecker({
         session_id: "test",
         tool_name: "Write",
@@ -60,7 +60,7 @@ describe("comment-checker CLI path resolution", () => {
         tool_input: { file_path: "/tmp/test.ts", content: "const x = 1" },
       })
       
-      // #then should return CheckResult type (binary may or may not exist)
+      // then should return CheckResult type (binary may or may not exist)
       expect(typeof result.hasComments).toBe("boolean")
       expect(typeof result.message).toBe("string")
     })