hatch3r 1.0.0 → 1.2.0

package/rules/hatch3r-i18n.md

@@ -1,7 +1,10 @@
 ---
+id: hatch3r-i18n
+type: rule
 description: Internationalization, localization, and RTL support conventions for the project
+scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.ts
-alwaysApply: false
+tags: [implementation]
 ---
 # Internationalization & RTL
 

package/rules/hatch3r-learning-consult.md

@@ -3,14 +3,15 @@ id: hatch3r-learning-consult
 type: rule
 description: Auto-consult project learnings before implementation
 scope: always
+tags: [core]
 ---
 # Learning Consultation
 
-Before implementing any task, check `/.agents/learnings/` for relevant past learnings.
+Before implementing any task, check `.agents/learnings/` for relevant past learnings.
 
 ## Consultation Process
 
-1. If `/.agents/learnings/` exists and contains files:
+1. If `.agents/learnings/` exists and contains files:
    - Scan learning file frontmatter for matching `tags` or `area` that overlap with the current task.
    - Read the `## Applies When` section of potential matches.
    - Surface relevant learnings to the developer/agent before implementation begins.
@@ -20,6 +21,7 @@ Before implementing any task, check `/.agents/learnings/` for relevant past lear
 
 - During `hatch3r-board-pickup` Step 6: consult learnings before implementation delegation.
 - During `hatch3r-board-fill` Step 4: consult learnings when scoping and estimating issues.
+- During `hatch3r-board-groom` Step 4c: consult learnings when re-scoping or reclassifying existing issues.
 - During any skill execution: check for relevant pitfalls before coding.
 
 ## Learning Priority

package/rules/hatch3r-learning-consult.mdc

@@ -4,11 +4,11 @@ alwaysApply: true
 ---
 # Learning Consultation
 
-Before implementing any task, check `/.agents/learnings/` for relevant past learnings.
+Before implementing any task, check `.agents/learnings/` for relevant past learnings.
 
 ## Consultation Process
 
-1. If `/.agents/learnings/` exists and contains files:
+1. If `.agents/learnings/` exists and contains files:
    - Scan learning file frontmatter for matching `tags` or `area` that overlap with the current task.
    - Read the `## Applies When` section of potential matches.
    - Surface relevant learnings to the developer/agent before implementation begins.
@@ -18,6 +18,7 @@ Before implementing any task, check `/.agents/learnings/` for relevant past lear
 
 - During `hatch3r-board-pickup` Step 6: consult learnings before implementation delegation.
 - During `hatch3r-board-fill` Step 4: consult learnings when scoping and estimating issues.
+- During `hatch3r-board-groom` Step 4c: consult learnings when re-scoping or reclassifying existing issues.
 - During any skill execution: check for relevant pitfalls before coding.
 
 ## Learning Priority

package/rules/hatch3r-migrations.md

@@ -3,6 +3,7 @@ id: hatch3r-migrations
 type: rule
 description: Database migration and schema change patterns for the project
 scope: always
+tags: [implementation, brownfield]
 ---
 # Migrations
 
@@ -15,3 +16,14 @@ scope: always
 - Document schema changes in project data model spec.
 - Rollback plan required for every migration. Never run destructive migrations without backup verification.
 - Hot documents must stay within size limits after migration.
+
+## Data Validation During Migration
+
+- Validate data integrity after each migration step, not just at the end. Check that migrated records match the expected schema, required fields are populated, and no data was silently dropped.
+- Include count checks: the number of records processed should match the number of records in the source collection. Log discrepancies as errors, not warnings.
+- For large datasets, migrate in batches with progress checkpoints. If a batch fails, resume from the last checkpoint rather than restarting the entire migration.
+
+## Migration Coordination in Multi-Service Environments
+
+- When a migration affects shared data (e.g., a schema used by multiple services), coordinate the migration order across services. The consuming services must be deployed with backward-compatible readers before the migration runs.
+- Never assume that all service instances will be running the same code version during a migration window. Design migrations to tolerate mixed-version reads and writes during the rollout period.

package/rules/hatch3r-observability.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-observability
+type: rule
 description: Logging, metrics, and tracing conventions for the project
