kpubdata 0.7.0__tar.gz → 0.8.0__tar.gz

kpubdata-0.8.0/.github/CODEOWNERS

@@ -0,0 +1,16 @@
+# R3 paths — changes here require CODEOWNER review (#520)
+/.github/                         @yeongseon
+/src/kpubdata/config.py           @yeongseon
+/src/kpubdata/transport/          @yeongseon
+/src/kpubdata/specs/schema.json   @yeongseon
+/docs/governance/                 @yeongseon
+# Credential host allowlist (#519, #629)
+/src/kpubdata/_hosts.py           @yeongseon
+# Run by jobs holding `contents: write` — release notes, version, titles (#629)
+/scripts/release_notes.py         @yeongseon
+/scripts/set_version.py           @yeongseon
+/scripts/next_version.py          @yeongseon
+/scripts/conventional_title.py    @yeongseon
+# Dependencies (#629)
+/pyproject.toml                   @yeongseon
+/uv.lock                          @yeongseon

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,6 @@
 name: 버그 리포트
 description: 예상과 다르게 동작하는 문제를 신고합니다
-title: "[Bug] "
-labels: ["type:bug"]
+title: "fix: "
 body:
   - type: markdown
     attributes:

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/ISSUE_TEMPLATE/dataset-request.yml

@@ -1,5 +1,6 @@
 name: 데이터셋 추가 요청
 description: spec 기반으로 추가할 공공데이터셋을 요청한다
+title: "feat(datasets): "
 labels: [dataset-request]
 body:
   - type: input

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/ISSUE_TEMPLATE/docs.yml

@@ -1,7 +1,6 @@
 name: 문서 개선
 description: 문서 오류, 누락, 개선 사항을 신고합니다
-title: "[Docs] "
-labels: ["type:docs"]
+title: "docs: "
 body:
   - type: input
     id: location

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,6 @@
 name: 기능 제안
 description: 새로운 기능이나 개선을 제안합니다 (신규 provider는 별도 템플릿 사용)
-title: "[Feature] "
-labels: ["type:feature"]
+title: "feat: "
 body:
   - type: markdown
     attributes:

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/ISSUE_TEMPLATE/new-provider-adapter.yml

@@ -1,7 +1,6 @@
 name: New Provider Adapter
 description: Propose or track a new Korean public data provider adapter
-title: "[Provider] "
-labels: ["type:feature"]
+title: "feat(providers): "
 body:
   - type: markdown
     attributes:

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,7 @@
 <!--
-PR 제목은 Conventional Commits 형식을 권장합니다: feat/fix/docs/refactor/test/chore
+PR 제목은 Conventional Commits 형식이어야 합니다 — `PR title` 체크가 검사합니다(POLICY 2.1.3).
+type: feat fix docs test perf refactor ci build chore style revert — 규칙 정본: docs/governance/POLICY.md 2.1.3
+이슈 번호는 제목이 아니라 본문에 적습니다 (Closes #123). squash 병합이 PR 번호를 붙입니다.
 예) feat: add KOSIS provider adapter
 -->
 

kpubdata-0.8.0/.github/actions/conventional-title/action.yml

