apm-review-panel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

APM Review Panel - Fan-Out Advisory Review

APM评审面板 - 扇出式咨询评审

The panel is FAN-OUT + SYNTHESIZER. Each persona runs in its own agent thread (via the

task

tool) and returns JSON matching

assets/panelist-return-schema.json

. The orchestrator schema-validates each return, hands all returns to the apm-ceo synthesizer (also a task thread, returns JSON matching

assets/ceo-return-schema.json

), then renders ONE recommendation comment from

assets/recommendation-template.md

This skill is ADVISORY by design. It does not compute a binary verdict, it does not apply verdict labels, and it does not gate merge. The panel surfaces findings; the maintainer and the PR author decide ship.

该面板采用扇出+合成器模式。每个角色都在独立的Agent线程中运行（通过

task

工具），并返回符合

assets/panelist-return-schema.json

格式的JSON。Orchestrator会验证每个返回结果的 schema 合法性，将所有结果传递给apm-ceo合成器（同样运行在task线程中，返回符合

assets/ceo-return-schema.json

格式的JSON），然后根据

assets/recommendation-template.md

生成唯一一条建议评论。

本Skill在设计上仅提供咨询意见。它不会计算二元 verdict，不会添加 verdict 标签，也不会设置合并门禁。面板仅呈现评审发现；是否发布由PR维护者和作者决定。

Architecture invariants

架构不变量

Advisory regime, not gate regime. There is no
```
APPROVE
```
/
```
REJECT
```
, no
```
panel-approved
```
/
```
panel-rejected
```
label, no deterministic verdict computation. The CEO returns a
```
ship_recommendation.stance
```
(
```
ship_now
```
/
```
ship_with_followups
```
/
```
needs_discussion
```
/
```
needs_rework
```
); this is prose for the human reviewer, never auto-applied as a label or status check. This is the architectural fix for the previous regime's over-strictness: removing the binary gate removes the incentive for panelists to inflate
```
required[]
```
defensively.
Three severity buckets, none of them gate. Findings carry
```
severity: blocking | recommended | nit
```
.
```
blocking
```
is the highest signal a panelist can send and renders prominently in the comment; it still does not block merge.
```
recommended
```
is the default for substantive feedback.
```
nit
```
is one-line polish. The orchestrator never reads severity to gate anything.
Single-writer interlock. Only the orchestrator writes to the PR: exactly one
```
add-comment
```
and one
```
remove-labels
```
call. The
```
remove-labels
```
call always sweeps
```
panel-review
```
(trigger idempotency) AND defensively removes
```
panel-approved
```
/
```
panel-rejected
```
if present (legacy verdict labels from the pre-advisory regime; they have no meaning here and would mislead readers if left on a PR after a fresh advisory pass). NO
```
add-labels
```
call -- there are no verdict labels to apply. Panelist subagents and the CEO subagent return JSON only and MUST NOT call any
```
gh
```
write command, post comments, apply labels, or touch the PR state.
Single-emission discipline. Exactly one comment per panel run, rendered from
```
assets/recommendation-template.md
```
after all subagents return.

咨询机制，而非门禁机制。 不设置
```
APPROVE
```
/
```
REJECT
```
，不添加
```
panel-approved
```
/
```
panel-rejected
```
标签，不进行确定性的 verdict 计算。CEO会返回
```
ship_recommendation.stance
```
（可选值：
```
ship_now
```
/
```
ship_with_followups
```
/
```
needs_discussion
```
/
```
needs_rework
```
）；该字段是供人工评审者参考的文本内容，绝不会自动作为标签或状态检查项应用。这是针对旧机制过于严格问题的架构修复：移除二元门禁后，评审专家便无需为了防御性目的而夸大
```
required[]
```
的内容。
三个严重程度等级，均非门禁。 评审发现的严重程度分为
```
blocking | recommended | nit
```
。
```
blocking
```
是评审专家能给出的最高信号，会在评论中突出显示；但即便如此，它也不会阻止合并。
```
recommended
```
是实质性反馈的默认等级。
```
nit
```
是单行的优化建议。Orchestrator绝不会根据严重程度设置任何门禁。
单一写入者互锁。 仅Orchestrator可向PR写入内容：仅执行一次
```
add-comment
```
和一次
```
remove-labels
```
操作。
```
remove-labels
```
操作始终会移除
```
panel-review
```
（触发幂等性重置），并且会防御性地移除可能存在的
```
panel-approved
```
/
```
panel-rejected
```
标签（这些是旧门禁机制遗留的 verdict 标签；在新的咨询机制下它们已无意义，若留在PR上会误导读者）。不执行
add-labels
操作——本机制下没有需要添加的 verdict 标签。评审子Agent和CEO子Agent仅返回JSON，绝对不能调用任何
```
gh
```
写入命令、发布评论、添加标签或修改PR状态。
单一输出原则。 每次面板运行仅生成一条评论，该评论在所有子Agent返回结果后根据
```
assets/recommendation-template.md
```
渲染生成。

