mindforge-cc 10.0.3 → 11.0.0

package/.mindforge/skills/audit-logging/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: audit-logging
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: audit logging, immutable audit trail, audit event, who what when why, retention policy, compliance logging, tamper detection, audit query, audit archival, audit schema, change tracking, audit correlation
+---
+
+# Skill — Audit Logging
+
+## When this skill activates
+Any task involving audit trails, compliance logging, change tracking, tamper detection,
+event recording for accountability, or data retention policies.
+
+## Mandatory actions when this skill is active
+
+### Before implementing audit logging
+1. Identify what events must be audited (regulatory + business requirements).
+2. Define the retention policy (how long, where stored, who can access).
+3. Design the event schema before writing any code.
+
+### Event schema (the 5 Ws)
+
+Every audit event MUST capture:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| **who** | user_id, IP address, session_id, service account | `{ userId: "u-123", ip: "10.0.1.5", sessionId: "sess-abc" }` |
+| **what** | action performed, resource affected, changes made | `{ action: "update", resource: "user/u-456", changes: { email: { from: "old@x.com", to: "new@x.com" } } }` |
+| **when** | UTC timestamp, monotonic sequence number | `{ timestamp: "2025-01-15T10:30:00Z", sequence: 1042 }` |
+| **why** | correlation_id, request_id, triggering event | `{ correlationId: "req-789", trigger: "user_request" }` |
+| **outcome** | success or failure, error details if failed | `{ status: "success" }` or `{ status: "failure", error: "permission_denied" }` |
+
+### Immutability guarantees
+
+**Append-only storage:**
+- Audit table has NO UPDATE or DELETE permissions for application roles.
+- Use a dedicated audit service account with INSERT-only grants.
+- Application database user must not have ALTER TABLE on audit tables.
+
+**Hash chain for tamper detection:**
+```
+event.hash = SHA-256(event.data + previous_event.hash)
+```
+- Each event references the hash of the previous event.
+- Broken chain = tampering detected.
+- Verify chain integrity on scheduled basis (daily audit job).
+
+**Alternative: immutable storage backends:**
+- AWS QLDB (purpose-built immutable ledger).
+- Object storage with Object Lock (S3 with WORM).
+- Append-only Kafka topic with compaction disabled.
+
+### Retention policy
+
+| Tier | Duration | Storage | Access |
+|------|----------|---------|--------|
+| Hot | 90 days | Primary database (indexed) | Real-time query |
+| Warm | 1 year | Object storage (Parquet/JSON) | Query via data warehouse |
+| Cold | 7+ years | Compressed archive (Glacier/equivalent) | Manual retrieval |
+
+**Rules:**
+- Define retention per event type (auth events may need longer than UI events).
+- Automate tier transitions (cron job moves hot → warm → cold).
+- Deletion must be cryptographic (delete encryption key, not data) for compliance.
+- Document retention policy in compliance documentation.
+
+### What to audit (mandatory events)
+
+**Authentication:**
+- Login success and failure (with failure reason).
+- Logout.
+- Password change / reset.
+- MFA enrollment / removal.
+- Session creation and termination.
+
+**Authorization:**
+- Permission grants and revocations.
+- Role assignments and removals.
+- Access denied events.
+
+**Data mutations:**
+- Create, update, delete of business entities.
+- Bulk operations (with count and scope).
+- Data exports and downloads.
+
+**Admin actions:**
+- Configuration changes.
+- User account management (create, disable, delete).
+- System setting modifications.
+
+**Failed access attempts:**
+- Rate limit violations.
+- Invalid token usage.
+- Attempts to access other tenants' data.
+
+### Querying audit logs
+
+**Required indexes:**
+- `user_id` — "show me everything user X did."
+- `resource_id` — "show me everything that happened to resource Y."
+- `timestamp` — "show me events in time range."
+- `action` — "show me all delete events."
+- `correlation_id` — "show me the full request chain."
+
+**Search capabilities:**
+- Full-text search on action descriptions.
+- Filter by outcome (success/failure).
+- Aggregate by user, resource, or time window.
+
+### Implementation patterns
+
+**Middleware/interceptor approach:**
+```
+Request → [Auth] → [Audit: log attempt] → Handler → [Audit: log outcome] → Response
+```
+
+**Event-driven approach:**
+- Domain events trigger audit entries asynchronously.
+- Decouples audit from business logic.
+- Risk: event loss if queue fails (use durable queue with DLQ).
+
+**Database trigger approach:**
+- PostgreSQL triggers capture all changes automatically.
+- No application code needed — cannot be bypassed.
+- Downside: less context (no user_id unless set in session).
+
+### Anti-patterns
+
+- Logging sensitive data in audit trail (passwords, full credit card numbers).
+- Audit log in same table/database as business data (lifecycle coupling).
+- Synchronous audit blocking the business transaction.
+- No alerting on audit failures (silent data loss).
+- Audit logs accessible to the application for modification.
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?

