refactor(sdd): make the feature spec issue-only (no committed spec.md)

The Gitea issue body is the single source of truth for a spec; the only
per-feature artifact in git is the RTM row (REQ-ID -> issue # -> test). Drops
per-feature spec.md/tasks.md/checklist files from the workflow (the _example
stays as a template/reference). Updates the guide, ADR-041, AGENTS.md, CLAUDE.md,
templates, the RTM (adds an Issue column), the implement/review-pr skills, and
replaces the file-spec CI jobs with an rtm-check.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitea/workflows/sdd-gate.yml

@@ -1,78 +1,64 @@
 name: SDD Gate
 
-# Spec-Driven Development quality gate. Runs on PRs and validates the SDD artifacts that
-# the PR touches. The first three jobs are NON-BLOCKING for now (continue-on-error) so the
-# team can adopt the workflow without CI immediately failing.
+# Spec-Driven Development quality gate. Runs on PRs.
 #
-# TODO: flip spec-lint, contract-validate, and traceability-check to BLOCKING
-#       (remove `continue-on-error: true`) once SDD adoption has settled — target: after the
-#       first 5 real features have shipped through the .specify/ workflow. Tracked in ADR-041.
+# This project is ISSUE-ONLY: a feature's spec lives in its Gitea issue body, not a committed
+# spec.md (see ADR-041). So CI cannot lint the spec text itself — instead it validates the SDD
+# artifacts that DO live in git: the RTM, any committed OpenAPI contract, and the constitution.
+#
+# The first two jobs are NON-BLOCKING for now (continue-on-error) so the team can adopt the
+# workflow without CI immediately failing.
+#
+# TODO: flip rtm-check and contract-validate to BLOCKING (remove `continue-on-error: true`)
+#       once SDD adoption has settled — target: after the first 5 features have shipped through
+#       the workflow. Tracked in ADR-041.
 
 on:
   pull_request:
 
 jobs:
-  # ─── Spec structure lint ──────────────────────────────────────────────────────
-  # Every modified .specify/features/*/spec.md must contain the required SDD sections
-  # and at least one REQ-NNN requirement. Pure grep — no external tooling.
-  spec-lint:
-    name: Spec Lint
+  # ─── RTM check ────────────────────────────────────────────────────────────────
+  # The Requirements Traceability Matrix is the one per-feature SDD artifact in git. Every
+  # data row must point at a Gitea issue (`#n`) and name at least one test. Warn otherwise.
+  # Pure awk — no external tooling. Columns: | REQ-ID | Summary | Issue | Feature | Impl | Test | Status |
+  rtm-check:
+    name: RTM Check
     runs-on: ubuntu-latest
     continue-on-error: true   # TODO: remove to make blocking (see header)
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
-      - name: Lint changed spec.md files
+      - name: Validate .specify/rtm.md rows
         shell: bash
         run: |
           set -uo pipefail
-          base="origin/${{ github.event.pull_request.base.ref }}"
-          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
+          rtm=".specify/rtm.md"
+          test -f "$rtm" || { echo "::error::$rtm is missing"; exit 1; }
 
-          required=(
-            "## Context & Why"
-            "## Requirements"
-            "## Acceptance Criteria"
-            "## Out of Scope"
-            "## Security Considerations"
-            "## Traceability"
-          )
+          # Self-test: a good row passes, a row with an empty Issue or Test is flagged.
+          check_row() { awk -F'|' '{
+            issue=$4; test_col=$7;
+            gsub(/^[ \t]+|[ \t]+$/,"",issue); gsub(/^[ \t]+|[ \t]+$/,"",test_col);
+            if (issue !~ /#/ || test_col=="") exit 1; else exit 0 }'; }
+          echo '| REQ-001 | x | #42 | f | impl | SomeTest#works | Done |'  | check_row \
+            || { echo "FAIL: rtm-check self-test rejected a valid row"; exit 1; }
+          echo '| REQ-002 | x |     | f | impl |               | Planned |' | check_row \
+            && { echo "FAIL: rtm-check self-test accepted an empty row"; exit 1; }
 
-          # Self-test: a fixture with all sections + a REQ id must pass the section check.
-          fixture="$(mktemp)"
-          { for s in "${required[@]}"; do echo "$s"; done; echo "- **REQ-001** (Ubiquitous) — The x shall y."; } > "$fixture"
-          for s in "${required[@]}"; do
-            grep -qF "$s" "$fixture" || { echo "FAIL: spec-lint self-test missing '$s'"; exit 1; }
-          done
-
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)"
-          if [ -z "$changed" ]; then
-            echo "No spec.md files changed — nothing to lint."
-            exit 0
-          fi
-
-          rc=0
-          for f in $changed; do
-            [ -f "$f" ] || continue   # deleted file
-            echo "── linting $f"
-            for s in "${required[@]}"; do
-              if ! grep -qF "$s" "$f"; then
-                echo "::error file=$f::missing required section '$s'"
-                rc=1
-              fi
-            done
-            if ! grep -qE 'REQ-[0-9]{3}' "$f"; then
-              echo "::error file=$f::no REQ-NNN requirement found"
-              rc=1
-            fi
-          done
-          exit $rc
+          bad=0
+          while IFS= read -r line; do
+            echo "$line" | check_row || {
+              req=$(echo "$line" | awk -F'|' '{gsub(/^[ \t]+|[ \t]+$/,"",$2); print $2}')
+              echo "::warning file=$rtm::row $req is missing an Issue (#n) or a Test"
+              bad=$((bad+1))
+            }
+          done < <(grep -E '^\| REQ-[0-9]{3} ' "$rtm")
+          echo "$bad RTM row(s) incomplete (warning only)."
 
   # ─── Contract validation ──────────────────────────────────────────────────────
-  # Validate any modified api-contract.yaml with Spectral (OpenAPI 3.1). REST stack —
-  # no GraphQL. Skips cleanly when no contract changed.
+  # Validate any committed OpenAPI contract with Spectral (OpenAPI 3.1). REST stack — no
+  # GraphQL. Contracts are optional and ride a feature branch when present; the _example one
+  # is always linted. Skips cleanly when none changed.
   contract-validate:
     name: Contract Validate
     runs-on: ubuntu-latest
@@ -92,9 +78,10 @@ jobs:
           set -uo pipefail
           base="origin/${{ github.event.pull_request.base.ref }}"
           git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/api-contract.yaml' || true)"
+          # Any *.yaml under .specify/ or any file named like a contract.
+          changed="$(git diff --name-only "$base"...HEAD -- '.specify/**/*.yaml' '**/api-contract.yaml' '**/*.openapi.yaml' || true)"
           if [ -z "$changed" ]; then
-            echo "No api-contract.yaml changed — nothing to validate."
+            echo "No OpenAPI contract changed — nothing to validate."
             exit 0
           fi
           rc=0
@@ -105,39 +92,6 @@ jobs:
           done
           exit $rc
 
-  # ─── Traceability check ───────────────────────────────────────────────────────
-  # Warn (non-blocking) when a changed spec.md references a REQ-NNN that is absent from
-  # .specify/rtm.md. Keeps the matrix honest without hard-failing during adoption.
-  traceability-check:
-    name: Traceability Check
-    runs-on: ubuntu-latest
-    continue-on-error: true   # TODO: remove to make blocking (see header)
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Cross-check spec REQ-IDs against rtm.md
-        shell: bash
-        run: |
-          set -uo pipefail
-          base="origin/${{ github.event.pull_request.base.ref }}"
-          git fetch --no-tags --depth=1 origin "${{ github.event.pull_request.base.ref }}" || true
-          changed="$(git diff --name-only "$base"...HEAD -- '.specify/features/*/spec.md' || true)"
-          [ -z "$changed" ] && { echo "No spec.md changed."; exit 0; }
-          test -f .specify/rtm.md || { echo "::warning::.specify/rtm.md missing"; exit 0; }
-          missing=0
-          for f in $changed; do
-            [ -f "$f" ] || continue
-            for req in $(grep -oE 'REQ-[0-9]{3}' "$f" | sort -u); do
-              if ! grep -qF "$req" .specify/rtm.md; then
-                echo "::warning file=$f::$req is not present in .specify/rtm.md"
-                missing=$((missing+1))
-              fi
-            done
-          done
-          echo "$missing REQ-ID(s) missing from rtm.md (warning only)."
-
   # ─── Constitution change impact ───────────────────────────────────────────────
   # When .specify/constitution.md is modified, list every file that references it (and so
   # may need a Sync Impact update) and post it as a PR comment. Best-effort: if no token is
@@ -164,7 +118,6 @@ jobs:
           fi
           echo "changed=true" >> "$GITHUB_OUTPUT"
           echo "Files referencing constitution.md (review for Sync Impact):"
-          # rg-free: grep recursively, excluding the file itself and VCS/build dirs.
           grep -rIl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=target \
             -e 'constitution.md' -e 'constitution §' . \
             | grep -v '^\./.specify/constitution.md$' | sort > /tmp/refs.txt || true
@@ -183,7 +136,6 @@ jobs:
         if: steps.impact.outputs.changed == 'true'
         shell: bash
         env:
-          # Gitea Actions exposes the repo token as GITHUB_TOKEN; the API is Gitea-compatible.
           TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SERVER: ${{ github.server_url }}
           REPO: ${{ github.repository }}