From 4055c952f2bc04fb702351f7232e6da04d5202e5 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:26:04 +0000
Subject: [PATCH 01/14] =?UTF-8?q?test:=20US1=20failing=20tests=20=E2=80=94?=
 =?UTF-8?q?=20baseline=20step,=20classification=20fields,=20chronic=20narr?=
 =?UTF-8?q?ative?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Red phase: 3 new tests assert domain specialists include Baseline step
(pcp_fetch_timeseries + pcp_detect_anomalies + 7-day window), classification
fields (ANOMALY/RECURRING/BASELINE), and chronic problem narrative guidance.
Cross-cutting correctly excluded.
---
 tests/unit/test_prompts_specialist.py | 92 +++++++++++++++++++++++++++
 1 file changed, 92 insertions(+)

diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index dcee6a6..b524a47 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -183,3 +183,95 @@ def test_specialist_impl_interpolates_lookback():
 
     text = _specialist_investigate_impl("cpu", lookback="4hours")[0]["content"]
     assert "4hours" in text
+
+
+# ---------------------------------------------------------------------------
+# T002: Baseline step presence in domain subsystems
+# ---------------------------------------------------------------------------
+
+_DOMAIN_SUBSYSTEMS = ("cpu", "memory", "disk", "network", "process")
+
+
+def test_baseline_step_present_in_domain_subsystems():
+    """T002: Domain specialists include a Baseline step referencing
+    pcp_fetch_timeseries, pcp_detect_anomalies, and 7-day window."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    for sub in _DOMAIN_SUBSYSTEMS:
+        text = _specialist_investigate_impl(sub)[0]["content"]
+        assert "baseline" in text.lower(), f"{sub}: missing Baseline step"
+        assert "pcp_fetch_timeseries" in text, f"{sub}: Baseline must reference pcp_fetch_timeseries"
+        assert "pcp_detect_anomalies" in text, f"{sub}: Baseline must reference pcp_detect_anomalies"
+        assert "7-day" in text.lower() or "7 day" in text.lower(), (
+            f"{sub}: Baseline must reference 7-day window"
+        )
+
+
+# ---------------------------------------------------------------------------
+# T003: Cross-cutting does NOT include Baseline step
+# ---------------------------------------------------------------------------
+
+
+def test_baseline_step_absent_from_crosscutting():
+    """T003: Cross-cutting specialist does NOT have a Baseline workflow step."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    text = _specialist_investigate_impl("crosscutting")[0]["content"]
+    # Cross-cutting should not have a numbered "Baseline" step in its workflow
+    # (it may reference the word "baseline" in domain knowledge for classification,
+    # but should NOT have a "## Baseline" or "**Baseline**" workflow step)
+    workflow_section = text.split("## Workflow")[1] if "## Workflow" in text else ""
+    assert "baseline" not in workflow_section.lower(), (
+        "Cross-cutting must NOT have a Baseline workflow step"
+    )
+
+
+# ---------------------------------------------------------------------------
+# T004: Classification fields in report structure
+# ---------------------------------------------------------------------------
+
+
+def test_classification_fields_in_domain_report_guidance():
+    """T004: Domain specialist output includes classification, ANOMALY,
+    RECURRING, BASELINE, baseline_context, severity_despite_baseline."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    required_terms = [
+        "classification",
+        "ANOMALY",
+        "RECURRING",
+        "BASELINE",
+        "baseline_context",
+        "severity_despite_baseline",
+    ]
+    for sub in _DOMAIN_SUBSYSTEMS:
+        text = _specialist_investigate_impl(sub)[0]["content"]
+        for term in required_terms:
+            assert term in text, f"{sub}: missing '{term}' in report guidance"
+
+
+# ---------------------------------------------------------------------------
+# T005: Narrative guidance for chronic problems
+# ---------------------------------------------------------------------------
+
+
+def test_chronic_problem_narrative_guidance():
+    """T005: Domain specialists include narrative guidance for BASELINE-classified
+    findings — explaining chronic problems in human terms."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    for sub in _DOMAIN_SUBSYSTEMS:
+        text = _specialist_investigate_impl(sub)[0]["content"].lower()
+        has_chronic_language = any(
+            phrase in text
+            for phrase in (
+                "not a new problem",
+                "your normal",
+                "chronic",
+                "historically typical",
+                "been this way",
+            )
+        )
+        assert has_chronic_language, (
+            f"{sub}: missing narrative guidance for chronic/baseline findings"
+        )

From 94eba6f4dde9973488898af5aaeba1b65755ad35 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:27:11 +0000
Subject: [PATCH 02/14] =?UTF-8?q?feat:=20US1=20=E2=80=94=20baseline=20step?=
 =?UTF-8?q?=20+=20classification=20fields=20in=20domain=20specialist=20pro?=
 =?UTF-8?q?mpts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Domain subsystems (cpu, memory, disk, network, process) now include a
Baseline step that instructs the agent to fetch 7-day history and run
pcp_detect_anomalies. Report guidance includes classification (ANOMALY/
RECURRING/BASELINE), baseline_context, severity_despite_baseline, and
chronic problem narrative. Cross-cutting workflow unchanged.
---
 src/pmmcp/prompts/specialist.py | 70 +++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 7 deletions(-)

