kodelyth-ecc 2.17.0 → 2.19.0

package/.kimi/skills/supply-chain-verification/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: supply-chain-verification
+description: Generate CycloneDX SBOMs, content manifests, and verify installed copies of kodelyth-ecc against shipped manifests. Use when an enterprise / security team asks "where does this code come from, is it tampered, and where is the SBOM".
+trigger:
+  - supply chain
+  - SBOM
+  - CycloneDX
+  - SLSA
+  - provenance
+  - manifest
+  - tamper
+  - integrity check
+  - verify install
+---
+
+# Skill: supply-chain-verification
+
+## What this skill does
+
+Phase 2.9 of the Devil Roadmap. Three pure-function libraries plus three CLI subcommands give every kodelyth-ecc release **enterprise-grade supply-chain credentials**:
+
+| Capability | What it produces | Format |
+|---|---|---|
+| **SBOM** | CycloneDX 1.5 software bill of materials for the package + every transitive dep in the lockfile | JSON |
+| **Manifest** | sha256 content manifest of every shipped asset (agents, skills, commands, rules, hooks, scripts, bin, bundles, root files) | JSON |
+| **Verify** | Compares an installed copy against a manifest and reports `ok` / `modified` / `missing` / `extra` | JSON or pretty |
+
+Plus, every release published via `.github/workflows/publish.yml` ships with **SLSA Level 3 build provenance** courtesy of `npm publish --provenance` (sigstore-backed).
+
+---
+
+## When to use this skill
+
+Use **explicitly** by name when:
+
+- An enterprise / SOC 2 / FedRAMP-adjacent team asks for an SBOM to ingest into Dependency-Track, Snyk, or Anchore.
+- A user reports a suspicious install — verify against the shipped manifest to confirm tamper or local mod.
+- You're preparing an audit response and need provenance + bill-of-materials in one shot.
+- You want to ship a third-party reproducibility check for a downstream consumer.
+
+```bash
+use supply-chain-verification
+
+# Generate a CycloneDX 1.5 SBOM
+npx kodelyth-ecc sbom --out sbom.cdx.json
+
+# Generate a content manifest
+npx kodelyth-ecc manifest --out manifest.json
+
+# Verify a downloaded / installed copy
+npx kodelyth-ecc verify --manifest manifest.json
+```
+
+Implicit triggers (the AI should route here automatically):
+
+- "is my install of kodelyth-ecc tampered?"
+- "give me an SBOM"
+- "where is the SLSA provenance for this release?"
+- "compliance team needs supply-chain attestation for this package"
+
+---
+
+## CLI surface
+
+### `kodelyth-ecc sbom`
+
+```
+kodelyth-ecc sbom [--root DIR] [--out FILE] [--json]
+```
+
+Produces a CycloneDX 1.5 BOM:
+
+```json
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.5",
+  "serialNumber": "urn:uuid:...",
+  "metadata": {
+    "timestamp": "2026-05-10T17:00:00Z",
+    "tools": [{ "vendor": "kodelyth-ecc", "name": "kodelyth-ecc-sbom", "version": "1.7.0" }],
+    "component": { "type": "application", "name": "kodelyth-ecc", "version": "1.7.0", "purl": "pkg:npm/kodelyth-ecc@1.7.0" }
+  },
+  "components": [/* one per lockfile entry */],
+  "dependencies": [{ "ref": "kodelyth-ecc@1.7.0", "dependsOn": [/* direct deps */] }]
+}
+```
+
+Pure: no network, no exec. Reads `package.json` + `package-lock.json` only. Components carry purl, license, and SHA-512 hash from npm SRI when present.
+
+### `kodelyth-ecc manifest`
+
+```
+kodelyth-ecc manifest [--root DIR] [--out FILE] [--json]
+```
+
+Walks every shipped directory + root file. Produces:
+
+```json
+{
+  "schema": "kodelyth.content-manifest/v1",
+  "package": "kodelyth-ecc",
+  "pkg_version": "1.7.0",
+  "generated_at": "2026-05-10T17:00:00Z",
+  "file_count": 730,
+  "digest": "<sha256 over deterministic JSON of the entries array>",
+  "files": [
+    { "path": "agents/code-reviewer.md", "size": 4521, "sha256": "…" },
+    …
+  ]
+}
+```
+
+Output is deterministic (sorted by path, stable sha256), so two runs against the same source tree produce identical files modulo `generated_at`.
+
+### `kodelyth-ecc verify`
+
+```
+kodelyth-ecc verify [--root DIR] [--manifest FILE] [--json]
+```
+
+Compares disk against manifest:
+
+| Category | Meaning | Fails verify? |
+|---|---|---|
+| `ok` | sha256 matches | No |
+| `modified` | file present, hash differs | **Yes** |
+| `missing` | file in manifest but not on disk | **Yes** |
+| `extra` | file on disk not in manifest | No (advisory) |
+
+Exits **0** if `ok=true`, **1** otherwise. Pair with `--json` for CI gates.
+
+---
+
+## What ships with each release
+
+The `.github/workflows/publish.yml` pipeline does **all five** of:
+
+1. Verify `package.json.version` matches the release tag.
+2. Run the full test suite (255 tests).
+3. `npm publish --provenance` → **SLSA Level 3** build provenance via npm + sigstore.
+4. Generate `kodelyth-ecc-sbom.cdx.json` and attach to the GitHub release.
+5. Generate `kodelyth-ecc-manifest.json` and attach to the GitHub release.
+
+Three artifacts ship with every release:
+
+```
+v1.X.Y/
+├── kodelyth-ecc-sbom.cdx.json    ← CycloneDX 1.5
+├── kodelyth-ecc-manifest.json    ← sha256 content manifest
+└── (npm sigstore provenance)     ← visible on npmjs.com
+```
+
+---
+
+## Programmatic API
+
+```js
+const { generateSBOM }       = require('kodelyth-ecc/scripts/supply-chain/sbom.js');
+const { generateManifest }   = require('kodelyth-ecc/scripts/supply-chain/manifest.js');
+const { verifyAgainstManifest } = require('kodelyth-ecc/scripts/supply-chain/verify.js');
+
+const bom = generateSBOM({ rootDir: '/path/to/installed/kodelyth-ecc' });
+const m   = generateManifest({ rootDir: '/path/to/installed/kodelyth-ecc' });
+const r   = verifyAgainstManifest({ rootDir: '/path/to/installed/kodelyth-ecc', manifest: m });
+
+if (!r.ok) {
+  console.error('Tamper detected:', r.summary);
+  process.exit(1);
+}
+```
+
+All three are pure functions. Safe to call from a CI step, an MCP tool, or any external automation.
+
+---
+
+## Hard rules
+
+1. **Never** weaken `verify`. Modified or missing files MUST exit non-zero. Extras stay advisory.
+2. SBOM `serialNumber` is derived deterministically from `name@version + timestamp`. If you need a true random UUID per build, set `timestamp` to the build timestamp.
+3. Manifest `digest` is the sha256 of the deterministic JSON of `files`. Reproducible across runs at the same source state.
+4. Don't include `node_modules/`, `.git/`, `.DS_Store`, `__pycache__/`, or `*.pyc` in the manifest. The skip list is in `scripts/supply-chain/manifest.js`.
+5. Treat the published manifest as authoritative for tamper detection of an installed copy. Don't substitute a freshly-generated one.
+
+---
+
+## Pairing with other ECC features
+
+| Pair with | What you get |
+|---|---|
+| **Phase 2.10 safety hooks** | The token-budget hook + this skill cover "trust" (no PII leakage + no tampered code). |
+| **MCP server (Phase 2.1)** | Expose `verify` as an MCP tool downstream agents can call to confirm their toolkit is clean. |
+| **Swarm orchestrator (Phase 2.7)** | Run `verify` as a pre-flight check before spawning N parallel workers. |
+| **Replay (Phase 2.8)** | Bundles can carry the manifest of the source ECC version that produced them, enabling reproducible replays. |
+
+---
+
+## See also
+
+- `commands/verify-supply-chain.md` — `/verify-supply-chain` slash command form
+- `docs/supply-chain.md` — full reference + downstream verification guide
+- `.github/workflows/publish.yml` — release pipeline that issues all three artifacts

