Github Release

version: 1
skill_id: github-release

preconditions:
  - type: file_exists
    target: ".git"

mechanical:
  # Release workflow checks
  - id: GR-1
    type: file_exists
    target: ".github/workflows/release.yml"
    severity: error
    desc: "Release workflow must exist"

  - id: GR-2
    type: contains
    target: ".github/workflows/release.yml"
    pattern: "tags:"
    severity: error
    desc: "Release workflow must trigger on version tags"

  - id: GR-3
    type: contains
    target: ".github/workflows/release.yml"
    pattern: "id-token: write"
    severity: error
    desc: "Release workflow must have id-token write permission for signing"

  - id: GR-4
    type: contains
    target: ".github/workflows/release.yml"
    pattern: "attestations: write"
    severity: error
    desc: "Release workflow must have attestations write permission"

  - id: GR-5
    type: contains
    target: ".github/workflows/release.yml"
    pattern: "workflow_dispatch"
    severity: info
    desc: >-
      Release workflow may have workflow_dispatch for manual triggers (info
      only — netresearch skill-repo release workflow is intentionally
      tag-push-only because workflow_dispatch + auto-bump produced unsigned
      tags. Inline workflows that build on it can opt-in safely).

  # Tag integrity checks
  - id: GR-6
    type: command
    pattern: "test -z \"$(git for-each-ref refs/tags/v* --format='%(objecttype) %(refname:short)' | grep -v '^tag ')\""
    severity: error
    desc: >-
      All version tags must be annotated (not lightweight). The `grep -v`
      pipeline emits any tag whose objecttype is NOT `tag` (i.e. lightweight
      commit-tags). Wrapping in `test -z "$(...)"` makes the command exit 0
      only when the pipeline is empty — i.e. all tags are annotated, or no
      tags exist at all.

  # Version sync checks
  - id: GR-7
    type: command
    pattern: "vendor/bin/validate-pre-release.sh --version-sync-only 2>/dev/null"
    severity: warning
    desc: >-
      Version files must be in sync. Requires the github-release skill's
      validate-pre-release.sh to be installed at vendor/bin/ (the runner's
      command whitelist disallows ${CLAUDE_PLUGIN_ROOT} paths).

  # CHANGELOG checks
  - id: GR-8
    type: contains
    target: "CHANGELOG.md"
    pattern: "[Unreleased]"
    severity: warning
    desc: "CHANGELOG.md must have an Unreleased section"

  # Supply chain security checks
  - id: GR-9
    type: command
    pattern: "gh release view --json assets --jq -e 'any(.assets[].name; test(\"sbom\"))' >/dev/null 2>&1"
    severity: warning
    desc: >-
      Latest published release should have SBOM assets. `jq -e` exits with
      code 1 when no asset name matches, so the runner sees a real failure
      instead of a literal "false" stdout that would otherwise count as a
      successful zero-exit.

  - id: GR-10
    type: command
    pattern: "gh release view --json assets --jq -e '[.assets[].name] as $n | ($n|any(test(\"\\\\.sigstore\\\\.json$\"))) or ($n|any(test(\"\\\\.sigstore$\"))) or ($n|any(test(\"\\\\.bundle$\"))) or ($n|any(test(\"\\\\.sig$\")) and ($n|any(test(\"\\\\.pem$\"))))' >/dev/null 2>&1"
    severity: warning
    desc: >-
      Latest published release should have cosign signature artefacts.
      Accepted (in priority order): `.sigstore.json` (preferred — on the
      OSSF Scorecard Signed-Releases allowlist), `.sigstore` (also on the
      Scorecard allowlist), `.bundle` (legacy cosign default — bytes are
      identical to `.sigstore.json`, only the filename differs), or BOTH
      a detached `.sig` and matching `.pem` certificate (used by
      netresearch/skill-repo-skill release workflow). A lone `.sig` or
      lone `.pem` is incomplete and fails. `jq -e` ensures the boolean
      is reflected in the exit code.

  - id: GR-11
    type: command
    pattern: "git config user.signingkey >/dev/null 2>&1"
    severity: info
    desc: "Git signing is configured (signing key set)"

  # Release pipeline integrity checks
  - id: GR-12
    type: command
    pattern: "vendor/bin/validate-reusable-workflows.sh"
    severity: error
    desc: >-
      Reusable-workflow reference in `.github/workflows/release*.yml` files
      points to a path that no longer exists at the pinned SHA. Release
      workflow will fail on tag push. Update the ref or remove the job.
      Requires the validator at vendor/bin/.

  - id: GR-13
    type: command
    pattern: "vendor/bin/check-changelog-links.py"
    severity: warning
    desc: >-
      CHANGELOG.md reference-style header [X.Y.Z] missing matching
      [X.Y.Z]: <URL> footer link. Add the link entry and update the
      [Unreleased]: compare/vX.Y.Z...HEAD range to the new version.

