GeezerVison

fix(autopilot): align worker and PR body contracts

Description

TL;DR

This PR fixes five source-backed inconsistencies in Autopilot worker packages and the PR-description skill. Human-owned deferral labels remain advisory-only, workers stop when active companion personas are missing, Mermaid validation is pinned, diagram requirements are conditional, and the review schema no longer points to an undeployed rubric path.

Problem (WHY)

• PR triage could write a human-decision label even though the contract says “Not invited for implementation now; never equivalent to accepted.”
• Triage and review rosters linked to companion agents through paths such as “../../agents/devx-ux-expert.agent.md”, but those roles are not bundled as worker-package files.
• Diagram guidance said “Any change that touches more than one file or alters control flow SHOULD include at least one mermaid diagram.”, conflicting with the same skill’s conditional diagram section for simple PRs.

The same review found a floating Mermaid CLI invocation and an unsupported rubric path in the panelist schema; the Approach and Implementation sections identify those exact surfaces.

Approach (WHAT)

Implementation (HOW)

Diagrams

This flow shows the new preflight boundary: all active roles are checked before a worker can continue.

flowchart LR
  Start[Resolve active roles] --> Check{All role files exist?}
  Check -- Yes --> Continue[Read personas and run full panel]
  Check -- No --> Missing[Report every missing role]
  Missing --> Stop[Stop before advice or fan-out]

This flow distinguishes an advisory deferral recommendation from the human-owned label decision.

flowchart LR
  PR[No accepted linked scope] --> Advice[Recommend needs-issue]
  Advice --> Comment[Explain human review is required]
  Comment --> Decision{Human chooses deferral?}
  Decision -- Yes --> Apply[Human applies status/deferred]
  Decision -- No --> Leave[Leave the label unchanged]

Trade-offs

• Keep specialist personas as consumer-provided companions instead of adding transitive dependencies; the workers remain standalone, while preflight makes the prerequisite explicit and fail-closed.
• Keep one small checker per standalone worker rather than introducing a shared package dependency that would couple their installation.
• Pin the Mermaid CLI package version while retaining the existing one-shot npx workflow; no global installation or unrelated dependency-management system is added.
• Remove only the stale schema path, not the principle vocabulary used by panelists.

Benefits

1. PR triage no longer writes status/deferred; the human decision boundary matches the shared label contract.
2. Both worker packages report all absent active roles before partial advice or review can occur.
3. Mermaid validation names an exact CLI version, and simple PRs can omit diagrams consistently.
4. The panelist schema retains its principle enum without directing consumers to a nonexistent file.

Validation

uv run --extra dev pytest tests/unit/test_workflow_actor_contract.py -q

..................                                                       [100%]
18 passed in 0.87s

uv run --extra dev ruff check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ && uv run --extra dev ruff format --check src/ tests/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ && uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/ scripts/lint_architecture_boundaries.py scripts/architecture_linter/ && bash scripts/lint-auth-signals.sh

All checks passed!
2091 files already formatted
Your code has been rated at 10.00/10
[+] auth-signal lint clean

uv run apm audit --ci

[*] All 10 check(s) passed

The environment did not provide the optional microsoft/.github-private policy, so organization policy enforcement was skipped by the audit.

uv run apm install --refresh --target agent-skills,copilot --force

[*] Installed 12 APM dependencies in 6.3s.

cd docs && npm run build

19:20:07 [build] 126 page(s) built in 9.14s
[+] Checked 1111 relative link(s) across generated pages. No broken relative links found.

Scenario Evidence

How to test

• Run uv run --extra dev pytest tests/unit/test_workflow_actor_contract.py -q; confirm all 18 contract tests pass.
• Run uv run apm audit --ci; confirm all 10 deployment-integrity checks pass.
• Run cd docs && npm run build; confirm the Starlight build and relative-link check pass.
• Install the packages in a clean consumer, omit one active .github/agents/<slug>.agent.md, and confirm the worker stops with the missing role named.
• Restore all active persona files and confirm the preflight reports ready: true.

Issue and approved scope

Issue: Fixes #3418

Human scope-approval comment: apm-scope:v1 approval

Does this PR complete the issue, or what remains? This PR completes the five bounded repairs and their regression coverage.

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

Spec conformance (OpenAPM v0.1)

If this PR changes behaviour that an OpenAPM v0.1 req-XXX covers,
confirm the three-step ritual in the
development guide:

• Spec edit: docs/src/content/docs/specs/openapm-v0.1.md updated
  (new/changed <a id="req-XXX"></a> anchor + prose + Appendix C
  row).
• Manifest edit: docs/src/content/docs/specs/manifests/openapm-v0.1.requirements.yml
  updated.
• Test edit: a @pytest.mark.req("req-XXX") test under
  tests/spec_conformance/ added or extended.
• CONFORMANCE.{md,json} regenerated via
  uv run --extra dev python -m tests.spec_conformance.gen_statement
  and committed.
• N/A -- this PR does not change OpenAPM-observable behaviour.

Co-authored-by: Copilot [email protected]