---
name: project-step1388-5a-pathway-hook-integration-2026-08-23
description: STEP 1369 Phase 8 - 5A oughtctl pathway hook 4 種統合 (git push / gh CLI / SCPI / rm) = 4D 導入禁止 解除 SW gate 達成
metadata: 
  node_type: memory
  type: project
  originSessionId: 3acd3853-c124-47b1-974e-9d8c55c72877
  modified: 2026-08-23T00:01:56.239Z
---

# STEP 1388 — 5A pathway hook 統合 (STEP 1369 Phase 8, 2026-08-23)

## 契機
- STEP 1387 (Phase 7 帳簿 3 v0.1) close report で 私 deferred list 冒頭:
  1. 5A oughtctl の **pathway hook 統合** (git push hook / gh CLI wrapper / SCPI proxy / rm 安全 wrapper) = 4D 導入禁止 解除 gate
- 藤本さん directive: 「1. 5A pathway hook 統合 (git push hook / gh CLI / SCPI proxy / rm 安全 wrapper) = 4D 導入禁止 解除 gate 此方を進めて頂けますか？」
- 「命名 → v0.1 spike → 実 pipeline 統合」 3 段の 第 3 段 (実 pipeline 統合) の 5A 側 arc

## 実装 — 4 pathway hook + 共通 library + install helper + test

### `scripts/oughtctl/hooks/_common.py` — shared library
- **require_approval(action, target, ledger_path, approval_id, allow_skip_env)** → (bool, dict)
- **mark_executed(entry_id)** → subprocess で `oughtctl execute <id>` を呼ぶ
- **print_denial(action, target, info)** → 標準化された 却下 message (次にすべき 4 手順を stderr 出力)
- Emergency bypass: `OUGHTCTL_SKIP=1` + `OUGHTCTL_SKIP_REASON` (>= 20 chars 必須) で 一時 bypass、 audit log entry (status=bypass) を ledger に 追記
- approval_id resolution priority: 引数 > `OUGHTCTL_APPROVAL_ID` env > `OUGHTCTL_SKIP` bypass

### `scripts/oughtctl/hooks/pre-push` — git pre-push hook
- Python shebang (git-bash + Windows 対応)
- 標準入力から git が渡す 4 field format (local_ref/local_sha/remote_ref/remote_sha) 各 push ref parse
- Zero-SHA local (`0`×40) は **delete** として 特別 flag
- target = `"<remote_name> <remote_ref1>,<remote_ref2>,..."` で approval match
- Action = `"push"`
- approve 済 なら mark_executed し 0 return (git が push 進行)、 否 なら 2 return で block
- git 側 push 失敗時の mark_executed rollback は 未装備 (別 arc: post-update hook or verify hook)

### `scripts/oughtctl/hooks/gh-wrapper.py` — gh CLI wrapper
- 17 irreversible pattern 検出: `release create/delete/edit/upload` / `pr merge/close/create` / `issue close/delete` / `repo delete/archive` / `workflow run/disable` / `secret set/remove/delete` / `gist delete`
- `api -X DELETE/PUT/POST/PATCH` は method flag parse で 検出
- `-h`/`--help`/`--version` は explicit pass-through
- **self-recursion 予防**: `find_gh_binary()` は wrapper 自身の dir を PATH 検索から exclude、 `OUGHTCTL_GH_BIN` env で 明示 override 可能
- Action = `"publish"` (gh CLI は publish domain)、 target = `"<gh subcmd + args[:4]>"` for approval matching

### `scripts/oughtctl/hooks/scpi_proxy.py` — SCPI actuator gate
- 4 classification: **READONLY** (`MEAS:` / `READ` / `FETC` / `SYST:ERR?` / `*IDN?` / any `?`-suffix) / **ACTUATOR** (`SOUR:` / `OUTP ON` / `VOLT` / `CURR` / `LOAD` / `RES` / `POW`) / **DANGEROUS** (`*RST` / `RESET` / `INIT` / `ABORT` / `TRIG:IMM`) / **UNKNOWN** (保守的に approval 要求)
- READONLY は approval 不要 pass-through (measurement は 安全な計測 subset)
- ACTUATOR/DANGEROUS/UNKNOWN は approval 要 (action=`"hardware"`、 target=`"<device> :: <command>"`)
- 2 mode: Python library API (`check_scpi_command`) + CLI (`check-cmd` / `send`)
- v0.1 spike は 実 hardware 送信 未実装、 simulated print (`[SCPI SIM]`) のみ = 実 benchtop-mcp SCPI stack 統合は 別 arc
- STEP 1345 benchtop-mcp SafetyGate との 相補: SafetyGate = SCPI argument-level hazard 検出 (Kikusui Siemens 混同 等)、 本 proxy = command-class gate (RO/ACT/DNG)