-alwaysApply: false
+scope: conditional
+tags: [devops]
 ---
 # Observability
 
@@ -163,3 +166,292 @@ Every telemetry-producing service must declare resource attributes at startup:
 - Attribute values should be low-cardinality. Never use unbounded values (full URLs with query params, raw SQL, user-generated content) as attribute values.
 - For high-cardinality identifiers (user IDs, request IDs), use span attributes sparingly and rely on correlated logs for detail.
 - Prefer semantic convention attributes over custom attributes. When custom attributes are necessary, prefix them with your organization or project namespace (e.g., `myapp.feature.flag_key`).
+
+### AI Agent Semantic Conventions
+
+Follow the [OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (experimental, introduced 2024) for instrumenting AI/LLM agent systems. These conventions provide consistent attribute naming for generative AI operations, enabling interoperability across agent frameworks and observability backends.
+
+#### `gen_ai.*` Span Attributes
+
+Use these attributes on all spans that represent interactions with generative AI models:
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `gen_ai.system` | string | The GenAI provider system name | `openai`, `anthropic`, `azure_openai` |
+| `gen_ai.request.model` | string | Model name as specified in the request | `gpt-4o`, `claude-sonnet-4-20250514` |
+| `gen_ai.response.model` | string | Model name as returned in the response (may differ from request) | `gpt-4o-2024-08-06` |
+| `gen_ai.request.max_tokens` | int | Maximum number of tokens requested for generation | `4096` |
+| `gen_ai.request.temperature` | float | Temperature parameter sent in the request | `0.7` |
+| `gen_ai.request.top_p` | float | Top-p (nucleus sampling) parameter | `0.9` |
+| `gen_ai.response.finish_reasons` | string[] | Reasons the model stopped generating | `["stop"]`, `["length"]`, `["tool_calls"]` |
+| `gen_ai.usage.input_tokens` | int | Number of tokens in the input/prompt | `1250` |
+| `gen_ai.usage.output_tokens` | int | Number of tokens in the generated output | `530` |
+
+- Always set `gen_ai.system` and `gen_ai.request.model` on every GenAI span. These are required for meaningful filtering and cost attribution.
+- Record `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response to enable token usage dashboards and cost tracking.
+- Use `gen_ai.response.finish_reasons` to detect truncated outputs (`length`) and trigger re-prompting or alerting logic.
+
+#### Agent Invocation Spans
+
+Instrument the full lifecycle of an agent invocation with a dedicated span. This span is the parent for all LLM calls, tool executions, and sub-agent delegations within a single agent run.
+
+- **Span name pattern:** `agent.{agent_name}.invoke` (e.g., `agent.code_reviewer.invoke`, `agent.research_assistant.invoke`)
+- **Required attributes:**
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `agent.id` | string | Unique identifier for this agent invocation | `agent-run-a1b2c3d4` |
+| `agent.name` | string | Logical name of the agent | `code_reviewer` |
+| `agent.parent_id` | string | ID of the parent agent (for sub-agent delegation chains) | `agent-run-x9y8z7` |
+| `agent.task` | string | High-level description of the agent's assigned task | `review PR #42` |
+| `agent.framework` | string | Agent framework in use | `langchain`, `autogen`, `custom` |
+
+- **Span events for state transitions:** Record span events to mark key lifecycle transitions within the agent invocation:
+  - `agent.planning` — Agent begins task decomposition or reasoning.
+  - `agent.tool_selection` — Agent selects a tool to invoke.
+  - `agent.awaiting_human` — Agent pauses for human-in-the-loop confirmation.
+  - `agent.delegating` — Agent spawns a sub-agent.
+  - `agent.completed` — Agent finishes its task and produces a final output.
+  - `agent.error` — Agent encounters a non-recoverable error. Include `exception.type` and `exception.message` attributes on the event.
+
+```typescript
+const agentSpan = tracer.startSpan('agent.code_reviewer.invoke', {
+  attributes: {
+    'agent.id': invocationId,
+    'agent.name': 'code_reviewer',
+    'agent.parent_id': parentAgentId ?? '',
+    'agent.task': `review PR #${prNumber}`,
+    'agent.framework': 'custom',
+  },
+});
+
+agentSpan.addEvent('agent.planning');
+// ... agent reasoning and tool calls happen as child spans ...
+agentSpan.addEvent('agent.completed');
+agentSpan.end();
+```
+
+#### Tool Call Spans
+
+Every tool invocation by an agent creates a child span of the agent invocation span. This enables tracing the full sequence of tool calls within an agent run, measuring tool latency, and detecting tool failures.
+
+- **Span name pattern:** `tool.{tool_name}.execute` (e.g., `tool.file_read.execute`, `tool.web_search.execute`)
+- **Required attributes:**
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `tool.name` | string | Canonical name of the tool | `file_read`, `git_diff`, `web_search` |
+| `tool.input_hash` | string | SHA-256 hash of the tool input (for deduplication, not logging raw input) | `sha256:3a7f...` |
+| `tool.output_status` | string | Outcome of the tool execution | `success`, `error`, `timeout`, `rejected` |
+| `tool.duration_ms` | float | Wall-clock execution time of the tool in milliseconds | `142.5` |
+| `tool.parameters_count` | int | Number of parameters passed to the tool | `3` |
+
+- **Parent-child relationship:** Tool spans must be children of the invoking agent span. Use `context.with(trace.setSpan(context.active(), agentSpan))` to propagate the agent span context to tool execution.
+- Set span status to `ERROR` when `tool.output_status` is `error` or `timeout`. Attach exception details as a span event.
+- For tools that perform I/O (HTTP requests, file system operations, database queries), create nested child spans using the appropriate semantic conventions (`http.*`, `db.*`) under the tool span.
+
+```typescript
+const toolSpan = tracer.startSpan(
+  'tool.git_diff.execute',
+  { attributes: { 'tool.name': 'git_diff' } },
+  trace.setSpan(context.active(), agentSpan),
+);
+
+const startTime = performance.now();
+try {
+  const result = await tools.gitDiff(params);
+  toolSpan.setAttributes({
+    'tool.output_status': 'success',
+    'tool.duration_ms': performance.now() - startTime,
+    'tool.input_hash': hashInput(params),
+  });
+} catch (err) {
+  toolSpan.setAttributes({
+    'tool.output_status': 'error',
+    'tool.duration_ms': performance.now() - startTime,
+  });
+  toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  toolSpan.recordException(err);
+  throw err;
+} finally {
+  toolSpan.end();
+}
+```
+
+#### LLM Request/Response Tracing
+
+Instrument every LLM API call with a dedicated span. These spans are typically children of an agent invocation span and capture model, token usage, and latency data for cost analysis and performance monitoring.
+
+- **Span name pattern:** `gen_ai.{operation}` (e.g., `gen_ai.chat`, `gen_ai.completion`, `gen_ai.embeddings`)
+- **Required attributes:** All applicable `gen_ai.*` attributes from the table above, plus:
+
+| Attribute | Type | Description | Example |
+|-----------|------|-------------|---------|
+| `gen_ai.operation.name` | string | The specific API operation | `chat`, `completion`, `embeddings` |
+| `gen_ai.request.stop_sequences` | string[] | Stop sequences sent in the request | `["\n\n", "END"]` |
+| `server.address` | string | Hostname of the GenAI API endpoint | `api.openai.com` |
+| `server.port` | int | Port of the GenAI API endpoint | `443` |
+
+- **Input/output token tracking:** Always capture `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens` from the API response. Aggregate these in metrics for cost dashboards:
+  - Counter: `gen_ai.tokens_total` with labels `{direction=input|output, model, agent_name}`
+  - Histogram: `gen_ai.request_duration_ms` with labels `{model, operation, agent_name}`
+
+- **Model version tracking:** Record both `gen_ai.request.model` (what was requested) and `gen_ai.response.model` (what was actually used). API providers may silently route to different model versions; capturing both enables drift detection.
+
+- **Error handling and retry spans:** When an LLM request fails and is retried, each attempt is a separate child span under the same parent. Record the error on the failed span and create a new span for the retry:
+  - Set `gen_ai.request.retries` (int) on the final successful span to indicate total retry count.
+  - Record `http.response.status_code` on failed spans to distinguish rate-limit errors (429) from server errors (500+).
+  - Use exponential backoff; the retry span's start time naturally captures the wait duration.
+
+```typescript
+const llmSpan = tracer.startSpan(
+  'gen_ai.chat',
+  {
+    attributes: {
+      'gen_ai.system': 'openai',
+      'gen_ai.operation.name': 'chat',
+      'gen_ai.request.model': 'gpt-4o',
+      'gen_ai.request.max_tokens': 4096,
+      'gen_ai.request.temperature': 0.2,
+      'server.address': 'api.openai.com',
+    },
+  },
+  trace.setSpan(context.active(), agentSpan),
+);
+
+try {
+  const response = await openai.chat.completions.create({ /* ... */ });
+  llmSpan.setAttributes({
+    'gen_ai.response.model': response.model,
+    'gen_ai.response.finish_reasons': response.choices.map(c => c.finish_reason),
+    'gen_ai.usage.input_tokens': response.usage.prompt_tokens,
+    'gen_ai.usage.output_tokens': response.usage.completion_tokens,
+  });
+
+  // Record token usage in metrics for cost tracking
+  tokenCounter.add(response.usage.prompt_tokens, {
+    direction: 'input', model: response.model, agent_name: agentName,
+  });
+  tokenCounter.add(response.usage.completion_tokens, {
+    direction: 'output', model: response.model, agent_name: agentName,
+  });
+} catch (err) {
+  llmSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+  llmSpan.recordException(err);
+  throw err;
+} finally {
+  llmSpan.end();
+}
+```
+
+- Never log raw prompt content or full model responses as span attributes — these are high-cardinality and may contain sensitive data. Use `gen_ai.usage.*` token counts for cost tracking and correlated logs for prompt debugging in non-production environments.
+- In production, sample GenAI spans at a higher rate than general spans (e.g., 50-100%) because each call is expensive and lower volume than typical HTTP traffic. Adjust sampling based on call volume and observability budget.
+
+### Tool Call Audit Trail
+
+Maintain a structured audit log for every tool invocation in agentic workflows. This log is separate from tracing spans and serves as an immutable compliance and debugging record.
+
+#### Schema Definition
+
+Every tool call audit log entry must include the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool.name` | string | Name of the tool invoked |
+| `tool.input_hash` | string | SHA-256 hash of the tool input (for privacy, never log raw input) |
+| `tool.output_status` | string | Outcome of the tool execution: `success`, `error`, `timeout`, or `denied` |
+| `tool.duration_ms` | float | Execution time in milliseconds |
+| `agent.id` | string | ID of the agent that invoked the tool |
+| `agent.name` | string | Human-readable agent name |
+| `correlation.id` | string | Trace correlation ID linking this entry to the broader workflow |
+| `timestamp` | string | ISO 8601 timestamp of the invocation |
+| `session.id` | string | Session identifier for grouping related tool calls |
+
+#### Logging Requirements
+
+- Log every tool invocation at `info` level with the full schema above.
+- Log tool failures at `error` level with additional `error.type` and `error.message` fields describing the failure.
+- Aggregate tool call counts per agent per session for anomaly detection (e.g., an agent invoking an unusual number of tools may indicate a loop or misconfiguration).
+- Retain audit logs for a minimum of 90 days to support post-incident investigation and compliance review.
+
+#### Example Log Entry
+
+```json
+{
+  "timestamp": "2026-02-15T14:32:07.891Z",
+  "level": "info",
+  "correlation.id": "agent-run-550e8400-e29b-41d4-a716-446655440000",
+  "session.id": "sess-8f14e45f-ceea-467f-a8f0-3b5c6d7e8f9a",
+  "agent.id": "agent-run-a1b2c3d4",
+  "agent.name": "code_reviewer",
+  "tool.name": "git_diff",
+  "tool.input_hash": "sha256:3a7f2c9e8b1d4f6a0e5c7b9d2f4a6e8c0b3d5f7a9e1c3b5d7f9a2c4e6b8d0f",
+  "tool.output_status": "success",
+  "tool.duration_ms": 142.5
+}
+```
+
+### Correlation IDs for Agent Workflows
+
+Correlation IDs provide the connective thread linking all telemetry signals (logs, spans, metrics) across a multi-agent workflow. Every participant in the workflow uses the same correlation ID, enabling end-to-end traceability from the initial trigger through all agent delegations and tool calls.
+
+#### ID Generation
+
+- Use UUIDv4 for correlation IDs. Generate the ID at the workflow entry point (the first agent invocation or the orchestrator that initiates the run).
+- Format: `{workflow-type}-{uuid}` (e.g., `agent-run-550e8400-e29b-41d4-a716-446655440000`, `review-flow-7c9e6679-7425-40de-944b-e07fc1f90ae7`).
+- The workflow-type prefix provides human-readable context when scanning logs and makes it possible to filter by workflow category without parsing the full ID.
+
+#### Propagation
+
+- The correlation ID propagates from the parent agent to all sub-agents via context. Pass it explicitly when delegating to sub-agents or invoking tools.
+- Every log entry, span, and metric produced during the workflow must include the `correlation.id` attribute.
+- When crossing process boundaries (e.g., HTTP calls between services), propagate the correlation ID via a custom header (`X-Correlation-ID`) alongside standard W3C Trace Context headers.
+
+#### Parent-Child Span Linking
+
+- The parent agent's span ID becomes the `parent_span_id` attribute on child agent spans, establishing a clear hierarchy in trace visualizations.
+- For cross-workflow references (e.g., an agent run triggered by a CI pipeline event), use OpenTelemetry `SpanLink` to connect the agent workflow trace to the originating trace without creating a parent-child relationship.
+- SpanLinks preserve the independence of each workflow trace while enabling navigation between related workflows in the observability backend.
+
+#### Implementation Pattern
+
+```typescript
+import { randomUUID } from 'node:crypto';
+import { context, trace, SpanStatusCode } from '@opentelemetry/api';
+
+function generateCorrelationId(workflowType: string): string {
+  return `${workflowType}-${randomUUID()}`;
+}
+
+async function runAgentWorkflow(task: string): Promise<void> {
+  const correlationId = generateCorrelationId('agent-run');
+  const tracer = trace.getTracer('agent-orchestrator');
+
+  const rootSpan = tracer.startSpan('agent.orchestrator.invoke', {
+    attributes: {
+      'correlation.id': correlationId,
+      'agent.name': 'orchestrator',
+      'agent.task': task,
+    },
+  });
+
+  const ctx = trace.setSpan(context.active(), rootSpan);
+
+  try {
+    // Sub-agent inherits the correlation ID from context
+    await context.with(ctx, async () => {
+      await delegateToSubAgent('code_reviewer', {
+        correlationId,
+        parentSpanId: rootSpan.spanContext().spanId,
+        task: 'review changes',
+      });
+    });
+  } catch (err) {
+    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: (err as Error).message });
+    rootSpan.recordException(err as Error);
+    throw err;
+  } finally {
+    rootSpan.end();
+  }
+}
+```

