Merge origin/main into vit-fixSyncVersionsSubmodule

Author: mountiny

.claude/agents/code-inline-reviewer.md

@@ -129,6 +129,10 @@ removeDeployBlockerLabel.sh "$ISSUE_URL" DeployBlocker      # For Frontend bugs
 
 Call scripts by name only (e.g., `removeDeployBlockerLabel.sh`), not with full paths.
 
+### Step 8: Assign contributors
+
+When a causing PR is identified with medium or high confidence, assign the PR author and all approving reviewers to the deploy blocker issue using `gh issue edit "$ISSUE_URL" --add-assignee`. Extract approving reviewers from `gh pr view <PR_NUMBER> --json reviews`.
+
 ---
 
 ## Decision Tree
@@ -182,6 +186,7 @@ Post ONE comment using this exact format:
 Brief explanation of why this recommendation (1-2 sentences).
 
 
+**Assigned**: @author (PR author), @reviewer (approving reviewer) — or omit if no causing PR identified
 **Labels**: [Describe any label changes made]
 
 <details>

.claude/agents/deploy-blocker-investigator.md

@@ -9,54 +9,35 @@ model: inherit
 
 You are **Support Doc Optimizer** — an AI trained to evaluate HelpDot articles written for Expensify and create inline comments for specific violations.
 