Agent roster

Agent角色列表

Agent	Role	Always active?
Python Architect	Architectural Reviewer + supplies mermaid diagrams	Yes
CLI Logging Expert	Output UX Reviewer	Yes
DevX UX Expert	Package-Manager UX	Yes
Supply Chain Security Expert	Threat-Model Reviewer	Yes
OSS Growth Hacker	Adoption Strategist	Yes
Auth Expert	Auth / Token Reviewer	Conditional (see below)
Doc Writer	Documentation Reviewer	Conditional (see below)
Test Coverage Expert	Test-Presence Reviewer (paired with DevX UX)	Yes (skipped only on docs-only PRs -- see below)
APM CEO	Strategic Arbiter / Synthesizer	Yes

Agent	角色	是否始终激活？
Python Architect	架构评审员 + 提供mermaid图表	是
CLI Logging Expert	输出UX评审员	是
DevX UX Expert	包管理器UX评审员	是
Supply Chain Security Expert	威胁模型评审员	是
OSS Growth Hacker	采用策略师	是
Auth Expert	认证/令牌评审员	可选（见下文）
Doc Writer	文档评审员	可选（见下文）
Test Coverage Expert	测试存在性评审员（与DevX UX专家配合）	是（仅纯文档PR会跳过——见下文）
APM CEO	战略仲裁者/合成器	是

Topology

拓扑结构

   apm-review-panel SKILL (orchestrator thread)
                      |
   FAN-OUT via task tool (panelists in parallel)
                      |
   +-----+-------+-------+-----+-----+------+-----------+----------+
   v     v       v       v     v     v      v           v          v (cond.)
  py    cli     dx-ux   sec   grw   auth   doc-writer  test-cov
   |     |       |       |     |     |      |           |
   |   each returns JSON per panelist-return-schema.json
   +-----+-------+-------+-----+-----+------+-----------+----------+
                      |
                      v   <-- S4 schema-validate
                      v   <-- on malformed: re-spawn that persona
                      v
   task: apm-ceo synthesizer
   - aggregates findings across panelists
   - resolves dissent
   - emits headline + arbitration prose + principle alignment
   - emits curated recommended_followups (prioritized)
   - emits ship_recommendation (stance + prose)
   - returns ceo-return-schema.json
                      |
                      v   <-- S4 schema-validate
                      v
   orchestrator (sole writer)
            |               |
            v               v
        add-comment    remove-labels
        (max:2)        [panel-review,
                        panel-approved,
                        panel-rejected]
                       (trigger reset +
                        legacy verdict sweep)

   apm-review-panel SKILL (orchestrator thread)
                      |
   FAN-OUT via task tool (panelists in parallel)
                      |
   +-----+-------+-------+-----+-----+------+-----------+----------+
   v     v       v       v     v     v      v           v          v (cond.)
  py    cli     dx-ux   sec   grw   auth   doc-writer  test-cov
   |     |       |       |     |     |      |           |
   |   each returns JSON per panelist-return-schema.json
   +-----+-------+-------+-----+-----+------+-----------+----------+
                      |
                      v   <-- S4 schema-validate
                      v   <-- on malformed: re-spawn that persona
                      v
   task: apm-ceo synthesizer
   - aggregates findings across panelists
   - resolves dissent
   - emits headline + arbitration prose + principle alignment
   - emits curated recommended_followups (prioritized)
   - emits ship_recommendation (stance + prose)
   - returns ceo-return-schema.json
                      |
                      v   <-- S4 schema-validate
                      v
   orchestrator (sole writer)
            |               |
            v               v
        add-comment    remove-labels
        (max:2)        [panel-review,
                        panel-approved,
                        panel-rejected]
                       (trigger reset +
                        legacy verdict sweep)

Conditional panelists

可选评审专家

Two personas are conditional (auth, doc-writer). A third (test-coverage) is mandatory on every PR that touches

src/

and only skipped on documentation-only PRs -- see its section below for why. The orchestrator ALWAYS spawns ALL three tasks to keep the schema return shape uniform; the prompt instructs the subagent to set

active: false

with an

inactive_reason

if the condition does not hold.

有两个角色是可选的（认证专家、文档撰写者）。第三个角色（测试覆盖率专家）在所有涉及

src/

目录的PR中都是必选的，仅在纯文档PR中会跳过——见下文说明。为了保持返回 schema 的一致性，Orchestrator始终会启动这三个角色的任务；如果条件不满足，提示会 instruct 子Agent设置

active: false

并填写

inactive_reason

。

Auth Expert

认证专家

