@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-cloud-agent-sdk.md

@@ -0,0 +1,92 @@
+# Local Cloud Agent SDK — Target Platform Reference
+
+> Apply target: Agent code built on a cloud provider's agent SDK (Anthropic, OpenAI, Google, etc.) running locally.
+> Target class: `local-code-construct`
+> Apply branch: local-code-construct (code edits via BG-worktree PR; lint+typecheck gate required)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-code-construct` |
+| Mutability | code edits via BG-worktree PR |
+| Isolation | BG-worktree per PR-004; lint+typecheck gate required |
+
+## Supported SDKs
+
+| SDK | Package | Trace Source |
+|-----|---------|-------------|
+| Anthropic Claude SDK | `@anthropic-ai/sdk` | `claude-code-transcripts` or OTel |
+| OpenAI Agents SDK | `openai` | OTel or Langfuse |
+| Google Genkit | `@genkit-ai/core` | OTel |
+| LangChain/LangGraph | `langchain` | Langfuse or OTel |
+| mutagent SDK | `@mutagent/sdk` | Langfuse (direct) |
+
+## How Remedies Are Applied
+
+Agent SDK remedies are **TypeScript/JavaScript code changes** — system prompts, tool schemas, retry configs, model settings.
+
+1. **BG-worktree isolation (PR-004)**: all changes happen in a separate worktree branch
+2. **Read before write (PR-003)**: read the target agent source file before proposing edits
+3. **Lint + typecheck gate**: `bun run lint && bun run typecheck` must pass before PR
+4. **Idempotent changes (PR-012)**: changes must be safe to apply multiple times
+5. **HITL gate (PR-014)**: PR includes diff summary; user reviews before merge
+
+## Code Targets
+
+Depends on SDK, but typically:
+
+| Pattern | Purpose |
+|---------|---------|
+| `new Anthropic.Claude({ systemPrompt: '...' })` | System prompt |
+| `model: 'claude-opus-4-5'` | Model selection |
+| `tools: [...]` | Tool definitions |
+| `maxTokens: N` | Budget setting |
+
+## Capability Probing
+
+```bash
+# Check SDK installed
+ls node_modules/@anthropic-ai/sdk 2>/dev/null
+ls node_modules/openai 2>/dev/null
+
+# Find agent entry points
+grep -r "new Anthropic\|new OpenAI\|createAgent\|Agent(" src/ --include="*.ts" -l
+
+# Typecheck
+bun run typecheck 2>&1 | head -20
+```
+
+## Remedy Categories
+
+- **System prompt edit**: update `systemPrompt` or `instructions` field
+- **Model change**: update `model` field (requires explicit operator sign-off per memory `feedback_provider_change_explicit_approval`)
+- **Tool schema fix**: update tool input schema or description
+- **Retry / timeout config**: update `maxRetries`, `timeout`, `maxTokens` fields
+- **Temperature / sampling**: update `temperature` or sampling parameters
+
+## Lint + Typecheck Gate
+
+For local-code-construct targets, the apply-worker MUST run:
+```bash
+bun run lint
+bun run typecheck
+```
+Both must exit 0. Failures block PR creation.
+
+## Audit
+
+```json
+{
+  "targetPlatform": "local-cloud-agent-sdk",
+  "targetClass": "local-code-construct",
+  "remedyType": "system-prompt-patch",
+  "sdk": "anthropic",
+  "branch": "diagnose/sdk-fix-<uuid>",
+  "pr": "https://github.com/.../pull/<N>",
+  "lintPassed": true,
+  "typecheckPassed": true,
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-codex.md

@@ -0,0 +1,72 @@
+# Local Codex — Target Platform Reference
+
+> Apply target: OpenAI Codex CLI running on the local machine.
+> Target class: `local-agent`
+> Apply branch: local-agent (read-verify-only; HITL for config changes)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-agent` |
+| Mutability | read-verify; HITL via HTML |
+| Isolation | N/A (agent runs in its own session) |
+
+## How Remedies Are Applied
+
+Codex CLI remedies are primarily **configuration changes** (`~/.codex/config.toml`).
+
+1. **Read before write (PR-003)**: read `~/.codex/config.toml` before proposing edits
+2. **HITL gate (PR-014)**: HTML report + markdown remedy; user applies via TOML edit or CLI command
+3. **Ephemeral mode**: suggest `codex exec --ephemeral` when sessions should not be recorded
+
+## Config Targets
+
+| File | Purpose |
+|------|---------|
+| `~/.codex/config.toml` | Main Codex CLI config |
+| `~/.codex/sessions/` | Active session recordings (read-only diagnostic source) |
+| `~/.codex/archived_sessions/` | Archived sessions (read-only) |
+
+## Capability Probing
+
+```bash
+# Check Codex CLI is installed
+which codex
+
+# Check config
+cat ~/.codex/config.toml 2>/dev/null
+
+# Session count
+ls ~/.codex/sessions/ | wc -l
+ls ~/.codex/archived_sessions/ | wc -l
+```
+
+## Remedy Categories (iter-8 locked)
+
+- **Config patch**: update `~/.codex/config.toml` key (model, provider, timeout)
+- **Session management guidance**: informational only; no automated session deletion
+- **Ephemeral mode recommendation**: when session recording is contributing to noise
+
+## Audit
+
+```json
+{
+  "targetPlatform": "local-codex",
+  "targetClass": "local-agent",
+  "remedyType": "config-patch",
+  "before": { "key": "model", "value": "old-model" },
+  "after": { "key": "model", "value": "new-model" },
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```
+
+## Session Path Constants (confirmed iter-8)
+
+```
+Active:   ~/.codex/sessions/<session>.jsonl
+Archived: ~/.codex/archived_sessions/<session>.jsonl
+Config:   ~/.codex/config.toml
+Source:   codex-rs/rollout/src/lib.rs
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-cursor.md

@@ -0,0 +1,108 @@
+# Local Cursor — Target Platform Reference
+
+> Apply target: Cursor IDE running on the local machine.
+> Target class: `local-agent`
+> Apply branch: local-agent (read-verify-only; HITL for rule changes)
+>
+> **Note (PR-016):** Cursor is an apply **target** only (`local-cursor`), NOT a trace source —
+> it ships no `SourcePlatform` enum entry and no `normalize/platforms/cursor.ts`. The binding-surface
+> research formerly held in `references/source-platforms/cursor.md` (a phantom source-platform doc)
+> was folded here in the 2026-06 drift-fix; see "Binding Surface & Install Path" below.
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-agent` |
+| Mutability | read-verify; HITL for `.cursorrules` edits |
+| Isolation | N/A (IDE rules are per-workspace) |
+
+## How Remedies Are Applied
+
+Cursor remedies target `.cursorrules` files and Cursor-specific settings.
+
+1. **Read before write (PR-003)**: read `.cursorrules` at workspace root before proposing changes
+2. **HITL gate (PR-014)**: HTML report + markdown diff of rule changes; user applies in Cursor UI or manually edits `.cursorrules`
+3. **BG-worktree for `.cursorrules` (PR-004)**: if remedy requires committing `.cursorrules` change, open a BG-worktree PR
+
+## Config Targets
+
+| File | Purpose |
+|------|---------|
+| `<workspace>/.cursorrules` | Workspace-scoped AI rules |
+| `~/.cursor/settings.json` | Global Cursor settings |
+| `<workspace>/.cursor/` | Per-workspace Cursor config |
+
+## Capability Probing
+
+```bash
+# Check Cursor is installed
+ls /Applications/Cursor.app 2>/dev/null || which cursor
+
+# Check workspace rules
+cat .cursorrules 2>/dev/null
+
+# Check global settings
+cat ~/.cursor/settings.json 2>/dev/null
+```
+
+## Session/Trace Source
+
+Cursor does not produce structured trace JSONL files by default. Diagnostics via:
+- OTel if Cursor Background Agents are configured with tracing export
+- Manual session exports if available
+
+## Remedy Categories
+
+- **`.cursorrules` update**: append or replace rule sections via PR (BG worktree)
+- **Settings recommendation**: informational; user applies in Cursor UI
+- **Background Agent config**: update Background Agent settings (post-v0.1 scheduling)
+
+## Audit
+
+```json
+{
+  "targetPlatform": "local-cursor",
+  "targetClass": "local-agent",
+  "remedyType": "cursorrules-patch",
+  "before": "...",
+  "after": "...",
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```
+
+## Binding Surface & Install Path (OQ-4 — lookup pending)
+
+> Folded from the retired `references/source-platforms/cursor.md` (2026-06 drift-fix). Cursor binding
+> is DEFERRED pending an authoritative docs lookup; these are best-effort research notes.
+
+Candidate binding surfaces identified prior to authoritative-docs confirmation:
+
+| Surface | Status | Notes |
+|---|---|---|
+| `.cursorrules` (root-level) | Deprecated in newer Cursor versions | Flat rules file; no per-agent dispatch; legacy |
+| `.cursor/rules/*.mdc` | **Likely correct for recent Cursor** | Project-scoped MDC rules; supports metadata frontmatter |
+| Cursor Background Agents | Separate cloud product | Different from local rule binding; requires Cursor subscription |
+
+**Provisional recommendation:** use `.cursor/rules/*.mdc` for project-scoped binding.
+Install path: `.cursor/rules/mutagent-diagnostics.mdc` (created in the user's project directory).
+
+**Detection marker** — `init.ts` detects Cursor by probing for a `.cursor/` directory in the
+**current working directory** (`existsSync(join(process.cwd(), ".cursor"))`); no user-global
+`~/.cursor/` detection yet.
+
+**MDC format (provisional)** — Markdown + Cursor-specific frontmatter keys (`description`, `globs`,
+`alwaysApply`); the skill's SKILL.md content is adapted into the `.mdc` body.
+
+**Agent primitive** — none on Cursor yet; `init.ts` installs the skill rule only (no agent files).
+
+**TODO (OQ-4 / OQ-7):** WebFetch Cursor docs to confirm the binding surface (`.cursorrules` vs
+`.cursor/rules/*.mdc`), determine the user-scope install location, verify MDC frontmatter keys, and
+add a Cursor transcript fetcher when the OQ-7 fetcher-extensibility design is resolved.
+
+Upstream docs: https://cursor.com/docs (search "rules", "background agents", ".cursorrules").
+
+## Post-v0.1 Scheduling
+
+Cursor Background Agents support `cron`-style scheduling. See `references/workflows/schedule-prep.md` for the post-v0.1 schedule integration plan.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-mastra.md

@@ -0,0 +1,77 @@
+# Local Mastra — Target Platform Reference
+
+> Apply target: Mastra.ai framework running locally (TypeScript/Node.js).
+> Target class: `local-code-construct`
+> Apply branch: local-code-construct (code edits via BG-worktree PR; lint+typecheck gate required)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-code-construct` |
+| Mutability | code edits via BG-worktree PR |
+| Isolation | BG-worktree per PR-004; lint+typecheck gate required |
+
+## How Remedies Are Applied
+
+Mastra remedies are **TypeScript code changes** — agent definitions, tool registrations, workflow configs.
+
+1. **BG-worktree isolation (PR-004)**: all changes happen in a separate worktree branch
+2. **Read before write (PR-003)**: read the target agent file before proposing edits
+3. **Lint + typecheck gate**: `bun run lint && bun run typecheck` must pass on the branch before PR is opened
+4. **Idempotent changes (PR-012)**: changes must be safe to apply multiple times
+5. **HITL gate (PR-014)**: PR description includes diff summary; user reviews before merge
+
+## Code Targets
+
+| Path | Purpose |
+|------|---------|
+| `src/mastra/agents/*.ts` | Agent definitions |
+| `src/mastra/tools/*.ts` | Tool registrations |
+| `src/mastra/workflows/*.ts` | Workflow configurations |
+| `mastra.config.ts` | Top-level Mastra config |
+
+## Capability Probing
+
+```bash
+# Check Mastra is installed
+ls node_modules/@mastra/core 2>/dev/null || bun pm ls | grep mastra
+
+# Check agent definitions
+find . -path "*/mastra/agents/*.ts" -ls
+
+# Validate config compiles
+bun run typecheck 2>&1 | head -20
+```
+
+## Remedy Categories
+
+- **Prompt system change**: edit agent `instructions` or `systemPrompt` in agent definition
+- **Tool update**: modify tool schema or handler in `src/mastra/tools/`
+- **Workflow step change**: update step order, retry logic, or timeout in workflow definition
+- **Model config update**: change `model` field in agent definition
+
+## Lint + Typecheck Gate
+
+For local-code-construct targets, the apply-worker MUST run:
+```bash
+bun run lint
+bun run typecheck
+```
+Both must exit 0 before the PR is opened. Failures block the PR creation.
+
+## Audit
+
+```json
+{
+  "targetPlatform": "local-mastra",
+  "targetClass": "local-code-construct",
+  "remedyType": "agent-definition-patch",
+  "branch": "diagnose/mastra-fix-<uuid>",
+  "pr": "https://github.com/.../pull/<N>",
+  "lintPassed": true,
+  "typecheckPassed": true,
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-opencode.md

@@ -0,0 +1,70 @@
+# Local OpenCode — Target Platform Reference
+
+> Apply target: OpenCode running on the local machine.
+> Target class: `local-agent`
+> Apply branch: local-agent (read-verify-only; HITL for config changes)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-agent` |
+> Mutability | read-verify; HITL via HTML |
+| Isolation | N/A (agent config is per-project) |
+
+## How Remedies Are Applied
+
+OpenCode remedies target `opencode.json` / `opencode.toml` configuration files.
+
+1. **Read before write (PR-003)**: read project config before proposing changes
+2. **HITL gate (PR-014)**: HTML report + markdown diff; user applies
+3. **BG-worktree (PR-004)**: if remedy requires a commit, open a BG-worktree PR
+
+## Config Targets
+
+| File | Purpose |
+|------|---------|
+| `<project>/opencode.json` | Project-level OpenCode config |
+| `<project>/opencode.toml` | Alternative TOML config |
+| `~/.opencode/` | Global OpenCode settings |
+
+## Capability Probing
+
+```bash
+# Check OpenCode is installed
+which opencode
+
+# Check project config
+cat opencode.json 2>/dev/null || cat opencode.toml 2>/dev/null
+
+# List sessions (if recorded)
+ls ~/.opencode/sessions/ 2>/dev/null
+```
+
+## Trace Source
+
+OpenCode session recording format: see `references/harness-knowledge.md` for Platform Knowledge Table entry. Path: TBD per OpenCode version (check harness-knowledge.md OQ-6 status).
+
+## Remedy Categories
+
+- **Config key update**: patch `opencode.json` field (model, timeout, provider)
+- **Rule/system-prompt update**: BG-worktree PR for project-scoped prompt changes
+- **Provider config**: update API key reference in config (key name only — never the key value)
+
+## Audit
+
+```json
+{
+  "targetPlatform": "local-opencode",
+  "targetClass": "local-agent",
+  "remedyType": "config-patch",
+  "before": {},
+  "after": {},
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```
+
+## Notes
+
+- OpenCode session path confirmation is deferred to a future wave. Session-ingestion for OpenCode traces is not implemented in v0.1. Check `references/harness-knowledge.md` for any updated OpenCode session path entry.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/workflows/apply-pr-comment-format.md

@@ -0,0 +1,82 @@
+# Diagnostic Apply PR Comment Format
+
+> Authority: PR-023 (v0.3+).
+> Applies to: every PR opened by `diagnostics-apply-worker` after applying operator-approved remedies.
+>
+> Pre-release note: no backwards-compat constraints. Streamroll updates permitted until v1.0.
+
+---
+
+## MANDATORY Closing PR Comment
+
+Every PR opened by `diagnostics-apply-worker` MUST include a closing "Final Status" comment
+BEFORE requesting review. The comment MUST contain all sections below.
+
+**Why**: creates an auditable record linking the applied change back to the diagnostic session,
+approved remedy payload, and verification result. The operator uses this comment to triage
+PRs across multiple parallel apply runs.
+
+---
+
+## Comment Template
+
+```markdown
+## Diagnostic Apply — Final Status
+
+### Decisions + WHYs
+
+| Decision | Choice | Why |
+|----------|--------|-----|
+| Remedy applied | <remedyId> — <title> | Operator-approved via copy-back at <diagnosedAt> |
+| Target | <targetClass> at <file:line> | From ActionablePlan.files[] |
+| Diff scope | <N lines> | Minimal change per PR-004 (branch hygiene) |
+
+### Verification Log
+
+```
+<paste of verify[] commands + output>
+```
+
+Acceptance criterion: <ActionablePlan.acceptance>
+Result: PASS / FAIL
+
+### Run-Tag References
+
+- runId: <runId from run-meta.json>
+- tags: <tags from run-meta.json>
+- diagnosedAt: <ISO timestamp>
+- sourcePlatform: <platform>
+- sessionId: <sessionId>
+
+### Backwards-compat Note
+
+Pre-release (v0.1–v0.5): streamroll updates permitted. No migration scripts required.
+First production release will add a migration note here.
+
+### Linked Finding
+
+Finding ID: <findingId>
+Failure origin: WHAT=<what> · WHY=<why> · WHERE=<where>
+Evidence: <evidence pointer from failureOrigin.evidence>
+```
+
+---
+
+## Enforcement
+
+- The `diagnostics-apply-worker` agent MUST post this comment before calling `gh pr create`.
+- If `run-meta.json` does not exist for the session (legacy run before v0.3), omit the
+  Run-Tag References section and note: "run-meta unavailable (pre-v0.3 run)".
+- The `acceptance` field in ActionablePlan is the contract. If verification fails, the PR
+  MUST be marked as draft and the operator notified before requesting review.
+- Do NOT reference the operator's local `feedback_pr_final_status_comment` memory rule —
+  this format is the skill's own, portable across any project using mutagent-diagnostics.
+
+---
+
+## Related
+
+- `references/principles.md` — PR-023 (Clipboard payloads = self-contained actionable plans)
+- `scripts/report/persist-selections.ts` — persists operator-selections.json
+- `scripts/run/session.ts` — run-meta.json generation
+- `assets/agents/diagnostics-apply-worker.md` — apply-worker agent definition

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/workflows/diagnostics.md

@@ -0,0 +1,35 @@
+# Diagnostics Workflow — Full Procedure
+
+> **SUPERSEDED-BY: `references/workflows/orchestrator-protocol.md` (canonical Steps 1–12)**
+>
+> This file is retained for anchor compatibility only. The authoritative step-by-step
+> execution protocol (Steps 1–12: config detection → score-scale probe → NL translation
+> → Tier-0 scan → slicing → analyzer dispatch → RCA → enricher → render → HITL →
+> apply gate → self-diagnostics) lives in `orchestrator-protocol.md`.
+>
+> Load `orchestrator-protocol.md` for execution. Load this file only for the legacy DAG
+> quick-reference below.
+
+## Diagnostics DAG (quick-reference)
+
+```
+1. fetch traces (filtered)
+   ↓
+2. Tier 0 static scan (tier0-scan.ts)
+   ↓
+3. Dynamic-cluster or window-based slicing (slicer.ts)
+   ↓
+4. N parallel analyzers (≤5) — each gets a slice
+   ↓
+5. Aggregate findings (cross-analyzer dedup + cluster correlation)
+   ↓
+6. RCA layer (WHAT/WHY/WHERE + recursive whys + remedy chain)
+   ↓
+7. Render HTML report (render.ts)
+   ↓
+8. Emit report path → await operator markdown copy-back
+   ↓
+9. AskUserQuestion (final apply gate) → spawn ai-engineer → shared `mutagent-cli apply` (apply-worker retired, M9)
+```
+
+For step-level detail on every node above, see `orchestrator-protocol.md`.