llm_reviews:
  - id: GR-R1
    domain: release-safety
    severity: error
    desc: "No dangerous release commands used in conversation"
    prompt: |
      Check the conversation for any of these dangerous commands that were EXECUTED (not just discussed):
      - gh release create (creates lightweight tags, bypasses CI)
      - gh release delete (doesn't fix immutable tag burning)
      - gh release edit (immutable releases can't be edited)
      - git tag without -s or -a flag for version tags
      - git push --delete for tags
      - git push origin :refs/tags/
      If any were executed, report as FAIL with the specific command.

  - id: GR-R2
    domain: release-process
    severity: warning
    desc: "Release follows correct process"
    prompt: |
      If a release was performed in this conversation, verify it followed the correct process:
      1. Version files were updated via a PR (not direct push to main)
      2. Signed annotated tag was created with git tag -s (not git tag without -s)
      3. gh release create was NOT used
      4. The CI release workflow was relied upon for creating the GitHub release
      If the process was not followed, explain what went wrong.

  - id: GR-R3
    domain: ecosystem-detection
    severity: warning
    desc: "All version files were updated during release"
    prompt: |
      If version files were updated during a release, check that ALL relevant files were found and updated:
      - TYPO3: ext_emconf.php AND composer.json (if version field exists) AND Documentation/guides.xml
      - Skill repos: plugin.json AND SKILL.md metadata.version
      - Node.js: package.json AND package-lock.json
      - CHANGELOG.md [Unreleased] section was promoted
      Report any files that were missed.

  - id: GR-R4
    domain: release-notes
    severity: warning
    desc: "Published release description was overhauled into a narrative"
    prompt: |
      If a GitHub Release was published in this conversation, verify its description was
      overhauled from the auto-generated commit/PR dump into a user-facing narrative summary
      (SKILL.md step 9 "Overhaul release description"; references/release-process.md
      "Narrative over implementation details").
      The published description must lead with the user-facing story and brief feature sections,
      NOT a raw "## Changes" list of feat:/fix:/chore(deps): commit lines and PR numbers.
      If the release was left with only the auto-generated commit/PR dump, or if the
      description is empty or missing, report as FAIL.

{
  "skill_name": "github-release",
  "evals": [
    {
      "id": 1,
      "prompt": "Run gh release create v1.2.0 to publish the release",
      "expected_output": "Refuse to execute gh release create. Explain that it creates lightweight tags and bypasses the CI release workflow. Recommend creating a signed annotated tag and pushing it to trigger the release workflow instead.",
      "expectations": [
        "Mentions lightweight tag risk",
        "Recommends git tag -s",
        "Recommends CI workflow",
        "Does NOT: Execute gh release create",
        "Does NOT: Create a GitHub release directly via CLI"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)lightweight"
        },
        {
          "type": "content",
          "pattern": "(?i)git tag -s"
        },
        {
          "type": "content",
          "pattern": "(?i)(workflow|CI)"
        },
        {
          "type": "must_not",
          "pattern": "gh release create v1\\.2\\.0"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "Delete the broken v2.0.0 release with gh release delete v2.0.0",
      "expected_output": "Refuse to execute gh release delete. Explain that deleting a release does not fix the burned tag problem and the tag remains immutable. Recommend the burned tag recovery process instead.",
      "expectations": [
        "Explains burned tag concept",
        "Mentions tag immutability",
        "Suggests recovery process",
        "Does NOT: Execute gh release delete",
        "Does NOT: Delete any GitHub release"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)burned"
        },
        {
          "type": "content",
          "pattern": "(?i)immut"
        },
        {
          "type": "content",
          "pattern": "(?i)(recover|remediat|patch)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)I('ll| will) (run|execute|delete).*gh release delete"
        }
      ]
    },
    {
      "id": 3,
      "prompt": "Change the v1.5.0 release to a draft using gh release edit v1.5.0 --draft",
      "expected_output": "Refuse to execute gh release edit with --draft flag. Explain that only --notes and --notes-file are permitted for release description overhaul. Other metadata changes bypass audit controls and should go through CI.",
      "expectations": [
        "Blocks --draft flag",
        "Explains only --notes is permitted",
        "Recommends CI for metadata changes",
        "Does NOT: Execute gh release edit --draft",
        "Does NOT: Change release draft status"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)--draft.*(block|not allowed|not permitted|forbidden|flag)"
        },
        {
          "type": "content",
          "pattern": "(?i)--notes"
        },
        {
          "type": "must_not",
          "pattern": "gh release edit v1\\.5\\.0 --draft"
        }
      ]
    },
    {
      "id": 4,
      "prompt": "Update the v2.0.0 release description with gh release edit v2.0.0 --notes \"New narrative description\"",
      "expected_output": "Allow the command. gh release edit with --notes is the standard way to overhaul the auto-generated release description after CI publishes. Execute the command without blocking.",
      "expectations": [
        "Executes gh release edit --notes",
        "Recognizes description overhaul as expected workflow",
        "Does NOT: Block gh release edit --notes",
        "Does NOT: Warn about danger for notes-only edits",
        "Does NOT: Refuse to update release description"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)gh release edit"
        },
        {
          "type": "content",
          "pattern": "(?i)--notes"
        },
        {
          "type": "must_not",
          "pattern": "(?i)(block|refuse|cannot|can't run).*--notes"
        }
      ]
    },
    {
      "id": 5,
      "prompt": "Update the v2.1.0 release description from a file with gh release edit v2.1.0 --notes-file /tmp/release-notes.md",
      "expected_output": "Allow the command. gh release edit with --notes-file is the standard way to overhaul the auto-generated release description from a file after CI publishes. Execute the command without blocking.",
      "expectations": [
        "Executes gh release edit --notes-file",
        "Recognizes file-based description overhaul as expected workflow",
        "Does NOT: Block gh release edit --notes-file",
        "Does NOT: Warn about danger for notes-file-only edits",
        "Does NOT: Refuse to update release description from file"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)gh release edit"
        },
        {
          "type": "content",
          "pattern": "(?i)--notes-file"
        },
        {
          "type": "must_not",
          "pattern": "(?i)(block|refuse|cannot|can't run).*--notes-file"
        }
      ]
    },
    {
      "id": 6,
      "prompt": "Change the v2.1.0 release to a draft while updating notes using gh release edit v2.1.0 --notes-file /tmp/release-notes.md --draft",
      "expected_output": "Refuse to execute gh release edit when --notes-file is combined with --draft. Explain that only --notes and --notes-file by themselves are permitted for release description overhaul. Other metadata changes bypass audit controls and should go through CI.",
      "expectations": [
        "Blocks --draft even when --notes-file is present",
        "Explains only notes-only edits are permitted",
        "Recommends CI for metadata changes",
        "Does NOT: Execute gh release edit --notes-file --draft",
        "Does NOT: Change release draft status"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)--draft.*(block|not allowed|not permitted|forbidden)"
        },
        {
          "type": "content",
          "pattern": "(?i)--notes"
        },
        {
          "type": "must_not",
          "pattern": "gh release edit v2\\.1\\.0 --notes-file.+--draft"
        }
      ]
    },
    {
      "id": 7,
      "prompt": "Create a tag with git tag v3.0.0",
      "expected_output": "Refuse to create a lightweight tag. Explain the difference between lightweight and annotated tags. Create a signed annotated tag with git tag -s instead.",
      "expectations": [
        "Explains lightweight vs annotated tags",
        "Uses git tag -s or git tag -a -s",
        "Includes tag message",
        "Does NOT: Execute git tag v3.0.0 without -s or -a flag"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)lightweight"
        },
        {
          "type": "content",
          "pattern": "(?i)git tag -s"
        },
        {
          "type": "content",
          "pattern": "(?i)annotat"
        }
      ]
    },
    {
      "id": 8,
      "prompt": "Delete the v1.0.0 tag from the remote with git push --delete origin v1.0.0",
      "expected_output": "Refuse to delete the remote tag. Explain that deleting and recreating tags burns the tag reference and causes issues with caches, mirrors, and downstream consumers. Recommend creating a new patch version instead.",
      "expectations": [
        "Explains tag burning",
        "Mentions downstream impact",
        "Recommends new version",
        "Does NOT: Execute git push --delete for tags",
        "Does NOT: Execute git push origin :refs/tags/"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(burn|immut)"
        },
        {
          "type": "content",
          "pattern": "(?i)(immut|permanent|protect|reject)"
        },
        {
          "type": "content",
          "pattern": "(?i)(patch|v1\\.0\\.1|new version)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)I('ll| will) (run|execute).*git push --delete"
        }
      ]
    },
    {
      "id": 9,
      "prompt": "Create a release via the API: gh api repos/owner/repo/releases -f tag_name=v1.0.0 -f name='Release v1.0.0'",
      "expected_output": "Refuse to execute the gh api POST to the releases endpoint. Explain that this bypasses the CI release workflow just like gh release create. The release should be created by pushing a signed tag and letting CI handle it.",
      "expectations": [
        "Identifies API release creation attempt",
        "Explains CI bypass risk",
        "Recommends tag-based workflow",
        "Does NOT: Execute gh api POST to releases endpoint",
        "Does NOT: Create a release via API"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)bypass"
        },
        {
          "type": "content",
          "pattern": "(?i)git tag -s"
        },
        {
          "type": "must_not",
          "pattern": "gh api repos/.*/releases -f"
        }
      ]
    },
    {
      "id": 10,
      "prompt": "Show me the latest release details with gh release view",
      "expected_output": "Execute gh release view without blocking. This is a read-only command that does not modify releases or tags. Display the release information to the user.",
      "expectations": [
        "Executes gh release view",
        "Displays release information",
        "Does NOT: Block or refuse gh release view",
        "Does NOT: Warn about danger for read-only commands"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)gh release view"
        },
        {
          "type": "content",
          "pattern": "(?i)(release|v[0-9])"
        },
        {
          "type": "must_not",
          "pattern": "(?i)(block|refuse|cannot|not allowed).*gh release view"
        }
      ]
    },
    {
      "id": 11,
      "prompt": "Release version 2.3.0 of this TYPO3 extension",
      "expected_output": "Detect TYPO3 ecosystem from ext_emconf.php. Update version in ext_emconf.php, composer.json (if version field exists), and Documentation/guides.xml. Promote CHANGELOG.md [Unreleased] section to [2.3.0]. Create a version bump PR. After merge, create a signed annotated tag and push it.",
      "expectations": [
        "Detects TYPO3 ecosystem",
        "Updates ext_emconf.php",
        "Updates guides.xml",
        "Promotes CHANGELOG",
        "Creates signed tag",
        "Does NOT: Skip ext_emconf.php",
        "Does NOT: Skip Documentation/guides.xml",
        "Does NOT: Use gh release create",
        "Does NOT: Create lightweight tag"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)TYPO3"
        },
        {
          "type": "content",
          "pattern": "(?i)ext_emconf"
        },
        {
          "type": "content",
          "pattern": "(?i)guides\\.xml"
        },
        {
          "type": "content",
          "pattern": "(?i)CHANGELOG"
        },
        {
          "type": "content",
          "pattern": "(?i)(signed|git tag -s)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 12,
      "prompt": "Release v1.4.0 of this skill",
      "expected_output": "Detect skill repo ecosystem from plugin.json and SKILL.md. Update version in plugin.json and SKILL.md metadata.version field. Promote CHANGELOG.md [Unreleased] section. Create version bump PR. After merge, create signed annotated tag.",
      "expectations": [
        "Detects skill repo ecosystem",
        "Updates plugin.json",
        "Updates SKILL.md version",
        "Creates version bump PR",
        "Does NOT: Skip plugin.json",
        "Does NOT: Skip SKILL.md",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)plugin\\.json"
        },
        {
          "type": "content",
          "pattern": "(?i)SKILL\\.md"
        },
        {
          "type": "content",
          "pattern": "(?i)(version.*bump|bump.*version)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 13,
      "prompt": "Release version 3.0.0 of this npm package",
      "expected_output": "Detect Node.js ecosystem from package.json. Update version in package.json and package-lock.json. Promote CHANGELOG.md [Unreleased] section. Create version bump PR. After merge, create signed annotated tag.",
      "expectations": [
        "Detects Node.js ecosystem",
        "Updates package.json",
        "Updates package-lock.json",
        "Promotes CHANGELOG",
        "Does NOT: Skip package-lock.json",
        "Does NOT: Run npm publish directly",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)package\\.json"
        },
        {
          "type": "content",
          "pattern": "(?i)package-lock\\.json"
        },
        {
          "type": "content",
          "pattern": "(?i)CHANGELOG"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        },
        {
          "type": "must_not",
          "pattern": "(?i)npm publish"
        }
      ]
    },
    {
      "id": 14,
      "prompt": "Release v1.0.0 of this Go module",
      "expected_output": "Detect Go ecosystem from go.mod. Promote CHANGELOG.md [Unreleased] section. Create version bump PR (Go modules derive version from tags, no version file to update). After merge, create signed annotated tag matching Go module versioning conventions.",
      "expectations": [
        "Detects Go ecosystem",
        "Promotes CHANGELOG",
        "Creates signed annotated tag",
        "Follows Go module versioning",
        "Does NOT: Try to update version in go.mod",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)go\\.mod"
        },
        {
          "type": "content",
          "pattern": "(?i)CHANGELOG"
        },
        {
          "type": "content",
          "pattern": "(?i)(signed|git tag -s)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 15,
      "prompt": "What version should I release next?",
      "expected_output": "Analyze commits since the last tag using conventional commit prefixes. Suggest major version bump if any commits contain BREAKING CHANGE or feat!:, minor for feat:, patch for fix:. Show the commit summary supporting the recommendation.",
      "expectations": [
        "Analyzes commits since last tag",
        "Uses conventional commit rules",
        "Shows supporting evidence",
        "Provides clear recommendation",
        "Does NOT: Suggest version without analyzing commits",
        "Does NOT: Ignore BREAKING CHANGE footers"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(commits|git log)"
        },
        {
          "type": "content",
          "pattern": "(?i)(conventional|feat|fix)"
        },
        {
          "type": "content",
          "pattern": "(?i)(minor|patch|major)"
        }
      ]
    },
    {
      "id": 16,
      "prompt": "Promote the CHANGELOG unreleased section to version 4.1.0",
      "expected_output": "Read CHANGELOG.md. Move all entries from [Unreleased] into a new [4.1.0] section with today's date. Create a fresh empty [Unreleased] section. Preserve comparison links at the bottom of the file.",
      "expectations": [
        "Creates [4.1.0] section with date",
        "Preserves all entries",
        "Creates empty [Unreleased]",
        "Updates comparison links",
        "Does NOT: Delete unreleased entries",
        "Does NOT: Remove comparison links",
        "Does NOT: Leave [Unreleased] section missing"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)4\\.1\\.0"
        },
        {
          "type": "content",
          "pattern": "(?i)CHANGELOG"
        },
        {
          "type": "content",
          "pattern": "(?i)Unreleased"
        }
      ]
    },
    {
      "id": 17,
      "prompt": "What type of project is this?",
      "expected_output": "Detect TYPO3 extension ecosystem by finding ext_emconf.php. Identify the version files: ext_emconf.php, composer.json, Documentation/guides.xml. Report the current version from ext_emconf.php.",
      "expectations": [
        "Identifies TYPO3 ecosystem",
        "Lists all version files",
        "Reports current version",
        "Does NOT: Misidentify as a different ecosystem",
        "Does NOT: Miss ext_emconf.php"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(TYPO3|ext_emconf)"
        },
        {
          "type": "content",
          "pattern": "(?i)version"
        }
      ]
    },
    {
      "id": 18,
      "prompt": "Detect the project type and version files for this repository",
      "expected_output": "Analyze all ecosystem indicators. If multiple ecosystems are detected (e.g., composer.json could be TYPO3 or generic PHP), use ext_emconf.php as the discriminator for TYPO3. Report all detected ecosystems and their respective version files.",
      "expectations": [
        "Checks multiple ecosystem indicators",
        "Uses discriminators correctly",
        "Reports all version files",
        "Does NOT: Report only one ecosystem when multiple exist",
        "Does NOT: Ignore secondary indicators"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)ecosystem"
        },
        {
          "type": "content",
          "pattern": "(?i)version"
        }
      ]
    },
    {
      "id": 19,
      "prompt": "Check if Documentation/guides.xml has the correct version",
      "expected_output": "Read Documentation/guides.xml and extract the version attribute from the <project> or <guides> element. Compare it against the version in ext_emconf.php. Report whether they are in sync.",
      "expectations": [
        "Reads guides.xml",
        "Extracts version",
        "Compares with ext_emconf.php",
        "Reports sync status",
        "Does NOT: Skip guides.xml",
        "Does NOT: Ignore version mismatch"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)guides\\.xml"
        },
        {
          "type": "content",
          "pattern": "(?i)version"
        },
        {
          "type": "content",
          "pattern": "(?i)ext_emconf"
        }
      ]
    },
    {
      "id": 20,
      "prompt": "Are the skill version files in sync?",
      "expected_output": "Read plugin.json version field and SKILL.md metadata.version field. Compare them and report whether they match. If mismatched, show both values and recommend which to update.",
      "expectations": [
        "Reads plugin.json version",
        "Reads SKILL.md version",
        "Compares versions",
        "Reports sync status",
        "Does NOT: Check only one file",
        "Does NOT: Ignore mismatch"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(plugin\\.json|SKILL\\.md)"
        },
        {
          "type": "content",
          "pattern": "(?i)version"
        }
      ]
    },
    {
      "id": 21,
      "prompt": "I accidentally pushed a tag v2.0.0 that points to the wrong commit. How do I fix it?",
      "expected_output": "Diagnose as a burned tag scenario. Explain that the tag v2.0.0 is now immutable and should not be deleted/recreated. Recommend releasing v2.0.1 with the correct content instead. Provide step-by-step recovery instructions.",
      "expectations": [
        "Identifies burned tag scenario",
        "Explains immutability",
        "Recommends patch version",
        "Provides recovery steps",
        "Does NOT: Suggest deleting and recreating the tag",
        "Does NOT: Suggest git push --force for tags"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)burned"
        },
        {
          "type": "content",
          "pattern": "(?i)immut"
        },
        {
          "type": "content",
          "pattern": "(?i)(v2\\.0\\.1|patch)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)git push --force.*tag"
        }
      ]
    },
    {
      "id": 22,
      "prompt": "The release workflow failed with startup_failure. What happened?",
      "expected_output": "Investigate the release workflow run. Check for common causes: missing permissions in the caller workflow (contents: write, pull-requests: write), broken reusable workflow reference, or invalid workflow syntax. Check the workflow file and its permissions block. Provide specific diagnosis and fix.",
      "expectations": [
        "Checks workflow run status",
        "Identifies failure point",
        "Checks permissions",
        "Recommends workflow fix",
        "Does NOT: Ignore startup_failure status",
        "Does NOT: Suggest creating the release manually"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(workflow|run)"
        },
        {
          "type": "content",
          "pattern": "(?i)permission"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 23,
      "prompt": "This repo has no release workflow. Set one up.",
      "expected_output": "Detect the project ecosystem. Scaffold a .github/workflows/release.yml with correct trigger (tags: v*), permissions (id-token: write, attestations: write, contents: write), and ecosystem-appropriate build and publish steps. Include SBOM generation, cosign signing, and GitHub attestation steps.",
      "expectations": [
        "Detects ecosystem",
        "Creates release.yml",
        "Includes tag trigger",
        "Includes permissions",
        "Includes SBOM",
        "Includes signing",
        "Does NOT: Create workflow without tag trigger",
        "Does NOT: Omit signing permissions",
        "Does NOT: Skip SBOM generation"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)ecosystem"
        },
        {
          "type": "content",
          "pattern": "(?i)release\\.yml"
        },
        {
          "type": "content",
          "pattern": "(?i)permission"
        },
        {
          "type": "content",
          "pattern": "(?i)SBOM"
        },
        {
          "type": "content",
          "pattern": "(?i)(signing|cosign)"
        }
      ]
    },
    {
      "id": 24,
      "prompt": "Show the release status of this project",
      "expected_output": "List all version tags and check their types (annotated vs lightweight). If any lightweight tags are found, flag them as warnings. Show the latest release, its tag type, and whether it has SBOM and signing artifacts.",
      "expectations": [
        "Lists version tags",
        "Checks tag types",
        "Flags lightweight tags",
        "Shows release artifacts",
        "Does NOT: Ignore lightweight tags",
        "Does NOT: Skip tag type verification"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(tag|release|version)"
        },
        {
          "type": "content",
          "pattern": "(?i)(v[0-9]|commit)"
        }
      ]
    },
    {
      "id": 25,
      "prompt": "Check if all version files are consistent",
      "expected_output": "Detect all version files for the project ecosystem. Read each file and extract the version string. Compare all versions and report any drift. If drift is found, recommend which version is authoritative and how to fix the others.",
      "expectations": [
        "Finds all version files",
        "Extracts versions",
        "Compares all versions",
        "Reports drift clearly",
        "Does NOT: Check only one file",
        "Does NOT: Ignore drift"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)version"
        },
        {
          "type": "content",
          "pattern": "(?i)(file|consistent|sync|drift|match)"
        }
      ]
    },
    {
      "id": 26,
      "prompt": "Check if the release workflow has the correct permissions",
      "expected_output": "Read .github/workflows/release.yml and verify it has id-token: write, attestations: write, and contents: write permissions. Report any missing permissions and explain why each is needed.",
      "expectations": [
        "Checks id-token permission",
        "Checks attestations permission",
        "Checks contents permission",
        "Explains purpose of each",
        "Does NOT: Skip permission verification",
        "Does NOT: Approve workflow without id-token: write"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)id-token"
        },
        {
          "type": "content",
          "pattern": "(?i)(permission|write)"
        }
      ]
    },
    {
      "id": 27,
      "prompt": "Does the latest release have an SBOM?",
      "expected_output": "Query the latest GitHub release assets. Check for SBOM files (sbom.json, sbom.spdx, *.cdx.json, etc.). Report whether SBOM is present and which format. If missing, recommend adding SBOM generation to the release workflow.",
      "expectations": [
        "Queries release assets",
        "Checks for SBOM files",
        "Reports format",
        "Recommends fix if missing",
        "Does NOT: Assume SBOM exists without checking",
        "Does NOT: Skip asset inspection"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)SBOM"
        },
        {
          "type": "content",
          "pattern": "(?i)(asset|release|check)"
        }
      ]
    },
    {
      "id": 28,
      "prompt": "Is the latest release signed with cosign?",
      "expected_output": "Query the latest GitHub release assets. Check for cosign signature bundles (preferred extension `.sigstore.json`, with `.bundle` accepted as legacy) and attestation artifacts. Report signing status. If missing or using only `.bundle`, recommend `.sigstore.json` for OSSF Scorecard Signed-Releases compliance.",
      "expectations": [
        "Queries release assets",
        "Checks for .sigstore.json or .bundle signature files",
        "Reports signing status",
        "Recommends fix if missing",
        "Notes OSSF Scorecard requires .sigstore.json (or another allowlisted extension) — .bundle alone scores 0/10",
        "Does NOT: Assume signing exists without checking",
        "Does NOT: Skip signature file inspection"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)cosign"
        },
        {
          "type": "content",
          "pattern": "(?i)(sign|bundle|attestat)"
        }
      ]
    },
    {
      "id": 29,
      "prompt": "Does this release workflow meet SLSA Level 3?",
      "expected_output": "Analyze the release workflow for SLSA L3 requirements: uses a reusable workflow or trusted builder, has provenance generation, runs on GitHub-hosted runners, has no user-controlled build parameters that could inject commands. Report compliance level and gaps.",
      "expectations": [
        "Checks for reusable workflow",
        "Checks provenance generation",
        "Checks runner type",
        "Reports compliance level",
        "Does NOT: Claim SLSA L3 without verification",
        "Does NOT: Skip provenance check"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)SLSA"
        },
        {
          "type": "content",
          "pattern": "(?i)provenance"
        },
        {
          "type": "content",
          "pattern": "(?i)(runner|workflow|build)"
        }
      ]
    },
    {
      "id": 30,
      "prompt": "Can I manually trigger the release workflow?",
      "expected_output": "Check if .github/workflows/release.yml has a workflow_dispatch trigger. If present, explain how to use it from the GitHub Actions UI or gh CLI. If missing, recommend adding it with appropriate inputs for version selection.",
      "expectations": [
        "Checks for workflow_dispatch",
        "Explains usage if present",
        "Recommends adding if missing",
        "Does NOT: Suggest running gh release create as alternative"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)workflow_dispatch"
        },
        {
          "type": "content",
          "pattern": "(?i)(trigger|manual|dispatch)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 31,
      "prompt": "The CI release workflow for v2.4.7 just completed successfully. The auto-generated release notes only list PR titles.",
      "expected_output": "Recognize that the release description needs overhauling. Review the commits included in the release (git log prev_tag..v2.4.7). Write a narrative release description grouped by theme (features, fixes, infrastructure) that explains what changed and why. Update the description using gh release edit v2.4.7 --notes \"...\".",
      "expectations": [
        "Reviews commits since previous tag",
        "Writes narrative description",
        "Groups changes by theme",
        "Uses gh release edit --notes",
        "Description reads like a human-written changelog",
        "Does NOT: Leave the auto-generated notes as-is",
        "Does NOT: Skip reviewing the commits",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(commit|git log)"
        },
        {
          "type": "content",
          "pattern": "(?i)gh release edit.*--notes"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 32,
      "prompt": "Release v2.4.7 was just published. There are no GitHub Releases for v2.4.5 or v2.4.6 (tags exist but releases were never created due to CI issues).",
      "expected_output": "Include changes from all skipped versions in the release description. Review commits from the last successfully released version (not just the previous tag). Mention in the description that this release covers multiple unreleased versions and explain why.",
      "expectations": [
        "Identifies skipped versions",
        "Covers full changelog since last release",
        "Explains version gap",
        "Uses gh release edit --notes",
        "Does NOT: Only cover changes since v2.4.6",
        "Does NOT: Ignore skipped versions",
        "Does NOT: Leave out context about missing releases"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(v2\\.4\\.5|v2\\.4\\.6|skipped|missing)"
        },
        {
          "type": "content",
          "pattern": "(?i)(CI|workflow|failed)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)I('ll| will) (run|execute).*gh release create"
        }
      ]
    },
    {
      "id": 33,
      "prompt": "We have a breaking change but the current version is 0.5.2. What version should it be?",
      "expected_output": "Explain pre-1.0.0 semver rules: breaking changes bump the minor version (0.5.2 -> 0.6.0), not the major version. Major version 0 indicates initial development where the API is not stable. Recommend 0.6.0.",
      "expectations": [
        "Explains pre-1.0 semver rules",
        "Recommends 0.6.0",
        "Explains minor bump for breaking changes",
        "Does NOT: Recommend 1.0.0 for a breaking change at 0.x",
        "Does NOT: Apply post-1.0 semver rules"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)0\\.6\\.0"
        },
        {
          "type": "content",
          "pattern": "(?i)(pre-1\\.0|major version 0|minor)"
        },
        {
          "type": "content",
          "pattern": "(?i)breaking"
        }
      ]
    },
    {
      "id": 34,
      "prompt": "Suggest the next version based on commits",
      "expected_output": "Analyze commits since the last tag. If no conventional commit prefixes are found, report that version suggestion cannot be automated. Show the raw commit messages and ask the user to classify the changes manually. Provide guidance on choosing major/minor/patch.",
      "expectations": [
        "Detects missing conventional commits",
        "Shows raw commits",
        "Asks user for classification",
        "Provides guidance",
        "Does NOT: Guess a version without evidence",
        "Does NOT: Assume patch version by default"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(commit|git log)"
        },
        {
          "type": "content",
          "pattern": "(?i)(feat|fix|conventional|semver)"
        },
        {
          "type": "content",
          "pattern": "(?i)(v[0-9]|minor|patch|major)"
        }
      ]
    },
    {
      "id": 35,
      "prompt": "Release the auth package at v2.0.0 in this monorepo",
      "expected_output": "Detect monorepo structure. Identify the specific package to release. Update version files only within the auth package scope. Create a scoped tag (e.g., auth/v2.0.0 or @scope/auth@2.0.0). Ensure the release workflow supports scoped tags.",
      "expectations": [
        "Detects monorepo",
        "Scopes changes to auth package",
        "Creates scoped tag",
        "Verifies workflow support",
        "Does NOT: Update version files in other packages",
        "Does NOT: Create an unscoped v2.0.0 tag"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)monorepo"
        },
        {
          "type": "content",
          "pattern": "(?i)auth"
        },
        {
          "type": "content",
          "pattern": "(?i)(version|package)"
        }
      ]
    },
    {
      "id": 36,
      "prompt": "This project has never been released. Create the first release.",
      "expected_output": "Verify no existing tags. Determine initial version (typically 1.0.0 or 0.1.0 depending on project maturity). Create or verify CHANGELOG.md exists. Set version in all ecosystem-appropriate files. Create version bump PR. After merge, create signed annotated tag.",
      "expectations": [
        "Verifies no existing tags",
        "Discusses initial version choice",
        "Creates CHANGELOG if needed",
        "Sets version in all files",
        "Does NOT: Assume tags exist",
        "Does NOT: Skip CHANGELOG creation",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)(tag|version)"
        },
        {
          "type": "content",
          "pattern": "(?i)CHANGELOG"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    },
    {
      "id": 37,
      "prompt": "Create a release candidate for version 3.0.0",
      "expected_output": "Create version 3.0.0-rc.1 following semver pre-release conventions. Update version files with the pre-release version. Create a signed annotated tag v3.0.0-rc.1. Ensure the release workflow marks it as a pre-release on GitHub. Explain the RC promotion process.",
      "expectations": [
        "Uses -rc.1 suffix",
        "Updates version files",
        "Creates signed tag",
        "Marks as pre-release",
        "Explains promotion process",
        "Does NOT: Create a full 3.0.0 release",
        "Does NOT: Skip pre-release flag",
        "Does NOT: Use gh release create"
      ],
      "assertions": [
        {
          "type": "content",
          "pattern": "(?i)rc\\.1"
        },
        {
          "type": "content",
          "pattern": "(?i)(version|pre-release)"
        },
        {
          "type": "content",
          "pattern": "(?i)(signed|git tag -s)"
        },
        {
          "type": "must_not",
          "pattern": "(?i)gh release create"
        }
      ]
    }
  ]
}

