@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/layers/agent-eval/trace-multi-turn/files/tests/per-turn-scorer.test.ts

@@ -0,0 +1,184 @@
+// Per-turn scorer — unmeasured-vs-failed disambiguation.
+//
+// Regression bait:
+//   - Pre-fix bug: turns with `weightTotal === 0` (no rubric matched any
+//     span) returned aggregateScore=0, which severityFromScore promoted
+//     to 'critical' findings in gradeSemanticStatus. Test asserts those
+//     turns now report `status: 'unmeasured'`, aggregateScore=null,
+//     contribute zero weight to cumulative, and never produce 'critical'.
+
+import test, { describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  scorePerTurn,
+  type StepRubric,
+} from '../src/eval/trace/per-turn-scorer.js'
+import type {
+  Trajectory,
+  TrajectoryStep,
+  Span,
+} from '@tangle-network/agent-eval'
+
+function llmStep(index: number, spanId: string, runId: string, output: string): TrajectoryStep {
+  const span: Span = {
+    spanId,
+    runId,
+    kind: 'llm',
+    name: 'gen',
+    startedAt: 0,
+    endedAt: 1,
+    status: 'ok',
+    model: 'test-model',
+    messages: [{ role: 'user', content: 'hi' }],
+    output,
+  }
+  return { index, span, depth: 0, events: [] }
+}
+
+function buildFiveTurnTrajectory(runId: string): {
+  trajectory: Trajectory
+  stepsByTurn: TrajectoryStep[][]
+} {
+  const turns: TrajectoryStep[][] = []
+  const all: TrajectoryStep[] = []
+  let idx = 0
+  for (let t = 1; t <= 5; t += 1) {
+    // Turns 2 and 4 are tool spans (non-llm) so the llm-only rubric won't match.
+    const isLlm = t !== 2 && t !== 4
+    if (isLlm) {
+      const step = llmStep(idx, `s${idx}`, runId, `output for turn ${t}`)
+      turns.push([step])
+      all.push(step)
+      idx += 1
+    } else {
+      const span: Span = {
+        spanId: `s${idx}`,
+        runId,
+        kind: 'tool',
+        name: 'noop',
+        startedAt: 0,
+        endedAt: 1,
+        status: 'ok',
+        toolName: 'noop',
+        args: {},
+      }
+      const step: TrajectoryStep = { index: idx, span, depth: 0, events: [] }
+      turns.push([step])
+      all.push(step)
+      idx += 1
+    }
+  }
+  const trajectory: Trajectory = {
+    runId,
+    steps: all,
+    llmTurns: 3,
+    toolCalls: 2,
+    judgeVerdicts: 0,
+    retrievals: 0,
+    totalDurationMs: 5,
+  }
+  return { trajectory, stepsByTurn: turns }
+}
+
+const llmOnlyRubric: StepRubric = {
+  id: 'llm-output-good',
+  kinds: ['llm'],
+  weight: 1,
+  grade: async () => ({ score: 0.9, rationale: 'looks good' }),
+}
+
+describe('per-turn-scorer: unmeasured turns are not silently failed', () => {
+  test('5-turn run with llm-only rubric reports turns 2 + 4 as unmeasured', async () => {
+    const { trajectory, stepsByTurn } = buildFiveTurnTrajectory('run-1')
+    const report = await scorePerTurn({
+      scenarioId: 'scenario-1',
+      runId: 'run-1',
+      trajectory,
+      stepsByTurn,
+      rubrics: [llmOnlyRubric],
+    })
+    assert.equal(report.perTurn.length, 5)
+    assert.equal(report.perTurn[0]!.status, 'measured')
+    assert.equal(report.perTurn[1]!.status, 'unmeasured', 'turn 2 had no llm span')
+    assert.equal(report.perTurn[2]!.status, 'measured')
+    assert.equal(report.perTurn[3]!.status, 'unmeasured', 'turn 4 had no llm span')
+    assert.equal(report.perTurn[4]!.status, 'measured')
+    assert.equal(report.perTurn[1]!.aggregateScore, null)
+    assert.equal(report.perTurn[3]!.aggregateScore, null)
+  })
+
+  test('cumulative score excludes unmeasured turns (no zero-pollution)', async () => {
+    const { trajectory, stepsByTurn } = buildFiveTurnTrajectory('run-2')
+    const report = await scorePerTurn({
+      scenarioId: 'scenario-1',
+      runId: 'run-2',
+      trajectory,
+      stepsByTurn,
+      rubrics: [llmOnlyRubric],
+    })
+    // 3 measured turns × 0.9 → cumulative 0.9, NOT (3*0.9 + 2*0)/5 = 0.54.
+    assert.ok(
+      Math.abs(report.cumulativeScore - 0.9) < 1e-9,
+      `cumulative should be 0.9 (excluding unmeasured), got ${report.cumulativeScore}`,
+    )
+  })
+
+  test('convergence turn lands on first measured turn meeting threshold', async () => {
+    const { trajectory, stepsByTurn } = buildFiveTurnTrajectory('run-3')
+    const report = await scorePerTurn({
+      scenarioId: 'scenario-1',
+      runId: 'run-3',
+      trajectory,
+      stepsByTurn,
+      rubrics: [llmOnlyRubric],
+      threshold: 0.7,
+    })
+    // Turn 1 is measured at 0.9 ≥ 0.7 → converges at turn 1.
+    assert.equal(report.convergenceTurn, 1)
+  })
+
+  test('all-unmeasured run does not emit critical findings or fake convergence', async () => {
+    // Build a run where every step is a tool span, so the llm-only rubric never matches.
+    const span = (i: number): TrajectoryStep => ({
+      index: i,
+      span: {
+        spanId: `s${i}`,
+        runId: 'run-x',
+        kind: 'tool',
+        name: 't',
+        startedAt: 0,
+        endedAt: 1,
+        status: 'ok',
+        toolName: 't',
+        args: {},
+      },
+      depth: 0,
+      events: [],
+    })
+    const steps = [span(0), span(1), span(2)]
+    const trajectory: Trajectory = {
+      runId: 'run-x',
+      steps,
+      llmTurns: 0,
+      toolCalls: 3,
+      judgeVerdicts: 0,
+      retrievals: 0,
+      totalDurationMs: 3,
+    }
+    const stepsByTurn = [[steps[0]!], [steps[1]!], [steps[2]!]]
+    const report = await scorePerTurn({
+      scenarioId: 'scenario-x',
+      runId: 'run-x',
+      trajectory,
+      stepsByTurn,
+      rubrics: [llmOnlyRubric],
+    })
+    assert.equal(report.cumulativeScore, 0)
+    assert.equal(report.convergenceTurn, null, 'no measured turn ⇒ no convergence')
+    // gradeSemanticStatus saw `available: false`. Status must NOT be 'pass'
+    // — there's nothing to pass. Either 'unavailable' or 'fail' is acceptable;
+    // 'pass' would be a muffled gate.
+    assert.notEqual(report.status, 'pass', 'all-unmeasured run must not falsely pass')
+  })
+})