@@ -0,0 +1,44 @@
+name: Conventional title
+description: >
+  Parse an issue or pull request title as `type(scope): description` and say which
+  `type:*` label it implies (POLICY 2.1.3). Wraps scripts/conventional_title.py so the
+  three repositories use one parser. Never fails the step — callers decide what an
+  invalid title means, because a pull request should go red and an issue should not.
+
+inputs:
+  title:
+    description: "The title to check. Pass it from the event payload, never through `run:`"
+    required: true
+
+outputs:
+  valid:
+    description: "true or false"
+    value: ${{ steps.run.outputs.valid }}
+  type:
+    description: "The Conventional Commits type, when valid"
+    value: ${{ steps.run.outputs.type }}
+  label:
+    description: "The type:* label the title implies, when valid"
+    value: ${{ steps.run.outputs.label }}
+  error:
+    description: "What is wrong with the title, when invalid"
+    value: ${{ steps.run.outputs.error }}
+
+runs:
+  using: composite
+  steps:
+    # The title is attacker-controlled text. It reaches the script through an
+    # environment variable, not by expansion into the shell line.
+    - id: run
+      shell: bash
+      env:
+        TITLE: ${{ inputs.title }}
+      run: |
+        script="${{ github.action_path }}/../../../scripts/conventional_title.py"
+        if out=$(python3 "${script}" "${TITLE}" 2>/tmp/title-error); then
+          echo "valid=true" >> "$GITHUB_OUTPUT"
+          echo "${out}" >> "$GITHUB_OUTPUT"
+        else
+          echo "valid=false" >> "$GITHUB_OUTPUT"
+          echo "error=$(sed 's/^::error:://' /tmp/title-error | head -1)" >> "$GITHUB_OUTPUT"
+        fi

kpubdata-0.8.0/.github/actions/release-notes/action.yml

@@ -0,0 +1,72 @@
+name: Release notes
+description: >
+  Take a release's notes from its CHANGELOG section, or put that section in place.
+  Wraps scripts/release_notes.py so the three repositories call one implementation.
+  `extract` fails when the section is missing or empty, so a release without notes
+  stops before a tag exists.
+
+inputs:
+  command:
+    description: "promote (prepare job) or extract (release job)"
+    required: true
+  version:
+    description: "The version being released, with or without the leading v"
+    required: true
+  changelog:
+    description: "Path to the CHANGELOG"
+    required: false
+    default: CHANGELOG.md
+  output:
+    description: "Where extract writes the notes (default: the runner's temp directory)"
+    required: false
+    default: ""
+
+outputs:
+  file:
+    description: "The notes file (extract only)"
+    value: ${{ steps.run.outputs.file }}
+  prerelease:
+    description: "true when the version is a pre-release (aN, bN, rcN) — pass --prerelease to gh release create (#622)"
+    value: ${{ steps.run.outputs.prerelease }}
+
+runs:
+  using: composite
+  steps:
+    # The link at the bottom compares against the previous release tag. A first
+    # release has none, so it links the history up to the new tag instead — the tag
+    # does not exist yet while this runs, but will by the time anyone clicks.
+    - id: run
+      shell: bash
+      env:
+        COMMAND: ${{ inputs.command }}
+        VERSION: ${{ inputs.version }}
+        CHANGELOG: ${{ inputs.changelog }}
+        OUTPUT: ${{ inputs.output }}
+        REPO: ${{ github.repository }}
+      run: |
+        script="${{ github.action_path }}/../../../scripts/release_notes.py"
+        if [ "${COMMAND}" = "promote" ]; then
+          python3 "${script}" promote "${VERSION}" --changelog "${CHANGELOG}"
+          exit $?
+        fi
+        OUTPUT="${OUTPUT:-${RUNNER_TEMP}/release-notes.md}"
+        tag="v${VERSION#v}"
+        prerelease=$(python3 "${script}" prerelease "${VERSION}")
+        echo "prerelease=${prerelease}" >> "$GITHUB_OUTPUT"
+        # A final release's notes fold in its pre-releases (#622), so its link
+        # compares against the previous final release, not the last pre-release.
+        exclude=()
+        if [ "${prerelease}" = "false" ]; then
+          exclude=(--exclude 'v*[a-z]*')
+        fi
+        previous=$(git describe --tags --abbrev=0 --match 'v[0-9]*' "${exclude[@]}" HEAD 2>/dev/null || true)
+        if [ -n "${previous}" ] && [ "${previous}" != "${tag}" ]; then
+          compare="https://github.com/${REPO}/compare/${previous}...${tag}"
+        else
+          compare="https://github.com/${REPO}/commits/${tag}"
+        fi
+        python3 "${script}" extract "${VERSION}" --changelog "${CHANGELOG}" \
+          --compare-url "${compare}" --output "${OUTPUT}"
+        echo "file=${OUTPUT}" >> "$GITHUB_OUTPUT"
+        echo "notes for ${tag}:"
+        cat "${OUTPUT}"

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/dependabot.yml