-Your job is to scan through changed documentation files and create **inline comments** for specific violations based on the three core criteria below.
-
-## 1. Readability Violations (Create inline comments for)
-- Poor sentence clarity, grammar, or scannability issues
-- Illogical flow or ordering of sections  
-- Reading level above 8th grade (complex jargon)
-- Unnecessary filler or verbose language
-- Incorrect use of numbered steps or bullet points
-
-## 2. AI Readiness Violations (Create inline comments for)
-- Vague headings without full feature names (e.g., "Enable it", "Connect to it")
-- Non-descriptive headings (e.g., "Where to find it" vs "Where to find Statement Matching")  
-- Vague references like "this," "that," or "it" without clear context
-- Missing or incomplete YAML metadata:
-```yaml
----
-title: [Full article title]
-description: [Concise, benefit-focused summary] 
-keywords: [feature name, related terms, navigation path, etc.]
----
-```
-- Missing breadcrumb paths below H1 (Settings > Workspaces > People)
-- Wrong heading levels (using ### or deeper instead of # or ##)
-
-## 3. Expensify Style Compliance Violations (Create inline comments for)
-- Voice and tone issues:
-  - Not casual yet professional
-  - Excessive exclamation marks (max 1 per 400 words)
-- Terminology violations:
-  - "Policy" instead of "Workspace"
-  - "User" instead of "Member"  
-  - Wrong role names (not "Workspace Admin," "Domain Owner")
-- Button label violations:
-  - "Continue" instead of "Next"
-  - "Save" instead of "Confirm" at end of flows
-- Markdown formatting violations
-- FAQ structure violations:
-  - Not using "# FAQ" as heading
-  - Questions not using ## subheadings
-  - Answers not in plain text
+Your job is to scan through changed documentation files and create **inline comments** for specific violations. **All rules and criteria come from the help site governance files** — you must use them as the single source of truth.
+
+## Governance (source of truth)
+
+**Before reviewing, read these files and use them as the authoritative source for all rules and violations:**
+
+1. **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing (buttons, tabs, menus, navigation), button/tab naming standards, three dots menu rule, navigation instructions, prohibited language, deterministic writing.
+2. **docs/HELP_AUTHORING_GUIDELINES.md** — Article structure, heading rules, metadata requirements, step formatting, AI retrieval optimization, cross-linking, screenshot placeholders, pre-publish validation.
+3. **docs/TEMPLATE.md** — Required YAML frontmatter pattern, heading guidance, FAQ structure, and structural expectations.
+
+Create inline comments for any violation of the rules defined in those governance files. When in doubt, the governance docs override any other guidance.
+
+**CRITICAL — Review only the proposed changes:** You must evaluate and comment only on the **diff** (the lines added or modified in the PR). Do NOT create inline comments on lines that are unchanged—those belong to the old file and are not part of the proposal. Use `gh pr diff` to know exactly which lines were changed; only create comments on those line numbers. Commenting on unchanged lines is out of scope and can fail or confuse the author.
+
+### Violation categories (aligned with governance)
+
+- **Readability / structure:** Clarity, flow, scannability, step formatting, heading hierarchy — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md.
+- **AI readiness:** Task-based headings, full feature names, YAML metadata (title, description, keywords, **internalScope**), no generic headings — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. (Breadcrumb paths after H1 are not required; do not flag their absence.)
+- **Naming and style:** Exact UI labels, button/tab naming, terminology (e.g. Workspace not Policy, Member not User), navigation phrasing, prohibited language — per HELPSITE_NAMING_CONVENTIONS.md and HELP_AUTHORING_GUIDELINES.md. FAQ must use `# FAQ` and ## for questions per TEMPLATE.md.
 
 ## Instructions
 
-1. **First, get the list of changed files:**
-   - Use `gh pr diff` to see what actually changed in the PR
-   - Focus ONLY on documentation files (*.md, *.csv, etc.)
+1. **Get the diff and scope (required):**
+   - Use `gh pr diff` to see the exact lines added or modified in the PR
+   - Identify which file paths and line numbers are in the diff—these are the **only** lines you may comment on
+   - Focus only on documentation files (*.md, *.csv, etc.)
 
 2. **For analyzing changed files:**
+   - **Restrict analysis to the diff:** When checking for violations, evaluate only content that appears on added or modified lines. If you read a full file for context, do not create inline comments on line numbers that are not part of the diff.
    - **Use a hybrid approach** because different violations require different analysis methods:
      - **Grep is suitable for pattern-based violations only:**
        - Terminology violations ("policy" → "workspace", "user" → "member")
@@ -75,7 +56,7 @@ keywords: [feature name, related terms, navigation path, etc.]
 
 4. **Required parameters for each inline comment:**
    - `path`: Full file path (e.g., "docs/articles/new-expensify/chat/Create-a-New-Chat.md")
-   - `line`: Line number where the issue occurs
+   - `line`: Line number where the issue occurs — **must be a line that appears in the PR diff (added or modified)**. Do not use line numbers from unchanged portions of the file.
    - `body`: Concise description of the violation and fix
 
 ## Tool Usage Example

.claude/agents/helpdot-inline-reviewer.md

@@ -9,30 +9,30 @@ model: inherit
 
 You are a documentation quality specialist that provides comprehensive assessments of HelpDot documentation changes.
 
-Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations.
+Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations. **All scoring criteria and rules come from the help site governance files** — use them as the single source of truth.
+
+## Governance (source of truth)
+
+**Before reviewing, read these files and use them as the authoritative source for scoring and recommendations:**
+
+1. **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing, button/tab naming, navigation rules, prohibited language.
+2. **docs/HELP_AUTHORING_GUIDELINES.md** — Structure, heading rules, metadata, steps, AI retrieval, cross-linking, validation checklist.
+3. **docs/TEMPLATE.md** — YAML frontmatter, heading guidance, FAQ structure.
+
+**CRITICAL — Review only the proposed changes:** Base your assessment, scores, and recommendations **only on the changes being proposed** in the PR (the diff). Use `gh pr diff` to see what was added or modified. Do not score or critique unchanged portions of the file—those are from the old version and are not part of the proposal. Evaluate and feedback only on the diff.
 
 ## Scoring Criteria
 
+Derive your scores from the governance files above:
+
 ### 1. Readability (1-10)
-- Sentence clarity and grammar
-- Logical flow and organization  
-- Appropriate reading level (8th grade or below)
-- Clear, jargon-free language
-- Proper use of formatting elements
-
-### 2. AI Readiness (1-10) 
-- Descriptive headings with full feature names
-- Clear context without vague references
-- Proper YAML metadata structure
-- Breadcrumb navigation paths
-- Consistent heading hierarchy (# and ## only)
+- Sentence clarity, flow, scannability, step formatting — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md.
+
+### 2. AI Readiness (1-10)
+- Task-based headings, full feature names, YAML metadata (including **internalScope**), heading hierarchy (# and ## only) — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. (Breadcrumb paths after H1 are not required; do not penalize for their absence.)
 
 ### 3. Style Compliance (1-10)
-- Expensify voice and tone standards
-- Correct terminology (workspace, member, etc.)
-- Proper button labels and UI terms
-- Markdown formatting compliance
-- FAQ structure adherence
+- Exact UI terminology, button/tab naming, terminology (e.g. Workspace, Member), navigation phrasing, FAQ structure — per HELPSITE_NAMING_CONVENTIONS.md and HELP_AUTHORING_GUIDELINES.md.
 
 ## Output Format
 
@@ -64,9 +64,10 @@ Provide your assessment as a **top-level PR comment** using this format:
 
 ## Instructions
 
-1. **Analyze all changed documentation files**
-2. **Look for patterns and overall quality trends**
-3. **Provide balanced feedback** (both positive and areas for improvement)
-4. **Focus on the big picture** rather than individual line issues
-5. **Use Bash(gh pr comment:*) tool** to post the summary comment
-6. **Reference that inline comments provide specific details**
+1. **Get the diff first:** Use `gh pr diff` to see the exact proposed changes. Your entire assessment (scores, findings, recommendations) must be based only on added or modified lines—not on unchanged content from the old file.
+2. **Analyze only the proposed changes** in each documentation file
+3. **Look for patterns and overall quality trends** within the diff
+4. **Provide balanced feedback** (both positive and areas for improvement) — only for the proposed changes
+5. **Focus on the big picture** rather than individual line issues
+6. **Use Bash(gh pr comment:*) tool** to post the summary comment
+7. **Reference that inline comments provide specific details**

.claude/agents/helpdot-summary-reviewer.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Bash(gh issue view:*),Bash(gh issue comment:*),Bash(gh issue list:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh pr diff:*),Bash(gh api:*),Bash(git log:*),Bash(git show:*),Bash(git blame:*),Bash(removeDeployBlockerLabel.sh:*),Glob,Grep,Read
+allowed-tools: Bash(gh issue view:*),Bash(gh issue comment:*),Bash(gh issue edit:*),Bash(gh issue list:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh pr diff:*),Bash(gh api:*),Bash(git log:*),Bash(git show:*),Bash(git blame:*),Bash(removeDeployBlockerLabel.sh:*),Glob,Grep,Read
 description: Investigate a deploy blocker issue to find the causing PR and recommend resolution
 ---
 

.claude/commands/investigate-deploy-blocker.md

@@ -1,5 +1,5 @@
 ---
-allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(addPrReaction.sh:*),Bash(createInlineComment.sh:*)
+allowed-tools: Bash(gh pr diff:*),Bash(gh pr view:*),Bash(check-compiler.sh:*)
 description: Review a code contribution pull request
 ---
 
@@ -8,10 +8,13 @@ Perform a comprehensive PR review using a specialized subagent:
 ## Inline Review
 Use the code-inline-reviewer agent to:
 - Scan all changed source code files
-- Create inline comments for specific review rule violations
-- Focus on line-specific, actionable feedback
+- Detect review rule violations with line-specific, actionable feedback
 
-Run the agent and ensure its feedback is posted to the PR.
+Run the agent. It will return structured JSON with any violations found.
+
+## Output
+Return the subagent's violations JSON as your structured output unchanged.
+Do NOT post comments or reactions yourself - the workflow handles that.
 
 <important>
 Keep feedback concise.

.claude/commands/review-code-pr.md

@@ -3,17 +3,21 @@ allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),mcp__
 description: Review a HelpDot documentation pull request
 ---
 
-Perform a comprehensive HelpDot documentation review using two specialized subagents:
+Perform a comprehensive HelpDot documentation review using two specialized subagents. Both reviewers use the **help site governance files** in the repo as the source of truth for rules and scoring:
+
+- **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing, button/tab naming, navigation
+- **docs/HELP_AUTHORING_GUIDELINES.md** — Structure, headings, metadata, AI retrieval, validation
+- **docs/TEMPLATE.md** — YAML frontmatter, heading guidance, FAQ structure
 
 ## Step 1: Inline Review
 Use the helpdot-inline-reviewer agent to:
 - Scan all changed documentation files
-- Create inline comments for specific HelpDot rule violations
+- Create inline comments for violations of the governance rules above
 - Focus on line-specific, actionable feedback
 
 ## Step 2: Summary Review  
 Use the helpdot-summary-reviewer agent to:
-- Analyze the overall quality of all changes
+- Analyze the overall quality of all changes using the governance criteria
 - Provide comprehensive assessment with scoring
 - Post one top-level PR comment with summary and recommendations
 

.claude/commands/review-helpdot-pr.md

@@ -0,0 +1,27 @@
+{
+    "type": "object",
+    "properties": {
+        "violations": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "ruleId": {
+                        "type": "string"
+                    },
+                    "path": {
+                        "type": "string"
+                    },
+                    "line": {
+                        "type": "integer"
+                    },
+                    "body": {
+                        "type": "string"
+                    }
+                },
+                "required": ["ruleId", "path", "line", "body"]
+            }
+        }
+    },
+    "required": ["violations"]
+}

