Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 6 additions & 0 deletions .claude/.idd/attachments/issue-502/_manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"issue": 502,
"fetched_at": "2026-11-12T08:02:05Z",
"fetched_by": "idd-diagnose",
"files": []
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
schema: spec-driven
created: 2026-11-12
created_by: che cheng <kiki830621@gmail.com>
created_with: claude
archived_by: che cheng <kiki830621@gmail.com>
archived_at: 2026-11-12
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
**GitHub-side tracker**: #502

## Problem

`idd-comment` Step 0.7 判斷這次呼叫是不是從 spectra-discuss 中斷進來的,判成是的時候 Step 7 會寫 bookmark 並印 resume prompt。四個訊號任一成立就算,其中一個是「repo 裡有開著的 Spectra change」。這個訊號說的是 repo 的狀態,不是這次呼叫從哪裡來:只要 repo 裡有任何一個開著的 change,每一次 `/idd-comment` 都被判成從 spectra-discuss 進來,主題還是空的。4.0.0 之後每張實作中的 issue 在封存前都有一個開著的 change,所以在這個 repo 幾乎每次都成立。#126 報過同一件事,當時只追蹤、沒有改。

## Root Cause

`rules/spectra-bridge.md` 把這個訊號標成 60%(could be unrelated),結論那一句卻寫「任一訊號成立就啟動」,區塊照著實作。沒有規格寫這段偵測,也沒有測試執行它(`bridge-path` 只檢查 bridge 檔的路徑)。

## Proposed Solution

- 維護者已決定(2026-11-12):拿掉這個訊號。
- `idd-comment` Step 0.7 的區塊拿掉查開著的 change 的那一段,不再執行 `spectra`。其他三個訊號不變:`--resume-spectra`、`--source` 含 `spectra-discuss`、bridge 檔的 `active_spectra_session` 是 true。
- `rules/spectra-bridge.md` 的偵測表拿掉那一列,並寫一句為什麼不算。
- plugin 的 `CLAUDE.md` 與 `README.md` 各有一句列出訊號,一起改;這兩句把 bridge 檔那個訊號寫成「檔案存在」,改成與規則一致的「存在而且 `active_spectra_session` 是 true」。
- 新增一條 requirement 與兩個 Example;新增 suite `spectra-bridge-detect`,把區塊抽出來執行。

## Non-Goals

- 另外兩個做法(要有另一個訊號同時成立才算、只認名稱點名這張 issue 的 change):前者等於拿掉,後者在這個 repo 仍會誤判,維護者沒有選。
- bridge 由 `--source` 或 bridge 檔啟動時主題是空的:另一個問題,#524。
- 規則的「Skill responsibilities」表把 `idd-issue` 寫成已實作:#524。
- 規則表裡「Conversation context」那一列:那是由執行 skill 的模型判斷的,不在區塊裡,這次不動。
- ASSUMPTION: 不升版號,CHANGELOG 加在既有的 Unreleased 區塊。

## Success Criteria

- `spectra-bridge-detect` 在改動前失敗:只有開著的 change 時區塊啟動了 bridge、而且呼叫了 `spectra`;四個地方都還列著那個訊號。改動後全部通過。
- 另外三個訊號各自單獨成立時仍然啟動(改動前後都通過)。
- `bridge-path` 照舊通過;`rules/spectra-bridge.md` 的 Hard rule 6 仍在第 116 行。
- run-all-tests 的全部 suite 與 spectra-archive-post-ic 通過;連結檢查對新增的 requirement 回 ok。

## Capabilities

### New Capabilities

- `spectra-bridge-detection`: 寫明 IDD skill 憑哪些訊號判斷自己是從 spectra-discuss 中斷進來的(`rules/spectra-bridge.md` 的 bridge),以及哪些不算。

### Modified Capabilities

(none)

## Impact

- Affected specs: spectra-bridge-detection(新增,ADDED requirement「Open Spectra changes do not turn the spectra bridge on」)
- Affected code:
- Modified: plugins/issue-driven-dev/skills/idd-comment/SKILL.md
- Modified: plugins/issue-driven-dev/rules/spectra-bridge.md
- Modified: plugins/issue-driven-dev/CLAUDE.md
- Modified: plugins/issue-driven-dev/README.md
- Modified: plugins/issue-driven-dev/CHANGELOG.md
- New: plugins/issue-driven-dev/scripts/tests/spectra-bridge-detect/test.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
## Purpose

Defines which signals tell an IDD skill that it was called in the middle of a spectra-discuss session, so that it saves a bookmark and prints a resume prompt (the bridge of `rules/spectra-bridge.md`), and which facts are not such a signal. It exists so that the state of the repository is not read as where a call came from.

