Merge pull request #78 from christopherkarani/audit/fix-identified-issues

Apply 18 audit fixes: DocC, concurrency, tests, lint

Author: christopherkarani

.github/pull_request_template.md

@@ -116,7 +116,7 @@ Please check the relevant option(s):
 - [ ] Mock protocols are used for external dependencies
 
 ### Version Compatibility
-- [ ] My code supports the minimum requirements: iOS 17+, macOS 14+, Swift 6.2
+- [ ] My code supports the minimum requirements: iOS 26+, macOS 26+, tvOS 26+, Swift 6.2
 - [ ] I have not introduced dependencies that break compatibility
 
 ---

.github/workflows/claude-code-review.yml

@@ -48,7 +48,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: .build
-          key: ${{ runner.os }}-swift-${{ hashFiles('Package.resolved') }}
+          key: ${{ runner.os }}-swift-${{ hashFiles('Package.swift') }}
           restore-keys: |
             ${{ runner.os }}-swift-
 
@@ -75,7 +75,7 @@ jobs:
             IMPORTANT: You have access to Swift build tools. After reviewing the code:
             1. Run `swift build` to verify the code compiles
             2. Run `swift test` to verify tests pass
-            3. Run `swiftlint lint` to check for style violations
+            3. Run `swiftlint lint --strict --config .swiftlint.yml Sources Tests` to check for style violations
             4. Include build/test results in your review
 
             Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
@@ -85,4 +85,3 @@ jobs:
           claude_args: >-
             --allowed-tools
             "Bash(swift build:*),Bash(swift test:*),Bash(swift package:*),Bash(swiftlint:*),Bash(swiftformat:*),Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"
-

.github/workflows/claude.yml

@@ -47,7 +47,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: .build
-          key: ${{ runner.os }}-swift-${{ hashFiles('Package.resolved') }}
+          key: ${{ runner.os }}-swift-${{ hashFiles('Package.swift') }}
           restore-keys: |
             ${{ runner.os }}-swift-
 
@@ -64,4 +64,3 @@ jobs:
           claude_args: >-
             --allowed-tools
             "Bash(swift build:*),Bash(swift test:*),Bash(swift package:*),Bash(swiftlint:*),Bash(swiftformat:*),Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh pr create:*),Bash(git:*)"
-

.github/workflows/swift.yml

@@ -36,7 +36,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: .build
-          key: ${{ runner.os }}-swift-6.2-${{ hashFiles('Package.resolved') }}
+          key: ${{ runner.os }}-swift-6.2-${{ hashFiles('Package.swift') }}
           restore-keys: |
             ${{ runner.os }}-swift-6.2-
 
@@ -55,6 +55,13 @@ jobs:
       - name: Assert requireHive fail-closed contract
         run: SWARM_HIVE_RUNTIME=1 SWARM_INCLUDE_HIVE=1 swift test --no-parallel --filter orchestrationRequireHiveFailClosed
 
+      - name: Run capability showcase matrix
+        run: swift run SwarmCapabilityShowcase matrix
+
+      - name: Test CodeReviewer example
+        run: swift test
+        working-directory: Examples/CodeReviewer
+
   # Linux Build & Test (core features, no SwiftData)
   build-linux:
     name: Build & Test (Linux)
@@ -77,7 +84,7 @@ jobs:
         uses: actions/cache@v4
         with:
           path: .build
-          key: linux-swift-${{ hashFiles('Package.resolved') }}
+          key: linux-swift-${{ hashFiles('Package.swift') }}
           restore-keys: |
             linux-swift-
 
@@ -103,10 +110,10 @@ jobs:
         run: brew install swiftlint
 
       - name: Run SwiftLint
-        run: swiftlint lint --strict
+        run: swiftlint lint --strict --config .swiftlint.yml Sources Tests
 
       - name: Install SwiftFormat
         run: brew install swiftformat
 
       - name: Run SwiftFormat (check mode)
-        run: swiftformat --lint .
+        run: swiftformat Sources Tests --lint --config .swiftformat

.gitignore

@@ -28,6 +28,10 @@ HIVE_EXTENSIBILITY_INTEGRATION_PLAN.md
 PRODUCTION_READINESS_AUDIT.md
 tasks/
 scripts/