Activate when the PR changes any of:

```
src/apm_cli/core/auth.py
```
```
src/apm_cli/core/token_manager.py
```
```
src/apm_cli/core/azure_cli.py
```
```
src/apm_cli/deps/github_downloader.py
```
```
src/apm_cli/marketplace/client.py
```
```
src/apm_cli/utils/github_host.py
```
```
src/apm_cli/install/validation.py
```
```
src/apm_cli/install/pipeline.py
```
```
src/apm_cli/deps/registry_proxy.py
```

Fallback self-check (when no fast-path file matched): "Does this PR change authentication behavior, token management, credential resolution, host classification used by

AuthResolver

, git or HTTP authorization headers, or remote-host fallback semantics? If unsure, answer YES."

当PR修改以下任一文件时激活：

```
src/apm_cli/core/auth.py
```
```
src/apm_cli/core/token_manager.py
```
```
src/apm_cli/core/azure_cli.py
```
```
src/apm_cli/deps/github_downloader.py
```
```
src/apm_cli/marketplace/client.py
```
```
src/apm_cli/utils/github_host.py
```
```
src/apm_cli/install/validation.py
```
```
src/apm_cli/install/pipeline.py
```
```
src/apm_cli/deps/registry_proxy.py
```

备选自检逻辑（当没有匹配快速路径文件时）：“该PR是否修改了认证行为、令牌管理、凭证解析、

AuthResolver

使用的主机分类、Git或HTTP授权头，或远程主机回退语义？若不确定，回答是。”

Doc Writer

文档撰写者

Activate when the PR changes any of:

```
README.md
```
```
CHANGELOG.md
```
```
MANIFESTO.md
```
```
docs/src/content/docs/**
```
```
.apm/skills/**/*.md
```
```
.apm/agents/**/*.md
```
```
.github/skills/**/*.md
```
```
.github/agents/**/*.md
```
```
.github/instructions/**/*.md
```
```
.github/workflows/*.md
```
(gh-aw natural-language workflows)
```
packages/apm-guide/**
```

Fallback self-check (when no fast-path file matched): "Does this PR change user-facing documentation, agent or skill prose, instruction files, CHANGELOG entries, README claims, or any natural-language artifact a reader will rely on? If unsure, answer YES."

When the doc-writer is active and the PR includes documentation changes, the persona reviews them for: (a) consistency with the existing voice and structure, (b) accuracy against the code being changed, (c) completeness for the typical reader (no orphan claims, no missing prerequisites), (d) discoverability (cross-links, sidebar order if Starlight content). When the doc-writer is active because of code changes that SHOULD have updated docs but did not, the persona surfaces that gap as a finding.

当PR修改以下任一文件时激活：

```
README.md
```
```
CHANGELOG.md
```
```
MANIFESTO.md
```
```
docs/src/content/docs/**
```
```
.apm/skills/**/*.md
```
```
.apm/agents/**/*.md
```
```
.github/skills/**/*.md
```
```
.github/agents/**/*.md
```
```
.github/instructions/**/*.md
```
```
.github/workflows/*.md
```
（gh-aw自然语言工作流）
```
packages/apm-guide/**
```

备选自检逻辑（当没有匹配快速路径文件时）：“该PR是否修改了面向用户的文档、Agent或Skill文本、说明文件、CHANGELOG条目、README声明，或任何读者会依赖的自然语言制品？若不确定，回答是。”

当文档撰写者激活且PR包含文档修改时，该角色会从以下方面评审文档：(a) 与现有风格和结构的一致性；(b) 与修改后代码的准确性；(c) 对普通读者的完整性（无孤立声明、无缺失前提条件）；(d) 可发现性（交叉链接、Starlight内容的侧边栏顺序）。当文档撰写者因代码修改应更新文档但未更新而激活时，该角色会将此差距作为评审发现提出。

Test Coverage Expert

测试覆盖率专家

Active by default on every PR that touches
src/**/*.py
. The only condition that flips this persona to

active: false

is a documentation-only PR -- the diff contains zero

src/**/*.py

files. In that case set

inactive_reason: "documentation-only PR -- no runtime code paths to defend"

The activation rule is intentionally narrow: under the advisory regime, test outcomes are LOAD-BEARING for CEO arbitration (passed / failed / missing test evidence outranks opinion-only findings -- see

apm-ceo.agent.md

and

panelist-return-schema.json

evidence block). A persona whose findings carry that weight cannot be silently skipped on a heuristic. Better to spawn it on a pure refactor and have it return a single

nit

-severity "no behavior surface touched -- no coverage finding" line than to skip it and leave the CEO without evidence to weigh. (Earlier revisions of this skill paired test-coverage with auth and doc-writer as conditional for symmetry; that symmetry broke when test evidence became load-bearing.)

