[CHORE] Refresh CONTRIBUTING.md: document issue-first + AI-disclosure (.audit) requirements; fix stale tox/paths

[oberstet]

Why

CONTRIBUTING.md is both incomplete (it omits requirements we actually
enforce) and stale (it references tooling/paths we no longer use). PR #1887
is a good example: the contributor followed the public guide, but tripped over
process rules that are only written down in AI_POLICY.md / .ai /
.audit/AI_AUDIT_PROCESS.md, not in CONTRIBUTING.md. Let's make the public
guide match reality so external contributors can succeed first time.

Missing — add these

• Issue-first workflow. State that every change starts from a GitHub
  issue, and the PR must reference it (Closes #<issue>). The current
  "Contributing Code" list jumps straight to fork/branch.
• AI-assistance disclosure. Document that every PR must include a
  disclosure file at .audit/<github-username>_<branch>.md (e.g.
  .audit/bblommers_websocket-server-typing.md), not a PR comment. Link
  .audit/AI_AUDIT_PROCESS.md
  and AI_POLICY.md. (This is the biggest gap — currently undocumented.)
• Branch guidance. Note the fix_<issue> convention for maintainers,
  while making clear descriptive branch names from external forks are welcome
  (e.g. patch-1).

Stale — fix these

• Test runner. Replace the tox / tox -e py312 section with the
  current just recipes (just test, just check, etc.).
• Test path. pytest autobahn/test/test_websocket.py → src-layout
  src/autobahn/test/....
• Install & docs. Re-check pip install -e .[dev,twisted,asyncio] and
  cd docs && make html against the current extras ([all]/[dev]) and the
  just docs recipe.

Notes

• Pure documentation; no code/behaviour change.
• Keep CONTRIBUTING.md aligned with docs/contributing.rst if both are shipped.

---

This analysis was produced with AI assistance (Claude Code) and requires human review before filing. Which I did.

Checklist

• I have searched existing issues to avoid duplicates
• I have provided a minimal reproducible example
• I have included version information
• I have included error messages/logs

[oberstet]

Notes-to-self: CI/CD + contrib-docs improvements (from PR #1887 friction)

Context: first-time contributor PR (autobahn-python #1887, issue #1888) surfaced several gaps. The code change was trivially correct; everything else was process friction we should remove so the next contributor succeeds first time. These are group-wide (every WAMP repo uses .ai + .audit + the shared .cicd).

A. Audit-file naming — the colon-on-Windows trap (root cause of the failed CI)

• The contributor named the audit file .audit/JavierSab:patch-1.md (a colon,
  copied from GitHub's owner:branch head-ref label). Colons are reserved in
  Windows filenames → git checkout fails on the Windows CI runner with
  error: invalid path ... (exit 128). Legal on Linux/macOS, so it only blows up
  on Windows — a nasty, late-surfacing failure.
• Convention is <github-username>_<branch>.md (underscore). Make this
  explicit and idiot-proof:
  1. Doc: in .audit/AI_AUDIT_PROCESS.md (and the CONTRIBUTING refresh), show
     the exact format with an example, and call out: "the GitHub owner:branch
     display is NOT the filename — use an underscore, never : / / / other
     reserved chars (cross-platform/Windows safety)."
  2. Tooling: the .ai generate-audit-file recipe already emits underscore +
     sanitizes the branch (/→-, strips dots). Consider hardening it to also
     strip/replace any char outside [A-Za-z0-9._-] (defensive — humans hand-name
     these). Recommend contributors run just generate-audit-file rather than
     hand-creating the file.
  3. Fast CI guard (cheap, high value): add a lint step (Linux job, runs in
     seconds) that fails if any .audit/*.md filename doesn't match
     ^[A-Za-z0-9._-]+\.md$, with a clear message ("audit filenames must be
     cross-platform safe; use <user>_<branch>.md, no colons"). Catches this on
     the fast Linux job instead of deep in the Windows checkout. Put it in the
     shared .cicd so all repos inherit it.

B. Audit-file CONTENT must reference the issue

• The Related issue(s): field was left blank. The whole point of issue-first is
  end-to-end traceability from version history (PR → issue). Doc + (optionally)
  the same CI guard could check the audit file has a non-empty Related issue(s):
  line referencing #<n>.

C. CONTRIBUTING.md is incomplete + stale (already drafted: /tmp/autobahn-issue-contributing-refresh.md)

Fold these in:

• Add the audit-filename rule (A) with example + the colon/Windows caveat.
• Add issue-first + Closes #<n> requirement, and that the audit file's
  Related issue(s): must reference it.
• Fix stale: tox→just, autobahn/test/→src/autobahn/test/, install/docs
  extras.

D. Branch naming (minor)

• External fork branches like patch-1 are fine (git refuses : in ref names, so
  the branch was never the problem — only the hand-written filename was). No change
  needed; just don't mirror owner:branch into filenames.

Suggested issues to file

1. (autobahn / or wamp-cicd) "Add .audit/ filename + content lint to CI" (the
   ^[A-Za-z0-9._-]+\.md$ + Related issue(s): check) — shared via .cicd.
2. CONTRIBUTING.md refresh — already drafted at
   /tmp/autobahn-issue-contributing-refresh.md; extend it with section A/B above.
3. (optional) harden .ai generate-audit-file to sanitize non-portable chars.