chore: sync skills + emit-schema scripts from socket-repo-template@563fd6a

Refresh:
- `.claude/skills/quality-scan/SKILL.md` — junior-dev-friendly
  rewrite of the quality-scan skill from socket-repo-template.
- `.claude/skills/updating/SKILL.md` — same, for the updating
  skill.
- `scripts/{xport,socket-repo-template}-emit-schema.mts` — both
  emitters now `pnpm exec oxfmt` their output so the emitted
  schema matches what oxfmt produces. Without this, every fleet
  repo that re-emits would flag the schema as drifted on
  `pnpm run check --all`.
- `xport.schema.json` + `socket-repo-template-schema.json` — re-
  emitted with the formatter applied.

All synced byte-identical from socket-repo-template via
sync-scaffolding.

Author: jdalton

.claude/skills/quality-scan/SKILL.md

@@ -1,59 +1,84 @@
 ---
 name: quality-scan
-description: Runs comprehensive quality scans across the codebase using specialized agents to identify critical bugs, logic errors, caching issues, and workflow problems. Use when improving code quality, before releases, or investigating issues.
+description: Scans the codebase for bugs, logic errors, caching issues, and workflow problems using specialized agents. Use when preparing for release, investigating quality issues, or running pre-merge checks.
+user-invocable: true
+allowed-tools: Task, Read, Grep, Glob, AskUserQuestion, Bash(pnpm run check:*), Bash(pnpm run test:*), Bash(pnpm test:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Bash(ls:*)
 ---
 
 # quality-scan
 
-<task>
-Performs comprehensive quality scans across the codebase, cleaning up junk files
-and spawning specialized agents for targeted analysis. Generates a prioritized
-report with actionable improvement tasks.
-</task>
-
-<constraints>
-- Analysis phase is read-only; do not fix issues during scan.
-- Must complete all enabled scans before reporting.
-- Findings prioritized by severity (Critical > High > Medium > Low).
-- All findings must include file:line references and suggested fixes.
-- Run `pnpm test` after each fix iteration.
-- Cap at 5 iterations; stop and report if issues persist.
-</constraints>
-
-## Phases
-
-1. **Validate Environment** — `git status`; follow `_shared/env-check.md`.
-2. **Update Dependencies** — `pnpm run update`; continue even if it fails.
-3. **Install External Tools** — See `_shared/security-tools.md` for zizmor; use `pnpm run setup`.
-4. **Repository Cleanup** — Glob for junk files (SCREAMING_TEXT.md, temp files, editor backups); confirm before deletion.
-5. **Structural Validation** — `pnpm run check`; report errors as Critical findings.
-6. **Determine Scan Scope** — Ask user: all scans, critical only, or custom selection. CI mode runs all automatically.
-7. **Execute Scans** — Spawn agents sequentially via Agent tool using prompts from [reference.md](reference.md). Apply `agents/code-reviewer.md` rules for code scans, `agents/security-reviewer.md` for security scans.
-8. **Aggregate Findings** — Deduplicate across scans, sort by severity then scan type.
-9. **Generate Report** — Summary table by severity + scan type, display to user.
-10. **Fix All Issues** — Apply fixes from Critical to Low; read each file before editing.
-11. **Run Tests** — `pnpm test`; revert and exit iteration on failure.
-12. **Commit Fixes** — Stage and commit with summary of fixed issue counts.
-13. **Iteration Decision** — Zero issues = done; otherwise loop back to Phase 7.
-
-## Available Scans
-
-See [reference.md](reference.md) for detailed agent prompts. Scan types:
-
-- **critical** — Crashes, security vulnerabilities, resource leaks, data corruption
-- **logic** — Algorithm errors, edge cases, type guards, off-by-one errors
-- **cache** — Cache staleness, race conditions, invalidation bugs
-- **workflow** — Build scripts, CI issues, cross-platform compatibility
-- **security** — GitHub Actions workflow security via zizmor + credential exposure
-- **documentation** — README accuracy, outdated docs, missing documentation
-
-## Scan Scope
-
-Primary: `src/`, `scripts/`, `test/`, `.github/workflows/`
-Excluded: `node_modules/`, `dist/`, `.pnpm-store/`
-
-## Error Recovery
-
-- **Scan agent failure**: Log warning, continue remaining scans.
-- **Test failure after fixes**: `git restore .`, report failures, exit iteration.
-- **Git commit failure**: Display error, ask user to resolve.
+Perform comprehensive quality analysis across the codebase using specialized agents. Clean up junk files first, then scan and generate a prioritized report with actionable fixes.
+
+## Scan Types
+
+1. **critical** - Crashes, security vulnerabilities, resource leaks, data corruption
+2. **logic** - Algorithm errors, edge cases, type guards, off-by-one errors
+3. **cache** - Cache staleness, race conditions, invalidation bugs
+4. **workflow** - Build scripts, CI issues, cross-platform compatibility
+5. **workflow-optimization** - CI optimization (build-required conditions on cached builds)
+6. **security** - GitHub Actions workflow security (zizmor scanner)
+7. **documentation** - README accuracy, outdated docs, missing documentation
+8. **patch-format** - Patch file format validation
+
+Agent prompts for each scan type are in `reference.md`.
+
+## Process
+
+### Phase 1: Validate Environment
+
+```bash
+git status
+```
+
+Warn about uncommitted changes but continue (scanning is read-only).
+
+### Phase 2: Update Dependencies
+
+```bash
+pnpm run update
+```
+
+Only update the current repository. Continue even if update fails.
+
+### Phase 3: Install zizmor
+
+Install zizmor for GitHub Actions security scanning, respecting the soak window — pnpm-workspace.yaml `minimumReleaseAge` in minutes, default 10080 (= 7 days). Query GitHub releases, find the latest stable release older than the threshold, and install via pipx/uvx. Skip the security scan if no release meets the soak requirement.
+
+### Phase 4: Repository Cleanup
+
+Find and remove junk files (with user confirmation via AskUserQuestion):
+- SCREAMING_TEXT.md files outside `.claude/` and `docs/`
+- Test files in wrong locations
+- Temp files (`.tmp`, `.DS_Store`, `*~`, `*.swp`, `*.bak`)
+- Log files in root/package directories
+
+### Phase 5: Structural Validation
+
+```bash
+node scripts/check-consistency.mjs
+```
+
+Report errors as Critical findings. Warnings are Low findings.
+
+### Phase 6: Determine Scan Scope
+
+Ask user which scans to run using AskUserQuestion (multiSelect). Default: all scans.
+
+### Phase 7: Execute Scans
+
+For each enabled scan type, spawn a Task agent with the corresponding prompt from `reference.md`. Run sequentially in priority order: critical, logic, cache, workflow, then others.
+
+Each agent reports findings as:
+- File: path:line
+- Issue, Severity, Pattern, Trigger, Fix, Impact
+
+### Phase 8: Aggregate and Report
+
+- Deduplicate findings across scan types
+- Sort by severity: Critical > High > Medium > Low
+- Generate markdown report with file:line references, suggested fixes, and coverage metrics
+- Offer to save to `reports/quality-scan-YYYY-MM-DD.md`
+
+### Phase 9: Summary
+
+Report final metrics: dependency updates, structural validation results, cleanup stats, scan counts, and total findings by severity.

.claude/skills/updating/SKILL.md

@@ -1,21 +1,45 @@
 ---
 name: updating
-description: Updates all npm dependencies to their latest versions. Triggers when user asks to "update dependencies", "update packages", or prepare for a release.
+description: Umbrella update skill for a Socket fleet repo. Runs `pnpm run update` (npm), validates `xport.json` via `pnpm run xport` (if present), optionally bumps submodules, and checks workflow SHA pins. Use when asked to update dependencies, sync upstreams, or prepare for a release.
 user-invocable: true
-allowed-tools: Bash(pnpm:*), Bash(npm:*), Bash(git:*), Bash(node:*), Bash(rg:*), Bash(grep:*), Bash(find:*), Bash(ls:*), Bash(cat:*), Bash(head:*), Bash(tail:*), Bash(wc:*), Bash(diff:*), Read, Grep, Glob, Edit---
+allowed-tools: Task, Skill, Read, Edit, Grep, Glob, Bash(pnpm run:*), Bash(pnpm test:*), Bash(pnpm install:*), Bash(git:*), Bash(claude --version)
+---
 
 # updating
 
 <task>
-Your task is to update all npm dependencies to their latest versions, ensuring all builds and tests pass.
+Update all dependencies for this repo: npm packages first, then the
+xport-managed version pins (if `xport.json` exists), then any other
+submodules tracked via `.gitmodules`, and finally verify workflow
+SHA pins are current. Validate with the full check/test suite before
+committing. The sub-skill delegation mirrors the canonical
+socket-registry `updating` skill; uncomment the phases that apply to
+this repo and delete those that don't.
 </task>
 
 <context>
 **What is this?**
-This skill updates npm packages for security patches, bug fixes, and new features.
+The umbrella update skill. Runs `pnpm run update` for npm deps, then
+adapts to what the repo has:
 
 **Update Targets:**
-- npm packages via `pnpm run update`
+- **npm packages** — via `pnpm run update` (every Socket repo has this script)
+- **xport-managed upstreams** — via `pnpm run xport` when `xport.json` exists
+  (manifest-managed submodule pins + advisory drift on file-fork /
+  feature-parity / spec-conformance / lang-parity rows)
+- **Other submodules** — via repo-specific `updating-*` sub-skills
+  when `.gitmodules` has entries not claimed by xport version-pin rows
+- **Workflow SHA pins** — check `_local-not-for-reuse-*.yml` against
+  `origin/main`; run the `updating-workflows` skill when stale
+
+**Key files this skill consults:**
+- `xport.json` — if present, drives version-pin bumps and surfaces drift
+- `.gitmodules` — listed submodules; xport's `version-pin` rows take precedence
+- `.github/workflows/_local-not-for-reuse-*.yml` — SHA pin sources
+- `package.json` — `pnpm run update` script
+
+Sub-skills are invoked only when applicable — this umbrella reads repo
+state first to discover what to run.
 </context>
 
 <constraints>
@@ -32,7 +56,9 @@ This skill updates npm packages for security patches, bug fixes, and new feature
 
 **Actions:**
 - Update npm packages
-- Create atomic commits
+- Apply xport-driven bumps (if `xport.json` present)
+- Bump remaining submodules (if any)
+- Create atomic commits per category
 - Report summary of changes
 </constraints>
 
@@ -42,44 +68,18 @@ This skill updates npm packages for security patches, bug fixes, and new feature
 
 ### Phase 1: Validate Environment
 
-<action>
-Check working directory is clean and detect CI mode:
-</action>
-
-```bash
-# Detect CI mode
-if [ "$CI" = "true" ] || [ -n "$GITHUB_ACTIONS" ]; then
-  CI_MODE=true
-  echo "Running in CI mode - will skip build validation"
-else
-  CI_MODE=false
-  echo "Running in interactive mode - will validate builds"
-fi
-
-# Check working directory is clean
-git status --porcelain
-```
-
-<validation>
-- Working directory must be clean
-- CI_MODE detected for subsequent phases
-</validation>
+Check clean working directory, detect CI mode (`CI=true` or
+`GITHUB_ACTIONS`), verify submodules initialized (if any).
 
 ---
 
 ### Phase 2: Update npm Packages
 
-<action>
-Run pnpm run update to update npm dependencies:
-</action>
-
 ```bash
-# Update npm packages
 pnpm run update
 
-# Check if there are changes
-if [ -n "$(git status --porcelain pnpm-lock.yaml package.json)" ]; then
-  git add pnpm-lock.yaml package.json
+if [ -n "$(git status --porcelain)" ]; then
+  git add pnpm-lock.yaml package.json */package.json
   git commit -m "chore: update npm dependencies
 
 Updated npm packages via pnpm run update."
@@ -91,47 +91,104 @@ fi
 
 ---
 
-### Phase 3: Final Validation
+### Phase 3: Validate xport manifest (if applicable)
 
-<action>
-Run build and test suite (skip in CI mode):
-</action>
+If `xport.json` exists at repo root, run the harness:
 
 ```bash
-if [ "$CI_MODE" = "true" ]; then
-  echo "CI mode: Skipping final validation (CI will run builds/tests separately)"
-  echo "Commits created - ready for push by CI workflow"
+if [ -f xport.json ]; then
+  pnpm run xport
+  XPORT_EXIT=$?
+
+  case $XPORT_EXIT in
+    0) echo "✓ xport clean — manifest valid, no drift" ;;
+    1) echo "✗ xport schema/structural error — stopping"; exit 1 ;;
+    2) echo "⚠ xport drift — review advisories; not a blocker" ;;
+  esac
+fi
+```
+
+Exit code semantics:
+- **0** — manifest valid, no drift; proceed.
+- **1** — schema violation, missing file, or unreachable baseline. Stop
+  and investigate via `scripts/xport-schema.mts` and the failing row's
+  `local_*`/`upstream` fields. Do not auto-retry.
+- **2** — drift detected. This is an **advisory signal** (upstream
+  advanced, feature-parity score below floor, rejected anti-pattern
+  reintroduced). Review the harness output, file follow-up tasks, and
+  proceed with the update.
+
+If `xport.json` does NOT exist, skip this phase.
+
+---
+
+### Phase 4: Update Upstream Submodules (if applicable)
+
+Invoke each `updating-*` sub-skill that this repo defines. Sub-skills
+handle their own submodule bumps, version detection, and commits.
+
+xport-managed submodules (`version-pin` rows) are auto-bumped in
+Phase 3 via the harness; do NOT also run a dedicated sub-skill for
+them. Only run sub-skills for submodules NOT claimed by xport.
+
+If no `.gitmodules` exists (or all submodules are xport-managed),
+skip this phase.
+
+---
+
+### Phase 5: Check Workflow SHA Pins
+
+Inspect `_local-not-for-reuse-*.yml` files for their pinned SHA and
+compare against `origin/main`:
+
+```bash
+PINNED_SHA=$(grep -ohP '(?<=@)[0-9a-f]{40}' .github/workflows/_local-not-for-reuse-ci.yml 2>/dev/null | head -1)
+MAIN_SHA=$(git rev-parse origin/main 2>/dev/null || echo "")
+
+if [ -n "$PINNED_SHA" ] && [ -n "$MAIN_SHA" ] && [ "$PINNED_SHA" != "$MAIN_SHA" ]; then
+  echo "Workflow SHA pins are stale: $PINNED_SHA → $MAIN_SHA"
+  echo "Run the updating-workflows skill to cascade."
+else
+  echo "Workflow SHA pins are up to date (or no _local-not-for-reuse-*.yml pins in this repo)"
+fi
+```
+
+---
+
+### Phase 6: Final Validation (skip in CI)
+
+```bash
+if [ "$CI" = "true" ] || [ -n "$GITHUB_ACTIONS" ]; then
+  echo "CI mode: skipping validation"
 else
