Refocus Superb boundaries and align bridge workflows (#20)

* docs: unify superb path contract

* feat: add specification and requirements checklists for refocusing superb boundaries

* feat: enhance specification for Superb boundaries with detailed task validation and lifecycle adjustments

* feat: implement comprehensive contracts and validation for refocused Superb boundaries

* feat: add implementation tasks for refocusing Superb as a bounded Spec Kit extension

* feat: update implementation plan and tasks for refocusing Superb boundaries with new tests and documentation adjustments

* Refactor and enhance the Superb workflow and command contracts

- Introduced a new WORKFLOW.md to define the Superb workflow contract, clarifying the responsibilities and routing of commands.
- Added implementation-gate.md to establish a mandatory pre-implementation gate that reports test-first readiness.
- Created multiple test scripts to validate command boundaries, lifecycle routing, capability contracts, and workflow contracts.
- Updated test-review-regressions.sh to streamline Python interpreter detection and improve readability.
- Removed deprecated commands and references from various scripts and documentation to ensure clarity and maintainability.
- Enhanced the test-superb-path-contract.sh to dynamically determine expected feature directories based on the current branch.
- Ensured that the memorylint extension adheres to independence contracts and does not reference removed lifecycle helpers.

* feat: refine Superb boundaries with updated task classifications, enhanced documentation, and removal of legacy dependencies

* feat: streamline superb path contract tests by removing deprecated checks and simplifying assertions

* fix: replace rg with grep for improved path checks in superb path contract tests

* fix(superpowers-bridge): use scoped npm package @rbbtsn0w/adg for install commands

The unscoped npm package "adg" was unpublished in 2017; npx resolved to
that dead package instead of the actual scoped package, failing CI's
new test-e2e-installation.sh with ENOVERSIONS.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* fix(ci): provide uvx for spec-kit install test

test-spec-kit-012-install.sh hard-requires uvx, which ubuntu-latest
runners lack; install uv via astral-sh/setup-uv so the integration test
runs in CI, and skip gracefully when uvx is absent locally.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(tests): add python3 presence check to test-review-regressions

Restore the canonical find_python3 helper (as used in test-catalog.sh)
so a missing interpreter yields an actionable prerequisite error instead
of a generic "python3: command not found".

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: RbBtSn0w

.github/workflows/ci.yml

@@ -17,14 +17,25 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+
       - name: Run shell regression tests
         shell: bash
         run: |
           bash tests/test-review-regressions.sh
           bash tests/test-release-workflow.sh
           bash tests/test-catalog.sh
-          bash superpowers-bridge/tests/test-status-sync.sh
-          bash superpowers-bridge/tests/test-archive-evidence.sh
+          bash tests/test-superb-path-contract.sh
+          bash superpowers-bridge/tests/test-capability-contract.sh
+          bash superpowers-bridge/tests/test-lifecycle-routing.sh
+          bash superpowers-bridge/tests/test-implementation-gate.sh
+          bash superpowers-bridge/tests/test-command-boundaries.sh
+          bash superpowers-bridge/tests/test-workflow-contract.sh
+          bash superpowers-bridge/tests/test-install-guidance.sh
+          bash superpowers-bridge/tests/test-resolve-skill.sh
+          bash superpowers-bridge/tests/test-e2e-installation.sh
+          bash superpowers-bridge/tests/test-spec-kit-012-install.sh
           bash universal-bridge/tests/test-pre-commit.sh
           bash tests/verify-feasibility.sh
           bash memorylint/tests/test-memorylint-regressions.sh
@@ -33,16 +44,3 @@ jobs:
           bash memorylint/tests/test-workspace-audit.sh
           bash memorylint/tests/test-apply-workflow.sh
           bash memorylint/tests/test-load-agents-proof.sh
-
-  powershell-bridge-tests:
-    name: powershell-bridge-tests
-    runs-on: windows-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Run PowerShell bridge tests
-        shell: pwsh
-        run: |
-          pwsh -File superpowers-bridge/tests/test-status-sync.ps1
-          pwsh -File superpowers-bridge/tests/test-archive-evidence.ps1

AGENTS.md

@@ -17,6 +17,9 @@
 - Command names must follow `speckit.{extension-id}.{command-name}`.
 - Every command markdown file under `commands/` must include the `$ARGUMENTS` context block.
 - If a command depends on scripts, declare them in Markdown frontmatter under `scripts:` instead of relying on undocumented side effects.
+- Use `scripts:` frontmatter with `../../scripts/...` only for Spec Kit core shared helpers that are expected to rewrite to `.specify/scripts/...` at registration time.
+- For extension-owned scripts, templates, configs, or other runtime assets, reference the installed extension path explicitly as `.specify/extensions/<extension-id>/...`; do not rely on repo-relative source paths after installation.
+- Do not use `{SCRIPT}` as a directory anchor to discover sibling helpers. `{SCRIPT}` is only the resolved frontmatter command placeholder, not an extension-root locator.
 - Hook `command:` values must match an entry declared under `provides.commands` exactly.
 - Prefer extension-local config templates such as `*-config.template.yml` and declare them under `provides.config` instead of hardcoding machine-local paths.
 - Extensions in this repo must be additive. Do not directly edit `.specify/scripts/` or `.specify/templates/` from an extension implementation.

README.md

@@ -2,7 +2,9 @@
 
 Evidence-first extensions for [Spec Kit](https://github.com/github/spec-kit) workflows.
 
-The current wedge is trustable AI-agent completion: when an agent says an implementation is complete, the workflow should have fresh tests, requirement coverage, and durable evidence to prove it. Broader AI governance and cross-tool portability are roadmap items, not the first product promise.
+The current wedge is focused lifecycle reinforcement: selected disciplines add
+specification quality, test-first readiness, debugging, review, and branch
+handoff without creating a second Spec Kit workflow.
 
 ## Extensions
 
@@ -61,7 +63,7 @@ specify extension add --dev ./superpowers-bridge
 
 ## Product Direction
 
-- **Now:** evidence-based completion gates, status synchronization, and requirement drift review for Spec Kit users.
+- **Now:** focused specification refinement, test-first readiness, debugging, review, and branch handoff for Spec Kit users.
 - **Next:** MemoryLint semantic audits for long-lived agent instructions.
 - **Later:** Universal Bridge portability once the Spec Kit loop proves useful in real repositories.
 

catalog.json

@@ -24,8 +24,8 @@
         ]
       },
       "provides": {
-        "commands": 10,
-        "hooks": 6
+        "commands": 7,
+        "hooks": 2
       },
       "tags": [
         "methodology",
@@ -34,7 +34,7 @@
         "workflow",
         "superpowers",
         "brainstorming",
-        "verification",
+        "readiness",
         "debugging",
         "branch-management"
       ],

