archetype-review-base

Archetype-review-base — 共享评审框架

每个领域评审员都遵循此框架。每位评审员自己的 SKILL.md 会在此基础上添加领域启发式规则。本技能定义了 所有评审员必须保持一致的部分。

输出产物（规范）

实施前评审员（*-reviewer Agent——agents/ 中约 30 个——由架构师在高级开发人员认领任务之前调用）会在 docs/sec-threats/TM-{slug}.md 中编写威胁模型，并追加一个 `` 块（参见 下文“工作流框架”）。这是所有评审员统一遵循的约定。

每个功能 slug 对应一个 TM 文件。 按评审员区分的文件名后缀 （TM-api-{slug}.md、TM-extension-{slug}.md）已弃用——使用方会 glob TM-{slug}.md，带后缀的文件会悄然绕过检查。当多个领域评审员针对同一 slug 运行时，每位评审员都要向共享的 TM-{slug}.md 追加自己的 ## {reviewer} findings 小节和自己的 `` 块——绝不能覆盖其他评审员的章节。

下方的发现 / 严重性 / 结论结构是要写入该产物的内容格式（也适用于评审级 Agent 实施后生成的 docs/reviews/REVIEW-{slug}.md）。路径因阶段而异；章节语法完全一致。

必需的报告章节

报告（TM 或 REVIEW）必须严格按以下顺序包含这些章节：

# TM-{slug} — {reviewer name}      

Reviewed: {commit-sha or file paths or ARCH doc reference}
Standard: {regulation / framework you applied — list specific clauses}
Date: {ISO timestamp}

## Scope

2-3 sentences. What did you look at? What's intentionally out of scope?

## Findings

For each finding, use this exact format:

- **[Critical|High|Medium|Low]** {one-sentence finding title}
  - Location: {file:line or component name}
  - Rationale: {why this matters IN THIS DOMAIN — cite a regulation or
    domain-specific best practice. Generic "could be a problem" is
    rejected.}
  - Repro: {a command, or numbered steps, that SHOWS the finding. Required for
    Critical and High.}
  - Remediation: {specific fix — code change, config change, or
    architectural change. NOT "consider adding X" — write the exact change.}
  - References: {URL or document section}

Order findings: Critical → High → Medium → Low.
If no findings at a tier, write: "_None at {tier} severity._"

### Repro, and why it is required at Critical and High

A finding with no reproduction cannot be shown to be fixed, so closing it is an
opinion. A security review on 2026-08-07 said exactly this about its own weaker
items and scored them lower for it — the rule is that reviewer's own standard,
written down.

It is also what makes the finding survive you. The person who fixes it is not
you, and neither is the person who checks the fix; a reproduction is the only
part of a finding that both of them can run.

### File Critical and High as beads

A finding that lives only in a report is one nobody can track, and one whose
closure nobody can check. Two of them were closed on 2026-08-07 by the author of
the fix, which is not a check at all — `scripts/lib/finding-closure.mjs` calls
that `self-verified` and refuses it, but only for findings it can see.

```bash
bd create "[Critical] {title}" --label finding --type bug \
  -d "Location: {file:line}
Repro: {command or steps}
Rationale: {why}
Remediation: {exact fix}"

然后，随着发现状态推进：

bd comment <id> "fixed-by: <agent>"      # whoever writes the fix
bd comment <id> "verified-by: <agent>
repro-result: passed"                    # someone who did NOT write it,
                                         # stating what the repro did NOW
bd close <id> --reason "repro re-run after the fix, now passing"

repro-result 的值为 passed、failed 或 not_run，并由 VERIFIER 在与 verified-by 相同的注释中填写。不会有人替你重新执行复现：运行 bead 描述中的命令，会让报告渠道变成执行渠道；而这在 2026-08-07 的 execution-claims 中造成了三个 CRITICAL。因此，这一环节检查的是谁声称复现通过，以及他们是否编写了修复——而不是命令本身。这是确实存在的限制，也是刻意为之。

如果验证没有说明复现结果如何，发现就会保持为 repro-not-run。“我觉得没问题”不算结果。

验证者不能是修复者，验证必须在修复之后进行，且复现必须通过。这些都会经过检查，而不是只作询问。

结论

VERDICT: {APPROVED|BLOCKED} reason="{specific reason}"

**Quotes must exist.** Before a finding quotes a file, run `node "${CLAUDE_PLUGIN_ROOT:-$(ls -d ~/.claude/plugins/cache/*/great_cto/*/ 2>/dev/null | awk -F'/plugins/cache/' '{split($NF,p,"/"); print p[3], $0}' | sort -V | tail -1 | cut -d' ' -f2- | sed 's|/$||')}/scripts/lib/quote-verify.mjs" --file <file> --quote "<passage>"` (or `--scan <report>`).
A quote that does not verify is removed, or rewritten as a paraphrase marked `(paraphrase)`.

## Severity scale (DOMAIN-anchored)

Severity is graded against THIS DOMAIN's regulatory or
correctness baseline, not generic STRIDE severity. Examples:

- A PCI reviewer rating an unencrypted PAN at REST = **Critical** (PCI
  scope violation; immediate regulatory exposure)
- An oracle reviewer rating a Chainlink staleness < 1h = **High**
  (likely OK now, MEV vulnerable in stress)
- A gov reviewer rating Section 508 a11y gaps = **High** (federal
  contract risk; not Critical because not an immediate breach)

Cite the standard in Rationale. If you can't, the finding is probably
generic and should be reduced one severity tier (the security-officer
agent handles generic concerns).

## Verdict rules

- `VERDICT: APPROVED` is allowed only when ALL Critical and ALL High
  findings have remediation in the bd backlog. (Use
  `bd ready --label {your-archetype}` to check.)
- `VERDICT: BLOCKED` is required when even one Critical or High has no
  remediation, OR when discovery surfaced an unknown that you couldn't
  resolve.
- Medium and Low findings do NOT block. Note them; pipeline continues.

## Domain heuristic vs generic check

You are the SPECIALIST. Your job is the domain-specific stuff that
generic STRIDE / OWASP misses. Decision rule:

| The check is about… | Belongs to |
|---|---|
| Card data, PCI scope, idempotency in payments | pci-reviewer |
| Oracle staleness, MEV, contract upgradeability | oracle-reviewer |
| PHI flows, BAA chain, FHIR/HL7 | healthcare-reviewer |
| Generic XSS, SQLi, weak hashing, secrets in source | security-officer (NOT you) |
| Generic "needs error handling" | senior-dev / code-reviewer (NOT you) |

If a finding is generic, mention it briefly but DON'T inflate severity.
Defer to the appropriate generic reviewer.

## Apply skeptical-triage

Before emitting `VERDICT: BLOCKED`, apply the `skeptical-triage` skill
(3 rounds of self-challenge). False-positive BLOCKED at gate:plan wastes
CTO time. Only block when 3/3 rounds confirm.

## Verdict log line

After writing your report, record the canonical verdict via the helper (see
`agents/_shared/verdict-format.md` — do NOT hand-write the line; the helper
guarantees the format the board parser and the pipeline dispatcher both read,
and `auto` records real token cost):

```bash
bash scripts/log-verdict.sh {your-name} {APPROVED|BLOCKED} auto \
  feature={slug} tm=docs/sec-threats/TM-{slug}.md criticals={N} highs={M} \
  need={implementer|decision} finding={id}   # need/finding on BLOCKED only

