bizlp prompt-lint Rule Reference (ADR-0063 / 9 fields + threshold + semver + state transitions SSoT)

Status: SSoT (ADR-0063 で確立、2026-05-25) 対象: prompts/production/*/prompt.meta.yaml (現状 6 dirs: body-generation / gate0-triage / gate1-socratic / gate2-consistency / gate3-parallel-review / gate4-scoring) の起案者・レビュアー・AI Agent (Claude / Gemini / GPT) 検証: scripts/prompt-meta-lint.mjs (ADR-0042 起源、9 REQUIRED_FIELDS + threshold) + scripts/adr-lint-doc-consistency.mjs (本 doc ↔ .promptpolicy.yaml ↔ script の 3 way 整合、Phase 2 で実装予定) 根拠 ADR:

• ADR-0063 — prompt-lint Rule Reference SSoT 確立
• ADR-0058 — 同パターン第三適用
• ADR-0054 — 10 節構造
• ADR-0042 — Prompt Lifecycle Policy 起源

1. Purpose & Scope

本 doc は scripts/prompt-meta-lint.mjs:25-67 に実装された 9 REQUIRED_FIELDS + threshold rule + semver rules + state transitions + 90 日 auto-archive の規約を 1 箇所に集約した Single Source of Truth (SSoT) である。.promptpolicy.yaml (機械可読 truth) と ADR-0042 本文 (設計意図) に分散していた根拠を、Discovery (Summary Table) + Detail (9 fields 深掘り) + 規約 3 カテゴリ (Threshold / Semver / State) + Lifecycle の四層構造で集約する。

対象読者:

• prompt 起案者: prompts/production/<name>/prompt.meta.yaml を新規作成・更新する前に §4 Summary Table と §5 Required Fields Detail を読む
• PR レビュアー: CI で prompt-meta-lint.mjs が fail した時の rule 解釈根拠として参照
• AI Agent: prompt lifecycle 自動化時の semver / state 判定基準
• Jr 入社時 (2026-10): onboarding 主要参照先 (CLAUDE.md / frontmatter-lint_rules.md / dev-spec-lint_rules.md と並ぶ品質規約 SSoT)

Non-Goals: prompt-meta-lint.mjs / .promptpolicy.yaml の機械可読 truth 書き換え (本 doc から片方向参照、Immutability 遵守) / ADR-0042 本文書換 / promptfoo eval ツール選定議論。

2. Severity Legend

9 fields すべて error。threshold 違反も error。Lifecycle (state) は ADR-0042 運用判断で起案者裁定、CI 警告のみ (future Phase で error 昇格検討)。

3. Category Legend

4. Summary Table (Discovery Layer)

scripts/prompt-meta-lint.mjs:25-28 の REQUIRED_FIELDS (9 種) + threshold rule (1 件):

集計: error 8 件 (required 6 + lifecycle 1 + threshold 1) / 対象 6 prompts × 将来増分。.promptpolicy.yaml から global rule を継承。(model_pin は 2026-06-08 廃止)

5. Required Fields Detail

5.1 id

id: prompt-id
severity: error
category: required
since: 2026-05-25  # ADR-0063 採択日
status: active
fixable: false
description: kebab-case のプロンプト識別子、production dir 名と一致
related_adrs: [ADR-0042, ADR-0063]

Rationale

id フィールドは prompts/production/<id>/prompt.meta.yaml の dir 名と一致させる。kv_key / KV namespace の prefix と紐付き、ID 不整合は KV active pointer の参照破壊を生む。kebab-case 必須 (snake_case や camelCase は AST 整合性 CI で reject、Phase 2)。

✅ PASS Example

# prompts/production/gate0-triage/prompt.meta.yaml
id: gate0-triage

References

• scripts/prompt-meta-lint.mjs:26: REQUIRED_FIELDS 配列 #1
• prompts/production/gate0-triage/prompt.meta.yaml:1: 実例

5.2 owner

id: owner
severity: error
category: required
since: 2026-05-25
status: active
fixable: false
description: 担当者 (email 形式)
related_adrs: [ADR-0042, ADR-0063]

Rationale

prompt 改修時の連絡先・責任者明示。Jr 入社後 (2026-10) は引き継ぎ完了まで [email protected]、引き継ぎ後は Jr のメールに更新。email 形式は .adr-lint-doc-consistency-allowlist.json で正規表現 strict 化を Phase 2 で検討。

✅ PASS Example

owner: [email protected]

5.3 status (Lifecycle)

id: status
severity: error
category: lifecycle
since: 2026-05-25
status: active
fixable: false
description: 6 state 値域 (draft / experiment / candidate / production / deprecated / archived)
related_adrs: [ADR-0042, ADR-0063]

Rationale

ADR-0042 で定めた 6 state の lifecycle。任意値を許すと experimentl / prod 等の表記揺れが発生し、weekly_cron (.promptpolicy.yaml:33-36) の自動 archive 対象抽出が破綻する。state 遷移ルールは §8 State Transitions 参照。

✅ PASS Example

status: production    # production state (本番運用中)

status: experiment    # experiment state (A/B test 中)
deprecation_at: null  # deprecated でないので null

5.4 semver

id: semver
severity: error
category: required
since: 2026-05-25
status: active
fixable: false
description: semver 形式 (major.minor.patch)
related_adrs: [ADR-0042, ADR-0063]

Rationale

prompt 改修履歴を semver で追跡。major/minor/patch 境界判断は §7 Semver Rules で明文化。任意 string は AST 整合性 CI で reject (Phase 2、正規表現 ^\d+\.\d+\.\d+$)。

✅ PASS Example

semver: 1.0.0    # initial production
semver: 1.1.0    # backward-compat feature add (minor)
semver: 2.0.0    # output schema breaking change (major)

5.5 model_pin (廃止 2026-06-08)

DEPRECATED: model_pin は 2026-06-08 に必須フィールドから廃止。prompt-meta-lint.mjs の REQUIRED_FIELDS からも削除済。 理由: runtime のモデル選択に一切使われておらず (worker src/ から参照 0 件)、値が 1 ヶ月 drift しても誰も気づかなかった (load-bearing でない)。当初の存在理由「model_pin + 週次 cron で drift 検知」(ADR-0042) は未実装の建前で、実際の週次 cron は promptfoo 回帰 (出力ベース) で model_pin を読まない。 モデル選択の SSoT は drp/src/llm/gateway.ts の MODELS (各ノードが createLlm(env, MODELS.X, ...) で参照)。ADR-0042 に廃止注記あり。

References

• ADR-0042 §model pin 設計: 上流モデル変更 detection 根拠
• prompts/production/gate0-triage/prompt.meta.yaml:5: 実例

5.6 output_schema

id: output_schema
severity: error
category: required
since: 2026-05-25
status: active
fixable: false
description: 出力スキーマ参照 (JSON Schema path or 'free-text')
related_adrs: [ADR-0042, ADR-0063]

Rationale

prompt 出力の構造を JSON Schema として明示。free-text の場合は free-text 文字列を指定し、起案者意図 (schema 不要) を明示。schema 違反は Pipeline 内で early failure detection (Gate 3 parallel review 等で利用)。

✅ PASS Example

output_schema: output_schema.json    # JSON Schema file
output_schema: free-text             # 構造化なし (Pipeline 簡易処理用)

5.7 eval_suite

id: eval_suite
severity: error
category: required
since: 2026-05-25
status: active
fixable: false
description: promptfoo eval suite (golden.jsonl path)
related_adrs: [ADR-0042, ADR-0063]

Rationale

promptfoo (.promptpolicy.yaml:19-24) で実行する eval suite path。weekly_cron で min_golden_cases: 20 件以上 + temperature 0 + majority verdict + retries 2 で検証。golden cases 不足は CI fail。

✅ PASS Example

eval_suite: ../../../prompts-eval/datasets/gate0-triage/golden.jsonl

5.8 eval_pass_threshold

id: eval_pass_threshold
severity: error
category: threshold
since: 2026-05-25
status: active
fixable: false
description: '>= global_min_threshold (0.70)'
related_adrs: [ADR-0042, ADR-0063]

Rationale

.promptpolicy.yaml:6 の global_min_threshold: 0.70 以上必須。0.70 未満は CI fail (prompt-meta-lint.mjs:61-67)。詳細は §6 Threshold Rules 参照。

✅ PASS Example

eval_pass_threshold: 0.85    # gate0-triage (現実例、>= 0.70)
eval_pass_threshold: 0.70    # 最低ライン (許容)

❌ FAIL Example

eval_pass_threshold: 0.65    # global_min 0.70 未満 → CI fail

5.9 kv_key

id: kv_key
severity: error
category: required
since: 2026-05-25
status: active
fixable: false
description: Cloudflare KV active pointer (`bizlp:prompts:<name>`)
related_adrs: [ADR-0042, ADR-0063]

Rationale

LangGraph Pipeline (ADR-0019) が active prompt 取得時に参照する Cloudflare KV key。.promptpolicy.yaml:8 の kv_namespace_prefix: "bizlp:prompts" + prompt id で構成。

✅ PASS Example

kv_key: bizlp:prompts:gate0-triage

6. Threshold Rules

6.1 global_min_threshold

.promptpolicy.yaml:6 で global_min_threshold: 0.70 を SSoT として定義。全 prompt の eval_pass_threshold はこの値以上必須。0.70 未満を許容するケースは現時点でなし。

6.2 Special case (experimental allowlist)

実験段階の prompt で threshold 未確定の場合、.adr-lint-doc-consistency-allowlist.json の prompt_lint_special_cases フィールドに id pattern + skip_rules + reason で登録。初期 ≤ 3 件、超過は ADR 再評価。

6.3 threshold 改訂時の手順

global 値を 0.70 → 0.75 等に引き上げる場合:

1. .promptpolicy.yaml:6 編集
2. 既存 prompt 全件の eval_pass_threshold を再確認 (scripts/prompt-meta-lint.mjs 実行)
3. 0.75 未満の prompt は事前に基準調整 PR
4. 本 doc §6.1 を更新

7. Semver Rules

.promptpolicy.yaml:10-13 の semver_rules 定義 (ADR-0042 起源):

Semver 判断 flow chart

flowchart TD
    A[prompt 改修] --> B{output schema / required input 変更?}
    B -->|Yes| C[major bump: X.0.0]
    B -->|No| D{feature 追加 / few-shot / eval scope 拡張?}
    D -->|Yes| E[minor bump: X.Y.0]
    D -->|No| F{expression fix / typo / same-gen swap?}
    F -->|Yes| G[patch bump: X.Y.Z]
    F -->|No| H[bump 不要、commit のみ]

Model pin と semver の関係

• claude-sonnet-4-5 → 4-6 (same generation 内 swap): patch
• claude-sonnet → opus (family 変更): minor 以上、内容変更があれば major

8. State Transitions

.promptpolicy.yaml:15-17 の lifecycle:

draft → experiment → candidate → production → deprecated → archived
                                                    ↓
                                            90 日 auto-archive

各 transition の許容前提

90 日 auto-archive

deprecated 状態の prompt は .promptpolicy.yaml:17 の deprecated_auto_archive_days: 90 に従って 90 日後に自動 archive される。deprecation_at (yaml フィールド、optional) に deprecated 日時を記録し、weekly_cron が day diff を計算して archive 判定する。

State transition の手動 escalation

緊急 hotfix で experiment → production 直行が必要な場合、ADR-0042 §緊急パッチ手順 (line 要追記) に従い owner 承認 + revert plan 明示の PR で対応。candidate 段階を skip した場合は post-mortem 必須。

9. Legacy / Deprecated

該当 rule なし。本 doc 起案時点 (2026-05-25) で全 9 fields + threshold + semver + state すべて status: active。Deprecated 化された rule が出た場合は本節に「deprecated 日付」「代替 rule への移行手順」「最終削除予定日」を記載する。

既知の 3 way 整合 follow-up (Phase 2 実装予定)

ADR-0058 で確立した 3 way 整合 CI (scripts/adr-lint-doc-consistency.mjs) の 第四適用例として、本 doc も Phase 2 で:

• scripts/prompt-meta-lint.mjs の REQUIRED_FIELDS 配列 + threshold ロジック
• 本 doc §4 Summary Table / §5 Required Fields Detail / §6 / §7 / §8
• .promptpolicy.yaml の global_min_threshold / semver_rules / state_transitions

の 3 way 整合を CI で機械強制する。Phase 2 実装は main workspace 側で scripts/adr-lint-doc-consistency.mjs 拡張として進められる予定 (TODO_future.md §7 DOC-OPS に転記)。

10. Changelog