@mutagent/helix 0.1.0-alpha.14

package/bin/mutagent-helix.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * mutagent-helix — npx/pnpx entry point for the ADL bundle.
+ *
+ *   pnpx @mutagent/helix init             → install Helix + the lifecycle skills (+ link CLAUDE/AGENTS)
+ *   pnpx @mutagent/helix init --global     → install into the home dir (default is project-local)
+ *   pnpx @mutagent/helix init --yes        → non-interactive (select all detected platforms)
+ *   pnpx @mutagent/helix doctor           → runtime probe (what is installed + linkage)
+ *   pnpx @mutagent/helix <script> [args]  → run any helix-skill script via the runtime selector
+ *
+ * Mirrors the @mutagent/diagnostics launcher: intentionally tiny + node-runnable
+ * (no deps). It locates the helix skill's run.sh runtime selector (bun → pnpm-tsx
+ * → npx-tsx fallback) and forwards the requested subcommand to the matching
+ * TypeScript entry point. The TS scripts are NOT compiled — run.sh picks an
+ * available runtime at install time so the package stays portable across hosts.
+ *
+ * cwd discipline (W9-fix): the child runs in the USER's invocation directory
+ * (process.cwd()), NOT the skill install dir — init's project-local install
+ * target is the user's project. run.sh + the script are passed as ABSOLUTE paths
+ * so they resolve regardless of cwd.
+ */
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, isAbsolute, join } from "node:path";
+import { existsSync } from "node:fs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const skillRoot = join(here, "..", ".claude", "skills", "mutagent-helix");
+const runSh = join(skillRoot, "scripts", "cli", "run.sh");
+
+if (!existsSync(runSh)) {
+  console.error(`[mutagent-helix] runtime selector not found at ${runSh}`);
+  console.error("The package may be corrupted. Reinstall: pnpx @mutagent/helix init");
+  process.exit(1);
+}
+
+// Subcommand → skill script map. Unknown first-arg is treated as a script path.
+const SUBCOMMANDS = {
+  init: "scripts/cli/init.ts",
+  doctor: "scripts/cli/doctor.ts",
+};
+
+const [sub, ...rest] = process.argv.slice(2);
+const HELP = !sub || sub === "--help" || sub === "-h";
+
+if (HELP) {
+  console.log(`mutagent-helix — the MutagenT ADL bundle (Helix orchestrator + lifecycle skills)
+
+Usage:
+  pnpx @mutagent/helix init [--global] [--yes]
+  pnpx @mutagent/helix doctor
+  pnpx @mutagent/helix <skill-script.ts> [args...]
+
+Install scope:
+  (default)   project-local — installs into <your project>/.claude (and .codex)
+  --global    home dir       — installs into ~/.claude (and ~/.codex)
+
+init installs the Helix conductor + the lifecycle-stage skills
+(agentspec · diagnostics · evaluator) and links CLAUDE.md / AGENTS.md so your
+coding agent boots Helix. After install, open your coding agent and invoke:
+  claude   →   /mutagent-helix   (or just:  *mutagent)
+
+Docs: see README.md + .claude/skills/mutagent-helix/SKILL.md`);
+  process.exit(0);
+}
+
+// Resolve the target script to an ABSOLUTE path. Known subcommands map to skill
+// scripts (under skillRoot); an unknown first-arg is treated as a script path.
+const mapped = SUBCOMMANDS[sub] ?? sub;
+const scriptAbs = isAbsolute(mapped) ? mapped : join(skillRoot, mapped);
+
+// NOTE: no `cwd` override — the child inherits the user's shell PWD so init's
+// project-local install targets the project, not the helix package (W9-fix).
+const result = spawnSync("bash", [runSh, scriptAbs, ...rest], {
+  stdio: "inherit",
+});
+process.exit(result.status ?? 1);

package/mutagent-agentspec/.claude/skills/mutagent-agentspec/CLAUDE.md