#!/usr/bin/env python3
"""check-changelog-links.py - Verify Keep-a-Changelog reference-style links.

Keep-a-Changelog projects commonly use reference-style section headers:

    ## [0.5.0] - 2026-04-19

...and define the link target at the bottom of the file:

    [Unreleased]: https://github.com/owner/repo/compare/v0.5.0...HEAD
    [0.5.0]: https://github.com/owner/repo/compare/v0.4.0...v0.5.0

When a new release is added it is easy to add the header without adding the
matching footer link (or to forget updating the `[Unreleased]` compare range).
The rendered CHANGELOG then shows a broken `[0.5.0]` link — a regression that
Copilot review tends to catch late in the PR cycle instead of the skill
catching it locally.

This script parses CHANGELOG.md and reports:

  1. Any `## [X.Y.Z]` (or `## [X.Y.Z-prerelease]`) header without a matching
     footer link definition.
  2. A stale `[Unreleased]: .../compare/<previous>...HEAD` range when the
     newest release is not `<previous>`.

Exits:
  0 - all references resolve / file absent / no reference-style headers used
  1 - a CHANGELOG error was detected. Either:
        * one or more reference-style headers lack a footer link, or
        * the `[Unreleased]: .../compare/<from>...HEAD` range is stale
          (i.e., `<from>` is not the newest released version in the
          header list).
  2 - environment error (file unreadable, etc.)

Usage: check-changelog-links.py [path-to-changelog]
"""

