feat(bundles): first-party bugfix and assess bundles with bundled workflows (#4504)

* feat(bundles): add first-party bugfix and assess bundles with bundled workflows

Implements #4495.

Two first-party bundles pairing the bug and assess extensions with
orchestrated, resumable pipelines:

- workflows/bugfix: bug assess -> human review gate -> bug fix -> bug test
- workflows/assess: intake -> research -> define -> shape -> decide -> verdict
  review gate (specify handoff stays manual)

Both workflows are registered in workflows/catalog.json (bundled: true) and
force-included in the wheel's core_pack like speckit. The bundles live in
bundles/{bugfix,assess} and are listed in a new repo-shipped first-party
catalog bundles/catalog.json (verified: true).

The reserved builtin://default catalog source now resolves from that catalog —
online from the repository, offline from the packaged wheel snapshot — so
`specify bundle add bugfix|assess` resolves by id. Also adds `bundle add` as an
alias for `bundle install`.

Tests: workflow validation and structure guards, wheel force-include contract
(mirrors test_wheel_bundled_presets.py), first-party catalog/manifest/pin
consistency, and workflows/catalog.json <-> workflow.yml id/version/url
consistency.

Assisted-by: opencode (model: glm-5.3, autonomous)

* fix(bundles): install bundled workflows offline

Install bundled workflow components from their packaged workflow.yml instead
of falling through to the network-backed workflow catalog. Validate the bundled
workflow ID and the bundle's pinned version before delegating to the local
workflow install path.

Add coverage for offline first-party bundle installs, bundle add alias
execution, version pin rejection, and command/input workflow contracts.

Assisted-by: opencode (model: glm-5.3, autonomous)

* fix(bundles): address review findings for first-party bundles

- Correct README wording for bundle remove behavior (FR-022).
- Parenthesize full assertion message in first-party catalog consistency test.
- Add contract coverage for `bundle add <id>` from an empty directory,
  mocking first-party catalog/manifest HTTP responses and verifying
  fresh-project init plus bundled extension + workflow installation.

Assisted-by: opencode (model: kimi-k2.7-code, supervised)

* docs(bundles): show required workflow inputs in bundle README run commands

The run examples showed bare `specify workflow run bugfix|assess`, which
fails immediately because both workflows declare required inputs
(`report`/`idea` and `slug`). Show the repeatable --input flags with the
same example values as the corresponding extension READMEs, and note
that inputs omitted from the command line are prompted interactively.

Assisted-by: opencode (model: glm-5.2, autonomous)

* test(events): pin the PowerShell launcher in the ps-variant argv test

test_ps_variant_prefixed_with_powershell_launcher asserted that a real
pwsh/powershell launcher resolves on PATH, so it failed on machines with
neither installed (a pre-existing, environment-specific failure since
#4340 removed the fake "pwsh" fallback — not related to the bundles
work, but it blocked a clean local full-suite run).

The test's contract is argv construction (launcher, -File, script), not
launcher discovery, so monkeypatch shutil.which to a synthetic pwsh path
— the same pattern the no-launcher sibling test already uses — keeping
the test running (not skipped) on every platform.

Assisted-by: opencode (model: glm-5.2, autonomous)

* docs(bundles): clarify required workflow inputs

Assisted-by: GitHub Copilot (model: gpt-5.6-luna, autonomous)

* Remove unused import of Path

Remove unused import of Path from test_bundled_bugfix_assess_workflows.py

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* fix(bundle): forward refresh flag in add alias

Assisted-by: GitHub Copilot (model: gpt-5.6-luna, autonomous)

* fix(bundler): fall back to packaged catalog snapshot

Assisted-by: GitHub Copilot (model: gpt-5.6-luna, autonomous)

* fix(bundler): only fall back to snapshot on transient catalog failures

The builtin catalog fallback previously caught every BundlerError from the
online fetch, silently masking malformed JSON, oversized responses, and
redirect/URL validation failures with the packaged snapshot. Classify only
transient failures (connection errors, timeouts, HTTP 5xx) as unavailable,
preserve validation failures, warn when a snapshot is used, and go quiet for
deliberate --offline use. Cover both builtin catalogs in unit and integration
tests, and assert the first-party catalog wheel mapping.

Assisted-by: opencode (model: deepseek-v4.1-flash, autonomous)

* fix bundler catalog fallback handling

Preserve redirect-policy failures and treat HTTP 408/429 as transient
when falling back to the packaged catalog snapshot, per review on #4504.

Co-authored-by: markuswondrak <245696895+markuswondrak@users.noreply.github.com>
Assisted-by: opencode (model: deepseek-v4.1-flash, autonomous)

* test(bundler): exercise real redirect handler and refresh fallback docstring

Address review nits on #4504: update the _CatalogUnavailable docstring to
mention 408/429 as transient, and drive the redirect-policy test through the
real _StripAuthOnRedirect handler instead of injecting the exception, with a
snapshot present to prove the fallback is not taken.

Assisted-by: opencode (model: deepseek-v4.1-flash, autonomous)

* fix(bundler): keep TLS certificate failures out of snapshot fallback

Address review on #4504: urllib wraps ssl.SSLCertVerificationError in
URLError(reason=...) and some paths raise it directly as an OSError. Detect
both before the transient transport branches and raise a hard BundlerError so
a certificate-verification failure is never masked by the packaged snapshot.
Add regression cases for the wrapped and direct forms.

Assisted-by: opencode (model: deepseek-v4.1-flash, autonomous)

* fix(bundler): treat truncated chunked responses as catalog-unavailable

Address review on #4504: http.client.IncompleteRead is neither URLError nor
OSError, so an interrupted chunked response fell through to the generic branch
and became a hard BundlerError, defeating the packaged-snapshot fallback.
Classify it as _CatalogUnavailable and add a regression test that raises it
from response.read().

Assisted-by: opencode (model: deepseek-v4.1-flash, autonomous)

---------

Co-authored-by: Markus <markus@example.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: markuswondrak <245696895+markuswondrak@users.noreply.github.com>

Author: 4 people

bundles/assess/README.md

@@ -0,0 +1,40 @@
+# Idea Assessment Bundle
+
+A first-party GitHub Spec Kit bundle that installs an idea-triage pipeline before committing to Spec-Driven Development.
+
+## What it provides
+
+- **Assess extension** (`extensions/assess`) — the `speckit.assess.intake`, `speckit.assess.research`, `speckit.assess.define`, `speckit.assess.shape`, and `speckit.assess.decide` commands.
+- **Assess workflow** (`workflows/assess`) — a guided, resumable pipeline:
+  1. `intake` the raw idea.
+  2. `research` the evidence.
+  3. `define` the problem.
+  4. `shape` the concept.
+  5. `decide` the verdict.
+  6. `review-verdict` gate — approve to complete the assessment; reject to abort. A `go` verdict is then handed off manually to `/speckit.specify`.
+
+## Install
+
+```bash
+specify bundle install assess
+# or
+specify bundle add assess
+```
+
+## Run the workflow
+
+```bash
+specify workflow run assess \
+  --input idea="Let users work offline and sync when they reconnect" \
+  --input slug="offline-mode"
+```
+
+Required inputs must be supplied with `--input`: `idea` and `slug`. The slug is used as the working directory under `.specify/assessments/<slug>/` for all artifacts.
+
+## Remove
+
+```bash
+specify bundle remove assess
+```
+
+Removing the bundle uninstalls the workflow and the extension it contributed, unless they are still depended on by another installed bundle (FR-022). Components you installed independently are not attributed to this bundle and survive removal.

bundles/assess/bundle.yml

@@ -0,0 +1,25 @@
+schema_version: "1.0"
+
+bundle:
+  id: "assess"
+  name: "Idea Assessment Pipeline"
+  version: "1.0.0"
+  role: "developer"
+  description: "Idea triage before Spec-Driven Development: intake, research, define, shape, decide with a verdict review gate; surviving ideas hand off manually to the specify command."
+  author: "GitHub"
+  license: "MIT"
+
+requires:
+  speckit_version: ">=0.9.0"
+  tools: []
+  mcp: []
+
+provides:
+  extensions:
+    - id: "assess"
+      version: "1.0.0"
+  workflows:
+    - id: "assess"
+      version: "1.0.0"
+
+tags: ["assessment", "discovery", "triage", "product"]

bundles/bugfix/README.md

@@ -0,0 +1,38 @@
+# Bug Fix Bundle
+
+A first-party GitHub Spec Kit bundle that installs an orchestrated bug-fixing pipeline.
+
+## What it provides
+
+- **Bug extension** (`extensions/bug`) — the `speckit.bug.assess`, `speckit.bug.fix`, and `speckit.bug.test` commands.
+- **Bugfix workflow** (`workflows/bugfix`) — a guided, resumable pipeline:
+  1. `assess` the bug report.
+  2. `review-assessment` gate — approve to proceed, reject to abort.
+  3. `fix` the bug.
+  4. `test` the fix.
+
+## Install
+
+```bash
+specify bundle install bugfix
+# or
+specify bundle add bugfix
+```
+
+## Run the workflow
+
+```bash
+specify workflow run bugfix \
+  --input report="https://github.com/example/repo/issues/1234" \
+  --input slug="callback-token"
+```
+
+Required inputs must be supplied with `--input`: `report` and `slug`. The slug is used as the working directory under `.specify/bugs/<slug>/` for all artifacts.
+
+## Remove
+
+```bash
+specify bundle remove bugfix
+```
+
+Removing the bundle uninstalls the workflow and the extension it contributed, unless they are still depended on by another installed bundle (FR-022). Components you installed independently are not attributed to this bundle and survive removal.

bundles/bugfix/bundle.yml

@@ -0,0 +1,25 @@
+schema_version: "1.0"
+
+bundle:
+  id: "bugfix"
+  name: "Guided Bug Fix"
+  version: "1.0.0"
+  role: "developer"
+  description: "Orchestrated bug triage: assess a bug report, review the assessment behind a human gate, apply the fix, and verify it with tests."
+  author: "GitHub"
+  license: "MIT"
+
+requires:
+  speckit_version: ">=0.9.0"
+  tools: []
+  mcp: []
+
+provides:
+  extensions:
+    - id: "bug"
+      version: "1.0.0"
+  workflows:
+    - id: "bugfix"
+      version: "1.0.0"
+
+tags: ["bug", "triage", "workflow", "qa"]

bundles/catalog.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "1.0",
+  "updated_at": "2026-09-10T00:00:00Z",
+  "catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/catalog.json",
+  "bundles": {
+    "bugfix": {
+      "id": "bugfix",
+      "name": "Guided Bug Fix",
+      "version": "1.0.0",
+      "role": "developer",
+      "description": "Orchestrated bug triage: assess a bug report, review behind a human gate, apply the fix, and verify with tests.",
+      "author": "GitHub",
+      "license": "MIT",
+      "download_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/bugfix/bundle.yml",
+      "repository": "https://github.com/github/spec-kit",
+      "requires": {
+        "speckit_version": ">=0.9.0"
+      },
+      "provides": {
+        "extensions": 1,
+        "presets": 0,
+        "steps": 0,
+        "workflows": 1
+      },
+      "tags": ["bug", "triage", "workflow", "qa"],
+      "verified": true
+    },
+    "assess": {
+      "id": "assess",
+      "name": "Idea Assessment Pipeline",
+      "version": "1.0.0",
+      "role": "developer",
+      "description": "Idea triage before Spec-Driven Development: intake, research, define, shape, decide with a verdict review gate; surviving ideas hand off manually to specify.",
+      "author": "GitHub",
+      "license": "MIT",
+      "download_url": "https://raw.githubusercontent.com/github/spec-kit/main/bundles/assess/bundle.yml",
+      "repository": "https://github.com/github/spec-kit",
+      "requires": {
+        "speckit_version": ">=0.9.0"
+      },
+      "provides": {
+        "extensions": 1,
+        "presets": 0,
+        "steps": 0,
+        "workflows": 1
+      },
+      "tags": ["assessment", "discovery", "triage", "product"],
+      "verified": true
+    }
+  }
+}

