Merge branch 'develop' into security-scanning

Author: NoorChasib

.claude/settings.json

@@ -13,7 +13,14 @@
       "Bash(git log *)",
       "Bash(cd apps/*)",
       "Bash(cd scripts/*)",
-      "mcp__playwright__browser_press_key"
+      "mcp__playwright__browser_press_key",
+      "Bash(npm test:*)",
+      "Bash(npx jest:*)",
+      "Bash(npm run:*)",
+      "Bash(helm lint:*)",
+      "Bash(helm template:*)",
+      "Bash(docker compose:*)",
+      "Bash(kustomize build:*)"
     ],
     "defaultMode": "acceptEdits",
     "model": "sonnet"

.claude/skills/requirements-refiner/SKILL.md

@@ -10,21 +10,38 @@ description: "Requirements Refiner: Iteratively questions the user to clarify va
 2. **Iterative Elicitation**:
 - Identify gaps, ambiguities, or assumptions.
 - Ask a set of numbered clarifying questions.
+- For **each question**, provide 2–4 concrete answer options labeled (a), (b), (c), etc., and mark one as **"Recommended"** with a brief rationale. The user can pick an option, combine options, or provide their own answer.
 - Wait for the user's response.
 - Repeat this step until the requirements are clear and complete.
 3. **Consolidate**:
 - Once the requirements are fully understood, create a single consolidated document.
 - This document should include the initial requirements plus all details gathered during the Q&A process.
 - Ensure the output is structured and ready for a User Story writer to consume.
 4. **Save to feature-docs**:
-- Examine the `feature-docs/` directory to find the highest numbered folder (e.g., `001-graph-workflows`).
-- Determine the next increment number (e.g., if `001` exists, use `002`).
+- Generate a datetime stamp in the format `YYYYMMDDHHmmss` (same format as Prisma migrations) using the current UTC time.
 - Generate a short feature name/slug (kebab-case, e.g., "benchmarking-system").
-- Create a new folder: `feature-docs/{NNN}-{feature-slug}/` (e.g., `feature-docs/002-benchmarking-system/`).
+- Create a new folder: `feature-docs/{YYYYMMDDHHmmss}-{feature-slug}/` (e.g., `feature-docs/20260313143022-benchmarking-system/`).
 - Save the consolidated requirements as `REQUIREMENTS.md` in that folder.
 
 ## Key Behaviors
 - **Iterative Approach**: Do not rush to the final output. Prioritize clarity over speed.
 - **Probe Deeply**: Ask about edge cases, error states, and user roles.
-- **Auto-increment Folders**: Always check existing feature-docs folders to determine the next number.
-- **Output Format**: The final output must be saved as `feature-docs/{NNN}-{feature-slug}/REQUIREMENTS.md`.
+- **Suggest, Don't Just Ask**: Every clarifying question must include concrete options with a recommended choice. Base recommendations on the project context, industry best practices, and the elicitation standards. This helps the user make faster decisions and reduces back-and-forth.
+- **Datetime-stamped Folders**: Use the current UTC time in `YYYYMMDDHHmmss` format as the folder prefix.
+- **Output Format**: The final output must be saved as `feature-docs/{YYYYMMDDHHmmss}-{feature-slug}/REQUIREMENTS.md`.
+
+## Question Format Example
+
+```
+1. **Who should be able to trigger this workflow?**
+   (a) Only admin users
+   (b) Any authenticated user
+   (c) Both authenticated users and external API consumers
+   → **Recommended: (b)** — Most workflows in this system are user-initiated; restricting to admins adds friction without clear security benefit.
+
+2. **How should the system handle partial failures?**
+   (a) Fail the entire operation and roll back
+   (b) Continue processing remaining items and report failures at the end
+   (c) Retry failed items up to N times, then report
+   → **Recommended: (c)** — Retries with a cap balance reliability with predictable completion times.
+```