@@ -0,0 +1,28 @@
+# mutagent-agentspec — skill nav map (lean)
+
+> Lean per-skill navigation. The substantive surface is `SKILL.md`. This file points.
+
+`mutagent-agentspec` is the **ADL ① SPEC** stage: a guided requirements interview that emits a
+portable, validated `agentspec.yaml`. The spec is the **Definition** (the interface — *what* the
+agent IS); `mutagent-builder` later implements it via `*build`. The parent session IS the domain
+orchestrator — it runs the interview itself and does **NOT** dispatch a coordinator sub-agent.
+
+## Where everything lives
+
+| You want… | Read |
+|---|---|
+| The skill surface (frontmatter · §0 setup · §0.1 star-commands · triggers · architecture) | `SKILL.md` |
+| The `*spec` interview FSM (+ BUILD/EVALUATE handoffs) | `references/workflows/orchestrator-protocol.md` |
+| Operative design principles (PR-NNN, operator-locked) | `references/principles.md` |
+| Machine-readable requirements hub (REQ-NNN) | `references/requirements.yaml` |
+| Pinned framework docs carried into BUILD | `references/frameworks/doc-pins.md` |
+| The `agentspec.yaml` schema (TypeBox, versioned `agentspec.v0.2.0`) | `scripts/contract/agentspec.schema.ts` |
+| The schema gate (CLI + pure validate fn) | `scripts/validate/validate-spec.ts` |
+| The worked, validated example spec | `assets/templates/agentspec.yaml.tpl` |
+| The constitution pointer + in-repo PRD link | `.meta/design-principles.md` |
+
+## Standalone
+
+This SPEC skill dispatches no build sub-agents. The `*build` handoff to `mutagent-builder` and the
+`*eval` handoff to an evaluator are designed composition boundaries mentioned at the doc/protocol
+level only — never a code import.