docs/reference/bundles.md

@@ -11,6 +11,24 @@ These demonstrate packaging a role-based setup, not filled generated feature
 specs; for end-to-end usage examples, see
 [community walkthroughs](../community/walkthroughs.md).
 
+## First-party Bundles
+
+Spec Kit ships a first-party bundle catalog in `bundles/catalog.json`. These bundles are curated, marked `verified: true`, and resolve through the built-in `builtin://default` catalog source.
+
+| Bundle    | Role        | Components                                            | Use case                                |
+| --------- | ----------- | ----------------------------------------------------- | --------------------------------------- |
+| `bugfix`  | `developer` | `bug` extension + `bugfix` workflow                   | Guided assess → gate → fix → test       |
+| `assess`  | `developer` | `assess` extension + `assess` workflow                | Idea triage before Spec-Driven Development |
+
+Install a first-party bundle the same way you install any bundle (`add` is an alias for `install`):
+
+```bash
+specify bundle install bugfix
+specify bundle add assess
+```
+
+The first-party catalog is fetched from the repository online and falls back to the packaged wheel snapshot offline so discovery works without network access. A local bundle manifest can install bundled extensions and workflows with `--offline`. Catalog-discovered bundle manifests still resolve from their `download_url`, so `specify bundle add <id>` requires network today; fully offline catalog installation is tracked as follow-up work.
+
 ## Search Available Bundles
 
 ```bash
@@ -146,7 +164,10 @@ If your bundle references components from non-default catalogs, document those c
 
 ## Manage Catalog Sources
 
-Bundles are discovered through a priority-ordered stack of catalog sources (project, user, and built-in scopes).
+Bundles are discovered through a priority-ordered stack of catalog sources (project, user, and built-in scopes). The built-in sources are:
+
+- `builtin://default` — first-party bundles shipped in `bundles/catalog.json` (`bugfix`, `assess`, ...), install-allowed.
+- `builtin://community` — community submissions in `bundles/catalog.community.json`, discovery-only.
 
 Each source has an install policy. `install-allowed` sources can be installed
 from; `discovery-only` sources appear in `search` and `info` but refuse

