Implement WP-0015-T03: Control Plane reference-rendering routes

New service/reference_docs.py renders specs/policies/*.md and
specs/profiles/*.md read-only at request time via a small markdown
library (added markdown + PyYAML to the service extras) -- not a
static-build pipeline, matching the WP-0012-T03 decision to skip
state-hub's heavier Observable Framework pattern.

One parameterized route, GET /reference/{kind}/{slug}, covers both
addendum URL shapes. Discovered phase_detail.html's Status table never
displayed the degeneration_policy id at all -- added that row (with
the reference link) rather than wiring a link with nothing to attach
it to. phase_new.html gets a plain link next to the field.

Deliberately did not wire extension-id links into the UI in this task
-- extension ids don't appear anywhere in the Control Plane today
(that's WP-0014's gap, not this one's to expand).

6 new Docker-gated tests. Full suite: 94 passing offline, 164 passing
with Docker (up from 158).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/target_revenue/service/control_plane_app.py

@@ -26,7 +26,7 @@ from psycopg_pool import ConnectionPool
 from starlette.middleware.sessions import SessionMiddleware
 
 from .. import control_plane, ledger, metrics, registry
-from . import keys
+from . import keys, reference_docs
 
 _STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
 _TEMPLATES_DIR = os.path.join(os.path.dirname(__file__), "control_plane_templates")
@@ -37,6 +37,8 @@ _SECRET_KEY_ENV = "TRF_CONTROL_PLANE_SECRET_KEY"
 app = FastAPI(title="Target Revenue Control Plane", version="0.1.0")
 app.mount("/static", StaticFiles(directory=_STATIC_DIR), name="static")
 templates = Jinja2Templates(directory=_TEMPLATES_DIR)
+templates.env.globals["policy_slug"] = reference_docs.policy_slug_from_id
+templates.env.globals["extension_slug"] = reference_docs.extension_slug_from_id
 
 _secret_key = os.environ.get(_SECRET_KEY_ENV)
 if not _secret_key:
@@ -408,3 +410,31 @@ def audit_log(
 ):
     log = control_plane.get_audit_log(conn)
     return templates.TemplateResponse(request, "audit.html", _template_context(request, licensor, log=log))
+
+
+# --- Reference docs (specs/policies/, specs/profiles/) ----------------------
+
+
+@app.get("/reference/{kind}/{slug}")
+def reference_doc(
+    kind: str,
+    slug: str,
+    request: Request,
+    licensor: registry.Licensor = Depends(require_login),
+):
+    """Read-only rendering of a `specs/policies/`/`specs/profiles/`
+    markdown file (WP-0015-T03) — never editable from here."""
+    result = reference_docs.load_reference_doc(kind, slug)
+    if result is None:
+        raise HTTPException(status_code=404, detail="reference document not found")
+    doc_html, frontmatter = result
+    return templates.TemplateResponse(
+        request,
+        "reference.html",
+        _template_context(
+            request, licensor,
+            doc_html=doc_html,
+            doc_title=frontmatter.get("title", slug),
+            source_path=f"specs/{kind}/{slug}.md",
+        ),
+    )

src/target_revenue/service/control_plane_templates/phase_detail.html

@@ -24,6 +24,13 @@
   <tr><td>Outstanding Target</td><td>{{ metrics.facts.outstanding_target }}</td></tr>
   <tr><td>Target satisfaction</td><td>{{ metrics.calculations.target_satisfaction_percentage }}%</td></tr>
   <tr><td>Converted</td><td>{{ metrics.facts.is_converted }}</td></tr>
+  <tr>
+    <td>Degeneration policy</td>
+    <td>
+      {{ manifest.phase.degeneration_policy }}
+      &middot; <a href="/reference/policies/{{ policy_slug(manifest.phase.degeneration_policy) }}">view spec</a>
+    </td>
+  </tr>
 </table>
 
 <h3>Ledger ({{ ledger | length }} entries)</h3>

src/target_revenue/service/control_plane_templates/phase_new.html

@@ -49,6 +49,9 @@
   <wn-field-row label="Degeneration policy">
     <wn-input name="degeneration_policy" value="trsl:policy:linear-longstop-v0@1.0" required></wn-input>
   </wn-field-row>
+  <p style="margin-top:-0.5rem;color:#888;font-size:0.85rem;">
+    <a href="/reference/policies/linear-longstop-v0">view the linear-longstop-v0 spec</a>
+  </p>
   <wn-field-row label="Longstop date (ISO 8601)">
     <wn-input name="longstop_at" required></wn-input>
   </wn-field-row>

src/target_revenue/service/control_plane_templates/reference.html

@@ -0,0 +1,15 @@
+{% extends "base.html" %}
+{% block title %}{{ doc_title }} — Target Revenue Control Plane{% endblock %}
+{% block content %}
+<wn-page-header>
+  <span slot="title">{{ doc_title }}</span>
+</wn-page-header>
+<p style="color:#888;font-size:0.85rem;">
+  Read-only reference, rendered from <code>{{ source_path }}</code>. See
+  that file's own git history for the full revision trail — this view
+  cannot be edited.
+</p>
+<div class="reference-doc">
+{{ doc_html | safe }}
+</div>
+{% endblock %}

src/target_revenue/service/reference_docs.py

@@ -0,0 +1,58 @@
+"""Read-only rendering of `specs/policies/`/`specs/profiles/` markdown
+files for the Control Plane (WP-0015-T03).
+
+Server-side markdown -> HTML at request time, deliberately not a static
+build pipeline (unlike state-hub's Observable Framework Reference
+section, confirmed materially heavier during WP-0012-T03) -- this repo's
+existing lightweight FastAPI+Jinja2 stack needs nothing more than a
+small markdown library for six profile pages and one policy page.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import markdown
+import yaml
+
+_SPECS_DIR = Path(__file__).resolve().parents[3] / "specs"
+
+# kind -> subdirectory name under specs/. Only these two exist today
+# (WP-0015-T02); a third kind (e.g. "calculators") can be added here if
+# a future workplan gives calculators their own reference route.
+REFERENCE_KINDS = frozenset({"policies", "profiles"})
+
+
+def load_reference_doc(kind: str, slug: str) -> tuple[str, dict[str, Any]] | None:
+    """Return (rendered_html, frontmatter) for one spec file, or None if
+    `kind` is unknown or no matching file exists. Read-only: there is no
+    corresponding write path anywhere in this module."""
+    if kind not in REFERENCE_KINDS:
+        return None
+    path = _SPECS_DIR / kind / f"{slug}.md"
+    if not path.is_file():
+        return None
+
+    raw = path.read_text(encoding="utf-8")
+    frontmatter: dict[str, Any] = {}
+    if raw.startswith("---\n"):
+        end = raw.find("\n---\n", 4)
+        if end != -1:
+            frontmatter = yaml.safe_load(raw[4:end]) or {}
+            raw = raw[end + 5 :]
+
+    html = markdown.markdown(raw)
+    return html, frontmatter
+
+
+def policy_slug_from_id(policy_id: str) -> str:
+    """`trsl:policy:linear-longstop-v0@1.0` -> `linear-longstop-v0`."""
+    name = policy_id.split(":")[-1]
+    return name.split("@")[0]
+
+
+def extension_slug_from_id(extension_id: str) -> str:
+    """`trsl:extension:development-license@1.0` -> `development-license`."""
+    name = extension_id.split(":")[-1]
+    return name.split("@")[0]