Academic Research Suite

interface:
  display_name: "Academic Research Suite"
  short_description: "ARS workflows plus Claude-style ars-* aliases"
  brand_color: "#2563EB"
  default_prompt: "Use $academic-research-suite with ars-plan to map my paper structure and missing evidence."

policy:
  allow_implicit_invocation: true

# Shell scripts MUST stay LF, even on Windows checkouts. The PreToolUse hook launcher
# (hooks/run_guard.sh) and the SessionStart announce hook (scripts/announce-ars-loaded.sh)
# are executed via Git Bash on Windows; a CRLF checkout would break them on the hot path
# (#454). Scope the rule to *.sh so existing line-ending behavior for other files is
# untouched.
*.sh text eol=lf

buy_me_a_coffee: crucify020v

name: Defer Label Gate

# Block a tag push if any issue labelled `defer:<this-tag>` remains open.
#
# Why: v3.7.1 spec MERGED 2026-05-07 but impl never started — overtaken
# by v3.7.3 then v3.8. Deferred items accumulate without a forcing
# function. This gate enforces "before tagging vX.Y.Z, all
# `defer:vX.Y.Z` issues must be closed (or relabelled to a later version)."
#
# Convention: label format is `defer:vMAJOR.MINOR.PATCH` (lowercase, with v).
# Example: `defer:v3.10` blocks the v3.10 tag.
#
# Override: include [skip-defer-check] in the tagged commit message.

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: read
  issues: read

jobs:
  defer-check:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Check defer label
        env:
          GH_TOKEN: ${{ github.token }}
          NEW_TAG: ${{ github.ref_name }}
        run: |
          set -euo pipefail

          # Normalize tag -> defer label. v3.9.4.1 -> defer:v3.9.4.1
          LABEL="defer:${NEW_TAG}"
          echo "Checking label: $LABEL"

          # Override
          TAG_BODY=$(git log -1 --format=%B "$NEW_TAG")
          if echo "$TAG_BODY" | grep -qF '[skip-defer-check]'; then
            echo "Override [skip-defer-check] present — defer gate bypassed."
            exit 0
          fi

          # Fetch open issues with this label
          COUNT=$(gh issue list \
            --label "$LABEL" \
            --state open \
            --json number \
            --jq 'length')

          echo "Open issues with label '$LABEL': $COUNT"

          if [ "$COUNT" -gt 0 ]; then
            echo "::error::$COUNT issue(s) labelled '$LABEL' are still open."
            echo "::error::Close them, relabel to a later version, or add [skip-defer-check] + justification."
            echo ""
            echo "Open issues:"
            gh issue list --label "$LABEL" --state open
            exit 1
          fi

          echo "No open defer issues for $NEW_TAG."

name: Eval Harness

# #184 Delta 3 — fire the multi-task eval harness on PRs (and main pushes) that
# touch scoring / generation logic or the gold sets themselves. Posts a markdown
# comment with the run metrics and blocks on un-acknowledged regressions.

on:
  pull_request:
    paths:
      # Delta 3 path filter — resolver clients + verification surfaces -> citation_extraction
      - "scripts/verification_gate/**"
      - "scripts/arxiv_client.py"
      - "scripts/verification_cache.py"
      - "scripts/crossref_client.py"
      - "scripts/openalex_client.py"
      - "scripts/citation_verification_summary.py"
      - "scripts/claim_audit_*.py"
      # epistemic-status surfaces -> status_classification + summarization_adequacy (Phase 2)
      - "scripts/epistemic_status_extractor.py"
      - "scripts/check_silent_upgrade.py"
      - "shared/references/epistemic_status_vocabulary.md"
      # writer prompts governing prose register -> status_classification + summarization_adequacy
      - "deep-research/agents/synthesis_agent.md"
      - "academic-paper/agents/draft_writer_agent.md"
      - "deep-research/agents/report_compiler_agent.md"
      # rq_framing_patterns scoring runner -> the harness dispatches to it, so
      # changes there must re-run the eval harness (else RQ scoring can drift
      # without the gate noticing).
      - "scripts/check_rq_framing_patterns.py"
      # the harness itself + gold sets
      - "evals/gold/**"
      - "scripts/run_evals.py"
      - "scripts/check_ranking_lift.py"
      - "shared/evals_lift_report.schema.json"
      - ".github/workflows/eval-harness.yml"
  push:
    branches: [main]
    paths:
      - "scripts/verification_gate/**"
      - "scripts/arxiv_client.py"
      - "scripts/verification_cache.py"
      - "scripts/crossref_client.py"
      - "scripts/openalex_client.py"
      - "scripts/citation_verification_summary.py"
      - "scripts/claim_audit_*.py"
      - "scripts/epistemic_status_extractor.py"
      - "scripts/check_silent_upgrade.py"
      - "shared/references/epistemic_status_vocabulary.md"
      - "deep-research/agents/synthesis_agent.md"
      - "academic-paper/agents/draft_writer_agent.md"
      - "deep-research/agents/report_compiler_agent.md"
      - "scripts/check_rq_framing_patterns.py"
      - "evals/gold/**"
      - "scripts/run_evals.py"
      - "scripts/check_ranking_lift.py"
      - "shared/evals_lift_report.schema.json"
      - ".github/workflows/eval-harness.yml"

concurrency:
  # House invariant: include github.event_name so push and pull_request runs on
  # the same ref do not fight over one group (avoids spurious cancelled-run
  # failure emails).
  group: eval-harness-${{ github.ref }}-${{ github.event_name }}
  cancel-in-progress: true

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  eval-harness:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: pip
          cache-dependency-path: requirements-dev.txt

      - name: Install dependencies
        run: pip install -r requirements-dev.txt pytest

      - name: Run eval harness (Phase-2 tasks auto-skipped by discovery)
        id: run
        env:
          PYTHONPATH: .
        run: |
          set -euo pipefail
          # run_evals discovers only present manifests, so Phase-2 gold sets that
          # have not landed (status_classification / summarization_adequacy) are
          # simply absent from the run — no separate skip-guard needed.
          report="eval_report.json"
          python -m scripts.run_evals --output "$report"
          # Absolute-threshold verdict (no exit here): which measured tasks failed
          # their aggregate threshold. Phase 1b has no main baseline, so this is an
          # ABSOLUTE gate, not a lift comparison. Logic lives in a unit-tested
          # module (scripts/_eval_threshold_gate.py), not an inline heredoc.
          failed=$(python -m scripts._eval_threshold_gate "$report")
          echo "failed_tasks=${failed}" >> "$GITHUB_OUTPUT"
          if [ -n "$failed" ]; then
            echo "::notice title=Eval below threshold::${failed}"
          fi
          {
            echo "## Eval harness results"
            echo ""
            echo '```json'
            cat "$report"
            echo '```'
          } > eval_comment.md

      - name: Post PR comment
        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('eval_comment.md', 'utf8');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body,
            });

      - name: Eval gate (absolute threshold + ack contract)
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_BODY: ${{ github.event.pull_request.body }}
          FAILED_TASKS: ${{ steps.run.outputs.failed_tasks }}
        run: |
          set -euo pipefail
          # Single integrated gate. Phase 1b has no main baseline, so this gate is
          # honestly ABSOLUTE-threshold only (the lift gate proper,
          # scripts/check_ranking_lift.py, activates once a baseline exists).
          #   - no failed task                                    -> pass
          #   - failed + [eval-regression-acknowledged] + >=1
          #     OPEN issue URL in THIS repo                       -> pass (noted)
          #   - failed + no valid ack                             -> ::error:: + fail
          failed="${FAILED_TASKS:-}"
          if [ -z "$failed" ]; then
            echo "All measured tasks meet their absolute threshold; gate passes."
            exit 0
          fi

          body="${PR_BODY:-}"
          if ! printf '%s' "$body" | grep -q '\[eval-regression-acknowledged\]'; then
            echo "::error::tasks below threshold (${failed}) but PR body lacks [eval-regression-acknowledged]."
            exit 1
          fi

          # Accept only issue URLs that point at THIS repo (owner/name), then
          # require >=1 of them to be OPEN. A foreign repo's issue does not count.
          repo="${GITHUB_REPOSITORY}"
          # Escape the literal dot in github.com and bound the issue number on
          # the right so 'github.com' is not a wildcard and a trailing path
          # segment cannot smuggle extra digits. ${repo} has no regex metachars.
          urls=$(printf '%s' "$body" \
            | grep -oE "https://github\.com/${repo}/issues/[0-9]+([^0-9]|$)" \
            | grep -oE "https://github\.com/${repo}/issues/[0-9]+" || true)
          if [ -z "$urls" ]; then
            echo "::error::[eval-regression-acknowledged] present but no ${repo} issue URL found."
            exit 1
          fi
          open_found=0
          while IFS= read -r url; do
            [ -z "$url" ] && continue
            num="${url##*/}"
            state=$(gh api "/repos/${repo}/issues/${num}" --jq '.state' 2>/dev/null || echo "missing")
            if [ "$state" = "open" ]; then
              open_found=1
            fi
          done <<< "$urls"
          if [ "$open_found" -ne 1 ]; then
            echo "::error::no OPEN ${repo} tracking issue among the declared URL(s)."
            exit 1
          fi
          echo "Below-threshold tasks acknowledged with >=1 OPEN same-repo issue; gate satisfied."

