@infinitedusky/indusk-mcp 1.10.0 → 1.10.2

package/dist/lib/config.d.ts

@@ -22,6 +22,23 @@ export interface InduskConfig {
          */
         groupId?: string;
     };
+    otel?: {
+        /**
+         * Project's relationship to OpenTelemetry. Controls whether the OTel gate
+         * fires when the planner writes impl phases and when the validate-impl-structure
+         * / check-gates hooks evaluate them.
+         *
+         * - `service`: produces telemetry I want to collect (default behavior; gate fires)
+         * - `library`: ships to other people, never produces telemetry (gate silent)
+         * - `tool`: short-lived script, telemetry overhead exceeds value (gate silent)
+         * - `none`: explicit opt-out for legacy/prototype/internal experiments (gate silent)
+         *
+         * **If unset, behaves as `service`** (gate fires). This preserves backwards
+         * compatibility — existing projects without the field continue to get the OTel
+         * gate enforced. Opt-out is explicit; opt-in is implicit.
+         */
+        role?: "service" | "library" | "tool" | "none";
+    };
 }
 export declare function getConfigPath(projectRoot: string): string;
 export declare function readConfig(projectRoot: string): InduskConfig | null;
@@ -38,3 +55,18 @@ export declare function getPlanningDir(projectRoot: string): string;
  * searching Graphiti — this gives both project-scoped and cross-project knowledge.
  */
 export declare function getProjectGroupId(projectRoot: string): string;
+/**
+ * Whether the OTel gate should fire for this project.
+ *
+ * Returns `true` if `.indusk/config.json` is missing, missing `otel.role`, or
+ * has `otel.role: "service"`. Returns `false` only when the project explicitly
+ * opts out via `otel.role: "library" | "tool" | "none"`.
+ *
+ * Used by:
+ *   - planner skill (whether to write `#### Phase N OTel` sections into impl.md)
+ *   - validate-impl-structure hook (whether to require an OTel section at write time)
+ *   - check-gates hook (whether to block phase advancement on missing OTel)
+ *
+ * Backwards compatible: projects without the new field behave exactly as before.
+ */
+export declare function shouldEmitOtelGate(projectRoot: string): boolean;

package/dist/lib/config.js

@@ -42,3 +42,22 @@ export function getProjectGroupId(projectRoot) {
         return config.graphiti.groupId;
     return basename(projectRoot);
 }
+/**
+ * Whether the OTel gate should fire for this project.
+ *
+ * Returns `true` if `.indusk/config.json` is missing, missing `otel.role`, or
+ * has `otel.role: "service"`. Returns `false` only when the project explicitly
+ * opts out via `otel.role: "library" | "tool" | "none"`.
+ *
+ * Used by:
+ *   - planner skill (whether to write `#### Phase N OTel` sections into impl.md)
+ *   - validate-impl-structure hook (whether to require an OTel section at write time)
+ *   - check-gates hook (whether to block phase advancement on missing OTel)
+ *
+ * Backwards compatible: projects without the new field behave exactly as before.
+ */
+export function shouldEmitOtelGate(projectRoot) {
+    const config = readConfig(projectRoot);
+    const role = config?.otel?.role;
+    return role === undefined || role === "service";
+}

package/extensions/dash0/skill.md

@@ -65,14 +65,22 @@ The MCP server provides 23 tools. The key ones for debugging:
 - **`getFailedChecks`** / **`getFailedCheckDetails`** — View check failures
 - **`searchKnowledgeBase`** — Search Dash0 documentation
 
-### MCP Usage Pattern
+### MCP Usage Pattern — Traces First
+
+**Always start with spans.** Logs are correlated with traces, so finding the right trace first helps you find the right logs — not the other way around.
+
 ```
-1. getLogRecords → find the log summary, get log record IDs
-2. getFullLogRecord → drill into a specific log for all attributes
-3. If log has traceId → getTraceDetails to see the full request chain
-4. getServiceCatalog → see all services, error rates, dependencies
+1. getSpans (last 30s, no filters) → scan recent spans for anything matching your investigation
+2. Found a relevant span? → getTraceDetails to see the full request chain
+3. Use trace/span IDs to find correlated logs → getLogRecords with traceId filter
+4. getFullLogRecord → drill into a specific log for all attributes
 ```
 