package/rules/hatch3r-performance-budgets.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-performance-budgets
+type: rule
 description: Performance budgets and targets for the project
-alwaysApply: false
+scope: conditional
+tags: [performance]
 ---
 # Performance Budgets
 
@@ -105,5 +108,5 @@ Targets align with Google's "Good" thresholds (measured at p75 from real user da
 | Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
 | Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
 
-- Automated regression detection: compare each PR's metrics against the `main` branch baseline. Flag regressions > 5% in any budget metric.
+- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.agents/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
 - Review performance budgets quarterly and tighten thresholds as the application matures.

package/rules/hatch3r-performance-budgets.mdc

@@ -105,5 +105,5 @@ Targets align with Google's "Good" thresholds (measured at p75 from real user da
 | Memory / CPU       | Chrome DevTools, profiler          | Infrastructure metrics (Prometheus) |
 | Visual regression  | Playwright screenshot diffing      | RUM CLS tracking                 |
 
-- Automated regression detection: compare each PR's metrics against the `main` branch baseline. Flag regressions > 5% in any budget metric.
+- Automated regression detection: compare each PR's metrics against the default branch baseline (`board.defaultBranch` from `.agents/hatch.json`; fallback: `"main"`). Flag regressions > 5% in any budget metric.
 - Review performance budgets quarterly and tighten thresholds as the application matures.