.claude/skills/split-branch-into-prs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: split-branch-into-prs
+description: "Splits a feature branch into multiple sequential draft PRs targeting develop. Trigger phrases: split branch into PRs, break branch into PRs, create stacked PRs, split into multiple PRs. Do NOT invoke for: creating a single PR, cherry-picking individual commits, or rebasing."
+---
+
+# Split Branch Into PRs
+
+Analyzes a feature branch, identifies logical commit groups, creates sequential branches via cherry-pick, and opens draft PRs with a standardized template. Includes merge workflow guidance.
+
+## Always Follow
+
+- Target branch is always `develop`
+- PRs are always created as **draft**
+- PRs are numbered (e.g., "PR 1/4", "PR 2/4") in the title so merge order is clear
+- Each PR branch includes all commits from prior groups (stacked), so that after squash-merge + "Update branch", the diff only shows net-new changes
+- Back up any sensitive untracked files (`.env`, tokens, etc.) before branch switching, restore them after
+- Never commit sensitive files — verify `.gitignore` coverage
+
+## Workflows
+
+1. **[Analyze & Plan](Workflows/analyze-and-plan.md)** — Identify the commit range, group commits into logical PRs, confirm the plan with the user
+2. **[Create Branches & PRs](Workflows/create-branches-and-prs.md)** — Cherry-pick commits, push branches, create draft PRs using the standard template
+3. **[Merge Workflow Guide](Workflows/merge-workflow-guide.md)** — Instructions for the squash-merge → update branch → repeat cycle

.claude/skills/split-branch-into-prs/Workflows/analyze-and-plan.md

@@ -0,0 +1,46 @@
+# Analyze & Plan
+
+Identify which commits need to be split and propose logical groupings.
+
+## Steps
+
+1. **Update develop to latest:**
+   ```bash
+   git fetch origin develop && git checkout develop && git pull origin develop
+   ```
+
+2. **Identify the commit range:**
+   - Run `git log --oneline develop..<current-branch>` to see all commits ahead of develop
+   - Ask the user which commit is the actual first commit on the branch (earlier commits may be from a parent branch that was squash-merged)
+   - Verify by checking `git diff develop..<branch> -- <path>` for suspected already-merged areas — 0 diff confirms they're in develop
+
+3. **List commits in chronological order:**
+   ```bash
+   git log --oneline --reverse <first-commit>^..<branch>
+   ```
+
+4. **Identify logical groups** by looking at:
+   - Commit message prefixes and user story references
+   - Which files each commit touches (`git log --oneline --name-only`)
+   - Natural breakpoints between features/workstreams
+   - Dependencies between groups (what must merge first)
+
+5. **Check for shared files across groups:**
+   ```bash
+   for f in <shared-files>; do
+     echo "=== $f ==="
+     git log --oneline --reverse <first-commit>^..<branch> -- "$f"
+   done
+   ```
+   Ensure shared files (package.json, Dockerfiles, app.module.ts, etc.) are grouped with the earliest PR that modifies them, or that modifications are sequential and won't conflict.
+
+6. **Present the plan to the user:**
+   - List each proposed PR with a title, the commits it includes, and a brief description
+   - Note any dependencies between groups
+   - Confirm the grouping before proceeding
+
+## Common Pitfalls
+
+- Don't assume all commits in `git log develop..<branch>` are unique — parent branches may have been squash-merged, leaving ghost commits that produce 0 diff
+- Always ask the user to confirm the first real commit rather than guessing
+- Watch for commits that touch the same file across groups — these need careful ordering

.claude/skills/split-branch-into-prs/Workflows/create-branches-and-prs.md