+**Why traces first:**
+- Spans show the full request lifecycle — what happened, how long, what called what
+- Logs are attached to spans via trace context — the trace tells you which logs matter
+- Starting with logs means guessing at filters; starting with spans gives you the map
+
 ## When to Use MCP vs CLI
 
 | Task | Use |
@@ -83,7 +91,7 @@ The MCP server provides 23 tools. The key ones for debugging:
 | Get full trace hierarchy | MCP `getTraceDetails` (preferred) |
 | Run PromQL metrics query | Either — MCP for simple, CLI for complex |
 | Deploy dashboard from YAML | CLI (`dash0 apply -f`) |
-| Diagnose a failing service | MCP `getServiceCatalog` → `getLogRecords` → `getFullLogRecord` |
+| Diagnose a failing service | MCP `getSpans` (last 30s) → `getTraceDetails` → `getLogRecords` (by traceId) |
 | CI/CD observability checks | CLI (scriptable, agent mode) |
 | Discover available attributes | MCP `getAttributeKeys` / `getAttributeValues` |
 
@@ -178,14 +186,16 @@ The CLI auto-detects Claude Code sessions and switches to agent mode (JSON outpu
 
 ### During verification
 When a verification step involves checking that a service is working correctly, don't just check the HTTP status — query Dash0 for:
-- Recent error logs for the service: `dash0 --experimental logs query --from now-15m --filter "service.name is game-server" --filter "otel.log.severity.range is_one_of ERROR WARN"`
-- Log entries matching the feature you modified
+- **Recent spans first**: use MCP `getSpans` with a short time range (last 30s) to see what the service just did — look for errors, slow spans, or missing expected operations
+- **Then correlated logs**: once you have a trace ID from a relevant span, use `getLogRecords` filtered by that trace ID to see exactly what happened during that request
+- **Only use broad log queries as a fallback** if no spans are present (e.g., the service isn't instrumented yet)
 
 ### During debugging
 When something fails:
-1. Check logs first — `dash0 --experimental logs query --from now-1h --filter "otel.log.severity.range is_one_of ERROR WARN" -o csv`
-2. Find the trace — look for trace IDs in log entries, then `dash0 --experimental traces get <trace-id>`
-3. Check metrics — is this a new problem or an existing one? Compare error rates over time.
+1. **Get recent spans first** — use MCP `getSpans` with a short time range (last 30s–1m). Don't filter yet — scan the results for spans matching what you're investigating.
+2. **Drill into the trace** — found a relevant span? Use `getTraceDetails` to see the full request chain, timing, errors, and hierarchy.
+3. **Find correlated logs** — use the trace ID from step 2 to query `getLogRecords` with a `traceId` filter. This gives you exactly the logs tied to that request, no guessing.
+4. **Check metrics** — is this a new problem or an existing one? Compare error rates over time.
 
 ### During retrospective
 Query Dash0 for metrics that show the impact of the plan:
@@ -201,5 +211,5 @@ Dash0 ingests standard OpenTelemetry data. If your services already export OTLP
 
 - **CLI `--experimental` required**: All query commands (logs, traces, metrics) require the `--experimental` flag. This will change when these commands become stable.
 - **Default time range is narrow**: Always specify `--from` when querying logs. Without it, you may get empty results.
-- **No trace search**: The CLI can only fetch traces by ID (`traces get <id>`), not search for them. Find trace IDs in log entries first.
+- **CLI has no trace search**: The CLI can only fetch traces by ID (`traces get <id>`), not search for them. Use the MCP `getSpans` tool to search spans — it supports filters and time ranges. The CLI requires you to already have a trace ID.
 - **Profile auth may not load in Claude Code shell**: Run `source ~/.zshrc` before `dash0` commands if auth fails.

package/hooks/check-gates.js

@@ -2,11 +2,16 @@
 /**
  * PreToolUse hook: blocks phase transitions in impl.md when gates are incomplete.
  *
+ * The OTel gate is conditional on the project's `otel.role` in .indusk/config.json:
+ *   - unset or "service": OTel gate is enforced (default)
+ *   - "library" / "tool" / "none": OTel gate is silenced (mirrors validate-impl-structure)
+ *
  * Exit 0 = allow the edit
  * Exit 2 = block the edit (stderr sent to agent as feedback)
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 
 // Read hook input from stdin
 let input = "";
@@ -115,14 +120,57 @@ function detectWorkflow(content) {
 	return m ? m[1] : "feature";
 }
 
-// Which gate types are required per workflow
-const WORKFLOW_GATES = {
+/**
+ * Find the project root by walking up from a starting directory looking for
+ * a .indusk/ or .claude/ directory. Falls back to startDir if none found.
+ */
+function findProjectRoot(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(`${dir}/.indusk`) || existsSync(`${dir}/.claude`)) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return startDir;
+}
+
+/**
+ * Whether the OTel gate should fire for this project. Reads .indusk/config.json
+ * and checks otel.role. Returns true if missing/unset/"service", false for
+ * library/tool/none. Mirrors shouldEmitOtelGate() in apps/indusk-mcp/src/lib/config.ts.
+ */
+function shouldEmitOtelGate(projectRoot) {
+	const configPath = `${projectRoot}/.indusk/config.json`;
+	if (!existsSync(configPath)) return true;
+	try {
+		const config = JSON.parse(readFileSync(configPath, "utf-8"));
+		const role = config?.otel?.role;
+		return role === undefined || role === "service";
+	} catch {
+		return true;
+	}
+}
+
+const projectRoot = findProjectRoot(event.cwd ?? process.cwd());
+const otelGateEnabled = shouldEmitOtelGate(projectRoot);
+
+// Which gate types are required per workflow.
+// OTel is filtered out below when the project opts out via otel.role.
+const WORKFLOW_GATES_BASE = {
 	feature: ["verification", "otel", "context", "document"],
 	refactor: ["verification", "otel", "context", "document"],
 	bugfix: ["verification", "document"],
 	spike: [],
 };
 
+const WORKFLOW_GATES = Object.fromEntries(
+	Object.entries(WORKFLOW_GATES_BASE).map(([wf, gates]) => [
+		wf,
+		otelGateEnabled ? gates : gates.filter((g) => g !== "otel"),
+	]),
+);
+
 // Parse phases from the NEW content (after edit) and OLD content (before edit)
 function parsePhases(content) {
 	// Strip frontmatter

package/hooks/validate-impl-structure.js

@@ -2,14 +2,20 @@
 /**
  * PreToolUse hook: validates that impl phases have all four gate sections.
  *
- * Every phase must have: implementation items, Verification, OTel, Context, Document.
+ * Every phase must have: implementation items, Verification, OTel*, Context, Document.
  * Sections can opt out with (none needed), (not applicable), or skip-reason: {why}.
  *
+ * *OTel section is conditional on the project's `otel.role` in .indusk/config.json:
+ *   - unset or "service": OTel section is required (default behavior)
+ *   - "library" / "tool" / "none": OTel section is NOT required (gate silenced)
+ * This mirrors `shouldEmitOtelGate()` in apps/indusk-mcp/src/lib/config.ts.
+ *
  * Exit 0 = allow the edit
  * Exit 2 = block the edit (stderr sent to agent as feedback)
  */
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
 
 // Read hook input from stdin
 let input = "";
@@ -26,6 +32,43 @@ if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
 	process.exit(0);
 }
 
+/**
+ * Find the project root by walking up from a starting directory looking for
+ * a .indusk/ or .claude/ directory. Falls back to event.cwd if none found.
+ * Mirrors the pattern used in check-catchup.js.
+ */
+function findProjectRoot(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 10; i++) {
+		if (existsSync(`${dir}/.indusk`) || existsSync(`${dir}/.claude`)) return dir;
+		const parent = resolve(dir, "..");
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return startDir;
+}
+
+/**
+ * Whether the OTel gate should fire for this project. Reads .indusk/config.json
+ * and checks otel.role. Returns true if the config is missing, if otel.role is
+ * unset, or if otel.role is "service" — matches shouldEmitOtelGate() in
+ * apps/indusk-mcp/src/lib/config.ts exactly.
+ */
+function shouldEmitOtelGate(projectRoot) {
+	const configPath = `${projectRoot}/.indusk/config.json`;
+	if (!existsSync(configPath)) return true;
+	try {
+		const config = JSON.parse(readFileSync(configPath, "utf-8"));
+		const role = config?.otel?.role;
+		return role === undefined || role === "service";
+	} catch {
+		return true; // on parse error, preserve default behavior
+	}
+}
+
+const projectRoot = findProjectRoot(event.cwd ?? process.cwd());
+const otelGateEnabled = shouldEmitOtelGate(projectRoot);
+
 // Check for skip-gates escape hatch
 const newContent = toolInput.new_string ?? toolInput.content ?? "";
 
@@ -100,10 +143,13 @@ const body = fmMatch ? newFullContent.slice(fmMatch[0].length) : newFullContent;
 const workflowMatch = frontmatter.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
 const workflow = workflowMatch ? workflowMatch[1] : "feature";
 
-// Different workflows have different requirements
+// Different workflows have different requirements.
+// OTel is further gated on the project's `otel.role` in .indusk/config.json —
+// libraries/tools/none opt out of the OTel gate entirely. Workflows that normally
+// require OTel (feature, refactor) will only require it when otelGateEnabled is true.
 const requirements = {
-	feature: { verification: true, otel: true, context: true, document: true },
-	refactor: { verification: true, otel: true, context: true, document: true },
+	feature: { verification: true, otel: otelGateEnabled, context: true, document: true },
+	refactor: { verification: true, otel: otelGateEnabled, context: true, document: true },
 	bugfix: { verification: true, otel: false, context: false, document: true },
 	spike: { verification: false, otel: false, context: false, document: false },
 }[workflow];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.10.0",
+	"version": "1.10.2",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/planner.md

@@ -108,6 +108,8 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
    Default is `ask`. See the work skill "Gate Override Policy" for full details on what each mode enforces at execution time.
 
+   **OTel gate is conditional on `otel.role`.** Read `.indusk/config.json` for the project's `otel.role` field (or use the `shouldEmitOtelGate(projectRoot)` helper from `apps/indusk-mcp/src/lib/config.ts`). The OTel gate fires for projects whose `otel.role` is unset or `"service"` — these are user-facing apps that produce telemetry you want to collect. **Do NOT write `#### Phase N OTel` sections** for projects whose `otel.role` is `"library"`, `"tool"`, or `"none"` — these are libraries, CLIs, or scripts that should never emit telemetry and writing OTel gates for them is friction without value. The `validate-impl-structure` and `check-gates` hooks apply the same rule. The other gates (verify, context, document) always apply regardless of `otel.role`.
+
 7. **If impl is completed** (all items checked off by `/work`), invoke the retrospective skill (`/retrospective {plan-name}`). This handles the structured audit (docs, tests, quality, context), knowledge handoff to the docs site, and archival. Do not write a freeform retrospective — use the skill. (Bugfix and refactor workflows may skip retrospective for small changes — user's call.)
 
 8. **Always present each document for review** before moving to the next stage. The user signs off on each step.
@@ -280,6 +282,8 @@ For multi-phase impls, include a boundary map showing what each phase produces a
   function withdrawFor(wallet: address, player: address, amount: uint256, historyHash: bytes32)
   ```
 
+{OPTIONAL: #### Phase 1 OTel — include ONLY if the project's `otel.role` in `.indusk/config.json` is unset or `"service"`. Skip the entire OTel block for projects with `otel.role: "library" | "tool" | "none"`. Use `shouldEmitOtelGate(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` to decide.}
+
 #### Phase 1 OTel
 - [ ] {Instrumentation check — are new code paths observable? See the OTel skill for patterns. Example items: "New endpoints have manual spans with `otel.category` and domain attributes", "Errors recorded with `recordException` + `setStatus(ERROR)` + trace-correlated log". Ask: "did this phase add endpoints, business logic, state transitions, or error paths?" If not, this section can be opted out per gate policy.}