draft: Add requirements tracking

.github/workflows/requirements-sync.yml

@@ -0,0 +1,29 @@
+name: Sync Requirements to GitHub Issues
+
+on:
+  push:
+    branches: [main, public-main]
+    paths:
+      - 'requirements/requirements.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: requirements-sync
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Sync issues and project
+        env:
+          GH_TOKEN: ${{ secrets.PROJECT_TOKEN || secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: ${{ github.repository }}
+        run: ./requirements/sync-issues.sh

Makefile

@@ -34,7 +34,7 @@ WORKER_SCRIPT := scripts/worker.sh
         add-worker-nodes worker-status approve-worker-csrs \
         deploy-csr-approver delete-csr-approver deploy-dpucluster-csr-approver delete-dpucluster-csr-approver \
         delete-dpf-hcp-provisioner-operator \
-        verify-deployment verify-workers verify-dpu-nodes verify-dpudeployment \
+        verify-deployment verify-workers verify-dpu-nodes verify-dpudeployment verify-requirements \
         run-traffic-flow-tests tft-setup tft-cleanup tft-show-config tft-results aicli-list \
         validate-env-files generate-env
 
@@ -272,6 +272,12 @@ verify-dpu-nodes:
 verify-dpudeployment:
 	@$(VERIFY_SCRIPT) verify-dpudeployment
 
+verify-requirements:
+	@echo "================================================================================"
+	@echo "Running Requirements Verification..."
+	@echo "================================================================================"
+	@./requirements/verify-requirements.sh $(VERIFY_REQ_ARGS)
+
 validate-env-files:
 	@$(ENV_SCRIPT) validate-env-files
 
@@ -338,6 +344,11 @@ help:
 	@echo "  verify-workers        - Wait for worker nodes to be Ready in host cluster"
 	@echo "  verify-dpu-nodes      - Wait for DPU nodes to be Ready in DPUCluster"
 	@echo "  verify-dpudeployment  - Wait for DPUDeployment to be Ready"
+	@echo "  verify-requirements   - Run requirement tests and produce a report"
+	@echo "                          Use VERIFY_REQ_ARGS to pass options, e.g.:"
+	@echo "                            make verify-requirements VERIFY_REQ_ARGS='REQ-001 REQ-049'"
+	@echo "                            make verify-requirements VERIFY_REQ_ARGS='--output report.md'"
+	@echo "                            make verify-requirements VERIFY_REQ_ARGS='--json'"
 	@echo ""
 	@echo "Traffic Flow Tests:"
 	@echo "  run-traffic-flow-tests - Run kubernetes-traffic-flow-tests for network validation"

requirements/README.md

@@ -0,0 +1,72 @@
+# Requirements Tracking
+
+This directory contains tooling to track project requirements as GitHub Issues, managed via a GitHub Project board.
+
+## How It Works
+
+1. **`requirements.json`** is the source of truth. Each requirement declares its description, test details, labels, and (once synced) the corresponding GitHub issue number.
+2. **`sync-issues.sh`** reads the JSON and creates or updates GitHub Issues and a GitHub Project.
+3. **`update-results.sh`** takes `go test -json` output and posts pass/fail results as comments on the corresponding issues.
+4. **GitHub Actions** automate both steps — syncing on push and posting test results on a schedule.
+
+## JSON Schema
+
+Each entry in `requirements.json`:
+
+| Field              | Type       | Description                                                  |
+|--------------------|------------|--------------------------------------------------------------|
+| `id`               | string     | Stable identifier, e.g. `REQ-001`. Never changes.           |
+| `requirement`      | string     | Brief description of the requirement.                        |
+| `test_description` | string     | What the test verifies / acceptance criteria.                |
+| `test_implementation` | string  | Go test reference: `package/path::TestFunctionName`.         |
+| `labels`           | string[]   | GitHub labels to apply (created automatically if missing).   |
+| `issue_number`     | int\|null  | Populated by `sync-issues.sh`. Do not edit manually.        |
+
+## Local Usage
+
+### Prerequisites
+
+- [`gh`](https://cli.github.com/) CLI installed and authenticated (`gh auth login`)
+- [`jq`](https://jqlang.github.io/jq/) installed
+- `GITHUB_REPOSITORY` env var set (or let the script auto-detect from `gh`)
+
+### Sync requirements to issues
+
+```bash
+# Dry run (no changes made)
+./requirements/sync-issues.sh --dry-run
+
+# Create/update issues and project
+./requirements/sync-issues.sh
+```
+
+After creating new issues, the script updates `requirements.json` with issue numbers. Commit this change.
+
+### Post test results
+
+```bash
+# Run tests and pipe to the results script
+go test ./... -json 2>&1 | ./requirements/update-results.sh
+```
+
+### Adding a new requirement
+
+1. Add an entry to `requirements.json` with a new `id` and `"issue_number": null`.
+2. Run `sync-issues.sh` (or push to main — the GitHub Action will handle it).
+3. The script creates the issue and writes the number back to the JSON.
+
+## GitHub Actions
+
+### `requirements-sync.yml`
+
+Runs automatically when `requirements/requirements.json` is pushed to `main`. Creates/updates issues, then commits the updated JSON back with `[skip ci]` to avoid loops.
+
+### `requirements-results.yml`
+
+Runs on weekdays at 06:00 UTC (and via manual dispatch). Runs `go test`, posts results to the matching issues as comments.
+
+### Secrets
+
+| Secret          | Required | Purpose                                                    |
+|-----------------|----------|------------------------------------------------------------|
+| `PROJECT_TOKEN` | Optional | PAT with `project` scope for GitHub Projects v2 operations. Falls back to `GITHUB_TOKEN` (which works for issues but not projects). |