package/rules/hatch3r-secrets-management.md

@@ -3,6 +3,7 @@ id: hatch3r-secrets-management
 type: rule
 description: Secret management, rotation, and secure handling patterns for the project
 scope: always
+tags: [security]
 ---
 # Secrets Management
 
@@ -42,9 +43,13 @@ scope: always
 ## CI/CD Secret Injection
 
 - **GitHub Actions:** Store secrets in repository or organization settings. Reference via `${{ secrets.SECRET_NAME }}`. Never echo secrets in workflow logs — use masking (`::add-mask::`). Use environment-scoped secrets for production deployments with required reviewers.
+- **Azure DevOps Pipelines:** Store secrets as pipeline variables marked "secret" or in Azure Key Vault linked variable groups. Reference via `$(SECRET_NAME)`. Use service connections with scoped permissions. Never log secret variables — Azure automatically masks variables marked as secret.
 - **GitLab CI:** Store in project or group CI/CD variables. Mark as "Protected" (only available on protected branches) and "Masked" (redacted from logs). Use file-type variables for multi-line secrets (certificates, keys).
-- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action versions by SHA (not tag) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
-- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation (e.g., GitHub Actions `aws-actions/configure-aws-credentials` with OIDC) instead of long-lived credentials.
+- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action/task versions by SHA or exact version (not mutable tags) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
+- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation instead of long-lived credentials:
+  - **GitHub Actions:** `aws-actions/configure-aws-credentials` with OIDC
+  - **Azure DevOps:** Workload Identity Federation with service connections
+  - **GitLab CI:** OIDC ID tokens via `id_tokens` keyword
 
 ## Application-Level Secret Handling
 