package/registry/layers/agent-eval/trace-multi-turn/manifest.json

@@ -0,0 +1,70 @@
+{
+  "id": "trace-multi-turn",
+  "slot": "agent-eval",
+  "description": "Multi-turn trajectory eval. Composes @tangle-network/agent-eval's Trajectory + TrajectoryStep + StepRubric + buildTrajectory + gradeSemanticStatus to drive a multi-turn rollout against an agent endpoint, capture per-turn spans, and grade each step independently. Per-turn scoring exposes WHERE quality degrades (Turn 3? Turn 5?) and emits a convergence-turn (first turn meeting threshold) so regressions surface as 'Turn 3 dropped from 0.82 → 0.61' rather than a flat aggregate. Composes on top of agent-eval:scenarios and agent-eval:judge-rubric — reuses the same scenario corpus and dimension-level rubric primitives. Opt-in only — appliesTo[] is empty by design; opt in via the workspace-compose `--preset` flag (eval+trace) or by adding to a family's `includes` list.",
+  "appliesTo": [],
+  "provides": [
+    "eval:trace-multi-turn"
+  ],
+  "requires": [
+    "eval:scenarios",
+    "eval:judge-rubric"
+  ],
+  "defaults": {
+    "multiTurnMaxTurns": 8,
+    "multiTurnConvergenceThreshold": 0.7,
+    "multiTurnTimeoutMs": 60000
+  },
+  "packageDeps": {
+    "dependencies": {
+      "@tangle-network/agent-eval": "^0.23.0"
+    }
+  },
+  "files": [
+    {
+      "source": "files/src/eval/trace/trajectory-runner.ts",
+      "target": "src/eval/trace/trajectory-runner.ts"
+    },
+    {
+      "source": "files/src/eval/trace/per-turn-scorer.ts",
+      "target": "src/eval/trace/per-turn-scorer.ts"
+    },
+    {
+      "source": "files/src/eval/trace/example-rubric.ts",
+      "target": "src/eval/trace/example-rubric.ts"
+    },
+    {
+      "source": "files/src/eval/trace/README.md",
+      "target": "src/eval/trace/README.md"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/eval/trace/trajectory-runner.ts"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/eval/trace/per-turn-scorer.ts"
+    }
+  ],
+  "contextHints": {
+    "extensionPoints": [
+      "src/eval/trace/trajectory-runner.ts",
+      "src/eval/trace/example-rubric.ts"
+    ]
+  },
+  "keywords": [
+    "multi-turn eval",
+    "trace scoring",
+    "trajectory eval",
+    "per-turn rubric",
+    "step rubric",
+    "convergence turn",
+    "trajectory step"
+  ],
+  "tieredKeywords": {
+    "tier1": ["multi-turn eval", "trace scoring", "trajectory eval", "per-turn rubric"],
+    "tier2": ["step rubric", "convergence turn", "trajectory step"]
+  }
+}