package/mutagent-agentspec/.claude/skills/mutagent-agentspec/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: mutagent-agentspec
+description: |
+  The ADL ① SPEC stage: a guided requirements interview that captures WHAT an AI agent IS and emits
+  a portable, validated agentspec.yaml. The spec is the Definition (the interface — persona, the
+  actual system prompt, jobs-to-be-done, context sources, tools across four buckets, agent type,
+  inbound activation triggers, decision modeling, standard operating procedures, and binary
+  eval criteria). BUILD is owned by mutagent-builder, which consumes the validated spec and implements
+  it into a target framework or harness. First invocation: auto-detects install. Then *spec runs a parent-session
+  interview (AskUserQuestion on Claude Code, chat multi-choice fallback elsewhere) → emits + validates
+  agentspec.yaml; *validate-spec is the TypeBox round-trip schema gate. The target may be a framework
+  (mastra / deepagents / pydantic-ai / langgraph) OR a harness (harness:claude-code / harness:codex).
+  After *spec or *validate-spec succeeds, Helix suggests *build; *build is owned by mutagent-builder.
+license: Apache-2.0. LICENSE + NOTICE have complete terms.
+compatibility: Designed for Claude Code, Codex, Cursor, OpenCode and similar coding-agent runtimes; works with git, gh CLI, and Bun/pnpm/npm runtimes.
+metadata:
+  author: mutagent
+  version: "0.1.0-alpha.0"
+# allowed-tools: OMITTED — agent uses all native tools per host runtime.
+---
+
+# mutagent-agentspec
+
+The **ADL ① SPEC** stage. Invoke this skill to specify a new agent — run a guided interview that
+captures *what the agent IS* and emit a portable, validated `agentspec.yaml`. The spec is the
+**Definition** (the interface); `mutagent-builder` later implements it into a target via `*build`.
+
+## §0 — Setup Detection (ALWAYS runs first)
+
+> **The parent session IS the domain orchestrator.** Run the interview yourself — do **NOT** dispatch
+> a coordinator sub-agent. AskUserQuestion (and therefore the interview) cannot run inside a
+> sub-agent (PR-006). BUILD sub-agents are owned by `mutagent-builder`; `*spec` dispatches none.
+
+**Lean install:** `pnpx @mutagent/agentspec init` installs the SPEC skill. There is no onboarding config
+to fill in this wave — `*spec` reads from the operator interactively, so "setup complete" simply means
+the skill tree is installed.
+
+```typescript
+// PSEUDOCODE — actual execution is agent-native
+const setup = await Bash("bash scripts/cli/run.sh scripts/setup/detect.ts");
+if (!setup.complete) {
+  // skill tree incomplete → reinstall: pnpx @mutagent/agentspec init
+} else {
+  // → load references/workflows/orchestrator-protocol.md and follow inline.
+  //   The parent session runs the *spec interview. DO NOT dispatch a coordinator.
+}
+```
+
+## §0.1 — Star-commands
+
+These are THIS skill's `*command` semantic map. Resolution is governed by the verbatim contract at
+the bottom of this section.
+
+| Command | Kind | Owner | Binds | Purpose |
+|---|---|---|---|---|
+| `*spec` | hybrid | own (full) | `references/workflows/orchestrator-protocol.md` | Guided parent-session interview → emits + validates `agentspec.yaml` (the Definition + Build + Appendix). |
+| `*validate-spec` | script | own | `scripts/validate/validate-spec.ts` | TypeBox round-trip schema gate over a spec file (`agentspec.v0.2.0`). |
+| `*sync-spec` | agent-chain | own entry · delegates read → `ai-architect #sync-spec` | `references/workflows/orchestrator-protocol.md#sync-spec--reconcile-the-spec--eval-triad-against-a-target-delegated` | The canonical **triad** reconcile (def → impl → EVAL; FUSES the former `*spec-from-impl` + builder `*spec-sync`). Cold (no spec → construct) AND warm (drift → reconcile) are ONE op — reverse-generate is drift-from-nothing. Reconciles BOTH the spec leg AND the **eval-criteria leg** (eval-suite criteria for agent/skill · code-quality criteria for code) against the impl. AgentSpec owns the entry but **NEVER reads code**: it delegates the target-read to builder's `ai-architect #sync-spec` (Helix-mediated HandoverBundle), then `*validate-spec`-gates + owns the spec result; the eval-leg write is the evaluator's criteria-maintenance hook (gated). |
+| `*eval` | agent-chain | route → evaluator (OUTLINED) | `references/workflows/orchestrator-protocol.md#eval` | Hand the built agent + its `evals.success_criteria` to an evaluator for eval-driven development (phased). |
+
+After `*spec` or `*validate-spec` succeeds, Helix suggests `*build`; `*build` is owned by `mutagent-builder` and consumes the validated `agentspec.yaml`.
+
+> **SPEC↔BUILD boundary (written once).** AgentSpec owns the spec ARTIFACT + its 3 commands (`*spec` ·
+> `*validate-spec` · `*sync-spec`). Builder owns the impl + the two agents (`ai-engineer` · `ai-architect`).
+> `ai-architect` is the SINGLE implementation-reader (`#verify` from `*build` + `#sync-spec` from `*sync-spec`).
+> Reverse-generate = drift-from-nothing = one `*sync-spec`. `*validate-spec` is never architectural review.
+
+### Star-command resolution contract (verbatim)
+
+When you encounter a `*<name>` token:
+1. **RESERVED** — `*` marks a command. NOT prose, NOT a file path, NOT an external shortcut. Never improvise.
+2. **RESOLVE** — look up `<name>` in the table above. Not found ⇒ ERROR + ask the operator. NEVER guess.
+3. **BINDING** — read `Kind` + `Binds`:
+   - `script` ⇒ CALL the bound script via `scripts/cli/run.sh`. Do NOT re-implement it in prose.
+   - `agent-chain` ⇒ load + run the bound workflow steps in order.
+   - `hybrid` ⇒ call script(s) for deterministic parts, reason for the rest.
+4. **PRE-GATE** — load any pre-gate references the bound workflow declares.
+5. **EXECUTE** — run the steps IN ORDER. Invent nothing.
+6. `Purpose` explains WHY (not executed). Steps MAY reference other `*commands` (composition).
+
+## §1 — Triggers
+
+This skill activates on any of:
+- `mutagent-agentspec` · `/mutagent-agentspec`
+- `*spec` · `spec` · `specify the agent` · `plan a new agent` · `define an agent` · `new agent spec`
+- `*sync-spec` · `sync the spec` · `spec sync` · `reconcile spec with code` · `code drifted from spec` · `spec from impl` · `reverse-generate a spec` · `adopt an existing agent` · `spec an existing implementation` · `no agentspec exists`
+- `pnpx @mutagent/agentspec init`
+
+## §2 — Quick start
+
+```bash
+# 1. install (project-local by default; --global for the home dir)
+pnpx @mutagent/agentspec init
+
+# 2. inside your coding agent
+/mutagent-agentspec        # load the skill
+*spec                      # run the guided interview → agentspec.yaml
+*validate-spec ./agentspec.yaml   # schema-gate it (round-trip)
+```
+
+Start from the worked example: `assets/templates/agentspec.yaml.tpl` (a complete, validated
+synthetic spec exercising every field).
+
+## §3 — Architecture
+
+```mermaid
+flowchart LR
+  spec["*spec — guided interview (parent session)"] --> emit["emit agentspec.yaml"]
+  emit --> validate["*validate-spec — TypeBox gate"]
+  validate -->|PASS| build["*build → mutagent-builder"]
+  build --> eval["*eval → evaluator"]
+  validate -.->|FAIL| spec
+```
+
+- **`*spec`** is full + parent-session-driven (the interview). **`*validate-spec`** is the schema gate.
+- **`*sync-spec`** reconciles the def → impl → EVAL triad against a target (cold construct OR warm drift — ONE op): the spec leg AND the eval-criteria leg (eval-suite for agent/skill · code-quality for code) both stay in lockstep with the impl. AgentSpec owns the entry but delegates the code-read to builder's `ai-architect #sync-spec`; it never reads code itself.
+- **`*build`** is owned by `mutagent-builder`; agentspec only suggests the next stage after a valid spec.
+- **`*eval`** is routed to EVALUATE after BUILD returns a handoff bundle.
+
+## §4 — Bill of materials
+
+| Surface | Path |
+|---|---|
+| The `agentspec.v0.2.0` schema (TypeBox) | `scripts/contract/agentspec.schema.ts` |
+| The schema gate | `scripts/validate/validate-spec.ts` |
+| The `*spec` output-dir resolver (`lifecycle.agentspec.spec_dir`; default `.mutagent/specs`) | `scripts/config/resolve-spec-dir.ts` |
+| The interview FSM (+ build/eval outlines) | `references/workflows/orchestrator-protocol.md` |
+| Operative principles (PR-NNN) | `references/principles.md` |
+| Requirements hub (REQ-NNN) | `references/requirements.yaml` |
+| Pinned framework docs | `references/frameworks/doc-pins.md` |
+| Worked example spec | `assets/templates/agentspec.yaml.tpl` |
+| CLI (install / probe / runner) | `scripts/cli/{init,doctor,run.sh}` · `scripts/setup/detect.ts` |
+
+## §5 — Standalone discipline
+
+Every artifact under `.claude/skills/mutagent-agentspec/` is a sealed SPEC unit. The `*build` handoff
+to `mutagent-builder` and the `*eval` handoff to EVALUATE are composition boundaries mentioned at the
+doc/protocol level only, never code imports. `*spec` itself dispatches no sub-agents.

