Make the buddy the tutor along the onboarding path

[DavidLeuter]

Summary

Persona and agent changes so the buddy tutors along the hire's onboarding path instead of acting as a second onboarding. Also: grading, orientation and diagrams now ask the model once more for corrected JSON instead of failing on its first broken reply.

Refs SprintStartProject/Wiki#311

Changes

Persona (buddy_persona.py)

• New identity: a tutor along the path, not "first day to real work". The old Task 0 / ramp wording is gone, and a test keeps it out.
• New clauses, each shown only when its tool is available: reading the path, numbered and linked references, locked items, phases that run side by side (the hire picks, not the lowest number), walking through material with search_docs, tutoring on knowledge questions without giving the answer away (starting from the hire's last wrong answer when the path shows it), closing steps that are READY TO CLOSE, checklist lines, adding steps with both waits_on and unlocks, skip requests, and routing between the path, the work pool, metrics and the ledger.
• The work pool is open from day one. The buddy stays with the hire after they claim a task (open_orientation + search_docs).
• _NO_BUTTON_CLAUSE: the buddy offers something by calling its tool, and a NOT PROPOSED result means no button was shown.

Agent (buddy_agent.py)

• _MAX_STEPS goes from 4 to 6.
• The forced final answer now gets a system note that no tools are available. Before, it promised buttons that didn't exist.

Retry broken JSON once

• grading.py, orientation.py and diagram.py send one correction round when the model's JSON can't be parsed. Before, grading marked the answer wrong, and orientation or diagram gave up.

Testing

• ruff check, ruff format --check: green
• pyright src/: clean
• pytest: 988 passed. 10 local failures in ingestion code this PR doesn't touch. They fail the same way on a clean origin/dev: 9 tree-sitter tests under my local Python 3.14 (CI runs 3.12), and a timing threshold in test_ingest_run_processes_artifacts_concurrently (elapsed < 0.5).

Notes

• The clauses are keyed to tool names, so they only show up once the backend mounts the new tools. That makes the merge order with the backend PR uncritical.
• Up to date with dev.

Related PRs

• Backend: Make the buddy the tutor along the onboarding path sprintstart-backend#261
• Frontend: Make the buddy the tutor along the onboarding path sprintstart-frontend#267

🤖 Generated with Claude Code

[DavidLeuter]

Follow-up fix (8f6adc3): offer flag_to_pm whenever the hire asks for it

While testing, the buddy refused a direct "flag this to my PM". The only thing the persona said about escalating was "offer flag_to_pm as the last resort", and the model applied that to the hire's own requests too.

Changes:

• New _FLAG_ON_REQUEST_CLAUSE, mounted only when flag_to_pm is available. When the hire asks to flag, raise or pass something to their PM, the buddy offers it in that reply. It never decides for them that it isn't a PM matter and never sends them to the docs first.
• The add-step clause gets the same exception: a step the hire asks for is offered, because it goes on their own copy of the path.
• New test in test_buddy_persona.py.

The matching tool-description change is in SprintStartProject/sprintstart-backend#261 (00203027). Verified manually. ruff, format and pyright are clean; 999 tests pass.

[Afif-del]

The retry only handles JSON/Pydantic parsing failures, but _Payload.results currently defaults to an empty list. Therefore a syntactically valid but incomplete response such as {}, or one that omits one requested answer ID, reaches this return without retrying. The caller then reports every missing grade as incorrect even though the model never graded it.

Please make results required and validate that the response contains exactly one result for every requested ID before returning. Missing, duplicate, or unexpected IDs should raise ValueError so the existing correction round is used. For example:

payload = _Payload.model_validate_json(extract_json_object(raw))
graded_by_id = {item.id: item for item in payload.results}
expected_ids = {item.id for item in to_grade}

if (
    len(payload.results) != len(to_grade)
    or set(graded_by_id) != expected_ids
):
    raise ValueError("grading response does not match requested answer IDs")

return graded_by_id

Also change _Payload to:

class _Payload(BaseModel):
    results: list[_GradedItem]