specs/004-refocus-superb-boundaries/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Refocus Superb Boundaries
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-07-02
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation passed on 2026-07-02 with no unresolved clarification markers.
+- MemoryLint is explicitly excluded from implementation scope and retained as an independent extension.

specs/004-refocus-superb-boundaries/contracts/capability-contract.md

@@ -0,0 +1,64 @@
+# Superb Capability Contract
+
+## Public Command Surface
+
+The installed `superb` extension MUST expose exactly these commands:
+
+1. `speckit.superb.check`
+2. `speckit.superb.brainstorm`
+3. `speckit.superb.implementation-gate`
+4. `speckit.superb.critique`
+5. `speckit.superb.debug`
+6. `speckit.superb.respond`
+7. `speckit.superb.finish`
+
+No alias or compatibility command may preserve a removed lifecycle surface.
+
+## Hook Surface
+
+| Stage | Command | Optional | Responsibility |
+|---|---|---:|---|
+| `after_specify` | `speckit.superb.brainstorm` | true | Offer a bounded specification-quality enhancement without taking ownership of planning. |
+| `before_implement` | `speckit.superb.implementation-gate` | false | Check implementation readiness and TDD availability without executing or scheduling tasks. |
+
+No Superb hook may run at `after_tasks`, `after_implement`, `before_converge`, or `after_converge`.
+
+## Skill Surface
+
+The bridge MUST discover or install exactly these logical Superpowers skills:
+
+1. `brainstorming`
+2. `test-driven-development`
+3. `systematic-debugging`
+4. `receiving-code-review`
+5. `finishing-a-development-branch`
+
+Missing skills MUST produce bounded native guidance or an explicit installation action. Missing skills MUST NOT activate an additional orchestration path.
+
+## Forbidden Active Surface
+
+The installed package MUST NOT expose or invoke:
+
+- Commands: `controller`, `review`, `verify`, or `plan-gate`.
+- Hooks: `after_tasks`, `after_implement`, `before_converge`, or `after_converge`.
+- Skills: `verification-before-completion`, `writing-plans`, `executing-plans`, `subagent-driven-development`, `requesting-code-review`, or `dispatching-parallel-agents`.
+- Runtime helpers that synchronize spec status, archive evidence, own task completion, dispatch agents, or persist execution state.
+
+Historical changelog entries may name removed surfaces, but active manifests, commands, scripts, config, tests, and installation artifacts may not depend on them.
+
+## Package Invariants
+
+- `extension.yml` remains valid for `schema_version: "1.0"`.
+- `extension.id` remains `superb`.
+- `extension.version` remains the latest published version until the release workflow publishes a new version.
+- All runtime assets use installed extension paths under `.specify/extensions/superb/`.
+- Superb owns no lifecycle status, task store, execution store, completion store, or convergence report.
+- MemoryLint manifests, commands, hooks, scripts, configuration, and behavior remain unchanged.
+
+## Compatibility Evidence
+
+Acceptance requires both source-tree and installed-package evidence:
+
+- Source validation proves the exact command, hook, skill, and forbidden-surface sets.
+- Installation validation uses a pinned Spec Kit `0.12.4` environment and inspects the registered extension.
+- Compatibility assertions test durable Spec Kit contracts and observable installed behavior, not copied internal skill prose.