package/.mindforge/skills/auth-patterns/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: auth-patterns
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: auth architecture design, oauth2 flow design, oidc implementation, session strategy design, jwt architecture pattern, token rotation strategy, mfa flow design, social login integration, rbac model design, abac policy engine, authorization architecture, identity provider pattern
+compose: guardrails-and-safety
+---
+
+# Skill — Auth Patterns
+
+## When this skill activates
+Any task involving authentication flow design, authorization model selection,
+token lifecycle management, MFA implementation, or identity provider integration.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify the auth requirements: Who are the users? What are the trust boundaries?
+2. Select the appropriate OAuth2 flow for the client type.
+3. Decide between sessions and JWTs based on revocation requirements.
+4. Map out the authorization model (RBAC vs ABAC vs hybrid).
+
+### During implementation
+- Never store plain-text credentials anywhere.
+- Use short-lived access tokens (15 min max) with long-lived refresh tokens (7 days max).
+- Implement token rotation on every refresh (detect reuse = compromised).
+- Check permissions in code, never roles directly.
+- Log every auth failure with context (IP, user agent, timestamp).
+
+### After implementation
+- Verify no auth bypass exists on any protected route.
+- Test token expiration and refresh flows end-to-end.
+- Confirm MFA cannot be bypassed via API directly.
+- Run security scan on auth-related endpoints.
+
+## OAuth2 Flows
+
+### Authorization Code + PKCE (SPAs, Mobile)
+```
+1. Client generates code_verifier + code_challenge
+2. Redirect to /authorize with code_challenge
+3. User authenticates, IdP redirects with auth_code
+4. Client exchanges auth_code + code_verifier for tokens
+5. IdP verifies challenge, returns access + refresh tokens
+```
+Use for: Browser apps, mobile apps, any public client.
+
+### Client Credentials (Machine-to-Machine)
+```
+1. Service sends client_id + client_secret to /token
+2. IdP returns access token (no refresh token needed)
+3. Service uses access token for API calls
+```
+Use for: Backend services, cron jobs, microservice-to-microservice.
+
+### Device Authorization (CLI, TV)
+```
+1. Device requests device_code + user_code from /device/authorize
+2. User visits verification URL, enters user_code
+3. Device polls /token until user completes auth
+```
+Use for: CLI tools, IoT devices, smart TVs.
+
+## Session vs JWT
+
+### Sessions (Server-Side)
+- **Pros**: Instantly revocable, smaller payload, server controls lifetime.
+- **Cons**: Requires session store (Redis), sticky sessions or shared store in distributed systems.
+- **Use when**: You need instant revocation, have a monolith or can share session store.
+
+### JWT (Stateless)
+- **Pros**: No server-side storage, works across services, self-contained claims.
+- **Cons**: Cannot revoke until expiry (unless you add a blocklist, negating statelessness).
+- **Use when**: Microservices, short-lived tokens acceptable, combined with refresh token rotation.
+
+### Hybrid (Recommended)
+- Short-lived JWT access token (15 min) — never stored server-side.
+- Long-lived refresh token (7 days) — stored server-side, rotated on each use.
+- Revoke by deleting refresh token and waiting for access token expiry.
+
+## Token Rotation
+```
+1. Client sends refresh_token to /token
+2. Server issues NEW access_token + NEW refresh_token
+3. Server invalidates the OLD refresh_token
+4. If old refresh_token is used again → COMPROMISED
+5. Revoke entire token family (all refresh tokens for this session)
+```
+
+## MFA Implementation
+
+### TOTP (Time-Based One-Time Password) — Preferred
+- Generate shared secret, encode as QR code for authenticator apps.
+- Verify with time-window tolerance (±1 step = 30 seconds).
+- Store backup codes (hashed) for account recovery.
+
+### WebAuthn / Passkeys — Most Secure
+- Phishing-resistant (bound to origin).
+- No shared secrets to steal.
+- Use as primary or second factor.
+
+### SMS — Last Resort
+- Vulnerable to SIM swapping.
+- Use only if no alternative and combine with other signals.
+
+## Authorization Models
+
+### RBAC (Role-Based Access Control)
+```
+User → Role → Permissions → Actions
+
+// In code: check PERMISSION, not ROLE
+if (user.hasPermission('posts:delete')) { ... }
+// NOT: if (user.role === 'admin') { ... }
+```
+
+### ABAC (Attribute-Based Access Control)
+```
+Policy: user.department === resource.department AND user.clearance >= resource.classification
+
+// More flexible than RBAC, but harder to audit
+const allowed = evaluatePolicy(user.attributes, resource.attributes, action);
+```
+
+### Hybrid (RBAC + ABAC)
+- Use RBAC for coarse-grained access (can this user access this module?).
+- Use ABAC for fine-grained rules (can this user edit THIS specific resource?).
+
+## Anti-patterns to avoid
+- Storing JWT in localStorage (XSS vulnerable — use httpOnly cookies or memory).
+- Checking roles instead of permissions in application code.
+- Long-lived access tokens without refresh rotation.
+- MFA bypass via direct API calls (always enforce server-side).
+- Shared secrets in client-side code.
+- Missing auth on internal/admin routes ("it's internal" is not security).
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] No plain-text credentials stored anywhere?
+- [ ] Access tokens are short-lived (≤15 min)?
+- [ ] Refresh token rotation implemented and reuse detected?
+- [ ] Permissions checked in code (not roles)?
+- [ ] Every protected route has auth middleware?
+- [ ] Auth failures logged with sufficient context?
+- [ ] MFA cannot be bypassed via API?

