chore: containerized dev env, Scorecard hash-pinning, agent-docs audit fixes

.claude/skills/add-lang/SKILL.md

@@ -519,7 +519,7 @@ invocation in:
 | `src/metrics/abc.rs` | `Abc` |
 | `src/metrics/cognitive.rs` | `Cognitive` |
 | `src/metrics/cyclomatic.rs` | `Cyclomatic` |
-| `src/metrics/exit.rs` | `Exit` |
+| `src/metrics/nexits.rs` | `Exit` |
 | `src/metrics/halstead.rs` | `Halstead` |
 | `src/metrics/loc.rs` | `Loc` |
 | `src/metrics/mi.rs` | `Mi` |
@@ -541,7 +541,7 @@ Run `cargo check -p big-code-analysis` — it should now succeed.
   branch** — this is consistent with the existing Java and Cpp impls
   in this repo, and was reaffirmed for Go in commit `e0701e1`. Match
   the language's actual node kinds, not generic names.
-- **Exit** (`src/metrics/exit.rs`): `+1` per `return`/`yield` /
+- **Exit** (`src/metrics/nexits.rs`): `+1` per `return`/`yield` /
   language-specific exit. A multi-value return counts once.
 - **Halstead** (`src/metrics/halstead.rs`): wire
   `compute_halstead::<Self>` through the existing