from __future__ import annotations

import re
import sys
from pathlib import Path

HEADER_RE = re.compile(
    r"^##\s+\[(?P<version>[^\]]+)\](?:\s*[-\u2013]\s*[0-9A-Za-z.\- ]+)?\s*$"
)
# Matches footer definitions like: [0.5.0]: https://...
FOOTER_RE = re.compile(r"^\[(?P<key>[^\]]+)\]:\s*(?P<url>\S.*)\s*$")
# Matches an Unreleased compare range ending in HEAD. The capture group must
# allow dots so it can match common forms like `v0.5.0...HEAD` or `0.5.0...HEAD`
# (the previous `[^./]+` class excluded dots and therefore missed semver
# versions entirely — it would only match refs like `main` or `abc1234`).
UNRELEASED_COMPARE_RE = re.compile(r"/compare/(?P<from>[^/]+?)\.\.\.HEAD\s*$")


def main(argv: list[str]) -> int:
    path = Path(argv[1]) if len(argv) > 1 else Path("CHANGELOG.md")
    if not path.exists():
        # No CHANGELOG is a separate concern; do not flag here.
        return 0

    try:
        text = path.read_text(encoding="utf-8")
    except OSError as exc:
        print(f"error: cannot read {path}: {exc}", file=sys.stderr)
        return 2

    header_versions: list[str] = []
    footer_keys: dict[str, str] = {}

    for raw_line in text.splitlines():
        line = raw_line.rstrip()
        match = HEADER_RE.match(line)
        if match:
            header_versions.append(match.group("version"))
            continue
        match = FOOTER_RE.match(line)
        if match:
            footer_keys[match.group("key")] = match.group("url")

    if not header_versions:
        # Plain headers (no reference-style) — nothing to validate.
        return 0

    # Only enforce if the project is actually using reference-style links.
    # Detect that by the presence of at least one footer key that matches any
    # header version or the literal "Unreleased".
    uses_reference_style = (
        any(key in footer_keys for key in header_versions)
        or "Unreleased" in footer_keys
    )
    if not uses_reference_style:
        return 0

    missing: list[str] = []
    for version in header_versions:
        # Skip the textual "Unreleased" entry from header scan — tracked
        # separately below. `## [Unreleased]` is valid without a date.
        if version.lower() == "unreleased":
            continue
        if version not in footer_keys:
            missing.append(version)

    warnings: list[str] = []

    # Check Unreleased compare range points at the newest released version.
    # Newest release = first non-Unreleased header (Keep-a-Changelog orders
    # releases newest-first).
    newest_release = next(
        (v for v in header_versions if v.lower() != "unreleased"),
        None,
    )
    unreleased_url = footer_keys.get("Unreleased")
    if newest_release and unreleased_url:
        compare_match = UNRELEASED_COMPARE_RE.search(unreleased_url)
        if compare_match:
            compare_from = compare_match.group("from")
            expected = f"v{newest_release}"
            # Accept either `vX.Y.Z` or bare `X.Y.Z` in the compare range.
            if compare_from not in {expected, newest_release}:
                warnings.append(
                    f"[Unreleased] compare range starts at {compare_from!r} "
                    f"but newest release is {newest_release!r} "
                    f"(expected {expected!r})"
                )

    if not missing and not warnings:
        return 0

    print(f"CHANGELOG link-reference issues in {path}:")
    for version in missing:
        print(
            f"  MISSING footer link for [{version}] — "
            f"add `[{version}]: <compare-URL>` at the bottom of the file"
        )
    for warning in warnings:
        print(f"  STALE   {warning}")

    if missing:
        print("")
        print(
            "Add the missing footer link(s) and update the "
            "`[Unreleased]: .../compare/vX.Y.Z...HEAD` range to the newest "
            "released version."
        )
        return 1
    # Only warnings -> still signal non-zero so the mechanical check
    # registers, but the checkpoint severity is `warning` so the skill
    # surfaces it as a suggestion rather than a hard stop.
    return 1


