kodelyth-ecc 2.19.0 → 2.21.0

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

@@ -1,201 +0,0 @@
----
-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/.gemini/skills/swarm-orchestrator/SKILL.md

@@ -1,177 +0,0 @@
----
-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/.gemini/skills/swift-actor-persistence/SKILL.md

@@ -1,143 +0,0 @@
----
-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