package/.kimi/skills/swarm-orchestrator/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: swarm-orchestrator
+description: Run N ECC specialist agents in parallel inside isolated git worktrees coordinated by a tmux session. Generalizes /devil-mode to arbitrary task + agent combinations. Use when one agent isn't enough — you want a parallel sweep across security, code quality, perf, UX, tests, architecture, and docs simultaneously.
+origin: ECC
+---
+
+# Swarm Orchestrator — Parallel Agent Execution at Scale
+
+The "team-of-specialists" pattern. Where `/devil-mode` is a fixed adversarial sweep with 4–8 specific agents, swarm is the **generalized form**: pick any task, pick any agents (or let ECC pick from task signals), get N parallel worktrees + a tmux session ready to attach.
+
+> Phase 2.7 of the [Devil Roadmap](../../README.md). Promotes the existing `tmux-worktree-orchestrator` infrastructure to a first-class CLI surface.
+
+---
+
+## When to invoke
+
+Trigger this skill when:
+
+- A task is too cross-cutting for one specialist (touches security AND perf AND API AND tests).
+- The user asks for "parallel review", "multi-agent sweep", "parallel agents", or "team review".
+- A change is high-stakes and you want defense-in-depth (security audit + UX + perf + arch in 15 min instead of 60).
+- The user has 4+ cores and wants throughput.
+
+Don't invoke when:
+
+- The task is genuinely single-axis (just security → use `security-reviewer` directly).
+- The repo is tiny enough that worktree overhead exceeds review time.
+- The user is on a machine without tmux/git worktree support.
+
+---
+
+## CLI surface
+
+```bash
+# Auto-pick agents from task signals.
+npx kodelyth-ecc swarm --task "audit the new oauth flow for security regressions" --agents 4
+
+# Explicit agent list.
+npx kodelyth-ecc swarm --task "ship v2.0" \
+  --agents release-captain,security-reviewer,e2e-runner,code-reviewer \
+  --execute
+
+# Different harness (codex / opencode / windsurf).
+npx kodelyth-ecc swarm --task "refactor payment module" --agents 6 --harness codex --execute
+
+# Power-user: hand-written plan.
+npx kodelyth-ecc swarm --plan plan.json --execute
+```
+
+Three execution modes:
+
+| Mode | Effect |
+|---|---|
+| (default) dry-run | Prints the plan. Doesn't spawn anything. Safe to inspect. |
+| `--write-only` | Materializes coordination files (`task.md`, `handoff.md`, `status.md`) but doesn't spawn worktrees or tmux. |
+| `--execute` | Creates git worktrees, spawns tmux session, launches each agent in its own pane. |
+
+---
+
+## Smart agent picking
+
+When you pass `--agents N` (a number), the swarm picks specialists in this priority order:
+
+1. **Signal-driven** — task keywords match agent specialties (security → `security-reviewer`, perf → `performance-optimizer`, API → `api-guardian`, etc.). 14 signal classes.
+2. **Baseline anchors** — `code-reviewer` and `pair-programmer` are added if not already picked (every task benefits from generalist eyes).
+3. **Rotation fill** — fills remaining slots from a 4 / 6 / 8-agent default rotation tuned for breadth.
+
+You can always override with `--agents code-reviewer,security-reviewer,architect`.
+
+---
+
+## Harness adapters
+
+| `--harness` | Launcher | Notes |
+|---|---|---|
+| `claude` | `claude --print --dangerously-skip-permissions ...` | Default. Works with Claude Code. |
+| `codex` | `bash scripts/orchestrate-codex-worker.sh ...` | Codex CLI worker with full status tracking. |
+| `opencode` | `opencode run --task-file ...` | OpenCode harness. |
+| `windsurf` | `windsurf-cli run --task-file ...` | Windsurf agent. |
+| `echo` | trivial echo | For dry-run validation only. |
+
+Use `--launcher-cmd "<your-template>"` to plug a custom harness. Available placeholders:
+
+```
+{worker_name} {worker_slug} {session_name} {repo_root}
+{worktree_path} {branch_name} {task_file} {handoff_file} {status_file}
+```
+
+Add `_sh` suffix for shell-quoted variants (`{task_file_sh}`, etc.).
+
+---
+
+## Coordination protocol
+
+Every worker gets three files in the coordination dir:
+
+- **`task.md`** — agent-shaped task with required handoff sections (Summary, Files Changed, Validation, Remaining Risks). Generated automatically.
+- **`handoff.md`** — where the worker writes its output. Watched by the launcher.
+- **`status.md`** — running / completed / failed marker for monitoring scripts and the future dashboard.
+
+Workers run in **isolated git worktrees** branched from `--base-ref` (default: `HEAD`). Each gets a unique branch (`orchestrator-<session>-<slug>`). Cleanup is automatic on failure (rolls back worktrees, branches, and tmux session).
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **`/devil-mode`** | Devil-mode is a hardcoded swarm of adversarial agents. Swarm generalizes it to arbitrary specialists. |
+| **Phase 2.4 cost router** | Each worker gets the same model-tier recommendation; security/incident workers force hard tier. |
+| **Phase 2.10 token-budget hook** | Each worker has its own session token-budget — one rogue worker can't burn the whole budget. |
+| **Phase 2.5 MCP client mode** | Workers can call registered external MCP servers (github, postgres, brave). |
+| **kodelyth-memory** | Capture the merged handoff bundle as a memory: `kodelyth-ecc remember "swarm 2026-05-10 oauth audit" --approach "..."`. |
+| **release-captain** | After a swarm, run `release-captain` to merge the best work and ship. |
+
+---
+
+## Examples
+
+### Pre-launch full sweep (8 agents, parallel)
+
+```bash
+npx kodelyth-ecc swarm \
+  --task "Pre-launch sweep for v2.0 — security, perf, UX, API contracts, docs, tests, release readiness" \
+  --agents 8 \
+  --replace \
+  --execute
+
+# Attach when ready:
+tmux attach -t swarm-2026-05-10-8a
+```
+
+### Production incident: 3-agent parallel triage
+
+```bash
+npx kodelyth-ecc swarm \
+  --task "Production is down. Auth service throwing 502s. Triage and propose fixes." \
+  --agents incident-commander,debug-detective,silent-failure-hunter \
+  --base-ref main \
+  --execute
+```
+
+### Refactor sprint with seeded files
+
+```bash
+npx kodelyth-ecc swarm \
+  --task "Refactor the payments module for testability without changing behavior" \
+  --agents refactor-cleaner,code-simplifier,type-design-analyzer,tdd-guide \
+  --seed src/payments \
+  --seed tests/payments \
+  --execute
+```
+
+---
+
+## Hard rules
+
+1. **Never run `--execute` without inspecting the dry-run first.** Worktree creation mutates the repo; bad plans waste disk.
+2. **Don't mix incompatible agents in one swarm.** Putting `release-captain` and `migration-guide` in the same swarm produces conflicting handoffs.
+3. **Cap N at 8 for a single repo.** Worktree contention + tmux pane crowding hurts past 8.
+4. **Never share tmux sessions across swarms.** Use `--session NAME` explicitly when running multiple swarms.
+5. **Always merge handoffs through human review** — don't auto-apply changes from N parallel agents without a human pass.
+
+---
+
+## Implementation
+
+- Plan builder: `scripts/swarm/build-plan.js` (pure function, fully tested).
+- Orchestrator: `scripts/lib/tmux-worktree-orchestrator.js` (the existing infrastructure).
+- Worker (codex): `scripts/orchestrate-codex-worker.sh`.
+- CLI: `npx kodelyth-ecc swarm`.
+- Slash command: `/swarm`.
+- Full reference: `docs/swarm.md`.
+
+---
+
+Built into [Kodelyth ECC](../../README.md). MIT licensed.