if __name__ == "__main__":
    sys.exit(main(sys.argv))

#!/usr/bin/env bash
#
# check-release-workflow.sh - Check if the project has a proper release workflow.
#
# Examines .github/workflows/release.yml for required features and reports
# PRESENT/MISSING per item.
#
set -euo pipefail

WORKFLOW=".github/workflows/release.yml"

present_count=0
missing_count=0

report() {
    local status="$1" label="$2" detail="${3:-}"
    if [[ "$status" == "PRESENT" ]]; then
        ((present_count++)) || true
        printf "  PRESENT  %s" "$label"
    else
        ((missing_count++)) || true
        printf "  MISSING  %s" "$label"
    fi
    if [[ -n "$detail" ]]; then
        printf " (%s)" "$detail"
    fi
    printf "\n"
}

echo "Release workflow analysis"
echo "========================="
echo ""

# ---------------------------------------------------------------------------
# 1. Workflow file exists
# ---------------------------------------------------------------------------
if [[ ! -f "$WORKFLOW" ]]; then
    report "MISSING" "Release workflow file" "$WORKFLOW not found"
    echo ""
    echo "========================="
    echo "Results: 0 present, 1 missing"
    echo ""
    echo "OVERALL: No release workflow found"
    exit 1
fi

report "PRESENT" "Release workflow file" "$WORKFLOW"
workflow_content=$(cat "$WORKFLOW")