## ADDED Requirements

### Requirement: Open Spectra changes do not turn the spectra bridge on

The detection block of `skills/idd-comment/SKILL.md` Step 0.7 SHALL set `SPECTRA_BRIDGE_ACTIVE=1` when at least one of these holds, and SHALL leave it `0` otherwise: the `--resume-spectra` value is not empty; the `--source` value contains `spectra-discuss`, in any letter case; a bridge file whose `active_spectra_session` is `true` exists at `.claude/.idd/state/bridge.json`, or at the legacy path `.claude/state/idd-bridge.json` when the new path has no file. Open Spectra changes in the repository SHALL NOT be a signal, and the block SHALL NOT run the `spectra` command. The places that list the signals for a reader SHALL NOT list open or in-flight Spectra changes: the detection table of `rules/spectra-bridge.md`, the Step 0 task description of `idd-comment`, and the sentence of the plugin's `CLAUDE.md` and of its `README.md` that lists them. Those two sentences SHALL name `active_spectra_session` for the bridge file.

No executable check: the row "Conversation context" of the rule's table is judged by the model that runs the skill and is not part of the block; what the skill does once the bridge is on (Step 7) is carried out by that model too.

#### Scenario: A comment in a repository that has open changes

- **GIVEN** a repository with eight open Spectra changes, none of them about the comment being posted
- **AND** `/idd-comment` is called without `--resume-spectra`, with a `--source` that does not mention spectra-discuss, and no bridge file exists
- **WHEN** Step 0.7 runs
- **THEN** `SPECTRA_BRIDGE_ACTIVE` stays `0`, no bookmark is written and no resume prompt is printed

##### Example: what turns the spectra bridge on

In every row the block does not run `spectra`.

| `--resume-spectra` | `--source` | Bridge file | Open Spectra changes | `SPECTRA_BRIDGE_ACTIVE` |
| --- | --- | --- | --- | --- |
| empty | empty | none | 8 | `0` |
| empty | empty | none | none | `0` |
| `my topic` | empty | none | none | `1` |
| empty | `Spectra-Discuss session` | none | none | `1` |
| empty | empty | new path, `active_spectra_session: true` | none | `1` |
| empty | empty | legacy path only, `active_spectra_session: true` | none | `1` |
| empty | empty | new path, `active_spectra_session: false` | 8 | `0` |

##### Example: where the bridge signals are listed

| Place | Lists open or in-flight Spectra changes | Names `active_spectra_session` for the bridge file |
| --- | --- | --- |
| the rows of the detection table in `rules/spectra-bridge.md` | no | yes |
| the `detect_spectra_context` task description in `skills/idd-comment/SKILL.md` | no | not checked |
| the "Step 0.7 Detect" sentence of the plugin's `CLAUDE.md` | no | yes |
| the "Step 0.7 Detect" sentence of the plugin's `README.md` | no | yes |
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
## 1. 測試先行

- [x] 1.1 偵測區塊有可執行的檢查:依 requirement「Open Spectra changes do not turn the spectra bridge on」的 Example「what turns the spectra bridge on」,新增 suite spectra-bridge-detect:從 idd-comment 的 SKILL.md 抽出 Step 0.7 的 bash 區塊,放進空目錄、只有假的 spectra 的環境執行,Example 的七列各一個檢查,另加一個檢查確認七列都沒有呼叫 spectra;測試檔帶標記 spec-example: spectra-bridge-detection / what turns the spectra bridge on。驗證:改 SKILL.md 之前,「只有開著的 change」那一列與「沒有呼叫 spectra」失敗,其餘六列通過。
- [x] 1.2 列出訊號的四個地方有檢查:依 Example「where the bridge signals are listed」,同一個 suite 檢查規則偵測表的每一列、idd-comment Step 0 的 task 描述、plugin 的 CLAUDE.md 與 README 列出訊號的那一句,都沒有把開著的 change 列為訊號,而且 CLAUDE.md 與 README 的那一句寫的是 bridge 檔的 active_spectra_session;測試檔帶標記 spec-example: spectra-bridge-detection / where the bridge signals are listed。驗證:改文字之前這些檢查失敗。

## 2. skill、規則與說明

