claude-code-pilot 3.1.1 → 3.3.0

package/src/skills/production-audit/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: production-audit
+description: Local-evidence production readiness audit for shipped apps, pre-launch reviews, post-merge checks, and "what breaks in prod?" questions without sending repo data to an external audit service.
+origin: community
+---
+
+# Production Audit
+
+Use this skill when the user asks whether an application is ready to ship, what
+could break in production, or what must be fixed before a launch. This is a
+maintainer-safe rewrite of the stale community production-audit idea: it keeps
+the useful production-readiness lens and removes unpinned external execution and
+third-party data sharing.
+
+## When to Use
+
+- The user asks "is this production-ready", "what would break in prod", "what
+  did we miss", "audit this repo", or "ready to ship?"
+- A feature was merged and needs a pre-deploy or post-merge risk pass.
+- A public launch, demo, customer rollout, or investor walkthrough is close.
+- CI is green but the user wants production risk, not only test status.
+- A deployed URL, release branch, PR, or current checkout is available for
+  evidence gathering.
+
+## When Not to Use
+
+- During active implementation when the right lens is line-level secure coding;
+  use `security-review` first.
+- For pure libraries, templates, docs-only repos, or scaffolds unless the user
+  wants packaging/release readiness rather than application readiness.
+- When the user asks for a formal compliance audit. This skill is engineering
+  triage, not legal, financial, medical, or regulatory certification.
+- When the only available evidence is a product idea with no repo, deployment,
+  CI, or runtime surface.
+
+## How It Works
+
+Build the audit from local and user-authorized evidence. Do not run unpinned
+remote code, upload repository contents to third-party services, or call
+external scanners unless the user explicitly approves that specific tool and
+data flow.
+
+Use this order:
+
+1. Establish the release surface.
+2. Read recent changes and current branch state.
+3. Inspect runtime, auth, data, payment, background-job, AI, and deployment
+   boundaries that actually exist in the repo.
+4. Check CI, tests, migrations, environment documentation, and rollback path.
+5. Produce a short ship/block recommendation with specific fixes.
+
+## Evidence Checklist
+
+Start with cheap, local signals:
+
+```text
+git status --short --branch
+git log --oneline --decorate -20
+git diff --stat origin/main...HEAD
+```
+
+Then inspect the project-specific surface:
+
+- Package scripts, CI workflows, release scripts, Docker files, and deployment
+  manifests.
+- API routes, webhooks, auth middleware, background workers, cron jobs, and
+  database migrations.
+- Environment variable documentation and startup checks.
+- Observability hooks, error reporting, logs, health checks, and dashboards.
+- Rollback, seed, migration, and backfill instructions.
+- E2E coverage for the user paths that matter most.
+
+If a deployed URL is in scope, use browser or HTTP checks only against that URL
+and avoid credentialed actions unless the user supplies a safe test account.
+
+## Risk Lenses
+
+### Security And Auth
+
+- Are public routes, API routes, and admin routes clearly separated?
+- Are auth and authorization enforced server-side?
+- Are secrets kept out of client bundles, logs, example output, and checked-in
+  files?
+- Are rate limits, CSRF protections, CORS policy, and upload validation present
+  where the app needs them?
+- Does the AI or agent surface defend against prompt injection, tool abuse, and
+  untrusted content crossing into privileged actions?
+
+### Data Integrity
+
+- Do migrations run forward cleanly and have a rollback or recovery plan?
+- Are destructive migrations, backfills, and data imports staged safely?
+- Do database policies, grants, and service-role boundaries match the app's
+  tenancy model?
+- Are retries idempotent for writes, jobs, and webhook handlers?
+
+### Payments And Webhooks
+
+- Are webhook signatures verified before parsing trusted payload fields?
+- Is each payment, subscription, or fulfillment webhook idempotent?
+- Are replay, duplicate delivery, and out-of-order delivery handled?
+- Are test-mode and live-mode credentials separated?
+
+### Operations
+
+- Can the app start from a clean checkout using documented commands?
+- Are required environment variables named, validated, and fail-fast?
+- Is there a health check that proves dependencies are reachable?
+- Are deploy, rollback, and incident-owner paths documented?
+- Are logs useful without leaking secrets or personal data?
+
+### User Experience
+
+- Are the launch-critical paths covered on desktop and mobile?
+- Are forms usable on mobile without input zoom, layout overlap, or blocked
+  submission states?
+- Do loading, empty, error, and permission-denied states tell the user what
+  happened?
+- Is there a support or recovery path when a critical operation fails?
+
+## Scoring
+
+Use scores to force prioritization, not to imply mathematical certainty.
+
+| Band | Score | Meaning |
+| --- | --- | --- |
+| Blocked | 0-49 | Do not ship until the top risks are fixed |
+| Risky | 50-69 | Ship only behind a small rollout or internal beta |
+| Launchable With Caveats | 70-84 | Ship if owners accept the listed risks |
+| Strong | 85-100 | No obvious launch blockers from available evidence |
+
+Cap the score at `69` if any of these are true:
+
+- Authentication or authorization is missing on sensitive data.
+- Payment or fulfillment webhooks are not idempotent.
+- Required migrations cannot be run safely.
+- Secrets are exposed in client bundles, logs, or committed files.
+- There is no rollback path for a high-impact release.
+
+Cap the score at `84` if CI is not green or the launch-critical path was not
+tested end to end.
+
+## Output Format
+
+Lead with one sentence:
+
+```text
+Production audit: 76/100, launchable with caveats, with webhook idempotency and rollback docs as the two risks to fix before public launch.
+```
+
+Then list:
+
+- `Blockers`: must-fix items before deploy.
+- `High-value fixes`: next fixes if the user wants to improve the score.
+- `Evidence checked`: files, commands, CI, deployed URL, or PRs inspected.
+- `Evidence missing`: what would change confidence if provided.
+- `Next action`: one concrete fix or verification step.
+
+Keep strengths short. The user asked for readiness, so the useful answer is the
+remaining risk and the next action.
+
+## Example
+
+User:
+
+```text
+is this ready to ship?
+```
+
+Response:
+
+```text
+Production audit: 68/100, risky, because Stripe webhooks are verified but not idempotent and there is no rollback note for the pending migration.
+
+Blockers:
+- Add idempotency for `checkout.session.completed` before fulfilling orders.
+- Write and test the rollback path for `20260511_add_billing_state.sql`.
+
+High-value fixes:
+- Add a health check that verifies database and payment-provider reachability.
+- Add one E2E path for upgrade, webhook fulfillment, and billing-page refresh.
+
+Evidence checked:
+- `api/stripe/webhook.ts`
+- `db/migrations/20260511_add_billing_state.sql`
+- GitHub Actions run for the release branch
+
+Next action: Want me to patch webhook idempotency first?
+```
+
+## Anti-Patterns
+
+- Running `npx <package>@latest` or a remote scanner as the default audit path.
+- Uploading source, secrets, customer data, or private topology to an external
+  audit service without explicit approval.
+- Producing a score without naming the evidence checked.
+- Treating green CI as production readiness.
+- Ending with a generic "let me know what you want to do."
+
+## See Also
+
+- Skill: `security-review`
+- Skill: `deployment-patterns`
+- Skill: `e2e-testing`
+- Skill: `tdd-workflow`
+- Skill: `verification-loop`