### `scripts/oughtctl/hooks/rm-safe.py` — rm safety wrapper
- 3 classification:
  - **FORBIDDEN** (常時 block、 approval あっても 通さない): `/` `/*` `/**` `\` `C:\` `C:/` `~` `~/` `/home` `/Users` `/etc` `/var` `/usr` `/bin` `$HOME` `%USERPROFILE%` + `len <= 2` root paths
  - **DANGEROUS** (approval 要): `.git/` `backup` `.env` `credentials` `secret` `PAT` `private_key` `id_rsa` `.ssh/` `node_modules` sensitive path patterns / `-r` with wildcard `*` `?` / `-r` on dir > 100 files / **strict default: 任意の `-r` は approval 要**
  - **SAFE** (pass-through): non-recursive rm of specific files
- self-recursion 予防: gh-wrapper と 同 pattern (`find_rm_binary()` + wrapper dir exclude + `OUGHTCTL_RM_BIN` override)
- Action = `"delete"`、 target = `"<argv 全 space join>"[:200]`

### `scripts/oughtctl/hooks/install.py` — installer helper
- `--install pre-push`: symlink (Unix) or copy (Windows) → `.git/hooks/pre-push`、 既存 hook を `.backup-before-oughtctl` に 退避
- `--install gh` / `--install rm`: shell alias 提案 print (bash/zsh + PowerShell 両対応)
- `--install scpi`: import 方法 print (library として consume する 想定)
- `--install all`: 上記 全 順次実行
- `--dry-run` support

## Test (test_hooks.py) — 58 assertion

- **require_approval 6**: missing id / valid / wrong action / wrong target / bypass without reason (rejected) / bypass with reason (allowed + ledger audit entry)
- **scpi_proxy 5**: 5 readonly patterns / 5 actuator patterns / 4 dangerous patterns / readonly bypasses approval / actuator requires approval flow
- **gh-wrapper 3**: 5 readonly (pr list/view/repo view/api /user/--help) all classified readonly / 7 irreversible patterns all detected / api -X DELETE method detection + api /user default GET readonly
- **rm-safe 5**: 4 FORBIDDEN paths / 4 DANGEROUS sensitive patterns / small recursive DANGEROUS / single-file SAFE / .git DANGEROUS
- Debug 1: SyntaxWarning `\ ` in rm-safe.py docstring (`C:\` escape) → replaced with `C-drive-root`

Result: **58/58 PASS**、 warning 全 clean

## Verify
- Site: md5 `f51471cf3b18fe919eb1eb4204eecde8`、 878 行 (前 874 +4)
- Commit `90f498ced` push (0a7b199e9..90f498ced、 previous HEAD = 別タブ auto site rebuild 挟まっていた)、 10 files/1266+/8-
  - 2 M: public + dist-renderer/tools/step-1369-five-machines-index/index.html
  - 8 A: scripts/oughtctl/hooks/{_common.py + pre-push + gh-wrapper.py + scpi_proxy.py + rm-safe.py + install.py + test_hooks.py + README.md}
- CF Pages deploy 103,134 bytes、 HTTP 200
- Phase 8 content marker (STEP 1388/Phase 8/pathway hook 4 種/4D 導入禁止 解除/test 58/58/pre-push/gh-wrapper/scpi_proxy/rm-safe): **8 hits**
- Test: 58/58 PASS
- URL: https://rei-aios.pages.dev/tools/step-1369-five-machines-index/

## 4D 作用hardware 導入禁止 解除 gate 状態 (最新)
- **SW side (5A pathway hook)**: 骨格 完了 ✓
  - 4 hook (pre-push + gh + scpi + rm) 全 実装
  - 共通 library で verify + mark_executed + emergency bypass 統一
  - 58/58 test coverage
  - install helper で 導入容易
- **HW side (実 4D hardware)**: 依然 blocker ⏸
  - Kikusui PLZ-5W / Zaber ステージ / Peltier / E-stop / interlock relay = 全 未取得
  - 藤本さん judgment + 予算 stance 待ち (STEP 1383 4A/4B/4C/4D BOM 参照)
= **SW gate は 満たす、 HW gate は 残る** ([[project-step1383-four-physical-auxiliary-machines-2026-08-23]] 4D 導入禁止 discipline 継続)

## SAC-4 47 教訓 Phase 3-8 6 連続 clean 成功
- Phase 3+4+5+6+7+8 = 6 連続 clean commit (Phase 3=252+, 4=264+, 5=468+, 6=1391+, 7=1440+, 8=1266+)
- 全 pre-staged 0 件 confirm 後 明示 file path のみ add
- 他タブ push 競合は Phase 4 で 1 度 → `git pull --rebase` autostash / Phase 8 で 1 度 (auto site rebuild) → git 自動 rebase clean
- 6 Phase 全て oukc/* sweep-in なし

## Honest scope
1. 全 4 hook は **v0.1 骨格 spike のみ** = 実 pathway (git push / gh CLI / SCPI stack / rm) は 外部 binary に 委譲、 hook 自体は shim
2. classification は **heuristic** = gh 17 pattern + rm パス pattern + SCPI regex = 網羅性 未検証、 false-negative 予防のため 「不明時は 保守的に approval 要求」 default
3. **TOCTOU race condition 未装備**: approval check → 実 action の 間で ledger 状態変化 (approval revoked 等) は 検出しない、 別 arc
4. **mark_executed のタイミング**: pre-push は approval verify 後即 mark = git push 失敗時も executed とマーク、 別 arc で post-action verify hook 検討
5. **bypass audit** は ledger 記録のみ、 定期 review protocol 別 arc (audit log rotation も 別 arc)
6. **実運用 evidence 未取得**: 本 spike は unit test 58/58 のみ、 実 git repo で pre-push hook installed の end-to-end + 実 SCPI target 送信 + 実 gh CLI wrapper 実運用 は 別 arc (pilot run 段階)
7. Windows での git pre-push hook 動作は git-bash + symlink permission 依存、 install.py が copy fallback で 対応するが 実運用 pilot 未実施
8. gh-wrapper の `-X` method detection は shorter form のみ、 環境変数 `GH_HTTP_METHOD` 経由の 設定は 未対応
9. scpi_proxy の実 benchtop-mcp SCPI 統合は 未装備 (現状 simulated `[SCPI SIM]` print のみ)、 別 arc
10. rm-safe の 「>100 files threshold」 は Path.rglob で 実行、 大 dir (100000+ files) では 遅い、 別 arc で size 上限 or timeout 設計

## Deferred (残 arc)
1. **HW side 4D hardware 取得** = 藤本さん judgment 依然待ち (STEP 1383 BOM 参照、 4B 環境 ~¥3,600 最低)
2. 各 hook の **実運用 pilot** (git pre-push installed + gh alias set + rm alias set + scpi 実 benchtop stack 統合)
3. **TOCTOU race condition 対策**: 実 action 直前 再 verify + `mark_pending` state + post-action `mark_executed`
4. **post-action verify hook** (git push 失敗時の rollback、 gh CLI 非zero exit 時 rollback)
5. **bypass audit periodic review protocol**: bypass entry の 定期 review + revoke workflow
6. 5C 限界機械 → 6 橋機械 実 wire (discovery-worker STEP 1382 上流に 5C 挿入)
7. 5D 意味機械 → 4A + 4C metadata 統合 (ProvenanceRecord schema 拡張)
8. 5A oughtctl_id → 5D annotate 実 link (承認 chain と 意味 metadata の 統合)
9. 5B frames の retroactive 記録 (2026-08-22 整理対象 10 件 + 46 vs 56 過去記録)
10. 6 橋機械 実 stack routing 統合
11. MEMORY.md 自動 compact tool (pattern 化 3 度目)
12. 図の 完全 dependency graph 版

## 関連
- [[project-step1387-ledger-machines-5B-5C-5D-v01-2026-08-23]] Phase 7 直前
- [[project-step1386-five-arc-sequential-execution-2026-08-23]] Phase 6 (5A oughtctl core origin)
- [[project-step1383-four-physical-auxiliary-machines-2026-08-23]] 4D 導入禁止 discipline + 4D actuator_stub.check_5a_approval() の 消費 side
- [[project-step1345-benchtop-provenance-spike-2026-08-19]] benchtop-mcp SafetyGate (SCPI 側 相補 layer)
- [[feedback-peace-axiom-hardware-io-extension-2026-08-17]] 4D 安全 discipline origin
- [[feedback-super-naming-siren-family-pattern]] 「v0.1 spike 済 = 完全実装ではない」 継承
- [[feedback-projection-self-audit-pattern]] SAC-4 47 教訓 Phase 3-8 6 連続 clean 成功
- [[feedback-all-research-site-reflection-default]] 2026-08-06 protocol 継続
- [[feedback-no-rush-publication]] 「命名 → v0.1 spike → 実 pipeline 統合」 3 段の 5A 側 第 3 段 到達