@@ -59,7 +64,10 @@ scope: always
 
 - **gitleaks:** Run `gitleaks detect` in CI on every push and PR. Configure `.gitleaks.toml` with project-specific rules and allowlists for false positives (test fixtures, documentation examples).
 - **TruffleHog:** Use `trufflehog git` for historical scanning of the full repository. Run quarterly or on suspected compromise. Focus on high-entropy strings and known secret patterns.
-- **GitHub Secret Scanning:** Enable GitHub's built-in secret scanning and push protection. Configure custom patterns for project-specific secret formats.
+- **Platform secret scanning:** Enable the platform's built-in secret scanning and push protection:
+  - **GitHub:** GitHub Secret Scanning with push protection. Configure custom patterns for project-specific secret formats.
+  - **Azure DevOps:** Microsoft Defender for DevOps or Credential Scanner task in pipelines.
+  - **GitLab:** GitLab Secret Detection CI template (`Secret-Detection.gitlab-ci.yml`). Configure custom rulesets for project-specific patterns.
 - **Pre-commit hooks:** Install a local pre-commit hook (e.g., `gitleaks protect --staged`) to catch secrets before they reach the remote. This is defense-in-depth — CI scanning is still required.
 - **Remediation SLA:** Secrets detected in CI must be rotated immediately (within 1 hour for production secrets). Assume any secret that reached a commit is compromised, even if the commit was force-pushed away — git history is recoverable.
 

