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/compaction-context-injector/index.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it, mock, beforeEach } from "bun:test"
+
+// Mock dependencies before importing
+const mockInjectHookMessage = mock(() => true)
+mock.module("../../features/hook-message-injector", () => ({
+  injectHookMessage: mockInjectHookMessage,
+}))
+
+mock.module("../../shared/logger", () => ({
+  log: () => {},
+}))
+
+mock.module("../../shared/system-directive", () => ({
+  createSystemDirective: (type: string) => `[DIRECTIVE:${type}]`,
+  SystemDirectiveTypes: {
+    TODO_CONTINUATION: "TODO CONTINUATION",
+    RALPH_LOOP: "RALPH LOOP",
+    BOULDER_CONTINUATION: "BOULDER CONTINUATION",
+    DELEGATION_REQUIRED: "DELEGATION REQUIRED",
+    SINGLE_TASK_ONLY: "SINGLE TASK ONLY",
+    COMPACTION_CONTEXT: "COMPACTION CONTEXT",
+    CONTEXT_WINDOW_MONITOR: "CONTEXT WINDOW MONITOR",
+    PROMETHEUS_READ_ONLY: "PROMETHEUS READ-ONLY",
+  },
+}))
+
+import { createCompactionContextInjector } from "./index"
+import type { SummarizeContext } from "./index"
+
+describe("createCompactionContextInjector", () => {
+  beforeEach(() => {
+    mockInjectHookMessage.mockClear()
+  })
+
+  describe("Agent Verification State preservation", () => {
+    it("includes Agent Verification State section in compaction prompt", async () => {
+      // given
+      const injector = createCompactionContextInjector()
+      const context: SummarizeContext = {
+        sessionID: "test-session",
+        providerID: "anthropic",
+        modelID: "claude-sonnet-4-5",
+        usageRatio: 0.85,
+        directory: "/test/dir",
+      }
+
+      // when
+      await injector(context)
+
+      // then
+      expect(mockInjectHookMessage).toHaveBeenCalledTimes(1)
+      const calls = mockInjectHookMessage.mock.calls as unknown as [string, string, unknown][]
+      const injectedPrompt = calls[0]?.[1] ?? ""
+      expect(injectedPrompt).toContain("Agent Verification State")
+      expect(injectedPrompt).toContain("Current Agent")
+      expect(injectedPrompt).toContain("Verification Progress")
+    })
+
+    it("includes Momus-specific context for reviewer agents", async () => {
+      // given
+      const injector = createCompactionContextInjector()
+      const context: SummarizeContext = {
+        sessionID: "test-session",
+        providerID: "anthropic",
+        modelID: "claude-sonnet-4-5",
+        usageRatio: 0.9,
+        directory: "/test/dir",
+      }
+
+      // when
+      await injector(context)
+
+      // then
+      const calls = mockInjectHookMessage.mock.calls as unknown as [string, string, unknown][]
+      const injectedPrompt = calls[0]?.[1] ?? ""
+      expect(injectedPrompt).toContain("Previous Rejections")
+      expect(injectedPrompt).toContain("Acceptance Status")
+      expect(injectedPrompt).toContain("reviewer agents")
+    })
+
+    it("preserves file verification progress in compaction prompt", async () => {
+      // given
+      const injector = createCompactionContextInjector()
+      const context: SummarizeContext = {
+        sessionID: "test-session",
+        providerID: "anthropic",
+        modelID: "claude-sonnet-4-5",
+        usageRatio: 0.95,
+        directory: "/test/dir",
+      }
+
+      // when
+      await injector(context)
+
+      // then
+      const calls = mockInjectHookMessage.mock.calls as unknown as [string, string, unknown][]
+      const injectedPrompt = calls[0]?.[1] ?? ""
+      expect(injectedPrompt).toContain("Pending Verifications")
+      expect(injectedPrompt).toContain("Files already verified")
+    })
+  })
+})

src/hooks/compaction-context-injector/index.ts

@@ -0,0 +1,76 @@
+import { injectHookMessage } from "../../features/hook-message-injector"
+import { log } from "../../shared/logger"
+import { createSystemDirective, SystemDirectiveTypes } from "../../shared/system-directive"
+
+export interface SummarizeContext {
+  sessionID: string
+  providerID: string
+  modelID: string
+  usageRatio: number
+  directory: string
+}
+
+const SUMMARIZE_CONTEXT_PROMPT = `${createSystemDirective(SystemDirectiveTypes.COMPACTION_CONTEXT)}
+
+When summarizing this session, you MUST include the following sections in your summary:
+
+## 1. User Requests (As-Is)
+- List all original user requests exactly as they were stated
+- Preserve the user's exact wording and intent
+
+## 2. Final Goal
+- What the user ultimately wanted to achieve
+- The end result or deliverable expected
+
+## 3. Work Completed
+- What has been done so far
+- Files created/modified
+- Features implemented
+- Problems solved
+
+## 4. Remaining Tasks
+- What still needs to be done
+- Pending items from the original request
+- Follow-up tasks identified during the work
+
+## 5. Active Working Context (For Seamless Continuation)
+- **Files**: Paths of files currently being edited or frequently referenced
+- **Code in Progress**: Key code snippets, function signatures, or data structures under active development
+- **External References**: Documentation URLs, library APIs, or external resources being consulted
+- **State & Variables**: Important variable names, configuration values, or runtime state relevant to ongoing work
+
+## 6. MUST NOT Do (Critical Constraints)
+- Things that were explicitly forbidden
+- Approaches that failed and should not be retried
+- User's explicit restrictions or preferences
+- Anti-patterns identified during the session
+
+## 7. Agent Verification State (Critical for Reviewers)
+- **Current Agent**: What agent is running (momus, oracle, etc.)
+- **Verification Progress**: Files already verified/validated
+- **Pending Verifications**: Files still needing verification
+- **Previous Rejections**: If reviewer agent, what was rejected and why
+- **Acceptance Status**: Current state of review process
+
+This section is CRITICAL for reviewer agents (momus, oracle) to maintain continuity.
+
+This context is critical for maintaining continuity after compaction.
+`
+
+export function createCompactionContextInjector() {
+  return async (ctx: SummarizeContext): Promise<void> => {
+    log("[compaction-context-injector] injecting context", { sessionID: ctx.sessionID })
+
+    const success = injectHookMessage(ctx.sessionID, SUMMARIZE_CONTEXT_PROMPT, {
+      agent: "general",
+      model: { providerID: ctx.providerID, modelID: ctx.modelID },
+      path: { cwd: ctx.directory },
+    })
+
+    if (success) {
+      log("[compaction-context-injector] context injected", { sessionID: ctx.sessionID })
+    } else {
+      log("[compaction-context-injector] injection failed", { sessionID: ctx.sessionID })
+    }
+  }
+}