[AAASM-3944] ✨ (scripts): Add validation script for AI onboarding scaffold

[Chisanan232]

Jira Ticket

• AAASM-3944

Summary

• Adds scripts/validate-ai-workspace.sh, the companion validator for the AI onboarding scaffold installed by bootstrap-ai-workspace.sh (AAASM-3943), per the layout in .claude/WORKSPACE.md (AAASM-3939). Depends on [AAASM-3939] 📝 (workspace): Add org-level AI workspace layout doc #25, [AAASM-3940] ✨ (docs): Add org-level CLAUDE.md and AGENTS.md baseline #26, [AAASM-3943] ✨ (scripts): Add bootstrap script for org AI config #29 (stacked on AAASM-3943).

Changes

• scripts/validate-ai-workspace.sh: checks a workspace root for CLAUDE.md, AGENTS.md, .claude/rules/, and .claude/skills/, classifying each as Missing / Broken symlink / Local override / OK. Local overrides are reported for visibility but do not fail validation, matching the override philosophy from AAASM-3941/3943. Also sweeps the workspace's .claude/ tree for other broken symlinks, and accepts optional repo-path arguments for a lightweight, informational check of each repo's own .claude/CLAUDE.md and AGENTS.md. Exits 0 when everything is present/correctly linked (overrides included), exits 1 if anything is missing or broken — usable as a CI gate.
• scripts/README.md: replaces the "not yet built" placeholder with usage docs for the new script.

Validation

• Content reviewed for accuracy
• Links verified
• No unintended scope changes

Manually tested three scenarios against a real bootstrap run:

1. Clean bootstrap into a fresh temp dir → validate: all 4 items OK, exit 0.
2. Broke AGENTS.md's symlink target and replaced .claude/skills with a real local directory → validate: 1 broken symlink + 1 local override reported, exit 1 (broken symlink correctly fails; override alone was separately confirmed to still exit 0).
3. Never-bootstrapped directory (and a wholly nonexistent path) → validate: all 4 items reported missing, exit 1.

Also verified bash -n syntax check passes and the script is careful about bash 3.2 (macOS default /bin/bash) empty-array-under-set -u pitfalls.

Checklist

• PR title follows: [<ticket ID>] <GitEmoji> (<change scope category>): <key point as summary>
• PR body follows this template

[Chisanan232]

Claude Code review — AAASM-3944

CI: Red, same org-wide Actions billing-block (see #25) — not caused by this change.

Scope vs ticket: Mostly matches AAASM-3944's AC (missing/broken/repo-gap reporting, useful exit codes, README docs) — but I found one real, verified mismatch while reading the code directly: .claude/WORKSPACE.md (#25) states the validation script "reports which org-level files are shadowed" by a repo-local override by filename (i.e. per-file, e.g. a single .claude/rules/01-security.md override). The actual check_item() in validate-ai-workspace.sh only ever checks the 4 top-level paths (CLAUDE.md, AGENTS.md, .claude/rules, .claude/skills) as whole units — a per-file override inside those directories is never detected. This is the same defect independently caught during #32's dogfooding pass (tracked as follow-up item #3 in #33) — confirmed here by reading both files side by side, not just taking that finding at face value.

Not a regression, not a security issue — the script fails safe (under-reports overrides rather than mis-reporting something as broken), it just under-delivers on a promise made in a sibling PR's doc. Two ways to close it: (a) extend check_item to walk each file inside .claude/rules/ and .claude/skills/ individually, or (b) correct WORKSPACE.md's wording to describe directory-level (not per-file) override detection. Your call whether to block this PR on it or take it as a tracked follow-up — I'd lean toward merging as-is and filing the fix, since it's a documentation-accuracy gap, not broken behavior.

Side effects: None.

Frontend: N/A.

Recommend: mergeable, with the override-detection gap called out above for a decision.