pyproject.toml

@@ -45,12 +45,15 @@ packages = ["src/specify_cli"]
 "extensions/agent-context" = "specify_cli/core_pack/extensions/agent-context"
 "extensions/assess" = "specify_cli/core_pack/extensions/assess"
 "extensions/bug" = "specify_cli/core_pack/extensions/bug"
-# Bundled workflows (auto-installed during `specify init`)
+# Bundled workflows (`specify init` installs only `speckit`; `bugfix`/`assess` are opt-in via first-party bundles)
 "workflows/speckit" = "specify_cli/core_pack/workflows/speckit"
+"workflows/bugfix" = "specify_cli/core_pack/workflows/bugfix"
+"workflows/assess" = "specify_cli/core_pack/workflows/assess"
 # Bundled presets (installable via `specify preset add <name>` or `specify init --preset <name>`)
 "presets/lean" = "specify_cli/core_pack/presets/lean"
 "presets/constitution-sync" = "specify_cli/core_pack/presets/constitution-sync"
-# Community bundle catalog snapshot (used for offline discovery)
+# Bundle catalog snapshots (used for offline discovery)
+"bundles/catalog.json" = "specify_cli/core_pack/bundles/catalog.json"
 "bundles/catalog.community.json" = "specify_cli/core_pack/bundles/catalog.community.json"
 
 [project.optional-dependencies]