@@ -1,6 +1,6 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "weekly"

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/workflows/build-dataset.yml

@@ -117,9 +117,12 @@ jobs:
             gh issue edit "$ISSUE_NUMBER" --add-label needs-human || true
             exit 1
           fi
-          git commit -m "feat: add dataset via agent procedure (issue #$ISSUE_NUMBER)"
+          # The title names the dataset, not the issue: POLICY 2.1.3 keeps issue numbers
+          # in the body (`Closes #N`), and a squash merge appends the PR number itself.
+          git commit -m "feat(datasets): add ${DATASET:-a requested dataset} via the agent procedure" \
+            -m "Refs #$ISSUE_NUMBER"
           git push origin "$BRANCH"
-          gh pr create --title "[agent] dataset from #$ISSUE_NUMBER" \
+          gh pr create --title "feat(datasets): add ${DATASET:-a requested dataset} via the agent procedure" \
             --body "에이전트 절차 산출물 — verify 통과 확인 후 사람 리뷰. Closes #$ISSUE_NUMBER" \
             --label agent-generated || true
 

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/workflows/ci.yml

@@ -37,6 +37,9 @@ jobs:
       - name: Install dependencies
         run: uv sync --frozen --extra dev
 
+      - name: Lockfile matches pyproject
+        run: uv lock --check
+
       - name: Ruff check
         run: uv run ruff check .
 
@@ -69,6 +72,11 @@ jobs:
       - name: README parity
         run: uv run python scripts/check_readme_parity.py
 
+      # ADR 0007 Rules 1-2: KPubData never depends on KPubData Builder or Studio.
+      # Dependencies flow Studio -> Builder -> KPubData only (#668).
+      - name: Independence (no Builder or Studio dependency)
+        run: uv run python scripts/check_independence.py
+
       # fixture 는 "이 데이터셋은 검증됐다" 의 근거다. 판정 대상이 근거를 고칠 수
       # 있으면 판정이 반증 불가능해진다 (#497, #523).
       - name: Recorded evidence authorship
@@ -284,10 +292,39 @@ jobs:
   #
   # `spec-changes` is left out on purpose: it is a summary for the reviewer, not a
   # verdict, and a gate that fails on it would block a pull request over a report.
+  secret-scan:
+    name: Secret scan (gitleaks)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      GITLEAKS_VERSION: "8.28.0"
+      # sha256 of gitleaks_8.28.0_linux_x64.tar.gz from the release's checksums file,
+      # pinned here so a tampered release cannot also swap its own checksum.
+      GITLEAKS_SHA256: "a65b5253807a68ac0cafa4414031fd740aeb55f54fb7e55f386acb52e6a840eb"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0  # history, not just the tip: a key removed later is still leaked
+
+      # The pinned binary rather than gitleaks-action, which needs a licence key for
+      # organisations — a secret added in order to scan for secrets.
+      - name: Install gitleaks
+        run: |
+          archive="gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz"
+          curl -sSfL -o "${archive}" \
+            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${archive}"
+          echo "${GITLEAKS_SHA256}  ${archive}" | sha256sum -c -
+          tar xzf "${archive}" gitleaks
+
+      # A leaked credential is never acceptable to merge, so this job is one of
+      # `CI gate`'s needs (#631). The dependency audit and CodeQL live in security.yml.
+      - name: Scan the full history
+        run: ./gitleaks git . --redact --no-banner --log-level info
+
   gate:
     name: CI gate
     runs-on: ubuntu-latest
