Skip to content

docs: OC-D5 re-land on dev (was only on fix-merge-perm-leak) #300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
terisuke merged 2 commits into from
Aug 8, 2026
Merged

docs: OC-D5 re-land on dev (was only on fix-merge-perm-leak) #300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
583408a
docs: remove ghost guardrail refs and real-value ADR evidence (OC-D5)
terisuke Aug 8, 2026
882ecb3
docs: drop remaining instrumentation filename string for OC-D5 grep
terisuke Aug 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 2 additions & 18 deletions packages/guardrails/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ This package exists to preserve the operating model imported from `claude-code-s
- pointer-based instructions instead of bloated always-loaded prompts
- runtime verifiability over "the code exists, so it must work"

Those principles come from `claude-code-skills` epic `#130` and are tracked in this fork under `docs/ai-guardrails/`.
Those principles come from `claude-code-skills` epic `#130` and are tracked in this fork under `specs/ai-guardrails-anti-patterns.md`.
They now also explicitly inherit Anthropic's `The Complete Guide to Building Skills for Claude` as the BDF-equivalent source for progressive disclosure, use-case-first design, and measurable testing discipline.

## Positioning
Expand Down Expand Up @@ -63,23 +63,7 @@ Planned next slices are tracked in the fork:

## AI agent instrumentation quality gate

The packaged guardrail plugin enforces AI agent instrumentation and metric changes through source-level hooks. It blocks global monkey patches during edit hooks and blocks PR/merge commands when instrumentation evidence is missing.

Traceability Matrix:

| Acceptance Criteria | Implementation code path |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Source-level hooks are required and global monkey patches are prohibited | `profile/plugins/guardrail-instrumentation.ts#createInstrumentationHandlers` |
| Instrumentation/cross-cutting PRs require integration or smoke coverage | `profile/plugins/guardrail-instrumentation.ts#integrationTestEvidence` |
| Metric semantics and source code path must be explicit | `profile/plugins/guardrail-instrumentation.ts#metricSemanticsEvidence` |
| Unmeasurable metrics must not be claimed | `profile/plugins/guardrail-instrumentation.ts#unmeasurableMetricClaim` |
| Optional dependency availability must be probed before use | `profile/plugins/guardrail-instrumentation.ts#dependencyProbeEvidence` |
| Resource lifecycle cleanup/finally paths are required for instrumentation resources | `profile/plugins/guardrail-instrumentation.ts#resourceLifecycleEvidence` |
| Unavailable metric state must carry an explicit reason instead of null | `profile/plugins/guardrail-instrumentation.ts#nullUnavailableReason` |

Metric semantics: `instrumentation_quality_state` records only this gate's evaluated state (`done` or `blocked`) for the current diff. `instrumentation_quality_blockers` records concrete blocker strings from the code path above; it does not claim runtime observability metrics that the guardrail cannot directly measure.

Dependency availability probe: PR/merge evidence must show the dependency, provider, SDK, CLI, or MCP dependency was checked and that unavailable data includes `unavailable_reason` or equivalent `reason`.
Historical note: a Traceability Matrix that pointed at a deleted instrumentation plugin (removed in #277) was retired from this README. Live push protection is implemented by `profile/plugins/guardrail-git.ts`. Acceptance evidence for anti-pattern work lives in `specs/ai-guardrails-anti-patterns.md`.

## Usage

Expand Down
6 changes: 3 additions & 3 deletions specs/ai-guardrails-anti-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,7 @@ ADR・ハンドオーバー文書は**ソフト規約**として残すが、実
| 各ガードが「無効化すると落ちる」反証を持つ | 実装 PR + テスト | 実装 Issue の各 PR | 未着手 |
| 各ガードが「過剰制限しない」(安全な操作が通る)陰性テストを持つ | 実装 PR + テスト | 実装 Issue の各 PR | 未着手 |
| CI が変更種別で層化される(docs PR にフル CI が走らない) | CI ワークフロー diff | 実装 Issue(J) | 未着手 |
| guardrails profile にガードが追加される | 実装 diff | `packages/guardrails/profile/` | 未着手 |
| パターン K(SSOT)が command/plugin/skill + pin 結線テストを持つ | 実装 PR + テスト | Issue #288 | 未着手 |
| パターン L–O(テスト検証信頼性)が plugin/command/skill + 結線ヘルパーを持つ | 実装 PR + テスト | Issue #290 | 未着手 |
| guardrails profile にガードが追加される | 実装 diff | PR #285 `3522f97ec5` 2026-08-03 | 取得済み |
| パターン K(SSOT)が command/plugin/skill + pin 結線テストを持つ | 実装 PR + テスト | PR #289 `2c33562a54` 2026-08-03 | 取得済み |
| パターン L–O(テスト検証信頼性)が plugin/command/skill + 結線ヘルパーを持つ | 実装 PR + テスト | PR #291 `1883ff4f14` 2026-08-03。付記: entrypoint pin が #292 自己被弾の直接トリガー | 取得済み |
| 全リポジトリ(Grift 含む)でガードが効く | 運用記録 | 次回以降の PR | 未着手 |
Loading