src/specify_cli/authentication/http.py

@@ -65,9 +65,13 @@ def _hostname_in_hosts(hostname: str, hosts: tuple[str, ...]) -> bool:
 RedirectValidator = Callable[[str, str], None]
 
 
+class RedirectPolicyError(urllib.error.URLError):
+    """A redirect rejected because it violates the client's security policy."""
+
+
 def _validate_strict_redirect(old_url: str, new_url: str) -> None:
     if not is_safe_download_redirect(old_url, new_url):
-        raise urllib.error.URLError(
+        raise RedirectPolicyError(
             f"unsafe redirect to {new_url}: target must use HTTPS with a hostname, "
             "must not enter a local target from a remote host, and may use HTTP only "
             "within loopback (for example localhost, 127.0.0.1, ::1)"
@@ -100,7 +104,7 @@ def redirect_request(self, req, fp, code, msg, headers, newurl):
         except ValueError as exc:
             # Malformed redirect target (e.g. unterminated IPv6 bracket).
             # Surface as URLError so callers' download error handling applies.
-            raise urllib.error.URLError(f"malformed redirect URL: {exc}") from exc
+            raise RedirectPolicyError(f"malformed redirect URL: {exc}") from exc
 
         if self._redirect_validator is not None:
             self._redirect_validator(req.full_url, newurl)