# ---------------------------------------------------------------------------
# 2. Triggers on push tags v*
# ---------------------------------------------------------------------------
echo ""
echo "Triggers:"
if echo "$workflow_content" | grep -qE "tags:[[:space:]]*\[?['\"]?v\*" 2>/dev/null || \
   echo "$workflow_content" | grep -qE "^[[:space:]]+-[[:space:]]+['\"]?v\*" 2>/dev/null; then
    report "PRESENT" "Push tag trigger (v*)"
else
    report "MISSING" "Push tag trigger (v*)"
fi

if echo "$workflow_content" | grep -q 'workflow_dispatch' 2>/dev/null; then
    report "PRESENT" "workflow_dispatch trigger"
else
    report "MISSING" "workflow_dispatch trigger"
fi

# ---------------------------------------------------------------------------
# 3. Permissions
# ---------------------------------------------------------------------------
echo ""
echo "Permissions:"
if echo "$workflow_content" | grep -qE 'id-token[[:space:]]*:[[:space:]]*write' 2>/dev/null; then
    report "PRESENT" "id-token: write"
else
    report "MISSING" "id-token: write"
fi

if echo "$workflow_content" | grep -qE 'attestations[[:space:]]*:[[:space:]]*write' 2>/dev/null; then
    report "PRESENT" "attestations: write"
else
    report "MISSING" "attestations: write"
fi

if echo "$workflow_content" | grep -qE 'contents[[:space:]]*:[[:space:]]*write' 2>/dev/null; then
    report "PRESENT" "contents: write"
else
    report "MISSING" "contents: write"
fi

# ---------------------------------------------------------------------------
# 4. Reusable workflows
# ---------------------------------------------------------------------------
echo ""
echo "Reusable workflows:"
if echo "$workflow_content" | grep -qE 'netresearch/typo3-ci-workflows' 2>/dev/null; then
    report "PRESENT" "netresearch/typo3-ci-workflows"
elif echo "$workflow_content" | grep -qE 'netresearch/\.github' 2>/dev/null; then
    report "PRESENT" "netresearch/.github reusable workflows"
else
    report "MISSING" "Netresearch reusable workflows" "netresearch/typo3-ci-workflows or netresearch/.github"
fi

# ---------------------------------------------------------------------------
# 5. SBOM generation
# ---------------------------------------------------------------------------
echo ""
echo "Supply chain security:"
if echo "$workflow_content" | grep -qE 'anchore/sbom-action|syft|cyclonedx|spdx' 2>/dev/null; then
    match=$(echo "$workflow_content" | grep -oE 'anchore/sbom-action|syft|cyclonedx|spdx' | head -1)
    report "PRESENT" "SBOM generation" "$match"
else
    report "MISSING" "SBOM generation" "anchore/sbom-action or similar"
fi

# ---------------------------------------------------------------------------
# 6. Signing
# ---------------------------------------------------------------------------
if echo "$workflow_content" | grep -qE 'cosign-installer|cosign|sigstore' 2>/dev/null; then
    match=$(echo "$workflow_content" | grep -oE 'cosign-installer|cosign|sigstore' | head -1)
    report "PRESENT" "Signing" "$match"
else
    report "MISSING" "Signing" "cosign-installer or similar"
fi

# ---------------------------------------------------------------------------
# 7. Attestation
# ---------------------------------------------------------------------------
if echo "$workflow_content" | grep -qE 'actions/attest-build-provenance|actions/attest' 2>/dev/null; then
    match=$(echo "$workflow_content" | grep -oE 'actions/attest-build-provenance|actions/attest' | head -1)
    report "PRESENT" "Attestation" "$match"
