{"record":{"id":"b2f0b230373a87f2","repo":"github/spec-kit","slug":"bundle-manifest-bundle-id-requires-spec-kit-m","errorCode":null,"errorMessage":"Bundle '{manifest.bundle.id}' requires Spec Kit {manifest.requires.speckit_version}, but this project uses {speckit_version}. Update Spec Kit or choose a compatible bundle.","messagePattern":"Bundle '(.+?)' requires Spec Kit (.+?), but this project uses (.+?)\\. Update Spec Kit or choose a compatible bundle\\.","errorType":"exception","errorClass":"BundlerError","httpStatus":null,"severity":"error","filePath":"src/specify_cli/bundler/services/resolver.py","lineNumber":72,"sourceCode":"    integration clash). Soft issues are collected in ``plan.warnings``.\n\n    *integration_explicit* signals that ``active_integration`` came from an\n    explicit ``--integration`` override rather than project auto-detection. When\n    a bundle pins an integration but the project's active integration cannot be\n    determined (``active_integration is None``) and the caller did not supply an\n    explicit override, resolution fails instead of silently adopting the\n    bundle's required integration (FR-019 guard).\n    \"\"\"\n    structural = manifest.structural_errors()\n    if structural:\n        raise BundlerError(\n            \"Cannot resolve an invalid manifest:\\n  - \" + \"\\n  - \".join(structural)\n        )\n\n    # FR-016: SpecKit version gate — refuse incompatible installs.\n    if enforce_version and manifest.requires.speckit_version:\n        if not satisfies(speckit_version, manifest.requires.speckit_version):\n            raise BundlerError(\n                f\"Bundle '{manifest.bundle.id}' requires Spec Kit \"\n                f\"{manifest.requires.speckit_version}, but this project uses \"\n                f\"{speckit_version}. Update Spec Kit or choose a compatible bundle.\"\n            )\n\n    # FR-019: integration-compatibility — a bundle that pins a different\n    # integration than the project's active one halts (no silent change).\n    #\n    # A blank integration arrives as ``\"\"``, not ``None`` — which is not a usable\n    # integration id but satisfied NEITHER guard below (the first is a truthiness\n    # test, the second an ``is None`` test), so a pinned bundle was silently\n    # adopted: precisely the outcome this guard exists to prevent. Treat blank as\n    # indeterminate, and strip first like the writer\n    # (``integration_state.clean_integration_key``) so a padded value is not\n    # reported as clashing with itself.\n    if active_integration is not None:\n        active_integration = active_integration.strip() or None\n    effective_integration = active_integration","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/github/spec-kit/blob/bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c/src/specify_cli/bundler/services/resolver.py#L54-L90","documentation":"The FR-016 Spec Kit version gate in resolve_install_plan(): the manifest declares requires.speckit_version, and the project's Spec Kit version does not satisfy that constraint (via satisfies()). This is a hard gate — the bundle refuses to install against an incompatible Spec Kit rather than half-working. Only enforced when the enforce_version argument is true and requires.speckit_version is non-empty.","triggerScenarios":"resolve_install_plan(manifest, speckit_version='1.4.0', ...) with a bundle.yml whose requires.speckit_version is '>=2.0' (or requires '1.x' while running 2.x); reached through 'specify bundle install <id-or-path>' in a project with an older/newer specify CLI.","commonSituations":"A bundle published for a newer Spec Kit release installed by a user on an older pip package; or after a Spec Kit major upgrade, older pinned bundles no longer satisfy their own constraint.","solutions":["Update Spec Kit so the project version satisfies the constraint: pip install -U specify-cli (or the project's package manager equivalent), then retry the install.","Pick a bundle version whose requires.speckit_version matches your installed Spec Kit.","If you own the bundle, relax/correct requires.speckit_version in bundle.yml (e.g. '>=1.2' instead of '>=2.0').","Programmatically: pre-check satisfies(speckit_version, manifest.requires.speckit_version) and skip with a warning instead of raising."],"exampleFix":"# before (bundle.yml)\nrequires:\n  speckit_version: \">=2.0\"\n\n# after (if the bundle actually works on 1.4+)\nrequires:\n  speckit_version: \">=1.4\"","handlingStrategy":"validation","validationCode":"from specify_cli.bundler.services.resolver import resolve_install_plan  # satisfies lives nearby\nfrom specify_cli.bundler.compatability import satisfies  # adjust import to project layout\n\nconstraint = manifest.requires.speckit_version\nif constraint and not satisfies(speckit_version, constraint):\n    print(f\"Skip {manifest.bundle.id}: needs Spec Kit {constraint}, have {speckit_version}\")","typeGuard":"def bundle_matches_speckit(manifest, speckit_version: str) -> bool:\n    c = manifest.requires.speckit_version\n    return not c or satisfies(speckit_version, c)","tryCatchPattern":"try:\n    resolve_install_plan(manifest, speckit_version=ver, ...)\nexcept BundlerError as exc:\n    if \"requires Spec Kit\" in str(exc):\n        # skip bundle or prompt user to upgrade Spec Kit\n        ...","preventionTips":["Pin requires.speckit_version to the range you actually tested, no wider.","Check 'specify --version' before installing third-party bundles.","Upgrade Spec Kit before filing bundle-install issues."],"tags":["bundler","version","compatibility","semver"],"backgroundTag":null,"analyzedSha":"bf88c9f9a82fa370c7a7257aa2b3cf10b457b65c","analyzedAt":"2026-08-14T19:43:37.150Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}