package/registry/layers/agent-output/blocks/files/lib/blocks.ts

@@ -0,0 +1,57 @@
+// Structured output block parser. Splits a streaming chat response
+// into typed chunks the host UI can render distinctly.
+//
+// Grammar: `:::<name>\n<body>\n:::` — name is alphanumeric+dashes, body
+// is anything until the matching `:::` on its own line. Unmatched fences
+// are passed through as prose so a partially-streamed block doesn't
+// vanish from the user's view.
+
+export type Chunk =
+  | { kind: 'prose'; text: string }
+  | { kind: 'block'; name: string; body: string }
+
+const FENCE = /^:::([a-z][a-z0-9-]*)$/i
+
+export function parseBlocks(input: string): Chunk[] {
+  const lines = input.split(/\r?\n/)
+  const out: Chunk[] = []
+  let proseBuf: string[] = []
+  let inBlock: { name: string; bodyLines: string[] } | null = null
+
+  const flushProse = () => {
+    if (proseBuf.length === 0) return
+    const text = proseBuf.join('\n')
+    if (text.trim().length > 0) out.push({ kind: 'prose', text })
+    proseBuf = []
+  }
+
+  for (const line of lines) {
+    if (inBlock) {
+      if (line.trim() === ':::') {
+        out.push({ kind: 'block', name: inBlock.name, body: inBlock.bodyLines.join('\n') })
+        inBlock = null
+      } else {
+        inBlock.bodyLines.push(line)
+      }
+      continue
+    }
+    const m = FENCE.exec(line.trim())
+    if (m) {
+      flushProse()
+      inBlock = { name: m[1] as string, bodyLines: [] }
+      continue
+    }
+    proseBuf.push(line)
+  }
+  // Unclosed block at EOF — emit body as prose so the user still sees it.
+  if (inBlock) {
+    proseBuf.push(`:::${inBlock.name}`)
+    proseBuf.push(...inBlock.bodyLines)
+  }
+  flushProse()
+  return out
+}
+
+export function blocksOfType(chunks: Chunk[], name: string): Array<Extract<Chunk, { kind: 'block' }>> {
+  return chunks.filter((c): c is Extract<Chunk, { kind: 'block' }> => c.kind === 'block' && c.name === name)
+}