- [x] 2.1 idd-comment Step 0.7 拿掉查開著的 change 的那一段,bridge 檔那一段的編號改成 Signal 3,區塊下面加一句說明為什麼開著的 change 不算;Step 0 的 task 描述拿掉那個訊號。驗證:1.1 全部通過;bridge-path 照舊通過。
- [x] 2.2 rules/spectra-bridge.md 的偵測表拿掉那一列,結論那一句後面加一句說明開著的 change 不算。驗證:1.2 對規則的檢查通過;Hard rule 6 仍在第 116 行(idd-comment 與 bridge-path 用行號引用它)。
- [x] 2.3 plugin 的 CLAUDE.md 與 README 列出訊號的那一句:拿掉那個訊號,bridge 檔寫成存在而且 active_spectra_session 是 true。驗證:1.2 對這兩個檔的檢查通過。

## 3. 收尾

- [x] 3.1 CHANGELOG 的 Unreleased 加 Fixed 條目(#502)。驗證:git diff 只有新增行,已發布版本的條目沒有改動。
- [x] 3.2 跑 spectra-bridge-detect、bridge-path 與整套測試(run-all-tests.sh 與 spectra-archive-post-ic)。驗證:結束碼都是 0。
43 changes: 43 additions & 0 deletions openspec/specs/spectra-bridge-detection/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# spectra-bridge-detection Specification

## Purpose

Defines which signals tell an IDD skill that it was called in the middle of a spectra-discuss session, so that it saves a bookmark and prints a resume prompt (the bridge of `rules/spectra-bridge.md`), and which facts are not such a signal. It exists so that the state of the repository is not read as where a call came from.

## Requirements

### Requirement: Open Spectra changes do not turn the spectra bridge on

The detection block of `skills/idd-comment/SKILL.md` Step 0.7 SHALL set `SPECTRA_BRIDGE_ACTIVE=1` when at least one of these holds, and SHALL leave it `0` otherwise: the `--resume-spectra` value is not empty; the `--source` value contains `spectra-discuss`, in any letter case; a bridge file whose `active_spectra_session` is `true` exists at `.claude/.idd/state/bridge.json`, or at the legacy path `.claude/state/idd-bridge.json` when the new path has no file. Open Spectra changes in the repository SHALL NOT be a signal, and the block SHALL NOT run the `spectra` command. The places that list the signals for a reader SHALL NOT list open or in-flight Spectra changes: the detection table of `rules/spectra-bridge.md`, the Step 0 task description of `idd-comment`, and the sentence of the plugin's `CLAUDE.md` and of its `README.md` that lists them. Those two sentences SHALL name `active_spectra_session` for the bridge file.

No executable check: the row "Conversation context" of the rule's table is judged by the model that runs the skill and is not part of the block; what the skill does once the bridge is on (Step 7) is carried out by that model too.

#### Scenario: A comment in a repository that has open changes

- **GIVEN** a repository with eight open Spectra changes, none of them about the comment being posted
- **AND** `/idd-comment` is called without `--resume-spectra`, with a `--source` that does not mention spectra-discuss, and no bridge file exists
- **WHEN** Step 0.7 runs
- **THEN** `SPECTRA_BRIDGE_ACTIVE` stays `0`, no bookmark is written and no resume prompt is printed

##### Example: what turns the spectra bridge on

In every row the block does not run `spectra`.

| `--resume-spectra` | `--source` | Bridge file | Open Spectra changes | `SPECTRA_BRIDGE_ACTIVE` |
| --- | --- | --- | --- | --- |
| empty | empty | none | 8 | `0` |
| empty | empty | none | none | `0` |
| `my topic` | empty | none | none | `1` |
| empty | `Spectra-Discuss session` | none | none | `1` |
| empty | empty | new path, `active_spectra_session: true` | none | `1` |
| empty | empty | legacy path only, `active_spectra_session: true` | none | `1` |
| empty | empty | new path, `active_spectra_session: false` | 8 | `0` |

##### Example: where the bridge signals are listed

| Place | Lists open or in-flight Spectra changes | Names `active_spectra_session` for the bridge file |
| --- | --- | --- |
| the rows of the detection table in `rules/spectra-bridge.md` | no | yes |
| the `detect_spectra_context` task description in `skills/idd-comment/SKILL.md` | no | not checked |
| the "Step 0.7 Detect" sentence of the plugin's `CLAUDE.md` | no | yes |
| the "Step 0.7 Detect" sentence of the plugin's `README.md` | no | yes |
9 changes: 9 additions & 0 deletions plugins/issue-driven-dev/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,15 @@ Version number left to the release.
the distribution sync. The order of the steps is unchanged. A new capability, `idd-close-doc-sync`, states the
position, and the doc-sync-sweep suite reads SKILL.md and compares the three places; it also runs the comparison
on copies broken on purpose, one for each thing it compares, so each part of the check is seen to fail.
- **An open Spectra change no longer makes `/idd-comment` think it was called from spectra-discuss (#502).** Step 0.7
turned the spectra bridge on whenever `spectra list` showed any open change, whatever the comment was about; Step 7
then had to write a bookmark with an empty topic and print a resume prompt for a discussion that did not exist
(reported before as #126). Since 4.0.0 every issue being implemented has an open change until it is archived, so in
this repository the signal held on almost every call. It is removed. The bridge turns on for `--resume-spectra`,
for a `--source` that contains `spectra-discuss`, or for a bridge file whose `active_spectra_session` is true, and
detection no longer runs `spectra`. `rules/spectra-bridge.md` and the summaries in the plugin's CLAUDE.md and README
list the same three signals; the two summaries used to say the bridge file only had to exist. A new capability,
`spectra-bridge-detection`, states this, and a new suite, spectra-bridge-detect, runs the block one signal at a time.

## [4.0.1] - 2026-11-11

Expand Down
2 changes: 1 addition & 1 deletion plugins/issue-driven-dev/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ flag 支援:`idd-issue`、`idd-comment`(其他 skill 走 prose detection)

當 IDD skill 在 `spectra-discuss` session 中被叫起來(例如討論到一半要把結論 comment 到 issue),依 [`rules/spectra-bridge.md`](rules/spectra-bridge.md) 提供 round-trip context:

1. **Step 0.7 Detect** — `--resume-spectra="<topic>"` flag、`--source` 含 `spectra-discuss`、`spectra list` 有 in-flight、`.claude/.idd/state/bridge.json` 存在 — 任一觸發 `SPECTRA_BRIDGE_ACTIVE=1`
1. **Step 0.7 Detect** — `--resume-spectra="<topic>"` flag、`--source` 含 `spectra-discuss`、`.claude/.idd/state/bridge.json` 存在且 `active_spectra_session` 為 true — 任一觸發 `SPECTRA_BRIDGE_ACTIVE=1`(repo 裡有開著的 Spectra change 不算,#502)
2. **Step N-1 寫 bookmark** — `.claude/.idd/state/bridge.json` 含 topic / issue / open_questions / next_step_hint
3. **Step N 印 Resume Prompt** — 可貼回 spectra-discuss 的 prompt block,使用者控 pacing

Expand Down
2 changes: 1 addition & 1 deletion plugins/issue-driven-dev/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ GitHub mentions are an irreversible side effect; the rule is mandatory not advis

When `spectra-discuss` is interrupted mid-flow to invoke an IDD skill (e.g. "let me capture this finding to the issue"), the bridge protocol preserves and resumes context:

- **Step 0.7 Detect** — `--resume-spectra="<topic>"` flag, `--source` contains `spectra-discuss`, `spectra list --json` shows in-flight changes, or `.claude/.idd/state/bridge.json` exists (legacy fallback: `.claude/state/idd-bridge.json`) → `SPECTRA_BRIDGE_ACTIVE=1`
- **Step 0.7 Detect** — `--resume-spectra="<topic>"` flag, `--source` contains `spectra-discuss`, or `.claude/.idd/state/bridge.json` exists with `active_spectra_session: true` (legacy fallback: `.claude/state/idd-bridge.json`) → `SPECTRA_BRIDGE_ACTIVE=1`. Open Spectra changes in the repository are not a signal (#502)
- **Step N-1 Bookmark** — `.claude/.idd/state/bridge.json` written with verbatim `spectra_topic` + `issue_url` + `open_questions[]` + `idd_action_url` + `next_step_hint`
- **Step N Resume Prompt** — final output prints a clearly-delimited `↩ Resume spectra-discuss` block with a copy-pasteable `/spectra-discuss <topic>...` prompt

Expand Down
2 changes: 1 addition & 1 deletion plugins/issue-driven-dev/rules/spectra-bridge.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,11 @@ An IDD skill is "in a spectra context" if **any** of these signals are true:
|--------|--------|------------|
| `--resume-spectra="<topic>"` flag | explicit | 100% |
| `--source` argument contains `spectra-discuss` | explicit-ish | 95% |
| `spectra list --json` returns in-flight changes | environmental | 60% (could be unrelated) |
| `.claude/.idd/state/bridge.json` exists with `active_spectra_session: true` | written by spectra (future contract) | 100% |
| Conversation context (skill caller knows it was launched from spectra) | implicit | varies |

If at least one signal fires → set `SPECTRA_BRIDGE_ACTIVE=1`. Otherwise, no bridge action.
Open Spectra changes in the repository are **not** a signal (#502): they describe the repository, not where this call came from, so detection never runs `spectra`.

## Bookmark file (Step N before exit)

Expand Down
Loading
Loading