specs/004-refocus-superb-boundaries/contracts/command-boundaries.md

@@ -0,0 +1,57 @@
+# Superb Command Boundaries
+
+## `speckit.superb.check`
+
+- Reads: installed extension metadata, Superb config, and availability of the five contracted skills.
+- Writes: nothing unless the user explicitly accepts a skill installation action.
+- Reports: five-skill readiness, two-hook registration, and availability of the four standalone commands.
+- Must not: inspect or install unrelated plugins, mutate feature artifacts, or create lifecycle state.
+
+## `speckit.superb.brainstorm`
+
+- Trigger: optional `after_specify` hook or explicit invocation.
+- Reads: the current feature specification, relevant project context, and the `brainstorming` skill when available.
+- Writes: only user-approved improvements to the current specification.
+- Fallback: safely skip or provide bounded native questions when the skill is unavailable.
+- Must not: create plans or tasks, change branches, select an execution mode, update status, or invoke `writing-plans`.
+
+## `speckit.superb.implementation-gate`
+
+- Trigger: mandatory `before_implement` hook or explicit invocation.
+- Reads: the current specification, plan, tasks, and availability of `test-driven-development`.
+- Writes: no feature artifacts and no runtime state.
+- Reports: implementation readiness, missing prerequisites, TDD guidance availability, and behavior-changing tasks without explicit test-first readiness.
+- Must not: inspect or report parallel markers, ordering, shared-file constraints, or any other task-scheduling metadata.
+- Fallback: provide the minimum native TDD gate when the Superpowers skill is unavailable.
+- Must not: select single-agent or multi-agent modes, form batches, dispatch agents, execute tasks, edit task checkboxes, commit changes, or persist status.
+
+## `speckit.superb.critique`
+
+- Trigger: explicit invocation only.
+- Reads: the supplied diff or review scope and relevant requirements.
+- Writes: no code or feature artifacts.
+- Reports: evidence-backed findings ordered by severity, with artifact-routing guidance when requirements are wrong or incomplete.
+- Must not: fix findings, create tasks, declare completion, or replace Spec Kit analysis and convergence.
+
+## `speckit.superb.debug`
+
+- Trigger: explicit invocation for a current reproducible failure.
+- Reads: the failing task, evidence, focused tests, and `systematic-debugging` when available.
+- Writes: a focused failing test and minimal fix when the user requested implementation.
+- Must not: dispatch parallel agents, update lifecycle status, modify unrelated tasks, or advance the Spec Kit stage automatically.
+
+## `speckit.superb.respond`
+
+- Trigger: explicit invocation with supplied review findings.
+- Reads: the findings, affected requirements, code, and `receiving-code-review` when available.
+- Writes: only accepted, in-scope fixes.
+- Routing rule: findings that change specification, planning, or task meaning return to `speckit-clarify`, `speckit-plan`, or `speckit-tasks` before code mutation.
+- Must not: invent review findings, silently broaden scope, or mark the feature complete.
+
+## `speckit.superb.finish`
+
+- Trigger: explicit invocation after Spec Kit convergence and required checks.
+- Reads: fresh verification evidence, branch state, workspace ownership, and `finishing-a-development-branch` when available.
+- Writes: only the git or pull-request action explicitly selected by the user.
+- Must preserve: unrelated workspaces and uncommitted changes not owned by the current feature.
+- Must not: run a second convergence workflow, write Superb status, archive evidence, or choose a destructive git action implicitly.

specs/004-refocus-superb-boundaries/data-model.md