package/registry/layers/agent-output/blocks/manifest.json

@@ -0,0 +1,95 @@
+{
+  "id": "blocks",
+  "slot": "agent-output",
+  "description": "Structured-output-blocks parser. Lets agents emit `:::proposal`, `:::filing`, `:::artifact`, `:::screener-result`, `:::escalation`, `:::survey` blocks inside streaming chat \u2014 downstream UIs parse the side-channel and render typed cards. Stack on every agent-runtime bundle that emits structured deliverables (most do).",
+  "appliesTo": [
+    "agent-runtime-account-executive-ts",
+    "agent-runtime-architect-ts",
+    "agent-runtime-auditor-ts",
+    "agent-runtime-business-partner-ts",
+    "agent-runtime-career-coach-ts",
+    "agent-runtime-chef-ts",
+    "agent-runtime-chemistry-research-ts",
+    "agent-runtime-cmo-advisor-ts",
+    "agent-runtime-college-counselor-ts",
+    "agent-runtime-cs-research-ts",
+    "agent-runtime-cs-tutor-ts",
+    "agent-runtime-customer-success-ts",
+    "agent-runtime-data-analyst-ts",
+    "agent-runtime-designer-ts",
+    "agent-runtime-devops-ts",
+    "agent-runtime-doctor-ts",
+    "agent-runtime-engineering-manager-ts",
+    "agent-runtime-essay-coach-ts",
+    "agent-runtime-financial-analyst-ts",
+    "agent-runtime-fitness-coach-ts",
+    "agent-runtime-friend-ts",
+    "agent-runtime-game-designer-ts",
+    "agent-runtime-grant-writer-ts",
+    "agent-runtime-history-tutor-ts",
+    "agent-runtime-illustrator-ts",
+    "agent-runtime-language-tutor-ts",
+    "agent-runtime-legal-counsel-ts",
+    "agent-runtime-math-research-ts",
+    "agent-runtime-math-tutor-ts",
+    "agent-runtime-mediator-ts",
+    "agent-runtime-meditation-coach-ts",
+    "agent-runtime-ml-research-ts",
+    "agent-runtime-music-producer-ts",
+    "agent-runtime-novelist-coach-ts",
+    "agent-runtime-nutritionist-ts",
+    "agent-runtime-pentester-ts",
+    "agent-runtime-pharmacist-ts",
+    "agent-runtime-photographer-ts",
+    "agent-runtime-physics-research-ts",
+    "agent-runtime-product-manager-ts",
+    "agent-runtime-real-estate-ts",
+    "agent-runtime-recruiter-ts",
+    "agent-runtime-relationship-coach-ts",
+    "agent-runtime-research",
+    "agent-runtime-sales-engineer-ts",
+    "agent-runtime-screenwriter-ts",
+    "agent-runtime-security-engineer-ts",
+    "agent-runtime-tax-ts",
+    "agent-runtime-therapist-ts",
+    "agent-runtime-travel-planner-ts",
+    "agent-runtime-veterinarian-ts",
+    "agent-runtime-wealth-manager-ts",
+    "multi-agent-creative-studio-ts",
+    "multi-agent-legal-ops-ts",
+    "multi-agent-product-ops-ts",
+    "multi-agent-research-lab-ts",
+    "multi-agent-startup-team-ts"
+  ],
+  "provides": [
+    "output:blocks-grammar"
+  ],
+  "defaults": {
+    "structuredOutputBlocks": true,
+    "blockTypes": [
+      "proposal",
+      "filing",
+      "artifact",
+      "screener-result",
+      "escalation",
+      "survey"
+    ]
+  },
+  "files": [
+    {
+      "source": "files/lib/blocks.ts",
+      "target": "src/lib/blocks.ts"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": "src/lib/blocks.ts"
+    }
+  ],
+  "contextHints": {
+    "extensionPoints": [
+      "src/lib/blocks.ts"
+    ]
+  }
+}