@@ -0,0 +1,106 @@
+# Create Branches & PRs
+
+After the plan is confirmed, create stacked branches and draft PRs.
+
+## Prerequisites
+
+- The plan from [Analyze & Plan](analyze-and-plan.md) has been confirmed by the user
+- You know: the commit groups, their order, and the first commit hash
+
+## Steps
+
+1. **Protect untracked sensitive files:**
+   ```bash
+   # Check for untracked files that might conflict with cherry-picks
+   git status --short
+   # Back up any sensitive untracked files (.env, tokens, etc.)
+   mkdir -p /tmp/branch-split-backup
+   # Copy files as needed, e.g.:
+   # cp deployments/openshift/config/*.env /tmp/branch-split-backup/
+   # Remove from working tree so cherry-picks don't conflict
+   ```
+
+2. **Ensure clean working tree on develop:**
+   ```bash
+   git checkout develop && git pull origin develop
+   git status --short  # must be clean (no untracked conflicts)
+   ```
+
+3. **Create branches — each includes all prior groups (stacked):**
+   For N groups, create N branches. Each branch cherry-picks all commits from group 1 through group N:
+   ```bash
+   # PR 1: just group 1
+   git checkout -b pr/<name-1> develop
+   git cherry-pick <first-commit-group1>^..<last-commit-group1>
+
+   # PR 2: group 1 + group 2
+   git checkout -b pr/<name-2> develop
+   git cherry-pick <first-commit-group1>^..<last-commit-group1>
+   git cherry-pick <first-commit-group2>^..<last-commit-group2>
+
+   # PR 3: group 1 + group 2 + group 3
+   # ... and so on
+   ```
+
+4. **Push all branches:**
+   ```bash
+   git push -u origin pr/<name-1>
+   git push -u origin pr/<name-2>
+   # ... etc.
+   ```
+
+5. **Create draft PRs using the standard template:**
+   Number each PR in the title (e.g., "PR 1/4: ..."). Include merge order guidance in the body.
+
+   ```bash
+   gh pr create --head pr/<name> --base develop --draft \
+     --title "PR 1/N: <descriptive title>" \
+     --body "$(cat <<'EOF'
+   ## Summary
+
+   [Brief description of what this PR adds]
+
+   > **Merge order:** This is PR X of N. Merge in sequence: **1 → 2 → 3 → ...** (use "Update branch" before merging each subsequent PR).
+
+   ## Changes
+
+   - [List of changes]
+
+   ## Testing
+
+   - [How it was tested]
+
+   ## Checklist
+
+   By submitting this pull request, I acknowledge that I have attempted to meet the following:
+
+   > - a self-review of my code
+   > - commented code particularly in hard-to-understand areas
+   > - corresponding changes to the documentation where required
+   > - changes tested to the best of my ability
+   > - no new errors or non-functional code
+   EOF
+   )"
+   ```
+
+6. **Restore sensitive files:**
+   ```bash
+   # Switch to the last PR branch (or whichever the user wants)
+   git checkout pr/<last-branch>
+   # Restore backed-up files
+   cp /tmp/branch-split-backup/* <original-locations>/
+   # Verify they're gitignored
+   git status --short
+   ```
+
+7. **Show the user a summary table:**
+   - PR number, branch name, GitHub URL
+   - Net-new commits per PR
+   - Merge order instructions
+
+## Common Pitfalls
+
+- Cherry-pick ranges use `^..` syntax: `git cherry-pick A^..B` picks A through B inclusive
+- Untracked files in the working tree can block cherry-picks if a commit creates the same file — always clean them out first and restore after
+- If cherry-pick conflicts occur, resolve them and `git cherry-pick --continue`
+- Always verify sensitive files are gitignored after restoring them

.claude/skills/split-branch-into-prs/Workflows/merge-workflow-guide.md

@@ -0,0 +1,37 @@
+# Merge Workflow Guide
+
+Instructions to give the user for merging the stacked PRs after creation.
+
+## Present This to the User
+
+After all PRs are created, explain the merge workflow:
+
+### How to Merge (repeat for each PR in order)
+
+1. **Review** the PR diff on GitHub — it should only show that PR's net-new changes
+2. **Squash & merge** the PR into develop
+3. On the **next PR**, click **"Update branch"** (the merge option, not rebase) — this pulls the newly merged develop into the PR branch
+4. The PR diff will automatically update to show only net-new changes
+5. Repeat from step 1
+
+### Why This Works
+
+- Each PR branch contains all prior groups' commits (stacked)
+- After squash-merging PR N, develop has all of PR N's content
+- "Update branch" on PR N+1 merges develop in — git resolves the duplicate content cleanly since the files are identical
+- The PR diff only compares the branch tip vs develop, so it shows only net-new changes
+- Since you're squash-merging, the duplicate commit history in the branch doesn't matter — only the final diff counts
+
+### Fixing Quality Gate Failures
+
+If a PR fails linting, tests, or other checks:
+
+- **Fix it on the PR where the code was introduced** — not on a later PR
+- Push the fix commit to that PR's branch
+- The fix will flow forward to later PRs when they do "Update branch" after the fixed PR is merged
+
+### Key Points
+
+- Always use **"Update branch"** (merge), not "Update with rebase" — simpler, no force-push needed
+- Always **squash & merge** — this is what makes the stacked approach work
+- The commit history on PR branches looks duplicated, but the GitHub diff and squash result are clean

