.planning/phases/15-ci-skip-api-harness-jobs-for-doc-only-prs/15-02-SUMMARY.md

@@ -0,0 +1,119 @@
+---
+phase: 15-ci-skip-api-harness-jobs-for-doc-only-prs
+plan: "02"
+subsystem: ci
+tags: [ci, gitea-actions, paths-filter, gate, doc-only-skip]
+dependency_graph:
+  requires: [15-01]
+  provides: [CI / gate commit-status, doc-only PR skip]
+  affects: [.gitea/workflows/ci.yml]
+tech_stack:
+  added:
+    - dorny/paths-filter@v4 (Gitea action for PR diff detection)
+  patterns:
+    - changes job with paths-filter
+    - always-running gate aggregate job
+    - Gitea-safe individual needs.X.result checks
+key_files:
+  modified:
+    - .gitea/workflows/ci.yml
+decisions:
+  - D-15-02-CHANGES-JOB: dorny/paths-filter@v4 with positive code filter; code==false means doc-only; ambiguous files default to full gate
+  - D-15-02-GATE-INDIVIDUAL: individual needs.X.result checks (not wildcard) due to Gitea 1.26.2 bug #31007
+  - D-15-02-GATE-ALWAYS: if:always() on gate prevents deadlock on skipped upstream jobs (fix in Gitea 1.21.8, instance is 1.26.2)
+metrics:
+  duration_minutes: 5
+  completed_date: "2026-06-12"
+  tasks_completed: 2
+  tasks_total: 2
+  files_modified: 1
+---
+
+# Phase 15 Plan 02: CI doc-only skip + gate aggregate Summary
+
+**One-liner:** `changes` job (dorny/paths-filter@v4) classifies each PR; `api`/`harness` skip on `code==false`; always-running `gate` job aggregates all results using Gitea-safe individual `needs.X.result` checks, emitting the `CI / gate` status that Plan 03's branch-protection update requires.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | Add changes job and gate api/harness on code output | 7260438 | .gitea/workflows/ci.yml |
+| 2 | Add always-running gate aggregate job | 547b12c | .gitea/workflows/ci.yml |
+
+## What Was Built
+
+**Task 1 — changes job + conditional api/harness:**
+
+A new `changes` job using `dorny/paths-filter@v4` was inserted before `fast-checks` in `.gitea/workflows/ci.yml`. It:
+- Runs on `ubuntu-latest` with `if: github.event_name == 'pull_request'`
+- Declares `permissions: pull-requests: read` (job-scoped, required by paths-filter v4)
+- Emits `outputs.code: ${{ steps.filter.outputs.code }}`
+- Contains a single `uses: dorny/paths-filter@v4` step with `id: filter` and NO `actions/checkout`
+- Defines a positive `code` filter covering `**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.json`, `**/*.yaml`, `**/*.yml`, `apps/**`, `packages/**`, `pnpm-lock.yaml`, `Dockerfile`, `docker-compose*.yml`
+
+The `api` and `harness` jobs were modified:
+- Added `needs: [changes]`
+- Changed `if` from `github.event_name == 'pull_request'` to `github.event_name == 'pull_request' && needs.changes.outputs.code == 'true'`
+- Updated inline comment to say "skipped for doc-only PRs"
+- All services, env, and step bodies left unchanged
+
+**Task 2 — gate aggregate job:**
+
+A new `gate` job was appended at the end of `ci.yml`:
+- `runs-on: ubuntu-latest`
+- `needs: [fast-checks, changes, api, harness]`
+- `if: always()` — ensures the job reports regardless of upstream outcome
+- One step running a bash script that:
+  1. Fails (exit 1) if `needs.fast-checks.result` is not `success` (fast-checks always runs)
+  2. Iterates over `needs.api.result` and `needs.harness.result`, failing if either is not `success` or `skipped`
+  3. Echoes "Gate passed." otherwise
+- Uses individual `needs.X.result` references (not `contains(needs.*.result,...)`) due to Gitea 1.26.2 bug #31007
+
+## Decisions Made
+
+- **D-15-02-CHANGES-JOB:** Positive `code` filter chosen (not a `docs` exclusion filter) so any new or ambiguous file type defaults to the full gate. A doc-only PR must have every changed file fall outside the code patterns.
+- **D-15-02-GATE-INDIVIDUAL:** Individual `needs.X.result` checks used instead of `contains(needs.*.result, ...)` wildcard — Gitea 1.26.2 issue #31007 confirms the wildcard returns false even when jobs succeed.
+- **D-15-02-GATE-ALWAYS:** `if: always()` on the `gate` job prevents deadlock when upstream jobs are skipped. The deadlock bug (Gitea #27906) was fixed in 1.21.8; this instance runs 1.26.2.
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Threat Model Coverage
+
+| Threat | Mitigation | Status |
+|--------|-----------|--------|
+| T-15-04: gate passes when fast-checks fails | gate exits 1 on fast-checks != success; skipped accepted only for api/harness | Implemented |
+| T-15-05: code PR misclassified doc-only | positive code filter — any ambiguous file matches code and runs full gate | Implemented |
+| T-15-06: supply chain via dorny/paths-filter@v4 | pinned to @v4 tag; pull-requests:read only; no secrets access | Implemented |
+| T-15-07: required check deadlock | gate uses if:always(); api/harness NOT added as required checks (Plan 03 scope) | Implemented |
+
+## Known Stubs
+
+None — this plan produces only CI workflow YAML. No runtime state or UI involved.
+
+## Threat Flags
+
+None — no new network endpoints, auth paths, file access patterns, or schema changes.
+
+## Verification
+
+**Static (pre-merge):**
+- Python yaml.safe_load parses ci.yml without error
+- `changes` job present with `dorny/paths-filter@v4`, `id: filter`, `permissions: pull-requests: read`, `outputs.code`
+- No `actions/checkout` step in `changes` job
+- `api` and `harness` have `needs: [changes]` and combined `if` with `needs.changes.outputs.code == 'true'`
+- `gate` job present with `if: always()` and `needs: [fast-checks, changes, api, harness]`
+- `needs.fast-checks.result`, `needs.api.result`, `needs.harness.result` individually referenced in gate
+- No `contains(needs.*.result` wildcard in file
+
+**Behavioral (post-merge, per 15-VALIDATION.md):**
+- Doc-only PR: `changes` emits `code=false`; `api`/`harness` show skipped; `fast-checks` runs; `gate` passes
+- Code PR: all three run; `gate` passes when green
+- Gate-fail path: failing fast-checks causes `gate` to exit 1
+
+## Self-Check: PASSED
+
+- `.gitea/workflows/ci.yml` modified: EXISTS
+- Commit 7260438 (Task 1): FOUND
+- Commit 547b12c (Task 2): FOUND