package/registry/layers/agent-tools/clinical-screeners/files/lib/tools/screeners.ts

@@ -0,0 +1,61 @@
+// Validated clinical screeners. Each scoreFn returns the screener's
+// numeric score AND a categorical band (e.g. PHQ-9 → minimal/mild/moderate/
+// moderately-severe/severe). The caller (the agent's runtime) must pair
+// any "moderate-or-above" band with the escalation protocol; the bundle
+// is NOT a substitute for real clinical care and must say so.
+
+export interface ScreenerResult {
+  screener: 'phq-9' | 'gad-7' | 'audit-c'
+  score: number
+  band: string
+  recommendEscalation: boolean
+}
+
+export function scorePhq9(answers: number[]): ScreenerResult {
+  if (answers.length !== 9 || answers.some((a) => a < 0 || a > 3)) {
+    throw new Error('PHQ-9 expects exactly 9 answers each in [0,3]')
+  }
+  const score = answers.reduce((a, b) => a + b, 0)
+  let band: string
+  if (score <= 4) band = 'minimal'
+  else if (score <= 9) band = 'mild'
+  else if (score <= 14) band = 'moderate'
+  else if (score <= 19) band = 'moderately-severe'
+  else band = 'severe'
+  // Q9 (suicidal ideation) ANY positive → always escalate, regardless of total
+  const q9 = answers[8] ?? 0
+  return { screener: 'phq-9', score, band, recommendEscalation: q9 > 0 || score >= 10 }
+}
+
+export function scoreGad7(answers: number[]): ScreenerResult {
+  if (answers.length !== 7 || answers.some((a) => a < 0 || a > 3)) {
+    throw new Error('GAD-7 expects exactly 7 answers each in [0,3]')
+  }
+  const score = answers.reduce((a, b) => a + b, 0)
+  let band: string
+  if (score <= 4) band = 'minimal'
+  else if (score <= 9) band = 'mild'
+  else if (score <= 14) band = 'moderate'
+  else band = 'severe'
+  return { screener: 'gad-7', score, band, recommendEscalation: score >= 10 }
+}
+
+const CRISIS_PATTERNS = [
+  /\b(kill\s+(my)?self|suicide|end\s+(it|my\s+life)|hurt\s+myself|i\s+want\s+to\s+die)\b/i,
+  /\b(no\s+reason\s+to\s+live|better\s+off\s+dead)\b/i,
+]
+
+export interface CrisisDetection {
+  detected: boolean
+  matched: string[]
+  recommendEscalation: boolean
+}
+
+export function detectCrisisLanguage(text: string): CrisisDetection {
+  const matched: string[] = []
+  for (const re of CRISIS_PATTERNS) {
+    const m = re.exec(text)
+    if (m) matched.push(m[0])
+  }
+  return { detected: matched.length > 0, matched, recommendEscalation: matched.length > 0 }
+}

package/registry/layers/agent-tools/clinical-screeners/files/templates/escalation-protocol.md