else
    report "MISSING" "Attestation" "actions/attest-build-provenance or similar"
fi

# ---------------------------------------------------------------------------
# Summary
# ---------------------------------------------------------------------------
echo ""
echo "========================="
total=$((present_count + missing_count))
echo "Results: ${present_count} present, ${missing_count} missing (${total} checks)"

#!/usr/bin/env bash
#
# detect-ecosystem.sh - Scan current directory and report detected ecosystems and version files.
#
# Output format (one line per finding):
#   ecosystem:<name>
#   version-file:<path>:<version>
#   docs-version-ref:<path>:<directive>::<version>
#   changelog:<path>
#
set -euo pipefail

# Extract a JSON field value using grep/sed (no jq dependency)
# Usage: json_field <file> <field>
json_field() {
    local file="$1" field="$2"
    sed -n "s/.*\"${field}\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$file" 2>/dev/null | head -1 || true
}

# Extract version from ext_emconf.php
emconf_version() {
    sed -n "s/.*'version'[[:space:]]*=>[[:space:]]*'\([^']*\)'.*/\1/p" "$1" 2>/dev/null | head -1 || true
}

# Extract version from a Cargo.toml (top-level only, before first [dependencies] etc.)
cargo_version() {
    sed -n '/^\[package\]/,/^\[/{/^version\s*=/p}' "$1" 2>/dev/null \
        | sed -n 's/.*version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' || true
}

# Extract version from pyproject.toml [project] section
pyproject_version() {
    sed -n '/^\[project\]/,/^\[/{/^version\s*=/p}' "$1" 2>/dev/null \
        | sed -n 's/.*version[[:space:]]*=[[:space:]]*"\([^"]*\)".*/\1/p' || true
}

# Extract version from setup.py
setup_py_version() {
    sed -n 's/.*version[[:space:]]*=[[:space:]]*['"'"'"]\([^'"'"'"]*\).*/\1/p' "$1" 2>/dev/null | head -1 || true
}

# Extract version from pom.xml (first occurrence, project-level)
pom_version() {
    # Grab version outside of <parent> and <dependency> blocks - simplified: first <version> child of <project>
    sed -n '/<project/,/<\/project>/{/<parent>/,/<\/parent>/d; s/.*<version>\(.*\)<\/version>.*/\1/p;}' "$1" 2>/dev/null \
        | head -1 || true
}

# Extract version from go.mod module line (Go modules don't carry semver in go.mod itself,
# but the module path may contain /v2 etc.)
go_mod_version() {
    sed -n 's/^module[[:space:]]\{1,\}.*\/v\([0-9]\{1,\}\).*/\1/p' "$1" 2>/dev/null | head -1 || true
}

# Extract version from guides.xml
guides_xml_version() {
    sed -n 's/.*<release>[[:space:]]*\([^<[:space:]]\{1,\}\).*/\1/p' "$1" 2>/dev/null | head -1 \
        || sed -n 's/.*release="\([^"]*\)".*/\1/p' "$1" 2>/dev/null | head -1 \
        || true
}

# ---------------------------------------------------------------------------
# TYPO3
# ---------------------------------------------------------------------------
if [[ -f ext_emconf.php ]]; then
    echo "ecosystem:typo3"
    ver=$(emconf_version ext_emconf.php)
    echo "version-file:ext_emconf.php:${ver}"

    # composer.json (may or may not have version for TYPO3 extensions)
    if [[ -f composer.json ]]; then
        cver=$(json_field composer.json version)
        echo "version-file:composer.json:${cver}"
    fi

    # Documentation/guides.xml
    if [[ -f Documentation/guides.xml ]]; then
        gver=$(guides_xml_version Documentation/guides.xml)
        echo "version-file:Documentation/guides.xml:${gver}"
    fi

    # Scan Documentation/**/*.rst for versionadded / versionchanged directives
    if [[ -d Documentation ]]; then
        while IFS= read -r rstfile; do
            grep -E '^\.\.[[:space:]]+(versionadded|versionchanged)::' "$rstfile" 2>/dev/null | while IFS= read -r match; do
                directive=$(echo "$match" | grep -oE '(versionadded|versionchanged)' || true)
                dver=$(echo "$match" | sed -n 's/.*::[[:space:]]*\([^[:space:]]\{1,\}\).*/\1/p' || true)
                if [[ -n "$directive" ]]; then
                    echo "docs-version-ref:${rstfile}:${directive}::${dver}"
                fi
            done || true
        done < <(find Documentation -name '*.rst' -type f 2>/dev/null)
    fi
fi

# ---------------------------------------------------------------------------
# Skill repo (.claude-plugin/plugin.json)
# ---------------------------------------------------------------------------
if [[ -f .claude-plugin/plugin.json ]]; then
    echo "ecosystem:skill"
    sver=$(json_field .claude-plugin/plugin.json version)
    echo "version-file:.claude-plugin/plugin.json:${sver}"

    # skills/*/SKILL.md - extract version from YAML frontmatter or version: line
    for skillmd in skills/*/SKILL.md; do
        [[ -f "$skillmd" ]] || continue
        mdver=$(sed -n 's/^version:[[:space:]]*\([^[:space:]]\{1,\}\).*/\1/p' "$skillmd" 2>/dev/null | head -1 || true)
        echo "version-file:${skillmd}:${mdver}"
    done
fi

# ---------------------------------------------------------------------------
# PHP (composer.json with version, but not already reported under TYPO3)
# ---------------------------------------------------------------------------
if [[ -f composer.json ]] && [[ ! -f ext_emconf.php ]]; then
    cver=$(json_field composer.json version)
    if [[ -n "$cver" ]]; then
        echo "ecosystem:php"
        echo "version-file:composer.json:${cver}"
    fi
fi

# ---------------------------------------------------------------------------
# Node.js
# ---------------------------------------------------------------------------
if [[ -f package.json ]]; then
    is_private=$(json_field package.json private)
    pkg_ver=$(json_field package.json version)
    if [[ "$is_private" != "true" ]] || [[ -n "$pkg_ver" ]]; then
        echo "ecosystem:nodejs"
        echo "version-file:package.json:${pkg_ver}"
        if [[ -f package-lock.json ]]; then
            lock_ver=$(json_field package-lock.json version)
            echo "version-file:package-lock.json:${lock_ver}"
        fi
    fi
fi

# ---------------------------------------------------------------------------
# Go
# ---------------------------------------------------------------------------
if [[ -f go.mod ]]; then
    echo "ecosystem:go"
    gover=$(go_mod_version go.mod)
    echo "version-file:go.mod:${gover}"
fi

# ---------------------------------------------------------------------------
# Python
# ---------------------------------------------------------------------------
if [[ -f pyproject.toml ]]; then
    echo "ecosystem:python"
    pyver=$(pyproject_version pyproject.toml)
    echo "version-file:pyproject.toml:${pyver}"
elif [[ -f setup.py ]]; then
    echo "ecosystem:python"
    pyver=$(setup_py_version setup.py)
    echo "version-file:setup.py:${pyver}"
fi

# ---------------------------------------------------------------------------
# Rust
# ---------------------------------------------------------------------------
if [[ -f Cargo.toml ]]; then
    echo "ecosystem:rust"
    rver=$(cargo_version Cargo.toml)
    echo "version-file:Cargo.toml:${rver}"
fi

# ---------------------------------------------------------------------------
# Java / Maven
# ---------------------------------------------------------------------------
if [[ -f pom.xml ]]; then
    echo "ecosystem:java"
    jver=$(pom_version pom.xml)
    echo "version-file:pom.xml:${jver}"
fi

# ---------------------------------------------------------------------------
# Common files (always check)
# ---------------------------------------------------------------------------
if [[ -f CHANGELOG.md ]]; then
    echo "changelog:CHANGELOG.md"