name: PRISMA-trAIce Freshness

on:
  schedule:
    # Monday 09:00 UTC (17:00 Taipei) — weekly upstream drift check
    - cron: "0 9 * * 1"
  push:
    paths:
      - "shared/prisma_trAIce_protocol.md"
      - "scripts/check_prisma_trAIce_freshness.py"
  workflow_dispatch:

concurrency:
  group: freshness-check-${{ github.ref }}
  cancel-in-progress: true

jobs:
  freshness:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"
          cache: pip
          cache-dependency-path: requirements-dev.txt

      - name: Install lint dependencies
        run: pip install -r requirements-dev.txt

      - name: Run freshness check (non-blocking)
        env:
          PYTHONPATH: .
        run: python3 scripts/check_prisma_trAIce_freshness.py
        # Stale snapshot surfaces a warning on stderr but exits 0. A
        # non-zero exit means a parse error (missing/malformed
        # snapshot_date), which SHOULD fail the workflow.

name: Harness Retirement (Monthly)

# Monthly audit for obsolete scaffolding in agent prompts. Opens a
# tracking issue with the audit report so retirement work can be
# scheduled rather than forgotten.
#
# Why: 5 days, 9 tags accumulated prompt-level workarounds. The
# harness-retirement skill exists but hasn't been run against ARS
# itself. Running monthly via cron prevents prompt debt from
# silently compounding.
#
# The skill is loaded locally (~/.claude/...), so this workflow
# can't invoke it directly on a GHA runner. Instead it opens an
# issue with a checklist the user can run locally with
# `/harness-retirement` and paste results into.

on:
  schedule:
    # 06:00 UTC on the 1st = 14:00 Asia/Taipei
    - cron: '0 6 1 * *'
  workflow_dispatch:

permissions:
  contents: read
  issues: write

jobs:
  open-audit-issue:
    runs-on: ubuntu-latest
    steps:
      - name: Compute month label
        id: month
        run: |
          M=$(date -u +%Y-%m)
          echo "label=$M" >> "$GITHUB_OUTPUT"

      - name: Open audit tracking issue
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          MONTH: ${{ steps.month.outputs.label }}
        run: |
          set -euo pipefail
          {
            echo "## Harness retirement audit — ${MONTH}"
            echo ""
            echo "Run \`/harness-retirement\` locally against ARS agents and paste the report below."
            echo ""
            echo "### Scope"
            echo ""
            echo "All 22 Bucket A agents under v3.9.2 prompt hard fence:"
            echo ""
            echo "- deep-research (×9): research_question / research_architect / bibliography / source_verification / synthesis / editor_in_chief / ethics_review / risk_of_bias / meta_analysis"
            echo "- academic-paper (×7): literature_strategist / structure_architect / draft_writer / citation_compliance / abstract_bilingual / peer_reviewer / formatter"
            echo "- academic-paper-reviewer (×6): eic / methodology / domain / perspective / devils_advocate_reviewer / editorial_synthesizer"
            echo ""
            echo "### Six debt categories"
            echo ""
            echo "- [ ] **Sonnet 3.x workarounds** — explicit JSON-mode coercion, redundant role priming"
            echo "- [ ] **Pre-tool-use scaffolds** — manual schema validation that current models do natively"
            echo "- [ ] **Verbose chain-of-thought prompts** — opus 4.7 handles structured reasoning without templates"
            echo "- [ ] **Defensive few-shot examples** — examples added for model limitations now fixed"
            echo "- [ ] **Format guards** — duplicated 'return ONLY JSON' across agents"
            echo "- [ ] **Deprecated tool references** — tool names / signatures from older Claude Code versions"
            echo ""
            echo "### Output checklist"
            echo ""
            echo "- [ ] Audit report posted as comment"
            echo "- [ ] P0 retirements scheduled (open separate issues with \`harness-retirement\` label)"
            echo "- [ ] P1 retirements logged in CHANGELOG [Unreleased]"
            echo "- [ ] P2+ added to backlog"
            echo ""
            echo "---"
            echo "_Auto-opened by harness-retirement-monthly.yml. Close once audit complete._"
          } > issue-body.md

          gh issue create \
            --title "harness-retirement audit ${MONTH}" \
            --label "harness-retirement" \
            --body-file issue-body.md

name: PR Closes-Issue Check

# Require every PR targeting main to reference at least one issue via
# the GitHub auto-close keywords. Aligns 99 PR / 43 issue asymmetry —
# every change should be traceable to a stated problem.
#
# Accepted keywords (case-insensitive, must use #N format):
#   Closes #N, Close #N, Closed #N
#   Fixes #N, Fix #N, Fixed #N
#   Resolves #N, Resolve #N, Resolved #N
#
# Per feedback_github_pr_close_issue_keywords: keyword must be
# immediately followed by #N (no intervening words), otherwise GitHub
# auto-close does not fire.
#
# Override: include [skip-closes-check] in PR body with justification.

on:
  pull_request:
    types: [opened, edited, synchronize, reopened, ready_for_review]
    branches: [main]