@@ -0,0 +1,77 @@
+---
+capability: escalation-protocol
+status: active
+source: hand-authored, aligned with 988 Suicide & Crisis Lifeline guidance
+retrieved: 2026-04-25
+---
+
+# Escalation Protocol
+
+This template is loaded whenever a screener returns a moderate-or-above
+band, OR `detectCrisisLanguage()` flags content, OR the user explicitly
+asks for help finding a clinician. **The agent never substitutes for
+real clinical care.** Treat every escalation path as a hard handoff,
+not a soft suggestion.
+
+## Trigger conditions (any one fires the protocol)
+
+1. **Suicidality.** PHQ-9 question 9 ≥ 1, OR explicit user statement of
+   intent / plan / means / timing.
+2. **Severe band.** PHQ-9 ≥ 20, GAD-7 ≥ 15, AUDIT-C indicating severe.
+3. **Crisis language detected.** `detectCrisisLanguage()` returns
+   `detected: true`.
+4. **User direct request.** "Find me a therapist" / "I need someone to
+   talk to" / equivalent.
+
+## Response sequence (in this order, every time)
+
+1. **Acknowledge directly.** "Thank you for telling me this. I hear how
+   hard things are right now." — short, plain, no clinical jargon.
+2. **State the limit.** "I'm an AI — I can listen and help you find
+   support, but I'm not a clinician and I can't give you the level of
+   care you deserve right now."
+3. **Provide hotline numbers** (US default; bundle's locale slot can
+   substitute regional equivalents):
+   - **988** — Suicide & Crisis Lifeline (call or text)
+   - **741741** — Crisis Text Line (text "HOME")
+   - **911** — emergencies
+4. **Offer to stay** while the user contacts help. Don't disappear; the
+   moment they say "I called" or "I'll go," then disengage gracefully.
+5. **Save the escalation event** to the bundle's `state/escalations/`
+   store with timestamp + trigger + screener result (if any). Do NOT
+   save free-text user content unless the bundle's privacy slot
+   permits.
+
+## Refusal mode
+
+Refuse to:
+
+- Provide specific medical advice ("take X medication", "stop taking Y")
+- Replace a real clinician
+- Promise confidentiality (the bundle's privacy contract is bounded;
+  state limits explicitly when asked)
+- Continue a conversation the user has indicated they want to end —
+  always honor disengagement requests
+
+## Locale slots
+
+Bundle families can override `defaults.crisisHotlines` in their manifest
+to provide regional equivalents (Samaritans UK 116-123, Lifeline AU
+13-11-14, etc.). If overridden, this template's hotline numbers are
+substituted at compose time.
+
+## Output discipline
+
+Crisis turns produce a `:::escalation` block alongside or instead of
+the user-visible response:
+
+```
+:::escalation
+trigger: <suicidality|severe-band|crisis-language|user-request>
+hotlines: [{ name, number, type: call|text }]
+session-id: <uuid>
+:::
+```
+
+Downstream UIs render escalation blocks distinctly (often as a banner
+that doesn't scroll away).

package/registry/layers/agent-tools/clinical-screeners/files/templates/screener-gad7.md

@@ -0,0 +1,62 @@
+---
+capability: gad-7-screener
+status: active
+source: GAD-7 (Spitzer, Kroenke, Williams, Löwe 2006) — public domain
+retrieved: 2026-04-25
+---
+
+# GAD-7 Anxiety Screener
+
+Use this screener when a user describes symptoms aligned with generalized
+anxiety (excessive worry, restlessness, irritability, sleep disturbance,
+muscle tension) AND consents to a structured screening conversation.
+
+## When to use
+
+Trigger this template when:
+
+- The user explicitly asks "do I have anxiety?" or similar
+- The conversation surfaces ≥3 anxiety-aligned symptoms
+- The user asks for a structured self-assessment
+
+Do NOT use this screener when:
+
+- The user is in active panic / crisis (de-escalate first; use
+  `escalation-protocol.md` if needed)
+- The user has not consented
+- The user's primary symptoms suggest a different condition (e.g.
+  PTSD-shaped — different validated tools apply)
+
+## Method
+
+Ask the user, one question at a time, "Over the last 2 weeks, how often
+have you been bothered by …" each of the 7 questions. Record each answer
+as 0 (not at all), 1 (several days), 2 (more than half the days), or 3
+(nearly every day).
+
+Questions:
+
+1. Feeling nervous, anxious, or on edge
+2. Not being able to stop or control worrying
+3. Worrying too much about different things
+4. Trouble relaxing
+5. Being so restless that it's hard to sit still
+6. Becoming easily annoyed or irritable
+7. Feeling afraid as if something awful might happen
+
+## Scoring
+
+Total = sum of 7 answers (range 0–21).
+
+| Score | Band | Recommendation |
+|---|---|---|
+| 0–4 | minimal | reassure, normalize |
+| 5–9 | mild | watchful waiting, supportive listening |
+| 10–14 | moderate | recommend professional consultation |
+| 15–21 | severe | strong recommendation for immediate care |
+
+## Output discipline
+
+Wrap result in a `:::screener-result` block matching the PHQ-9 shape.
+Refuse to diagnose or replace clinical care; always pair
+moderate-or-above with the escalation protocol.

