The Professor: drafting agent persona for the handbook knowledge layer

[serina-mcfall]

Summary

Adds The Professor: a persona pack that drafts handbook pages, wired to a real 5-tool MCP server (read-only) against the handbook's own provenance contract, plus a real drafting attempt that produced and gate-validated a two-claim page end-to-end.

Related issue

Closes #9

Issue type

Task

---

Agent provenance

Field	Value
Harness / provider	Claude Code
Model	claude-sonnet-5
Session reference	N/A - harness does not expose a stable run id/URL for this session
Initiating human	@serina-mcfall

Objective

A .persona.md persona pack for The Professor, wired to a read-only MCP tool server against the handbook's page contract, proven against a real drafting attempt.

Impacted components

launchpad/agents/the-professor/personas/the-professor.persona.md
launchpad/agents/the-professor/tools/server.py
launchpad/agents/the-professor/tools/check_server.py
launchpad/agents/the-professor/skills/draft-page/SKILL.md
launchpad/agents/the-professor/.mcp.json
launchpad/agents/the-professor/.plugin/plugin.json
launchpad/agents/the-professor/README.md
launchpad/AGENTS.md
launchpad/Research/the-professor-design.md
launchpad/plans/2026-08-19-issue-9-the-professor-persona.md

Approach and rejected alternatives

Built a real MCP tool server (official mcp Python SDK, uv run --script shebang) rather than trusting the model to resolve pins/paths from memory — the design doc's own identified SHA-hallucination risk. Route 2 (plain buzz-acp configured from the environment) was chosen over Route 1 (recreating the desktop app's config, not scriptable/testable) — see README's Runtime Route section for the full reasoning, including the explicit specification-vs-configuration caveat. Scratch-path draft output was chosen over a real write-path/PR-against-handbook flow, since #9's bounded acceptance does not require one and the design doc names that as a separate, deferred decision (Open Question 2, Route 3).

Verification

Command run:

just test-unit

Raw output (tail):

  Passed (8):
    pass buzz-core tests
    pass buzz-auth unit tests
    pass buzz-voice tests
    pass buzz-cli tests
    pass buzz-db unit tests
    pass buzz-conformance tests
    pass buzz-push-gateway tests
    pass buzz-backend-kubernetes tests

[run-tests] All tests passed!

Command run:

uv run --script /tmp/verify_draft.py   # calls check_page via the real MCP server, same protocol path as check_server.py

Raw output:

{
  "findings": [],
  "unchecked": [],
  "skipped": [],
  "page_index": {
    "ok": true,
    "errors": []
  }
}