package/rules/hatch3r-secrets-management.mdc

@@ -40,9 +40,13 @@ alwaysApply: true
 ## CI/CD Secret Injection
 
 - **GitHub Actions:** Store secrets in repository or organization settings. Reference via `${{ secrets.SECRET_NAME }}`. Never echo secrets in workflow logs — use masking (`::add-mask::`). Use environment-scoped secrets for production deployments with required reviewers.
+- **Azure DevOps Pipelines:** Store secrets as pipeline variables marked "secret" or in Azure Key Vault linked variable groups. Reference via `$(SECRET_NAME)`. Use service connections with scoped permissions. Never log secret variables — Azure automatically masks variables marked as secret.
 - **GitLab CI:** Store in project or group CI/CD variables. Mark as "Protected" (only available on protected branches) and "Masked" (redacted from logs). Use file-type variables for multi-line secrets (certificates, keys).
-- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action versions by SHA (not tag) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
-- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation (e.g., GitHub Actions `aws-actions/configure-aws-credentials` with OIDC) instead of long-lived credentials.
+- **General CI principles:** Secrets must not appear in build logs, artifacts, or cached layers. Pin CI action/task versions by SHA or exact version (not mutable tags) to prevent supply chain attacks on secret-accessing workflows. Rotate CI secrets on the same schedule as application secrets.
+- **Ephemeral secrets:** For CI jobs that need temporary cloud access, use OIDC federation instead of long-lived credentials:
+  - **GitHub Actions:** `aws-actions/configure-aws-credentials` with OIDC
+  - **Azure DevOps:** Workload Identity Federation with service connections
+  - **GitLab CI:** OIDC ID tokens via `id_tokens` keyword
 
 ## Application-Level Secret Handling
 