package/src/skills/security-bounty-hunter/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: security-bounty-hunter
+description: Hunt for exploitable, bounty-worthy security issues in repositories. Focuses on remotely reachable vulnerabilities that qualify for real reports instead of noisy local-only findings.
+origin: ECC direct-port adaptation
+version: "1.0.0"
+---
+
+# Security Bounty Hunter
+
+Use this when the goal is practical vulnerability discovery for responsible disclosure or bounty submission, not a broad best-practices review.
+
+## When to Use
+
+- Scanning a repository for exploitable vulnerabilities
+- Preparing a Huntr, HackerOne, or similar bounty submission
+- Triage where the question is "does this actually pay?" rather than "is this theoretically unsafe?"
+
+## How It Works
+
+Bias toward remotely reachable, user-controlled attack paths and throw away patterns that platforms routinely reject as informative or out of scope.
+
+## In-Scope Patterns
+
+These are the kinds of issues that consistently matter:
+
+| Pattern | CWE | Typical impact |
+| --- | --- | --- |
+| SSRF through user-controlled URLs | CWE-918 | internal network access, cloud metadata theft |
+| Auth bypass in middleware or API guards | CWE-287 | unauthorized account or data access |
+| Remote deserialization or upload-to-RCE paths | CWE-502 | code execution |
+| SQL injection in reachable endpoints | CWE-89 | data exfiltration, auth bypass, data destruction |
+| Command injection in request handlers | CWE-78 | code execution |
+| Path traversal in file-serving paths | CWE-22 | arbitrary file read or write |
+| Auto-triggered XSS | CWE-79 | session theft, admin compromise |
+
+## Skip These
+
+These are usually low-signal or out of bounty scope unless the program says otherwise:
+
+- Local-only `pickle.loads`, `torch.load`, or equivalent with no remote path
+- `eval()` or `exec()` in CLI-only tooling
+- `shell=True` on fully hardcoded commands
+- Missing security headers by themselves
+- Generic rate-limiting complaints without exploit impact
+- Self-XSS requiring the victim to paste code manually
+- CI/CD injection that is not part of the target program scope
+- Demo, example, or test-only code
+
+## Workflow
+
+1. Check scope first: program rules, SECURITY.md, disclosure channel, and exclusions.
+2. Find real entrypoints: HTTP handlers, uploads, background jobs, webhooks, parsers, and integration endpoints.
+3. Run static tooling where it helps, but treat it as triage input only.
+4. Read the real code path end to end.
+5. Prove user control reaches a meaningful sink.
+6. Confirm exploitability and impact with the smallest safe PoC possible.
+7. Check for duplicates before drafting a report.
+
+## Example Triage Loop
+
+```bash
+semgrep --config=auto --severity=ERROR --severity=WARNING --json
+```
+
+Then manually filter:
+
+- drop tests, demos, fixtures, vendored code
+- drop local-only or non-reachable paths
+- keep only findings with a clear network or user-controlled route
+
+## Report Structure
+
+```markdown
+## Description
+[What the vulnerability is and why it matters]
+
+## Vulnerable Code
+[File path, line range, and a small snippet]
+
+## Proof of Concept
+[Minimal working request or script]
+
+## Impact
+[What the attacker can achieve]
+
+## Affected Version
+[Version, commit, or deployment target tested]
+```
+
+## Quality Gate
+
+Before submitting:
+
+- The code path is reachable from a real user or network boundary
+- The input is genuinely user-controlled
+- The sink is meaningful and exploitable
+- The PoC works
+- The issue is not already covered by an advisory, CVE, or open ticket
+- The target is actually in scope for the bounty program