package/.mindforge/skills/autonomous-agent-harness/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: autonomous-agent-harness
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: autonomous harness, persistent agent, background agent, scheduled execution, agent cron, task queue agent, self-monitoring agent, persistent memory agent, long-running agent, agent daemon, agent lifecycle, always-on agent
+---
+
+# Skill — Autonomous Agent Harness
+
+## When this skill activates
+
+When designing, implementing, or operating agents that persist beyond single
+conversation sessions. Use when building infrastructure for agents that run on
+schedules, maintain state across invocations, process task queues, self-monitor
+their health, or operate as background daemons.
+
+This skill covers the architecture layer between "single-shot agent conversation"
+and "production autonomous system" — the harness that manages lifecycle, memory,
+scheduling, and self-regulation.
+
+## Mandatory actions when this skill is active
+
+### Before designing the harness
+
+1. **Define the autonomy level:**
+
+   | Level | Description | Human oversight | Example |
+   |-------|-------------|-----------------|---------|
+   | L1 — Scheduled | Runs on cron, reports results | Review output post-run | Daily code review bot |
+   | L2 — Reactive | Triggers on events, acts within bounds | Alert on anomaly | PR auto-labeler |
+   | L3 — Proactive | Identifies tasks, proposes actions | Approve before execute | Dependency updater |
+   | L4 — Autonomous | Full loop with self-correction | Exception-only review | Incident responder |
+
+2. **Identify persistence requirements:**
+   - What state must survive between sessions? (task history, learned patterns, config)
+   - What is the acceptable data loss window? (none, last hour, last day)
+   - What is the memory format? (markdown files, SQLite, MCP server, JSON)
+   - How large will accumulated state grow over time?
+
+3. **Define boundaries and kill switches:**
+   - Maximum actions per invocation (prevent runaway loops)
+   - Maximum cost per session (token budget ceiling)
+   - Forbidden actions list (no force-push, no production deploys without approval)
+   - Human escalation triggers (confidence < threshold, high-impact decisions)
+   - Emergency stop mechanism (file-based kill switch, API endpoint)
+
+### During harness implementation
+
+**Core architecture components:**
+
+```
++------------------+     +------------------+     +------------------+
+|   Scheduler      |---->|   Task Queue     |---->|   Agent Core     |
+|  (cron/events)   |     |  (FIFO+priority) |     |  (LLM session)   |
++------------------+     +------------------+     +------------------+
+                                                         |
+                         +------------------+            |
+                         |  Self-Monitor    |<-----------+
+                         |  (health/budget) |            |
+                         +------------------+            v
+                                                  +------------------+
+                         +------------------+     |  Persistent      |
+                         |  Kill Switch     |     |  Memory          |
+                         |  (emergency stop)|     |  (MCP/markdown)  |
+                         +------------------+     +------------------+
+```
+
+**1. Persistent Memory System:**
+```
+.agent-harness/
+  memory/
+    knowledge-base.md      # Accumulated learnings and patterns
+    task-history.jsonl     # Every task executed with outcome
+    config.json            # Runtime configuration
+    state.json             # Current operational state
+  queues/
+    pending.jsonl          # Tasks awaiting execution
+    in-progress.jsonl      # Currently executing tasks
+    completed.jsonl        # Finished tasks (rotate after 30 days)
+    dead-letter.jsonl      # Failed tasks after max retries
+```
+
+- Knowledge base uses markdown for human-readable, agent-writable state
+- Task history is append-only JSONL for auditability
+- State file tracks: last run time, current task, health metrics, budget remaining
+- Integration with MindForge memory: read from `.mindforge/memory/`, write learnings back
+
+**2. Scheduled Execution:**
+```json
+{
+  "schedules": [
+    {
+      "name": "daily-review",
+      "cron": "0 9 * * 1-5",
+      "task": "review-open-prs",
+      "timeout_minutes": 30,
+      "max_retries": 2
+    },
+    {
+      "name": "continuous-monitor",
+      "interval_minutes": 15,
+      "task": "check-deployments",
+      "timeout_minutes": 5,
+      "max_retries": 1
+    }
+  ]
+}
+```
+
+- Cron expressions for periodic tasks
+- Interval-based polling for monitoring
+- Event-triggered execution (webhook, file watcher, git hook)
+- Each schedule entry defines timeout and retry policy independently
+
+**3. Task Queue:**
+```json
+{
+  "id": "task-uuid",
+  "created_at": "ISO-8601",
+  "priority": 1,
+  "type": "review-pr",
+  "payload": { "pr_number": 42, "repo": "org/project" },
+  "status": "pending",
+  "attempts": 0,
+  "max_attempts": 3,
+  "timeout_seconds": 1800,
+  "dead_letter_after": 3
+}
+```
+
+- FIFO within same priority level; higher priority preempts
+- Retry with exponential backoff: 1min, 5min, 25min
+- Dead letter queue for tasks that exceed max attempts
+- Idempotency keys prevent duplicate execution
+
+**4. Self-Monitoring:**
+```json
+{
+  "health": {
+    "last_heartbeat": "ISO-8601",
+    "consecutive_failures": 0,
+    "token_budget_remaining": 45000,
+    "token_budget_period": "daily",
+    "drift_score": 0.12,
+    "uptime_minutes": 1440
+  },
+  "alerts": [
+    {
+      "condition": "consecutive_failures > 3",
+      "action": "pause_and_notify"
+    },
+    {
+      "condition": "token_budget_remaining < 5000",
+      "action": "enter_low_power_mode"
+    },
+    {
+      "condition": "drift_score > 0.5",
+      "action": "request_human_review"
+    }
+  ]
+}
+```
+
+- Heartbeat every execution cycle (detect stalls)
+- Token budget tracking with low-power mode (reduce scope, not stop)
+- Drift detection: compare recent outputs to baseline patterns
+- Alert escalation: log → notify → pause → kill
+
+**5. Lifecycle Management:**
+
+```
+STARTUP → RUNNING → IDLE → WAKE → RUNNING → ... → SHUTDOWN
+   |         |                                         ^
+   |         +------- ERROR -----> RECOVERING ---------+
+   |                                    |
+   +--- BLOCKED (kill switch) ----------+
+```
+
+- **Startup:** Load config, validate memory integrity, check kill switch, announce ready
+- **Running:** Process task queue, update heartbeat, track budget
+- **Idle:** No pending tasks, reduce polling frequency, maintain heartbeat
+- **Wake:** New task arrived or schedule triggered, resume full operation
+- **Recovering:** After error, attempt self-repair, reload state, retry last task
+- **Shutdown:** Graceful — complete current task, flush state, log final report
+- **Blocked:** Kill switch active — cease all operations, preserve state, await unblock
+
+### After harness deployment
+
+1. **Operational verification:**
+   - Run a canary task through the full pipeline (schedule → queue → execute → report)
+   - Verify memory persistence across restarts
+   - Test kill switch responsiveness (must halt within 1 execution cycle)
+   - Confirm dead letter queue captures failed tasks correctly
+   - Validate budget tracking accuracy
+
+2. **Monitoring setup:**
+   - Dashboard showing: queue depth, success rate, token spend, last heartbeat
+   - Alerts for: stall (no heartbeat in 2x interval), budget exhaustion, error spike
+   - Weekly summary: tasks completed, failures, cost, learnings accumulated
+
+3. **Maintenance cadence:**
+   - Daily: review dead letter queue, check for stale tasks
+   - Weekly: rotate completed task log, prune knowledge base, verify budget projections
+   - Monthly: review drift trends, update boundaries, assess autonomy level appropriateness
+
+## Self-check before task completion
+
+Before marking an autonomous harness task done:
+
+- [ ] Did I define the autonomy level and appropriate human oversight?
+- [ ] Did I implement all 5 core components (memory, scheduler, queue, monitor, lifecycle)?
+- [ ] Did I define explicit boundaries (max actions, budget ceiling, forbidden actions)?
+- [ ] Did I implement a kill switch that halts within one execution cycle?
+- [ ] Did I set up retry logic with dead letter queue for failed tasks?
+- [ ] Did I configure self-monitoring with escalating alert thresholds?
+- [ ] Did I test the full lifecycle (startup through shutdown)?
+- [ ] Did I integrate with MindForge's existing memory and autonomous engine?