@@ -57,7 +61,10 @@ alwaysApply: true
 
 - **gitleaks:** Run `gitleaks detect` in CI on every push and PR. Configure `.gitleaks.toml` with project-specific rules and allowlists for false positives (test fixtures, documentation examples).
 - **TruffleHog:** Use `trufflehog git` for historical scanning of the full repository. Run quarterly or on suspected compromise. Focus on high-entropy strings and known secret patterns.
-- **GitHub Secret Scanning:** Enable GitHub's built-in secret scanning and push protection. Configure custom patterns for project-specific secret formats.
+- **Platform secret scanning:** Enable the platform's built-in secret scanning and push protection:
+  - **GitHub:** GitHub Secret Scanning with push protection. Configure custom patterns for project-specific secret formats.
+  - **Azure DevOps:** Microsoft Defender for DevOps or Credential Scanner task in pipelines.
+  - **GitLab:** GitLab Secret Detection CI template (`Secret-Detection.gitlab-ci.yml`). Configure custom rulesets for project-specific patterns.
 - **Pre-commit hooks:** Install a local pre-commit hook (e.g., `gitleaks protect --staged`) to catch secrets before they reach the remote. This is defense-in-depth — CI scanning is still required.
 - **Remediation SLA:** Secrets detected in CI must be rotated immediately (within 1 hour for production secrets). Assume any secret that reached a commit is compromised, even if the commit was force-pushed away — git history is recoverable.
 

package/rules/hatch3r-security-patterns.md

@@ -1,6 +1,9 @@
 ---
+id: hatch3r-security-patterns
+type: rule
 description: Security patterns including input validation, auth enforcement, and AI/agentic security for the project
-alwaysApply: true
+scope: always
+tags: [security]
 ---
 # Security Patterns
 
@@ -61,6 +64,11 @@ alwaysApply: true
 - Enforce parameter schemas on every tool call. Reject calls with unexpected, missing, or out-of-range arguments.
 - Rate-limit tool invocations per agent per time window. Alert on anomalous tool usage patterns.
 - Sandbox tool execution: restrict file system access, network egress, and subprocess spawning.
+- **MCP server filesystem scope:** MCP servers with filesystem access must be scoped to the minimum necessary directories:
+  - Restrict filesystem access to the project directory. MCP servers should never have access to the home directory, system directories, or unrelated project directories.
+  - Document which MCP servers have filesystem access and define their intended scope (read-only vs read-write, which directories).
+  - Configure `allowedDirectories` in MCP server configs where supported. If the server does not support directory restrictions, document this as a known risk and apply compensating controls (monitoring, read-only mode).
+  - Audit MCP server filesystem access on configuration changes. Verify that added servers do not expand the filesystem attack surface beyond the project boundary.
 
 ### ASI03 — Identity & Privilege Abuse
 
@@ -75,6 +83,12 @@ alwaysApply: true
 - Verify package integrity (checksums, signatures) before loading tools or plugins.
 - Audit third-party prompt templates for injected instructions before use.
 - Maintain an allowlist of approved MCP servers and tool sources.
+- **`npx -y` safety:** The `-y` flag auto-confirms installation of unknown packages without prompts, creating a supply chain attack vector:
+  - Never use `npx -y` with untrusted, unknown, or typo-squattable package names.
+  - Always pin explicit versions when using npx: `npx package@1.2.3` instead of `npx package`.
+  - Prefer `npm exec --package=package@version -- command` for critical tooling — it provides explicit version control and avoids silent auto-install.
+  - In CI pipelines, install tools as explicit `devDependencies` with pinned versions rather than relying on `npx` at runtime.
+  - Verify the package name and publisher on the npm registry before first use. Typosquatting attacks exploit `npx -y` by registering names similar to popular packages.
 
 ### ASI05 — Unexpected Code Execution
 