This re-verifies (independent of the ACP session transcript) the exact draft content The Professor produced during the real Step 16 drafting attempt: two claims, [upstream] block/buzz@main pinned to 9a1e861ab8507ee28e5f03010b7f36d1b74ec919 (crates/buzz-persona/PERSONA_PACK_SPEC.md), and [launchpad] launchpad-26/buzz@launchpad pinned to 45dd387e316bdd2ad677ce6bcc1d742baec53532 (launchpad/AGENTS.md §3, launchpad/review-agent/'s existence) — both resolved via resolve_pin against the real GitHub API, not recalled from memory.

Command run:

just mobile-test   # via pre-push lefthook, after merging origin/launchpad

Raw output (tail):

04:56 +1461 -4: Some tests failed.
error: Recipe `mobile-test` failed on line 680 with exit code 1

4 pre-existing failures, all in accessibility large-text-size timestamp layout tests (compose_note_page_test.dart, forum_widgets_test.dart, note_card_test.dart) — filed as #237, unrelated to this PR's diff (zero mobile/** files touched). Pushed past this hook with --no-verify on Serina's explicit authorization, with #237 filed first as the paper trail (same category of problem as the precedent at #181).

Command run:

uv run --script /tmp/verify_injection_fix.py

Raw output:

injection attempt (bad path) -> Error executing tool path_exists_at: path_exists_at('block/buzz', '0000000000000000000000000000000000000000', 'crates/buzz-persona/PERSONA_PACK_SPEC.md?ref=main&'): `path` contains '?' or '&', which cannot appear in a real repository path. Refusing rather than risk it being interpreted as part of the request's query string.
non-SHA commit -> Error executing tool path_exists_at: path_exists_at('block/buzz', 'main', 'crates/buzz-persona/PERSONA_PACK_SPEC.md'): `commit` is not a 40-character hex SHA. This tool checks existence at a pinned commit, not a branch or tag -- resolve it with resolve_pin() first.
ALL INJECTION CHECKS BEHAVED AS EXPECTED (see output above)

Confirms the exact exploit review-code identified (a path value smuggling its own ?ref= to override the pinned commit) is now rejected outright, and that a bare branch name in commit (instead of a real pin) is also rejected.

• Tests or checks were run and the raw output is pasted above
• The diff is confined to the scope of the linked issue
• No secrets, keys, tokens or hostnames were added to tracked files

Not verified

Desktop and relay-integration behavior beyond what just test-unit/cargo test -p buzz-cli cover — this PR touches no desktop or relay code, so those suites were not re-run beyond the pre-push hook's own pass. Whether the persona pack format itself (frontmatter shape, MCP wiring) is stable against upstream PERSONA_PACK_SPEC.md changes going forward — only checked against the pinned commit resolved during Step 16. Whether goose's GOOSE_TEMPERATURE/GOOSE_MODEL env-var projection is the correct mechanism long-term, versus a config file — noted in the README's Runtime Route section as an open, stated caveat rather than something this PR resolves.

Security implications

All five MCP tools in server.py are confirmed read-only (no write, push, or commit calls to GitHub or the handbook repo) — independently re-verified by direct code inspection, not just trusted from the implementation report. The credential used to run the agent (an Anthropic API key) is bring-your-own-key per person, documented explicitly in the README's Credential Policy section, and was never read or printed by the controller during setup — only copied between environment variables. No secret, key, or hostname was added to any tracked file.

Escalations

1. Credential/provider decision — surfaced to Serina as a group decision (shared infra, not a solo call); resolved as bring-your-own-key per individual for Route 2, documented in README's Credential Policy section. Explicitly does not answer Route 3's (unattended-operation) credential question.
2. Write-path capability gap — the real Step 16 drafting attempt showed The Professor can compose and validate a correct draft, but has no tool that can write it to disk or reply — only this pack's five read-only MCP tools were ever wired into the runtime; goose's built-in shell/write extension was never enabled. The controller extracted and placed the already-validated draft by hand (documented in README's Observed Behaviour section). This is exactly why Route 3 is filed as task: Route 3 projector — resolve The Professor's pack into a real, write-capable runtime #239, a separate follow-up issue, rather than attempted in this PR.
3. Pre-existing mobile test failures — filed as bug: accessibility timestamp widget tests fail on launchpad tip (4 failures in mobile/) #237, unrelated to this PR's diff; pushed past the pre-push hook with --no-verify on Serina's explicit authorization after filing that issue first.
4. Merge-to-nav decision (Step 21) — this PR's draft page stays proof-only; it is not merged into the live launchpad-26/handbook nav. The draft's own body states it is a scratch/test artifact, not real handbook content, and the save step above was not fully autonomous.
5. review-final findings — a full-branch review was run before this PR left draft. One Blocker: the plan's own review-code gate on server.py (real security surface — gh api subprocess calls, gate-script invocation) was never dispatched during the original build. Two Medium findings (a stale model ID in README's Model section contradicting the persona file, and Step 19's required exact scratch-path evidence missing from the README) were deferred as their own follow-up: task: fix two README documentation-accuracy gaps for The Professor #240.
6. review-code results (the Blocker from # prd-03 — reproducible and hardened Buzz deployment: rebuild the cohort server from a bare Ubuntu host #5, resolved) — dispatched against server.py, independent of the branch's author. Found real issues, now fixed in c55272389: a Blocker — path_exists_at built its gh api request as a hand-concatenated query string, so a path value containing its own ?ref=... could override the pinned commit it was supposed to check against, defeating pin verification entirely; fixed by passing ref via gh api --method GET -f and rejecting any path containing ?/& outright. A High — check_page never checked whether check_provenance.py itself exited non-zero, only whether its stdout parsed as JSON, so a failed gate run printing valid-but-empty JSON would report as a clean pass; fixed to raise when a non-zero exit carries no findings/unchecked/skipped. A Medium — the local handbook checkout lived at a predictable, world-writable /tmp path trusted without an ownership check; fixed to verify ownership and wipe-and-reclone if it doesn't match. A Low — path_exists_at's commit argument was never validated as a real SHA the way resolve_pin's output is; now validated up front. Re-verified against check_server.py's full fixture suite plus a new targeted check confirming the exact injection payload and a bare branch name both now raise.

[benmitchell11]

Read the full diff, with server.py as the priority given the PR's own escalation #5 flags it as never having gone through review-code before this PR opened.

Security review of server.py (all 5 MCP tools), done independently:

• Confirmed read-only end to end: read_contract/list_categories/resolve_pin/path_exists_at are all single gh api GET calls; check_page does git fetch+reset --hard against a local temp-dir cache of the handbook (not the real repo) and shells out to the handbook's own check_provenance.py/page_index.py read-only. No push/commit/write call to GitHub or the handbook repo anywhere in the file.
• All subprocess.run calls use list-form argv, never shell=True — repo/ref/path/commit args can't achieve shell injection regardless of content.
• The rate-limit/auth-vs-404 disambiguation in resolve_pin/path_exists_at (checking the JSON status field rather than trusting exit code or falling through) is a real, non-obvious trap correctly avoided — an ordinary 403 could otherwise silently masquerade as "no such ref."
• _subprocess_env_with_github_token() never logs or returns the token, only places it in the env dict handed to the gate-script subprocess — checked this holds.

Spot-verified, not just trusted:

• Both pinned SHAs from the Step 16 drafting attempt are real: crates/buzz-persona/PERSONA_PACK_SPEC.md does exist at 9a1e861a... in block/buzz (main has since moved, which is expected — a pin is point-in-time by design, not a claim that it's still HEAD). The launchpad pin (45dd387e3...) is the same commit I independently verified as accurate while reviewing buzz-infrastructure#69.
• #237, #239, #240 all exist and match what's described. The --no-verify mobile-test bypass is justified — zero mobile/** files in this diff, issue filed first, same precedent as #181.
• check_server.py's test design is genuinely careful — it deliberately avoids using broken-01 as a negative control because that fixture would pass regardless of whether check_page works (checked this reasoning against check_provenance.py's own documented judgement-vs-script engine split), and checks both the true and false case for path_exists_at rather than only the happy path.

One new finding, not covered by #240: personas/the-professor.persona.md's frontmatter description ("A mentoring persona designed to guide learning through questions and insights.") and the identical copy in .plugin/plugin.json don't match what the persona actually is. The body defines a strict citation-discipline drafting agent scoped to exactly five named tools ("You do not have access to Slack, live systems, or arbitrary search") — nothing about guiding learning through Socratic questions. Reads like unedited template boilerplate carried over from scaffolding, and it's user-facing (plugin listings, marketplace description). #240 only covers the Model section and Observed Behaviour path — this is a third, separate doc-accuracy gap worth folding into that follow-up or its own tiny issue.

Not blocking — approving. The security-critical piece (server.py) checks out independently, and this is a one-line description fix, not a functional defect.