.claude/skills/story-implementer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: story-implementer
+description: "Implements user stories from a user_stories directory in dependency order using subagents. Reads README.md to find the next unchecked story, spawns Agent tool subagents to implement each one, tracks progress via scenario checkboxes in story files and story checkboxes in README. Trigger phrases: implement stories, implement user stories, story implementer, work on stories, implement next story. Do NOT invoke for: writing user stories (use write-user-stories), general code changes, checklist execution."
+---
+
+Implement user stories from: $ARGUMENTS
+
+**Role**: You are an implementation orchestrator. You read a user stories README.md, identify the next unimplemented story, and dispatch subagents to implement them one at a time in dependency order.
+
+## Input
+
+$ARGUMENTS should be a path to either:
+- A `user_stories/README.md` file, OR
+- A `user_stories/` directory (read README.md inside it), OR
+- A feature-docs directory containing a `user_stories/` subfolder
+
+If no argument is provided, look for the most recently modified directory under `feature-docs/` that contains `user_stories/README.md`.
+
+## Orchestration Algorithm
+
+### Step 1: Read README.md and locate context
+
+1. Read the `user_stories/README.md` file
+2. Extract the path to the requirements document from the NOTE line at the top
+3. Identify the base directory (the parent of `user_stories/`)
+
+### Step 2: Find the next unchecked story
+
+1. Go to the "Suggested Implementation Order" section
+2. Find the first line matching `- [ ] **US-XXX**`
+3. Extract the story ID (e.g., `US-001`)
+4. If no unchecked stories remain, report completion to the user and stop
+
+### Step 3: Read the story file and assess size
+
+1. Find the story file matching the ID in the `user_stories/` directory (e.g., `US-001-*.md`)
+2. Read the story file
+3. Count the number of `- [ ]` scenario checkboxes in the Acceptance Criteria section
+4. Decide the implementation strategy:
+   - **8 or fewer unchecked scenarios**: Send ALL to a single subagent
+   - **More than 8 unchecked scenarios**: Split into batches of 4-6 scenarios, send to sequential subagents
+
+### Step 4: Dispatch subagent(s)
+
+Read the workflow template from `.claude/skills/story-implementer/Workflows/implement-story.md` and construct the subagent prompt by substituting the variables.
+
+Use the **Agent tool** to spawn the subagent. Pass the constructed prompt as the `prompt` parameter.
+
+**For a single subagent (all scenarios fit):**
+- Pass the full story file content
+- Pass the requirements document path
+- Pass the list of ALL scenario numbers to implement
+- Pass the story file path (so subagent can check off scenarios)
+
+**For batched scenarios:**
+- For each batch:
+  - Pass the full story file content
+  - Pass the requirements document path
+  - Pass the specific scenario numbers for THIS batch only (e.g., "Scenarios 1-4")
+  - Pass the story file path
+  - Add batch note: "This is batch N of M. Only implement the specified scenarios."
+  - After each batch subagent completes, re-read the story file to verify the scenarios were checked off
+  - Then dispatch the next batch
+
+### Step 5: Verify story completion
+
+After the subagent(s) finish:
+1. Re-read the story file
+2. Verify ALL scenario checkboxes are `[x]`
+3. If any scenarios remain unchecked, report which ones to the user and ask whether to retry or skip
+
+### Step 6: Mark story complete and commit
+
+1. In `user_stories/README.md`, change the line `- [ ] **US-XXX**` to `- [x] **US-XXX**`
+2. Stage all changes and commit with message: `feat: implement US-XXX - <story title>`
+   - Include `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`
+3. Report to the user: which story was completed, summary of what was implemented
+
+### Step 7: Loop
+
+Return to Step 2 to find the next unchecked story. Continue until all stories are implemented or the user interrupts.
+
+## Rules
+
+- Implement stories strictly in the order listed in the README (respect dependency chain)
+- Never skip a story without user approval
+- Always re-read README.md fresh before each iteration (it may have been modified)
+- Each subagent MUST follow all CLAUDE.md rules (tests for backend, proper typing, no placeholders, update docs-md)
+- Auto-commit after each STORY (not each scenario)
+- If a subagent encounters a question or ambiguity, it should surface it to the user rather than making assumptions
+- Do not modify the story file format beyond checking off scenario checkboxes
+- The orchestrator never implements code directly — always delegate to subagents via Agent tool
+
+## Workflow Reference
+
+- [Implement a single story](Workflows/implement-story.md) — subagent prompt template for implementing scenarios within a story