package/src/skills/security-scan/references/agentshield-policy-exception/candidate-playbook.md

@@ -0,0 +1,49 @@
+# AgentShield Policy Exception Playbook
+
+Candidate id: `sarif-backed-timeboxed-exception-review`
+
+Use this playbook when AgentShield organization-policy output produces a
+finding that may need remediation, a time-boxed exception, or explicit
+enforcement.
+
+## Accepted Path
+
+1. Identify the AgentShield finding id, category, severity, affected file or
+   MCP/hook surface, and policy pack or organization baseline.
+2. Retrieve scanner evidence before judgment:
+   - SARIF/code-scanning result, especially `agentshield-policy/*`
+   - JSON/HTML report evidence
+   - terminal or GitHub Action job-summary counts
+3. Record lifecycle fields for any exception request: owner, ticket, scope,
+   expiry, rationale, and whether it is active, expiring soon, or expired.
+4. Keep expired exceptions rejected or enforced until new evidence exists.
+5. Decide whether immediate remediation is possible. If not, only promote a
+   narrow time-boxed exception tied to the named owner, ticket, scope, and
+   expiry.
+6. Keep AgentShield code, policy packs, enforcement settings, release state,
+   and live security posture out of the read-only evaluator run.
+
+## Rejected Path
+
+Do not blanket suppress a policy category, policy pack, or organization gate
+because a finding is inconvenient.
+
+Do not downgrade critical/high findings without SARIF or report evidence and a
+current owner, ticket, scope, and expiry.
+
+Do not treat expired exceptions as active. Expired means the policy gate should
+remain enforced until a maintainer creates a fresh, bounded exception or fixes
+the underlying issue.
+
+## Minimum Validation
+
+- `npx ecc-agentshield scan --format json`
+- AgentShield SARIF/code-scanning artifact or report evidence
+- `npx ecc-agentshield scan --format html` when executive review evidence is
+  needed
+- Current exception lifecycle fields: owner, ticket, scope, expiry, status
+- `node tests/docs/evaluator-rag-prototype.test.js`
+- `git diff --check`
+
+Record the scanner evidence, lifecycle state, policy-pack source, and
+remediation-versus-exception decision in the maintainer PR body or handoff.