-    needs: [quality, test, coverage, build, base-install, docs]
+    needs: [quality, test, coverage, build, base-install, docs, secret-scan]
     # `always()` so a failed job still reaches this step. Without it the gate is
     # skipped when something upstream fails, and a skipped required check is the same
     # absence this job exists to remove.

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/workflows/publish-pypi.yml

@@ -1,7 +1,20 @@
 # Build and publish the distribution. Two ways in, and neither of them pushes to main.
 #
 #   release: published   — a release made by hand in the GitHub UI
-#   workflow_call        — release.yml, after a release pull request merged
+#   workflow_dispatch    — after release.yml has tagged (see below)
+#
+# **This has to stay the top-level workflow.** PyPI's trusted publisher matches the
+# OIDC certificate's Build Config URI, which names the workflow GitHub *started*, not
+# the one that ran. Calling this from release.yml as a reusable workflow made the
+# certificate say `release.yml` and PyPI refused v0.7.0:
+#
+#   Certificate's Build Config URI (.../workflows/release.yml@refs/heads/main)
+#   does not match expected Trusted Publisher (publish-pypi.yml @ yeongseon/kpubdata)
+#
+# So release.yml tags and creates the GitHub Release, and this is dispatched against
+# that tag. One more click, no secret and no change to the PyPI account. Adding
+# release.yml as a second trusted publisher on PyPI would remove the click; that is a
+# change only the account owner can make (#593).
 #
 # The version bump used to live here and committed straight to main (#586). Branch
 # protection refuses that now, and it should: the tag was created *before* the gates
@@ -12,10 +25,10 @@ on:
   release:
     types: [published]
 
-  workflow_call:
+  workflow_dispatch:
     inputs:
       ref:
-        description: "Tag or SHA to build from."
+        description: "Tag to build and publish, e.g. v0.7.0"
         required: true
         type: string
 

{kpubdata-0.7.0 → kpubdata-0.8.0}/.github/workflows/release.yml

@@ -102,6 +102,16 @@ jobs:
         with:
           version: ${{ steps.bump.outputs.new_version }}
 
+      # The release pull request carries its own CHANGELOG change: `[Unreleased]` becomes
+      # this version, dated. 0.7.0 shipped with its entries still under `[Unreleased]`
+      # because nothing did this. An empty `[Unreleased]` stops here, before a branch.
+      - name: Date the CHANGELOG section
+        if: ${{ !inputs.dry_run }}
+        uses: ./.github/actions/release-notes
+        with:
+          command: promote
+          version: ${{ steps.bump.outputs.new_version }}
+
       - name: Show what changed
         if: ${{ !inputs.dry_run }}
         run: git --no-pager diff --stat
@@ -204,6 +214,16 @@ jobs:
           fi
           echo "${TAG} is free"
 
+      # The notes are the CHANGELOG section, not a list of pull request titles. Taken
+      # before the gates so a missing or empty section stops the release while there
+      # is still nothing to clean up.
+      - name: Release notes from the CHANGELOG
+        id: notes
+        uses: ./.github/actions/release-notes
+        with:
+          command: extract
+          version: ${{ steps.tag.outputs.tag }}
+
       - name: Install dependencies
         run: uv sync --frozen --extra dev
 
@@ -225,18 +245,22 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git tag "${TAG}"
           git push origin "${TAG}"
-          gh release create "${TAG}" --title "${TAG}" --generate-notes \
+          gh release create "${TAG}" --title "${TAG}" \
+            --notes-file "${{ steps.notes.outputs.file }}" \
             --target "${{ steps.commit.outputs.sha }}"
 
-  publish:
-    name: Publish
+  # Publishing is not called from here. PyPI's trusted publisher matches the
+  # workflow GitHub started, so a reusable call made the certificate say
+  # `release.yml` and the upload was refused. publish-pypi.yml is dispatched against
+  # the tag this job created — see its header, and #593 for removing the extra step.
+  say-what-is-next:
+    name: Say what to do next
     needs: [release]
