docs(#2775): align package-legitimacy docs to the ADR-0656 registry-API gate (#3010)

* 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
2026-08-02 20:24:42 -04:00
committed by GitHub
parent 97f2af29da
commit de78f2eef2
26 changed files with 96 additions and 88 deletions

View File

@@ -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` です。
**プロンプトインジェクション防御が低減するもの:** 計画アーティファクト内のユーザー制御テキストがエージェントの指示を正常に上書きする確率。既知のインジェクション形式のパターンマッチングは一般的なケースをキャッチします;新しいジェイルブレイクや低シグナルのインジェクションは検出されない可能性があります。アドバイザリーのみの姿勢は、検出がログに記録されるがブロックされないことを意味します——検出でハード停止するコストではなく、ワークフロー継続性を保持する意図的な選択。