concurrency:
  group: pr-closes-issue-${{ github.event.pull_request.number }}-${{ github.event_name }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: read

jobs:
  closes-check:
    runs-on: ubuntu-latest
    steps:
      - name: Validate PR body
        env:
          PR_BODY: ${{ github.event.pull_request.body }}
        run: |
          set -euo pipefail

          if [ -z "${PR_BODY:-}" ]; then
            echo "::error::PR body is empty. Add a 'Closes #N' reference (or [skip-closes-check] with justification)."
            exit 1
          fi

          if echo "$PR_BODY" | grep -qF '[skip-closes-check]'; then
            echo "Override [skip-closes-check] present — skipping."
            exit 0
          fi

          # Strict GitHub auto-close pattern: keyword + space + #N (no intervening tokens)
          PATTERN='(^|[^a-zA-Z])(Clos(e|es|ed)|Fix(es|ed)?|Resolv(e|es|ed))[[:space:]]+#[0-9]+'
          if echo "$PR_BODY" | grep -qiE "$PATTERN"; then
            echo "Found valid closes-issue reference."
            echo "$PR_BODY" | grep -iE "$PATTERN" | head -5
            exit 0
          fi

          echo "::error::PR body must contain a GitHub auto-close keyword followed by #N."
          echo "::error::Examples: 'Closes #134', 'Fixes #138', 'Resolves #102'"
          echo "::error::Bypass: add [skip-closes-check] + justification to the PR body."
          exit 1

name: pytest

on:
  pull_request:
    paths:
      - 'scripts/**'
      - 'tests/**'
      - 'shared/contracts/**'
      - 'conftest.py'
      - 'pyproject.toml'
      - 'requirements-dev.txt'
      - '.github/workflows/pytest.yml'
      - 'academic-pipeline/references/adapters/**'
      - 'academic-pipeline/references/literature_corpus_consumers.md'
      - 'deep-research/agents/bibliography_agent.md'
  push:
    branches: [main]
    paths:
      - 'scripts/**'
      - 'tests/**'
      - 'shared/contracts/**'
      - 'conftest.py'
      - 'pyproject.toml'
      - 'requirements-dev.txt'
      - '.github/workflows/pytest.yml'
      - 'academic-pipeline/references/adapters/**'
      - 'academic-pipeline/references/literature_corpus_consumers.md'
      - 'deep-research/agents/bibliography_agent.md'

concurrency:
  # Suffix by event_name so push (branches: [main]) and pull_request
  # events don't fight over the same group on the rare case both fire.
  group: pytest-${{ github.ref }}-${{ github.event_name }}
  cancel-in-progress: true

jobs:
  pytest:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip
          cache-dependency-path: requirements-dev.txt

      - name: Install deps
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt pytest

      - name: Run test suite
        env:
          PYTHONPATH: .
          # actions/checkout does not set origin/HEAD, so the v3.6.8
          # pattern-protection lint cannot resolve the default branch via
          # `git symbolic-ref`. Provide its documented env fallback.
          GITHUB_DEFAULT_BRANCH: main
        run: pytest scripts/ tests/

name: Release Cooldown

# Block consecutive minor/patch tags within 24h of a hotfix tag.
#
# Why: v3.9.4 -> v3.9.4.1 (6hr) was a structural symptom — ship velocity
# overran review chain. This gate enforces a 24h cooldown after any tag
# whose name or annotated message indicates a hotfix, so the next release
# requires either elapsed time or an explicit override.
#
# Override: include the literal token [skip-cooldown] in the commit message
# the new tag points to, with a justification on the next line.

on:
  push:
    tags:
      - 'v*'

concurrency:
  group: release-cooldown-${{ github.ref }}-${{ github.event_name }}
  cancel-in-progress: false

jobs:
  cooldown-check:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          fetch-tags: true

      - name: Evaluate cooldown window
        env:
          NEW_TAG: ${{ github.ref_name }}
        run: |
          set -euo pipefail

          echo "New tag: $NEW_TAG"

          # Find previous release tag (v*, by creator date, exclude current).
          # Filtering to v* avoids non-release tags (e.g., test, internal markers)
          # being picked as PREV_TAG and bypassing the cooldown classification.
          PREV_TAG=$(git tag -l 'v*' --sort=-creatordate | grep -v "^${NEW_TAG}$" | head -1 || true)
          if [ -z "$PREV_TAG" ]; then
            echo "No previous release tag — first release, skip cooldown."
            exit 0
          fi
          echo "Previous tag: $PREV_TAG"

          # Was the previous tag a hotfix?
          # Three signals (any one is sufficient):
          #   a) Tag name has 4 dot-segments (e.g., v3.9.4.1)
          #   b) Pointed commit subject matches hotfix pattern
          #   c) Annotated tag subject (if any) matches hotfix pattern
          # The regex accepts both 'hotfix' and 'hot-fix' spellings.
          PREV_COMMIT_SUBJECT=$(git log -1 --format=%s "$PREV_TAG")
          PREV_TAG_SUBJECT=$(git for-each-ref "refs/tags/${PREV_TAG}" --format='%(subject)')
          HOTFIX_REGEX='(hot-?fix|post-ship|^fix\(v)'
          IS_HOTFIX="false"
          if [[ "$PREV_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
            IS_HOTFIX="true"
          fi
          if echo "$PREV_COMMIT_SUBJECT" | grep -qiE "$HOTFIX_REGEX"; then
            IS_HOTFIX="true"
          fi
          if [ -n "$PREV_TAG_SUBJECT" ] && echo "$PREV_TAG_SUBJECT" | grep -qiE "$HOTFIX_REGEX"; then
            IS_HOTFIX="true"
          fi
          echo "Previous tag classified as hotfix: $IS_HOTFIX"

          if [ "$IS_HOTFIX" != "true" ]; then
            echo "Previous tag was not a hotfix — no cooldown required."
            exit 0
          fi

          # Compute elapsed hours
          PREV_TS=$(git log -1 --format=%ct "$PREV_TAG")
          NEW_TS=$(git log -1 --format=%ct "$NEW_TAG")
          ELAPSED_S=$((NEW_TS - PREV_TS))
          ELAPSED_H=$((ELAPSED_S / 3600))
          echo "Elapsed since previous hotfix tag: ${ELAPSED_H}h"

          # Override check — accept [skip-cooldown] token in either the pointed
          # commit message OR the annotated tag message. Symmetry with hotfix
          # detection (which reads both sources): for squash-merged hotfix PRs
          # the commit message is fixed at merge time, so the only place the
          # tagger can add the override is the tag annotation. Reading both
          # avoids forcing a follow-up commit just to carry the override token.
          NEW_COMMIT_BODY=$(git log -1 --format=%B "$NEW_TAG")
          NEW_TAG_BODY=$(git for-each-ref "refs/tags/${NEW_TAG}" --format='%(contents)')
          OVERRIDE_SOURCE=""
          OVERRIDE_BODY=""
          if echo "$NEW_COMMIT_BODY" | grep -qF '[skip-cooldown]'; then
            OVERRIDE_SOURCE="commit message"
            OVERRIDE_BODY="$NEW_COMMIT_BODY"
          elif [ -n "$NEW_TAG_BODY" ] && echo "$NEW_TAG_BODY" | grep -qF '[skip-cooldown]'; then
            OVERRIDE_SOURCE="annotated tag message"
            OVERRIDE_BODY="$NEW_TAG_BODY"
          fi
          if [ -n "$OVERRIDE_SOURCE" ]; then
            echo "Override token [skip-cooldown] present in ${OVERRIDE_SOURCE} — cooldown bypassed."
            echo "Justification (next non-empty line):"
            echo "$OVERRIDE_BODY" | awk '/\[skip-cooldown\]/{found=1; next} found && NF{print; exit}'
            exit 0
          fi

          if [ "$ELAPSED_H" -lt 24 ]; then
            echo "::error::Cooldown violation — previous hotfix tag $PREV_TAG was ${ELAPSED_H}h ago (<24h)."
            echo "::error::Either wait until $((24 - ELAPSED_H))h have passed, or add [skip-cooldown] + justification to the tagged commit."
            exit 1
          fi

          echo "Cooldown satisfied (${ELAPSED_H}h >= 24h)."

# Repository hygiene scan (#151): gitleaks over the full git history with
# the upstream default ruleset. Catches accidentally committed credentials
# (API keys, tokens, private-key blocks, high-entropy secrets) before they
# reach main. What it detects is documented at the level of the upstream
# tool's docs — https://github.com/gitleaks/gitleaks — no repo-specific
# rules; the only local configuration is the false-positive allowlist in
# .gitleaks.toml (citation keys misread as generic-api-key).
#
# The binary is version-pinned and checksum-verified rather than pulled via
# a marketplace action: gitleaks-action requires a license key for org
# accounts, and a pinned release binary keeps the supply chain auditable.

name: repository-hygiene

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: repository-hygiene-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  gitleaks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          # Full history: the scan covers every commit, not just the PR diff,
          # so a secret buried in an intermediate commit cannot slip through.
          fetch-depth: 0

      - name: Run gitleaks (pinned, checksum-verified)
        env:
          GITLEAKS_VERSION: "8.30.1"
          GITLEAKS_SHA256: "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb"
        run: |
          set -euo pipefail
          curl -sSfL \
            "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" \
            -o /tmp/gitleaks.tgz
          echo "${GITLEAKS_SHA256}  /tmp/gitleaks.tgz" | sha256sum --check --strict
          tar -xzf /tmp/gitleaks.tgz -C /tmp gitleaks
          # --redact keeps any genuine hit out of public CI logs.
          /tmp/gitleaks detect --source . --config .gitleaks.toml --no-banner --redact --exit-code 1

name: Spec Consistency

on:
  push:
  pull_request:

concurrency:
  # Suffix by event_name so push and pull_request events on the same ref
  # don't fight over the same group. Without the suffix, GHA cancels one
  # of the two — usually leaving the cancelled run in a `failure` / stuck
  # `queued` state that triggers GitHub failure-notification emails to
  # subscribers even though the latest push event run actually succeeded.
  group: spec-consistency-${{ github.ref }}-${{ github.event_name }}
  cancel-in-progress: true

jobs:
  spec-consistency:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          # v3.7.1 byte-equivalence SHA gate derives the v3.6.7 base commit
          # via `git log -1 -- scripts/v3_6_7_inversion_manifest.json`. A
          # shallow clone (default fetch-depth: 1) would render that lookup
          # vacuous. Deepening the clone here lets the lint hash the base
          # block directly without falling back to `git fetch --unshallow`.
          # Spec: 2026-04-30-ars-v3.6.8-trust-provenance-and-drift-transparency-spec.md § Step 0 (round-6 R6-002 + round-7 R7-001).
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.x"
          cache: pip
          cache-dependency-path: requirements-dev.txt

      - name: Install lint dependencies
        # pytest is installed once here so the unified manifest runner (#156)
        # and the legacy `python3 -m unittest scripts.test_*` steps share one
        # pip install. Previously each pytest step did its own `pip install
        # pytest [pyyaml] [jsonschema]`; consolidating saves ~12 redundant
        # installs per workflow run.
        run: pip install -r requirements-dev.txt pytest

      - name: Run spec consistency check
        run: python3 scripts/check_spec_consistency.py

      - name: Lint CI pytest manifest (#156)
        # Drift guard for scripts/_ci_pytest_manifest.toml — verifies entry
        # path existence, id/(path,args) uniqueness, args shape, and that
        # spec-consistency.yml contains no direct `pytest scripts/test_*.py`
        # outside the runner. Runs before the runner so a malformed manifest
        # fails fast.
        run: python3 scripts/check_ci_pytest_manifest.py

      - name: Ensure jq is available (#349)
        # The cross-model grounding-guard tests (run via the manifest below) shell out to `jq`
        # to exercise the canonical .jq filters and REQUIRE it (they fail clearly rather than
        # skip — a skipped safety test reads as covered). jq is preinstalled on ubuntu-latest,
        # but make the dependency explicit so a runner-image change can't silently break it.
        run: |
          if ! command -v jq >/dev/null 2>&1; then
            sudo apt-get update && sudo apt-get install -y jq
          fi
          jq --version

      - name: Run CI pytest manifest (#156)
        # Single entry point for the pytest invocations spec-consistency.yml used
        # to run file-by-file. Each manifest entry is wrapped in a
        # `::group::<id>` annotation so the GitHub UI collapses one block
        # per invocation. Manifest at scripts/_ci_pytest_manifest.toml.
        env:
          PYTHONPATH: .
        run: python3 scripts/run_ci_pytest_manifest.py

      - name: Check PREPRINT_VENUES list consistency (#105)
        run: python3 scripts/check_preprint_venues_consistency.py

      - name: Run #105 migration unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_contamination_signals scripts.test_migrate_literature_corpus_to_v3_7_3 scripts.test_semantic_scholar_client -v

      - name: Check data_access_level declarations
        env:
          PYTHONPATH: scripts
        run: python3 scripts/check_data_access_level.py

      - name: Check instruction-vs-data boundary (#272 guidance layer)
        # Drift guard for the retrieved-content instruction/data principle:
        # authoritative canonical block in ground_truth_isolation_pattern.md +
        # verbatim-inlined copies in the two hot-spot retrieval agents + backpoints.
        # The mutation test (272-instruction-data-boundary-mutation) runs via the
        # pytest manifest above. Commit-time documentation check only — not a
        # runtime gate (see docs/design/2026-06-07-272-...-design.md § 3/§ 5).
        run: python3 scripts/check_instruction_data_boundary.py

      - name: Check task_type declarations
        env:
          PYTHONPATH: scripts
        run: python3 scripts/check_task_type.py

      - name: Run compliance validator + fixture unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_compliance_report scripts.test_validate_compliance_fixtures -v

      - name: Check collaboration depth rubric + observer contract
        env:
          PYTHONPATH: scripts
        run: python3 scripts/check_collaboration_depth_rubric.py

      - name: Run collaboration depth rubric unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_collaboration_depth_rubric -v

      - name: Check rubric weight consistency (quality_rubrics / framework / SKILL rule 14)
        run: python3 scripts/check_rubric_weight_consistency.py

      - name: Check citation-verification intake wiring (#392)
        run: python3 scripts/check_392_citation_verification_intake.py

      - name: Check agents/ mirror sync (#413)
        # The pytest companion `test_check_agents_mirror_sync.py` runs via the
        # unified manifest.
        run: python3 scripts/check_agents_mirror_sync.py

      - name: Check revision-patch discipline (#390 Slice B)
        # The pytest companion `test_check_390_revision_patch_discipline.py`
        # runs via the unified manifest.
        run: python3 scripts/check_390_revision_patch_discipline.py

      - name: Check version consistency (CLAUDE.md / SKILL.md / CHANGELOG)
        env:
          PYTHONPATH: scripts
        run: python3 scripts/check_version_consistency.py

      - name: Run version consistency unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_version_consistency -v

      - name: Run spec consistency unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_spec_consistency -v

      - name: Run check_sprint_contract unit tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_sprint_contract -v

      - name: Validate sprint contract templates
        shell: bash
        run: |
          set -euo pipefail
          shopt -s globstar nullglob
          # Widened from 3-segment to N-segment so 4+ segment hotfix entries
          # (e.g. ## [3.9.4.2]) match without falling through to a predecessor.
          # Same defect class as #169 (closed by PR #173).
          ARS_VERSION=$(grep -m1 -oE '## \[[0-9]+(\.[0-9]+)+\]' CHANGELOG.md | grep -oE '[0-9]+(\.[0-9]+)+' || true)
          if [[ -z "$ARS_VERSION" ]]; then
            echo "ERROR: could not extract ARS version from CHANGELOG.md (need '## [X.Y.Z]' heading)" >&2
            exit 1
          fi
          for f in shared/contracts/reviewer/*.json; do
            python3 scripts/check_sprint_contract.py "$f" --ars-version "v${ARS_VERSION}"
          done
          # v3.6.6: writer + evaluator template validation loops mirror reviewer loop above.
          for f in shared/contracts/writer/*.json; do
            python3 scripts/check_sprint_contract.py "$f" --ars-version "v${ARS_VERSION}"
          done
          for f in shared/contracts/evaluator/*.json; do
            python3 scripts/check_sprint_contract.py "$f" --ars-version "v${ARS_VERSION}"
          done

      - name: Validate v3.6.6 A/B fixture manifest
        run: python3 scripts/check_v3_6_6_ab_manifest.py

      - name: Validate literature_corpus schemas and examples
        run: python3 scripts/check_literature_corpus_schema.py

      - name: Validate corpus consumer protocol (v3.6.5+)
        run: python3 scripts/check_corpus_consumer_protocol.py

      - name: Validate experiment_provenance[] example shape (#260)
        # Standalone shape gate (mirrors the non-CI check_repro_lock.py family):
        # asserts the shipped example's experiment_provenance[] entries are
        # well-formed against experiment_provenance_entry.schema.json so the
        # example cannot rot. Cross-array EP/EA invariants + the repro_lock drift
        # guard are covered by scripts.test_experiment_provenance +
        # scripts.test_repro_lock_validation_drift (run below + via pytest).
        run: python3 scripts/check_experiment_provenance.py examples/passport_with_experiment_provenance.yaml

      - name: Run #260 experiment-provenance + repro_lock drift tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_experiment_provenance scripts.test_repro_lock_validation_drift -v

      - name: Validate domain evidence profile documentation surface (#259)
        run: python3 scripts/check_domain_evidence_profile.py

      - name: Check adapter docs up-to-date
        run: python3 scripts/sync_adapter_docs.py --check

      - name: Validate passport reset contract
        run: python3 scripts/check_passport_reset_contract.py --root .

      - name: Run passport reset contract tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_passport_reset_contract -v

      - name: Validate v3.6.7 downstream-agent pattern protection
        run: python3 scripts/check_v3_6_7_pattern_protection.py

      - name: Run v3.6.7 pattern-protection mutation tests
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_v3_6_7_pattern_protection -v

      - name: Validate v3.7.1 byte-equivalence SHA gate (v3.6.7 boundary)
        # v3.7.1 work must NOT mutate v3.6.7-tagged PATTERN PROTECTION blocks.
        # This lint hashes each block at PR HEAD and at the v3.6.7 base commit
        # (derived via `git log -1 -- scripts/v3_6_7_inversion_manifest.json`)
        # and asserts equality. Requires fetch-depth: 0 on the checkout step.
        run: python3 scripts/check_v3_6_8_pattern_protection.py

      - name: Validate v3.7.1 trust-chain frontmatter schema
        # Step 1 of v3.7.1: enforces three firm rules from spec §3.1
        # (verified⇒acquired+method, not-acquired⇒no-real-audit-round, no
        # literal human_read_*) across literature_corpus[] entries.
        run: python3 scripts/check_v3_6_8_frontmatter_trust_schema.py

      - name: Validate v3.7.1 audit Scope Report block (Step 2 / D2)
        # Step 2 of v3.7.1: enforces spec §3.2 Scope Report contract on the
        # cross-model audit prompt template — Section 0 header + four required
        # content fields + three aggregate-status splits + forbidden
        # combined-aggregate "PASSED" verb (spec line 152).
        run: python3 scripts/check_v3_6_8_audit_scope_block.py

      - name: Validate v3.7.1 Cite-Time Provenance Finalizer (Step 3b)
        # Step 3b of v3.7.1: enforces spec §3.3 4-cell matrix + §3.6 peer-file
        # join + idempotency + revision-loop preservation on the
        # `## Cite-Time Provenance Finalizer (v3.7.1)` subsection of
        # academic-pipeline/agents/pipeline_orchestrator_agent.md.
        run: python3 scripts/check_v3_6_8_cite_provenance_pipeline.py

      - name: Validate v3.6.8 /ars-mark-read plugin commands (#190)
        # Step 7 of v3.6.8: enforces the 2 commands (mark-read, unmark-read)
        # exist, carry the literature_corpus[] validation reference, point at
        # the human_read_log.yaml peer file (NOT entry frontmatter per §3.1
        # firm rule 3), and declare model: sonnet routing.
        run: python3 scripts/check_v3_6_8_mark_read_commands.py

      - name: Run v3.6.8 /ars-mark-read CLI tests (#190)
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_ars_mark_read scripts.test_check_v3_6_8_mark_read_commands -v

      - name: v3.9.0 cross-index triangulation lint
        # §3.8 rules 5-6 (R3 P2 closure): verifies formatter pass-through
        # allowlist equals the canonical 9-suffix set (exact-token extraction
        # from backtick spans, not substring matching) and that refusal rules
        # 1-10 contain no CONTAMINATED-* tokens (R-L3-2-E invariant).
        # The pytest companion `test_check_v3_9_0_triangulation.py` runs via
        # the unified manifest (#156).
        env:
          PYTHONPATH: .
        run: python scripts/check_v3_9_0_triangulation.py

      - name: Firm-rules sync + ID-collision lint (v3.10 PR-A, #127)
        # Pins the canonical R-L3-2-* (contamination) / R-CIM-* (claim-manifest)
        # firm-rule wording in shared/references/firm_rules.md against the agent
        # prompt mirrors, and guards the v3.10 PR-A disambiguation (the two rule
        # families no longer share the R-L3-2-A/B/C ID). v3.10 PR-B adds a
        # contradiction guard on the contamination mirrors (no unqualified
        # "advisory only / never block" claim once strict can block). The pytest
        # companion `test_check_firm_rules_sync.py` runs via the unified manifest.
        env:
          PYTHONPATH: .
        run: python scripts/check_firm_rules_sync.py

      - name: Judge-prompt-version drift guard (#361)
        # Recomputes the SHA-256 of the canonical judge-prompt section (between
        # the JUDGE-PROMPT-CANONICAL markers in claim_ref_alignment_audit_agent.md)
        # and fails if it drifts from JUDGE_PROMPT_SHA256 in _claim_audit_constants.py.
        # Forces a prompt edit to re-pin the hash + bump JUDGE_PROMPT_VERSION, so a
        # judge-prompt change cannot silently leave stale judge-cache entries valid.
        # The pytest companion `test_check_judge_prompt_version.py` runs via the
        # unified manifest.
        env:
          PYTHONPATH: .
        run: python scripts/check_judge_prompt_version.py

      - name: v3.10 policy-layer lint (#127 PR-B)
        # Verifies the v3.10 terminal-policy-layer contract: venue_type /
        # venue_type_provenance / venue_type_source schema fields (incl. the
        # explicit `unknown` member + no `_inferred` provenance), the pair
        # dependency branches, the trusted_source laundering guard, the standalone
        # terminal_policies schema home (Inv. 11), the marker grammar (severity=
        # HIGH-BLOCK only inside <!--ref-->, two shapes, policy_hash stamp), the
        # generic formatter rule 11 + STAMP-ONLY two-gate, and temporal_integrity
        # accepting only `advisory` (Inv. 3). Runs ALONGSIDE the v3.9.0 lint, not a
        # rename. The pytest companion `test_check_v3_10_policy.py` runs via the
        # unified manifest.
        env:
          PYTHONPATH: .
        run: python scripts/check_v3_10_policy.py

      - name: "#394 slice-4 submission-policy lint"
        # Verifies the submission-package terminality contract: the
        # terminal_policies submission_package enum {advisory, strict} with no
        # JSON-Schema default, the orchestrator Submission-Package Terminal
        # Gate section's load-bearing literals (fix-loop bound, VERIFICATION-
        # INCOMPLETE, --check-freshness, sole-reader + gate-on-tokens
        # sentences), the formatter Submission Package Advisories section,
        # the AST single-homed guard (the verifier never READS
        # terminal_policies — docstring mentions stay free, gate-1 P2), and
        # the report schema's closed policy_slug enum. The pytest companion
        # `test_check_394_submission_policy.py` runs via the unified manifest.
        env:
          PYTHONPATH: .
        run: python scripts/check_394_submission_policy.py

      - name: "#439 format_profile contract lint"
        # Guards the scholar-declared layout profile feature (8 invariants):
        # valid standalone Draft 2020-12 schema + locked root (Invariant 11), the
        # line_spacing.fixed_pt conditional (required iff mode==fixed_pt, AND mode
        # itself required), NO venue_profile provenance machinery leaked in
        # (declared-only downgraded to docs, design §3), cut fields stay cut
        # (design §4), the synthetic example validates, the formatter + intake
        # prose wiring carry their load-bearing literals (byte-equivalence guard,
        # fail-closed, venue precedence; write-nothing-when-declined + structural
        # PCR row), and the POSITIONING ship-contract-not-content boundary (§6).
        # The pytest companion `test_check_439_format_profile.py` runs via the
        # unified manifest.
        env:
          PYTHONPATH: .
        run: python scripts/check_439_format_profile.py

      - name: Run v3.9.2 Phase Boundary coverage lint (#133)
        # Enforces 22 Bucket A agents have ## Phase Boundary (v3.9.2)
        # block, 16 Bucket B/C/D agents DON'T, and each Bucket A block
        # contains the four load-bearing phrases (Phase Boundary v3.9.2,
        # MUST NOT, MAY READ, Enforcement v3.9.2). See
        # docs/design/2026-05-18-ars-v3.9.2-agent-phase-classification.md.
        # The pytest companion `test_check_v3_9_2_phase_boundary.py` and the
        # #133 pipeline-integrity advisory verifier tests run via the unified
        # manifest (#156).
        env:
          PYTHONPATH: .
        run: python3 scripts/check_v3_9_2_phase_boundary.py

      - name: Run #215 field-norm severity coverage lint
        # Asserts the three #215 reviewer surfaces (domain_reviewer Step 5,
        # devils_advocate dimension 9 + CRITICAL fields, calibration Phase 3.5)
        # carry their scoped field-norm-severity blocks. Block-scoped keyword
        # checks (not file-wide) so a stray keyword cannot mask a missing rule.
        # The pytest companion test_check_215_field_norm.py (mutation tests) runs
        # via the unified manifest (#156). Issue #215 (Kim et al. 2026 W1/§F.3.4).
        env:
          PYTHONPATH: .
        run: python3 scripts/check_215_field_norm.py

      - name: Run #216 surface-form parity gold-set integrity lint
        # Validates the mixed-provenance §F.3.6 gold set: structural completeness,
        # provenance honesty (paper_verbatim quotes the paper; counterfactual_rewrite /
        # maintainer_boundary are labelled as maintainer-authored, never paper-verbatim),
        # pair invariants (paired items hold claim + verdict constant, differ in framing),
        # no rotting pdftotext line anchors, and gold<->manifest agreement. NOT an FNR/FPR
        # detector — there is no deterministic predictor for the surface-form bias.
        # Companion test_check_surface_form_parity.py (mutation + serializer-strip) runs
        # via the unified manifest (#156). Issue #216 (Kim et al. 2026 §F.3.6).
        env:
          PYTHONPATH: .
        run: python3 -m scripts.check_surface_form_parity

      - name: Run #216 surface-form parity coverage lint
        # Asserts the Devil's Advocate agent carries the Surface-Form Parity self-check
        # block at verdict time, with every load-bearing clause inside its marker block
        # (block-scoped + fence-aware), so a stray keyword cannot mask a missing rule.
        # Companion test_check_216_surface_form.py (6-class mutation suite) runs via the
        # unified manifest (#156). Issue #216 (Kim et al. 2026 §F.3.6).
        env:
          PYTHONPATH: .
        run: python3 scripts/check_216_surface_form.py

      - name: Run v3.10 #134 write-scope three-way name cross-check lint
        # THE FAIL-OPEN GUARD for the Slice 1 write-scope hook. Asserts the 23 Bucket A
        # agent names match across the classification roster, the scope manifest keys,
        # and the on-disk agent frontmatter `name` fields. A drift would silently fail
        # the PreToolUse hook OPEN (treat a fenced agent as unconstrained). The pytest
        # companions test_ars_write_scope_guard.py + test_check_v3_10_134_write_scope.py
        # (hook decision tests + lint mutation tests) run via the unified manifest (#156).
        # Spec: docs/design/2026-06-01-ars-134-conductor-rescope-deterministic-write-guard-spec.md
        env:
          PYTHONPATH: .
        run: python3 scripts/check_v3_10_134_write_scope.py

      - name: Validate ARS plugin hooks.json wires the write-scope guard
        # Pins hooks/hooks.json to (a) be valid JSON, (b) carry a PreToolUse entry whose
        # matcher covers the structured write tools + Bash, (c) invoke the cross-platform
        # launcher hooks/run_guard.sh via ${CLAUDE_PLUGIN_ROOT}, AND (d) confirm the launcher
        # actually execs the guard script (so the launcher->guard chain can't be silently
        # severed by a future edit). The hook went via run_guard.sh in #454: a bare `python3`
        # command broke on Windows where python3 is a 0-byte Microsoft Store alias stub.
        run: |
          python3 - <<'PY'
          import json
          h = json.load(open("hooks/hooks.json"))
          pre = h.get("hooks", {}).get("PreToolUse", [])
          assert pre, "hooks.json has no PreToolUse entry"
          entry = pre[0]
          matcher = entry.get("matcher", "")
          for tool in ("Write", "Edit", "MultiEdit", "Bash"):
              assert tool in matcher, f"PreToolUse matcher missing {tool!r}: {matcher!r}"
          cmds = " ".join(hk.get("command", "") for hk in entry.get("hooks", []))
          assert "hooks/run_guard.sh" in cmds, "PreToolUse does not invoke the run_guard.sh launcher"
          assert "${CLAUDE_PLUGIN_ROOT}" in cmds, "hook command must use ${CLAUDE_PLUGIN_ROOT}"
          # The launcher must still chain to the guard script — pin it so the chain stays intact.
          # P2-f: do NOT use a bare substring (a COMMENT mentioning the guard would false-pass and
          # the launcher->guard chain could be severed while CI stays green). Skip whole-line
          # comments, then require non-comment EXECUTABLE shapes: (1) the guard path is ASSIGNED
          # from the launcher's own location, and (2) that assigned path is EXEC'd in the guard
          # call site's command-substitution. This is a fast smoke pin, not full semantic proof —
          # the authoritative launcher->guard exec verification is scripts/test_run_guard_launcher.py
          # (run via the CI pytest manifest), which actually runs the launcher and asserts a real
          # `deny` is forwarded. So we keep the static check tight enough to catch an obvious
          # severance (commenting out the exec line) without trying to out-parse the shell:
          # the exec match is bound to the GUARD_OUT=$( ... run_bounded ... "$GUARD" ) call-site
          # shape. The assignment line is ANCHORED at line start (^\s*) so an inline comment like
          # `ls # GUARD_OUT=$(run_bounded "$GUARD")` can't satisfy it, and the run_bounded/"$GUARD"
          # tokens are confined to a single command substitution (no `)` between them) so
          # `GUARD_OUT=$( echo run_bounded "$GUARD" )` doesn't false-pass either (gemini r6 P2,
          # tightening the codex r6 P2 fix).
          import re
          guard_assigned = guard_run = False
          for raw in open("hooks/run_guard.sh"):
              if raw.lstrip().startswith("#"):
                  continue  # whole-line comment — never load-bearing
              # (1) GUARD=...ars_write_scope_guard.py  (assignment, derived from $0 dir)
              if re.search(r'\bGUARD=.*ars_write_scope_guard\.py', raw):
                  guard_assigned = True
              # (2) the guard call site, anchored at line start; run_bounded must be the command
              #     run inside the substitution (only a pipe `|` may precede it), and "$GUARD" its
              #     argument — all within one $( ... ) (the [^)]* forbids a closing paren between).
              if re.search(r'^\s*GUARD_OUT=\$\([^)]*\|\s*run_bounded\b[^)]*"\$GUARD"', raw):
                  guard_run = True
          assert guard_assigned, \
              "run_guard.sh has no non-comment GUARD=...ars_write_scope_guard.py assignment — chain severed"
          assert guard_run, \
              'run_guard.sh has no anchored GUARD_OUT=$(... | run_bounded ... "$GUARD") call site — launcher->guard exec chain severed'
          print("hooks.json PreToolUse write-scope guard wiring OK (via run_guard.sh launcher)")
          PY

      - name: Run v3.9.4 temporal verification lint (#135)
        # Verifies check_v3_9_4_temporal_verification.py against all bundled
        # fixtures in tests/fixtures/v3.9.4-temporal/. Each fixture directory
        # carries timeline.yaml, citation_provenance.yaml, and
        # expected_temporal_audit_results.yaml (the verifier's expected output,
        # used as the lint's --temporal-audit input). The guard protects against
        # directories that don't have all three files (defensive, forward-compat).
        # Spec: docs/design/2026-05-18-ars-v3.9.4-temporal-verification-spec.md
        env:
          PYTHONPATH: .
        run: |
          for fixture in tests/fixtures/v3.9.4-temporal/*/; do
            if [ -f "$fixture/timeline.yaml" ] && [ -f "$fixture/citation_provenance.yaml" ] && [ -f "$fixture/expected_temporal_audit_results.yaml" ]; then
              python3 scripts/check_v3_9_4_temporal_verification.py \
                --timeline "$fixture/timeline.yaml" \
                --citation-provenance "$fixture/citation_provenance.yaml" \
                --temporal-audit "$fixture/expected_temporal_audit_results.yaml"
            fi
          done

      - name: Run v3.8 annotation-literal sync lint (#103)
        # Step 8 /simplify reuse P2-1: lint pins that every
        # ANNOTATION_HIGH_WARN_* literal in scripts/claim_audit_finalizer.py
        # has a matching bracket-prefix in formatter_agent.md REFUSE rules
        # 6-10. Without this CI step a finalizer literal rename would
        # silently break the formatter terminal hard gate.
        env:
          PYTHONPATH: .
        run: |
          python3 scripts/check_v3_8_annotation_literal_sync.py

      - name: Run v3.8 annotation-literal sync lint tests (#103)
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_v3_8_annotation_literal_sync -v

      - name: Check cross-model grounding-guard doc sync (#346 / #349)
        # Drift guard: asserts shared/cross_model_verification.md references the canonical jq
        # filters under scripts/cross_model_verification/ via `jq -f` and still carries the
        # NOT_SEARCHED + CROSS-MODEL-ERROR safety branches — so a doc edit can't re-inline a
        # weaker filter or drop a branch while the behavioral tests keep passing against the
        # untouched .jq files. Behavior of the filters themselves is pinned by the manifest test
        # 346-349-cross-model-grounding-guards.
        run: python3 scripts/check_cross_model_verification_sync.py

      - name: Run v3.8 claim_audit pipeline + schema + uncited-assertion + manifest + finalizer + e2e + calibration tests (#103)
        # The v3.8 #103 test suite covers the L3 claim-faithfulness audit
        # contract end-to-end:
        #   - Step 4-6: schema validation (T-S1..T-S8 + the 4 manifest /
        #     uncited / drift / constraint invariant families), pipeline
        #     routing (T-P1..T-P11 §4 step 1-6), uncited token rule
        #     (T-U1..T-U5 D4-c three-condition detector).
        #   - Step 7 (round-2 review closure): manifest set-diff +
        #     constraint inheritance + MANIFEST-MISSING fallback
        #     (T-M1..T-M3 §7.3) + T-CO-1..T-CO-4 carry-overs.
        #   - Step 8: 8-row finalizer matrix (T-F1a..h + T-F2..T-F5 §7.5).
        #   - Step 9: end-to-end synthetic-paper test (5 citations, 1
        #     fabricated; spec §7.6) — exercises detector → pipeline →
        #     finalizer chain.
        #   - Step 10: calibration gate (T-C1 FNR<0.15 + FPR<0.10 against
        #     20-tuple gold set; T-C2 per-class reporting; T-C3 gold-set
        #     shape integrity; spec §7.7).
        #   - Step 11 (regression baseline): all 7 modules run together
        #     against the full diff to guarantee zero regression before
        #     independent review (spec §7.8 + §13 step 11).
        # Without this CI step the audit contracts shipped from Steps 4-10
        # could regress silently. Spec:
        # docs/design/2026-05-15-issue-103-claim-alignment-audit-spec.md §7
        env:
          PYTHONPATH: .
        run: |
          python3 -m unittest \
            scripts.test_claim_audit_schema \
            scripts.test_claim_audit_pipeline \
            scripts.test_uncited_assertion \
            scripts.test_claim_intent_manifest \
            scripts.test_claim_audit_finalizer \
            scripts.test_e2e_claim_audit \
            scripts.test_claim_audit_calibration \
            -v

      - name: Run v3.6.7 Step 6 audit schema + helper tests (Phase 6.2 + 6.4)
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_audit_schemas scripts.test__next_verified_at_ms -v

      - name: Run v3.6.7 Step 6 Phase 6.6 orchestrator prompt static checks
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_v3_6_7_phase_6_6 -v

      - name: Validate v3.6.7 Step 8 pattern-eval fixture manifests (Phase 6.8)
        run: python3 scripts/check_pattern_eval_manifest.py

      - name: "Check policy anchor table structural lint (#108)"
        run: python3 scripts/check_policy_anchor_table.py

      - name: "Run policy anchor table validator unit tests (#108)"
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_policy_anchor_table -v

      - name: "Check policy anchor disclosure protocol lint (#108)"
        run: python3 scripts/check_policy_anchor_protocol.py

      - name: "Run policy anchor protocol validator unit tests (#108)"
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_check_policy_anchor_protocol -v

      - name: "Run policy anchor disclosure conformance suite — referee (#108)"
        env:
          PYTHONPATH: .
        run: python3 -m unittest scripts.test_policy_anchor_disclosure -v

      - name: Validate evals gold sets (#184)
        # Phase 1a citation-extraction gold subset validator.
        # Enforces 9 invariants (I1-I7, I9, I10) per
        # docs/design/2026-05-21-v3.10-184-extend-eval-harness-spec.md.
        env:
          PYTHONPATH: .
        run: python3 -m scripts.check_evals_gold_set evals/gold/citation_extraction

      - name: Validate #268 nested-object Commitment Ledger
        # Schema 11 parallel-list -> nested-object refactor (#268). N1-N5:
        # seed extraction-field presence, no retired parallel-list keys,
        # per-commitment lifecycle coherence, and no surviving index notation
        # in the Schema 11 prose + re_review_mode_protocol surfaces.
        # Spec: docs/design/2026-05-31-ars-268-schema11-nested-commitment-ledger-spec.md.
        env:
          PYTHONPATH: .
        run: python3 -m scripts.check_268_nested_commitment_ledger

name: Test Count Monotonic

# Verify the PR doesn't reduce pytest collection count vs. base.
#
# Why: 5 days from v3.9.0 to v3.9.4.1 added 1463 -> 1561 tests
# (+98, 0 regression). Manual baseline tracking. This gate catches
# any PR that silently drops tests (deletion, accidental skip,
# fixture rename leaving orphans).
#
# Tolerance: net count must be >= base. Renames are fine; deletions
# require explicit justification.
#
# Override: include [skip-test-count] in PR body with justification
# (e.g., "removing dead suite X — N tests retired intentionally").

on:
  pull_request:
    branches: [main]

concurrency:
  group: test-count-${{ github.event.pull_request.number }}-${{ github.event_name }}
  cancel-in-progress: true

permissions:
  contents: read
  pull-requests: read

jobs:
  count-check:
    runs-on: ubuntu-latest
    steps:
      - name: Check out PR
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip
          cache-dependency-path: requirements-dev.txt

      - name: Install deps (PR head)
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt pytest

      - name: Count tests on PR head
        id: head
        run: |
          set -euo pipefail
          # Capture pytest exit code separately from grep so a collection
          # error (broken import, missing fixture file, etc.) fails the gate
          # instead of being swallowed by the pipe (#155 / re-attempt of F4
          # from the v3.9.4.2 cycle, originally in PR #153 commit 8121dfa
          # before being reverted in 4abf9de while #154 was still open).
          set +e
          pytest --collect-only -q > pytest-collect.txt 2> pytest-collect.err
          PYTEST_EXIT=$?
          set -e
          # Exit 5 = pytest "no tests collected"; tolerable for degenerate
          # cases (empty repo, path filter that matches nothing). Any other
          # non-zero exit is a real collection failure and must fail the gate.
          if [ "$PYTEST_EXIT" -ne 0 ] && [ "$PYTEST_EXIT" -ne 5 ]; then
            echo "::error::pytest collection failed on PR head (exit $PYTEST_EXIT)"
            cat pytest-collect.err >&2 || true
            tail -20 pytest-collect.txt >&2 || true
            exit 1
          fi
          # grep -c exits 1 when there are zero matches — tolerate ONLY that;
          # any other non-zero exit from grep is a real error (unreadable
          # file, missing binary) and must propagate.
          set +e
          COUNT=$(grep -c '::' pytest-collect.txt)
          GREP_EXIT=$?
          set -e
          if [ "$GREP_EXIT" -ne 0 ] && [ "$GREP_EXIT" -ne 1 ]; then
            echo "::error::grep failed unexpectedly (exit $GREP_EXIT)"
            exit 1
          fi
          echo "Head test count: $COUNT"
          echo "count=$COUNT" >> "$GITHUB_OUTPUT"
          rm -f pytest-collect.txt pytest-collect.err

      - name: Add base via worktree
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          set -euo pipefail
          git worktree add ../base "$BASE_SHA"

      - name: Install deps (base)
        working-directory: ../base
        run: |
          # Reuse pip cache; requirements may differ
          if [ -f requirements-dev.txt ]; then
            pip install -r requirements-dev.txt pytest --quiet
          else
            pip install pytest --quiet
          fi

      - name: Count tests on base
        id: base
        working-directory: ../base
        run: |
          set -euo pipefail
          # Symmetric strict collection — mirrors the PR-head step above.
          # The previous `2>/dev/null | grep -c '::' || true` pattern would
          # set BASE_COUNT to 0 on any collection error, making the
          # monotonic comparison (head >= base) vacuously pass and hiding
          # genuine drift. Fail the gate on real collection errors instead.
          set +e
          pytest --collect-only -q > pytest-collect.txt 2> pytest-collect.err
          PYTEST_EXIT=$?
          set -e
          if [ "$PYTEST_EXIT" -ne 0 ] && [ "$PYTEST_EXIT" -ne 5 ]; then
            echo "::error::pytest collection failed on base (exit $PYTEST_EXIT)"
            cat pytest-collect.err >&2 || true
            tail -20 pytest-collect.txt >&2 || true
            exit 1
          fi
          set +e
          COUNT=$(grep -c '::' pytest-collect.txt)
          GREP_EXIT=$?
          set -e
          if [ "$GREP_EXIT" -ne 0 ] && [ "$GREP_EXIT" -ne 1 ]; then
            echo "::error::grep failed unexpectedly (exit $GREP_EXIT)"
            exit 1
          fi
          echo "Base test count: $COUNT"
          echo "count=$COUNT" >> "$GITHUB_OUTPUT"
          rm -f pytest-collect.txt pytest-collect.err

      - name: Compare
        env:
          PR_BODY: ${{ github.event.pull_request.body }}
          HEAD_COUNT: ${{ steps.head.outputs.count }}
          BASE_COUNT: ${{ steps.base.outputs.count }}
        run: |
          set -euo pipefail
          DELTA=$((HEAD_COUNT - BASE_COUNT))
          echo "Base: $BASE_COUNT  Head: $HEAD_COUNT  Delta: $DELTA"

          if [ "$HEAD_COUNT" -ge "$BASE_COUNT" ]; then
            echo "OK — test count monotonic ($DELTA)."
            exit 0
          fi

          if echo "${PR_BODY:-}" | grep -qF '[skip-test-count]'; then
            echo "::warning::Test count dropped by $((BASE_COUNT - HEAD_COUNT)) but [skip-test-count] override present."
            exit 0
          fi

          echo "::error::Test count dropped: $BASE_COUNT -> $HEAD_COUNT (-$((BASE_COUNT - HEAD_COUNT)))."
          echo "::error::Add [skip-test-count] + justification to PR body if intentional."
          exit 1

# Repository-hygiene scan config (#151).
#
# Extends the upstream gitleaks default ruleset; adds NO custom rules.
# What it catches is documented at the level of the upstream tool's docs:
# https://github.com/gitleaks/gitleaks#rules
#
# The allowlist removes the single structural false-positive class this repo
# carries: bibliographic citation keys (e.g. "Becht2019UMAP",
# "vaswani2017-arxiv-v1") stored in key-shaped fields of eval gold tuples,
# the version-family example/design doc, and their schema test. These match
# the generic-api-key heuristic but are literature identifiers, not
# credentials — the 2026-06-10 baseline evaluation found 43 findings across
# 518 commits, all of this class, zero true positives.
#
# Maintenance note: a new citation-tuple file under the allowlisted evals
# path needs no action here. A NEW false-positive class elsewhere should be
# added as a path entry (or a .gitleaksignore fingerprint for a one-off),
# never as a rule edit.

[extend]
useDefault = true

[allowlist]
description = "Bibliographic citation keys misread as generic-api-key (literature identifiers, not credentials)"
paths = [
  '''evals/gold/citation_extraction/tuples/.*\.json''',
  '''scripts/fixtures/check_evals_gold_set/.*''',
  '''scripts/adapters/examples/.*''',
  '''scripts/adapters/tests/test_zotero\.py''',
  '''academic-paper/examples/version_family_reconciliation_example\.md''',
  '''docs/design/2026-05-28-kong-258-version-family-reconciliation\.md''',
  '''docs/design/2026-04-23-ars-v3\.6\.4-literature-corpus-adapters-plan\.md''',
  '''scripts/test_version_records_schema\.py''',
]