Install spectacles SDD suite (ref: v0.1.2) by norrietaylor · Pull Request #360 · gominimal/minimal

norrietaylor · 2026-06-07T00:13:07Z

Installs the spectacles SDD agent suite (ADR 0004) via scripts/quick-setup.sh. Wrappers pin hosted reusable workflows at @v0.1.2. Labels, variables, and secrets were applied directly; the file artifacts in this PR honor the protected default branch. Merge to activate the workflows.

Summary by CodeRabbit

Release Notes

New Features
- Added automated spike execution and re-entry workflows for deterministic spike-wave management.
Documentation
- Added spike protocol guide for authors covering branch naming, required frontmatter, status values, and cleanup requirements.
Chores
- Updated workflow action versions to v0.1.2 across multiple pipelines.
- Added explicit observability endpoint configuration support.
- Enhanced workflow permissions for improved security posture.

coderabbitai · 2026-06-07T00:13:17Z

📝 Walkthrough

Walkthrough

This PR upgrades the SDD (Spectacles Dispatch Dispatch) GitHub Actions platform from v0.1.0 to v0.1.2 across all workflows, adds check-suite CI failure handling with implicit revise routing, introduces deterministic task label state management and Unit issue closing in dispatch, implements phase C cycle detection in triage, and introduces two new spike wave orchestration workflows with supporting documentation.

Changes

SDD v0.1.2 Platform Update

Layer / File(s)	Summary
Version bump and observability endpoint unification `.github/workflows/distillery-sync.yml`, `.github/workflows/sdd-dispatch.yml`, `.github/workflows/sdd-execute-haiku.yml`, `.github/workflows/sdd-execute-opus.yml`, `.github/workflows/sdd-execute-sonnet.yml`, `.github/workflows/sdd-monitor.yml`, `.github/workflows/sdd-pr-sanitize.yml`, `.github/workflows/sdd-review.yml`, `.github/workflows/sdd-spec.yml`, `.github/workflows/sdd-triage-dedupe-tasks.yml`, `.github/workflows/sdd-triage-promote-ready.yml`, `.github/workflows/sdd-validate.yml`	All Spectacles action and reusable workflow references updated from `@v0.1.0` to `@v0.1.2`. Added explicit `GH_AW_OTEL_ENDPOINT` secret pass-through to reusable workflow calls with documentation for observability endpoint resolution and safe unsetting.
Check-suite failure routing in execute wrappers `.github/workflows/sdd-execute-haiku.yml`, `.github/workflows/sdd-execute-opus.yml`, `.github/workflows/sdd-execute-sonnet.yml`	Three execute wrappers now trigger on `check_suite.completed` events. Concurrency key changed to route failure-like conclusions on `sdd/` branches by PR number (or head branch) instead of `run_id`. Route job permissions expanded with `checks: read` and gating logic updated to recognize `check_suite.completed` failure-like conclusions as implicit `/revise` directives.
Dispatch label state determinism and Unit closing `.github/workflows/sdd-dispatch.yml`	Compute job now exports `closeable_units` output. Dispatch job labeling becomes idempotent: adds `sdd:in-progress` (treating `422` as already-present) then removes `sdd:ready` (treating `404` as already-absent). Lifecycle job parses and closes nominated Units from `CLOSEABLE_UNITS` JSON. Initial dispatch `/dispatch` command now fails job on `sdd:dispatched` label API errors instead of logging-only.
Triage phase C cycle detection backstop `.github/workflows/sdd-triage.yml`	New `cycle-detect` job runs after `sdd-triage` when phase is `C`, invokes cycle detection, and on cycle/tree incompleteness, mints App token to label tracking issue with `needs-human` and post tailored backstop comment describing the detected cycle or unresolvable `blocked by` reference.
Spike wave actuation workflow `.github/workflows/sdd-spike-actuator.yml`	New workflow triggers on `issues` events (`opened`, `labeled`) filtered to `kind:spike` label. Resolves spike's parent tracking issue and gates on `armed` status. When armed, mints GitHub App token and posts `/execute` comment to spike sub-issue via `github-script` with failure handling.
Spike wave re-entry orchestration `.github/workflows/sdd-spike-reentry.yml`	New workflow handles `issues.closed` and `issues.unlabeled` events for `kind:spike` children when phase B cannot naturally drain. Walk job validates spike child and computes armed/drained status, route job builds reentry context, and conditional sdd-triage job calls reusable workflow with constructed context and explicit secret mappings.
Spike protocol documentation `docs/spikes/README.md`	New documentation defines spike authoring protocol: file naming, branch conventions, frontmatter and section requirements, status values, budget tracking, evidence quoting for parked spikes, `needs-human` hand-off behavior, and cleanup requirements for docs-only diffs.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

gominimal/spectacles-test#241: PR updates .github/workflows/distillery-sync.yml workflow with v0.1.2 reference and OTEL secret wiring, directly addressing the distillery-sync observability endpoint resolution.

Possibly related PRs