-  echo "Interactive mode: Running full validation..."
-  pnpm run fix --all
   pnpm run check --all
   pnpm test
+  pnpm run build  # if this repo has a build step
 fi
 ```
 
 ---
 
-### Phase 4: Report Summary
-
-<action>
-Generate update report:
-</action>
+### Phase 7: Report Summary
 
 ```
 ## Update Complete
 
 ### Updates Applied:
 
-| Category | Status |
-|----------|--------|
-| npm packages | Updated/Up to date |
+| Category           | Status                               |
+|--------------------|--------------------------------------|
+| npm packages       | Updated / Up to date                 |
+| xport manifest     | <ok>/<total> ok, <drift> drift, <error> error (exit <code>) — or n/a |
+| Other submodules   | K bumped — or n/a                    |
+| Workflow SHA pins  | Up to date / Stale                   |
 
 ### Commits Created:
-- [list commits if any]
+- [list commits, if any]
 
 ### Validation:
-- Build: SUCCESS/SKIPPED (CI mode)
-- Tests: PASS/SKIPPED (CI mode)
+- Build: SUCCESS / SKIPPED (CI mode)
+- Tests: PASS / SKIPPED (CI mode)
 
 ### Next Steps:
 **Interactive mode:**
@@ -149,15 +206,18 @@ Generate update report:
 ## Success Criteria
 
 - All npm packages checked for updates
+- xport manifest validated (when present); schema/structural errors block
 - Full build and tests pass (interactive mode)
 - Summary report generated
 
 ## Context
 
 This skill is useful for:
 
-- Weekly maintenance (automated via weekly-update.yml)
+- Weekly maintenance (automated via `weekly-update.yml`)
 - Security patch rollout
 - Pre-release preparation
 
-**Safety:** Updates are validated before committing. Failures stop the process.
+**Safety:** Updates are validated before committing. Schema errors
+(xport exit 1) stop the process; drift (xport exit 2) is advisory
+and does not block.