package/.mindforge/skills/autonomous-agents/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: autonomous-agents
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: autonomous agent design, agent loop architecture, tool use orchestration, AI planning system, agent self-correction, agentic workflow, agent reasoning loop, multi-agent collaboration, agent task decomposition, agent goal pursuit, agent reflection pattern, autonomous decision making
+compose:
+  - agent-orchestration-patterns
+---
+
+# Autonomous Agents & Reasoning Loops
+
+## When this skill activates
+
+This skill activates when building autonomous agents that pursue goals independently, implement planning and reasoning loops, use tools dynamically, self-correct errors, or coordinate across multiple agents. It applies to systems where AI must operate with minimal human intervention across multi-step tasks.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Define agent scope and boundaries** — Specify what the agent can do (available tools, permitted actions) and cannot do (restricted tools, human approval required). Define goal structure: explicit goals (user-provided task), implicit goals (system constraints, safety rules), and emergent goals (agent-discovered subgoals). Unbounded agents are dangerous.
+2. **Design the reasoning loop** — Choose loop architecture: ReAct (Reasoning + Acting), Plan-Act-Reflect, or Chain-of-Thought with Tool Use. Define loop termination conditions: goal achieved, max iterations reached (prevent infinite loops), error threshold exceeded, or human intervention requested. Document loop explicitly.
+3. **Select tool inventory** — Identify tools the agent can use: APIs (web search, database queries), code execution (sandboxed interpreters), file operations (read/write), external services (send email, create tickets). For each tool, define input schema, output schema, error modes, and safety constraints (rate limits, authorization).
+4. **Establish self-correction mechanisms** — Agents make mistakes (hallucinations, tool errors, reasoning failures). Design self-correction: validation (check outputs against constraints), reflection (analyze failures and adjust strategy), and retry logic (re-attempt with modified approach). Define max retry count to prevent infinite loops.
+
+### During implementation
+
+- **Implement explicit planning phase** — Before acting, the agent should decompose the goal into subtasks (task decomposition), estimate feasibility, and select tools. Plan structure: {goal, subtasks: [{action, tool, expected_outcome}], constraints, success_criteria}. Plans must be inspectable and modifiable by humans.
+- **Design tool calling with error handling** — Wrap every tool call in try-catch with explicit error handling: retry on transient errors (network failures, rate limits), escalate on permanent errors (invalid credentials, malformed inputs), and degrade gracefully (skip optional steps, use fallback tools). Log all tool calls with inputs, outputs, and errors.
+- **Build reflection and self-critique loops** — After each action or subtask completion, the agent should reflect: "Did this action achieve the expected outcome? If not, why? What should I try next?" Use structured reflection prompts: {action_taken, expected_outcome, actual_outcome, error_analysis, next_action}. Reflection improves multi-step task success rates by 20-40%.
+- **Implement goal-state tracking** — Maintain explicit state: current goal, progress toward goal (% complete, subtasks finished), blockers (errors, missing information), and next planned action. State must be serializable and resumable (agent can pause and resume later). Use structured state representations (JSON, database records).
+- **Design safety constraints** — Prevent harmful actions via pre-execution checks: validate tool inputs against safety rules (no file deletion without confirmation, no email to external addresses without review), enforce rate limits (max N API calls per minute), and require human approval for high-risk actions (financial transactions, data deletion).
+- **Implement multi-agent coordination** — When multiple agents collaborate, define communication protocols: message passing (agents send structured messages), shared state (agents read/write common store), or supervisor coordination (central agent dispatches tasks). Avoid race conditions and deadlocks: use locks, optimistic concurrency, or single-writer patterns.
+
+### After implementation
+
+- **Validate goal completion accuracy** — Test the agent on a suite of goals with known correct solutions. Measure success rate (% of goals fully achieved), partial success rate (% of goals partially achieved), and failure modes (why did the agent fail?). Target: >80% success rate for well-defined goals.
+- **Measure loop efficiency** — Track iterations per goal (how many reasoning steps until completion). More iterations = higher cost and latency. Target: <10 iterations for most tasks. If higher, improve planning quality or provide better tools.
+- **Test self-correction effectiveness** — Simulate tool errors (API returns invalid data, file not found, timeout) and validate that the agent recovers gracefully. Measure recovery rate (% of errors successfully handled without human intervention). Target: >70% recovery rate.
+- **Audit for infinite loops and runaway costs** — Test with adversarial goals designed to trigger infinite loops (unsolvable tasks, circular dependencies). Validate that termination conditions activate (max iterations, timeout, error threshold). Monitor token usage and cost per goal in production.
+
+## Self-check before task completion
+
+- [ ] Agent scope is defined with explicit permitted and restricted tools
+- [ ] Goal structure includes explicit (user-provided), implicit (system constraints), and emergent goals
+- [ ] Reasoning loop architecture (ReAct/Plan-Act-Reflect/CoT+Tools) is selected and documented
+- [ ] Loop termination conditions prevent infinite loops (max iterations, timeout, error threshold)
+- [ ] Tool inventory is documented with input/output schemas and error modes per tool
+- [ ] Self-correction mechanisms include validation, reflection, and retry logic with max retry limits
+- [ ] Planning phase decomposes goals into subtasks with feasibility estimates
+- [ ] Tool calls are wrapped with error handling (retry transient, escalate permanent, degrade gracefully)
+- [ ] Reflection loops analyze action outcomes and adjust strategy ({action, expected, actual, error_analysis, next})
+- [ ] Goal-state tracking maintains serializable, resumable state (progress, blockers, next action)
+- [ ] Safety constraints validate tool inputs pre-execution and enforce rate limits
+- [ ] Multi-agent coordination uses message passing, shared state, or supervisor patterns without race conditions
+- [ ] Goal completion accuracy is validated at >80% success rate on test suite
+- [ ] Loop efficiency is measured (target <10 iterations per task)
+- [ ] Self-correction effectiveness is tested with simulated tool errors (target >70% recovery rate)
+- [ ] Infinite loop prevention is validated with adversarial goals and termination condition testing