.claude/schemas/code-review-output.json

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# Secure proxy script to run React Compiler compliance check on a single file.
+# Validates the filepath before passing it to the underlying npm script.
+set -eu
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <filepath>" >&2
+    exit 1
+fi
+
+readonly FILEPATH="$1"
+
+# Strict filepath validation - reject shell metacharacters
+if ! [[ "$FILEPATH" =~ ^[a-zA-Z0-9_./@-]+$ ]]; then
+    echo "Error: Invalid filepath (contains disallowed characters)" >&2
+    exit 1
+fi
+
+npm run react-compiler-compliance-check -- check "$FILEPATH"

.claude/scripts/check-compiler.sh

@@ -3,7 +3,7 @@
 # Secure proxy script to create an inline comment on a GitHub PR.
 set -eu
 
-readonly ALLOWED_RULES_FILE="${GITHUB_WORKSPACE}/.claude/allowed-rules.txt"
+readonly ALLOWED_RULES_FILE="${ALLOWED_RULES_FILE:-${GITHUB_WORKSPACE}/.claude/allowed-rules.txt}"
 
 # Print error and exit.
 die() {
@@ -25,7 +25,7 @@ validate_rule() {
 
     [[ -f "$ALLOWED_RULES_FILE" ]] || die "Comment rejected: allowed rules file missing at $ALLOWED_RULES_FILE"
 
-    rule=$(echo "$body" | grep -oE '[A-Z]+-[0-9]+' | head -1 || true)
+    rule=$(echo "$body" | grep -oE '[A-Z]+(-[A-Z]+)*-[0-9]+' | head -1 || true)
     [[ -n "$rule" ]] || die "Comment rejected: missing allowed rule reference (e.g. PERF-1)"
 
     if grep -qF "$rule" "$ALLOWED_RULES_FILE"; then
@@ -47,11 +47,12 @@ readonly LINE_ARG="${3:-}"
 validate_rule "$BODY_ARG"
 echo "Comment approved: $COMMENT_STATUS_REASON"
 
-readonly FOOTER=$'\n\n---\n\nPlease rate this suggestion with 👍 or 👎 to help us improve! Reactions are used to monitor reviewer efficiency.'
-readonly COMMENT_BODY="${BODY_ARG}${FOOTER}"
-
 COMMIT_ID=$(gh api "/repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '.head.sha')
 readonly COMMIT_ID
+readonly SHORT_SHA="${COMMIT_ID:0:7}"
+
+readonly FOOTER=$'\n\n---\n\n'"Reviewed at: [${SHORT_SHA}](https://github.com/${GITHUB_REPOSITORY}/commit/${COMMIT_ID}) | Please rate this suggestion with 👍 or 👎 to help us improve! Reactions are used to monitor reviewer efficiency."
+readonly COMMENT_BODY="${BODY_ARG}${FOOTER}"
 
 PAYLOAD=$(jq -n \
     --arg body "$COMMENT_BODY" \