package/src/skills/security-scan/references/agentshield-policy-exception/report.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "ecc.evaluator-rag.report.v1",
+  "scenario_id": "agentshield-policy-exception",
+  "run_id": "2026-05-12-agentshield-policy-exception-prototype",
+  "result": "prototype_passed",
+  "read_only": true,
+  "scores": {
+    "sarif_report_evidence": 0.95,
+    "exception_lifecycle": 0.93,
+    "ownership_specificity": 0.9,
+    "remediation_decision": 0.88,
+    "blanket_suppression_safety": 1
+  },
+  "findings": [
+    {
+      "id": "sarif-report-match-required",
+      "severity": "warning",
+      "summary": "AgentShield policy exceptions must name SARIF or report evidence before a remediation or exception playbook can be promoted."
+    },
+    {
+      "id": "expired-exception-enforcement",
+      "severity": "warning",
+      "summary": "Expired exceptions must remain rejected or enforced; the evaluator cannot treat stale approvals as active evidence."
+    },
+    {
+      "id": "bounded-owner-fields",
+      "severity": "info",
+      "summary": "Accepted exceptions preserve owner, ticket, scope, expiry, policy-pack source, and affected surface fields."
+    }
+  ],
+  "recommended_next_action": {
+    "candidate_id": "sarif-backed-timeboxed-exception-review",
+    "action": "Use the promoted playbook for future AgentShield policy exception requests before changing gates, suppressing categories, or accepting security risk."
+  }
+}

package/src/skills/security-scan/references/agentshield-policy-exception/scenario.json

@@ -0,0 +1,62 @@
+{
+  "schema_version": "ecc.evaluator-rag.scenario.v1",
+  "scenario_id": "agentshield-policy-exception",
+  "title": "Gate AgentShield policy exceptions with report and SARIF evidence",
+  "mode": "read_only_prototype",
+  "objective": "Given an AgentShield organization-policy finding or proposed exception, retrieve report, SARIF, lifecycle, and ownership evidence before promoting a remediation or time-boxed exception playbook.",
+  "sources": [
+    {
+      "kind": "repo_doc",
+      "path": "docs/ECC-2.0-GA-ROADMAP.md",
+      "purpose": "Durable record of AgentShield policy gates, SARIF output, policy packs, reports, corpus benchmark, and exception lifecycle audit evidence"
+    },
+    {
+      "kind": "repo_command",
+      "path": "commands/security-scan.md",
+      "purpose": "ECC command contract for running AgentShield and separating scanner facts from follow-up judgment"
+    },
+    {
+      "kind": "repo_skill",
+      "path": "skills/security-scan/SKILL.md",
+      "purpose": "Operator-facing AgentShield scan workflow and output-format guidance"
+    },
+    {
+      "kind": "external_pr_evidence",
+      "repo": "affaan-m/agentshield",
+      "prs": [
+        55,
+        56,
+        57,
+        59,
+        60,
+        62
+      ],
+      "purpose": "Policy gate, SARIF, policy-pack, HTML report, corpus benchmark, and exception lifecycle implementation evidence"
+    }
+  ],
+  "retrieval_questions": [
+    "Which AgentShield policy finding, category, severity, and affected file or MCP/hook surface triggered the request?",
+    "Is there SARIF/code-scanning evidence for an `agentshield-policy/*` result, and does it match the report finding?",
+    "Is the exception active, expiring soon, or expired?",
+    "Does the exception include owner, ticket, scope, expiry, and rationale fields?",
+    "Which policy pack or organization baseline produced the finding?",
+    "Is remediation possible now, or is a bounded exception safer than a blanket suppression?"
+  ],
+  "forbidden_actions": [
+    "approving policy exceptions without SARIF or report evidence",
+    "treating expired exceptions as active",
+    "blanket-suppressing AgentShield policy packs or organization-policy gates",
+    "downgrading critical/high findings without owner, ticket, scope, and expiry",
+    "editing AgentShield code or policy files from this ECC evaluator run",
+    "publishing or enforcing new security policy from this read-only evaluator run"
+  ],
+  "acceptance_gates": [
+    "SARIF or report evidence is named",
+    "finding id, category, severity, and affected surface are preserved",
+    "policy pack or organization baseline is named",
+    "owner, ticket, scope, and expiry state are recorded",
+    "expired exceptions stay rejected or enforced",
+    "remediation versus time-boxed exception decision is explicit",
+    "at least one blanket suppression candidate is rejected"
+  ]
+}