@@ -727,7 +727,7 @@ were:
 |--------|-----------:|--------------------------------------------|
 | `cognitive` | 9 | no-op file, simple function, sequence of same/different booleans, negated booleans, 1-level nesting, 2-level nesting, `break`/`continue`, complex `if let / else if / else`. |
 | `cyclomatic` | 1 | nested-control-flow representative test. (Go currently overshoots Rust here at 10 — match Rust's 1, optionally add a couple more if the language has unusual constructs.) |
-| `exit` | 2 | function with no exit, function with `?` / language equivalent of early-exit. |
+| `nexits` | 2 | function with no exit, function with `?` / language equivalent of early-exit. |
 | `halstead` | 1 | one comprehensive `<lang>_operators_and_operands` test pinning every Halstead field via `insta`. |
 | `loc` | 15 | blank, no-zero-blank, cloc, lloc, then **at least one `<lang>_no_*_lloc` test for each gating decision** (Rust has: `field_expression`, `parenthesized_expression`, `array_expression`, `tuple_expression`, `unit_expression`, `call_function`, `macro_invocation`, `function_in_loop`, `function_in_if`, `function_in_return`, `closure_expression`). Mirror this — every node kind your `compute` excludes from LLOC needs a dedicated test that would fail if the gating is removed. |
 | `nargs` | 5 | no functions/closures, single function, single closure, multiple functions, nested functions. |
@@ -761,7 +761,7 @@ only when the grammar has constructs the existing repo has not seen
   (Go's `defer`/`go` test is the template). Do not pad the count by
   adding one test per ordinary branching keyword; that is what the
   single nested test already covers.
-- **`exit`** — `<lang>_no_exit` (function with no return), and one
+- **`nexits`** — `<lang>_no_exit` (function with no return), and one
   test per language-specific exit path (e.g. Rust's `?`, Go's
   multi-value return, Python's `yield`/`raise`, Ruby's `next`/`break`
   out of a block if you treat them as exits — document the choice).
@@ -928,7 +928,7 @@ language alphabetically:
 
 `CHANGELOG.md` is present at the repo root and used. A new language
 warrants its own entry — do not consolidate into a batch-fix line.
-Append under `Added`:
+Append under `Added` within the `## [Unreleased]` section:
 
 ```markdown
 - Support for <LangName> source files (`.<ext>`).
@@ -1069,7 +1069,7 @@ Files changed:
   src/checker.rs
   src/getter.rs
   src/alterator.rs                   (if applicable)
-  src/metrics/{abc,cognitive,cyclomatic,exit,halstead,loc,mi,nargs,nom,npa,npm,wmc}.rs
+  src/metrics/{abc,cognitive,cyclomatic,nexits,halstead,loc,mi,nargs,nom,npa,npm,wmc}.rs
   big-code-analysis-book/src/languages.md
   *.snap                             (new insta snapshots)
 

.claude/skills/audit-crate/SKILL.md

@@ -9,9 +9,9 @@ Audit the Rust crate `$ARGUMENTS` for logic errors, unnecessary complexity,
 bugs, security issues, incorrect comments, and code smells.
 
 If `$ARGUMENTS` is empty, default to `big-code-analysis` — the root library
-crate. The other crates in this workspace are `big-code-analysis-cli` and
-`big-code-analysis-web`. The crate root is the directory containing the
-crate's `Cargo.toml`.
+crate. The other crates in this workspace are `big-code-analysis-cli`,
+`big-code-analysis-web`, `big-code-analysis-py`, `xtask`, and `enums`.
+The crate root is the directory containing the crate's `Cargo.toml`.
 
 **Resolve `$ARGUMENTS` once at the very start of the run** and use the
 resolved value for every subsequent reference (memory keys, `cargo -p`, issue
@@ -204,7 +204,7 @@ CRATE_DIR=$(cargo metadata --format-version 1 --no-deps \
 
 # Self-host: use this project's own CLI to measure the crate under audit.
 if cargo build -p big-code-analysis-cli >/dev/null 2>&1; then
-  ./target/debug/big-code-analysis-cli -m -O json -p "$CRATE_DIR" > /tmp/audit-metrics.json || true
+  ./target/debug/bca metrics -O json "$CRATE_DIR" > /tmp/audit-metrics.json || true
 fi
 ```
 

.claude/skills/audit-file/SKILL.md

@@ -219,7 +219,7 @@ the audit to the highest-risk functions.
 
 ```bash
 if cargo build -p big-code-analysis-cli >/dev/null 2>&1; then
-  ./target/debug/big-code-analysis-cli -m -O json -p "$FILE_ABS" > /tmp/audit-metrics.json || true
+  ./target/debug/bca metrics -O json "$FILE_ABS" > /tmp/audit-metrics.json || true
 fi
 ```
 

.claude/skills/audit-naming/SKILL.md

@@ -6,13 +6,14 @@ description: Audit naming quality in a crate or directory for misleading, incons
 # Audit Naming Quality
 
 Audit naming quality in `$ARGUMENTS` for misleading, inconsistent, or unclear
-names across the Rust source under audit. Distinct from `audit` (logic,
-security, complexity) -- this focuses exclusively on whether names tell the
-truth.
+names across the Rust source under audit. Distinct from `audit-crate` /
+`audit-file` (logic, security, complexity) -- this focuses exclusively on
+whether names tell the truth.
 
 If `$ARGUMENTS` is empty, default to `big-code-analysis` — the root library
-crate. Other crates in this workspace are `big-code-analysis-cli` and
-`big-code-analysis-web`. `$ARGUMENTS` may also be a directory path; in that
+crate. Other crates in this workspace are `big-code-analysis-cli`,
+`big-code-analysis-web`, `big-code-analysis-py`, `xtask`, and `enums`.
+`$ARGUMENTS` may also be a directory path; in that
 case the audit is scoped to that directory.
 
 **Resolve `$ARGUMENTS` once at the very start of the run** and use the
@@ -277,14 +278,14 @@ Severity definitions:
 | ID | Check |
 |----|-------|
 | P1 | Cross-language naming parity: when `language_rust.rs`, `language_python.rs`, etc. expose the same concept, the names match (no `is_func` in one and `is_function` in another) |
-| P2 | Metric names follow the canonical metric vocabulary (`abc`, `cognitive`, `cyclomatic`, `halstead`, `loc`, `mi`, `nargs`, `nom`, `npa`, `npm`, `wmc`) — abbreviations are standard, expanded forms or alternates are inconsistent |
+| P2 | Metric names follow the canonical metric vocabulary (`abc`, `cognitive`, `cyclomatic`, `halstead`, `loc`, `mi`, `nargs`, `nexits`, `nom`, `npa`, `npm`, `tokens`, `wmc`) — abbreviations are standard, expanded forms or alternates (e.g. `exit` for `nexits`) are inconsistent |
 | P3 | Tree-sitter node-type strings used as identifiers match the upstream grammar's exact spelling (deviations are bugs, not style) |
 
 ---
 
 ## Step 4: Group findings into issues
 
-**Key difference from `audit`**: Group findings into coherent tickets:
+**Key difference from `audit-crate` / `audit-file`**: Group findings into coherent tickets:
 
 1. Group by **file** if multiple findings in the same file
 2. Group by **theme** if the same naming pattern repeats across files

.claude/skills/audit-tests/SKILL.md

@@ -18,7 +18,7 @@ Determine what to audit based on `$ARGUMENTS`:
 |----------|-------|
 | *(empty)* | Tests in unstaged + staged changes (`git diff HEAD`) |
 | `staged` | Tests in staged changes only (`git diff --cached`) |
-| `branch` | Tests in all commits on current branch vs `master` (`git diff master...HEAD`) |
+| `branch` | Tests in all commits on current branch vs `main` (`git diff main...HEAD`) |
 | *file path* | Specific test file |
 | *directory path* | All test files under the directory (`tests/`, `src/**/mod.rs`, `#[cfg(test)]` modules) |
 

.claude/skills/batch-fix/SKILL.md

@@ -113,6 +113,10 @@ The workspace crates are:
   traversal, metric computation, per-language modules
 - `big-code-analysis-cli` — CLI binary (`big-code-analysis-cli/`)
 - `big-code-analysis-web` — REST API server (`big-code-analysis-web/`)
+- `big-code-analysis-py` — PyO3 Python bindings (`big-code-analysis-py/`,
+  excluded from default-members; needs Python headers + maturin)
+- `xtask` — man-page generation helper (`xtask/`, excluded from
+  default-members)
 - `enums` — code-generation helper for language enums (`enums/`, excluded
   from default workspace)
 
@@ -124,7 +128,8 @@ Use these signals in priority order:
    - "parser", "tree-sitter", "AST", "node", "grammar", "ParserTrait" ->
      `big-code-analysis`
    - "metric", "halstead", "cyclomatic", "cognitive", "loc", "abc", "wmc",
-     "nargs", "nom", "npa", "npm", "exit", "mi" -> `big-code-analysis`
+     "nargs", "nom", "npa", "npm", "nexits", "exit", "tokens", "mi" ->
+     `big-code-analysis`
    - "checker", "getter", "alterator", "spaces" -> `big-code-analysis`
    - "language X", a specific language name (rust, python, javascript, c,
      cpp, java, kotlin, typescript, etc.), or `src/languages/` path ->
@@ -133,6 +138,9 @@ Use these signals in priority order:
      CLI flags) -> `big-code-analysis-cli`
    - "REST", "API", "server", "HTTP", "endpoint", "route" ->
      `big-code-analysis-web`
+   - "Python", "PyO3", "maturin", "stub", "`_native.pyi`", "wheel" ->
+     `big-code-analysis-py`
+   - "man page", "manpage", "xtask" -> `xtask`
    - "language enum", "enum generation", "code generation",
      `enums/templates/`, `enums/src/` -> `enums`
 3. **Ambiguous**: If the crate cannot be determined from labels or keywords,
@@ -528,6 +536,14 @@ After all waves are processed, if any merges succeeded:
 
 ```bash
 git checkout <INTEGRATION_BRANCH>
+```
+
+Then run `make pre-commit` — the canonical gate per "Validation gates"
+in `AGENTS.md` (it adds udeps, doc warnings, the lint families, the
+self-scan gates, and `make snapshot-anchors` on top of the cargo trio).
+If `make` is unavailable, fall back to:
+
+```bash
 cargo fmt --all -- --check
 cargo clippy --workspace --all-targets -- -D warnings
 cargo test --workspace --all-features
@@ -739,12 +755,13 @@ Follow the `/fix-issue` workflow:
    cause is repeated, fix all instances. Similarly, if metric code under
    `src/metrics/` has the same anti-pattern in multiple metrics, fix all of
    them.
-5. **Plan the fix using sequential thinking.** Use the
-   `sequential-thinking:sequentialthinking` MCP tool to reason through the
-   resolution step by step before writing any code. The sequential thinking
-   process MUST:
-   - **Start** with `thoughtNumber: 1`, an initial `totalThoughts` estimate
-     (typically 5-8), and `nextThoughtNeeded: true`.
+5. **Plan the fix with explicit step-by-step reasoning.** If the
+   `sequential-thinking:sequentialthinking` MCP tool is available, use it
+   (start with `thoughtNumber: 1`, a `totalThoughts` estimate of typically
+   5-8, and `nextThoughtNeeded: true`; adjust `totalThoughts` as
+   understanding evolves and use `isRevision` to correct earlier
+   reasoning; conclude with `nextThoughtNeeded: false`). If it is not
+   configured, reason through the same phases inline. The plan MUST:
    - **Analyze** the root cause — not just the symptom. Trace the
      data/control flow that leads to the bug.
    - **Enumerate approaches** and evaluate trade-offs (simplicity,
@@ -761,15 +778,12 @@ Follow the `/fix-issue` workflow:
      code, or any other anti-pattern from `AGENTS.md`, redesign before
      proceeding.
    - **Verify completeness** — confirm the plan covers implementation,
-     tests for **every affected language**, and documentation before
-     concluding.
-   - **Conclude** with `nextThoughtNeeded: false` and a final plan summary.
-   - Adjust `totalThoughts` up or down as understanding evolves. Use
-     `isRevision` if earlier reasoning needs correction.
+     tests for **every affected language**, and documentation, and
+     conclude with a final plan summary.
 6. **Implement the fix.** Execute the plan from step 5. Before changing any
    public API, run `find_referencing_symbols` (or workspace-wide `rg`) to
    enumerate every call site. If the implementation reveals issues the plan
-   missed, revise via sequential thinking before proceeding.
+   missed, revise the plan the same way before proceeding.
 7. Self-review the implementation:
    - Correctness: root cause addressed, not just symptom?
    - Performance: appropriate algorithms and data structures? No O(n²) on
@@ -795,7 +809,18 @@ Follow the `/fix-issue` workflow:
      language affected.
    - **Snapshot tests** (`insta`): if existing snapshots changed, run
      `cargo insta test --review` and accept each diff individually rather
-     than blindly accepting all.
+     than blindly accepting all. Every **new**
+     `insta::assert_json_snapshot!(metric.…)` must be anchored (inline
+     expected block, integer `assert_eq!` above the call, or an
+     `// expected: <derivation>` comment) — bare snapshots fail
+     `make snapshot-anchors`.
+   - **Integration-snapshot submodule**: a behaviour-changing metric /
+     traversal / alterator fix generates `.snap.new` inside
+     `tests/repositories/big-code-analysis-output/`. Follow the submodule
+     discipline in `AGENTS.md`: accept the snapshots, push them to the
+     submodule remote, and record the new submodule SHA in the **same**
+     commit as the fix (`git add tests/repositories/big-code-analysis-output`
+     is exempt from the "only files you changed" staging rule).
    - **Regression check**: `cargo test --workspace --all-features` and
      `cargo clippy --workspace --all-targets -- -D warnings` must pass.
    - Tests must actually assert what they claim — no silent fallbacks
@@ -836,8 +861,8 @@ directly:
 - Helper functions that duplicate standard library or crate functionality
 - Duplicate logic across sibling language modules that should live in a
   shared helper, trait method, or macro (the project already uses
-  `c_langs_macros/`, `src/macros.rs`, and `src/c_macro.rs` for shared
-  structure)
+  `src/c_langs_macros/`, `src/macros/`, and `src/c_macro.rs` for shared
+  structure; follow `.claude/rules/macro-comments.md` when consolidating)
 
 **Clarity**:
 