The test-coverage-expert is paired with the devx-ux-expert lens and defends the user-promise contracts the DevX persona enumerates (CLI surface, error wording, install idempotency, lockfile determinism, auth resolution). It MUST verify "no test exists" claims with

view

grep

on the test tree before emitting a finding -- false-positive coverage findings destroy trust in the field. It does NOT compute coverage percentages, does NOT flag tests for pure refactors, and does NOT duplicate python-architect on test-code design.

默认在所有涉及
src/**/*.py
文件的PR中激活。唯一会将该角色设为

active: false

的情况是纯文档PR——差异中不包含任何

src/**/*.py

文件。此时需设置

inactive_reason: "documentation-only PR -- no runtime code paths to defend"

。

激活规则故意设置得很严格：在咨询机制下，测试结果是CEO仲裁的核心依据（测试通过/失败/缺失证据的优先级高于仅基于观点的评审发现——见

apm-ceo.agent.md

和

panelist-return-schema.json

中的证据块）。一个评审发现具有如此高权重的角色，不能基于启发式规则被静默跳过。与其在纯重构PR上跳过它，不如启动它并让它返回一条

nit

级别的“未触及行为表面——无覆盖发现”记录，这样CEO就有证据可权衡。（本Skill的早期版本为了对称性将测试覆盖率专家与认证、文档撰写者归为可选角色；但当测试证据成为核心依据后，这种对称性就被打破了。）

测试覆盖率专家与DevX UX专家配合，捍卫DevX角色列举的用户承诺契约（CLI界面、错误措辞、安装幂等性、锁文件确定性、认证解析）。在发布评审发现之前，它必须通过

view

grep

检查测试目录来验证“不存在相关测试”的说法——误报的覆盖发现会破坏维护者对该机制的信任。它不计算覆盖率百分比，不针对纯重构PR标记测试，也不重复Python架构师对测试代码设计的评审工作。

Routing matrix (CEO synthesis emphasis only)

路由矩阵（仅针对CEO合成重点）

These routes describe WHICH specialist's findings the CEO weights more heavily for a given PR type. They do NOT change which personas run -- every mandatory persona always runs. Routing is a CEO synthesis hint.

Architecture-heavy PR -> CEO weights Python Architect on abstraction calls; CLI Logging on consistency.
CLI UX PR -> CEO weights DevX UX on command surface; CLI Logging on output paths; Growth Hacker on first-run conversion.
Security PR -> CEO biases toward Supply Chain Security on default behavior; DevX UX flags ergonomics regression from any mitigation.
Auth PR (auth-expert active) -> CEO weights Auth Expert on AuthResolver / token precedence; Supply Chain on token-scoping.
Docs / release / comms PR (doc-writer active) -> CEO weights Doc Writer on accuracy and voice; Growth Hacker on hook and story angle.
Behavior-change PR (test-coverage active) -> CEO weights Test Coverage Expert on regression-trap presence; DevX UX on which user promises the change touches. A blocking-severity coverage finding on a critical-promise surface (auth, lockfile, install, marketplace, hooks) is the highest signal in this routing.
Full panel (default) -> CEO synthesizes equally; calls out any dissent in
```
dissent_notes
```
.

这些路由规则描述了对于特定类型的PR，CEO会更重视哪些专家的评审发现。它们不会改变哪些角色会运行——所有必选角色始终会运行。路由是CEO合成的提示信息。

架构密集型PR -> CEO会重视Python架构师关于抽象调用的评审发现；重视CLI日志专家关于一致性的评审发现。
CLI UX PR -> CEO会重视DevX UX专家关于命令界面的评审发现；重视CLI日志专家关于输出路径的评审发现；重视增长黑客关于首次运行转化率的评审发现。
安全PR -> CEO会倾向于重视供应链安全专家关于默认行为的评审发现；DevX UX专家会标记任何缓解措施导致的用户体验退化。
认证PR（认证专家激活）-> CEO会重视认证专家关于AuthResolver/令牌优先级的评审发现；重视供应链专家关于令牌范围的评审发现。
文档/发布/沟通PR（文档撰写者激活）-> CEO会重视文档撰写者关于准确性和风格的评审发现；重视增长黑客关于钩子和故事角度的评审发现。
行为变更PR（测试覆盖率专家激活）-> CEO会重视测试覆盖率专家关于回归陷阱存在性的评审发现；重视DevX UX专家关于变更涉及哪些用户承诺的评审发现。在关键承诺表面（认证、锁文件、安装、市场、钩子）上的
```
blocking
```
级覆盖发现是此路由中的最高信号。
完整面板（默认）-> CEO会平等地综合所有评审发现；在
```
dissent_notes
```
中指出任何异议。

Execution checklist

执行检查清单