APPROVED 和 BLOCKED 是仅有的两个词；若为 BLOCKED，need 会说明由谁采取行动——相关规则以及为何没有第三个词，见 agents/_shared/reviewer-verdict.md。每位评审员自己的提示词都会填入其名称并包含这一行。

行文规则——应用 prose-style 技能

• 不使用模糊词（“通常”“有些”“也许”）
• 先给出结论
• 优先提供具体证据（文件:行号），而不是形容词
• 不要用填充式开头（“在本次评审中，我们将……”）
• 报告的最后一行必须是结论行

何时升级处理，而非评审

遇到以下情况时，升级给 security-officer（而不只是 BLOCK）：

• 发现超出你的领域边界（例如，PCI 评审员发现一般的 SQLi——这属于 security-officer 的职责）
• 监管问题含糊不清（例如，“根据 HIPAA，这是业务伙伴还是子处理方？”）
• 用户提供了相互冲突的要求（对矛盾之处标记为 BLOCKED，而不是质疑你的领域专业能力）

升级处理：创建一个带有 security-officer 标签且 blocks 你的评审结论的 bd 任务。

签署前自测

写下结论行之前，用 grep 检查草稿：

• \b(generally|somewhat|fairly|mostly|possibly|perhaps|maybe)\b——改写
• 任何没有 Location 行的发现——修正
• 任何没有具体变更作为 Remediation 的发现——修正
• 任何没有 remediation-in-bd 的 Critical/High——将结论改为 BLOCKED

如果任何检查在非引用内容中触发，签署前必须修正。

工作流框架（共享内容——你的提示词不得重复）

每位评审员都共享同一套框架。它位于此处；领域评审员自己的 提示词只能在此基础上添加领域启发式规则，绝不能重述以下步骤。 （过去每位评审员都会复制约 80 行内容——正是为了消除这种重复，才创建了此技能。）

当你被调用时

• senior-dev 处于实现前模式，且项目的 archetype 与你的匹配（或符合你声明的 applies_to:）。
• Architect 已完成 ARCH 文档；senior-dev 尚未开始编码。
• 你的领域内出现任何新接口（新标志、新连接器、支付路径、迁移……）。

你要在 senior-dev 认领任务之前运行。关键/高危发现必须先在 bd 待办中有对应的修复措施，流水线才能继续。

步骤 0 — 读取输入（权威内容；不要重新推导）

mkdir -p docs/sec-threats
ARCH=$(ls docs/architecture/ARCH-*.md 2>/dev/null | sort -V | tail -1)
[ -z "$ARCH" ] && { echo "BLOCKED: no ARCH doc — architect must run first." >&2; exit 1; }
SLUG=$(basename "$ARCH" .md | sed 's/^ARCH-//')
TM="docs/sec-threats/TM-${SLUG}.md"

然后按顺序阅读：ARCH 文档中与你的领域相关的章节、你领域内的源文件，以及 .great_cto/PROJECT.md 中你的领域所需的字段（例如 code-sets:、payers:、compliance:）。

输出 — docs/sec-threats/TM-${SLUG}.md

如果存在适用于你领域的模板，请使用 skills/great_cto/templates/TM-{archetype}.md；否则使用上文的 Findings/Severity/Verdict 语法。文件末尾必须包含编排器可解析的交接区块：

{your-name}-verdict: signed-off | blocked
critical-findings: <N>
high-findings: <M>
must-implement-before-senior-dev:
  - <specific change 1>
  - <specific change 2>
gate: <gate:domain-signoff or — if none>

请勿在提示词中包含

• “## Skills used”页脚 — 你的 skills: 前置元数据才是事实来源。
• 重述严重性级别、判定规则、行文规则、升级策略或自测 — 这些均已在本技能的上文中定义。
• 复制步骤 0 的 bash 脚本 — 此处已有权威版本。

在将此框架提取后，领域审查者应遵循的最简结构，请参阅 skills/archetype-review-base/reviewer-template.md。