package/registry/layers/agent-tools/clinical-screeners/files/templates/screener-phq9.md

@@ -0,0 +1,84 @@
+---
+capability: phq-9-screener
+status: active
+source: PHQ-9 (Kroenke, Spitzer, Williams 2001) — public domain
+retrieved: 2026-04-25
+---
+
+# PHQ-9 Depression Screener
+
+Use this screener when a user describes symptoms aligned with depression
+(persistent low mood, loss of interest, sleep/appetite changes, fatigue,
+hopelessness) AND consents to a structured screening conversation.
+
+## When to use
+
+Trigger this template when:
+
+- The user explicitly asks "am I depressed?" or similar
+- The conversation surfaces ≥3 depression-aligned symptoms organically
+- The user asks for a structured self-assessment
+
+Do NOT use this screener when:
+
+- The user is in active crisis (use `escalation-protocol.md` instead)
+- The user has not consented to a structured screening
+- The user is under 18 (different validated tools apply)
+
+## Method
+
+Ask the user, one question at a time, "Over the last 2 weeks, how often
+have you been bothered by …" each of the 9 questions. Record each answer
+as 0 (not at all), 1 (several days), 2 (more than half the days), or 3
+(nearly every day).
+
+Questions:
+
+1. Little interest or pleasure in doing things
+2. Feeling down, depressed, or hopeless
+3. Trouble falling or staying asleep, or sleeping too much
+4. Feeling tired or having little energy
+5. Poor appetite or overeating
+6. Feeling bad about yourself — that you are a failure or have let yourself or your family down
+7. Trouble concentrating on things, such as reading the newspaper or watching television
+8. Moving or speaking so slowly that other people could have noticed; or the opposite — being so fidgety or restless that you have been moving around a lot more than usual
+9. **Thoughts that you would be better off dead, or of hurting yourself in some way**
+
+Question 9 is the suicidality screen. **ANY non-zero answer triggers
+mandatory escalation per `escalation-protocol.md`, regardless of the
+total score.**
+
+## Scoring
+
+Total score = sum of all 9 answers (range 0–27).
+
+| Score | Band | Recommendation |
+|---|---|---|
+| 0–4 | minimal | reassure, normalize, watchful waiting |
+| 5–9 | mild | watchful waiting, supportive listening, repeat in 2 weeks |
+| 10–14 | moderate | recommend professional consultation |
+| 15–19 | moderately-severe | recommend professional consultation, consider safety planning |
+| 20–27 | severe | strong recommendation for immediate professional care |
+
+## Output discipline
+
+Wrap the result in a `:::screener-result` block:
+
+```
+:::screener-result
+screener: phq-9
+score: <0-27>
+band: <minimal|mild|moderate|moderately-severe|severe>
+recommend-escalation: <true|false>
+notes: <one sentence — never speculate beyond the score>
+:::
+```
+
+## Refusal mode
+
+Refuse to:
+
+- Diagnose. The screener is a screening tool, not a diagnostic instrument.
+- Replace clinical care. Always pair moderate-or-above bands with
+  `escalation-protocol.md`.
+- Score on user-recalled answers from a different conversation. Re-ask.