-    # A release created with GITHUB_TOKEN does not fire `release: published`, so the
-    # publish is called rather than waited for.
-    uses: ./.github/workflows/publish-pypi.yml
-    with:
-      ref: ${{ needs.release.outputs.tag }}
-    permissions:
-      contents: read
-      id-token: write
-    secrets: inherit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Next step
+        env:
+          TAG: ${{ needs.release.outputs.tag }}
+        run: |
+          echo "::notice::${TAG} is tagged and released. Publish it with:"
+          echo "::notice::  gh workflow run publish-pypi.yml -f ref=${TAG}"

kpubdata-0.8.0/.github/workflows/security.yml

@@ -0,0 +1,74 @@
+name: Security
+
+# Supply-chain checks (kpubdata-builder#691). Two questions, one job each:
+#
+#   dependency audit  does anything uv.lock installs have a known vulnerability?
+#   CodeQL            does the Python source have a known-dangerous pattern?
+#
+# They run on every pull request and push to main, and weekly, because a dependency
+# gains an advisory without anyone touching this repository. Neither gates merges yet:
+# whether a new advisory should block every open pull request is the owner's decision
+# left open in #631. The secret scan does gate merges — it runs in ci.yml under
+# `CI gate`, because a leaked credential is never acceptable to merge.
+#
+# Actions are pinned by commit SHA, the same SHAs kpubdata-builder uses.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 3 * * 1"  # Monday 03:17 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  dependency-audit:
+    name: Dependency audit (pip-audit, Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        # The lock resolves differently on each side of `python_full_version < '3.12'`
+        # (anyio, typing-extensions), and `uv export` keeps the markers, which pip-audit
+        # evaluates against the interpreter it runs on. Auditing on 3.10 and 3.12 covers
+        # both sides.
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4  # v10.1.0
+
+      # Every extra: an optional dependency is still installed by whoever asks for it.
+      # --no-deps: the export is already the full, pinned closure.
+      - name: Audit the locked dependencies
+        env:
+          PYTHON: ${{ matrix.python }}
+        run: |
+          uv export --frozen --no-hashes --no-emit-project --all-extras -o requirements.txt
+          uvx --python "${PYTHON}" pip-audit==2.10.1 -r requirements.txt --no-deps --disable-pip \
+            --progress-spinner off
+
+  codeql:
+    name: CodeQL (python)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2  # v4.38.2
+        with:
+          languages: python
+          build-mode: none
+      - uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2  # v4.38.2
+        with:
+          category: /language:python

kpubdata-0.8.0/.github/workflows/titles.yml

@@ -0,0 +1,135 @@
+# Titles carry the change type; the `type:*` label follows (POLICY 2.1.3).
+#
+#   pull_request   the title must be `type(scope): description`, or this check fails.
+#                  A squash merge turns the title into the commit, and the commit into
+#                  the CHANGELOG entry someone writes from it.
+#   issues         a valid title sets the matching `type:*` label and removes every other
+#                  `type:*` label, including `type:refactor` and `type:architecture` from
+#                  before POLICY 2.1.3, so an issue carries exactly one. An invalid one gets one comment saying what to change, which
+#                  is deleted once the title is fixed. Issues are never failed: the
+#                  person filing a bug should not see a red cross for it.
+#
+# Nobody sets `type:*` by hand. A label set by hand is a second place for the type to
+# live, and POLICY 2.1 says why that goes stale.
+name: Titles
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+  issues:
+    types: [opened, edited, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  pull-request:
+    name: PR title
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # The action is this repository's own, so it has to be checked out first. The
+      # other two repositories reference it remotely and need no checkout.
+      - uses: actions/checkout@v7
+
+      - name: Parse the title
+        id: title
+        uses: ./.github/actions/conventional-title
+        with:
+          title: ${{ github.event.pull_request.title }}
+
+      - name: The title must follow the convention
+        env:
+          VALID: ${{ steps.title.outputs.valid }}
+          ERROR: ${{ steps.title.outputs.error }}
+          LABEL: ${{ steps.title.outputs.label }}
+        run: |
+          if [ "${VALID}" != "true" ]; then
+            echo "::error::${ERROR}"
+            exit 1
+          fi
+          echo "title ok (${LABEL})"
+
+  issue:
+    name: Issue type label
+    # `edited` also fires for body edits. Only a title change can change the type.
+    if: >-
+      github.event_name == 'issues' &&
+      (github.event.action != 'edited' || github.event.changes.title != null)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      # The action is this repository's own, so it has to be checked out first. The
+      # other two repositories reference it remotely and need no checkout.
+      - uses: actions/checkout@v7
+
+      - name: Parse the title
+        id: title
+        uses: ./.github/actions/conventional-title
+        with:
+          title: ${{ github.event.issue.title }}
+
+      - name: Set the type label from the title
+        if: steps.title.outputs.valid == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+          LABEL: ${{ steps.title.outputs.label }}
+        run: |
+          # The four labels POLICY 2.1.3 derives. Created when missing, so a repository
+          # that never had `type:chore` does not fail here — no other label is made.
+          declare -A colour=(
+            [type:bug]=d73a4a [type:feature]=a2eeef [type:docs]=0075ca [type:chore]=cfd3d7
+          )
+          if ! gh label list --repo "${REPO}" --limit 200 --json name -q '.[].name' \
+              | grep -qxF "${LABEL}"; then
+            gh label create "${LABEL}" --repo "${REPO}" --color "${colour[$LABEL]}" \
+              --description "Set from the title prefix (POLICY 2.1.3). Do not set by hand."
+          fi
+
+          args=(--add-label "${LABEL}")
+          while IFS= read -r current; do
+            if [[ "${current}" == type:* ]] && [ "${current}" != "${LABEL}" ]; then
+              args+=(--remove-label "${current}")
+            fi
+          done < <(gh issue view "${NUMBER}" --repo "${REPO}" --json labels -q '.labels[].name')
+          gh issue edit "${NUMBER}" --repo "${REPO}" "${args[@]}"
+          echo "#${NUMBER} → ${LABEL}"
+
+      # One comment, found again by its marker: said once when the title is wrong,
+      # removed when it is right, so a fixed issue carries no stale advice.
+      - name: Say what the title needs, or take the note back
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+          VALID: ${{ steps.title.outputs.valid }}
+          ERROR: ${{ steps.title.outputs.error }}
+        run: |
+          # pipefail, and no `| head -1`: a failed `gh api` used to vanish behind the pipe
+          # and read as "no comment yet", which posted the note twice (#628).
+          set -euo pipefail
+          marker="<!-- title-check -->"
+          ids=$(gh api "repos/${REPO}/issues/${NUMBER}/comments" --paginate \
+            -q ".[] | select(.body | startswith(\"${marker}\")) | .id")
+          existing="${ids%%$'\n'*}"
+          if [ "${VALID}" = "true" ]; then
+            if [ -n "${existing}" ]; then
+              gh api -X DELETE "repos/${REPO}/issues/comments/${existing}"
+            fi
+            exit 0
+          fi
+          if [ -z "${existing}" ]; then
+            printf '%s\n' "${marker}" \
+              "이슈 제목은 \`type(scope): 설명\` 형식으로 씁니다 (POLICY 2.1.3)." \
+              "예: \`fix(localdata): empty wrapper becomes a phantom row\`" "" \
+              "> ${ERROR}" "" \
+              "제목을 고치면 \`type:*\` 라벨이 자동으로 붙고 이 댓글은 지워집니다." \
+              > "${RUNNER_TEMP}/comment.md"
+            gh issue comment "${NUMBER}" --repo "${REPO}" --body-file "${RUNNER_TEMP}/comment.md"
+          fi