@@ -0,0 +1,97 @@
+# Data Model: Refocus Superb Boundaries
+
+**Feature**: `004-refocus-superb-boundaries` | **Date**: 2026-07-03
+
+This feature has no application persistence model. Its entities are declarative
+extension contracts represented in YAML, Markdown, configuration, and tests.
+
+## CapabilityContract
+
+| Field | Type | Validation |
+|---|---|---|
+| `commands` | ordered set of `CommandContract` | Exactly seven unique command names |
+| `hooks` | ordered set of `HookBinding` | Exactly two unique lifecycle keys |
+| `skills` | ordered set of `SkillContract` | Exactly five unique skill names |
+| `statuses` | set | Must be empty |
+| `task_stores` | set | Must be empty |
+| `execution_stores` | set | Must be empty |
+| `completion_stores` | set | Must be empty |
+
+Identity is the `superb` extension namespace plus the installed extension
+version. Counts must agree across manifest, configuration, installer,
+diagnostics, documentation, and tests.
+
+## CommandContract
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | command identifier | Must use `speckit.superb.*` |
+| `kind` | `hook` or `standalone` | Hook commands remain manually invocable |
+| `lifecycle_boundary` | hook key or `standalone` | Exactly one accountable boundary |
+| `user_outcome` | string | Lifecycle benefit, not internal terminology |
+| `reads` | set | Minimum necessary artifacts/context |
+| `writes` | set | Explicit allowlist |
+| `forbidden` | set | State, orchestration, or ownership violations |
+| `skill` | optional `SkillContract` | At most one primary upstream discipline |
+| `fallback` | enum | `native_minimum`, `unavailable`, or `not_applicable` |
+
+### Command Identities
+
+1. `speckit.superb.check`
+2. `speckit.superb.brainstorm`
+3. `speckit.superb.implementation-gate`
+4. `speckit.superb.critique`
+5. `speckit.superb.debug`
+6. `speckit.superb.respond`
+7. `speckit.superb.finish`
+
+## HookBinding
+
+| Hook | Command | Policy | Mutation |
+|---|---|---|---|
+| `after_specify` | `speckit.superb.brainstorm` | Optional | User-approved `spec.md` refinement only |
+| `before_implement` | `speckit.superb.implementation-gate` | Mandatory | Read-only |
+
+No other Superb hook is valid. In particular, `after_tasks`, `after_implement`,
+`before_converge`, and `after_converge` must be absent.
+
+## SkillContract
+
+| Name | Consumer | Availability behavior | Stable dependency |
+|---|---|---|---|
+| `brainstorming` | `brainstorm` | Optional command/hook unavailable or skipped safely | Design alternatives, scope, approval |
+| `test-driven-development` | `implementation-gate` | Optional upstream enhancement; bridge-native minimum TDD readiness when absent | RED before production change |
+| `systematic-debugging` | `debug` | Standalone unavailable with install guidance | Evidence-led root-cause investigation |
+| `receiving-code-review` | `respond` | Standalone unavailable with install guidance | Technical verification of feedback |
+| `finishing-a-development-branch` | `finish` | Standalone unavailable with install guidance | Fresh tests and explicit branch choice |
+
+Internal headings, prompt-template filenames, named agents, and exact workflow
+steps are not fields in this contract.
+
+## ArtifactRoute
+
+| Defect class | Owning command | Superb behavior |
+|---|---|---|
+| Requirement ambiguity | `speckit.clarify` | Report and route |
+| Plan/architecture mismatch | `speckit.plan` | Report and route |
+| Missing or malformed tasks | `speckit.tasks` | Report and route |
+| Cross-artifact inconsistency | `speckit.analyze`, then earliest owner | Report and route |
+| Implementation execution | `speckit.implement` | Gate readiness only |
+| Delivered-code gap | `speckit.converge` | Route only |
+| Feedback changes requirement/plan/task meaning | Earliest affected owner | Respond stops direct code mutation |
+
+## MigrationRemoval
+
+Each removed surface has one terminal transition: `active -> removed`.
+
+| Surface | Replacement/route |
+|---|---|
+| `speckit.superb.controller` | `speckit.superb.implementation-gate` |
+| `speckit.superb.review` | `speckit.tasks` and `speckit.analyze` |
+| `speckit.superb.verify` | `speckit.implement` validation and `speckit.converge` |
+| `plan-gate.md` | Native `speckit.plan` |
+| Superb status synchronization | No replacement state machine |
+| Temporary evidence archive | Owning command's fresh in-session evidence |
+
+Removed files, config keys, docs, and tests must not remain in the installed
+payload. Migration guidance may name them only as historical removed surfaces.