…#4035)

* Consolidate Claude config: shared vs personal split + project.md

Add a portable, repo-side convention so each developer can keep personal
Claude config alongside the shared team config without committing it, and
fold project-level knowledge into the committed common config.

- .claude/.gitignore: ignore per-developer paths (personal/, commands/,
  scripts/, skills/omc-reference/, settings.local.json, worktrees/, .omc/)
  in place; keep personal/README.md committed. Previously this relied on
  each developer's global gitignore, which isn't portable and silently
  hid new shared files.
- .claude/personal/: git-ignored drop zone for per-developer config;
  CLAUDE.md optionally imports personal/CLAUDE.md if present.
- .claude/project.md: project knowledge (overview, layout, architecture,
  INI, conventions) in the terse house style, cross-referencing the
  existing build/CI/debug docs instead of duplicating them. Reflects the
  ext/ -> tracer/ split (#3912); versions reference VERSION / Cargo.toml
  / rust-toolchain.toml rather than being pinned inline.
- CLAUDE.md: link general.md, project.md, ci/index.md and import personal.

* Auto-load common config via @import (general.md, project.md)

Plain markdown links in CLAUDE.md are not injected into context by Claude
Code — only @-imports are. Import general.md and project.md so the shared
operating rules and project knowledge are always loaded alongside each
developer's personal config. ci/index.md stays a link (large on-demand CI
reference).

* Restructure shared config: scripts/ and debugging/ folders; shareable commands

Addresses PR review feedback:

- .claude/.gitignore: commands/ is now personal-by-default via `/commands/*`
  (instead of ignoring the whole dir), so the team CAN commit shared commands
  by un-ignoring them while personal ones stay ignored. Claude Code discovers
  commands by filesystem regardless of git status, so both coexist.
- Scripts: shared helper scripts moved into .claude/scripts/ (dd_php_release_url,
  find_map_region.py, parse_ucontext.py); personal scripts go in
  .claude/scripts/local/ (git-ignored). crash-analysis skill refs updated.
- Debugging docs grouped under .claude/debugging/ with an index.md (like ci/):
  gdb.md, appsec-integration.md (was debugging.md), system-tests.md (was
  debugging-system-tests.md). All inbound/outbound links updated.

Note: ci/ keeps its own co-located tooling (dockerh, check-ci, ...) since those
are referenced throughout the ci/ docs as a self-contained module.

* Keep personal skill ignores out of shared gitignore

Personal skills live in .claude/skills/ alongside shared ones (Claude Code
discovers by filesystem, ignoring git status). Their dir name is the skill
name, so there's no generic pattern; document that each dev ignores their own
personal skill dirs in .git/info/exclude (per-clone) instead of publishing
personal skill names into the committed shared config.

* Drop in-repo personal mechanism; personal config lives in ~/.claude

Personal Claude config now lives entirely in ~/.claude (global), so the repo's
.claude/ is purely shared team config:

- Remove .claude/personal/ (README) and the @.claude/personal/CLAUDE.md import
  from CLAUDE.md.
- Slim .claude/.gitignore to just local/runtime artifacts (settings.local.json,
  worktrees/, .omc/); document that personal config goes in ~/.claude.

* Remove .claude/.gitignore; personal tool artifacts ignored globally

The repo .claude/ carries no ignore file now — it's purely shared config.
Local/runtime artifacts are handled outside the shared config: settings.local.json
via the repo root .gitignore, and per-developer tooling output (OMC .omc/, Claude
Code agent worktrees/checkpoints/etc.) via each dev's own global ~/.gitignore.

* Expand project.md into a project/ code-guide folder

Turn the single project.md into a ci/-style folder: a concise always-imported
index.md (overview, layout, subsystem map, architecture summary, config,
conventions, pointers) plus one terse orientation file per subsystem —
ext, tracer, userland (src/), components (+components-rs/ZAI), sidecar, appsec,
profiling. Each covers what it is / key files & dirs / how it fits / gotchas,
cross-linked, with build/CI/debug content linked out (not duplicated).

Produced via an analyze→write→review pass over the actual source: per-subsystem
code analysis, drafting, then a source-accuracy + house-style review. Versions
are referenced by source-of-truth (VERSION, Cargo.toml, rust-toolchain.toml);
no hardcoded versions or source line numbers. CLAUDE.md now imports
project/index.md.

* project/: add data-flow to tracer/ext/sidecar; link architecture & CONTRIBUTING

Targeted depth-increase (on-demand area files only; index stays lean):
- tracer.md: ordered span→upload data-flow (RINIT → headers → span create →
  uhook → close → sampling → serializer → auto_flush → sidecar/coms → agent).
- ext.md: fix the incorrect "MSHUTDOWN tears down in reverse" claim — it isn't
  (sidecar shuts down late, after config is freed); tighten MINIT/RINIT/RSHUTDOWN
  ordering (logging-first, zend_extension registration, dd_rinit_once).
- sidecar.md: submit→upload flow (serialize → send_traces_to_sidecar → IPC →
  TraceFlusher batches ~5s/~1MB → agent upload; fork preserves session ID).
- index.md: link architecture.md (background sender / components / version code)
  and CONTRIBUTING.md (setup/testing) from Pointers.

Produced via the OMC analyze→write→review pipeline over live source; verified
accurate (flush thresholds, ordering, function anchors). No line numbers.

* project/: address Codex review — fix 4 doc inaccuracies

All four verified against live source:
- appsec.md: C++ helper client/runner/engine/service are .cpp/.hpp files, not
  dirs (only network/, remote_config/, subscriber/ are dirs).
- appsec.md: the helper is enabled via the sidecar — ext/sidecar.c calls the
  appsec module's dd_appsec_maybe_enable_helper -> ddog_sidecar_enable_appsec
  (resolved Rust/C++ path) before ddappsec's first RINIT — not spawned by
  ddappsec MINIT/RINIT.
- tracer.md + index.md: the sidecar sender is only the default on PHP 8.3+ /
  Windows (DD_SIDECAR_TRACE_SENDER_DEFAULT); on PHP 7.0-8.2 the in-process
  coms.c sender is the default.
- components.md: drop container_id from the component list — it's a stale
  build-artifact dir with no source; container ID is in the Rust bridge
  (ddtrace_get_container_id).

* project/: address review — drop FFI-surface note; fix cbindgen regen trigger

Per @bwoebi: the "keep FFI surface small" line isn't actionable (dropped), and cbindgen headers regenerate when any components-rs/libdatadog source changes, not just lib.rs.

* Update .claude/project/tracer.md

Co-authored-by: Bob Weinand <[email protected]>

* feat(ci): add --jobs named-subset filter to check-ci

Add an opt-in --jobs "pat1,pat2" option (comma-separated, case-insensitive
substring patterns) to the check-ci monitor. When set, blocking-wait
completion and failure/timeout accounting consider only jobs whose name
matches any pattern, so the monitor finishes as soon as the matched subset
is terminal instead of waiting for the whole pipeline. --list-jobs shows
only matched jobs. Applies to both GitLab jobs and GitHub Actions jobs.
Default (no --jobs) keeps whole-pipeline monitoring unchanged.

* docs(claude): add CI flakiness & debugging gotchas to shared config

---------

Co-authored-by: Bob Weinand <[email protected]>