package/mutagent-agentspec/.claude/skills/mutagent-agentspec/assets/templates/agentspec.yaml.tpl

@@ -0,0 +1,247 @@
+# =============================================================================
+# agentspec.yaml — WORKED EXAMPLE (agentspec.v0.2.0)
+# =============================================================================
+# A complete, NDA-clean, synthetic example exercising EVERY field of the contract.
+# Subject: "Atlas Research Assistant" — a generic research/support assistant. This file
+# is asserted VALID by scripts/validate/validate-spec.test.ts (the primary
+# "worked example is valid" gate). Copy it, then edit via the *spec interview.
+#
+# Descriptions are deliberately VERBOSE (PR-015) — the description is the primary
+# field the implementing LLM reads. Keep yours verbose too.
+# =============================================================================
+
+schema_version: "0.2.0"
+
+# ── META — canonical identity + loop position. The spec is implementation-AGNOSTIC:
+#    it does NOT enumerate its impls/subjects (PR-013 backwards-only linking). Downstream
+#    artifacts carry spec_id and point UP to this spec.
+meta:
+  spec_id: "atlas-research-assistant"          # stable identity anchor — survives all versions (PR-012)
+  spec_version: "0.1.0"
+  loop_state:
+    stage: "spec"                              # spec|build|eval|ship|diagnose|discover|improve (PR-010)
+    # last_verdict is OPTIONAL — omitted at spec-time (a freshly-spec'd agent has no verdict yet).
+    # Once the loop runs, set it to a string, e.g. last_verdict: "PASS".
+    updated_at: "2026-06-23T00:00:00.000Z"     # ISO-8601 (injected, never a self-read clock)
+
+# ── DEFINITION — the interface (WHAT the agent is, framework-independent).
+definition:
+  identity:
+    name: "Atlas Research Assistant"
+    version: "0.1.0"
+    description: >
+      A conversational research/support assistant that answers user questions grounded in
+      retrieved internal documentation and public reference material, always citing its
+      sources and never fabricating an answer when no source supports it.
+    kind: "agent"                              # agent|skill|composite (A2A-aligned)
+
+  persona:
+    role: "Senior research assistant"
+    persona: >
+      Methodical, precise, and source-obsessed. Atlas reads widely before answering, prefers
+      a short honest "I could not find a source for that" over a confident guess, and always
+      attributes claims to the document that supports them. Tone is calm and professional;
+      boundaries: never speculates beyond the retrieved evidence, never invents citations.
+
+  # The ACTUAL operative system prompt the runtime sends — the FULL text, not a summary (PR-014).
+  system_prompt: |
+    You are Atlas, a senior research assistant. Your job is to answer the user's question using
+    ONLY the sources you retrieve. Follow this procedure on every turn:
+      1. Restate the question in one sentence to confirm intent.
+      2. Retrieve relevant sources via the docs-search and web-reference tools.
+      3. Synthesize an answer that is fully grounded in the retrieved sources.
+      4. Cite every non-trivial claim with the source it came from.
+      5. If no retrieved source supports an answer, say so plainly and stop — do NOT guess.
+    Never fabricate a citation. Never present unsourced speculation as fact. Prefer a short,
+    correct, cited answer over a long, confident, unsourced one.
+
+  jobs_to_be_done:
+    - id: "answer-research-question"
+      description: >
+        Given a user research question, retrieve grounding sources and produce a cited,
+        evidence-backed answer — or an explicit "no supporting source found" when none exists.
+      expected_output: >
+        A concise answer with inline citations to the retrieved sources, or a clearly-labeled
+        "insufficient evidence" response.
+      backed_by: ["citation-formatter"]        # PR-024: the code tool(s) implementing this job; the
+                                               # build-faithfulness gate asserts each is built + tested.
+    - id: "summarize-document"
+      description: >
+        Given a document reference, produce a faithful structured summary that preserves the
+        document's claims without adding interpretation the document does not support.
+      expected_output: >
+        A bulleted summary with each bullet traceable to a section of the source document.
+
+  context_sources:
+    - id: "internal-docs-search"
+      kind: "api"
+      description: >
+        The internal documentation search API — the primary grounding source. Needed because the
+        assistant must answer from the organization's own knowledge base, not its training prior.
+      where_from: "https://docs.example.test/search"
+      auth_ref: "DOCS_SEARCH_API_KEY"
+    - id: "web-reference-mcp"
+      kind: "mcp"
+      description: >
+        A public web-reference MCP server used to corroborate or supplement internal answers with
+        cited public material. Preferred over a bespoke HTTP client per MCP-first binding (PR-004).
+      where_from: "mcp://web-reference"
+
+  tools:
+    integration:
+      - id: "docs-search"
+        kind: "saas"
+        ref: "docs-search-api"
+        description: >
+          Calls the internal documentation search API and returns ranked passages with source IDs.
+          Use it FIRST on every research question to gather grounding evidence.
+      - id: "web-reference"
+        kind: "mcp"
+        ref: "mcp://web-reference/search"
+        description: >
+          MCP tool that searches public reference material. Use it to corroborate internal findings
+          or when the internal docs return no relevant passage.
+    code:                                      # at *build, each module carries `// @implements <id>` +
+                                               # a test; the faithfulness gate (PR-024) asserts coverage.
+      - id: "citation-formatter"
+        lang: "python"
+        sandbox: true
+        description: >
+          A small sandboxed code tool that normalizes retrieved source IDs into a consistent
+          inline-citation format. Runs in a sandbox because it processes untrusted source metadata.
+    skills:
+      - id: "deep-summarize"
+        ref: "skill://deep-summarize"
+        description: >
+          A reusable summarization skill invoked for the summarize-document job — produces a
+          section-traceable structured summary from a long source document.
+    subagents:
+      - name: "retrieval-planner"
+        description: >
+          Plans a multi-step retrieval strategy for a complex question (decomposes it into
+          sub-queries, orders the searches, dedupes results).
+        instructions: >
+          Decompose the question into atomic sub-queries, issue docs-search for each, dedupe and
+          rank the combined passages, and return the top grounding set with source IDs.
+        tools: ["docs-search", "web-reference"]
+        model: "claude-sonnet-4-6"             # honored verbatim — model intent is sacred (PR-003)
+
+  agent_type: "conversational"                 # conversational|automation|orchestrator
+
+  triggers:                                    # how the DESIGNED agent is ACTIVATED (PR-017) — distinct from *monitor
+    - id: "a2a-research-request"
+      kind: "a2a"
+      description: >
+        An agent-to-agent research request arrives via the A2A protocol carrying a question payload;
+        Atlas answers and returns a cited response to the calling agent.
+      config:
+        protocol: "a2a"
+        accepts: "research-request/v1"
+    - id: "support-webhook"
+      kind: "webhook"
+      description: >
+        A support-platform webhook fires when a customer asks a knowledge-base question; the payload
+        carries the question text and a conversation ID for the reply.
+      config:
+        path: "/hooks/support-question"
+
+  modeling:
+    decision_graph:
+      state: "ResearchConversationState"
+      nodes: ["intake", "plan-retrieval", "retrieve", "synthesize", "cite", "answer", "no-evidence"]
+      edges:
+        - { from: "intake", to: "plan-retrieval" }
+        - { from: "plan-retrieval", to: "retrieve" }
+        - { from: "retrieve", to: "synthesize", condition: "at least one source found" }
+        - { from: "retrieve", to: "no-evidence", condition: "no source found" }
+        - { from: "synthesize", to: "cite" }
+        - { from: "cite", to: "answer" }
+    workflows:
+      - "research-answer: intake → plan-retrieval → retrieve → synthesize → cite → answer"
+      - "summarize: intake → retrieve(document) → deep-summarize → answer"
+
+  sop:                                         # standardized SOP — when + context + procedure (PR-016)
+    - id: "sop-grounded-answer"
+      when: "A user or calling agent asks a research question"
+      context: "The retrieved grounding passages (with source IDs) for the question"
+      procedure: >
+        Restate the question; plan and run retrieval; synthesize ONLY from retrieved passages;
+        attach a citation to every non-trivial claim; if no passage supports an answer, return the
+        no-evidence response.
+      on_outcome:
+        success: "Return the cited answer and log the sources used."
+        failure: "Return a labeled insufficient-evidence response; never guess."
+    - id: "sop-faithful-summary"
+      when: "A user asks for a summary of a specific document"
+      context: "The full text of the referenced document"
+      procedure: >
+        Invoke deep-summarize; verify each summary bullet is traceable to a section of the source;
+        drop any bullet that cannot be traced.
+
+  evals:                                       # binary-actionable + append-extensible (PR-019)
+    success_criteria:
+      - id: "every-claim-cited"
+        criterion: "Every non-trivial factual claim in the answer carries a citation to a retrieved source."
+        type: "llm-judge"
+        goal: "100% of factual claims are cited."
+      - id: "no-fabricated-citations"
+        criterion: "No citation in the answer points to a source that was not actually retrieved."
+        type: "code-check"
+        goal: "Zero fabricated citations."
+      - id: "honest-no-evidence"
+        criterion: "When no source supports an answer, the agent returns the no-evidence response instead of guessing."
+        type: "llm-judge"
+        goal: "100% of unsupported questions get an honest no-evidence response."
+    scenarios:                                 # the SITUATIONS the agent must handle (seed for the eval-suite)
+      - id: "grounded-question"
+        description: "A user asks a question the internal docs directly answer."
+        expected_behavior: "Plans retrieval, gathers passages, returns an answer with a citation per claim."
+        category: "answer-research-question"
+      - id: "no-supporting-source"
+        description: "A user asks a question no retrieved passage supports."
+        expected_behavior: "Returns the labeled no-evidence response; never guesses or invents a citation."
+        category: "answer-research-question"
+        edge_case: true
+      - id: "conflicting-sources"
+        description: "Two retrieved passages support opposite answers."
+        expected_behavior: "Surfaces the conflict with both citations rather than silently picking one."
+        category: "answer-research-question"
+        edge_case: true
+      - id: "summarize-long-doc"
+        description: "A user asks for a summary of a long referenced document."
+        expected_behavior: "Invokes deep-summarize; every bullet is traceable to a source section."
+        category: "summarize-document"
+    dataset_categories:                        # the GOLDEN eval-suite slices the *eval dataset must cover (F2)
+      - id: "answer-research-question"
+        description: >
+          Grounded Q&A over the internal docs + public reference material — the primary use case.
+          The dataset must span easy single-source hits through the hard edge-cases below.
+        edge_cases:
+          - "no supporting source exists (must return no-evidence)"
+          - "sources conflict (must surface the conflict)"
+          - "prompt-injection embedded in the question (must ignore injected instructions)"
+      - id: "summarize-document"
+        description: "Faithful structured summaries of referenced documents."
+        edge_cases:
+          - "document longer than the context window (must chunk, not truncate)"
+          - "document makes a claim with no support (summary must not amplify it)"
+
+# ── BUILD — the implementation target (guided choice, lives inside the spec → cascade-update, PR-001).
+build:
+  # String — accepts a framework (mastra|deepagents|pydantic-ai|langgraph) OR a harness
+  # (harness:claude-code|harness:codex|harness:<other>) OR a future target (PR-005).
+  target_framework: "langgraph"
+  # The execution runtime, PINNED at spec-time so *build implements ONCE (bun|node|deno|python|shell|…).
+  # Dogfood F4: an unpinned runtime caused a bash→Bun rebuild — pin it here to prevent the rework.
+  runtime: "python"
+  target_eval_framework: "mutagent-evaluator"
+
+# ── APPENDIX — pinned doc roots the *build agent crawls FRESH at build time (PR-002).
+appendix:
+  framework_docs:
+    langgraph:
+      - "https://docs.langchain.com/llms.txt"
+      - "https://docs.langchain.com/oss/python/langgraph/graph-api"
+  references:
+    - "Decision: langgraph chosen as the only fully-declarative graph target for this assistant."
+    - "Glossary: 'grounding source' = a passage retrieved at answer-time, never a training prior."