@@ -168,7 +182,10 @@ alwaysApply: true
 
 - Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
 - Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
-- Subscribe to security advisories for all critical dependencies (GitHub Dependabot, Snyk, or equivalent).
+- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
+  - **GitHub:** Dependabot alerts and security advisories
+  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
+  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
 - Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
 - Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
 - Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
@@ -189,7 +206,10 @@ alwaysApply: true
 - CI/CD pipelines: require code review for all changes, enforce branch protection, sign commits where feasible.
 - Never deserialize untrusted data without validation. Use schemas (zod, JSON Schema) to validate structure before processing.
 - Protect CI/CD secrets and permissions: restrict who can modify pipeline configuration, require approval for deployment steps.
-- Pin GitHub Actions and CI plugins by commit SHA, not mutable tags.
+- Pin CI actions/tasks by commit SHA or exact version, not mutable tags:
+  - **GitHub Actions:** Pin by commit SHA (e.g., `actions/checkout@abc123`)
+  - **Azure DevOps:** Pin pipeline tasks by exact version (e.g., `task@2`)
+  - **GitLab CI:** Pin included templates by SHA or tag reference
 
 ### A09 — Security Logging and Monitoring Failures
 

package/rules/hatch3r-security-patterns.mdc

@@ -168,7 +168,10 @@ alwaysApply: true
 
 - Maintain a software bill of materials (SBOM) for all direct and transitive dependencies.
 - Run `npm audit` (or equivalent) in CI on every build. Block merges with critical or high vulnerabilities.
-- Subscribe to security advisories for all critical dependencies (GitHub Dependabot, Snyk, or equivalent).
+- Subscribe to security advisories for all critical dependencies using the platform's built-in tools or third-party equivalents:
+  - **GitHub:** Dependabot alerts and security advisories
+  - **Azure DevOps:** Microsoft Defender for DevOps or WhiteSource/Mend integration
+  - **GitLab:** GitLab Dependency Scanning CI template, or Snyk integration
 - Remove unused dependencies. Unused code with known vulnerabilities is still a risk.
 - Pin dependency versions in lockfiles. Review lockfile changes in PRs with the same scrutiny as code changes.
 - Establish SLAs for vulnerability remediation: critical within 24 hours, high within 1 week, moderate within 1 sprint.
@@ -189,7 +192,10 @@ alwaysApply: true
 - CI/CD pipelines: require code review for all changes, enforce branch protection, sign commits where feasible.
 - Never deserialize untrusted data without validation. Use schemas (zod, JSON Schema) to validate structure before processing.
 - Protect CI/CD secrets and permissions: restrict who can modify pipeline configuration, require approval for deployment steps.
-- Pin GitHub Actions and CI plugins by commit SHA, not mutable tags.
+- Pin CI actions/tasks by commit SHA or exact version, not mutable tags:
+  - **GitHub Actions:** Pin by commit SHA (e.g., `actions/checkout@abc123`)
+  - **Azure DevOps:** Pin pipeline tasks by exact version (e.g., `task@2`)
+  - **GitLab CI:** Pin included templates by SHA or tag reference
 
 ### A09 — Security Logging and Monitoring Failures
 

package/rules/hatch3r-testing.md

@@ -3,6 +3,7 @@ id: hatch3r-testing
 type: rule
 description: Test standards and conventions for the project
 scope: always
+tags: [core]
 ---
 # Testing Standards
 

package/rules/hatch3r-theming.md

@@ -1,7 +1,10 @@
 ---
+id: hatch3r-theming
+type: rule
 description: Theming, dark mode, and color system conventions for the project
+scope: conditional
 globs: src/**/*.vue, src/**/*.tsx, src/**/*.jsx, src/**/*.css, src/**/*.scss
-alwaysApply: false
+tags: [implementation]
 ---
 # Theming & Dark Mode