[docs] standardize GitHub linking convention across archived Spectra proposals (mid-plan tangential from #56)

[kiki830621]

Source

Surfaced during /idd-plan #56 Step 2.5 tangential sweep (2026-05-18).

Observation

Inspected all 6 archived Spectra proposals under openspec/changes/archive/*/proposal.md for GitHub linking patterns:

Archive	Linking pattern
2026-05-04-add-vagueness-layer-routing	(none)
2026-05-04-idd-all-hitl-mode	(none)
2026-05-05-add-bundle-flags-to-idd-issue	(none)
2026-05-10-add-idd-all-chain-skill	**GitHub-side tracker**: #44 (explicit)
2026-05-10-add-multi-finding-source-mode-to-idd-issue	(none — only mentions #46 / #47 in 'Future' context)
2026-05-18-multi-root-traversal-idd-all-chain	(none)

Only 1/6 archives use the explicit **GitHub-side tracker** marker. This forces #56's auto-post-Implementation-Complete detection to walk a 3-fallback chain (explicit marker / Refs-Closes-Fixes / commit grep). Standardizing on the explicit marker would simplify future tooling.

Suggested

Document GitHub-side tracker as canonical convention in openspec/LANGUAGE.md (or a Spectra workflow doc), retroactively or going-forward as user prefers.

Priority

P3 — quality-of-life, not blocking. Issue #56 implementation handles missing markers via fallbacks already.

---

Current Status

Phase: closed

Complexity

Simple — Layer 1 (docs/pattern deliverable, no behavior change).

Next

Done. Cluster PR #101 merged (squash 0eb419c); closed via /idd-close.

History

• 2026-05-19 — diagnosed (Simple): comment-4484830923

• 2026-05-19 — implemented (cluster-PR idd/cluster-simple-docs-followups): comment-4484901803

• 2026-05-19 — verified (cluster PR cluster: 6 Simple docs/pattern follow-ups (#96-backlog triage) #101, 6-AI R1 CONDITIONAL → R2 PASS)

• 2026-05-19 — merged (PR cluster: 6 Simple docs/pattern follow-ups (#96-backlog triage) #101 → squash 0eb419c) + closed: comment-4485337912

[kiki830621]

Diagnosis

Type

documentation (convention standardization)

Analysis

Surfaced during /idd-plan #56 Step 2.5 tangential sweep. An inspection of all 6 archived Spectra proposals under openspec/changes/archive/*/proposal.md found only 1 of 6 uses the explicit **GitHub-side tracker**: #NN marker. The other 5 carry no canonical linking marker. This forces #56's auto-post-Implementation-Complete detection to walk a 3-fallback chain (explicit marker → Refs/Closes/Fixes → commit grep). Standardizing on the explicit marker simplifies all future tooling that needs to resolve a Spectra change ↔ GitHub issue mapping.

Impact

• File: openspec/LANGUAGE.md (or a Spectra workflow doc) — document the convention
• No behavior change — documents a convention going-forward; retroactive application to the 5 unmarked archives is optional (issue body marks it "as user prefers")

Strategy

• Document **GitHub-side tracker**: #NN as the canonical proposal→issue linking convention in openspec/LANGUAGE.md
• State scope: going-forward is mandatory; retroactive backfill of the 5 unmarked archives is optional (out of scope for this ticket unless trivial)

Complexity

Simple

Layer 1 disqualifier hit — deliverable is a doc convention paragraph, no behavior change, single file. (#56's tooling already handles missing markers via fallbacks, so this is pure quality-of-life.)

Risks

• Low. If retroactive backfill is later wanted, that's a separate mechanical pass — keep it out of this ticket's scope to stay Simple.

Vagueness Pre-check

• V1: 2 (Clear) — the marker format + target file are specified
• V4: 3 (Mostly clear) — "retroactively or going-forward as user prefers" leaves the retroactive scope to the writer; resolved by scoping it out (going-forward only)
• Triggered: no — both axes ≤ 3

Next Step

/idd-all-chain (batched with the other 5 Simple cluster issues).

[kiki830621]

Implementation Plan

• openspec/LANGUAGE.md — create the file; document **GitHub-side tracker**: #NN as the canonical Spectra-proposal → GitHub-issue linking convention

Adaptation note: the issue's Strategy named openspec/LANGUAGE.md as the target, but the file does not currently exist (openspec/ has only changes/, specs/, config.yaml). LANGUAGE.md is a standard OpenSpec file for project spec-authoring conventions, so creating it with this convention is consistent with the issue's primary suggestion. Going-forward convention only; retroactive backfill of the 5 unmarked archives is out of scope.

Cluster-PR (#96-backlog Simple cluster). Refs #90.

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• openspec/LANGUAGE.md — created the file; documented **GitHub-side tracker**: #NN as the canonical Spectra-proposal → GitHub-issue linking convention (going-forward mandatory; retroactive backfill scoped out) → commit 08f7c26

Changes

• 08f7c26: docs: standardize GitHub-side tracker marker convention in openspec/LANGUAGE.md (Refs [docs] standardize GitHub linking convention across archived Spectra proposals (mid-plan tangential from #56) #90)

Files Changed

• openspec/LANGUAGE.md (new file, +37)

Scope Compliance

Adaptation from the Strategy: the issue named openspec/LANGUAGE.md as the target, but the file did not exist (openspec/ had only changes/, specs/, config.yaml). LANGUAGE.md is a standard OpenSpec file for project spec-authoring conventions, so creating it with this convention is consistent with the issue's primary suggestion ("openspec/LANGUAGE.md or a Spectra workflow doc"). Retroactive backfill of the 5 unmarked archived proposals is explicitly scoped out (the issue marked it optional; idd-close's fallback chain already handles their absence).

Next: verification pending (cluster PR — #96-backlog Simple cluster)

[kiki830621]

Closing Summary

Problem

Only 1 of 6 archived Spectra proposals carried an explicit **GitHub-side tracker**: #NN marker. This forced idd-close's auto-post-Implementation-Complete detection (#56) to walk a 3-fallback chain (explicit marker → Refs/Closes/Fixes scan → commit grep) on every tooling run.

Root Cause

No documented convention for linking a Spectra change proposal to its GitHub issue.

Solution

Documented **GitHub-side tracker**: #NN as the canonical proposal→issue linking convention (going-forward mandatory; retroactive backfill of the 5 unmarked archives scoped out — idd-close's fallback already handles their absence).

R1 → R2 correction: R1 created the convention at openspec/LANGUAGE.md. The 6-AI verify Devil's Advocate found (and the coordinator confirmed) that openspec/LANGUAGE.md is a reserved filename — spectra-discuss SKILL.md reads it as "the project's canonical vocabulary" (terms with definition/avoid/why notes) and has a vocabulary-drift capture mechanism targeting it. A workflow convention there collides with that contract. R2 relocated the convention to openspec/CONVENTIONS.md — a purpose-built filename, parallel to LANGUAGE.md in openspec/, verified not referenced by any skill.

Note: the Implementation Complete checklist item names openspec/LANGUAGE.md (its R1 state). The delivered file is openspec/CONVENTIONS.md per the R2 relocation above — this Closing Summary is the accurate final record.

Verification

6-AI cluster verify on PR #101. R1: CONDITIONAL PASS — Devil's Advocate finding DA-2 (LANGUAGE.md reserved-name collision) blocking. R2: relocated to openspec/CONVENTIONS.md; grep -rn 'CONVENTIONS.md' across all skill/command/agent/plugin trees confirmed not reserved. R2 aggregate: PASS.

Changes

• Squash-merged to main as 0eb419c (PR cluster: 6 Simple docs/pattern follow-ups (#96-backlog triage) #101)
• Pre-squash: 08f7c26 (R1 — created openspec/LANGUAGE.md) + e49d6cb (R2 — git mv → openspec/CONVENTIONS.md, content reframed), both Refs #90
• Final delivered file: openspec/CONVENTIONS.md (+41)

Verify reports: PR #101 R1 · R2

Distribution Sync

• Detected: plugin (issue-driven-dev)
• Choice: chain /plugin-tools:plugin-update issue-driven-dev
• Outcome: bumped v2.62.0 → v2.63.0 (plugin.json + marketplace.json + CHANGELOG, commit a410e35); claude plugin marketplace update + claude plugin update → installed plugin now v2.63.0. This cluster's 6 issues ship together in v2.63.0.
• At: 2026-05-19T07:29:42Z