Work through these steps in order. Do not skip ahead. Do not emit any output to the PR before step 6.

Read PR context (the orchestrating workflow already fetched it via
```
gh pr view
```
/
```
gh pr diff
```
). Identify changed files for the conditional panelist routing decisions (auth-expert and doc-writer).
Resolve the conditional panelists using the rules above. Decide for EACH conditional persona: spawn active OR spawn with
```
active: false
```
+ an
```
inactive_reason
```
. Either way, all three conditional personas ARE spawned -- the schema requires uniform return shape.
Fan out panelist tasks. Spawn the following tasks in PARALLEL via the
```
task
```
tool, one task per persona:
- ```
python-architect
```
  (also asked to supply
```
extras.diagrams
```
  :
```
class_diagram
```
  (mermaid
```
classDiagram
```
  ),
```
component
```
  (mermaid
```
flowchart TD
```
  ), and OPTIONAL
```
sequence
```
  (mermaid
```
sequenceDiagram
```
  ) blocks per the persona's section 1/2/3 contract)
- ```
cli-logging-expert
```
- ```
devx-ux-expert
```
- ```
supply-chain-security-expert
```
- ```
oss-growth-hacker
```
- ```
auth-expert
```
  (always - active per step 2)
- ```
doc-writer
```
  (always - active per step 2)
- ```
test-coverage-expert
```
  (always - active per step 2)
Each task prompt MUST:
- Reference its persona file by relative path so the subagent loads its own scope, lens, and anti-patterns.
- Include the PR number, title, body, and diff (passed inline).
- Cite
```
assets/panelist-return-schema.json
```
  and require the subagent to emit JSON matching that schema as its FINAL message.
- State the calibrated severity contract: "Use
```
severity: blocking
```
  ONLY for correctness regressions, security/auth bypasses, or architectural faults that compound, with explicit rationale. Default substantive feedback to
```
recommended
```
  . Use
```
nit
```
  for one-line polish. The panel is advisory; nothing you return blocks merge -- pick the severity that honestly matches your signal strength."
- Restate the output contract: NO
```
gh
```
  write commands, NO posting comments, NO label changes, NO touching PR state. JSON return only.
S4 schema gate. When each panelist task returns, parse the JSON and validate against
```
assets/panelist-return-schema.json
```
. On validation failure:
- Re-spawn that ONE panelist with an explicit error message pointing at the violated rule.
- Maximum two re-spawn attempts per panelist. If still malformed, synthesize a placeholder
```
{persona: "<slug>", active: true, summary: "Schema failure -- see extras.", findings: [], extras: {schema_failure: "<reason>"}}
```
  and surface the failure in the CEO arbitration prompt.
Spawn the CEO synthesizer task. Pass the full set of validated panelist JSON returns to a
```
task
```
invocation that loads
```
../../agents/apm-ceo.agent.md
```
. The prompt MUST:
- Provide all panelist returns as structured input.
- Ask for: headline, arbitration prose, principle alignment (only applicable principles), curated recommended_followups (prioritized by signal, NOT a re-listing of every finding), ship_recommendation (stance + prose).
- Cite
```
assets/ceo-return-schema.json
```
  and require JSON return.
- Restate the contract: the panel is advisory. The CEO does NOT pick a verdict label. The
```
ship_recommendation.stance
```
  is prose for the human reviewer, not a gate. NO
```
gh
```
  write commands.
Validate the CEO return against
```
assets/ceo-return-schema.json
```
. On failure, re-spawn once with the violation cited.
Resolve the notification audience. The advisory comment must surface in the inboxes of the people who will act on it. Run:
```
gh pr view <PR_NUMBER> --json author,reviewRequests
```
Build
```
notify_audience
```
as the deduplicated list:
- the PR author's
```
@login
```
  (always included);
- every requested reviewer's
```
@login
```
  (these are the CODEOWNERS-resolved reviewers GitHub auto-requested for the touched paths, plus any explicitly-requested human reviewers);
- every requested team's
```
@org/team-slug
```
  (CODEOWNERS team entries).
Filter out:
- bot logins (login ending in
```
[bot]
```
  or matching
```
dependabot|github-actions|copilot-pull-request-reviewer
```
  );
- the orchestrator's own identity (avoid self-ping).
Cap the final list at 6 handles to avoid notification noise (PR author + up to 5 reviewers/teams). If the cap trims, prefer team handles over individual logins. Pass the resulting list to the template renderer as
```
notify_audience
```
.
This step replaces the maintainer-notification signal that the pre-advisory verdict labels carried. It is the only mechanism by which a fresh panel pass announces itself.
Render the comment. Load
```
assets/recommendation-template.md
```
, fill the placeholders from the panelist + CEO JSON, and emit it as exactly ONE comment.
Filling rules:
- The per-persona summary table renders ONLY active panelists, one row per persona, with finding counts by severity and the persona's
```
summary
```
  field.
- The mermaid diagrams come from
```
python-architect.extras.diagrams
```
  . If absent, render the placeholder lines from the template (do NOT invent diagrams).
- The recommended follow-ups list renders the CEO's curated subset, not every finding. Full per-persona findings collapse at the bottom.
- NEVER render the words "Verdict", "APPROVE", "REJECT", "blocked", "merge gate", or any equivalent. The panel is advisory.
Sweep labels via
```
safe-outputs.remove-labels
```
. The list MUST be
```
[panel-review, panel-approved, panel-rejected]
```
-- always all three, regardless of which are currently on the PR.
```
panel-review
```
is the re-run idempotency reset; the other two are LEGACY VERDICT LABELS from the pre-advisory regime that have no meaning under the advisory contract and would mislead readers if left on a freshly-reviewed PR.
```
safe-outputs.remove-labels
```
is idempotent on missing labels, so sweeping all three on every run is safe and self-healing. NO verdict labels are applied.

按顺序完成以下步骤。不要跳过任何步骤。在完成第6步之前，不要向PR输出任何内容。

读取PR上下文（编排工作流已通过
```
gh pr view
```
/
```
gh pr diff
```
获取）。识别变更文件，以便决定可选评审专家的路由（认证专家和文档撰写者）。
确定可选评审专家的状态使用上述规则。为每个可选角色决定：启动激活状态的任务，还是启动
```
active: false
```
+
```
inactive_reason
```
的任务。无论哪种情况，三个可选角色都会被启动——schema要求返回格式一致。
扇出评审专家任务。通过
```
task
```
工具并行启动以下任务，每个角色对应一个任务：
- ```
python-architect
```
  （同时要求提供
```
extras.diagrams
```
  ：
```
class_diagram
```
  （mermaid
```
classDiagram
```
  ）、
```
component
```
  （mermaid
```
flowchart TD
```
  ），以及可选的
```
sequence
```
  （mermaid
```
sequenceDiagram
```
  ）块，符合该角色的1/2/3契约）
- ```
cli-logging-expert
```
- ```
devx-ux-expert
```
- ```
supply-chain-security-expert
```
- ```
oss-growth-hacker
```
- ```
auth-expert
```
  （始终启动——状态由第2步决定）
- ```
doc-writer
```
  （始终启动——状态由第2步决定）
- ```
test-coverage-expert
```
  （始终启动——状态由第2步决定）
每个任务的提示必须：
- 通过相对路径引用其角色文件，以便子Agent加载自身的范围、视角和反模式。
- 包含PR编号、标题、正文和差异（内联传递）。
- 引用
```
assets/panelist-return-schema.json
```
  ，要求子Agent输出符合该schema的JSON作为最终消息。
- 明确严重程度契约：“仅当存在正确性回归、安全/认证绕过或会加剧的架构缺陷时，才使用
```
severity: blocking
```
  ，并需提供明确理由。实质性反馈默认使用
```
recommended
```
  。单行优化建议使用
```
nit
```
  。面板仅提供咨询意见；你返回的任何内容都不会阻止合并——选择与信号强度真实匹配的严重程度。”
- 重申输出契约：禁止调用
```
gh
```
  写入命令、发布评论、修改标签、修改PR状态。仅返回JSON。
S4 schema校验。当每个评审专家任务返回结果后，解析JSON并根据
```
assets/panelist-return-schema.json
```
进行验证。若验证失败：
- 重新启动该评审专家的任务，并提供明确的错误消息指出违反的规则。
- 每个评审专家最多重新启动两次。若仍格式错误，则生成一个占位符：
```
{persona: "<slug>", active: true, summary: "Schema failure -- see extras.", findings: [], extras: {schema_failure: "<reason>"}}
```
  ，并在CEO仲裁提示中说明该失败情况。
启动CEO合成器任务。将所有验证通过的评审专家JSON结果传递给加载
```
../../agents/apm-ceo.agent.md
```
的
```
task
```
调用。提示必须：
- 提供所有评审专家的返回结果作为结构化输入。
- 要求返回：标题、仲裁文本、原则对齐（仅适用的原则）、整理后的推荐后续任务（按信号优先级排序，而非简单列出所有发现）、发布建议（立场+文本）。
- 引用
```
assets/ceo-return-schema.json
```
  ，要求返回JSON。
- 重申契约：面板仅提供咨询意见。CEO不选择verdict标签。
```
ship_recommendation.stance
```
  是供人工评审者参考的文本，而非门禁。禁止调用
```
gh
```
  写入命令。
根据
```
assets/ceo-return-schema.json
```
验证CEO的返回结果。若失败，重新启动一次并指出违反的规则。
确定通知受众。咨询评论必须出现在会采取行动的人员的收件箱中。运行：
```
gh pr view <PR_NUMBER> --json author,reviewRequests
```
构建去重后的
```
notify_audience
```
列表：
- PR作者的
```
@login
```
  （始终包含）；
- 所有被请求的评审者的
```
@login
```
  （这些是GitHub根据触及路径自动请求的CODEOWNERS评审者，加上任何明确请求的人工评审者）；
- 所有被请求的团队的
```
@org/team-slug
```
  （CODEOWNERS团队条目）。
过滤掉：
- bot账号（登录名以
```
[bot]
```
  结尾，或匹配
```
dependabot|github-actions|copilot-pull-request-reviewer
```
  ）；
- Orchestrator自身的身份（避免自 ping）。
将最终列表限制为6个账号，以避免通知噪音（PR作者+最多5个评审者/团队）。若需要截断，优先保留团队账号而非个人登录名。将生成的列表传递给模板渲染器作为
```
notify_audience
```
。
此步骤替代了旧门禁机制中维护者通知的信号。这是新面板运行后告知相关人员的唯一机制。
渲染评论。加载
```
assets/recommendation-template.md
```
，用评审专家和CEO的JSON结果填充占位符，并生成唯一一条评论。
填充规则：
- 每个角色的摘要表仅渲染激活的评审专家，每个角色一行，包含各严重程度的发现数量和角色的
```
summary
```
  字段。
- mermaid图表来自
```
python-architect.extras.diagrams
```
  。若缺失，则渲染模板中的占位符行（不要自行生成图表）。
- 推荐后续任务列表渲染CEO整理后的子集，而非所有发现。完整的每个角色的发现会折叠在评论底部。
- 绝对不要渲染“Verdict”、“APPROVE”、“REJECT”、“blocked”、“merge gate”或任何等效词汇。面板仅提供咨询意见。
清理标签通过
```
safe-outputs.remove-labels
```
执行。标签列表必须为
```
[panel-review, panel-approved, panel-rejected]
```
——无论PR当前有哪些标签，始终清理这三个。
```
panel-review
```
用于重置重运行的幂等性；另外两个是旧门禁机制遗留的VERDICT标签，在咨询机制下已无意义，若留在刚评审过的PR上会误导读者。
```
safe-outputs.remove-labels
```
对不存在的标签是幂等的，因此每次运行都清理这三个标签是安全且能自我修复的。不添加任何verdict标签。

Output contract (non-negotiable)

输出契约（不可协商）

Exactly ONE comment per panel run, rendered from
```
assets/recommendation-template.md
```
. The
```
safe-outputs.add-comment.max: 2
```
is a fail-soft ceiling; the discipline lives here.

Exactly ONE

remove-labels

call sweeping

[panel-review, panel-approved, panel-rejected]

NO
```
add-labels
```
call. The advisory regime has no verdict to encode.
Subagents (panelists + CEO) NEVER write to PR state, NEVER call
```
gh pr comment
```
, NEVER call
```
gh pr edit --add-label
```
. They return JSON. The orchestrator is the sole writer.
Never invent new top-level template sections or drop existing ones.

每次面板运行仅生成一条评论，根据
```
assets/recommendation-template.md
```
渲染。
```
safe-outputs.add-comment.max: 2
```
是容错上限；实际需严格遵守仅一条的原则。

仅执行一次

remove-labels

操作，清理

[panel-review, panel-approved, panel-rejected]

。

不执行
add-labels
操作。咨询机制下没有需要编码的verdict。
子Agent（评审专家+CEO）绝对不能修改PR状态、调用
```
gh pr comment
```
、调用
```
gh pr edit --add-label
```
。它们仅返回JSON。Orchestrator是唯一的写入者。
不要自行添加新的顶级模板章节，也不要删除现有章节。

Gotchas

注意事项

Roster invariant. The frontmatter description, the roster table, the conditional rules, the recommendation template, and the JSON schema MUST agree on the persona set. If you change one, change all in the same edit.
Calibrated severity discipline. The advisory regime relies on panelists honestly distinguishing
```
blocking
```
from
```
recommended
```
. If a panelist marks everything
```
blocking
```
, the comment becomes noisy and the maintainer learns to ignore the field. The panelist prompts state the contract explicitly; the CEO arbitration prose is the safety valve when a panelist over-flags.
Mermaid diagrams are template-required. The python-architect persona is asked to supply
```
extras.diagrams.class_diagram
```
,
```
extras.diagrams.component
```
, and the OPTIONAL
```
extras.diagrams.sequence
```
. The template renders nothing when they are missing -- it does NOT invent diagrams. Real diagrams are what makes the comment scannable for the human reviewer.
Mermaid
classDiagram

:::cssClass
shorthand gotcha. GitHub's mermaid renderer rejects
```
:::cssClass
```
appended to relationship lines (e.g.
```
A *-- B:::touched
```
); use standalone
```
class Name:::cssClass
```
declarations instead. Authority:
```
python-architect.agent.md:146-154
```
.
Doc-writer detects DRIFT, not just edits. When the PR changes user-facing code that SHOULD have updated docs but did not, doc-writer surfaces that as a finding. The conditional rule above is necessary but not sufficient -- doc-writer reasons about doc consistency given the diff, not just whether doc files were touched.
False-negative auth gotcha. Auth regressions can be introduced from non-auth files that change the inputs to auth -- host classification, dependency parsing, clone URL construction, HTTP authorization headers, or call sites that bypass
```
AuthResolver
```
. If a diff changes how a remote host, org, token source, or fallback path is selected and you are not certain it is auth-neutral, activate auth-expert as
```
active: true
```
.
Test-coverage probe is mandatory. The test-coverage-expert MUST verify "no test exists for X" via
```
view
```
/
```
grep
```
on the
```
tests/
```
tree before emitting a finding. A false-positive coverage finding (test exists but persona claimed it does not) destroys maintainer trust in the field. The persona scope file enforces this; the orchestrator passes the diff and trusts the persona to probe.
Subagent write enforcement is contract-based, not sandbox-based. Tool permissions are workflow-scoped, not subagent-scoped, so every spawned task technically inherits the same
```
gh
```
toolset. The "subagents must not write" rule is enforced by the prompt contract in each
```
.agent.md
```
plus the
```
safe-outputs.add-comment.max: 2
```
fail-soft. If a subagent ever tries to post a comment, the cap catches it.
No verdict-label reset workflow. The previous regime had a companion workflow
```
pr-panel-label-reset.yml
```
that stripped verdict labels on every push. The advisory regime has no verdict labels to strip; that workflow is removed.

角色列表不变量。前置描述、角色列表表格、可选规则、推荐模板和JSON schema必须在角色集合上保持一致。若修改其中一个，必须在同一编辑中修改所有相关部分。
校准后的严重程度原则。咨询机制依赖评审专家诚实地区分
```
blocking
```
和
```
recommended
```
。若评审专家将所有发现都标记为
```
blocking
```
，评论会变得嘈杂，维护者会学会忽略该字段。评审专家的提示中明确说明了契约；当评审专家过度标记时，CEO的仲裁文本是安全阀门。
Mermaid图表是模板必需项。Python架构师角色被要求提供
```
extras.diagrams.class_diagram
```
、
```
extras.diagrams.component
```
，以及可选的
```
extras.diagrams.sequence
```
。若缺失，模板会渲染占位符——不要自行生成图表。真实的图表能让人工评审者更易浏览评论。
Mermaid
classDiagram

:::cssClass
简写陷阱。GitHub的mermaid渲染器拒绝在关系行末尾添加
```
:::cssClass
```
（例如
```
A *-- B:::touched
```
）；请改用独立的
```
class Name:::cssClass
```
声明。依据：
```
python-architect.agent.md:146-154
```
。
文档撰写者检测偏差，而非仅编辑。当PR修改了应更新文档但未更新的面向用户的代码时，文档撰写者会将此作为发现提出。上述可选规则是必要但不充分的——文档撰写者会根据差异判断文档的一致性，而非仅检查是否修改了文档文件。
认证误报陷阱。非认证文件的修改也可能引入认证回归——例如修改主机分类、依赖解析、克隆URL构造、HTTP授权头，或绕过
```
AuthResolver
```
的调用点。若差异修改了远程主机、组织、令牌源或回退路径的选择逻辑，且你不确定它是否与认证无关，请将认证专家设为
```
active: true
```
。
测试覆盖率探测是必需的。测试覆盖率专家必须通过
```
view
```
/
```
grep
```
检查
```
tests/
```
目录来验证“X不存在测试”的说法，然后才能发布评审发现。误报的覆盖发现（实际存在测试但角色声称不存在）会破坏维护者对该机制的信任。角色范围文件强制执行此规则；Orchestrator传递差异并信任角色会进行探测。
子Agent写入限制基于契约，而非沙箱。工具权限是工作流范围的，而非子Agent范围的，因此每个启动的任务在技术上都继承了相同的
```
gh
```
工具集。“子Agent不能写入”的规则通过每个
```
.agent.md
```
中的提示契约以及
```
safe-outputs.add-comment.max: 2
```
的容错机制来强制执行。若子Agent尝试发布评论，上限会阻止它。
无verdict标签重置工作流。旧机制有一个配套工作流
```
pr-panel-label-reset.yml
```
，会在每次推送时移除verdict标签。咨询机制下没有verdict标签需要移除；该工作流已被删除。