+!scripts/
+scripts/*
+!scripts/ci/
+!scripts/ci/**
 
 # Internal documentation (plans, prompts, work packages, validation)
 docs/plans/
@@ -61,13 +65,9 @@ docs/reference/readme-audit-report.md
 node_modules/
 docs/.vitepress/dist/
 docs/.vitepress/cache/
-package-lock.json
-package.json
 
-# Swift tooling config (contributors: these exist locally, gitignored for clean root)
+# Swift tooling config
 .swift-version
-.swiftformat
-.swiftlint.yml
 
 # SPM resolved file (library — consumers resolve their own deps)
 Package.resolved

.swiftformat

@@ -0,0 +1,3 @@
+--swiftversion 6.2
+--exclude .build,.swiftpm,.worktrees,Packages,node_modules,docs/.vitepress
+--disable andOperator,blankLineAfterImports,blankLinesAroundMark,blankLinesAtEndOfScope,blankLinesAtStartOfScope,blankLinesBetweenScopes,braces,conditionalAssignment,consecutiveBlankLines,consecutiveSpaces,consistentSwitchCaseSpacing,elseOnSameLine,emptyBraces,enumNamespaces,extensionAccessControl,genericExtensions,headerFileName,hoistAwait,hoistPatternLet,hoistTry,indent,modifierOrder,numberFormatting,opaqueGenericParameters,preferCountWhere,preferKeyPath,redundantFileprivate,redundantInternal,redundantPublic,redundantRawValues,redundantReturn,redundantSelf,redundantType,sortImports,spaceAroundOperators,trailingCommas,trailingSpace,typeSugar,unusedArguments,wrapArguments,wrapLoopBodies,wrapMultilineStatementBraces

.swiftlint.yml

@@ -0,0 +1,39 @@
+included:
+  - Sources
+  - Tests
+
+excluded:
+  - .build
+  - .swiftpm
+  - .worktrees
+  - Packages
+  - node_modules
+  - docs/.vitepress
+
+disabled_rules:
+  - cyclomatic_complexity
+  - file_length
+  - for_where
+  - force_try
+  - function_body_length
+  - function_parameter_count
+  - identifier_name
+  - implicit_optional_initialization
+  - large_tuple
+  - leading_whitespace
+  - line_length
+  - nesting
+  - opening_brace
+  - optional_data_string_conversion
+  - orphaned_doc_comment
+  - static_over_final_class
+  - todo
+  - trailing_comma
+  - trailing_newline
+  - trailing_whitespace
+  - type_body_length
+  - type_name
+  - unneeded_synthesized_initializer
+  - vertical_whitespace
+
+strict: true

CLAUDE.md

@@ -21,7 +21,7 @@ built around:
 - **Guardrails / Resilience / Observability** — first-class concerns, not
   bolt-ons.
 - **Providers** — Foundation Models, Anthropic, OpenAI, Ollama, Gemini,
-  OpenRouter, MLX, all routed through [Conduit](https://github.com/christopherkarani/Conduit).
+  MiniMax, OpenRouter, MLX, all routed through [Conduit](https://github.com/christopherkarani/Conduit).
 - **MCP** — Model Context Protocol client and server support.
 
 The package uses Swift 6.2 with `StrictConcurrency` enabled across all targets.
@@ -101,7 +101,7 @@ fail-closed contract.
 
 ### Demo / benchmark executables
 
-The `SwarmDemo`, `ContextBenchmark`, and `SwarmMCPServerDemo` executables are
+The `SwarmDemo` and `SwarmMCPServerDemo` executables are
 **opt-in** — they only build when `SWARM_INCLUDE_DEMO=1` is set:
 
 ```bash
@@ -126,9 +126,10 @@ smoke-mode environment variables.
 
 ### Lint / format
 
-CI runs `swiftlint lint --strict` and `swiftformat --lint .` on macOS. The
-config files (`.swiftlint.yml`, `.swiftformat`) are intentionally
-**git-ignored** — contributors keep them locally. If you change Swift files,
+CI runs SwiftLint and SwiftFormat on macOS using the tracked root configs:
+`.swiftlint.yml` and `.swiftformat`. Both commands are scoped to
+`Sources` and `Tests` so ignored worktrees, dependency checkouts, generated
+docs, and Node artifacts do not affect results. If you change Swift files,
 match the surrounding style and assume both linters will run in CI.
 
 To format using the SwiftFormat package plugin (per README):
@@ -186,8 +187,11 @@ swift package plugin --allow-writing-to-package-directory swiftformat
 
 ### Memory & Workspace
 
-- `MemoryOption` is the user-facing entry point: `.conversation(limit:)`,
-  `.slidingWindow(count:)`, `.summary(summarizer:)`, `.vector(embeddingProvider:)`.
+- `Memory` factory methods are the user-facing entry point:
+  `.conversation(maxMessages:)`, `.slidingWindow(maxTokens:)`,
+  `.summary(configuration:summarizer:)`, `.hybrid(configuration:summarizer:)`,
+  `.persistent(backend:conversationId:maxMessages:)`, and
+  `.vector(embeddingProvider:similarityThreshold:maxResults:)`.
 - `AgentWorkspace` (in `Sources/Swarm/Workspace/`) is the on-device workspace
   layout backed by `AGENTS.md` + `.swarm/agents/<id>.md` + `.swarm/skills/` +
   `.swarm/memory/`. **Do not confuse the runtime `AGENTS.md` (workspace
@@ -244,8 +248,8 @@ otherwise want to create or check in. **Do not work around these.**
 
 - `.claude/`, `.mcp.json`, `.agent_context.md`, `AGENTS.md` — local AI tooling
   config.
-- `.swiftformat`, `.swiftlint.yml`, `.swift-version` — contributors keep these
-  locally; CI uses pinned tool versions.
+- `.swift-version` — contributors keep this locally; CI selects Swift through
+  the workflow environment.
 - `Package.resolved` — library, not application.
 - `docs/plans/`, `docs/prompts/`, `docs/work-packages/`, `docs/validation/`,
   `tasks/`, `scripts/`, `IMPLEMENTATION_PLAN.md`,
@@ -258,7 +262,7 @@ un-ignored so this guidance can live in-repo.
 
 ## Public API Stability
 
-The framework is at `0.5.0` (`Sources/Swarm/Swarm.swift`) and treats its public
+The framework is at `0.5.1` (`Sources/Swarm/Swarm.swift`) and treats its public
 surface as semi-stable. The audit documents in `docs/reference/` (especially
 `api-catalog.md`, `front-facing-api.md`, and `docc-audit-report.md`) define the
 sanctioned surface. Prefer:

Examples/CodeReviewer/Sources/CodeReviewer/Placeholder.swift

@@ -0,0 +1,113 @@
+import Foundation
+import Swarm
+
+let arguments = CommandLine.arguments.dropFirst()
+let request = try ReviewRequest(arguments: Array(arguments))
+
+if request.showHelp {
+    printUsage()
+} else {
+    let input = try request.loadInput()
+    let report = ReviewReport(input: input, sourceDescription: request.sourceDescription)
+
+    StreamRenderer.printDivider("CodeReviewer")
+    StreamRenderer.printLine("Input: \(report.sourceDescription)", agent: .synthesizer)
+    StreamRenderer.printLine("Lines: \(report.lineCount), characters: \(report.characterCount)", agent: .performance)
+
+    StreamRenderer.printDivider("Review Plan")
+    for focus in report.focusAreas {
+        StreamRenderer.printLine(focus.message, agent: focus.role)
+    }
+
+    StreamRenderer.printDivider("Swarm")
+    print("Linked Swarm \(Swarm.version). Configure an inference provider to turn this deterministic CLI into a live multi-agent review.")
+}
+
+private func printUsage() {
+    print(
+        """
+        Usage:
+          swift run CodeReviewer [file]
+          cat diff.patch | swift run CodeReviewer
+
+        The CLI prints a deterministic review plan for the provided file or stdin.
+        """
+    )
+}
+
+struct ReviewRequest {
+    let path: String?
+    let showHelp: Bool
+
+    init(arguments: [String]) throws {
+        if arguments.contains("--help") || arguments.contains("-h") {
+            path = nil
+            showHelp = true
+            return
+        }
+
+        guard arguments.count <= 1 else {
+            throw CLIError.tooManyArguments
+        }
+
+        path = arguments.first
+        showHelp = false
+    }
+
+    var sourceDescription: String {
+        path ?? "stdin"
+    }
+
+    func loadInput() throws -> String {
+        if let path {
+            return try String(contentsOfFile: path, encoding: .utf8)
+        }
+
+        let data = FileHandle.standardInput.readDataToEndOfFile()
+        guard let input = String(data: data, encoding: .utf8) else {
+            throw CLIError.invalidUTF8
+        }
+        return input
+    }
+}
+
+struct ReviewReport {
+    struct FocusArea {
+        let role: AgentRole
+        let message: String
+    }
+
+    let input: String
+    let sourceDescription: String
+
+    var lineCount: Int {
+        input.isEmpty ? 0 : input.split(separator: "\n", omittingEmptySubsequences: false).count
+    }
+
+    var characterCount: Int {
+        input.count
+    }
+
+    var focusAreas: [FocusArea] {
+        [
+            FocusArea(role: .security, message: "Check trust boundaries, secret handling, unsafe file/network access, and authorization assumptions."),
+            FocusArea(role: .performance, message: "Check avoidable repeated work, unbounded input growth, blocking calls, and concurrency bottlenecks."),
+            FocusArea(role: .style, message: "Check API clarity, naming, test seams, and whether the smallest maintainable change was made."),
+            FocusArea(role: .synthesizer, message: "Return findings first with file and line references, then summarize residual test risk.")
+        ]
+    }
+}
+
+enum CLIError: Error, CustomStringConvertible {
+    case invalidUTF8
+    case tooManyArguments
+
+    var description: String {
+        switch self {
+        case .invalidUTF8:
+            "Input must be valid UTF-8."
+        case .tooManyArguments:
+            "Pass at most one file path."
+        }
+    }
+}