@joshuafolkken/kit 1.1128.0 → 1.1166.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/investigator.md +17 -0
- package/.claude/settings.json +5 -4
- package/.claude/skills/epic-commands/SKILL.md +27 -239
- package/.claude/skills/epic-commands/epic-bundle.md +115 -0
- package/.claude/skills/epic-commands/execution-waves.md +126 -0
- package/.claude/skills/workflow-commands/SKILL.md +48 -194
- package/.claude/skills/workflow-commands/background-commands.md +1 -1
- package/.claude/skills/workflow-commands/backlogrun-child.md +12 -123
- package/.claude/skills/workflow-commands/backlogrun-lanes.md +11 -60
- package/.claude/skills/workflow-commands/backlogrun-park.md +10 -8
- package/.claude/skills/workflow-commands/backlogrun-progress.md +19 -175
- package/.claude/skills/workflow-commands/backlogrun-recovery.md +155 -0
- package/.claude/skills/workflow-commands/backlogrun-steps.md +64 -144
- package/.claude/skills/workflow-commands/backlogrun.md +5 -4
- package/.claude/skills/workflow-commands/chain-rule.md +3 -2
- package/.claude/skills/workflow-commands/delegation.md +7 -3
- package/.claude/skills/workflow-commands/entry-sequence.md +62 -0
- package/.claude/skills/workflow-commands/followup.md +104 -181
- package/.claude/skills/workflow-commands/fullrun-steps.md +8 -9
- package/.claude/skills/workflow-commands/fullrun.md +16 -73
- package/.claude/skills/workflow-commands/halfrun.md +10 -36
- package/.claude/skills/workflow-commands/into-target.md +4 -4
- package/.claude/skills/workflow-commands/issue-comments.md +7 -8
- package/.claude/skills/workflow-commands/issue-scout.md +6 -6
- package/.claude/skills/workflow-commands/kickoff.md +6 -6
- package/.claude/skills/workflow-commands/needs-human-review.md +6 -6
- package/.claude/skills/workflow-commands/observation-filing.md +21 -172
- package/.claude/skills/workflow-commands/observation-ledger.md +150 -0
- package/.claude/skills/workflow-commands/pre-gate-cut.md +33 -93
- package/.claude/skills/workflow-commands/prerequisite.md +6 -6
- package/.claude/skills/workflow-commands/progress-watcher.md +90 -0
- package/.claude/skills/workflow-commands/prrun.md +5 -5
- package/.claude/skills/workflow-commands/retrospective.md +9 -9
- package/.claude/skills/workflow-commands/split-assessment.md +2 -2
- package/.claude/skills/workflow-commands/target-repository.md +2 -2
- package/.claude/skills/workflow-commands/working-tree-hold.md +7 -5
- package/.codex/hooks.json +4 -4
- package/AGENTS.md +1 -6
- package/CLAUDE.md +58 -120
- package/GEMINI.md +1 -6
- package/SECURITY.md +1 -0
- package/dist/CLAUDE.md +58 -120
- package/dist/hooks/batch-guard.js +4 -4
- package/dist/hooks/{chunk-MKVGBQPA.js → chunk-5KTCMCOT.js} +14 -1
- package/dist/hooks/{chunk-NXYMNPUQ.js → chunk-A6P7PN7P.js} +59 -21
- package/dist/hooks/{chunk-77J7IEQM.js → chunk-ANJ2WGFD.js} +1 -1
- package/dist/hooks/{chunk-4JZDP5X5.js → chunk-DYAVAM6S.js} +572 -127
- package/dist/hooks/{chunk-7HVB7SZG.js → chunk-ENA7P5FB.js} +4 -4
- package/dist/hooks/{chunk-M7QKEKWO.js → chunk-GU5MATVE.js} +214 -85
- package/dist/hooks/chunk-GYNGP7HI.js +56 -0
- package/dist/hooks/{chunk-5SD2YM7Z.js → chunk-URJA6XY4.js} +4 -4
- package/dist/hooks/{chunk-XYUIQOW3.js → chunk-V2BTOZHT.js} +6 -4
- package/dist/hooks/{chunk-AIOIOMPX.js → chunk-ZDZ555YH.js} +225 -78
- package/dist/hooks/codex-hook-adapter.js +10 -10
- package/dist/hooks/duplicate-read-guard.js +5 -5
- package/dist/hooks/format-edited.js +2 -2
- package/dist/hooks/inputs.json +186 -184
- package/dist/hooks/investigation-guard.js +5 -5
- package/dist/hooks/pretool-guard.js +11 -10
- package/dist/hooks/stop-guard.js +5 -5
- package/dist/josh.js +33 -3
- package/dist/version/index.js +5 -1
- package/package.json +7 -4
- package/prompts/collaboration-workflow/file-edits.md +11 -10
- package/prompts/collaboration-workflow/gh-rest.md +2 -4
- package/prompts/collaboration-workflow/glossary.md +1 -1
- package/prompts/collaboration-workflow/issue-citation.md +5 -9
- package/prompts/collaboration-workflow/issue-template.md +40 -115
- package/prompts/collaboration-workflow/operating-rules.md +4 -5
- package/prompts/collaboration-workflow/output-bounds.md +12 -78
- package/prompts/collaboration-workflow/overview.md +7 -13
- package/prompts/collaboration-workflow/plan-comment.md +11 -39
- package/prompts/collaboration-workflow/principles.md +3 -4
- package/prompts/collaboration-workflow/report-format.md +28 -74
- package/prompts/collaboration-workflow/residency.md +12 -109
- package/prompts/collaboration-workflow/rule-delivery.md +98 -97
- package/prompts/collaboration-workflow/shell-body.md +3 -13
- package/prompts/collaboration-workflow/turn-batching.md +14 -88
- package/prompts/collaboration-workflow/upstream-interrupt.md +12 -14
- package/prompts/collaboration-workflow/wip-cap.md +6 -45
- package/prompts/collaboration-workflow.md +1 -13
- package/prompts/review-rubric.md +8 -71
- package/prompts/review.md +25 -55
- package/prompts/testing-guide.md +18 -67
- package/scripts/agent/agent-role-profile.ts +1 -1
- package/scripts/agent/codex-hooks.ts +3 -12
- package/scripts/backlog/backlog-budget.ts +1 -1
- package/scripts/backlog/backlog-drive-cli.ts +4 -3
- package/scripts/backlog/backlog-drive-offer-argv.ts +10 -1
- package/scripts/backlog/backlog-offer.ts +6 -6
- package/scripts/behavior/behavior-rules.ts +11 -4
- package/scripts/delegation/delegation-policy.ts +9 -1
- package/scripts/delegation/investigation-guard.ts +1 -1
- package/scripts/delegation/investigation-reads.ts +109 -23
- package/scripts/discovery/repo-discovery.ts +21 -7
- package/scripts/discovery/repo-origin.ts +26 -0
- package/scripts/discovery/repo-party.ts +42 -1
- package/scripts/document/backlogrun-parent-read-set.ts +14 -15
- package/scripts/document/capped-print.ts +74 -0
- package/scripts/document/document-byte-budget.ts +34 -20
- package/scripts/document/document-section-cli.ts +4 -3
- package/scripts/document/entry-read-budget.ts +21 -9
- package/scripts/document/lane-child-read-set.ts +12 -14
- package/scripts/document/read-set-cli.ts +4 -4
- package/scripts/document/read-set-point-of-use.ts +10 -2
- package/scripts/document/resident-budget.ts +47 -0
- package/scripts/epic/epic-shape.ts +10 -13
- package/scripts/epic/epic-solo.ts +1 -1
- package/scripts/exports/unused-members-cli.ts +7 -3
- package/scripts/gate/scoped-green.ts +25 -14
- package/scripts/gh/git-gh-api-path.ts +7 -0
- package/scripts/hooks/pretool-guard-cli.ts +2 -2
- package/scripts/hooks/pretool-guard.ts +45 -2
- package/scripts/hooks/run-hook.sh +41 -0
- package/scripts/init/claude-kit-only-settings.ts +29 -0
- package/scripts/init/hook-command-rewrite.ts +18 -35
- package/scripts/init/hook-launch.ts +21 -32
- package/scripts/init/init-copy-content.ts +8 -2
- package/scripts/init/initial-commit.ts +24 -0
- package/scripts/init/start-exec.ts +16 -3
- package/scripts/init/start-steps.ts +8 -12
- package/scripts/issue/issue-auto-ok.ts +95 -0
- package/scripts/issue/issue-file-cli.ts +53 -7
- package/scripts/issue/issue-file.ts +28 -5
- package/scripts/issue/issue-labels.ts +12 -12
- package/scripts/issue/issue-rank.ts +1 -1
- package/scripts/issue/issue-read-cli.ts +4 -3
- package/scripts/issue/issue-read.ts +2 -2
- package/scripts/issue/issue-report-failures.ts +6 -2
- package/scripts/issue/issue-scout-cli.ts +2 -2
- package/scripts/issue/issue-state-cli.ts +2 -2
- package/scripts/issue/issue-state.ts +2 -2
- package/scripts/issue/issue-wip.ts +70 -0
- package/scripts/josh/hook-decision.ts +17 -0
- package/scripts/josh/josh-commands-development.ts +10 -0
- package/scripts/josh/josh-commands-issue.ts +2 -2
- package/scripts/josh/josh-commands-lane.ts +1 -1
- package/scripts/josh/josh-commands-project.ts +7 -0
- package/scripts/lane/lane-await.ts +46 -2
- package/scripts/lane/lane-cli.ts +11 -13
- package/scripts/lines/bytes-command.ts +29 -6
- package/scripts/observations/observation-ledger-line.ts +1 -1
- package/scripts/release/github-release-environment.ts +1 -0
- package/scripts/release/github-release.ts +103 -17
- package/scripts/release/release-progress.ts +167 -0
- package/scripts/release/release-publish.ts +19 -8
- package/scripts/release/release-tag.ts +22 -8
- package/scripts/rules/decision-oracle-stage.ts +1 -1
- package/scripts/rules/decision-oracle.ts +6 -6
- package/scripts/rules/delivered-rules.ts +11 -11
- package/scripts/rules/direct-pr-create.ts +110 -0
- package/scripts/rules/file-body.ts +98 -42
- package/scripts/rules/filing-cap.ts +2 -2
- package/scripts/rules/filing-offer.ts +1 -1
- package/scripts/rules/gh-api.ts +18 -1
- package/scripts/rules/implementation-cut.ts +3 -1
- package/scripts/rules/lane-background.ts +67 -10
- package/scripts/rules/permission-guards.ts +10 -2
- package/scripts/rules/stop-rules.ts +4 -4
- package/scripts/rules/test-declared-commit.ts +1 -1
- package/scripts/rules/third-party-write.ts +56 -12
- package/scripts/run/run-carry-cli.ts +3 -1
- package/scripts/run/run-carry-conversation.ts +94 -0
- package/scripts/run/run-carry-reclaim.ts +37 -0
- package/scripts/run/run-carry.ts +21 -5
- package/scripts/run/run-cut-handoff.ts +21 -1
- package/scripts/run/run-entry-cli.ts +11 -3
- package/scripts/run/run-hold-cli.ts +16 -2
- package/scripts/run/run-label.ts +50 -0
- package/scripts/run/run-merge-steps.ts +12 -4
- package/scripts/run/run-merge.ts +1 -1
- package/scripts/run/run-prep-cli.ts +6 -2
- package/scripts/run/run-prep.ts +17 -0
- package/scripts/run/run-ship-preflight.ts +34 -3
- package/scripts/run/run-ship-review-steps.ts +1 -1
- package/scripts/run/run-ship-review.ts +26 -5
- package/scripts/run/run-step-cli.ts +20 -7
- package/scripts/run/run-wake-driver.ts +24 -1
- package/scripts/run/run-wake-session.ts +2 -1
- package/scripts/test/test-declared-logic.ts +1 -1
- package/scripts/test/test-related.ts +1 -6
- package/scripts/test/test-unit-guard.ts +21 -7
- package/scripts/time-runtime/time-batch-guard.ts +52 -16
- package/scripts/time-runtime/time-density-hook.ts +20 -2
- package/scripts/time-runtime/time-density.ts +4 -3
- package/scripts/time-runtime/time-markers.ts +15 -4
- package/scripts/time-runtime/time-spans.ts +4 -0
- package/scripts/version/npm-registry.ts +11 -1
- package/templates/workflows/ci.yml +9 -1
- package/templates/workflows/github-release.yml +13 -25
- package/.claude/skills/workflow-commands/followup-reference.md +0 -118
- package/dist/hooks/chunk-QVLT52OV.js +0 -464
|
@@ -1,134 +1,37 @@
|
|
|
1
1
|
## 常駐ドキュメントと skill の分担(何を常駐に残すか)
|
|
2
2
|
|
|
3
|
-
**規則をどこに書くか、常駐にどこまで残すかの判定は、このファイルが単一ソースである**(joshuafolkken/kit#2891
|
|
4
|
-
|
|
5
|
-
`CLAUDE.md` は毎ターン全文が読み込まれる。したがって常駐に書ける量は有限で、`scripts/claude/workflow-skills.test.ts` の `RESIDENT_CEILING_BYTES` がその上限を固定している。**どの規則をどこに置くかは、書き手の重要度判断ではなく、下の 4 つの問いを順に当てて決める。**
|
|
3
|
+
**規則をどこに書くか、常駐にどこまで残すかの判定は、このファイルが単一ソースである**(joshuafolkken/kit#2891)。**読むのは規則を置く・移す・引退させるターンだけ**である。`CLAUDE.md` は毎ターン全文が読み込まれ、上限は `scripts/document/resident-budget.ts` の `RESIDENT_CEILING_BYTES`(残りは `pnpm josh bytes CLAUDE.md`)。**置き場所は書き手の重要度判断ではなく、下の 4 つの問いを順に当てて決める。** 経緯・一覧・作例は `docs/maintainers/residency-rationale.md` にある。
|
|
6
4
|
|
|
7
5
|
### 第 0 問(先に問う)
|
|
8
6
|
|
|
9
7
|
> **その規則の答えは、機械的に読める入力だけから計算できるか。**
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
**できない場合は、次の順序の問いに進む。**
|
|
9
|
+
**できるなら、コマンドが答える。** 文書には「このコマンドに聞け」の導線 1 行だけを置く。既存のオラクルは `pnpm josh oracle:list`、単一ソースは `scripts/rules/decision-oracle.ts`。
|
|
14
10
|
|
|
15
11
|
### 順序の問い(第 0 問の次に問う)
|
|
16
12
|
|
|
17
13
|
> **その規則は「何を」ではなく「いつ・どの順で・どの引数で」を決めているか。**
|
|
18
14
|
|
|
19
|
-
**そうであれば、規則はドライバの状態遷移に書き、散文には書かない。** `pnpm josh run:step <N>`
|
|
20
|
-
|
|
21
|
-
**順序でないなら、以下の 2 問に進む。**
|
|
15
|
+
**そうであれば、規則はドライバの状態遷移に書き、散文には書かない。** `pnpm josh run:step <N>` が次の 1 手を計算する(`scripts/run/run-step.ts`、joshuafolkken/kit#2248)。文書は導線 1 行を張るだけである。
|
|
22
16
|
|
|
23
17
|
### 第 1 問 — 引き金を名指しできるか
|
|
24
18
|
|
|
25
19
|
> **その規則が効き始める瞬間を、1 件のツール呼び出しとして名指しできるか。**
|
|
26
20
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
**常駐側にはトリガと判断基準の 1 行を残す。配送経路は 1 つの harness にしか届かないからである。** フックが届くのは Claude Code だけである。`CLAUDE.md` は特定のエージェントに依存しない前提で書かれており(`AGENTS.md` / `GEMINI.md` / `.cursorrules` はいずれもそこへの導線である)、Codex や Gemini CLI、Cursor のセッションは `.claude/settings.json` のフックを 1 つも走らせない。停止スイッチを立てた Claude Code も同じである。**規則の行を丸ごと消すと、それらのセッションではその規則がどこにも存在しなくなる。** したがって移設で常駐から出るのは**規則本文**であって行そのものではなく、実測値・却下した機構案・手順は配送側と話題ファイルへ移り、1 行だけが残る。**得るのは本文であって行ではない。** 常駐から完全に外してよいのは、その規則に従う主体が常にこの harness だと言える場合に限られる。
|
|
30
|
-
|
|
31
|
-
**第 1 問が先に来るのは、届ける手段が増えたからである。** 旧来この一覧は第 2 問だけで決まっていたが、それは「規則を届ける手段が常駐しかない」時代の基準だった。`PreToolUse` / `PostToolUse` / `UserPromptSubmit` が稼働している以上その前提は成立せず、joshuafolkken/kit#1344 と joshuafolkken/kit#1460 は**常駐していながら一度も発火していなかった規則が実在した**ことを計測で示している。
|
|
32
|
-
|
|
33
|
-
名指しできない規則は、次の問いに進む。
|
|
21
|
+
**名指しできる規則は、規則本文を常駐から出し、[`rule-delivery.md`](./rule-delivery.md) の列挙表に 1 行加える**(joshuafolkken/kit#1524)。フックは Claude Code にしか届かないので、**常駐にはトリガと判断基準の 1 行を残す**。根拠は `docs/maintainers/residency-rationale.md` → "Why a delivered rule keeps one resident line"。
|
|
34
22
|
|
|
35
23
|
### 第 2 問 — skill なしのターンでも効く必要があるか
|
|
36
24
|
|
|
37
25
|
> **その規則は、skill がロードされていないターンでも効く必要があるか。**
|
|
38
26
|
|
|
39
|
-
**`CLAUDE.md` に残るのは、skill がロードされていないターンでも効く必要がある規則だけである。**
|
|
40
|
-
|
|
41
|
-
### 常駐規則をどこまで常駐させるか — トリガと導線
|
|
42
|
-
|
|
43
|
-
上の問いは規則を常駐に**残すかどうか**を決めるが、**どこまで残すか**は決めない。長いあいだ何もそれを決めておらず、通った規則は手順を丸ごと連れて入ってきた。その結果、手順を既に移し終えた後でも `CLAUDE.md` は上限まで 585 バイトのところまで膨らみ直した(joshuafolkken/kit#964)。
|
|
44
|
-
|
|
45
|
-
**常駐規則は、トリガと導線の 2 つで書く。** 3 つ目は置かない。
|
|
46
|
-
|
|
47
|
-
1. **トリガ** — 規則が効く状況と、ほかを何も読む前に従うべき 1 つの指示。そこから先を何も読まないエージェントでも、止まる・起票する・拒否する・尋ねるといった安全な振る舞いができるように書く。
|
|
48
|
-
2. **導線** — 手順を持つ `prompts/collaboration-workflow/` の話題ファイルか skill のファイル。探さずに開けるだけ正確に名指す。
|
|
49
|
-
|
|
50
|
-
それ以外 — 手順、作例、根拠、規則が書かれるきっかけになった失敗 — は導線の先に置く。**判定は、導線を一度も開かないターンでも常駐の記述だけで正しく振る舞えるかである。** ある文を落とすとエージェントが誤って進みうるなら、その文はトリガの一部である。落としても情報が減るだけなら、導線の先に置く。
|
|
51
|
-
|
|
52
|
-
**削ることは移すことであり、削除は理由を示して初めて許される例外である。** 文が `CLAUDE.md` から出る前に、その文は導線の先に存在していなければならず、それを固定していたマーカーテストは捨てずに導線の先へ付け替える。正典の節が常駐の写しより薄いのは普通のことであって削除の理由にはならない — そのときは常駐側が詳しい版なので、先に正典へ移してから常駐から切る。
|
|
53
|
-
|
|
54
|
-
**移すことしかできない仕組みはいずれ詰まるので、出口を 1 つだけ設ける。ただし狭い**(joshuafolkken/kit#1525)。規則を移すのではなく**引退**させてよいのは、消してもどのエージェントの振る舞いも変わりえないときだけであり、それは主張ではなく次の 3 条件で示す。
|
|
55
|
-
|
|
56
|
-
1. **単一ソースが宣言された文の写しである。** 単一ソースが同じ文書の中で名指されている。2 つが食い違えば誤っているのは写しの側なので、写しに正しく依存できるものは無い。
|
|
57
|
-
2. **ほかのどこにも無い文を 1 つも運んでいない。** 記憶ではなく、写し元の単一ソースと突き合わせて確かめる。
|
|
58
|
-
3. **マーカーテストが固定していない。** 引退と一緒に落ちるアサーションが無い。
|
|
59
|
-
|
|
60
|
-
**「重複に見える」は 3 条件のどれも満たさない。発火テスト・マーカー・測定された効果を持つ規則は、そもそも候補ではない。** これらの文書の規則はどれも、特定の失敗の後に書かれている。今日何も変えていない規則は、**そこにあるから**失敗が再発していないだけかもしれない。3 条件がそろわなければ、その発見は証拠つきの候補として記録し、規則は残す — 載せた候補は何も払わず後で拾えるが、誤って消した規則は何か月も後に、誰も見ていないランで黙って失敗する。**引退できるものが無かった回は、候補と証拠を記録してそこで止める** — 削除が出てくるまで基準を下げることはしない。
|
|
61
|
-
|
|
62
|
-
**`rule:value` は測定であって、削減の門番ではない**(joshuafolkken/kit#1931 → `## Decisions`)。低い単独遵守率は常駐の写しが働いている証拠になるが、何も引退させなかった読み取りが文書を凍結することはない。単一ソースの導線先に本文が重複している常駐の写しは、読み取りの許可を待たずに上の「削ることは移すこと」に従ってトリガまで削る。比較の値が `-` の規則は遵守テストを宣言していないのであって、0 ではなく**未測定**であり、それだけで候補にはならない。門番として使っていた時期の経緯と各回の読み取りは `docs/maintainers/residency-rationale.md` → "The reduction freeze and its retraction"、`docs/maintainers/residency-rationale.md` → "Measurement decides what leaves"、`docs/maintainers/residency-rationale.md` → "The `rule:value` readings" にある。
|
|
63
|
-
|
|
64
|
-
### 常駐規則の一覧
|
|
65
|
-
|
|
66
|
-
**この一覧の対象範囲は、オンデマンド側に対応する手順を持つ常駐規則である** — skill であれ、オンデマンドで読むプロンプトであれ、常駐の記述が導線を張っている先を持つもの。判定基準が問うているのはまさにその規則群であり、いずれも「移せたはずだが、名前を挙げるに足る理由で残った」ものである。この範囲の中では網羅的であり、対応する手順を持つ規則がここに載らずに常駐へ入っていれば、判定基準に照らされていない。
|
|
67
|
-
|
|
68
|
-
**skill の数で線を引くのは誤りである** — `verify-ui` も 3 文書から導線が張られており、下の一覧の 1 件は skill ですらない `prompts/review.md` を指している。
|
|
69
|
-
|
|
70
|
-
**範囲の外にある常駐規則はこの一覧に載らないのが正常である。** 命名規約、品質上限、Code Change Rules、Package-First などには移す先が存在せず、判定基準が問う「skill がロードされていないターンでも効くか」という問い自体が成り立たない。一覧に無いことは欠落ではない(joshuafolkken/kit#955)。
|
|
71
|
-
|
|
72
|
-
範囲の中で常駐に残る規則は次で全部であり、いずれも `CLAUDE.md` に残っていることをマーカーテストが表明している(大半は `scripts/claude/workflow-skills.test.ts`、UI 検証ゲートは `scripts/claude/verify-ui-skill.test.ts`、後追い起票とファイル編集の禁止は `scripts/document/document-markers.test.ts`)。**引き金つき配送へ移した規則は、常駐にあることではなく発火することで固定される** — ターン内バッチングは `scripts/rules/turn-batching-rule.test.ts`、WIP 上限は `scripts/backlog/backlog-manufacturing-rule.test.ts`、機構そのものは `scripts/rules/delivered-rules.test.ts` であり、常駐していると表明されるのはトリガの 1 行だけである。
|
|
73
|
-
|
|
74
|
-
- **明示起動の必須**(「指示されていない行動は取らない」)— そもそもワークフローを開始してよいかを決める規則なので、ユーザーがキーワードを打った瞬間、つまり skill を読むより前に効く必要がある
|
|
75
|
-
- **停止時の `confirmation` 通知** — これを要する停止の大半(別パッケージ起因の割り込み、Tier C の確認)は、ワークフローのキーワードが一度も打たれていないターンで起きる
|
|
76
|
-
- **`overrides` の保護**と **`devEngines` の保護** — 依存更新コマンドはどのターンでも走りうる。`dependency-update` skill をロードしないターンでも走り、skill を読む頃には pin は既に書き換わっている
|
|
77
|
-
- **UI 検証ゲート** — 画面に出る変更は、実際にレンダリング結果を見るまで完了ではない。撮影の手順は `verify-ui` にある。このゲートが効くのは UI 変更の完了を報告する瞬間であり、ワークフローのキーワードが打たれておらず skill が何もロードされていないターンであることが多い
|
|
78
|
-
- **レビュー上限後の後追い起票の手順** — 起票して `epic:bundle` で EPIC へ繋ぎ直すところまで。コミット前セルフレビューはワークフローの外でも回るので、そこで起票された Issue も同じように孤児になる。完全な手順は `prompts/review.md` →「Review round cap」にある(joshuafolkken/kit#946)
|
|
79
|
-
- **`josh epic:*` のうちコマンドの外側で効く 3 件** — 決定の記録による `needs-decision` の解除、`epic:audit` の指摘を直すのが Tier A であること、別リポジトリの EPIC を `owner/repo#N` で参照すること。いずれも `epic:*` コマンドを走らせていないターン(Issue を起票した直後、決定を書いた瞬間)に効く。コマンド自身の手順は `.claude/skills/epic-commands/` にある
|
|
80
|
-
- **編集後の本文をコマンドに載せない禁止** — ファイル編集はどのターンでも起き、**編集の直前にロードされる skill は存在しない**。オンデマンド側に置くとこの規則は一度も発火せず、書いたのに削除したのと同じ振る舞いになる。可否表は [`file-edits.md`](./file-edits.md)、実測値と根拠は [`docs/maintainers/file-edits-rationale.md`](../../docs/maintainers/file-edits-rationale.md) にあり、常駐に残すのは指示と判断基準(「本文を丸ごと運ぶか」であってツール名ではない)だけである(joshuafolkken/kit#1150)。**Edit 自体を全文へ広げる形も同じ規則の一部である** — 数行の指摘に対する全文書き直しは、ツールを替えただけで同じコストを払っている。常駐にはその禁止の一句だけを置き、全文を書いてよい 3 条件は同じ指し先にある(joshuafolkken/kit#1260)
|
|
81
|
-
|
|
82
|
-
**第 1 問で「名指しできる」となり、引き金つき配送へ移したもの**(joshuafolkken/kit#1524)。いずれも本文は消えておらず、規則が効く瞬間にフックが突きつける。下は常駐に 1 行を残した、またはその判断に理由が要った行だけであり、配送されている規則の全体ではない。**列挙表と、引き金が発火しないターンの意味の単一ソースは [`rule-delivery.md`](./rule-delivery.md) であり、ここには行数を写さない** — 2 か所に置いた数は必ずずれる(joshuafolkken/kit#1525)。
|
|
83
|
-
|
|
84
|
-
- **独立した呼び出しを同じターンに載せる規則** — 引き金は `pnpm josh batch:guard`(単発呼び出しのターンが 3 つ続いた次の `Bash` / `Edit` / `Read`)。常駐していた間の実測が示したのは、**常駐は効いていなかった**という事実である(数値は指し先)。実測値・却下した機構案・ゲートを弱めない条件は [`turn-batching.md`](./turn-batching.md) にある(joshuafolkken/kit#1304、#1390、#1524、`Edit` は #1762、`Read` は #1798 で加わった)
|
|
85
|
-
- **バックログの WIP 上限** — 引き金は `pnpm josh rule:guard`(Issue を作成する `Bash`)。配送文が件数の数え方・起票しない判断・2 つの免除・**割り込みの 3 条件**をそのまま運ぶ。3 条件を落とすと「重大かどうか」が判断に戻るため、配送文からも削っていない(joshuafolkken/kit#1518)。コメントの投稿は起票ではないので対象外である。手順と数字を動かす条件は [`wip-cap.md`](./wip-cap.md) にある(joshuafolkken/kit#1469、#1524)
|
|
86
|
-
- **Issue コメントの読み取り** — 引き金は `pnpm josh rule:guard`(Issue 本文だけを読む `Bash`)。拒否文はコメント込みの読み直しと、本文と食い違うコメントの扱いを渡す。前提を満たすまで毎回拒否するので、`batch:guard` と引き金が重なるターンでも拒否する。手順は `SKILL.md` → §2g に残る — フックを走らせないセッションにも読み取りの義務は残るからである
|
|
87
|
-
- **本文をシェルの二重引用符に載せない** — 引き金は `pnpm josh rule:guard`(本文値にバッククォートか `$` を含む `Bash`)。**引き金はフラグではなく本文を読む** — 作例はどれも無害なプレースホルダを渡しているので、フラグで引くと規則を既に守っているターンで拒否することになる。**常駐側に 1 行が残っているのは、ここが「削除してよい」側ではないからである** — 配送は Claude Code にしか届かず、正規表現が知っている綴り(`-f body=` / `--body` / `--notify-message`)だけが規則の適用範囲になってはならない。実測・安全な綴り・引き金の死角は [`shell-body.md`](./shell-body.md) にある(joshuafolkken/kit#1198)
|
|
88
|
-
|
|
89
|
-
no になり skill 側に本体を置くものの例:
|
|
90
|
-
|
|
91
|
-
- 分割判定(`.claude/skills/workflow-commands/split-assessment.md`)
|
|
92
|
-
- 実行中に前提 Issue が判明した場合の入口別手順(`fullrun.md` / `halfrun.md` / `.claude/skills/workflow-commands/backlogrun.md`)
|
|
93
|
-
- `backlogrun` の単独 Issue 受理と park-and-continue(`.claude/skills/workflow-commands/backlogrun.md`)
|
|
94
|
-
- 検証ゲートとマージ連鎖(`.claude/skills/workflow-commands/chain-rule.md` / `followup.md`)
|
|
95
|
-
- 依存更新後の検証手順(`.claude/skills/dependency-update/`)— 上の 2 つの保護が導線を張る先
|
|
96
|
-
- `auto-ok` の拾い上げと「ラベルを付けるのは人だけ」(`.claude/skills/workflow-commands/backlogrun.md`)。書き込みの禁止は普通なら常駐側に来るが、`auto-ok` はそれを禁じているドキュメント以外のどこにも存在しないため、それらを開かないターンではそもそも到達しない
|
|
97
|
-
|
|
98
|
-
### 指し先になった話題ファイルは引用しない
|
|
99
|
-
|
|
100
|
-
**引用先は「本文がある場所」であって、ファイルの役割名ではない。** 話題ファイルの本文を skill へ単一ソース化し、話題ファイル自体を指し先へ縮小したら、その話題への引用は **skill のファイルを直接指す**。`CLAUDE.md` も `docs/` も他の話題ファイルも同じで、「カノニカル参照」として指し先の話題ファイルを名指すことはしない(joshuafolkken/kit#1178)。
|
|
101
|
-
|
|
102
|
-
判定は 1 問で、書き手の裁量には委ねない。
|
|
103
|
-
|
|
104
|
-
> **その話題の本文はどのファイルにあるか。**
|
|
105
|
-
|
|
106
|
-
本文がまだ話題ファイルにあるなら、これまでどおり話題ファイルを直接指す。本文が skill にあるなら skill を指す。横展開(joshuafolkken/kit#1176)の途中では両方の状態の話題が同時に存在するので、ファイルの役割名ではなく本文の所在で決めることが要る。
|
|
107
|
-
|
|
108
|
-
**指し先を「カノニカル参照」として名指すと、2 回読みが戻ってくる。** 索引を指してから節名を書く形を禁じたのと同じ欠陥であり、しかも今度は本文が 1 行も無いファイルを経由させる。読み手は指し先を開き、そこに書かれた skill の名前を読み、もう一度開くことになる。**節名まで書いてある引用はさらに悪い** — 指し先には本文が無いのだから、その節はもうそこには無い。
|
|
109
|
-
|
|
110
|
-
**指し先だけになった話題ファイルは残さない。** 本文が skill へ移り、案内の 1 段落しか持たなくなった話題ファイルは削除し、索引(`prompts/collaboration-workflow.md`)の行も消す(joshuafolkken/kit#1925、joshuafolkken/kit#2996)。削除までの間に残る指し先は「本文がどこへ行ったか」の記録として索引から辿られるものであり、他の文書からの引用で辿られるものではない。例外は単一ソースである skill 自身で、自分の指し先を名指すのは逆向きの参照だから 2 回読みを生まない。
|
|
111
|
-
|
|
112
|
-
`scripts/rules/pointer-citation-document-rule.test.ts` がこれを固定する。**削除までの間に残る、縮小した話題ファイルは冒頭に「この規則の単一ソースは …」の宣言文を置くこと** — 検査はこの宣言文で指し先を機械的に検出し、そこに書かれた skill が実在すること、および他の文書がその話題ファイルを引用していないことを確かめる。宣言文が入口なので、横展開で新しく縮小された話題も、この規則の対象へ自動で入る。
|
|
113
|
-
|
|
114
|
-
### 常駐予算
|
|
115
|
-
|
|
116
|
-
**この基準は努力目標ではない。** `scripts/claude/workflow-skills.test.ts` は常駐文書ごとに `RESIDENT_CEILING_BYTES` の上限とその下の余白を要求する。常駐に手順を書き戻すと、その分の予算を次に本当に常駐が要る規則が既存の文章から取り返すことになる。上限に張り付いた状態で 1 文を足すために別の文を削ると、**削る対象はマーカーで固定されていなかった箇所から選ばれる** — 規則の重要度ではなく、テストに拾われていなかったかどうかで残る文が決まる(joshuafolkken/kit#951)。予算が詰まったときに何を出すかは、マーカーの有無ではなく測定で決める(`rule:value`、上の「トリガと導線」の節)。上限そのものを引き上げる対処は、上限が防いでいる状態の追認にあたるので採らない。
|
|
117
|
-
|
|
118
|
-
### 上限を引き上げてよい条件(反証条件)
|
|
119
|
-
|
|
120
|
-
**「引き上げない」は絶対の禁止ではなく、反証可能な既定である。** 禁止としてだけ書くと、回収の余地が本当に尽きた日に上限を動かす手続きがどこにも無いことになり、そのとき選ばれるのは「マーカーで固定されていない文を削る」という、この基準がまさに防いでいる手であった(joshuafolkken/kit#1275)。したがって、引き上げが正当化される条件をここに書き下しておく。
|
|
121
|
-
|
|
122
|
-
**次の 3 つが同時に満たされたときにかぎり、`RESIDENT_CEILING_BYTES` の引き上げを提案してよい。** 1 つでも欠けていれば、引き上げではなく回収を先にやる。
|
|
123
|
-
|
|
124
|
-
1. **安いほうの選択肢が枯れている。** 常駐に残っている記述が全部この基準(「skill がロードされていないターンでも効くか」+「トリガと導線だけか」)を通っており、指し先へ戻せる手順・根拠・ワークト例がもう無い。**枯れたことは主張ではなく測定で示す** — 回収候補を列挙し、それぞれが基準を通る理由を 1 行ずつ書いた上で、合計回収可能量が要求量を下回っていることを示す。joshuafolkken/kit#1275 の時点ではこれが満たされていなかった(Code Change Rules Step 0 のラベル規則だけで約 3KB の回収余地があり、実際に回収された)。
|
|
125
|
-
2. **要求が 1 つの規則ではなく構造から来ている。** 「次の 1 文が入らない」は回収で解ける。引き上げが要るのは、常駐すべき規則の**件数**が増えて構造的に収まらなくなったときであり、そのときは「どの規則が増えたか」を列挙できる。
|
|
126
|
-
3. **引き上げ幅が測定に基づく。** 1 で数えた回収可能量と 2 で数えた要求量の差だけを足す。切りのよい数字に丸めない — 丸めた余白は次の書き戻しに使われる。
|
|
127
|
-
|
|
128
|
-
**非対称なリスクがあるので、迷ったら回収を選ぶ。** 回収を選んで足りなかった場合の損失は「もう一度考える」だけだが、引き上げを選んで間違っていた場合の損失は、常駐面が毎ターン全文読まれるコストとして恒久的に乗り続ける。しかも上限は一度上げると次の判断の基準線になるので、誤りが自己修復しない。
|
|
27
|
+
**`CLAUDE.md` に残るのは、skill がロードされていないターンでも効く必要がある規則だけである。** 入力は「最初に効くのはコマンド開始の前か後か」の 1 点で、規則の重要さは入力に含まれない。後なら `CLAUDE.md` から導線を張り、再掲しない。
|
|
129
28
|
|
|
130
|
-
|
|
29
|
+
### 残すときの書き方と予算
|
|
131
30
|
|
|
132
|
-
|
|
31
|
+
- **常駐規則は、トリガと導線の 2 つで書く。** **判定は、導線を一度も開かないターンでも常駐の記述だけで正しく振る舞えるかである。**
|
|
32
|
+
- **削ることは移すことであり、削除は理由を示して初めて許される例外である。** 先に導線の先へ移し、マーカーテストも付け替える。引退の 3 条件は `docs/maintainers/residency-rationale.md` → "Trigger and pointer, and the narrow retirement route"。
|
|
33
|
+
- **経緯(Issue 番号・なぜ・計測・却下案)は実行時の文書に書かず `docs/maintainers/<topic>-rationale.md` に置く。** agent が読む文書の Issue 番号引用の件数は `scripts/document/issue-citation-budget.ts` のラチェットが検証ゲートで抑える — 増やせば落ち、減らしたら記録も下げる。経緯は `docs/maintainers/residency-rationale.md` → "The issue-citation ratchet"。
|
|
34
|
+
- 引用は本文があるファイルを直接指す — `docs/maintainers/residency-rationale.md` → "A pointer-only topic file is never cited"。
|
|
35
|
+
- 予算が詰まったら上限ではなく回収で解く。**引き上げは Tier C として扱う** — `RESIDENT_CEILING_BYTES`・`RESIDENT_HEADROOM_BYTES`・`RE_INLINE_GUARD_HEADROOM_BYTES` の緩和は、`docs/maintainers/residency-rationale.md` → "When the ceiling may be raised" の 3 条件を示した上でユーザーの明示指示を得てから行う。
|
|
133
36
|
|
|
134
|
-
|
|
37
|
+
常駐に残る規則と引き金つき配送へ移した規則の一覧は `docs/maintainers/residency-rationale.md` → "The resident-rule list"。そのほかの経緯は `docs/maintainers/residency-rationale.md` → "The reduction freeze and its retraction"、`docs/maintainers/residency-rationale.md` → "Measurement decides what leaves"、`docs/maintainers/residency-rationale.md` → "The `rule:value` readings"、`docs/maintainers/residency-rationale.md` → "Why the delivered list carries no count"、`docs/maintainers/residency-rationale.md` → "Why the workflow index is split by topic"、`docs/maintainers/residency-rationale.md` → "One list, not two"、`docs/maintainers/residency-rationale.md` → "The resident budget"。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# 引き金つき配送 — 規則を「効く瞬間」に届ける(joshuafolkken/kit#1524)
|
|
2
2
|
|
|
3
|
-
規則の届け方は 2 つある。**常駐**(`CLAUDE.md`
|
|
3
|
+
規則の届け方は 2 つある。**常駐**(`CLAUDE.md` に書き、毎ターン読み込ませる)と、**引き金つき配送**(規則が効く瞬間にフックが本文を突きつける)である。この文書は後者の単一ソースであり、配送される規則の一覧でもある。配線・判定の細部と経緯は `docs/maintainers/rule-delivery-rationale.md` にあり、ランの途中で読む必要はない。
|
|
4
4
|
|
|
5
5
|
## なぜ配送が要るのか
|
|
6
6
|
|
|
@@ -8,111 +8,112 @@
|
|
|
8
8
|
|
|
9
9
|
## 判定基準 — 引き金を特定できるか
|
|
10
10
|
|
|
11
|
-
どの規則を配送へ移すか — 引き金を 1 件のツール呼び出しとして名指しできるか、常駐側にトリガの 1 行を残す理由、移設が削除ではないこと — の単一ソースは [`residency.md`](./residency.md) →「第 1
|
|
11
|
+
どの規則を配送へ移すか — 引き金を 1 件のツール呼び出しとして名指しできるか、常駐側にトリガの 1 行を残す理由、移設が削除ではないこと — の単一ソースは [`residency.md`](./residency.md) →「第 1 問」であり、ここには写さない。この文書が持つのは、移した規則の一覧である。
|
|
12
12
|
|
|
13
13
|
## 機構 — 1 本だけ、新規に作らない
|
|
14
14
|
|
|
15
|
-
配送はすべて
|
|
16
|
-
|
|
17
|
-
- **列挙表**: `scripts/rules/delivered-rules.ts`。1 規則 = 1 行(`id` / 引き金 / 配送文)。
|
|
18
|
-
- **入口**: `scripts/hooks/pretool-guard-cli.ts`(ガードの合成は `scripts/hooks/pretool-guard.ts`)= `pnpm josh pretool:guard`。3 つの `PreToolUse` ガード(バッチング / 調査 / 規則)を 1 プロセスにまとめ、`.claude/settings.json` の `PreToolUse` に**単一エントリ**として `Bash|Edit|Read|Write` のマッチャで配線されている。拒否の優先順位はバッチングの理由が先、次に調査、最後に規則であり、各ガードは内部で従来どおり自分の環境変数スイッチを尊重する。
|
|
19
|
-
- **停止スイッチ**: `JOSH_RULE_GUARD`(規則ガードのぶん。既定で有効。`off` / `0` / `false` / `no` で無効)。バッチング・調査の各ガードも同じく自前のスイッチを持つ。
|
|
20
|
-
|
|
21
|
-
**規則ガードの列挙表に載るのは、効く瞬間がシェル呼び出しである規則に限られる。** Claude Code は 1 ターンのうち 1 件だけを拒否して残りを実行するため、拒否された `Edit` は兄弟の編集だけが適用された状態を残す(joshuafolkken/kit#1390)。単一の `pretool:guard` プロセスは `Bash|Edit|Read|Write` を受け取るが、規則ガードが拒否理由を返すのはシェル呼び出しに限られる。
|
|
22
|
-
|
|
23
|
-
### Stop フック — 2 つ目の入口、同じ土台(joshuafolkken/kit#2121)
|
|
24
|
-
|
|
25
|
-
`pretool-guard` が `PreToolUse` の入口であるのと同じ意味で、`stop:guard`(`scripts/hooks/stop-guard.ts` = `pnpm josh stop:guard`)は **`Stop` イベントの入口**である。`.claude/settings.json` の `Stop` に matcher 空の**単一エントリ**として配線され、turn の終わりごとに走る。
|
|
26
|
-
|
|
27
|
-
**土台は共有し、判定は再利用する。** スイッチ(`JOSH_STOP_GUARD`)と `.env` の読み込みは `hook-decision.ts` のものを、停止通知かどうかは `lane-park.ts` の正規表現を、押さえの有無は `run:hold` の記録読み取りを使う — **2 本目の判定機構は作らない**。起票の有無は `filing-cap.ts` の数え方を、第一者かどうかは `repo-party.ts` の比較を使う。違うのはイベントだけで、`Stop` のペイロードにはツール呼び出しが無く、4 行はいずれも `{"decision":"block","reason":…}` で返す。`Stop` イベントからモデルへ文字を届ける経路はこれ 1 本しかない(joshuafolkken/kit#2247)。
|
|
28
|
-
|
|
29
|
-
**入口が 2 つでも土台は 1 つ。**「1 本だけ、新規に作らない」が禁じるのは共有部の 2 つ目の写しであって、イベントごとの入口ではない。`stop:guard` の 4 行は下の列挙表に載るが、引き金がシェル呼び出しではなく**ランの停止**なので、`delivered-rules.ts` の `DELIVERED_RULES`(`PreToolUse` 専用)ではなく `stop-rules.ts` に住む。どのエラーでも停止は通す(フェイルオープン)— 4 つのブロック行は自己解消し(通知を送る/押さえを解放する/起票する/引用を直して返信を出し直す)、`stop_hook_active` が無限ループの歯止めになる。
|
|
30
|
-
|
|
31
|
-
`backlogrun` の通常の親ループと次の Issue の取得は監督プロセスが扱うため、次の Issue を取得させる Stop 判定は撤去した。名前を指定したエピックを判断用の headless セッションに渡す経路では、子レーンの待機がそのセッションに残るため、待機保護を維持する。停滞と取り残しの検出は Stop イベントが起きた時だけ実行し、停止判定とは独立して報告する。
|
|
15
|
+
配送はすべて 1 つの土台に載り、入口はイベントごとに 2 つある。`PreToolUse` の入口が `pnpm josh pretool:guard`(バッチング / 調査 / 規則の 3 ガードを 1 プロセスで合成)、Stop フックの入口が `pnpm josh stop:guard` である。**2 本目の配送経路を作るのは `CLAUDE.md` →「No clones」が禁じるクローン**である。配線・停止スイッチ・拒否の優先順位: `docs/maintainers/rule-delivery-rationale.md` →「機構」。
|
|
32
16
|
|
|
33
17
|
## 配送されている規則
|
|
34
18
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
19
|
+
各項目は**規則**(単一ソース)・**発火点**・**発火しないとき**を持つ。フックが走らないエージェントはこれを自己適用のチェックリストにする(`principles.md`)。頻度を書いていない項目は 1 ラン 1 回だけ配送される — 「毎回発火する」「毎回拒否する」「たびに発火する」「停止をブロックする」(`stop:guard` は止まるたびに判定する)と書いた項目は、条件を満たすかぎり何度でも発火し、「再び発火する」と書いた項目は間隔をおいて再発火する。
|
|
20
|
+
|
|
21
|
+
- **ターン内バッチング**(`turn-batching.md`)
|
|
22
|
+
- 発火点: `pnpm josh batch:guard` — 単発呼び出しのターンが 3 つ続いた次の `Bash` / `Edit` / `Read`。単発が続くかぎり、さらに 3 ターンごとに**再び発火する**(joshuafolkken/kit#2164)
|
|
23
|
+
- 発火しないとき: 往復あたりの呼び出し数が下限を上回っている = 規則は既に守られている
|
|
24
|
+
- **調査の委譲しきい値**(`delegation.md`)
|
|
25
|
+
- 発火点: `pnpm josh investigation:guard` — 編集しないファイルの読み取りが 3 件目に達した `Read` / `Bash`。拒否の後も読み取りがもう一度しきい値まで積み上がれば**再び発火する**
|
|
26
|
+
- 発火しないとき: 読み取りがしきい値未満 = 委譲する対象がまだ無い
|
|
27
|
+
- **バックログ WIP 上限**(`wip-cap.md`)
|
|
28
|
+
- 発火点: `pnpm josh rule:guard` — Issue を起票する `Bash`(`pnpm josh issue:file`)
|
|
29
|
+
- 発火しないとき: Issue が起票されていない = 上限に触れる行為が無い
|
|
30
|
+
- **直接起票の禁止**(`docs/josh-commands-automation.md` → `josh issue:file`、joshuafolkken/kit#2808)
|
|
31
|
+
- 発火点: `pnpm josh rule:guard` — `josh issue:file` を通さずに Issue を作成する `Bash`(`gh issue create`、または `…/issues` への `title` 付き POST)。拒否文は `pnpm josh issue:file` の書式を渡す。**毎回発火する**
|
|
32
|
+
- 発火しないとき: `pnpm josh issue:file` で起票している = 重複探し・本文の検査・`epic:bundle` までの全段がそろっている
|
|
33
|
+
- **1 ラン 10 件の起票上限**(`.claude/skills/workflow-commands/prerequisite.md`、`observation-filing.md`)
|
|
34
|
+
- 発火点: `pnpm josh rule:guard` — 拒否されていない起票が既に 10 件あるランの 11 件目の `pnpm josh issue:file`。失敗した呼び出しは数えない。**毎回発火する**
|
|
35
|
+
- 発火しないとき: 拒否されていない起票が 10 件未満 = 上限に触れていない
|
|
36
|
+
- **Issue コメントの読み取り**(`issue-comments.md`)
|
|
37
|
+
- 発火点: `pnpm josh rule:guard` — Issue 本文だけを読む `Bash`(`gh issue view <N>`、または `…/issues/<N>` で終わる GET)。コメント込みで読み直すまで毎回拒否する
|
|
38
|
+
- 発火しないとき: Issue を読んでいない、または最初から `--comments` / `--json comments` / `…/comments` で読んでいる
|
|
39
|
+
- **本文をシェルに載せない**(`shell-body.md`)
|
|
40
|
+
- 発火点: `pnpm josh rule:guard` — 二重引用符の本文値(`-f body="…"` / `-f "body=…"` / `--body "…"` / `--notify-message "…"`)にバッククォートか `$` を含む `Bash`
|
|
41
|
+
- 発火しないとき: 本文がシェルに評価されない = 規則は既に守られている(経緯: `docs/maintainers/rule-delivery-rationale.md` →「本文のシェル評価を同じ機構の 1 行で覆った経緯」)
|
|
42
|
+
- **@path をリテラル投稿する誤射**(`shell-body.md`、joshuafolkken/kit#2304)
|
|
43
|
+
- 発火点: `pnpm josh rule:guard` — 生フィールド(`-f` / `--raw-field`)で `body=@<path>` を渡した `Bash`。**毎回発火する**
|
|
44
|
+
- 発火しないとき: `-F` / `--field body=@`・`@` を含まない本文・`pnpm josh issue:comment` = リテラルの `@path` が送出されない
|
|
45
|
+
- **検証コマンドのパイプ**(`output-bounds.md`)
|
|
46
|
+
- 発火点: `pnpm josh rule:guard` — 合否を意味する josh のチェック(`gate` / `check` / `lint*` / `cspell*` / `test*` / `eval` / `overrides` / `ranges`)がパイプの手前に立った `Bash`
|
|
47
|
+
- 発火しないとき: 検証の終了コードが握りつぶされていない = 失敗が失敗として伝わる
|
|
48
|
+
- **早すぎる進捗報告**(`.claude/skills/workflow-commands/progress-watcher.md` → 「Progress while the run is quiet」)
|
|
49
|
+
- 発火点: `pnpm josh rule:guard` — 待つことだけが目的の `Bash`(`sleep` だけ、または `echo` / `:` / `date` を並べただけ)を、タイマーが生きている回か報告が間隔前に着地する回に出したとき。**毎回発火する**
|
|
50
|
+
- 発火しないとき: 待機タイマーを自前で張っていない = 時計は `run:progress` が 1 本だけ持っている
|
|
51
|
+
- **run 末尾の空転**(`background-commands.md`)
|
|
52
|
+
- 発火点: `pnpm josh rule:guard` — `pnpm josh git -y`(別名 `josh g`、`--yes` も同じ)を**前景**で出した `Bash`。**毎回発火する**
|
|
53
|
+
- 発火しないとき: 背景で発行している = 完了通知が run を再開させ、push とマージのあいだが空かない
|
|
54
|
+
- **gate 手前の cut**(`.claude/skills/workflow-commands/pre-gate-cut.md`)
|
|
55
|
+
- 発火点: `pnpm josh rule:guard` — レーンの作業ツリーで、目印 `JOSH_LANE_CHILD` がその Issue を指し、cut 記録が無いまま `pnpm josh gate`(別名 `josh ga`)を走らせる `Bash`
|
|
56
|
+
- 発火しないとき: レーン以外の checkout に居る、目印が無い(レーン内の人)、または既に cut 済み = 規則が守られている状態
|
|
57
|
+
- **実装フェーズの cut**(`.claude/skills/workflow-commands/pre-gate-cut.md` → 「It is a guard, fired at the edit that crosses the threshold」、joshuafolkken/kit#2310)
|
|
58
|
+
- 発火点: `pnpm josh rule:guard` — 派遣されたレーンの子が cut 前に、直近文脈のコストが `pnpm josh cost --cut` のしきい値を超えた状態で出す `Edit` / `Write`。拒否文は `pnpm josh run:cut --impl <N> --handoff <path>` を渡す。しきい値を跨ぐたびに発火する
|
|
59
|
+
- 発火しないとき: レーンの子でない、非編集ツール、既に cut 済み、またはコストがしきい値未満 = 打ち切りが要らない状態
|
|
60
|
+
- **レーンの子の保留**(`.claude/skills/workflow-commands/pre-gate-cut.md`)
|
|
61
|
+
- 発火点: `pnpm josh rule:guard` — 派遣されたレーンの子が停止通知 `pnpm josh notify --task-type confirmation` を出した `Bash`
|
|
62
|
+
- 発火しないとき: レーンの子でない(レーン外・目印なし・レーン内の人)、または停止通知でない = 保留を記録すべき停止が無い
|
|
63
|
+
- **レーンの子の対話質問**(`.claude/skills/workflow-commands/pre-gate-cut.md` → 「The interactive ask is refused one call earlier」)
|
|
64
|
+
- 発火点: `pnpm josh rule:guard` — 派遣されたレーンの子の `AskUserQuestion`。park 手順を返す。**毎回発火する**
|
|
65
|
+
- 発火しないとき: レーンの子でない、または対話ツールでない = 握りつぶされる質問が無い
|
|
66
|
+
- **テストの宣言**(`CLAUDE.md` → Code Change Rules)
|
|
67
|
+
- 発火点: `pnpm josh rule:guard` — `pnpm josh git -y`(別名 `josh g`)を出した瞬間に `pnpm josh test:declared` が `required` と答える `Bash`
|
|
68
|
+
- 発火しないとき: `exempt`(非ランタイムのみ)または `satisfied`(テストを含む)= テストが要らない、または伴っている
|
|
69
|
+
- **force push / ブランチ削除**(`operating-rules.md`、joshuafolkken/kit#2120)
|
|
70
|
+
- 発火点: `pnpm josh rule:guard` — 綴りによらず force(`--force` / `-f` / `-uf` 等)・削除(`--delete` / `-d` / `-D` / `:branch`)と判定した `git push` / `git branch` の `Bash`。**毎回発火する**
|
|
71
|
+
- 発火しないとき: 通常の `git push` / `git branch` = 破壊的操作が無い
|
|
72
|
+
- **認可外の作業ツリー変更**(`operating-rules.md`、joshuafolkken/kit#2120)
|
|
73
|
+
- 発火点: `pnpm josh rule:guard` — `git checkout -- <path>` / `git restore <path>` / 強制 `git clean -f` / 認可外の `git stash`(bare・メッセージ無し push・位置指定 pop 等)の `Bash`。**毎回発火する**
|
|
74
|
+
- 発火しないとき: `git stash push -m` ・`git stash list` ・`pnpm josh git` ・`pnpm josh stash:pop` = 認可された退避
|
|
75
|
+
- **index の書き換え**(`operating-rules.md`、joshuafolkken/kit#2983)
|
|
76
|
+
- 発火点: `pnpm josh rule:guard` — 綴りによらず `git add` / `commit` / `reset` / `rm` / `mv` / `restore --staged` と判定した `Bash`。**毎回発火する**
|
|
77
|
+
- 発火しないとき: `pnpm josh git` = 承認済みのコミットフロー
|
|
78
|
+
- **破壊的コマンド**(`operating-rules.md`、joshuafolkken/kit#2983)
|
|
79
|
+
- 発火点: `pnpm josh rule:guard` — `rm -rf`(綴りによらず)・`gh repo delete` / `archive`・`gh pr close`・`gh api -X DELETE` の `Bash`。**毎回発火する**
|
|
80
|
+
- 発火しないとき: `gh issue close`・Issue ラベルの削除 = ワークフロー自身の手順
|
|
81
|
+
- **PR の直接作成**(`CLAUDE.md` → Git Rules、joshuafolkken/kit#3183)
|
|
82
|
+
- 発火点: `pnpm josh rule:guard` — `gh pr create`・`repos/<o>/<r>/pulls` への `gh api` 書き込みの `Bash`。`pnpm josh pr` を案内する。**毎回発火する**
|
|
83
|
+
- 発火しないとき: `pnpm josh pr`・PR の閲覧 = `closes #N` を生成する経路
|
|
84
|
+
- **保護ファイル**(`operating-rules.md`、joshuafolkken/kit#2983)
|
|
85
|
+
- 発火点: `pnpm josh rule:guard` — `.env` の `Read`、kit 以外のリポジトリでの `.claude/settings.json` の `Edit` / `Write`。**毎回発火する**
|
|
86
|
+
- 発火しないとき: kit 自身とユーザー単位の `~/.claude/settings.json` の編集
|
|
87
|
+
- **ファイル本文をシェルに載せない**(`file-edits.md`、joshuafolkken/kit#2120)
|
|
88
|
+
- 発火点: `pnpm josh rule:guard` — 既存ファイルへのヒアドキュメント書き込み・書き込みを伴う `node -e` / インタプリタ heredoc・`perl -0pi -e` の `Bash`。**毎回発火する**
|
|
89
|
+
- 発火しないとき: 新規ファイル作成・読み取り専用のヒアドキュメント・短い `sed -i` = 本文を丸ごと運んでいない
|
|
90
|
+
- **停止時の通知**(`CLAUDE.md` →「Mid-workflow stop notification」、joshuafolkken/kit#2121)
|
|
91
|
+
- 発火点: `pnpm josh stop:guard` — 作業ツリーを押さえたまま、その turn に `confirmation` 通知を出さずに止まる。**停止をブロックする**
|
|
92
|
+
- 発火しないとき: 押さえが無い、`confirmation` 通知が末尾にある、または pre-gate cut を取った回 = 人待ちの停止ではない
|
|
93
|
+
- **hold の解放**(`.claude/skills/workflow-commands/working-tree-hold.md`、joshuafolkken/kit#2121)
|
|
94
|
+
- 発火点: `pnpm josh stop:guard` — ツリーが綺麗なのに `run:hold` 記録が残ったまま止まる。**停止をブロックする**
|
|
95
|
+
- 発火しないとき: ツリーが汚れている(`halfrun` の commit 前停止・`needs-human-review` 停止)、または解放済み = 次のランが踏まない
|
|
96
|
+
- **Issue 引用の書式**(`prompts/collaboration-workflow/issue-citation.md`、joshuafolkken/kit#2121・joshuafolkken/kit#2247)
|
|
97
|
+
- 発火点: `pnpm josh stop:guard` — 最後の返信の地の文に裸の `#N` を含む。**停止をブロックする**。引用を直して返信を出し直させる
|
|
98
|
+
- 発火しないとき: リンク形式・コード/引用行の中・`PR` 直後の `#N`・GitHub 向け成果物 = 差し戻す裸の番号が無い
|
|
99
|
+
- **起票の申し出**(`.claude/skills/workflow-commands/observation-filing.md`、joshuafolkken/kit#2422)
|
|
100
|
+
- 発火点: `pnpm josh stop:guard` — 最後の返信の地の文が起票を申し出る(「起票してよければ」等)のに、起票していない。**停止をブロックする**
|
|
101
|
+
- 発火しないとき: 起票済み、フェンス/引用行の中、第三者の `owner/repo` を名指す、または owner 不明 = 保留された Tier A 起票が無い
|
|
102
|
+
- **規則本文を散文に書き足す前の第 0 問・順序の問い**(`residency.md`、joshuafolkken/kit#2272・joshuafolkken/kit#2324)
|
|
103
|
+
- 発火点: `pnpm josh rule:guard` — `CLAUDE.md` / `prompts/**/*.md` / `.claude/skills/**/*.md` への `Edit` / `Write` で、正味の追記が閾値以上のもの。`pnpm josh oracle:list` と `pnpm josh run:step` の両方を走らせるまで毎回拒否する
|
|
104
|
+
- 発火しないとき: 規則ドキュメントでない、追記が閾値未満(誤字・リンク張り替え・削除)、または両コマンドを実行済み = 配置の問いに答え済み
|
|
105
|
+
- **オラクル未参照の行為**(`decision-oracle.ts`、joshuafolkken/kit#2324)
|
|
106
|
+
- 発火点: `pnpm josh rule:guard` — 発火点を宣言したオラクルが支配する `Bash`(`pkg:scout` = `pnpm add`)を、そのオラクルの `pnpm josh <command>` 無しで出したとき。実行するまで毎回拒否する
|
|
107
|
+
- 発火しないとき: 支配下の行為を出していない、またはそのオラクルを実行済み = 規則は既に守られている
|
|
108
|
+
|
|
109
|
+
**引き金はシェルのコマンド文字列しか見えない**(node 内の REST や `gh api --input <file>` は掛からない)。だから常駐側にトリガ 1 行を残し、配送はそれを効く瞬間に補強する。
|
|
110
|
+
|
|
111
|
+
**「引き金が発火しないターンでは何も起きない」ことは仕様である。** 各項目の発火しない状態は「規則が守られている状態」と一致する。一致が取れない規則は引き金を特定できておらず、常駐に残す。**誤ったターンで発火するフックは、フックが無いより悪い。**
|
|
86
112
|
|
|
87
113
|
## 配送は 1 ラン 1 回
|
|
88
114
|
|
|
89
|
-
配送文は**ラン 1 回につき 1
|
|
90
|
-
|
|
91
|
-
### 例外 — 繰り返す行為を止める行は毎回発火する(joshuafolkken/kit#1570)
|
|
92
|
-
|
|
93
|
-
**1 ラン 1 回が正しいのは、拒否がランの「知っていること」を変える行だけである。** コメントを読む、Issue を数える、本文をファイルに書く — いずれも一度届けば、そのランは以後それを知った状態で進む。**一方、止めたい対象そのものが繰り返される行為なら、1 回で終わる配送は「一度断られたあとは自由」を意味し、強制は親の自制に戻る。** その自制が破れたのが #1570 である。
|
|
94
|
-
|
|
95
|
-
そこで **`decide` を自前で持つ行は 1 ラン 1 回の対象から外れ、条件を満たすかぎり毎回拒否する**。
|
|
96
|
-
|
|
97
|
-
**`batch:guard` との待避分岐は、そういう行では守る対象が変わる。** 1 ラン 1 回の行では**記録**を守っていた — レースに負ければ、そのランに 1 度しかない配送を無駄打ちするからである。毎回発火する行はその形では消えない。一方で待機タイマーを張る呼び出しは定義上「単発の `Bash`」であり、まさにバッチングガードも候補として扱う形なので、**拒否まで待避させると、10 秒の窓とその中の再発行で規則がまるごと黙る**。したがって**拒否は無条件に行い、待避は「記録してよいか」として行へ渡す** — 他のフックが止めうる呼び出しでしてはならないのは、走らなかったタイマーを生きていると書き残すことだからである。配送文には「これは毎回発火する」と明記する(1 回きりだと読まれると、再発行すれば通ると誤解される)。
|
|
98
|
-
|
|
99
|
-
### 例外 — 前提を求める行は、前提が満たされるまで毎回拒否する(joshuafolkken/kit#2807)
|
|
100
|
-
|
|
101
|
-
**`already_satisfied`(前提の行為がトランスクリプト末尾にあるか)を持つ行は、1 ラン 1 回の対象から外れる。** 前提が末尾に現れるまで、毎回拒否する。1 ラン 1 回のままだと、前提を飛ばしたランの再発行がそのまま通る。手順を読み飛ばしたランほどガードを素通りしてしまい、ガードの意味がない。対象は `issue-fold`・`issue-comments`・`rule-body`・`oracle-consulted:*` である。
|
|
102
|
-
|
|
103
|
-
従うランが詰まることはない。前提の行為を済ませれば、stand-down が先に答えて通すからである。記録を使い切る心配もないので、`batch:guard` との待避もしない。待避すると、10 秒の窓の中の再発行が前提を満たさないまま通ってしまう。配送文には「前提が末尾に現れるまで拒否する」と明記する。
|
|
104
|
-
|
|
105
|
-
**前提の証拠を読めないときは、拒否を基本とする。** たとえば前提の行為を確かめるための記録が読めないときがこれに当たる。意図して通す例外は、理由をコードのコメントに残す。現在の例外は次のとおりである。
|
|
106
|
-
|
|
107
|
-
- トランスクリプト自体を読めないとき(`hook-decision.ts`)
|
|
108
|
-
- 初回の起票で、畳み込む相手がないとき(`issue-fold.ts`)
|
|
109
|
-
- 進捗の記録がないとき(`early-heartbeat.ts`)
|
|
110
|
-
- git の読み取りに失敗して、変更なしとして扱うとき(`delivered-rules.ts` の `test-declared` 行)
|
|
111
|
-
|
|
112
|
-
## 本文のシェル評価は同じ機構の 1 行で覆った(joshuafolkken/kit#1198)
|
|
113
|
-
|
|
114
|
-
`delivered-rules.ts` の `shell-body` 行は、`-f body=` / `--body "` というフラグで引くのではなく、**二重引用符の本文値に `` ` `` か `$` が実際に含まれるとき**だけ発火する。`!`(履歴展開)は引き金に入れない。規則本文と引き金の死角は [`shell-body.md`](./shell-body.md) にある。経緯: `docs/maintainers/rule-delivery-rationale.md` →「本文のシェル評価を同じ機構の 1 行で覆った経緯」。
|
|
115
|
+
配送文は**ラン 1 回につき 1 度**しか出ない — 2 度目も拒否すれば、規則に従った直後の呼び出しを止めてしまう。だから**配送文には「同じ呼び出しをもう一度出せ」と明記する**。例外は 2 つで、繰り返す行為を止める項目は毎回発火し(joshuafolkken/kit#1570)、前提の行為を求める項目は前提が末尾に現れるまで毎回拒否する(joshuafolkken/kit#2807)。これとは別に、バッチングと調査の 2 ガードは同じ呼び出しを二度拒否しないまま、違反が間隔分続けば再び発火する(joshuafolkken/kit#2164)— 1 回きりの注意ではない。先の 2 つの例外の配送文には「同じ呼び出しをもう一度出せ」ではなく、それぞれ「これは毎回発火する」「前提が末尾に現れるまで拒否する」と明記する — 1 回きりと読まれると、再発行すれば通ると誤解される。前提の証拠を読めないときは拒否を基本とする。経緯と意図した通過例外: `docs/maintainers/rule-delivery-rationale.md` →「配送は 1 ラン 1 回」。
|
|
115
116
|
|
|
116
117
|
## マーカーテスト
|
|
117
118
|
|
|
118
|
-
|
|
119
|
+
各項目を固定するスイートの一覧: `docs/maintainers/rule-delivery-rationale.md` →「マーカーテスト」。
|
|
@@ -56,11 +56,9 @@ pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path>
|
|
|
56
56
|
|
|
57
57
|
**`$'…'` も安全である。** ANSI-C クォートの中ではコマンド置換も変数展開も起きない。`CLAUDE.md` が Telegram の本文に `--body=$'…'` を指定しているのはそのためであり、この規則はそれを置き換えるものではない。ただし本文が長くなるほどファイルの方が扱いやすい。
|
|
58
58
|
|
|
59
|
-
### 引き金つき配送
|
|
59
|
+
### 引き金つき配送
|
|
60
60
|
|
|
61
|
-
`pnpm josh rule:guard`
|
|
62
|
-
|
|
63
|
-
**引き金はフラグではなく本文の中身である** — 二重引用符の本文値にバッククォートか `$` が実際に含まれるときだけ発火し、プレースホルダの作例(`-f body="<plan>"`)では無言である(`docs/maintainers/shell-body-rationale.md` →「引き金をフラグでなく本文で引く理由」)。
|
|
61
|
+
`pnpm josh rule:guard` が、二重引用符の本文値にバッククォートか `$` が実際に含まれる `Bash` 呼び出しを拒否して本文を突きつける。拒否されたら本文をファイルに移して出し直す。配線は `docs/maintainers/shell-body-rationale.md` →「引き金つき配送にした理由」、引き金の設計は `docs/maintainers/shell-body-rationale.md` →「引き金をフラグでなく本文で引く理由」、固定しているテストは `docs/maintainers/shell-body-rationale.md` →「マーカーテスト」にある。
|
|
64
62
|
|
|
65
63
|
### 引き金が見えないもの
|
|
66
64
|
|
|
@@ -69,12 +67,4 @@ pnpm josh notify --task-type confirmation --issue-url "<url>" --body-file <path>
|
|
|
69
67
|
- **`-b`(GitHub CLI の `--body` の短縮形)は覆っていない** — 同じ綴りが `git checkout -b` のブランチ名でもあり、そこで拒否するのは誤ったターンでの発火になる
|
|
70
68
|
- **`-f title="…"`** は覆っていない。タイトルは英語へ正規化された短い語であり、バッククォートを含む運用がない
|
|
71
69
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
### マーカーテスト
|
|
75
|
-
|
|
76
|
-
- `scripts/josh/cli-body.test.ts` — バッククォート・`$` を含む本文がファイル経由で無改変に通ること、`-` が標準入力を読むこと、通常ファイル以外の読める経路(`/dev/stdin`・プロセス置換)を開けること、インラインとファイルの同時指定を拒否すること
|
|
77
|
-
- `scripts/rules/shell-body-trigger.test.ts` — 危険な綴りで発火し、プレースホルダ・`@file` 形式・エスケープ済み `\$` では無言であること。`body=` のどちら側に引用符があっても発火すること、`$( … )` で包んでもバッククォートは免除されないこと、`$( … )` の中の引用符で捕捉が切れないことを、いずれも発火・非発火の対で固定する
|
|
78
|
-
- `scripts/rules/raw-field-body.test.ts` — `-f` / `--raw-field body=@` の綴りで発火し、`-F` / `--field body=@`・`@` を含まない本文・`labels[]=`・`pnpm josh issue:comment` では無言であること
|
|
79
|
-
- `scripts/rules/delivered-rules.test.ts` — 上の引き金が列挙表の行に配線されており、非 `Bash` ツールでは無言であること
|
|
80
|
-
- `scripts/rules/shell-body-rule.test.ts` — 常駐 1 行がこの文書を指しており、配送文が被害・安全な綴り・再発行の指示を運ぶこと。**この一覧そのものも固定する** — 一覧が「あるスイートが何を固定しているか」を書きながら、そのケースが存在しないという食い違いが実際に起きた(`-` の標準入力)
|
|
70
|
+
引き金が見えない綴りでも規則は同じく拘束する。フックが走らないエージェントも同じである。
|