archetype-review-base

Archetype-review-base — 共通レビューのフレームワーク

すべてのドメインレビュアーは、このひな形に従います。各レビュアーの SKILL.md は、ドメイン固有のヒューリスティックを追加します。このスキルでは、 すべてのレビュアー間で同一にしなければならない部分を定義します。

出力成果物（標準）

実装前のレビュアー（agents/ にある約30の *-reviewer エージェント。 アーキテクトがシニア開発者にタスクを割り当てる前に呼び出します）は、 docs/sec-threats/TM-{slug}.md に脅威モデルを作成し、 `` ブロックを追記します（下記の「ワークフローのひな形」を参照）。これが すべてのレビュアーに共通する唯一の規約です。

機能スラッグごとにTMファイルを1つ作成します。 レビュアーごとのファイル名サフィックス （TM-api-{slug}.md、TM-extension-{slug}.md）は非推奨です。利用側は TM-{slug}.md を glob で検索するため、サフィックス付きのファイルはチェックを すり抜けてしまいます。同じスラッグに対して複数のドメインレビュアーが実行される場合、 それぞれが共有の TM-{slug}.md に独自の ## {reviewer} findings セクションと独自の `` ブロックを追記します。他のレビュアーのセクションを 上書きしてはいけません。

以下のFindings / Severity / Verdict 構成は、その成果物（および レビューティアのエージェントが作成する、実装後の 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 で3件の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 の2つだけです。BLOCKED の場合、 need に対応者を記載します。ルールと、3つ目の語がない理由については agents/_shared/reviewer-verdict.md を参照してください。各レビュアーのプロンプトには、 この行にレビュアー名を入れたものが含まれます。

文体ルール — prose-style スキルを適用

• 断定を避ける表現（「一般的に」「多少」「たぶん」など）は使用しない
• 結論から述べる
• 形容詞より具体的な証拠（ファイル:行）を優先する
• 埋め草の書き出し（「このレビューでは、これから…」など）は使わない
• レポートの最終行に判定行を記載する

エスカレーションする場合とレビューする場合

以下の場合は、単にBLOCKするのではなく、security-officer にエスカレーションします。

• 指摘事項が自身のドメイン境界を越える場合（例：PCIレビュアーが一般的な SQLiを見つけた場合は、security-officer の担当です）
• 規制上の判断が曖昧な場合（例：「HIPAAにおけるBAかサブプロセッサーか？」）
• ユーザーが矛盾する要件を提示した場合（自身のドメインに関する知識ではなく、 矛盾を理由に BLOCKED とします）

エスカレーションするには、security-officer ラベルを付けた bd タスクを作成し、 そのタスクがレビューの判定を blocks するようにします。

承認前のセルフテスト

判定行を書く前に、下書きを 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 がタスクを引き受ける前に実行してください。パイプラインを進める前に、Critical／High の指摘に対する修正対応を 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 を参照してください。