gominimal/minspec-test#60: Both PRs touch SDD workflow wiring in .github/workflows/sdd-dispatch.yml, with the main PR evolving v0.1.0 wrapper logic by updating actions and changing dispatch/lifecycle labeling behavior.
gominimal/minimal#307: Main PR directly updates the same Spectacles SDD wrapper workflows introduced in PR #307—bumping versions from @v0.1.0 → @v0.1.2 and adding GH_AW_OTEL_ENDPOINT secret pass-through—plus related routing and label logic changes.
gominimal/webapp#102: Both PRs modify the same GitHub workflow wiring, especially .github/workflows/sdd-dispatch.yml (task label handling and making sdd:dispatched failures fatal) and execute wrappers' check_suite→implicit /revise routing, with the main PR adding newer @v0.1.2 versions and OTEL plumbing.

Suggested reviewers

twitchyliquid64

Poem

🐰 Workflows dance in v0.1.2 finery,
Check-suite storms now route revise machinery,
Spike waves actuate with deterministic grace,
Cycles caught backstage, OTEL tracks the race!
Another hop toward observability's embrace. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: installing the spectacles SDD suite at version v0.1.2, which is the primary purpose evident across all workflow updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/sdd-spike-actuator.yml:
- Around line 79-87: The "Mint App token" step (id: app, uses:
actions/create-github-app-token@v3) is creating a token with full App
permissions; restrict it by adding a permissions entry so the token only has
issues: write access. Update the step to include the permissions parameter
(e.g., permissions: issues: write) so the minted token can only call
github.rest.issues.createComment and nothing else.

In @.github/workflows/sdd-triage.yml:
- Around line 195-205: The catch block around github.rest.issues.addLabels
swallows failures (using core.info) causing the workflow to proceed as if the
tracker was parked; change the error handling so failures cause the job to
fail-closed: in the catch for github.rest.issues.addLabels (referencing
addLabels, tracking and core.info) either rethrow the error or call
core.setFailed with a descriptive message and the caught error.message, and
ensure any subsequent "parked" comment/posting only runs when addLabels
succeeded (i.e., move or gate the comment logic behind successful addLabels).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9b41d0e7-4f83-451e-8f1a-65cb5864b8e7

📥 Commits

Reviewing files that changed from the base of the PR and between 35fe939 and fd73b37.

📒 Files selected for processing (16)

.github/workflows/distillery-sync.yml
.github/workflows/sdd-dispatch.yml
.github/workflows/sdd-execute-haiku.yml
.github/workflows/sdd-execute-opus.yml
.github/workflows/sdd-execute-sonnet.yml
.github/workflows/sdd-monitor.yml
.github/workflows/sdd-pr-sanitize.yml
.github/workflows/sdd-review.yml
.github/workflows/sdd-spec.yml
.github/workflows/sdd-spike-actuator.yml
.github/workflows/sdd-spike-reentry.yml
.github/workflows/sdd-triage-dedupe-tasks.yml
.github/workflows/sdd-triage-promote-ready.yml
.github/workflows/sdd-triage.yml
.github/workflows/sdd-validate.yml
docs/spikes/README.md

bryan-minimal

LGTM

norrietaylor added 20 commits June 6, 2026 17:12

chore: install sdd-spec wrapper (spectacles quick-setup)

bf6fb9d

chore: install sdd-triage wrapper (spectacles quick-setup)

c60972d

chore: install sdd-dispatch wrapper (spectacles quick-setup)

8af9084

chore: install sdd-execute-haiku wrapper (spectacles quick-setup)

5f7b6d1

chore: install sdd-execute-sonnet wrapper (spectacles quick-setup)

1952e02

chore: install sdd-execute-opus wrapper (spectacles quick-setup)

4dd9f63

chore: install sdd-validate wrapper (spectacles quick-setup)

95aa2df

chore: install sdd-review wrapper (spectacles quick-setup)

ccb492c

chore: install distillery-sync wrapper (spectacles quick-setup)

175c213

chore: install sdd-pr-sanitize wrapper (spectacles quick-setup)

85e395a

chore: install sdd-triage-dedupe-tasks wrapper (spectacles quick-setup)

e60123f

chore: install sdd-triage-promote-ready wrapper (spectacles quick-setup)

de1527c

chore: install sdd-monitor wrapper (spectacles quick-setup)

c498f1a

chore: install sdd-spike-actuator wrapper (spectacles quick-setup)

1481f3a

chore: install sdd-spike-reentry wrapper (spectacles quick-setup)

927ed5e

chore: install feature issue template (spectacles quick-setup)

7222f07

chore: install bug issue template (spectacles quick-setup)

645aace

chore: install chore issue template (spectacles quick-setup)

036540b

chore: install spec issue template (spectacles quick-setup)

2da5f83

docs: install spike-author README (spectacles quick-setup)

fd73b37

coderabbitai Bot reviewed Jun 7, 2026

View reviewed changes

Comment thread .github/workflows/sdd-spike-actuator.yml

Comment thread .github/workflows/sdd-triage.yml

bryan-minimal approved these changes Jun 8, 2026

View reviewed changes

norrietaylor merged commit 29501d0 into main Jun 8, 2026
44 of 50 checks passed

norrietaylor deleted the spectacles/install branch June 8, 2026 20:32

Navigation Menu

Uh oh!

Install spectacles SDD suite (ref: v0.1.2) - #360

Install spectacles SDD suite (ref: v0.1.2)#360
norrietaylor merged 20 commits into
mainfrom
spectacles/install

norrietaylor commented Jun 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 7, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

bryan-minimal left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

norrietaylor commented Jun 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related issues

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bryan-minimal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

norrietaylor commented Jun 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 7, 2026 •

edited

Loading