package/mutagent-agentspec/.claude/skills/mutagent-agentspec/references/frameworks/doc-pins.md

@@ -0,0 +1,53 @@
+# Framework Doc Pins
+
+> **PR-002 — fetched at build, never copied.** These are the CANONICAL documentation ROOTS the
+> `*build` agent (`ai-engineer`) crawls FRESH (WebFetch) at build time for the chosen
+> `build.target_framework`. SDKs churn — never vendor the doc BODIES into this skill. PIN the roots
+> here (and per-spec in `appendix.framework_docs`); crawl them live when building.
+
+## Pinned roots (per target)
+
+| Target | `llms.txt` / index root | Reference root | Notes |
+|---|---|---|---|
+| `mastra` | `https://mastra.ai/llms.txt` | `https://mastra.ai/reference/agents/agent` | TS-native agent framework. |
+| `deepagents` | `https://reference.langchain.com/python/deepagents/` | `github.com/langchain-ai/deepagents` | LangChain deep-agents. |
+| `pydantic-ai` | `https://ai.pydantic.dev/llms-full.txt` | `https://ai.pydantic.dev/api/agent/` | `llms.txt` intermittently drops the Agent section → use the HTML `api/agent/` fallback. |
+| `langgraph` | `https://docs.langchain.com/llms.txt` | `https://docs.langchain.com/oss/python/langgraph/graph-api` | Docs moved to `docs.langchain.com`; only fully-declarative graph target. |
+
+## Provider best-practices (dogfood F3 — crawl + apply at build)
+
+The `*build` agent also crawls the chosen MODEL PROVIDER's best-practice docs and applies them to the
+scaffold — chiefly **prompt-caching** (cache the static `system_prompt` + tool/skill defs + few-shot
+prefixes). Pin the provider's caching root for whichever provider the spec's models target; crawl it
+FRESH (PR-002) — never guess the caching API.
+
+| Provider | Prompt/context caching root | Notes |
+|---|---|---|
+| Anthropic | `https://docs.claude.com/en/docs/build-with-claude/prompt-caching` | `cache_control` breakpoints; cache the long static prefix. |
+| OpenAI | `https://platform.openai.com/docs/guides/prompt-caching` | Automatic for long prompts; order static content first. |
+| Google (Gemini) | `https://ai.google.dev/gemini-api/docs/caching` | Explicit context caching for repeated large prefixes. |
+
+The `ai-architect` Verifier confirms the caching (and any other crawled best-practice) was
+actually applied to the scaffold — a skipped, documented best-practice is a STEER.
+
+## Harness targets
+
+`build.target_framework` may also be a HARNESS of the form `harness:<x>` (PR-005), e.g.
+`harness:claude-code` or `harness:codex`. Harness targets emit a skill/agent definition for the
+named coding-agent runtime rather than a framework SDK scaffold. Harness-target doc pins + the
+emission shape are a Wave-2 `*build` concern (careful-design item) — they are NOT enumerated here
+yet, by design (lean, PR-007).
+
+## How a pin is used (PR-002)
+
+1. The spec's `appendix.framework_docs[target]` carries the spec-specific pin list (it may add to or
+   override the canonical roots above).
+2. At `*build`, `ai-engineer` runs `*crawl-docs` → WebFetch each pinned root FRESH.
+3. If a pin is dead/moved, the Actor escalates rather than scaffolding against a stale local copy.
+4. The `ai-architect` Verifier confirms every framework API the scaffold uses appears in the
+   crawled docs; an unpinned/guessed API is a STEER.
+
+## Maintenance
+
+When an upstream framework moves its docs, update the pinned root HERE (and note the move). Do NOT
+add a vendored copy of the doc body — the whole point of pinning is to crawl fresh.