.claude/skills/cleanup-crate/SKILL.md

@@ -68,8 +68,8 @@ Parse `$ARGUMENTS` as: `<crate-name> [--dry-run] [--aggressive]`
 ## Constraints
 
 - **Deletions only**: no refactoring, no API changes, no behavioral changes
-- **Do not merge to master**: leave the integration branch for the user
-  (note: this repo's default branch is `master`, not `main`)
+- **Do not merge to main**: leave the integration branch for the user
+  (this repo's default branch is `main`)
 - **Skip on failure**: if any removal area fails, discard it and log the reason
 - **No re-examination**: skip files already reviewed in prior runs
 - **Never remove test code**
@@ -108,7 +108,7 @@ If there are uncommitted changes, abort:
 ### 0c: Create integration branch
 
 ```bash
-git checkout -b cleanup/<crate-name> master
+git checkout -b cleanup/<crate-name> main
 ```
 
 If the branch already exists from a prior partial run, check it out and
@@ -328,16 +328,16 @@ cargo check -p <CRATE>
 
 If check fails, attempt to fix (one retry); otherwise SKIP.
 
-If check passes, run the full validation:
+If check passes, run the fast per-agent validation (the canonical
+`make pre-commit` gate runs once on the integration branch in Step 4 —
+do not pay its full cost per removal area):
 
 ```bash
 cargo fmt --all -- --check
 cargo clippy --workspace --all-targets -- -D warnings
 cargo test --workspace --all-features
 ```
 
-(If `pre-commit` is installed, also run `pre-commit run --all-files`.)
-
 If validation fails:
 
 - If the failure is in code you changed, attempt to fix it (one retry).
@@ -379,7 +379,8 @@ Return SUCCESS (branch, commit hash, files, removed symbols) or SKIPPED
 
 ## Step 4: Integrate successful changes
 
-> **Branch mode**: Skip — integration happens inline in Step 3.
+> **Branch mode**: Skip the merges — integration happened inline in
+> Step 3 — but still run the validation gate below.
 
 For each successful worktree agent:
 
@@ -390,7 +391,12 @@ git merge <worktree-branch-name> --no-edit
 
 If a merge conflict: `git merge --abort` and log as conflict.
 
-After all merges, run the full validation suite on the integration branch.
+After all merges (or directly, in branch mode), run `make pre-commit` on
+the integration branch — the canonical validation gate (see "Validation
+gates" in `AGENTS.md`; it adds udeps, doc warnings, the lint families,
+the self-scan gates, and `make snapshot-anchors` on top of the cargo
+trio run in 3e). If `make` is unavailable, fall back to the raw cargo
+gates from 3e.
 
 ---
 
@@ -449,15 +455,15 @@ Branch: cleanup/<crate-name>
 ```
 
 Remind the user: "Integration branch `cleanup/<crate-name>` is ready for
-review. Merge to `master` when satisfied."
+review. Merge to `main` when satisfied."
 
 If approval-required items exist, suggest `--aggressive`.
 
 ---
 
 ## Guardrails
 
-- Do NOT merge `cleanup/<crate-name>` into `master`
+- Do NOT merge `cleanup/<crate-name>` into `main`
 - Do NOT remove public API items unless `--aggressive` is set
 - Do NOT remove items re-exported from `src/lib.rs`
 - Do NOT remove trait implementations

.claude/skills/doc-author/SKILL.md

@@ -13,7 +13,8 @@ source under `big-code-analysis-book/src/`).
 is an editor helper that applies those rules. If the skill and the
 convention disagree, the convention wins. For lessons-learned entries
 use the `lessons-learned` skill; for changelog entries follow the
-changelog rules in `AGENTS.md`. This skill does neither.
+`## Changelog` section of `docs/conventions/documentation.md` (plus the
+stability-contract rules in `AGENTS.md`). This skill does neither.
 
 ## Arguments