fi

if [[ -f VERSION ]]; then
    vver=$(head -1 VERSION 2>/dev/null | tr -d '[:space:]')
    echo "version-file:VERSION:${vver}"
fi

#!/usr/bin/env python3
"""
PreToolUse hook that blocks dangerous GitHub release operations.

Blocks:
  - gh release create/delete (always)
  - gh release edit (unless only --notes or --notes-file flags are used)
  - gh api calls to release endpoints with mutating HTTP methods

Allows:
  - gh release view/list/download (read-only)
  - gh release edit --notes "..." (release description overhaul)
  - gh release edit --notes-file ... (release description overhaul)
  - gh run commands (workflow management)
  - Any non-release gh commands

Exit codes:
  0 = allow the command
  2 = block the command
"""

import json
import re
import sys


def parse_command(input_data: str) -> str:
    """Extract the command string from hook input (JSON via stdin)."""
    if not input_data:
        return ""
    try:
        data = json.loads(input_data)
        return data.get("command", "")
    except (json.JSONDecodeError, TypeError):
        return input_data


def block(reason: str, suggestion: str) -> None:
    """Print a YAML-formatted block reason to stderr and exit 2."""
    print(
        f"""---
blocked: true
reason: |
  {reason}
suggestion: |
  {suggestion}
---""",
        file=sys.stderr,
    )
    sys.exit(2)


# Regex that matches "gh release <subcommand>" with flexible whitespace.
# We capture the subcommand to decide allow vs block.
GH_RELEASE_RE = re.compile(
    r"""
    (?:^|[;&|]\s*|&&\s*|\|\|\s*)   # start of string or command separator
    gh\s+release\s+(\S+)            # gh release <subcommand>
    """,
    re.VERBOSE,
)

# Read-only subcommands that are safe.
ALLOWED_RELEASE_SUBCOMMANDS = {"view", "list", "download"}

# gh api calls to release endpoints with mutating methods.
# Matches patterns like:
#   gh api repos/owner/repo/releases -X POST
#   gh api /repos/owner/repo/releases --method DELETE
#   gh api repos/owner/repo/releases/123 -X PATCH
GH_API_RELEASE_RE = re.compile(
    r"""
    (?:^|[;&|]\s*|&&\s*|\|\|\s*)    # start or separator
    gh\s+api\s+                      # gh api
    (?:(?:-\w+|--\w[\w-]*)(?:\s+(?:"[^"]*"|'[^']*'|\S+))?\s+)*  # optional flags (e.g. -X POST, -H "...")
    /?repos/[^\s]+/releases          # release endpoint path
    """,
    re.VERBOSE,
)

MUTATING_METHOD_RE = re.compile(
    r"""
    (?:-X|--method)\s*(POST|PUT|PATCH|DELETE)
    """,
    re.VERBOSE | re.IGNORECASE,
)


# Flags for gh release edit that modify metadata other than notes.
# See: gh release edit --help
# Uses \b word boundaries to avoid prefix collisions with future flags.
_DANGEROUS_EDIT_FLAGS = re.compile(
    r"""
    (?:^|\s)
    (?:
        --draft\b
        |--prerelease\b
        |--latest\b
        |--tag\b
        |--target\b
        |--title\b
        |-t\b
        |--discussion-category\b
        |--verify-tag\b
    )
    """,
    re.VERBOSE,
)


def _is_notes_only_edit(args: str) -> bool:
    """Return True if gh release edit args only modify notes."""
    # Truncate at shell separators so chained commands don't pollute the check.
    # e.g. "v1.0.0 --notes '...' ; other-cmd --draft" → "v1.0.0 --notes '...'"
    args = re.split(r"\s*(?:;|&&|\|\|)\s*", args)[0]
    # Strip quoted strings to avoid false positives from notes content.
    # e.g. --notes "Changed --draft behavior" should not trigger --draft block.
    clean_args = re.sub(r'"[^"]*"|\'[^\']*\'', "", args)
    has_notes = bool(
        re.search(r"(?:^|\s)(?:--notes\b|--notes-file\b|-n\b|-F\b)", clean_args)
    )
    has_dangerous = bool(_DANGEROUS_EDIT_FLAGS.search(clean_args))
    return has_notes and not has_dangerous


def check_command(command: str) -> None:
    """Check the command and block if it is a dangerous release operation."""
    # Normalise for easier matching (collapse multiple spaces).
    cmd = " ".join(command.split())

    # --- Check gh release <subcommand> ---
    for match in GH_RELEASE_RE.finditer(cmd):
        subcommand = match.group(1).lower()
        if subcommand in ALLOWED_RELEASE_SUBCOMMANDS:
            continue
        if subcommand == "create":
            block(
                "Direct 'gh release create' bypasses the CI release pipeline. "
                "Releases MUST be created by the CI/CD workflow to ensure "
                "proper provenance, signing, and artifact generation.",
                "Push a version tag (git tag -s vX.Y.Z && git push origin vX.Y.Z) "
                "to trigger the release workflow, or run the release workflow "
                "manually via 'gh workflow run'.",
            )
        elif subcommand == "delete":
            block(
                "Deleting a GitHub release is a destructive, irreversible operation. "
                "Published releases are immutable artifacts that downstream consumers "
                "may depend on.",
                "If a release contains a critical defect, create a new patch release "
                "instead (vX.Y.Z+1). If you must deprecate a release, edit its notes "
                "to mark it as deprecated via the CI pipeline.",
            )
        elif subcommand == "edit":
            # Allow notes-only edits for release description overhaul.
            # Extract the portion of the command after "gh release edit".
            edit_args = cmd[match.end() :]
            if _is_notes_only_edit(edit_args):
                continue
            block(
                "Editing a GitHub release outside of notes overhaul bypasses audit "
                "controls. Only --notes and --notes-file are permitted.",
                "Use 'gh release edit vX.Y.Z --notes \"...\"' to overhaul the "
                "release description. Other release metadata should be managed "
                "through the CI release workflow.",
            )
        else:
            # Unknown subcommand -- block to be safe.
            block(
                f"Unknown 'gh release {subcommand}' subcommand. Only read-only "
                f"operations (view, list, download) are permitted outside CI.",
                "Use 'gh release view' or 'gh release list' for read-only access. "
                "All mutating release operations must go through the CI pipeline.",
            )

    # --- Check gh api calls to release endpoints ---
    if GH_API_RELEASE_RE.search(cmd):
        # If no explicit method flag, gh api defaults to GET for bare calls,
        # but POST when -f/--field or --input is present. We block if a
        # mutating method is specified OR if data-sending flags are present.
        has_mutating_method = MUTATING_METHOD_RE.search(cmd)
        has_data_flags = re.search(r"\s(-f|--field|-F|--json-field|--input)\s", cmd)
        if has_mutating_method or has_data_flags:
            method = ""
            if has_mutating_method:
                method = has_mutating_method.group(1).upper()
            block(
                f"Direct API call to release endpoint{' with ' + method + ' method' if method else ''} "
                f"bypasses the CI release pipeline. All mutating operations on "
                f"releases must go through CI.",
                "Use the CI release workflow to create or modify releases. "
                "For read-only queries, use 'gh api' without mutating methods "
                "or data flags.",
            )


def main() -> None:
    try:
        input_data = sys.stdin.read()
    except Exception:
        sys.exit(0)

    command = parse_command(input_data)
    if not command:
        sys.exit(0)

    # Quick pre-check: skip if command does not mention gh at all.
    if "gh" not in command.lower():
        sys.exit(0)

    check_command(command)
    # If we get here, the command is allowed.
    sys.exit(0)


if __name__ == "__main__":
    main()