diff --git a/src/pmmcp/prompts/specialist.py b/src/pmmcp/prompts/specialist.py
index 77e2fa9..1c4f2b0 100644
--- a/src/pmmcp/prompts/specialist.py
+++ b/src/pmmcp/prompts/specialist.py
@@ -141,6 +141,7 @@ def _specialist_investigate_impl(
     entry = _SPECIALIST_KNOWLEDGE[subsystem]
     display = entry["display_name"]
     prefix = entry["prefix"]
+    is_domain = prefix is not None
 
     # Build context clauses
     host_clause = f" on host **{host}**" if host else " across all monitored hosts"
@@ -149,7 +150,7 @@ def _specialist_investigate_impl(
     request_clause = f"\n\n**Investigation request**: {request}" if request else ""
 
     # Discovery instruction — prefix-based for subsystems with a prefix
-    if prefix:
+    if is_domain:
         discovery = (
             f'Use `pcp_discover_metrics(prefix="{prefix}")` as your **primary discovery** '
             f"mechanism to enumerate all available {display} metrics. Do not rely solely on "
@@ -161,6 +162,65 @@ def _specialist_investigate_impl(
             "ALL namespaces for anomalies, then drill into the subsystems that surface problems."
         )
 
+    # Report guidance — domain subsystems get classification fields
+    report_guidance = entry["report_guidance"]
+    if is_domain:
+        report_guidance += """
+
+### Finding Classification
+
+For **each** finding, assign a classification based on the 7-day baseline:
+
+- **classification**: One of ANOMALY, RECURRING, or BASELINE
+  - **ANOMALY**: `pcp_detect_anomalies` reports a significant z-score AND the pattern \
+does not recur at consistent times in the 7-day timeseries
+  - **RECURRING**: The 7-day timeseries shows repeated spikes at consistent times of day \
+(batch jobs, log rotation, backups, cron jobs) — look for time-of-day correlation
+  - **BASELINE**: Current values are within normal range based on 7-day history (low z-score \
+or no anomaly detected)
+- **baseline_context**: Human-readable comparison to the 7-day baseline \
+(e.g., "CPU idle has been below 15% for the past 7 days")
+- **severity_despite_baseline**: Threshold-based severity independent of classification \
+(critical/warning/info/none). A BASELINE finding with severity=warning means the host's \
+normal operating state is degraded — this is not a new problem, but it is still a problem.
+
+### Chronic Problem Articulation
+
+When a finding is classified as BASELINE but has non-trivial severity_despite_baseline, \
+articulate this clearly: the condition is chronic — it has historically been this way — \
+but "your normal is sick." For example: "CPU idle has been below 10% for a week — this is \
+not a new problem, but the host is chronically saturated."\
+"""
+
+    # Workflow — domain subsystems get a Baseline step after Discover
+    if is_domain:
+        workflow = """\
+1. **Discover** available metrics using the approach above.
+2. **Baseline** — establish the 7-day historical context:
+   a. Fetch 7-day historical data at 1hour interval using `pcp_fetch_timeseries` for your \
+key metrics.
+   b. Run `pcp_detect_anomalies` comparing the current investigation window against the \
+7-day baseline to identify statistically significant deviations.
+   c. Note the anomaly results — you will use them in the Analyse step to classify findings.
+   d. **Graceful degradation**: If `pcp_detect_anomalies` returns insufficient data (few or \
+no results — common for new hosts, recent PCP deployments, or archive gaps), fall back to \
+threshold-only analysis. Note "insufficient baseline data, falling back to threshold-only \
+analysis" in your report. If data is sparse (gaps from PCP restarts), attempt detection but \
+note reduced confidence. If 0 days of history are available, skip this Baseline step entirely.
+3. **Fetch** key metrics with `pcp_fetch_timeseries` at an appropriate interval for the \
+current investigation window.
+4. **Analyse** using the domain knowledge heuristics — check thresholds, correlations, \
+trends. Use the baseline results from step 2 to classify each finding.
+5. **Report** each finding in the structured format described above, including classification.
+6. **Recommend** next steps — immediate actions, further investigation, or escalation."""
+    else:
+        workflow = """\
+1. **Discover** available metrics using the approach above.
+2. **Fetch** key metrics with `pcp_fetch_timeseries` at an appropriate interval.
+3. **Analyse** using the domain knowledge heuristics — check thresholds, correlations, trends.
+4. **Report** each finding in the structured format described above.
+5. **Recommend** next steps — immediate actions, further investigation, or escalation."""
+
     content = f"""\
 You are a **{display} specialist** conducting a focused performance investigation\
 {host_clause}{time_clause}{lookback_clause}.{request_clause}
@@ -177,15 +237,11 @@ def _specialist_investigate_impl(
 
 ## Reporting Structure
 
-{entry["report_guidance"]}
+{report_guidance}
 
 ## Workflow
 
-1. **Discover** available metrics using the approach above.
-2. **Fetch** key metrics with `pcp_fetch_timeseries` at an appropriate interval.
-3. **Analyse** using the domain knowledge heuristics — check thresholds, correlations, trends.
-4. **Report** each finding in the structured format described above.
-5. **Recommend** next steps — immediate actions, further investigation, or escalation.
+{workflow}
 
 If you find no anomalies, say so explicitly — "no anomalies found in {display}" is a valid result.
 """

From e3f13c33e702a1275358a315dc37adab903f747c Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:27:51 +0000
Subject: [PATCH 03/14] =?UTF-8?q?test:=20US2=20failing=20tests=20=E2=80=94?=
 =?UTF-8?q?=20baseline-aware=20heuristics=20in=20domain=20knowledge?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Red phase: 5 tests assert each domain specialist's domain_knowledge
contains at least one baseline-aware heuristic referencing the 7-day
baseline, time-of-day patterns, or scheduled job detection.
---
 tests/unit/test_prompts_specialist.py | 64 +++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index b524a47..4b9b72a 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -275,3 +275,67 @@ def test_chronic_problem_narrative_guidance():
         assert has_chronic_language, (
             f"{sub}: missing narrative guidance for chronic/baseline findings"
         )
+
+
+# ---------------------------------------------------------------------------
+# T010-T013: Baseline-aware heuristics in domain knowledge
+# ---------------------------------------------------------------------------
+
+
+def test_cpu_domain_knowledge_baseline_heuristic():
+    """T010: CPU domain_knowledge includes guidance to check whether current
+    CPU levels are typical for this time of day over the past week."""
+    from pmmcp.prompts.specialist import _SPECIALIST_KNOWLEDGE
+
+    dk = _SPECIALIST_KNOWLEDGE["cpu"]["domain_knowledge"].lower()
+    assert "time of day" in dk or "past week" in dk or "7-day" in dk or "baseline" in dk, (
+        "CPU domain_knowledge missing baseline-aware heuristic"
+    )
+
+
+def test_memory_domain_knowledge_baseline_heuristic():
+    """T011: Memory domain_knowledge includes guidance to compare memory growth
+    against the 7-day baseline to distinguish leaks from normal working-set growth."""
+    from pmmcp.prompts.specialist import _SPECIALIST_KNOWLEDGE
+
+    dk = _SPECIALIST_KNOWLEDGE["memory"]["domain_knowledge"].lower()
+    has_baseline = any(
+        phrase in dk
+        for phrase in ("7-day", "baseline", "working-set growth", "normal growth", "past week")
+    )
+    assert has_baseline, "Memory domain_knowledge missing baseline-aware leak heuristic"
+
+
+def test_disk_domain_knowledge_baseline_heuristic():
+    """T012: Disk domain_knowledge includes guidance to check whether I/O spikes
+    recur at the same time daily (scheduled jobs)."""
+    from pmmcp.prompts.specialist import _SPECIALIST_KNOWLEDGE
+
+    dk = _SPECIALIST_KNOWLEDGE["disk"]["domain_knowledge"].lower()
+    has_schedule = any(
+        phrase in dk
+        for phrase in ("same time daily", "scheduled job", "recur", "backup", "log rotation")
+    )
+    assert has_schedule, "Disk domain_knowledge missing baseline-aware scheduled job heuristic"
+
+
+def test_network_domain_knowledge_baseline_heuristic():
+    """T013a: Network domain_knowledge contains at least one baseline-aware heuristic."""
+    from pmmcp.prompts.specialist import _SPECIALIST_KNOWLEDGE
+
+    dk = _SPECIALIST_KNOWLEDGE["network"]["domain_knowledge"].lower()
+    has_baseline = any(
+        phrase in dk for phrase in ("baseline", "7-day", "past week", "normal variance")
+    )
+    assert has_baseline, "Network domain_knowledge missing baseline-aware heuristic"
+
+
+def test_process_domain_knowledge_baseline_heuristic():
+    """T013b: Process domain_knowledge contains at least one baseline-aware heuristic."""
+    from pmmcp.prompts.specialist import _SPECIALIST_KNOWLEDGE
+
+    dk = _SPECIALIST_KNOWLEDGE["process"]["domain_knowledge"].lower()
+    has_baseline = any(
+        phrase in dk for phrase in ("baseline", "7-day", "past week", "7-day pattern")
+    )
+    assert has_baseline, "Process domain_knowledge missing baseline-aware heuristic"

From 43c76d1e89e9235109bf6dec8da4fbf9d5b7f500 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:28:46 +0000
Subject: [PATCH 04/14] =?UTF-8?q?feat:=20US2=20=E2=80=94=20baseline-aware?=
 =?UTF-8?q?=20heuristics=20in=20all=205=20domain=20specialist=20knowledge?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each domain specialist now has a 9th heuristic referencing the 7-day
baseline: CPU (time-of-day saturation), Memory (leak vs working-set),
Disk (scheduled job I/O), Network (drop rate variance), Process
(count/context-switch patterns).
---
 src/pmmcp/prompts/specialist.py | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/pmmcp/prompts/specialist.py b/src/pmmcp/prompts/specialist.py
index 1c4f2b0..f377ccb 100644
--- a/src/pmmcp/prompts/specialist.py
+++ b/src/pmmcp/prompts/specialist.py
@@ -21,7 +21,8 @@
 5. Runqueue depth (`kernel.all.runnable`) sustained > ncpu signals CPU starvation; correlate with load average.
 6. Per-CPU imbalance: if one CPU is pegged at 100% while others idle, suspect single-threaded bottleneck or IRQ affinity.
 7. High iowait (`kernel.all.cpu.wait.total`) with low user/sys → the CPU is waiting on I/O, investigate disk/network.
-8. Sudden CPU spike with no workload change → check for runaway process, cron job, or garbage collection storm.""",
+8. Sudden CPU spike with no workload change → check for runaway process, cron job, or garbage collection storm.
+9. Before flagging saturation, check the 7-day baseline — is this CPU level typical for this time of day over the past week? A host that always runs hot at 2pm (batch processing) is different from a sudden spike.""",
         "report_guidance": """\
 For each finding report: metric name, observed value (as %), baseline comparison, \
 affected time window, and severity (critical/warning/info). Express CPU values as \
@@ -38,7 +39,8 @@
 5. Slab growth (`mem.vmstat.nr_slab_reclaimable`, `nr_slab_unreclaimable`) — unreclaimable slab bloat is a kernel memory leak.
 6. Huge page usage (`mem.util.hugepagesTotalBytes` vs `mem.util.hugepagesFreeBytes`) — misconfig wastes reserved memory.
 7. Buffer/cache ratio: high `mem.util.bufmem` + `mem.util.cached` with low `mem.util.free` is normal — Linux aggressively caches.
-8. Memory pressure trend: plot `mem.util.available` over time — a steady decline indicates a leak even if current usage looks OK.""",
+8. Memory pressure trend: plot `mem.util.available` over time — a steady decline indicates a leak even if current usage looks OK.
+9. Compare memory growth against the 7-day baseline to distinguish genuine leaks from normal working-set growth — if `mem.util.available` has been declining at the same rate all week, it is the baseline, not a new leak.""",
         "report_guidance": """\
 For each finding report: metric name, observed value in human units (MB/GB), \
 percentage of total memory, trend direction (stable/rising/falling), and severity. \
@@ -55,7 +57,8 @@
 5. I/O latency = avactive / (reads + writes) — > 10ms for SSD or > 20ms for HDD is slow.
 6. Read vs write ratio: heavy writes with journaling FS (ext4, xfs) amplify actual I/O — check for write-behind flush storms.
 7. Correlate disk saturation with CPU iowait (`kernel.all.cpu.wait.total`) — if both high, disk is the bottleneck.
-8. Per-device breakdown matters: one saturated device with others idle → workload imbalance or partition misplacement.""",
+8. Per-device breakdown matters: one saturated device with others idle → workload imbalance or partition misplacement.
+9. Check whether I/O spikes recur at the same time daily — scheduled jobs like backups, log rotation, or cron-driven ETL cause predictable bursts that are not anomalies.""",
         "report_guidance": """\
 For each finding report: device name, metric, observed value in human units \
 (IOPS, MB/s, ms latency), device utilisation %, and severity. Always identify \
@@ -72,7 +75,8 @@
 5. Connection states: `network.tcp.currestab` for active connections — sudden spike may indicate connection storm or DDoS.
 6. Per-interface breakdown: aggregate numbers hide problems — a saturated eth0 with idle eth1 suggests missing bonding or routing issues.
 7. Dropped packets with no errors → buffer exhaustion (ring buffer too small) or CPU too slow to process incoming packets.
-8. Compare inbound vs outbound — asymmetric traffic patterns help identify whether the host is a client, server, or relay.""",
+8. Compare inbound vs outbound — asymmetric traffic patterns help identify whether the host is a client, server, or relay.
+9. Check whether the current packet drop rate is within normal variance over the past week — a host that always drops 0.01% of packets at peak hours is not the same as a sudden 5% drop rate.""",
         "report_guidance": """\
 For each finding report: interface name, metric, observed rate in human units \
 (KB/s, MB/s, packets/s), percentage of link capacity if known, and severity. \
@@ -89,7 +93,8 @@
 5. Per-process CPU/memory via hotproc (if available) — identifies the specific process consuming resources.
 6. Blocked processes (`proc.runq.blocked`) — processes stuck in uninterruptible sleep, usually waiting on I/O.
 7. Thread count trends — growing thread count over time without corresponding workload increase suggests thread pool leak.
-8. New process creation rate (`rate(proc.nprocs)`) — high churn (many short-lived processes) wastes fork/exec overhead.""",
+8. New process creation rate (`rate(proc.nprocs)`) — high churn (many short-lived processes) wastes fork/exec overhead.
+9. Check whether process count and context switch rate match the 7-day pattern before flagging runaway processes — some hosts legitimately run 500+ processes at baseline.""",
         "report_guidance": """\
 For each finding report: process metric, observed value, comparison to healthy \
 baseline (e.g., normal process count), trend direction, and severity. Identify \

From 00fda6e1f4052f9d37ff81d185c0c43af642ad2c Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:30:01 +0000
Subject: [PATCH 05/14] =?UTF-8?q?test:=20US5=20=E2=80=94=20graceful=20degr?=
 =?UTF-8?q?adation=20tests=20(pass=20immediately,=20covered=20by=20US1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Degradation fallback was included in the Baseline step text from US1.
Tests validate the contract: threshold-only fallback instruction and
"insufficient baseline" limitation note are present for all domain
subsystems.
---
 tests/unit/test_prompts_specialist.py | 32 +++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index 4b9b72a..eb4efee 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -339,3 +339,35 @@ def test_process_domain_knowledge_baseline_heuristic():
         phrase in dk for phrase in ("baseline", "7-day", "past week", "7-day pattern")
     )
     assert has_baseline, "Process domain_knowledge missing baseline-aware heuristic"
+
+
+# ---------------------------------------------------------------------------
+# T020-T021: Graceful degradation when baseline data is insufficient
+# ---------------------------------------------------------------------------
+
+
+def test_graceful_degradation_fallback_instruction():
+    """T020: Domain specialists include instructions to fall back to
+    threshold-only analysis if pcp_detect_anomalies returns insufficient data."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    for sub in _DOMAIN_SUBSYSTEMS:
+        text = _specialist_investigate_impl(sub)[0]["content"].lower()
+        assert "threshold-only" in text or "threshold only" in text, (
+            f"{sub}: missing threshold-only fallback instruction"
+        )
+        assert "insufficient" in text or "fall back" in text or "fallback" in text, (
+            f"{sub}: missing fallback trigger language"
+        )
+
+
+def test_graceful_degradation_report_limitation():
+    """T021: Domain specialists include instructions to note 'insufficient baseline'
+    or similar limitation wording in the report when degraded."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    for sub in _DOMAIN_SUBSYSTEMS:
+        text = _specialist_investigate_impl(sub)[0]["content"].lower()
+        assert "insufficient baseline" in text, (
+            f"{sub}: missing 'insufficient baseline' limitation note"
+        )

From 62e2ca844bf678fbaa6834f97436b05d4017f0a0 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:30:40 +0000
Subject: [PATCH 06/14] =?UTF-8?q?fix:=20lint=20=E2=80=94=20line=20length?=
 =?UTF-8?q?=20in=20baseline=20step=20test=20assertions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/unit/test_prompts_specialist.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index eb4efee..fddccc9 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -200,8 +200,12 @@ def test_baseline_step_present_in_domain_subsystems():
     for sub in _DOMAIN_SUBSYSTEMS:
         text = _specialist_investigate_impl(sub)[0]["content"]
         assert "baseline" in text.lower(), f"{sub}: missing Baseline step"
-        assert "pcp_fetch_timeseries" in text, f"{sub}: Baseline must reference pcp_fetch_timeseries"
-        assert "pcp_detect_anomalies" in text, f"{sub}: Baseline must reference pcp_detect_anomalies"
+        assert "pcp_fetch_timeseries" in text, (
+            f"{sub}: Baseline must reference pcp_fetch_timeseries"
+        )
+        assert "pcp_detect_anomalies" in text, (
+            f"{sub}: Baseline must reference pcp_detect_anomalies"
+        )
         assert "7-day" in text.lower() or "7 day" in text.lower(), (
             f"{sub}: Baseline must reference 7-day window"
         )

From 5335c51de2ccdc534d137dd82a12dbe89272d1e8 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:31:09 +0000
Subject: [PATCH 07/14] =?UTF-8?q?test:=20US3=20failing=20tests=20=E2=80=94?=
 =?UTF-8?q?=20cross-cutting=20classification=20prioritisation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Red phase: 3 tests assert cross-cutting specialist prioritises ANOMALY
over RECURRING/BASELINE, flags correlated anomalies across subsystems,
and notes mixed classification scenarios.
---
 tests/unit/test_prompts_specialist.py | 50 +++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index fddccc9..52723fc 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -345,6 +345,56 @@ def test_process_domain_knowledge_baseline_heuristic():
     assert has_baseline, "Process domain_knowledge missing baseline-aware heuristic"
 
 
+# ---------------------------------------------------------------------------
+# T026-T028: Cross-cutting classification prioritisation
+# ---------------------------------------------------------------------------
+
+
+def test_crosscutting_classification_prioritisation():
+    """T026: Cross-cutting output includes guidance to prioritise
+    ANOMALY-classified findings over RECURRING or BASELINE."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    text = _specialist_investigate_impl("crosscutting")[0]["content"]
+    assert "ANOMALY" in text, "Cross-cutting missing ANOMALY reference"
+    has_priority = any(
+        phrase in text.lower()
+        for phrase in ("prioriti", "rank", "above", "higher")
+    )
+    assert has_priority, (
+        "Cross-cutting missing prioritisation guidance for ANOMALY"
+    )
+
+
+def test_crosscutting_correlated_anomalies():
+    """T027: Cross-cutting output includes guidance to flag correlated
+    anomalies across multiple subsystems at the same timestamp."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    text = _specialist_investigate_impl("crosscutting")[0]["content"].lower()
+    assert "correlat" in text, (
+        "Cross-cutting missing correlated anomaly guidance"
+    )
+    has_multi = any(
+        phrase in text
+        for phrase in ("multiple subsystem", "across subsystem", "same timestamp")
+    )
+    assert has_multi, (
+        "Cross-cutting missing multi-subsystem anomaly correlation"
+    )
+
+
+def test_crosscutting_mixed_classification_guidance():
+    """T028: Cross-cutting output includes guidance to note when one
+    subsystem reports BASELINE while another reports ANOMALY."""
+    from pmmcp.prompts.specialist import _specialist_investigate_impl
+
+    text = _specialist_investigate_impl("crosscutting")[0]["content"]
+    assert "BASELINE" in text and "ANOMALY" in text, (
+        "Cross-cutting missing BASELINE/ANOMALY mixed classification ref"
+    )
+
+
 # ---------------------------------------------------------------------------
 # T020-T021: Graceful degradation when baseline data is insufficient
 # ---------------------------------------------------------------------------

From 72f51f58acee66e605e30c1d88d755a592d12058 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:31:26 +0000
Subject: [PATCH 08/14] =?UTF-8?q?feat:=20US3=20=E2=80=94=20cross-cutting?=
 =?UTF-8?q?=20specialist=20prioritises=20by=20classification?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cross-cutting domain knowledge now instructs the agent to prioritise
ANOMALY over RECURRING/BASELINE, flag correlated anomalies across
subsystems, and note mixed classification scenarios.
---
 src/pmmcp/prompts/specialist.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/pmmcp/prompts/specialist.py b/src/pmmcp/prompts/specialist.py
index f377ccb..cc9edac 100644
--- a/src/pmmcp/prompts/specialist.py
+++ b/src/pmmcp/prompts/specialist.py
@@ -111,7 +111,10 @@
 5. Load average vs individual subsystems: high load with low CPU user% → the load is I/O-bound or memory-bound, not compute-bound.
 6. Time correlation: find the exact moment things changed, then look at ALL subsystems at that timestamp.
 7. Use `pcp_compare_windows` to quantify before/after — "it got 3× worse" is more useful than "it's bad."
-8. Check derived metrics (derived.cpu.utilisation, derived.mem.utilisation, derived.disk.utilisation) for quick triage.""",
+8. Check derived metrics (derived.cpu.utilisation, derived.mem.utilisation, derived.disk.utilisation) for quick triage.
+9. Prioritise ANOMALY-classified findings above RECURRING or BASELINE — what changed is more actionable than what has always been wrong.
+10. Flag correlated anomalies across multiple subsystems at the same timestamp with higher confidence — if disk and CPU both spike simultaneously, the root cause is likely upstream of both.
+11. When one subsystem reports BASELINE while another reports ANOMALY at the same time, the ANOMALY subsystem is more likely root cause — the BASELINE subsystem's chronic condition is not the trigger.""",
         "report_guidance": """\
 For each finding report: the originating subsystem, metric, observed value, \
 cross-subsystem correlation (e.g., "disk saturation causing CPU iowait"), \

From 4906195c61e676126607d71cc34a2aec1bc9c8cd Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:32:14 +0000
Subject: [PATCH 09/14] =?UTF-8?q?test:=20US4=20failing=20tests=20=E2=80=94?=
 =?UTF-8?q?=20coordinator=20classification-based=20ranking?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Red phase: 3 tests assert coordinator synthesis ranks ANOMALY above
BASELINE/RECURRING, calls out normal behaviour, and highlights
recurring pattern matches.
---
 tests/unit/test_prompts_coordinator.py | 51 ++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/tests/unit/test_prompts_coordinator.py b/tests/unit/test_prompts_coordinator.py
index dcca88d..be61321 100644
--- a/tests/unit/test_prompts_coordinator.py
+++ b/tests/unit/test_prompts_coordinator.py
@@ -119,3 +119,54 @@ def test_coordinator_impl_interpolates_lookback():
 
     text = _coordinate_investigation_impl(request="issue", lookback="6hours")[0]["content"]
     assert "6hours" in text
+
+
+# ---------------------------------------------------------------------------
+# T032-T034: Classification-based ranking in coordinator synthesis
+# ---------------------------------------------------------------------------
+
+
+def test_coordinator_classification_ranking():
+    """T032: Coordinator ranks ANOMALY above BASELINE/RECURRING regardless
+    of severity, with severity as secondary sort within each tier."""
+    from pmmcp.prompts.coordinator import _coordinate_investigation_impl
+
+    text = _coordinate_investigation_impl(request="app is slow")[0]["content"]
+    assert "ANOMALY" in text, "Coordinator missing ANOMALY reference"
+    has_ranking = any(
+        phrase in text.lower()
+        for phrase in ("rank", "prioriti", "above", "tier")
+    )
+    assert has_ranking, "Coordinator missing classification ranking guidance"
+
+
+def test_coordinator_baseline_callout():
+    """T033: Coordinator explicitly calls out findings that are normal
+    behaviour for the host."""
+    from pmmcp.prompts.coordinator import _coordinate_investigation_impl
+
+    text = _coordinate_investigation_impl(request="app is slow")[0]["content"]
+    has_callout = any(
+        phrase in text.lower()
+        for phrase in (
+            "normal behaviour",
+            "normal behavior",
+            "baseline behaviour",
+            "baseline behavior",
+            "chronic",
+        )
+    )
+    assert has_callout, (
+        "Coordinator missing baseline/normal behaviour callout"
+    )
+
+
+def test_coordinator_recurring_pattern_highlight():
+    """T034: Coordinator highlights when an apparent anomaly matches a
+    known recurring pattern."""
+    from pmmcp.prompts.coordinator import _coordinate_investigation_impl
+
+    text = _coordinate_investigation_impl(request="app is slow")[0]["content"]
+    assert "RECURRING" in text or "recurring" in text, (
+        "Coordinator missing recurring pattern reference"
+    )

From 35bbb1521e4a9b9a7eb39fdbbd5cea75fe245ea3 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:32:51 +0000
Subject: [PATCH 10/14] =?UTF-8?q?feat:=20US4=20=E2=80=94=20coordinator=20s?=
 =?UTF-8?q?ynthesis=20ranks=20by=20classification=20then=20severity?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Synthesis phase now ranks ANOMALY > RECURRING > BASELINE (severity as
secondary sort within each tier). Output structure updated from
"Findings by Severity" to "Findings by Classification & Severity"
with sections for New Anomalies, Recurring Patterns, Baseline
Behaviour, and Normal Operation.
---
 src/pmmcp/prompts/coordinator.py | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/pmmcp/prompts/coordinator.py b/src/pmmcp/prompts/coordinator.py
index b6760ae..69d9161 100644
--- a/src/pmmcp/prompts/coordinator.py
+++ b/src/pmmcp/prompts/coordinator.py
@@ -95,9 +95,21 @@ def _coordinate_investigation_impl(
    story of what happened. "At 14:32, memory utilisation crossed 95%, triggering swap \
    activity, which caused disk I/O to spike, which manifested as CPU iowait."
 
-4. **Rank by impact**: Order findings by severity and blast radius, not by subsystem.
+4. **Rank by classification, then severity**: Group findings by classification tier, \
+   not by subsystem. ANOMALY findings rank above RECURRING, which rank above BASELINE — \
+   regardless of severity. Within each tier, sort by severity (critical → warning → info). \
+   What changed (ANOMALY) is more actionable than what has always been wrong (BASELINE).
 
-5. **Recommend actions**: Concrete next steps — not "investigate further" but \
+5. **Call out normal behaviour**: Explicitly identify findings that are baseline \
+   behaviour — chronic conditions that are normal for this host. These still matter \
+   (a host whose "normal" is CPU-saturated is sick), but they are not the trigger \
+   for the current incident.
+
+6. **Highlight recurring patterns**: When an apparent anomaly matches a known \
+   recurring pattern (RECURRING classification from specialists), call this out — \
+   "this spike looks alarming but occurs daily at 2am during the backup window."
+
+7. **Recommend actions**: Concrete next steps — not "investigate further" but \
    "check process X for memory leak" or "increase swap space as immediate mitigation."
 
 ## Output Structure
@@ -109,10 +121,20 @@ def _coordinate_investigation_impl(
 ## Root Cause Analysis
 <unified narrative with timeline and cross-subsystem correlation>
 
-## Findings by Severity
+## Findings by Classification & Severity
+
+### New Anomalies
 1. [CRITICAL] ...
 2. [WARNING] ...
-3. [INFO] ...
+
+### Recurring Patterns
+1. [WARNING] ... (occurs daily at <time>)
+
+### Baseline Behaviour (Chronic Conditions)
+1. [WARNING] ... (has been this way for 7+ days — not a new problem)
+
+### Normal Operation
+- <subsystem>: no anomalies detected
 
 ## Recommendations
 1. Immediate: ...

From 7c6921ab29c668cde3ba6e3ecdbb38e8b8288488 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 02:34:54 +0000
Subject: [PATCH 11/14] docs: update investigation-flow for 5-step specialist
 workflow + classification ranking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Specialist workflow diagram updated from 4-step to 5-step (Discover →
Baseline → Fetch → Analyse → Report) with pcp_detect_anomalies call.
Cross-cutting noted as excluded from Baseline step. Synthesis phase
updated for ANOMALY > RECURRING > BASELINE ranking. Output structure
now shows "Findings by Classification & Severity". Test formatting
applied.
---
 docs/investigation-flow.md             | 48 +++++++++++++++++---------
 tests/unit/test_prompts_coordinator.py |  9 ++---
 tests/unit/test_prompts_specialist.py  | 20 +++--------
 3 files changed, 39 insertions(+), 38 deletions(-)

diff --git a/docs/investigation-flow.md b/docs/investigation-flow.md
index 9d4bf72..cc7c3f3 100644
--- a/docs/investigation-flow.md
+++ b/docs/investigation-flow.md
@@ -83,7 +83,7 @@ flowchart TD
     PROC --> SYN
     CROSS --> SYN
 
-    SYN --> OUT["Unified Report\n• Root cause narrative\n• Timeline correlation\n• Findings ranked by severity\n• Concrete recommendations"]
+    SYN --> OUT["Unified Report\n• Root cause narrative\n• Timeline correlation\n• Findings ranked by classification & severity\n  (ANOMALY > RECURRING > BASELINE)\n• Concrete recommendations"]
 
     style CI fill:#2d6a4f,color:#fff
     style PAR fill:#40916c,color:#fff
@@ -107,10 +107,13 @@ relationships, and interpretation rules from experienced performance engineers.
 
 ## Specialist Workflow
 
-Every specialist follows the same 4-step discipline: discover what metrics exist,
-fetch the data, analyse against domain heuristics, then report structured findings.
-This prevents the common failure mode of querying metrics that don't exist on the
-target host.
+Domain specialists (CPU, Memory, Disk, Network, Process) follow a 5-step
+discipline: discover what metrics exist, establish a 7-day baseline for anomaly
+detection, fetch current data, analyse against domain heuristics with baseline
+context, then report structured and classified findings.
+
+The **cross-cutting** specialist does NOT include a Baseline step — it consumes
+classifications from the domain specialists rather than baselining independently.
 
 ```mermaid
 sequenceDiagram
@@ -126,22 +129,29 @@ sequenceDiagram
         T-->>S: Available metric names
     end
 
+    rect rgb(225, 235, 225)
+        Note over S,T: 2. Baseline (domain specialists only)
+        S->>T: pcp_fetch_timeseries(names=[...], interval="1hour", start="-7days")
+        T-->>S: 7-day historical data
+        S->>T: pcp_detect_anomalies(recent vs 7-day baseline)
+        T-->>S: Anomaly results (z-scores, directions)
+        Note over S: Note results for step 4<br/>If insufficient data → threshold-only fallback
+    end
+
     rect rgb(230, 235, 245)
-        Note over S,T: 2. Fetch
+        Note over S,T: 3. Fetch
         S->>T: pcp_fetch_timeseries(names=[...])
-        T-->>S: Time-series data
-        S->>T: pcp_compare_windows(...) [optional]
-        T-->>S: Statistical comparison
+        T-->>S: Current investigation window data
     end
 
     rect rgb(245, 235, 225)
-        Note over S,T: 3. Analyse
-        Note over S: Apply domain heuristics<br/>Check thresholds & correlations<br/>Identify anomalies
+        Note over S,T: 4. Analyse
+        Note over S: Apply domain heuristics<br/>Check thresholds & correlations<br/>Classify: ANOMALY / RECURRING / BASELINE<br/>Assign severity_despite_baseline
     end
 
     rect rgb(240, 230, 230)
-        Note over S,T: 4. Report
-        S-->>C: Structured findings<br/>(metric, value, severity,<br/>affected window, recommendation)
+        Note over S,T: 5. Report
+        S-->>C: Classified findings<br/>(metric, value, classification,<br/>baseline_context, severity,<br/>severity_despite_baseline)
     end
 ```
 
@@ -155,8 +165,14 @@ coordinator synthesises findings:
 2. **Timeline correlation** — the subsystem that changed first is the likely root
    cause
 3. **Unified narrative** — tell the story of what happened, not just list findings
-4. **Rank by impact** — order by severity and blast radius
-5. **Recommend actions** — concrete next steps, not "investigate further"
+4. **Rank by classification, then severity** — ANOMALY findings rank above
+   RECURRING, which rank above BASELINE (severity is secondary sort within each
+   tier). What changed is more actionable than what has always been wrong.
+5. **Call out normal behaviour** — explicitly identify chronic baseline conditions
+6. **Highlight recurring patterns** — flag when an apparent anomaly matches a known
+   recurring pattern (e.g., daily backup window)
+7. **Recommend actions** — concrete next steps, not "investigate further"
 
 The output follows a structured format: executive summary → root cause analysis →
-findings by severity → recommendations → specialist status.
+findings by classification & severity (New Anomalies → Recurring Patterns →
+Baseline Behaviour → Normal Operation) → recommendations → specialist status.
diff --git a/tests/unit/test_prompts_coordinator.py b/tests/unit/test_prompts_coordinator.py
index be61321..58d7dbf 100644
--- a/tests/unit/test_prompts_coordinator.py
+++ b/tests/unit/test_prompts_coordinator.py
@@ -133,10 +133,7 @@ def test_coordinator_classification_ranking():
 
     text = _coordinate_investigation_impl(request="app is slow")[0]["content"]
     assert "ANOMALY" in text, "Coordinator missing ANOMALY reference"
-    has_ranking = any(
-        phrase in text.lower()
-        for phrase in ("rank", "prioriti", "above", "tier")
-    )
+    has_ranking = any(phrase in text.lower() for phrase in ("rank", "prioriti", "above", "tier"))
     assert has_ranking, "Coordinator missing classification ranking guidance"
 
 
@@ -156,9 +153,7 @@ def test_coordinator_baseline_callout():
             "chronic",
         )
     )
-    assert has_callout, (
-        "Coordinator missing baseline/normal behaviour callout"
-    )
+    assert has_callout, "Coordinator missing baseline/normal behaviour callout"
 
 
 def test_coordinator_recurring_pattern_highlight():
diff --git a/tests/unit/test_prompts_specialist.py b/tests/unit/test_prompts_specialist.py
index 52723fc..6712c4f 100644
--- a/tests/unit/test_prompts_specialist.py
+++ b/tests/unit/test_prompts_specialist.py
@@ -357,13 +357,8 @@ def test_crosscutting_classification_prioritisation():
 
     text = _specialist_investigate_impl("crosscutting")[0]["content"]
     assert "ANOMALY" in text, "Cross-cutting missing ANOMALY reference"
-    has_priority = any(
-        phrase in text.lower()
-        for phrase in ("prioriti", "rank", "above", "higher")
-    )
-    assert has_priority, (
-        "Cross-cutting missing prioritisation guidance for ANOMALY"
-    )
+    has_priority = any(phrase in text.lower() for phrase in ("prioriti", "rank", "above", "higher"))
+    assert has_priority, "Cross-cutting missing prioritisation guidance for ANOMALY"
 
 
 def test_crosscutting_correlated_anomalies():
@@ -372,16 +367,11 @@ def test_crosscutting_correlated_anomalies():
     from pmmcp.prompts.specialist import _specialist_investigate_impl
 
     text = _specialist_investigate_impl("crosscutting")[0]["content"].lower()
-    assert "correlat" in text, (
-        "Cross-cutting missing correlated anomaly guidance"
-    )
+    assert "correlat" in text, "Cross-cutting missing correlated anomaly guidance"
     has_multi = any(
-        phrase in text
-        for phrase in ("multiple subsystem", "across subsystem", "same timestamp")
-    )
-    assert has_multi, (
-        "Cross-cutting missing multi-subsystem anomaly correlation"
+        phrase in text for phrase in ("multiple subsystem", "across subsystem", "same timestamp")
     )
+    assert has_multi, "Cross-cutting missing multi-subsystem anomaly correlation"
 
 
 def test_crosscutting_mixed_classification_guidance():

From 6d824337dc56abf1d5ea3bdbec8db4854fb82ee6 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 03:04:18 +0000
Subject: [PATCH 12/14] docs: add 011-specialist-baselining spec artifacts

Spec, plan, tasks (all complete), research, data model, contracts,
checklist, and quickstart for the specialist historical baselining
feature.
---
 .../checklists/requirements.md                |  37 +++
 .../contracts/prompt-contracts.md             |  56 ++++
 specs/011-specialist-baselining/data-model.md |  42 +++
 specs/011-specialist-baselining/plan.md       | 206 +++++++++++++
 specs/011-specialist-baselining/quickstart.md |  44 +++
 specs/011-specialist-baselining/research.md   |  88 ++++++
 specs/011-specialist-baselining/spec.md       | 160 ++++++++++
 specs/011-specialist-baselining/tasks.md      | 290 ++++++++++++++++++
 8 files changed, 923 insertions(+)
 create mode 100644 specs/011-specialist-baselining/checklists/requirements.md
 create mode 100644 specs/011-specialist-baselining/contracts/prompt-contracts.md
 create mode 100644 specs/011-specialist-baselining/data-model.md
 create mode 100644 specs/011-specialist-baselining/plan.md
 create mode 100644 specs/011-specialist-baselining/quickstart.md
 create mode 100644 specs/011-specialist-baselining/research.md
 create mode 100644 specs/011-specialist-baselining/spec.md
 create mode 100644 specs/011-specialist-baselining/tasks.md

diff --git a/specs/011-specialist-baselining/checklists/requirements.md b/specs/011-specialist-baselining/checklists/requirements.md
new file mode 100644
index 0000000..e4a121c
--- /dev/null
+++ b/specs/011-specialist-baselining/checklists/requirements.md
@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Specialist Historical Baselining
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-03-10
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Spec references specific tool names (`pcp_detect_anomalies`, `pcp_fetch_timeseries`) which are domain-specific terminology in this project context, not implementation details — these are the user-facing MCP tool names that the LLM agent invokes.
+- The spec references specific file paths in the Scope section, which is acceptable for a purely prompt-engineering feature where the scope is narrow and well-defined.
+- All items pass. Spec is ready for `/speckit.plan`.
+- Clarification session 2026-03-10: 4 questions asked and resolved (severity_despite_baseline, ranking order, RECURRING detection, cross-cutting scope).
diff --git a/specs/011-specialist-baselining/contracts/prompt-contracts.md b/specs/011-specialist-baselining/contracts/prompt-contracts.md
new file mode 100644
index 0000000..87f1b48
--- /dev/null
+++ b/specs/011-specialist-baselining/contracts/prompt-contracts.md
@@ -0,0 +1,56 @@
+# Prompt Contracts: Specialist Historical Baselining
+
+**Feature**: 011-specialist-baselining | **Date**: 2026-03-10
+
+## Contract: No Interface Changes
+
+This feature makes **zero changes** to function signatures or MCP protocol surface.
+
+### specialist_investigate (UNCHANGED)
+
+```python
+def specialist_investigate(
+    subsystem: str,
+    request: str | None = None,
+    host: str | None = None,
+    time_of_interest: str | None = None,
+    lookback: str | None = None,
+) -> list[dict]:
+```
+
+- Parameters: unchanged
+- Return type: `list[dict]` — unchanged
+- MCP registration: unchanged
+
+### coordinate_investigation (UNCHANGED)
+
+```python
+def coordinate_investigation(
+    request: str,
+    host: str | None = None,
+    time_of_interest: str | None = None,
+    lookback: str | None = None,
+) -> list[dict]:
+```
+
+- Parameters: unchanged
+- Return type: `list[dict]` — unchanged
+- MCP registration: unchanged
+
+## Content Contracts (Unit Test Assertions)
+
+Since no interfaces change, the "contracts" for this feature are content assertions verified in unit tests:
+
+| Contract | Verified By |
+|----------|------------|
+| Domain specialists (5) include Baseline step | String assertion: "Baseline" in workflow for cpu, memory, disk, network, process |
+| Cross-cutting does NOT include Baseline step | String assertion: "Baseline" NOT in cross-cutting workflow |
+| Classification fields in report guidance | String assertion: "classification", "ANOMALY", "RECURRING", "BASELINE" |
+| `baseline_context` in report guidance | String assertion: "baseline_context" |
+| `severity_despite_baseline` in report guidance | String assertion: "severity_despite_baseline" |
+| Coordinator ranks by classification | String assertion: "ANOMALY" ranking guidance in synthesis |
+| Graceful degradation | String assertion: "insufficient baseline" or fallback in prompt |
+
+## Existing Contract Tests (UNCHANGED)
+
+The existing contract tests in `tests/contract/test_prompts.py` continue to pass unchanged — they verify prompt registration and argument schemas, which are not modified.
diff --git a/specs/011-specialist-baselining/data-model.md b/specs/011-specialist-baselining/data-model.md
new file mode 100644
index 0000000..b880c01
--- /dev/null
+++ b/specs/011-specialist-baselining/data-model.md
@@ -0,0 +1,42 @@
+# Data Model: Specialist Historical Baselining
+
+**Feature**: 011-specialist-baselining | **Date**: 2026-03-10
+
+## Overview
+
+This feature adds no new Pydantic models or database entities. All changes are to prompt text templates that guide LLM behaviour. The "data model" here describes the report structure fields added to prompt output guidance.
+
+## Report Structure Fields (Prompt-Guided)
+
+These fields are instructed in the specialist report guidance — the LLM produces them as structured text. They are NOT enforced by code; they are advisory prompt instructions.
+
+### Finding Classification
+
+| Field | Type (advisory) | Values | Description |
+|-------|-----------------|--------|-------------|
+| `classification` | enum string | ANOMALY, RECURRING, BASELINE | Whether the finding is new (anomaly), a known periodic pattern, or normal baseline behaviour |
+| `baseline_context` | free text | — | Human-readable comparison to the 7-day baseline (e.g., "CPU idle has been below 15% for the past 7 days") |
+| `severity_despite_baseline` | enum string | critical, warning, info, none | Threshold-based severity independent of classification. A BASELINE finding with severity=warning means "your normal is degraded" |
+
+### Classification Decision Rules (LLM Heuristics)
+
+| Classification | Condition |
+|---------------|-----------|
+| ANOMALY | `pcp_detect_anomalies` reports significant z-score AND pattern does not recur at consistent times in the 7-day timeseries |
+| RECURRING | 7-day timeseries shows repeated spikes at consistent times of day (batch jobs, log rotation, backups, cron jobs) |
+| BASELINE | Current values are within normal range based on 7-day history (low z-score or no anomaly detected) |
+
+### Coordinator Ranking Order
+
+| Priority | Classification | Severity Sort |
+|----------|---------------|---------------|
+| 1 (highest) | ANOMALY | critical → warning → info |
+| 2 | RECURRING | critical → warning → info |
+| 3 (lowest) | BASELINE | critical → warning → info |
+
+## Existing Entities (Unchanged)
+
+- `_SPECIALIST_KNOWLEDGE` dict in `specialist.py` — keys: `prefix`, `display_name`, `domain_knowledge`, `report_guidance`. Structure unchanged; content updated.
+- `_specialist_investigate_impl()` signature — unchanged (subsystem, request, host, time_of_interest, lookback)
+- `_coordinate_investigation_impl()` signature — unchanged (request, host, time_of_interest, lookback)
+- `pcp_detect_anomalies` tool — unchanged (metrics, recent_start, recent_end, baseline_start, baseline_end, z_score_threshold, host, interval)
diff --git a/specs/011-specialist-baselining/plan.md b/specs/011-specialist-baselining/plan.md
new file mode 100644
index 0000000..41dfd6d
--- /dev/null
+++ b/specs/011-specialist-baselining/plan.md
@@ -0,0 +1,206 @@
+# Implementation Plan: Specialist Historical Baselining
+
+**Branch**: `011-specialist-baselining` | **Date**: 2026-03-10 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/011-specialist-baselining/spec.md`
+
+## Summary
+
+Add 7-day historical baselining to domain specialist prompts so each finding is classified as ANOMALY, RECURRING, or BASELINE. This eliminates false alarms on known patterns (daily batch jobs, normal working-set growth) by inserting a Baseline step between Discover and Fetch in each specialist's workflow. The coordinator synthesis phase ranks anomalies above baseline/recurring findings. This is purely prompt engineering — no new tools, no new dependencies, no API changes.
+
+## Technical Context
+
+**Language/Version**: Python 3.11+
+**Primary Dependencies**: `mcp[cli]` ≥1.2.0 (FastMCP), `pydantic` v2.x — no new dependencies
+**Storage**: N/A — prompts are stateless text generators
+**Testing**: pytest + pytest-asyncio, unit tests asserting prompt output content
+**Target Platform**: MCP server (stdio JSON-RPC)
+**Project Type**: Single project
+**Performance Goals**: N/A — prompt rendering is synchronous string interpolation
+**Constraints**: No changes to tool signatures or MCP protocol surface
+**Scale/Scope**: 3 files modified (specialist.py, coordinator.py, investigation-flow.md), ~200 lines of prompt text added
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes / Justification |
+|-----------|--------|----------------------|
+| I. Code Quality — linting enforced, single-responsibility, complexity ≤ 10, peer review, documentation impact reviewed | PASS | Pure text additions to existing prompt modules. No new functions, no complexity increase. Ruff enforced. Docs impact: `docs/investigation-flow.md` (workflow diagram update), `README.md` prompt table (no signature changes, but specialist workflow description needs update). |
+| II. Testing Standards — TDD cycle, ≥ 80% unit coverage, contract tests on interface changes | PASS | TDD: write tests asserting baseline/classification presence → implement prompt changes → green. No interface changes (same function signatures). Coverage ≥80% maintained. |
+| III. UX Consistency — design system adherence, WCAG 2.1 AA, actionable error messages | N/A | No user-facing UI. Prompt text follows existing specialist output patterns. |
+| IV. Performance — latency SLA defined, performance budget in CI, profiling before optimization | N/A | No runtime performance impact — prompt rendering is string interpolation. The additional 7-day fetch is an LLM-executed action, not our code. |
+| V. Simplicity — YAGNI posture, no speculative abstractions, complexity justified below | PASS | No new abstractions. Classification is LLM judgement guided by prompt text. No new tools, no periodicity detection, no configuration — YAGNI respected. |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/011-specialist-baselining/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output (report structure)
+├── quickstart.md        # Phase 1 output
+└── tasks.md             # Phase 2 output (/speckit.tasks)
+```
+
+### Source Code (files modified)
+
+```text
+src/pmmcp/prompts/
+├── specialist.py        # Add Baseline step, classification, domain heuristics
+└── coordinator.py       # Add classification-based ranking in synthesis
+
+docs/
+└── investigation-flow.md  # Update workflow diagram to 5-step flow
+
+tests/unit/
+├── test_prompts_specialist.py  # New assertions for baseline/classification
+└── test_prompts_coordinator.py # New assertions for classification ranking
+```
+
+**Structure Decision**: Existing single-project layout. All changes are modifications to existing files — no new modules created.
+
+## Complexity Tracking
+
+> No violations. All changes are additive text within existing modules.
+
+---
+
+## Design: Changes by File
+
+### 1. `src/pmmcp/prompts/specialist.py`
+
+#### 1a. Workflow: Insert Baseline Step (Step 2)
+
+Current 4-step workflow becomes 5 steps: **Discover → Baseline → Fetch → Analyse → Report**
+
+The Baseline step (for all 5 domain specialists, NOT cross-cutting) instructs the agent to:
+
+1. Fetch 7-day historical data at 1hour interval using `pcp_fetch_timeseries` for the discovered metrics
+2. Run `pcp_detect_anomalies` comparing the investigation window against the 7-day baseline
+3. Note anomaly detection results for use in the Analyse step
+4. If `pcp_detect_anomalies` returns insufficient data or errors, note the limitation and proceed with threshold-only analysis
+
+#### 1b. Report Structure: Add Classification Fields
+
+Each finding in the specialist report gains three new fields:
+
+- `classification`: ANOMALY | RECURRING | BASELINE
+- `baseline_context`: human-readable comparison (e.g., "CPU idle has been below 15% for the past 7 days")
+- `severity_despite_baseline`: threshold-based severity independent of classification (critical/warning/info/none)
+
+Report guidance instructs the agent to:
+- Articulate chronic problems narratively ("this is bad, but based on previous days this is not a new problem")
+- Distinguish RECURRING from BASELINE by examining timeseries shape for time-of-day correlation
+
+#### 1c. Domain Knowledge: Add Baseline-Aware Heuristics
+
+Each subsystem gets at least one baseline-aware heuristic:
+
+- **CPU**: Check whether current CPU levels are typical for this time of day over the past week before flagging saturation
+- **Memory**: Compare memory growth against 7-day baseline to distinguish leaks from normal working-set growth
+- **Disk**: Check whether I/O spikes recur at the same time daily (scheduled jobs like backups, log rotation)
+- **Network**: Check whether current packet drop rate is within normal variance for this interface over the past week
+- **Process**: Check whether process count and context switch rate match the 7-day pattern before flagging runaway processes
+
+#### 1d. Cross-Cutting: Classification Consumption (No Baseline Step)
+
+Cross-cutting domain knowledge updated to:
+- Prioritise ANOMALY-classified findings over RECURRING or BASELINE
+- Flag correlated anomalies across multiple subsystems at the same timestamp
+- Note when one subsystem reports BASELINE while another reports ANOMALY (the anomaly is more likely root cause)
+
+#### 1e. Graceful Degradation
+
+The Baseline step includes fallback instructions:
+- If `pcp_detect_anomalies` returns insufficient data: fall back to threshold-only analysis
+- Note "insufficient baseline data, falling back to threshold-only analysis" in the report
+- If baseline data exists but is sparse: attempt anomaly detection but note reduced confidence
+- If 0 days of history: skip Baseline step entirely, proceed with threshold-only Fetch → Analyse → Report
+
+### 2. `src/pmmcp/prompts/coordinator.py`
+
+#### 2a. Synthesis Phase: Classification-Based Ranking
+
+Update the synthesis section to:
+- Always rank ANOMALY findings above BASELINE/RECURRING regardless of severity
+- Within each classification tier, sort by severity (critical → warning → info)
+- Explicitly call out findings that are normal behaviour for the host
+- Highlight when an apparent anomaly matches a known recurring pattern
+
+#### 2b. Output Structure Update
+
+The "Findings by Severity" section becomes "Findings by Classification & Severity":
+
+```
+## Findings by Classification & Severity
+
+### New Anomalies (changed from baseline)
+1. [CRITICAL] ...
+2. [WARNING] ...
+
+### Recurring Patterns (known periodic behaviour)
+1. ...
+
+### Baseline Behaviour (chronic conditions)
+1. [WARNING] ... (your normal is degraded — here's context)
+
+### Normal Operation
+- No anomalies detected for: [subsystems]
+```
+
+### 3. `docs/investigation-flow.md`
+
+Update the specialist workflow diagram from 4-step to 5-step:
+- Discover → **Baseline** → Fetch → Analyse → Report
+- Note that cross-cutting does NOT include the Baseline step
+- Update the prompt table if it references specialist workflow steps
+
+## Test Strategy
+
+All tests are unit tests asserting prompt output string content — same pattern as existing tests.
+
+### Specialist Tests (Story 1 + 2 + 5)
+
+| Test | Asserts |
+|------|---------|
+| Baseline step present for all 5 domain subsystems | "Baseline" in workflow, `pcp_detect_anomalies` referenced |
+| Baseline step absent for cross-cutting | "Baseline" NOT in cross-cutting workflow |
+| Classification fields in report structure | "classification", "ANOMALY", "RECURRING", "BASELINE" in report guidance |
+| `baseline_context` in report structure | "baseline_context" in report guidance |
+| `severity_despite_baseline` in report structure | "severity_despite_baseline" in report guidance |
+| Domain heuristics reference baseline | Each subsystem has at least one baseline-aware heuristic |
+| Graceful degradation instructions present | "insufficient baseline" or fallback guidance in prompt |
+| 7-day window referenced | "7-day" or "7 day" in baseline instructions |
+| `pcp_fetch_timeseries` referenced in baseline | Tool name appears in baseline step |
+
+### Cross-Cutting Tests (Story 3)
+
+| Test | Asserts |
+|------|---------|
+| Classification prioritisation in domain knowledge | "ANOMALY" prioritised over "RECURRING"/"BASELINE" |
+| Correlated anomaly detection guidance | Cross-subsystem correlation referenced |
+| Mixed classification guidance | Guidance for BASELINE + ANOMALY across subsystems |
+
+### Coordinator Tests (Story 4)
+
+| Test | Asserts |
+|------|---------|
+| Classification ranking in synthesis | "ANOMALY" ranked above "BASELINE"/"RECURRING" |
+| Baseline behaviour call-out | Normal behaviour explicitly mentioned |
+| Recurring pattern highlighting | Pattern matching guidance present |
+
+## Implementation Order
+
+Stories are independent enough for parallel implementation in worktrees:
+
+**Worktree A**: Stories 1 + 2 + 5 (specialist.py changes + specialist tests)
+- These are tightly coupled — baseline step, domain heuristics, and degradation are all in the same `_SPECIALIST_KNOWLEDGE` dict and workflow template
+
+**Worktree B**: Story 3 + 4 (cross-cutting + coordinator changes + tests)
+- Cross-cutting domain knowledge update + coordinator synthesis update + their tests
+
+**Final merge**: Story 3+4 depends on Story 1+2 classification fields existing, but since they're prompt text (not runtime dependencies), the tests can assert independently. Merge worktree A first, then worktree B.
+
+**Docs** (investigation-flow.md): Can be done in either worktree or main branch after merge.
diff --git a/specs/011-specialist-baselining/quickstart.md b/specs/011-specialist-baselining/quickstart.md
new file mode 100644
index 0000000..79808d2
--- /dev/null
+++ b/specs/011-specialist-baselining/quickstart.md
@@ -0,0 +1,44 @@
+# Quickstart: Specialist Historical Baselining
+
+**Feature**: 011-specialist-baselining | **Date**: 2026-03-10
+
+## What Changed
+
+Domain specialist prompts now include a **Baseline step** that instructs the investigating agent to fetch 7-day historical data and classify each finding as ANOMALY, RECURRING, or BASELINE. The coordinator ranks anomalies above baseline behaviour in its synthesis.
+
+## Verify It Works
+
+```bash
+# Run all tests (baseline assertions included)
+uv run pytest tests/unit/test_prompts_specialist.py tests/unit/test_prompts_coordinator.py -v
+
+# Full suite with coverage
+uv run pytest --cov=pmmcp --cov-report=term-missing
+```
+
+## Key Files
+
+| File | Change |
+|------|--------|
+| `src/pmmcp/prompts/specialist.py` | Baseline step, classification fields, baseline-aware heuristics, graceful degradation |
+| `src/pmmcp/prompts/coordinator.py` | Classification-based ranking in synthesis phase |
+| `docs/investigation-flow.md` | 5-step workflow diagram |
+| `tests/unit/test_prompts_specialist.py` | Baseline/classification presence assertions |
+| `tests/unit/test_prompts_coordinator.py` | Classification ranking assertions |
+
+## How Classification Works
+
+The specialist prompt instructs the agent to:
+1. **Baseline step**: Fetch 7-day history at 1hour interval, run `pcp_detect_anomalies`
+2. **Classify each finding**:
+   - **ANOMALY**: Significant deviation from baseline, not a recurring pattern
+   - **RECURRING**: Spikes that repeat at the same time of day (batch jobs, backups)
+   - **BASELINE**: Normal behaviour for this host
+3. **Severity despite baseline**: A finding can be BASELINE and still critical (chronic degradation)
+
+## Impact on Existing Prompts
+
+- **No signature changes** — `specialist_investigate` and `coordinate_investigation` accept the same parameters
+- **No tool changes** — `pcp_detect_anomalies`, `pcp_quick_investigate`, etc. are unchanged
+- **No new dependencies** — pure prompt text additions
+- **Cross-cutting specialist** does NOT get a Baseline step — it consumes classifications from domain specialists
diff --git a/specs/011-specialist-baselining/research.md b/specs/011-specialist-baselining/research.md
new file mode 100644
index 0000000..dc5028e
--- /dev/null
+++ b/specs/011-specialist-baselining/research.md
@@ -0,0 +1,88 @@
+# Research: Specialist Historical Baselining
+
+**Feature**: 011-specialist-baselining | **Date**: 2026-03-10
+
+## Research Tasks & Findings
+
+### R1: How does `pcp_detect_anomalies` work and what does it return?
+
+**Decision**: Use the existing `pcp_detect_anomalies` tool as-is — no modifications needed.
+
+**Findings**:
+- Signature: `(metrics, recent_start, recent_end, baseline_start, baseline_end, z_score_threshold=2.0, host="", interval="auto")`
+- Returns `list[dict]` with: `metric`, `severity` (critical/warning/info/none), `z_score`, `direction` (higher/lower), `recent_mean`, `recent_stddev`, `baseline_mean`, `baseline_stddev`
+- Z-score calculation: `(recent_mean - baseline_mean) / baseline_stddev`
+- Already handles the statistical comparison between two time windows
+
+**Rationale**: The tool already accepts arbitrary time windows. The Baseline step just needs to instruct the agent to call it with a 7-day baseline window.
+
+### R2: How should the Baseline step be structured in the workflow?
+
+**Decision**: Insert Baseline as step 2 in the specialist workflow (Discover → **Baseline** → Fetch → Analyse → Report).
+
+**Findings**:
+- Current workflow is 4 steps: Discover → Fetch → Analyse → Report
+- The Baseline step needs to come after Discover (so we know what metrics exist) but before Fetch (so the live data fetch can be informed by baseline context)
+- The Baseline step instructs the agent to:
+  1. Fetch 7-day historical data at 1hour interval using `pcp_fetch_timeseries`
+  2. Run `pcp_detect_anomalies` comparing investigation window against 7-day baseline
+  3. Note anomaly results for use in the Analyse step
+
+**Alternatives considered**:
+- Baseline after Fetch: Rejected — agent benefits from knowing baseline context before interpreting live data
+- Baseline merged into Analyse: Rejected — separating concerns keeps each step focused
+
+### R3: How should classification (ANOMALY/RECURRING/BASELINE) be assigned?
+
+**Decision**: LLM judgement guided by prompt heuristics — no new tool required.
+
+**Findings**:
+- ANOMALY: `pcp_detect_anomalies` returns a significant z-score and the pattern doesn't recur in the 7-day timeseries
+- RECURRING: 7-day timeseries shows repeated spikes at consistent times of day (batch jobs, log rotation, backups)
+- BASELINE: Current values are within normal range for this host based on the 7-day history
+- The specialist examines timeseries shape for time-of-day correlation
+
+**Rationale**: Domain knowledge already references daily patterns. LLM is well-suited to pattern recognition in timeseries shapes described textually. A dedicated periodicity tool would be over-engineering for this iteration.
+
+### R4: How should `severity_despite_baseline` work?
+
+**Decision**: Independent field that carries threshold-based severity regardless of classification.
+
+**Findings**:
+- A finding can be BASELINE (normal for this host) but still severity=warning/critical (thresholds exceeded)
+- This captures the "your normal is sick" scenario — e.g., CPU idle consistently < 10% for a week
+- The specialist articulates this narratively: "this is bad, but based on previous days this is not a new problem"
+
+**Alternatives considered**:
+- Merge severity into classification: Rejected — conflates "is this new?" with "is this bad?"
+- Separate classification and severity tools: Rejected — over-engineering; the LLM assigns both from the same data
+
+### R5: Cross-cutting specialist — baseline step or not?
+
+**Decision**: No baseline step for cross-cutting. It consumes classifications from domain specialists.
+
+**Findings**:
+- Cross-cutting already runs `pcp_quick_investigate` for broad anomaly scanning
+- Adding a baseline step would duplicate domain specialists' work
+- Cross-cutting's role is correlation, not independent metric analysis
+- It receives classification data through domain specialist reports and uses it for prioritisation
+
+### R6: Graceful degradation approach
+
+**Decision**: Prompt-level fallback instructions — no code changes needed.
+
+**Findings**:
+- When `pcp_detect_anomalies` returns insufficient data (few or no results), the specialist falls back to threshold-only analysis
+- The specialist notes the limitation in its report: "insufficient baseline data, falling back to threshold-only analysis"
+- Common causes: new host, recent PCP deployment, archive gaps
+- Sparse data (gaps from PCP restarts) still produces results but with reduced confidence — specialist notes this
+
+### R7: Coordinator classification ranking
+
+**Decision**: ANOMALY always ranks above BASELINE/RECURRING, regardless of severity. Severity is secondary sort within each tier.
+
+**Findings**:
+- "What changed" is more actionable than "what's chronically wrong"
+- Chronic issues (BASELINE with severity warning/critical) are still reported, just after anomalies
+- Coordinator synthesis explicitly calls out baseline behaviour to reduce noise
+- Highlights when an apparent anomaly matches a known recurring pattern
diff --git a/specs/011-specialist-baselining/spec.md b/specs/011-specialist-baselining/spec.md
new file mode 100644
index 0000000..d5ea6be
--- /dev/null
+++ b/specs/011-specialist-baselining/spec.md
@@ -0,0 +1,160 @@
+# Feature Specification: Specialist Historical Baselining
+
+**Feature Branch**: `011-specialist-baselining`
+**Created**: 2026-03-10
+**Status**: Draft
+**Input**: User description: "Specialists should baseline against historical data to distinguish anomalies from normal behaviour"
+**GitHub Issue**: #30
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - Specialist findings include anomaly classification (Priority: P1)
+
+When a performance investigation runs, each domain specialist (CPU, Memory, Disk, Network, Process) fetches a 7-day historical baseline for its key metrics and classifies every finding as ANOMALY, RECURRING, or BASELINE. This prevents false alarms on known patterns like daily batch jobs or normal working-set growth.
+
+**Why this priority**: This is the core value proposition — without classification, specialists cry wolf on business-as-usual behaviour, drowning the signal in noise.
+
+**Independent Test**: Invoke `specialist_investigate(subsystem="cpu")` and verify the prompt output includes instructions to fetch a 7-day baseline, run `pcp_detect_anomalies`, and classify each finding.
+
+**Acceptance Scenarios**:
+
+1. **Given** a specialist prompt for any domain subsystem, **When** the prompt is rendered, **Then** it includes a Baseline step between Discover and Fetch that instructs the agent to fetch 7-day historical data and run `pcp_detect_anomalies`.
+2. **Given** a specialist prompt for any domain subsystem, **When** the prompt is rendered, **Then** it includes instructions to classify each finding as ANOMALY, RECURRING, or BASELINE with baseline context.
+3. **Given** a specialist prompt for any domain subsystem, **When** the prompt is rendered, **Then** the report structure includes `classification`, `baseline_context`, and `severity_despite_baseline` fields.
+4. **Given** a specialist prompt for any domain subsystem, **When** the prompt is rendered, **Then** the report guidance instructs the agent to articulate chronic problems narratively (e.g., "this is bad, but based on previous days this is not a new problem — here's what I think is happening").
+
+---
+
+### User Story 2 - Domain knowledge augmented with baseline-aware guidance (Priority: P1)
+
+Each specialist's domain knowledge heuristics are updated to reference the baseline before making threshold-based judgements. For example, the CPU specialist checks whether current CPU levels are typical for this time of day before flagging saturation.
+
+**Why this priority**: Tied with Story 1 — the baseline step is useless if the domain heuristics still say "idle < 10% = saturated" without checking whether that's normal.
+
+**Independent Test**: Read the domain knowledge for each subsystem and verify at least one heuristic references the baseline or `pcp_detect_anomalies`.
+
+**Acceptance Scenarios**:
+
+1. **Given** the CPU specialist domain knowledge, **When** rendered, **Then** it includes guidance to check whether current CPU levels are typical for this time of day over the past week before flagging saturation.
+2. **Given** the Memory specialist domain knowledge, **When** rendered, **Then** it includes guidance to compare memory growth against the 7-day baseline to distinguish leaks from normal working-set growth.
+3. **Given** the Disk specialist domain knowledge, **When** rendered, **Then** it includes guidance to check whether I/O spikes recur at the same time daily (scheduled jobs like backups, log rotation).
+4. **Given** the Network and Process specialist domain knowledge, **When** rendered, **Then** each includes at least one baseline-aware heuristic.
+
+---
+
+### User Story 3 - Cross-cutting specialist prioritises by classification (Priority: P2)
+
+The cross-cutting specialist uses anomaly classifications from domain specialists to prioritise findings. ANOMALY-classified findings are prioritised over RECURRING or BASELINE. Correlated anomalies across multiple subsystems at the same timestamp receive higher confidence.
+
+**Why this priority**: Builds on P1 classifications to improve the cross-cutting correlator's signal-to-noise ratio.
+
+**Independent Test**: Render the cross-cutting specialist prompt and verify it references classification-based prioritisation and correlated anomaly detection.
+
+**Acceptance Scenarios**:
+
+1. **Given** the cross-cutting specialist domain knowledge, **When** rendered, **Then** it includes guidance to prioritise ANOMALY-classified findings over RECURRING or BASELINE.
+2. **Given** the cross-cutting specialist domain knowledge, **When** rendered, **Then** it includes guidance to flag correlated anomalies across multiple subsystems at the same timestamp.
+3. **Given** the cross-cutting specialist domain knowledge, **When** rendered, **Then** it includes guidance to note when one subsystem reports BASELINE while another reports ANOMALY.
+
+---
+
+### User Story 4 - Coordinator synthesis weights findings by classification (Priority: P2)
+
+The coordinator's synthesis phase leads with anomalies, explicitly calls out baseline behaviour to reduce noise, and highlights when an apparent anomaly matches a known recurring pattern.
+
+**Why this priority**: Final layer of the classification value chain — ensures the end-user report is noise-reduced.
+
+**Independent Test**: Render the `coordinate_investigation` prompt and verify the synthesis section references classification weighting.
+
+**Acceptance Scenarios**:
+
+1. **Given** the coordinator synthesis prompt, **When** rendered, **Then** it includes guidance to always rank ANOMALY findings above BASELINE/RECURRING regardless of severity, with severity as secondary sort within each tier.
+2. **Given** the coordinator synthesis prompt, **When** rendered, **Then** it includes guidance to explicitly call out findings that are normal behaviour for the host.
+3. **Given** the coordinator synthesis prompt, **When** rendered, **Then** it includes guidance to highlight when an apparent anomaly matches a known recurring pattern.
+
+---
+
+### User Story 5 - Graceful degradation when baseline data is insufficient (Priority: P2)
+
+When a host has less than 7 days of historical data (new host, recent PCP deployment, archive gaps), the specialist gracefully falls back to threshold-only analysis and notes the limitation.
+
+**Why this priority**: Without this, the baseline step would fail or produce misleading results on hosts with limited history.
+
+**Independent Test**: Verify the specialist prompt includes fallback guidance for insufficient baseline data.
+
+**Acceptance Scenarios**:
+
+1. **Given** a specialist prompt, **When** rendered, **Then** it includes instructions to fall back to threshold-only analysis if `pcp_detect_anomalies` returns insufficient data.
+2. **Given** a specialist prompt, **When** rendered, **Then** it includes instructions to note "insufficient baseline data, falling back to threshold-only analysis" in the report when degraded.
+
+---
+
+### Edge Cases
+
+- What happens when the host has exactly 0 days of historical data? Specialist falls back entirely to threshold-based analysis with a clear note.
+- What happens when baseline data exists but is sparse (e.g., gaps due to PCP restarts)? Specialist should still attempt anomaly detection but note reduced confidence.
+- What happens when the 7-day baseline itself is anomalous (e.g., host was under sustained incident for a week)? The classification should still flag current behaviour relative to the available baseline — the specialist cannot know the baseline is "wrong" but the report should note the baseline window.
+- What happens when `pcp_detect_anomalies` returns no anomalies? The specialist should report "no anomalies detected relative to 7-day baseline" — this is a valid finding.
+
+## Clarifications
+
+### Session 2026-03-10
+
+- Q: Should BASELINE classification distinguish "normal and healthy" from "normal but degraded"? → A: Keep three classifications (ANOMALY / RECURRING / BASELINE) but add a `severity_despite_baseline` field. A finding can be BASELINE and still carry a severity (warning/critical) based on thresholds. This lets the agent articulate "this is your normal, but your normal is sick."
+- Q: How should coordinator rank ANOMALY vs BASELINE findings when severity differs? → A: ANOMALY always ranks above BASELINE/RECURRING regardless of severity. "What changed" is more actionable than "what's chronically wrong." Chronic issues are still reported but after new anomalies.
+- Q: How should specialists distinguish RECURRING from BASELINE without a periodicity-detection tool? → A: LLM judgement guided by prompt heuristics. The specialist examines the 7-day timeseries shape for time-of-day correlation (repeated spikes at the same hour). Domain knowledge already references daily patterns (batch jobs, log rotation, backups). No new tooling needed.
+- Q: Should the cross-cutting specialist get its own baseline step? → A: No. Cross-cutting consumes and correlates classifications from the 5 domain specialists only. It already runs `pcp_quick_investigate` for broad anomaly scanning — adding a baseline step would duplicate the domain specialists' work.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+- **FR-001**: Each domain specialist prompt (cpu, memory, disk, network, process) MUST include a Baseline step in its workflow between Discover and Fetch. The cross-cutting specialist does NOT get a Baseline step — it consumes and correlates classifications from domain specialists.
+- **FR-002**: The Baseline step MUST instruct the agent to fetch 7-day historical data at a coarse interval (e.g., 1hour) using `pcp_fetch_timeseries`.
+- **FR-003**: The Baseline step MUST instruct the agent to run `pcp_detect_anomalies` comparing the investigation window against the 7-day baseline.
+- **FR-004**: The specialist report structure MUST include a `classification` field with values: ANOMALY, RECURRING, or BASELINE. RECURRING is assigned by LLM judgement when the 7-day timeseries shows repeated spikes at consistent times of day — guided by domain heuristics (batch jobs, log rotation, backups). No dedicated periodicity-detection tool is required.
+- **FR-005**: The specialist report structure MUST include a `baseline_context` field providing human-readable comparison to the baseline.
+- **FR-005a**: The specialist report structure MUST include a `severity_despite_baseline` field that carries the threshold-based severity (critical/warning/info/none) independently of classification. A BASELINE-classified finding with severity warning or critical indicates a chronic problem — "this is your normal, but your normal is degraded."
+- **FR-006**: Each domain specialist's domain knowledge MUST include at least one baseline-aware heuristic relevant to its subsystem.
+- **FR-007**: The cross-cutting specialist domain knowledge MUST reference anomaly classification for prioritisation and correlation.
+- **FR-008**: The coordinator synthesis phase MUST rank findings with ANOMALY classification above BASELINE/RECURRING regardless of severity. Within each classification tier, findings are sorted by severity (critical → warning → info). Chronic issues (BASELINE/RECURRING with non-zero severity) MUST still be reported, but after anomalies.
+- **FR-009**: The specialist prompt MUST include graceful degradation instructions for insufficient baseline data.
+- **FR-010**: The investigation flow documentation MUST be updated to reflect the 5-step specialist workflow (Discover → Baseline → Fetch → Analyse → Report).
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: All 5 domain specialist prompts include the Baseline step referencing `pcp_detect_anomalies` in their workflow.
+- **SC-002**: All 5 domain specialist prompts include the classification field (ANOMALY / RECURRING / BASELINE), baseline_context, and severity_despite_baseline in their report structure.
+- **SC-003**: All 5 domain specialist domain knowledge sections include at least one baseline-aware heuristic.
+- **SC-004**: Cross-cutting specialist references classification-based prioritisation in its domain knowledge.
+- **SC-005**: Coordinator synthesis phase references classification weighting.
+- **SC-006**: Specialist prompts include fallback guidance for insufficient baseline data.
+- **SC-007**: Investigation flow diagram shows 5-step workflow (Discover → Baseline → Fetch → Analyse → Report).
+- **SC-008**: All unit tests pass, including new tests verifying baseline step and classification presence in prompt output.
+
+## Assumptions
+
+- The 7-day baseline window is a fixed default — not user-configurable in this iteration. This covers daily and weekly recurring patterns, which are the most common. Configurability can be added later if needed.
+- The `pcp_detect_anomalies` tool already handles the statistical comparison (z-score based) and does not need modification.
+- The `pcp_compare_windows` and `pcp_quick_investigate` tools do not need modification — this feature is purely prompt engineering.
+- The classification is advisory — the LLM agent interprets the anomaly detection results and assigns the classification. There is no new tool that automatically classifies.
+- Performance impact of the additional baseline fetch is acceptable — the 7-day fetch at 1hour interval is a modest data volume.
+- This feature does not change the specialist prompt's function signature — no new parameters are added.
+
+## Scope
+
+### In scope
+
+- Modifications to `src/pmmcp/prompts/specialist.py` (workflow, domain knowledge, report structure)
+- Modifications to `src/pmmcp/prompts/coordinator.py` (synthesis guidance)
+- Updates to `docs/investigation-flow.md` (workflow diagram)
+- Unit tests for prompt output verification
+
+### Not in scope
+
+- Changes to existing tools (`pcp_detect_anomalies`, `pcp_compare_windows`, `pcp_quick_investigate`)
+- New tool development
+- Making the baseline window configurable
+- Changing the `lookback` parameter semantics
diff --git a/specs/011-specialist-baselining/tasks.md b/specs/011-specialist-baselining/tasks.md
new file mode 100644
index 0000000..9031ab5
--- /dev/null
+++ b/specs/011-specialist-baselining/tasks.md
@@ -0,0 +1,290 @@
+# Tasks: Specialist Historical Baselining
+
+**Input**: Design documents from `/specs/011-specialist-baselining/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Per the project constitution (Principle II — Testing Standards, NON-NEGOTIABLE), tests
+are mandatory. Unit coverage MUST reach ≥ 80% and contract tests MUST accompany any interface
+change. TDD cycle: write failing tests → implement → refactor.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: No new dependencies or project structure changes. This feature is purely prompt text modifications to existing files.
+
+- [x] T001 Verify existing tests pass and baseline coverage in `tests/unit/test_prompts_specialist.py` and `tests/unit/test_prompts_coordinator.py` by running `uv run pytest tests/unit/test_prompts_specialist.py tests/unit/test_prompts_coordinator.py --cov=pmmcp.prompts -v`
+
+**Checkpoint**: Green baseline confirmed — all existing prompt tests pass, coverage baseline recorded.
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: No foundational/blocking prerequisites for this feature. All changes are additive text to existing prompt modules. User story phases can begin immediately after Phase 1 confirmation.
+
+---
+
+## Phase 3: User Story 1 — Specialist findings include anomaly classification (Priority: P1) MVP
+
+**Goal**: Insert a Baseline step (step 2) into the 5 domain specialist workflows and add classification/baseline_context/severity_despite_baseline fields to the report structure. Cross-cutting does NOT get a Baseline step.
+
+**Independent Test**: Invoke `_specialist_investigate_impl(subsystem="cpu")` and verify the prompt output includes instructions to fetch a 7-day baseline, run `pcp_detect_anomalies`, and classify each finding.
+
+**Worktree**: A (specialist.py changes — shares worktree with US2 and US5)
+
+### Tests for User Story 1 *(required per Principle II — Testing Standards)*
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation (Red-Green-Refactor)**
+
+- [x] T002 [US1] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl()` output for each of the 5 domain subsystems (cpu, memory, disk, network, process) contains a "Baseline" step between Discover and Fetch that references `pcp_fetch_timeseries` and `pcp_detect_anomalies` and a "7-day" or "7 day" baseline window
+- [x] T003 [US1] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl(subsystem="crosscutting")` output does NOT contain a "Baseline" step (cross-cutting consumes classifications, it doesn't baseline independently)
+- [x] T004 [US1] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl()` output for each of the 5 domain subsystems includes `classification`, `ANOMALY`, `RECURRING`, `BASELINE`, `baseline_context`, and `severity_despite_baseline` in the report structure guidance
+- [x] T005 [US1] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl()` output for domain subsystems includes narrative guidance for chronic problems (e.g., references to "not a new problem" or "your normal" or similar phrasing that instructs the agent to contextualise baseline-classified findings)
+- [x] T006 [US1] Run tests and confirm they FAIL (RED): `uv run pytest tests/unit/test_prompts_specialist.py -v -k "baseline or classification"` — commit failing tests
+
+### Implementation for User Story 1
+
+- [x] T007 [US1] In `src/pmmcp/prompts/specialist.py`, add a Baseline step (step 2) to the specialist workflow template for domain subsystems only (cpu, memory, disk, network, process). The step instructs the agent to: (1) fetch 7-day historical data at 1hour interval using `pcp_fetch_timeseries`, (2) run `pcp_detect_anomalies` comparing investigation window against 7-day baseline, (3) note results for the Analyse step. Cross-cutting workflow remains unchanged (4 steps).
+- [x] T008 [US1] In `src/pmmcp/prompts/specialist.py`, update the report structure/guidance for domain subsystems to include three new fields: `classification` (ANOMALY/RECURRING/BASELINE), `baseline_context` (human-readable comparison), `severity_despite_baseline` (threshold severity independent of classification). Add narrative guidance for RECURRING detection (time-of-day correlation in 7-day timeseries) and chronic problem articulation.
+- [x] T009 [US1] Run tests and confirm they PASS (GREEN): `uv run pytest tests/unit/test_prompts_specialist.py -v` — commit implementation
+
+**Checkpoint**: Domain specialist prompts now include Baseline step and classification fields. Cross-cutting unchanged.
+
+---
+
+## Phase 4: User Story 2 — Domain knowledge augmented with baseline-aware guidance (Priority: P1)
+
+**Goal**: Add at least one baseline-aware heuristic to each domain specialist's domain knowledge section so threshold judgements reference the 7-day baseline before flagging.
+
+**Independent Test**: Read the domain knowledge for each subsystem and verify at least one heuristic references the baseline or `pcp_detect_anomalies`.
+
+**Worktree**: A (same worktree as US1 — same file, same data structure)
+
+### Tests for User Story 2 *(required per Principle II — Testing Standards)*
+
+- [x] T010 [US2] Write test in `tests/unit/test_prompts_specialist.py` asserting that the `_SPECIALIST_KNOWLEDGE` domain_knowledge for CPU contains guidance to check whether current CPU levels are typical for this time of day over the past week before flagging saturation
+- [x] T011 [US2] Write test in `tests/unit/test_prompts_specialist.py` asserting that the `_SPECIALIST_KNOWLEDGE` domain_knowledge for Memory contains guidance to compare memory growth against the 7-day baseline to distinguish leaks from normal working-set growth
+- [x] T012 [US2] Write test in `tests/unit/test_prompts_specialist.py` asserting that the `_SPECIALIST_KNOWLEDGE` domain_knowledge for Disk contains guidance to check whether I/O spikes recur at the same time daily (scheduled jobs)
+- [x] T013 [US2] Write test in `tests/unit/test_prompts_specialist.py` asserting that the `_SPECIALIST_KNOWLEDGE` domain_knowledge for Network and Process each contain at least one baseline-aware heuristic (referencing "baseline" or "7-day" or "past week" or similar)
+- [x] T014 [US2] Run tests and confirm they FAIL (RED): `uv run pytest tests/unit/test_prompts_specialist.py -v -k "baseline_heuristic or domain_knowledge_baseline"` — commit failing tests
+
+### Implementation for User Story 2
+
+- [x] T015 [US2] In `src/pmmcp/prompts/specialist.py`, add baseline-aware heuristic to CPU domain_knowledge: check whether current CPU levels are typical for this time of day over the past week before flagging saturation
+- [x] T016 [US2] In `src/pmmcp/prompts/specialist.py`, add baseline-aware heuristic to Memory domain_knowledge: compare memory growth against 7-day baseline to distinguish leaks from normal working-set growth
+- [x] T017 [US2] In `src/pmmcp/prompts/specialist.py`, add baseline-aware heuristic to Disk domain_knowledge: check whether I/O spikes recur at the same time daily (scheduled jobs like backups, log rotation)
+- [x] T018 [US2] In `src/pmmcp/prompts/specialist.py`, add baseline-aware heuristic to Network domain_knowledge: check whether current packet drop rate is within normal variance over the past week; and Process domain_knowledge: check whether process count and context switch rate match the 7-day pattern before flagging runaway processes
+- [x] T019 [US2] Run tests and confirm they PASS (GREEN): `uv run pytest tests/unit/test_prompts_specialist.py -v` — commit implementation
+
+**Checkpoint**: All 5 domain specialists have baseline-aware heuristics. Worktree A pre-push sanity check.
+
+---
+
+## Phase 5: User Story 5 — Graceful degradation when baseline data is insufficient (Priority: P2)
+
+**Goal**: Add fallback instructions to the Baseline step so specialists degrade gracefully when historical data is missing or sparse.
+
+**Independent Test**: Verify the specialist prompt includes fallback guidance for insufficient baseline data.
+
+**Worktree**: A (same worktree as US1/US2 — modifies the Baseline step text added in US1)
+
+> **Note**: US5 is prioritised before US3/US4 because it modifies the same Baseline step text from US1, and completing it in the same worktree avoids merge conflicts.
+
+### Tests for User Story 5 *(required per Principle II — Testing Standards)*
+
+- [x] T020 [US5] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl()` output for domain subsystems includes instructions to fall back to threshold-only analysis if `pcp_detect_anomalies` returns insufficient data
+- [x] T021 [US5] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl()` output for domain subsystems includes instructions to note "insufficient baseline" or similar limitation wording in the report when degraded
+- [x] T022 [US5] Run tests and confirm they FAIL (RED): `uv run pytest tests/unit/test_prompts_specialist.py -v -k "degradation or fallback or insufficient"` — commit failing tests
+
+### Implementation for User Story 5
+
+- [x] T023 [US5] In `src/pmmcp/prompts/specialist.py`, add graceful degradation instructions to the Baseline step: (1) if `pcp_detect_anomalies` returns insufficient data, fall back to threshold-only analysis; (2) note "insufficient baseline data, falling back to threshold-only analysis" in the report; (3) if data is sparse (gaps from restarts), attempt detection but note reduced confidence; (4) if 0 days of history, skip Baseline entirely
+- [x] T024 [US5] Run tests and confirm they PASS (GREEN): `uv run pytest tests/unit/test_prompts_specialist.py -v` — commit implementation
+- [x] T025 [US5] Run pre-push sanity for Worktree A: `scripts/pre-push-sanity.sh` — all lint, format, and tests must pass. Push Worktree A branch.
+
+**Checkpoint**: Worktree A complete (US1+US2+US5). All domain specialist prompt changes done. Merge to feature branch before starting Worktree B.
+
+---
+
+## Phase 6: User Story 3 — Cross-cutting specialist prioritises by classification (Priority: P2)
+
+**Goal**: Update cross-cutting specialist domain knowledge to prioritise ANOMALY-classified findings and flag correlated anomalies across subsystems.
+
+**Independent Test**: Render the cross-cutting specialist prompt and verify it references classification-based prioritisation and correlated anomaly detection.
+
+**Worktree**: B (cross-cutting + coordinator — separate from Worktree A)
+
+### Tests for User Story 3 *(required per Principle II — Testing Standards)*
+
+- [x] T026 [P] [US3] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl(subsystem="crosscutting")` output includes guidance to prioritise ANOMALY-classified findings over RECURRING or BASELINE
+- [x] T027 [P] [US3] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl(subsystem="crosscutting")` output includes guidance to flag correlated anomalies across multiple subsystems at the same timestamp
+- [x] T028 [P] [US3] Write test in `tests/unit/test_prompts_specialist.py` asserting that `_specialist_investigate_impl(subsystem="crosscutting")` output includes guidance to note when one subsystem reports BASELINE while another reports ANOMALY
+- [x] T029 [US3] Run tests and confirm they FAIL (RED): `uv run pytest tests/unit/test_prompts_specialist.py -v -k "crosscutting_classification or crosscutting_priorit"` — commit failing tests
+
+### Implementation for User Story 3
+
+- [x] T030 [US3] In `src/pmmcp/prompts/specialist.py`, update the crosscutting entry in `_SPECIALIST_KNOWLEDGE` domain_knowledge to: (1) prioritise ANOMALY findings over RECURRING/BASELINE, (2) flag correlated anomalies across subsystems at the same timestamp with higher confidence, (3) note when one subsystem reports BASELINE while another reports ANOMALY (the anomaly is more likely root cause)
+- [x] T031 [US3] Run tests and confirm they PASS (GREEN): `uv run pytest tests/unit/test_prompts_specialist.py -v` — commit implementation
+
+**Checkpoint**: Cross-cutting specialist now consumes and prioritises by classification.
+
+---
+
+## Phase 7: User Story 4 — Coordinator synthesis weights findings by classification (Priority: P2)
+
+**Goal**: Update coordinator synthesis phase to rank ANOMALY above BASELINE/RECURRING, call out baseline behaviour, and highlight recurring pattern matches.
+
+**Independent Test**: Render the `coordinate_investigation` prompt and verify the synthesis section references classification weighting.
+
+**Worktree**: B (same worktree as US3 — different file: coordinator.py)
+
+### Tests for User Story 4 *(required per Principle II — Testing Standards)*
+
+- [x] T032 [P] [US4] Write test in `tests/unit/test_prompts_coordinator.py` asserting that `_coordinate_investigation_impl()` output includes guidance to rank ANOMALY findings above BASELINE/RECURRING regardless of severity, with severity as secondary sort within each tier
+- [x] T033 [P] [US4] Write test in `tests/unit/test_prompts_coordinator.py` asserting that `_coordinate_investigation_impl()` output includes guidance to explicitly call out findings that are normal behaviour for the host
+- [x] T034 [P] [US4] Write test in `tests/unit/test_prompts_coordinator.py` asserting that `_coordinate_investigation_impl()` output includes guidance to highlight when an apparent anomaly matches a known recurring pattern
+- [x] T035 [US4] Run tests and confirm they FAIL (RED): `uv run pytest tests/unit/test_prompts_coordinator.py -v -k "classification_ranking or baseline_callout or recurring_pattern"` — commit failing tests
+
+### Implementation for User Story 4
+
+- [x] T036 [US4] In `src/pmmcp/prompts/coordinator.py`, update the synthesis section to: (1) rank ANOMALY above BASELINE/RECURRING regardless of severity, severity as secondary sort within each tier; (2) explicitly call out findings that are normal behaviour; (3) highlight when an apparent anomaly matches a known recurring pattern
+- [x] T037 [US4] In `src/pmmcp/prompts/coordinator.py`, update the output structure template from "Findings by Severity" to "Findings by Classification & Severity" with sections: New Anomalies, Recurring Patterns, Baseline Behaviour (chronic conditions), Normal Operation
+- [x] T038 [US4] Run tests and confirm they PASS (GREEN): `uv run pytest tests/unit/test_prompts_coordinator.py -v` — commit implementation
+- [x] T039 [US4] Run pre-push sanity for Worktree B: `scripts/pre-push-sanity.sh` — all lint, format, and tests must pass. Push Worktree B branch.
+
+**Checkpoint**: Worktree B complete (US3+US4). Merge to feature branch.
+
+---
+
+## Phase 8: Polish & Cross-Cutting Concerns
+
+**Purpose**: Documentation updates, final validation, cleanup.
+
+- [x] T040 [P] Update `docs/investigation-flow.md`: change specialist workflow diagram from 4-step to 5-step (Discover → Baseline → Fetch → Analyse → Report), note cross-cutting does NOT include Baseline step, update the sequence diagram to show the Baseline step with `pcp_fetch_timeseries` and `pcp_detect_anomalies` calls, update the "Specialist Workflow" prose section
+- [x] T041 [P] Update `docs/investigation-flow.md`: update the Synthesis Phase section to reference classification-based ranking (ANOMALY > RECURRING > BASELINE) and the new output structure
+- [x] T042 [P] Review `README.md` for documentation impact — update the specialist workflow description in the prompt table if it references the 4-step flow, and update tool count / prompt descriptions if affected
+- [x] T043 Run full test suite with coverage: `uv run pytest --cov=pmmcp --cov-report=term-missing --cov-fail-under=80` — confirm ≥ 80% coverage maintained
+- [x] T044 Run final pre-push sanity: `scripts/pre-push-sanity.sh` — lint, format, all tests green
+- [x] T045 Run quickstart.md validation: execute the verification commands from `specs/011-specialist-baselining/quickstart.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Phase 1 (Setup)**: No dependencies — confirm green baseline
+- **Phases 3-5 (US1+US2+US5)**: Worktree A — sequential within worktree (same file), can start after Phase 1
+- **Phases 6-7 (US3+US4)**: Worktree B — can start after Worktree A merges (US3 tests assert on classification fields added by US1)
+- **Phase 8 (Polish)**: After both worktrees merged
+
+### Worktree Strategy
+
+```
+main (or feature branch)
+ │
+ ├── Worktree A: US1 → US2 → US5 (specialist.py — domain specialists)
+ │   └── merge back after T025
+ │
+ └── Worktree B: US3 → US4 (specialist.py crosscutting + coordinator.py)
+     └── merge back after T039
+
+ → Phase 8: Polish (docs, README, final validation)
+```
+
+### Within Each User Story
+
+- Tests MUST be written and FAIL before implementation (Red-Green-Refactor)
+- Commit failing tests, then commit passing implementation as separate commits
+- Pre-push sanity MUST pass before pushing each worktree
+
+### Parallel Opportunities
+
+- **T026, T027, T028**: US3 tests can be written in parallel (different test functions, no dependencies)
+- **T032, T033, T034**: US4 tests can be written in parallel (different test functions, no dependencies)
+- **T040, T041, T042**: Polish documentation tasks can be done in parallel (different files/sections)
+- **Worktrees A and B**: Worktree B can begin setup while Worktree A is in final pre-push, but tests should run after Worktree A merge
+
+---
+
+## Parallel Example: Worktree A
+
+```bash
+# Story 1: Write all failing tests, then implement
+# (sequential — tests and impl touch same file sections)
+
+# Story 2: Write all failing tests, then implement per-subsystem
+# T015-T018 modify different subsystem entries in _SPECIALIST_KNOWLEDGE
+# but are in the same file — implement sequentially to avoid merge issues
+
+# Story 5: Write failing tests, implement degradation, pre-push sanity
+```
+
+## Parallel Example: Worktree B
+
+```bash
+# US3 tests can be written in parallel:
+Task: "T026 — cross-cutting classification prioritisation test"
+Task: "T027 — correlated anomaly detection test"
+Task: "T028 — mixed classification guidance test"
+
+# US4 tests can be written in parallel:
+Task: "T032 — classification ranking test"
+Task: "T033 — baseline behaviour call-out test"
+Task: "T034 — recurring pattern highlighting test"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Confirm green baseline
+2. Complete Phase 3: US1 — Baseline step + classification fields
+3. **STOP and VALIDATE**: Run specialist tests, verify baseline step renders for all 5 domain subsystems
+4. This alone delivers the core value: classification in specialist output
+
+### Incremental Delivery
+
+1. US1 → Baseline step and classification fields (core value)
+2. US2 → Domain heuristics reference baseline (prevents false threshold alarms)
+3. US5 → Graceful degradation (handles edge cases)
+4. US3 → Cross-cutting prioritises by classification (correlation layer)
+5. US4 → Coordinator ranks by classification (synthesis layer)
+6. Polish → Documentation catches up
+
+### Worktree Strategy (Recommended)
+
+With parallel execution capacity:
+
+1. **Worktree A**: US1 → US2 → US5 (all specialist.py domain specialist changes)
+2. Merge Worktree A
+3. **Worktree B**: US3 → US4 (cross-cutting + coordinator)
+4. Merge Worktree B
+5. **Main**: Phase 8 polish (docs, README review)
+
+---
+
+## Notes
+
+- All changes are prompt text modifications — no new Python functions, classes, or modules
+- No new dependencies — `pyproject.toml` unchanged
+- No interface changes — function signatures for `specialist_investigate` and `coordinate_investigation` are unchanged
+- Existing contract tests in `tests/contract/test_prompts.py` should continue to pass without modification
+- [P] tasks = different files or test functions, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Pre-push sanity MUST pass before pushing each worktree: `scripts/pre-push-sanity.sh`

From 118656ea0abbf97d1f94939c0dbbc92308b54413 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 03:04:59 +0000
Subject: [PATCH 13/14] =?UTF-8?q?docs:=20constitution=20v1.3.0=20=E2=80=94?=
 =?UTF-8?q?=20mandatory=20documentation=20impact=20review?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Principle I now requires documentation impact review before PR merge.
Plan template updated with docs gate. Aligns with Documentation
Discipline section added to CLAUDE.md.
---
 .specify/memory/constitution.md     | 17 +++++++++++++++--
 .specify/templates/plan-template.md |  2 +-
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
index c375704..e9de46d 100644
--- a/.specify/memory/constitution.md
+++ b/.specify/memory/constitution.md
@@ -1,6 +1,13 @@
 <!--
 SYNC IMPACT REPORT
 ==================
+Version change: 1.2.0 → 1.3.0 (2026-03-10)
+Amendment: Principle I — added mandatory documentation impact review requirement
+Templates updated:
+  ✅ .specify/memory/constitution.md — this file
+  ✅ .specify/templates/plan-template.md — Constitution Check row added for Principle I docs gate
+  ✅ CLAUDE.md — Documentation Discipline section added with concrete checklist
+
 Version change: 1.1.0 → 1.2.0 (2026-02-27)
 Amendment: Principle II — added story-scoped TDD decomposition requirement
 
@@ -51,10 +58,15 @@ clean, comprehensible, and internally consistent.
 - Code reviews MUST be completed by at least one peer before merging to any protected branch.
 - Dead code, commented-out blocks, and orphaned files MUST be removed rather than retained.
 - All dependencies MUST be explicitly declared; implicit transitive reliance is prohibited.
+- Every feature MUST include a documentation impact review before completion. Changes that affect
+  user-facing behaviour, architecture, public APIs, or operational procedures MUST update the
+  relevant documentation (README, design docs, architecture diagrams, contributor guides) in the
+  same PR. Documentation debt is treated with the same urgency as code debt.
 
 **Rationale**: Technical debt compounds. Defects caught at review time cost an order of magnitude
 less to fix than those discovered post-deployment. Consistent quality lowers onboarding time and
-reduces cognitive overhead for the entire team.
+reduces cognitive overhead for the entire team. Stale documentation is worse than no documentation —
+it actively misleads.
 
 ### II. Testing Standards (NON-NEGOTIABLE)
 
@@ -161,6 +173,7 @@ Every pull request MUST pass all of the following gates before merge:
 - [ ] Performance budget checks pass in CI (Principle IV)
 - [ ] At least one peer code review approved (Principle I)
 - [ ] Constitution Check section in `plan.md` completed with pass/fail per principle (all)
+- [ ] Documentation impact reviewed — README, design docs, architecture diagrams updated if affected (Principle I)
 - [ ] Any principle violations documented in the Complexity Tracking table with justification
 
 Compliance reviews MUST be conducted at the start of each feature (Constitution Check in
@@ -200,4 +213,4 @@ For runtime development guidance and active technology context, see agent files
 
 ---
 
-**Version**: 1.2.0 | **Ratified**: 2026-02-20 | **Last Amended**: 2026-02-27
+**Version**: 1.3.0 | **Ratified**: 2026-02-20 | **Last Amended**: 2026-03-10
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
index 1d4e2f6..f581519 100644
--- a/.specify/templates/plan-template.md
+++ b/.specify/templates/plan-template.md
@@ -35,7 +35,7 @@ For each principle, record **PASS**, **FAIL + justification**, or **N/A + reason
 
 | Principle | Status | Notes / Justification |
 |-----------|--------|----------------------|
-| I. Code Quality — linting enforced, single-responsibility, complexity ≤ 10, peer review | | |
+| I. Code Quality — linting enforced, single-responsibility, complexity ≤ 10, peer review, documentation impact reviewed | | |
 | II. Testing Standards — TDD cycle, ≥ 80% unit coverage, contract tests on interface changes | | |
 | III. UX Consistency — design system adherence, WCAG 2.1 AA, actionable error messages | | |
 | IV. Performance — latency SLA defined, performance budget in CI, profiling before optimization | | |

From 71d861e6c406128921fa701cee8550bddacdd238 Mon Sep 17 00:00:00 2001
From: Paul Smith <tallpsmith@gmail.com>
Date: Tue, 10 Mar 2026 03:05:28 +0000
Subject: [PATCH 14/14] =?UTF-8?q?docs:=20CLAUDE.md=20=E2=80=94=20documenta?=
 =?UTF-8?q?tion=20discipline=20section=20+=20011=20active=20tech?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index b2c9cc5..04e091c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -186,6 +186,27 @@ def investigate_subsystem(subsystem: str, ...) -> list[dict]:
 - Registration: side-effect import `import pmmcp.prompts` in `server.py` (bottom, like tools)
 - Contract tests use `srv.mcp._prompt_manager.list_prompts()` and `asyncio.run(srv.mcp.get_prompt(...))`
 
+## Documentation Discipline
+
+**Mandatory before any feature is considered complete** (required by Constitution v1.3.0, Principle I).
+
+Every feature MUST include a documentation impact review. Before closing a PR, check whether changes affect any of the following — and update them in the same PR:
+
+| Document | Update when... |
+|----------|---------------|
+| `README.md` | New/changed tools, prompts, CLI flags, setup steps, or user-facing behaviour |
+| `docs/investigation-flow.md` | Workflow steps, specialist domains, coordinator behaviour, or diagram topology change |
+| `CONTRIBUTING.md` | Dev workflow, testing approach, or project conventions change |
+| `CLAUDE.md` | New conventions, gotchas, or patterns discovered during implementation |
+| Architecture diagrams (mermaid) | Component relationships, data flow, or dispatch patterns change |
+| Prompt table in README | Prompt signatures, descriptions, or argument lists change |
+| `docker-compose.yml` comments | Container topology, env vars, or service dependencies change |
+
+Rules:
+- Documentation updates land in the **same PR** as the code change — not "we'll do it later"
+- If no docs are affected, note it explicitly in the PR description: "Docs impact: none"
+- Stale documentation is worse than no documentation — it actively misleads
+
 ## Pre-Push Sanity Check
 
 **Mandatory before any `git push`** (required by Constitution v1.2.0, Principle II).
@@ -210,6 +231,7 @@ The check runs in order: lint → format → unit+integration tests (≥80% cove
 - N/A — stateless tool; no persistence (006-quick-investigate)
 - Python 3.11+ + `mcp[cli]` ≥1.2.0 (FastMCP), `pydantic` v2.x — no new dependencies (010-specialist-agents)
 - N/A — prompts are stateless text generators (010-specialist-agents)
+- Python 3.11+ + `mcp[cli]` ≥1.2.0 (FastMCP), `pydantic` v2.x — no new dependencies (011-specialist-baselining)
 
 ## Recent Changes
 - 002-add-integration-e2e-tests: Added Python 3.11+ + `mcp[cli]` ≥1.26.0 (FastMCP + ClientSession), `anyio` (memory streams), `respx` (already present — mocks httpx for integration tier), `pytest-asyncio` (already present)