package/.kimi/skills/swift-actor-persistence/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: swift-actor-persistence
+description: Thread-safe data persistence in Swift using actors — in-memory cache with file-backed storage, eliminating data races by design.
+origin: ECC
+---
+
+# Swift Actors for Thread-Safe Persistence
+
+Patterns for building thread-safe data persistence layers using Swift actors. Combines in-memory caching with file-backed storage, leveraging the actor model to eliminate data races at compile time.
+
+## When to Activate
+
+- Building a data persistence layer in Swift 5.5+
+- Need thread-safe access to shared mutable state
+- Want to eliminate manual synchronization (locks, DispatchQueues)
+- Building offline-first apps with local storage
+
+## Core Pattern
+
+### Actor-Based Repository
+
+The actor model guarantees serialized access — no data races, enforced by the compiler.
+
+```swift
+public actor LocalRepository<T: Codable & Identifiable> where T.ID == String {
+    private var cache: [String: T] = [:]
+    private let fileURL: URL
+
+    public init(directory: URL = .documentsDirectory, filename: String = "data.json") {
+        self.fileURL = directory.appendingPathComponent(filename)
+        // Synchronous load during init (actor isolation not yet active)
+        self.cache = Self.loadSynchronously(from: fileURL)
+    }
+
+    // MARK: - Public API
+
+    public func save(_ item: T) throws {
+        cache[item.id] = item
+        try persistToFile()
+    }
+
+    public func delete(_ id: String) throws {
+        cache[id] = nil
+        try persistToFile()
+    }
+
+    public func find(by id: String) -> T? {
+        cache[id]
+    }
+
+    public func loadAll() -> [T] {
+        Array(cache.values)
+    }
+
+    // MARK: - Private
+
+    private func persistToFile() throws {
+        let data = try JSONEncoder().encode(Array(cache.values))
+        try data.write(to: fileURL, options: .atomic)
+    }
+
+    private static func loadSynchronously(from url: URL) -> [String: T] {
+        guard let data = try? Data(contentsOf: url),
+              let items = try? JSONDecoder().decode([T].self, from: data) else {
+            return [:]
+        }
+        return Dictionary(uniqueKeysWithValues: items.map { ($0.id, $0) })
+    }
+}
+```
+
+### Usage
+
+All calls are automatically async due to actor isolation:
+
+```swift
+let repository = LocalRepository<Question>()
+
+// Read — fast O(1) lookup from in-memory cache
+let question = await repository.find(by: "q-001")
+let allQuestions = await repository.loadAll()
+
+// Write — updates cache and persists to file atomically
+try await repository.save(newQuestion)
+try await repository.delete("q-001")
+```
+
+### Combining with @Observable ViewModel
+
+```swift
+@Observable
+final class QuestionListViewModel {
+    private(set) var questions: [Question] = []
+    private let repository: LocalRepository<Question>
+
+    init(repository: LocalRepository<Question> = LocalRepository()) {
+        self.repository = repository
+    }
+
+    func load() async {
+        questions = await repository.loadAll()
+    }
+
+    func add(_ question: Question) async throws {
+        try await repository.save(question)
+        questions = await repository.loadAll()
+    }
+}
+```
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Actor (not class + lock) | Compiler-enforced thread safety, no manual synchronization |
+| In-memory cache + file persistence | Fast reads from cache, durable writes to disk |
+| Synchronous init loading | Avoids async initialization complexity |
+| Dictionary keyed by ID | O(1) lookups by identifier |
+| Generic over `Codable & Identifiable` | Reusable across any model type |
+| Atomic file writes (`.atomic`) | Prevents partial writes on crash |
+
+## Best Practices
+
+- **Use `Sendable` types** for all data crossing actor boundaries
+- **Keep the actor's public API minimal** — only expose domain operations, not persistence details
+- **Use `.atomic` writes** to prevent data corruption if the app crashes mid-write
+- **Load synchronously in `init`** — async initializers add complexity with minimal benefit for local files
+- **Combine with `@Observable`** ViewModels for reactive UI updates
+
+## Anti-Patterns to Avoid
+
+- Using `DispatchQueue` or `NSLock` instead of actors for new Swift concurrency code
+- Exposing the internal cache dictionary to external callers
+- Making the file URL configurable without validation
+- Forgetting that all actor method calls are `await` — callers must handle async context
+- Using `nonisolated` to bypass actor isolation (defeats the purpose)
+
+## When to Use
+
+- Local data storage in iOS/macOS apps (user data, settings, cached content)
+- Offline-first architectures that sync to a server later
+- Any shared mutable state that multiple parts of the app access concurrently
+- Replacing legacy `DispatchQueue`-based thread safety with modern Swift concurrency