package/src/skills/security-scan/references/agentshield-policy-exception/trace.json

@@ -0,0 +1,45 @@
+{
+  "schema_version": "ecc.evaluator-rag.trace.v1",
+  "scenario_id": "agentshield-policy-exception",
+  "run_id": "2026-05-12-agentshield-policy-exception-prototype",
+  "read_only": true,
+  "events": [
+    {
+      "phase": "observation",
+      "summary": "A policy finding or exception request references AgentShield organization-policy output. The evaluator records the affected finding without editing AgentShield code, policy packs, or enforcement settings.",
+      "evidence": [
+        "docs/ECC-2.0-GA-ROADMAP.md",
+        "commands/security-scan.md"
+      ]
+    },
+    {
+      "phase": "retrieval",
+      "summary": "Retrieved SARIF/report evidence, policy-pack source, exception lifecycle state, owner, ticket, scope, expiry, and whether remediation is immediately available.",
+      "evidence": [
+        "agentshield-policy/* SARIF result",
+        "AgentShield report exception counts",
+        "skills/security-scan/SKILL.md"
+      ]
+    },
+    {
+      "phase": "proposal",
+      "summary": "Generated two candidate playbooks: SARIF-backed time-boxed exception review, and blanket policy suppression for the affected category.",
+      "candidate_ids": [
+        "sarif-backed-timeboxed-exception-review",
+        "blanket-policy-suppression"
+      ]
+    },
+    {
+      "phase": "verification",
+      "summary": "Accepted the evidence-backed exception review because it preserves finding details and lifecycle fields. Rejected blanket suppression because it bypasses policy gates and ignores expired exceptions.",
+      "evidence": [
+        "examples/evaluator-rag-prototype/agentshield-policy-exception/verifier-result.json"
+      ]
+    },
+    {
+      "phase": "promotion",
+      "summary": "Promoted only the read-only AgentShield policy exception playbook. The evaluator does not modify AgentShield code, policy packs, enforcement settings, release state, or live security posture.",
+      "promoted_candidate_id": "sarif-backed-timeboxed-exception-review"
+    }
+  ]
+}

package/src/skills/security-scan/references/agentshield-policy-exception/verifier-result.json

@@ -0,0 +1,35 @@
+{
+  "schema_version": "ecc.evaluator-rag.verifier.v1",
+  "scenario_id": "agentshield-policy-exception",
+  "run_id": "2026-05-12-agentshield-policy-exception-prototype",
+  "read_only": true,
+  "candidates": [
+    {
+      "candidate_id": "sarif-backed-timeboxed-exception-review",
+      "decision": "accepted",
+      "score": 0.93,
+      "reasons": [
+        "names SARIF/code-scanning or report evidence for the AgentShield finding",
+        "preserves finding id, category, severity, affected surface, and policy-pack source",
+        "records owner, ticket, scope, expiry, and active/expiring/expired lifecycle state",
+        "rejects expired exceptions and requires remediation or a time-boxed exception",
+        "keeps AgentShield code, policy packs, enforcement settings, and release actions out of the read-only evaluator run"
+      ],
+      "rollback": "Do not apply the future exception or suppression; re-run AgentShield, restore the prior organization policy, and keep the finding enforced until owner/ticket/scope/expiry evidence is current."
+    },
+    {
+      "candidate_id": "blanket-policy-suppression",
+      "decision": "rejected",
+      "score": 0.11,
+      "reasons": [
+        "has no SARIF or report evidence",
+        "blanket-suppresses AgentShield policy packs and organization-policy gates",
+        "treats expired exceptions as active",
+        "drops owner, ticket, scope, and expiry fields",
+        "would edit AgentShield or policy gate behavior from an ECC evaluator run"
+      ],
+      "rollback": "Do not suppress the policy category; restart from scanner evidence, lifecycle state, and a bounded remediation or exception request."
+    }
+  ],
+  "promoted_candidate_id": "sarif-backed-timeboxed-exception-review"
+}

package/src/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