package/.mindforge/skills/build-system-optimization/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: build-system-optimization
+version: 1.0.0
+min_mindforge_version: 10.7.0
+status: stable
+triggers: build system optimization, build cache architecture, incremental build design, remote build execution, dependency graph optimization, build farm design, Bazel Buck optimization, build time reduction, distributed build, build artifact caching, hermetic build, build reproducibility
+---
+
+# Skill — Build System Optimization
+
+## When this skill activates
+
+This skill activates when the user is optimizing build systems for speed and reliability. This includes build cache architecture, incremental builds, remote build execution, dependency graph optimization, build farm design, Bazel/Buck/Gradle optimization, build time reduction, distributed builds, artifact caching, hermetic builds, and build reproducibility.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. Establish baseline build times: clean build (no cache), incremental build (single file change), and CI build. Measure p50, p95, p99.
+2. Profile the build to identify bottlenecks: dependency resolution, compilation, linking, testing, packaging. Use build system profiling tools (Gradle Build Scan, Bazel analyze-profile).
+3. Audit dependency graph: identify unnecessary dependencies, circular dependencies, and overly-coupled modules.
+4. Assess cache hit rates: local cache, remote cache, CI cache. Identify cache invalidation causes (non-deterministic inputs, timestamp dependencies).
+5. Determine build reproducibility: same source + same toolchain = identical binary. Test by building twice and comparing checksums.
+
+### During implementation
+
+- **Incremental Builds:** Only rebuild changed modules and their dependents. Requires accurate dependency tracking. Bazel and Buck are incremental by design. Gradle requires careful task input/output declaration. Target: single-file change rebuild in under 30 seconds.
+- **Build Caching:** Layer caching at multiple levels: local (developer machine), shared (team), remote (CI). Use content-addressable storage (hash inputs to determine cache key). Cache should serve 80%+ of CI builds from cache.
+- **Remote Build Execution:** Offload compilation and tests to remote workers (Bazel Remote Execution, BuildBuddy, Gradle Enterprise). Provides massive parallelism (100+ workers). Requires hermetic builds.
+- **Dependency Graph Optimization:** Reduce fan-out (modules with many dependents). Split large modules into smaller ones. Use interface modules to break circular dependencies. Visualize graph with Bazel query or Gradle's dependency graph plugin.
+- **Hermetic Builds:** All inputs (source, toolchain, dependencies) must be explicit. No reliance on global state (env vars, system tools, internet access during build). Hermetic builds enable reproducibility and remote caching.
+- **Build Artifact Caching:** Cache compiled binaries, test results, and packaged artifacts. Use content-addressable storage (Artifactory, Nexus, S3). Artifacts should be immutable (never overwrite).
+- **Parallelization:** Build independent modules in parallel. Bazel parallelizes by default. Gradle requires `org.gradle.parallel=true`. Monitor CPU utilization (target: 80%+ during build).
+- **Build Farm Design:** Centralized build cluster with auto-scaling workers. Use spot instances for cost savings. Workers should be stateless and ephemeral. Monitor queue depth and scale workers accordingly.
+- **Build Time Reduction Targets:** Clean build under 10 minutes. Incremental build under 1 minute. CI build (with cache) under 5 minutes.
+
+### After implementation
+
+- Verify incremental builds only rebuild changed modules and dependents (use build system logs to confirm).
+- Confirm cache hit rates exceed 80% in CI and 90% for developers (for incremental builds).
+- Validate remote build execution distributes work across workers (monitor parallelism and CPU utilization).
+- Ensure builds are hermetic by building in a clean container and comparing output checksums.
+- Check that build artifact cache is content-addressable and serves artifacts in under 2 seconds.
+
+## Self-check before task completion
+
+- [ ] Baseline build times are measured (clean, incremental, CI) and tracked over time.
+- [ ] Incremental builds only rebuild changed modules (verified via build logs).
+- [ ] Build caching achieves 80%+ cache hit rate in CI.
+- [ ] Remote build execution distributes work across workers with 80%+ CPU utilization.
+- [ ] Dependency graph is optimized (reduced fan-out, no circular dependencies).
+- [ ] Builds are hermetic (no reliance on global state or internet access).
+- [ ] Build artifacts are cached in content-addressable storage and immutable.
+- [ ] Build time targets are met: clean <10min, incremental <1min, CI <5min.