* docs(#2775): align package-legitimacy docs to the ADR-0656 registry-API gate security-model.md, USER-GUIDE.md, ARCHITECTURE.md, COMMANDS.md, FEATURES.md, and gsd-planner.md's STRIDE template (+ ja-JP mirrors) described the pre-ADR-0656 design: slopcheck as the install-or-degrade gate, with unavailability degrading every package to [ASSUMED]. ADR-0656 inverted this months ago — registry-API verdicts (npm/PyPI/ crates.io) are the gate; slopcheck is an optional escalate-only adapter that no shipped configuration wires. Verified every replacement claim against src/package-legitimacy.cts (checkPackages, classifyPackage, lookupNpm/lookupPypi/lookupCrates) via Memtrace before writing it, so the corrected prose matches the live implementation rather than restating the ADR from memory. Restored docs/explanation/security-model.md:79-84 (and its ja-JP mirror) to original wording after an orthogonal spec review caught that an earlier draft had edited the "Why WebSearch packages are always [ASSUMED]" paragraph — inside the range issue #2775 explicitly named as correct and to leave alone. The ja-JP mirror was missing the closing clause present in the corrected English original ("its absence leaves registry-API verdicts intact rather than downgrading everything to [ASSUMED]") — added for parity. This completes the ja-JP mirror the issue's acceptance criteria named explicitly. zh-CN/ko-KR/pt-BR (not named by #2775, but carrying the same stale design) get the mechanical portion of the same fix: command-string swaps, table headers, ARCHITECTURE.md diagram labels, and technical- term swaps that reuse a word already attested elsewhere in the same file (合法性/적법성/legitimidade for "legitimacy") — surrounding prose untouched. The remainder in those three locales — full-paragraph rewrites of the corrected degrade-path mechanism, deleted "External dependency" bullets, and "manually install slopcheck" code blocks — needs prose composed by a fluent speaker of each language and is filed as open-gsd/gsd-core#3002 with an exact file:line inventory. * test(#2775): acknowledge gsd-planner.md byte growth from the STRIDE-row fix agents/gsd-planner.md grew 14 bytes (49309 -> 49323) from the STRIDE supply-chain row correction (slopcheck -> package-legitimacy gate). Emitted agent/workflow files are byte-tracked; this fragment acknowledges the growth per tests/emitted-attribution.test.cjs's "differential attribution over the real tree" check. * docs(#2775): close ja-JP FEATURES.md gap; fix a ko-KR transliterated heading docs/ja-JP/FEATURES.md:2808 still read the katakana transliteration "スロップチェック verdict" in REQ-PKG-GATE-01 — invisible to a literal "slopcheck" grep, so it was missed when ja-JP parity was checked and declared complete. Corrected to "正当性判定" (legitimacy verdict), matching the term already established in ja-JP/explanation/ security-model.md and ja-JP/USER-GUIDE.md. This was the only remaining ja-JP gap; a full sweep for the transliterated form across docs/ja-JP/ now returns zero hits, and the ja-JP mirror is genuinely at parity. docs/ko-KR/USER-GUIDE.md:398's heading "슬롭체크 판정:" had the same transliteration problem. Fixed inline to "적법성 판정:", reusing the 적법성/legitimacy word already attested two lines below in the same table. A parallel sweep of zh-CN and pt-BR found no transliterated forms of "slopcheck" in either locale. The remaining transliterated occurrence in ko-KR (USER-GUIDE.md:406, the lead-in to the pip-install code block) needs prose composition like the rest of that block and is added to open-gsd/gsd-core#3002's inventory. * chore(#2775): backfill changeset PR number to 3010 --------- Co-authored-by: sim <sim@local>
This commit is contained in:
Tom Boucher
@@ -375,7 +375,7 @@ ui-phase → UI-SPEC.md (design contract, optional)
|
||||
plan-phase
|
||||
├── Research gate (blocks if RESEARCH.md has unresolved open questions)
|
||||
├── Phase Researcher → RESEARCH.md
|
||||
│ └── Package Legitimacy Gate: slopcheck on every package; [SLOP] removed,
|
||||
│ └── Package Legitimacy Gate: registry-API verdict on every package; [SLOP] removed,
|
||||
│ [SUS]/[ASSUMED] flagged; Audit table written to RESEARCH.md
|
||||
├── Planner (with reachability check) → PLAN.md files
|
||||
│ └── checkpoint:human-verify injected before [ASSUMED]/[SUS] installs;
|
||||
@@ -598,7 +598,7 @@ Runtime Engine (Claude Code / Gemini CLI)
|
||||
|
||||
| レイヤー | コンポーネント | アクション |
|
||||
|-------|-----------|--------|
|
||||
| 調査 | `gsd-phase-researcher` | `slopcheck install <pkgs> --json` を実行；`## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込む；RESEARCH.md が書かれる前に `[SLOP]` パッケージを除去 |
|
||||
| 調査 | `gsd-phase-researcher` | `gsd-tools query package-legitimacy check --ecosystem <npm\|pypi\|crates> <pkgs>` を実行；`## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込む；RESEARCH.md が書かれる前に `[SLOP]` パッケージを除去 |
|
||||
| 計画 | `gsd-planner` | 監査テーブルを読み取る；任意の `[ASSUMED]` または `[SUS]` インストールタスクの前に `checkpoint:human-verify` を挿入；`<threat_model>` に `T-{phase}-SC` STRIDE サプライチェーン行を追加 |
|
||||
| 実行 | `gsd-executor` | RULE 3 はパッケージインストールを自動修正スコープから除外；失敗したインストールはチェックポイントとして表面化し、サイレントな代替なし |
|
||||
|
||||
|
||||
@@ -185,13 +185,13 @@ GSD ワークスペースを管理 — リポジトリコピーと独立した `
|
||||
- `--view` 付き: 既存の RESEARCH.md を標準出力に表示し、起動なし。RESEARCH.md がない場合はエラー。
|
||||
|
||||
**パッケージ正当性ゲート（v1.42.1）:**
|
||||
リサーチャーが外部パッケージを推奨する場合、各パッケージに対して `slopcheck install <pkg> --json` を実行し、Registry、Age、Downloads、Source Repo、および slopcheck の評決を記録した `## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込みます。評決:
|
||||
リサーチャーが外部パッケージを推奨する場合、各パッケージに対して `gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkg>` を実行し、Registry、Age、Downloads、Source Repo、および正当性評決を記録した `## Package Legitimacy Audit` テーブルを RESEARCH.md に書き込みます。評決はライブのレジストリ API（npm、PyPI、crates.io）から計算されます:
|
||||
|
||||
- `[SLOP]` — パッケージは RESEARCH.md から完全に削除され、プランナーには届かない
|
||||
- `[SUS]` — パッケージにフラグが付けられ、プランナーはインストールタスクの前に `checkpoint:human-verify` を挿入
|
||||
- `[OK]` — パッケージが承認され、チェックポイントは追加されない
|
||||
|
||||
WebSearch から取得したパッケージは `[ASSUMED]`（`[VERIFIED]` ではない）とタグ付けされ、`[SUS]` と同様に扱われます — インストール前に人間によるチェックポイントが設けられます。`slopcheck` がインストールできない場合、すべての推奨パッケージは `[ASSUMED]` とタグ付けされ、ゲートが設けられます。
|
||||
WebSearch から取得したパッケージは `[ASSUMED]`（`[VERIFIED]` ではない）とタグ付けされ、`[SUS]` と同様に扱われます — インストール前に人間によるチェックポイントが設けられます。レジストリルックアップが失敗した場合はスローせず `[SUS]` にデグレードされるため、サイレントに承認されることはありません。`slopcheck` はオプションのエスカレート専用アダプターであり、出荷される設定では配線されていません。ゲートの動作に必須ではありません。
|
||||
|
||||
詳細については、[ユーザーガイドのパッケージ正当性ゲート](../USER-GUIDE.md#package-legitimacy-gate-v1421)（チェックポイント形式、評決テーブル、トラブルシューティングを含む）を参照してください。
|
||||
|
||||
|
||||
@@ -2805,7 +2805,7 @@ Source commit: abc1234 (3 commits behind HEAD)
|
||||
- Executor のインストール失敗は、同様の名前のパッケージを自動的に試みる代わりに人間の確認のために停止する。
|
||||
|
||||
**要件:**
|
||||
- REQ-PKG-GATE-01: リサーチはパッケージレジストリ、年齢、ダウンロード/ソースシグナル、スロップチェック verdict、および処分を記録しなければならない。
|
||||
- REQ-PKG-GATE-01: リサーチはパッケージレジストリ、年齢、ダウンロード/ソースシグナル、正当性判定、および処分を記録しなければならない。
|
||||
- REQ-PKG-GATE-02: プランナーは実行前に未検証または疑わしいパッケージのインストールをゲートしなければならない。
|
||||
- REQ-PKG-GATE-03: Executor はパッケージマネージャーのインストール失敗後にパッケージ名を自動置換してはならない。
|
||||
|
||||
|
||||
@@ -382,8 +382,8 @@ AI コーディングツールはパッケージ名を幻覚することがあ
|
||||
```markdown
|
||||
## Package Legitimacy Audit
|
||||
|
||||
| Package | Registry | Age | Downloads | Source Repo | slopcheck | Disposition |
|
||||
|---------|----------|-----|-----------|-------------|-----------|-------------|
|
||||
| Package | Registry | Age | Downloads | Source Repo | Verdict | Disposition |
|
||||
|---------|----------|-----|-----------|-------------|---------|-------------|
|
||||
| express | npm | 13 yrs | 100M+/wk | github.com/expressjs/express | [OK] | Approved |
|
||||
| some-new-util | npm | 3 days | 47 | none | [SLOP] | REMOVED |
|
||||
| api-bridge | npm | 6 mo | 1.2k/wk | github.com/user/api-bridge | [SUS] | Flagged |
|
||||
@@ -395,7 +395,7 @@ AI コーディングツールはパッケージ名を幻覚することがあ
|
||||
|
||||
**実行中** — インストールが失敗した場合、エグゼキューターはチェックポイントを提示して停止し、代替案をサイレントに試みません。
|
||||
|
||||
**スロップチェックの判定:**
|
||||
**正当性の判定:**
|
||||
|
||||
| 判定 | 意味 | GSD のアクション |
|
||||
|---------|---------|------------|
|
||||
@@ -403,12 +403,7 @@ AI コーディングツールはパッケージ名を幻覚することがあ
|
||||
| `[SUS]` | 疑わしいシグナル | フラグ付き; プランナーが `checkpoint:human-verify` を追加 |
|
||||
| `[SLOP]` | 高確信度の幻覚 | RESEARCH.md から削除; プランナーに到達しない |
|
||||
|
||||
slopcheck を手動でインストールするには:
|
||||
|
||||
```bash
|
||||
pip install slopcheck
|
||||
# verify: slopcheck install express --json
|
||||
```
|
||||
判定はライブのレジストリ API（npm、PyPI、crates.io）から計算されます — 個別にインストールするツールはありません。`slopcheck` はオプションのエスカレート専用アダプター（判定を引き上げることはできますが、引き下げることはできません）です。出荷される設定はこれを配線しておらず、その不在によってゲートの動作が変わることはありません。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ AI モデルはパッケージ名を幻覚します。これはまれな失敗
|
||||
|
||||
ゲートは 3 つのパイプラインステージにわたって動作します：
|
||||
|
||||
**調査ステージ。** `gsd-phase-researcher` が外部パッケージを推奨するとき、それぞれに対して `slopcheck install <pkgs> --json` を実行します。結果は `RESEARCH.md` の `## Package Legitimacy Audit` テーブルに書き込まれます。`[SLOP]`（高信頼度の幻覚または攻撃者登録済み）とタグ付けされたパッケージは、ファイルが保存される前に **`RESEARCH.md` から完全に除去されます**。それらはプランナーに届きません。
|
||||
**調査ステージ。** `gsd-phase-researcher` が外部パッケージを推奨するとき、それぞれに対して `gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>` を実行します。評決（`OK|SUS|SLOP`）はライブのレジストリ API から、しきい値 `{ minAgeDays: 30, minWeeklyDownloads: 1000, requireRepo: true }` に基づいて計算され、非存在および疑わしい `postinstall` スクリプトに対する終端ショートサーキットも含まれます。結果は `RESEARCH.md` の `## Package Legitimacy Audit` テーブルに書き込まれます。`[SLOP]`（高信頼度の幻覚または攻撃者登録済み）とタグ付けされたパッケージは、ファイルが保存される前に **`RESEARCH.md` から完全に除去されます**。それらはプランナーに届きません。
|
||||
|
||||
**計画ステージ。** `gsd-planner` は監査テーブルを読み取ります。`[SUS]`（疑わしい：新規登録、低ダウンロード数、ソースリポジトリなし、または人気パッケージに近い命名パターン）または `[ASSUMED]`（直接レジストリ検証ではなく WebSearch から取得）とタグ付けされたパッケージについて、プランナーはインストールステップの前に **`checkpoint:human-verify` タスクを挿入します**。チェックポイントにはレジストリページへの直接リンクと、確認すべき具体的な事項が含まれます：メンテナー履歴、イシュートラッカーの活動、疑わしいインストールスクリプトがないこと。
|
||||
|
||||
@@ -36,19 +36,19 @@ WebSearch を通じて発見されたパッケージ名は、`npm view` が成
|
||||
|
||||
### エコシステムカバレッジ
|
||||
|
||||
調査者は単一の汎用チェックではなく、レジストリ固有の検証コマンドを使います：
|
||||
ゲートは単一の汎用チェックではなく、各エコシステムのレジストリ API から直接シグナルを解決します：
|
||||
|
||||
- Node.js：`npm view`
|
||||
- Python：`pip index versions`
|
||||
- Rust：`cargo search`
|
||||
- Node.js：`registry.npmjs.org`（登録日、リポジトリ URL、`postinstall` スクリプト）と `api.npmjs.org/downloads`（週間ダウンロード数）
|
||||
- Python：`pypi.org/pypi/<pkg>/json`（登録日、リポジトリ URL）
|
||||
- Rust：crates.io API（登録日、週間ダウンロード数、リポジトリ URL）
|
||||
|
||||
これは 2025 年の USENIX 研究によると約 9% の割合で発生するクロスエコシステム幻覚をカバーします——AI が実際に使用しているエコシステムには存在しない別のエコシステムのパッケージを推奨するケース。
|
||||
|
||||
### グレースフルデグレデーション
|
||||
|
||||
`slopcheck` が利用できない場合（インストールされていない、または調査時に pip インストールが失敗した）、GSD は可能な限り厳格なフォールバックを適用します：**すべての推奨パッケージが `[ASSUMED]` とタグ付けされ**、プランナーはすべてのインストールを `checkpoint:human-verify` タスクでゲートします。調査と計画は通常どおり進行します——システムはツールの依存関係の欠落でハードフェイルすることはありません。これは通常フローより意図的に厳格です：slopcheck の利用不可は、すべてのパッケージインストールに人間のチェックポイントを付与することを意味します。
|
||||
各レジストリアダプターには 5 秒のタイムアウトがあり、失敗したルックアップに対しては例外をスローせずデグレードされた（すべて null の）シグナルを返します。欠落したシグナルは `unknown-age` / `unknown-downloads` の理由として現れ、パッケージを `[SUS]` に押し上げます——そして `[SUS]` は `[ASSUMED]` と同じ `checkpoint:human-verify` タスクでゲートされます。ゲートはサイレントにではなく人間のレビューに向かって失敗し、調査と計画は通常どおり進行します：ネットワークやツールの障害でハードフェイルすることはありません。
|
||||
|
||||
`slopcheck` ツールは MIT ライセンスで pip インストール可能です。廃止された場合でも、`[ASSUMED]` ゲートフォールバックにより、人間チェックポイントカバレッジが維持されます。
|
||||
`slopcheck` はオプションのアダプターであり、評決をエスカレートすることしかできず（引き下げることはできません）、インストールまたはデグレードのゲートではありません。出荷される設定はこれを配線しません。その不在は、すべてを `[ASSUMED]` に格下げするのではなく、レジストリ API の評決をそのまま維持します。
|
||||
|
||||
---
|
||||
|
||||
@@ -99,7 +99,7 @@ GSD のランタイム動作の上流で、`open-gsd` 組織はリポジトリ
|
||||
|
||||
**パッケージ正当性ゲートが低減するもの：** 幻覚されたまたは攻撃者登録済みのパッケージが人間のチェックポイントなしに `npm install` に届く確率。`[SLOP]` ゲートは高信頼度の悪質なパッケージを完全に除去します；`[SUS]`/`[ASSUMED]` ゲートは実行前に人間のレビューを要求します。これによりスロップスクワッティング攻撃の成功コストが実質的に引き上げられます。
|
||||
|
||||
**パッケージ正当性ゲートが排除しないもの：** 後で侵害された正規パッケージ（アカウント乗っ取り、そのパッケージ自体のツリーでの依存関係混同）は、調査時に登録シグナルを確認する slopcheck ではキャッチされません。その種の攻撃に対するコントロールは、依存関係整合性レイヤーのロックファイルと `npm audit` です。
|
||||
**パッケージ正当性ゲートが排除しないもの：** 後で侵害された正規パッケージ（アカウント乗っ取り、そのパッケージ自体のツリーでの依存関係混同）は、調査時に登録シグナルを確認するレジストリ API ゲートではキャッチされません。その種の攻撃に対するコントロールは、依存関係整合性レイヤーのロックファイルと `npm audit` です。
|
||||
|
||||
**プロンプトインジェクション防御が低減するもの：** 計画アーティファクト内のユーザー制御テキストがエージェントの指示を正常に上書きする確率。既知のインジェクション形式のパターンマッチングは一般的なケースをキャッチします；新しいジェイルブレイクや低シグナルのインジェクションは検出されない可能性があります。アドバイザリーのみの姿勢は、検出がログに記録されるがブロックされないことを意味します——検出でハード停止するコストではなく、ワークフロー継続性を保持する意図的な選択。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user