runbook SSOT + doc/link integrity + allgemeine hygiene

[tomtastisch]

Summary

This PR finalizes prod-readiness hardening around runbook SSOT, documentation integrity, repository hygiene, and targeted Qodana cleanup without breaking public APIs.

Included changes

• Runbook/doc SSOT cleanup from previous commit (e1a4fca).
• Qodana-focused cleanup + safe upgrades (33e0027):
  • removed unused test helper member CreateNestedZip
  • removed unused FixtureManifestCatalog.Entries
  • turned previously-unused manifest fields (SourceUrl, SourceRef, Purpose, SecurityNotes) into validated required fields
  • simplified sequential null/count check via property pattern
  • converted if-chain to switch in ArchiveManagedBackendUnitTests
  • replaced constant auto-properties with computed properties in test doubles
  • kept public API methods non-static and documented CA1822 suppression (non-breaking)
  • upgraded Microsoft.NET.Test.Sdk 17.14.1 -> 18.0.1
  • upgraded xunit.runner.visualstudio 3.1.4 -> 3.1.5

Evidence

• Build: dotnet build FileClassifier.sln -v minimal (exit 0)
• Tests: TEST_BDD_OUTPUT_DIR=artifacts/tests bash tools/test-bdd-readable.sh -- ... (exit 0)
• Vulnerabilities: dotnet list FileClassifier.sln package --vulnerable --include-transitive (no vulnerable packages)
• Deprecated packages: only xunit 2.9.3 shown as legacy alternative
• Outdated check: dotnet list tests/FileTypeDetectionLib.Tests/FileTypeDetectionLib.Tests.csproj package --outdated (no updates after upgrade)

CI Evidence

• .github/workflows/ci.yml: dedicated job/step tests-bdd-coverage / BDD Tests + Coverage Gate (Single Run) executes tools/test-bdd-readable.sh.
• .github/workflows/qodana.yml: separate workflow; execution gated by QODANA_TOKEN.

Decision log

1. xunit package was not migrated to v3 in this PR to avoid framework-level migration risk in test infrastructure.
2. Evidence from local NuGet metadata (~/.nuget/packages/reqnroll.xunit/3.3.3/reqnroll.xunit.nuspec) states:
   • "Package to use Reqnroll with xUnit 2.x. Use Reqnroll.xunit.v3 for xUnit 3.x."
3. Therefore this PR performs safe, non-breaking upgrades only.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 50cb92a4db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR restructures CI into a contract-first, deterministic “check runner” model (artifacts + result contract), tightens documentation/link integrity checks across the repo, and applies targeted hygiene/Qodana-driven cleanups while keeping public APIs stable.

Changes:

• Introduces tools/ci/ orchestration (runner, policies, validators) with standardized artifacts/ci/<check_id>/... outputs and schema validation.
• Refactors GitHub workflows (ci.yml, qodana.yml) to call the unified runner and to publish consistent CI artifacts.
• Improves doc/link integrity tooling and updates docs/READMEs; includes small code/test cleanups and package lockfile updates.

Reviewed changes

Copilot reviewed 57 out of 60 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/versioning/check-versioning.sh	Base version resolution made deterministic (base ref first, tags fallback).
tools/ci/schema/result.schema.json	Adds JSON schema for CI result.json contract.
tools/ci/policies/policy_shell_safety.sh	Adds workflow shell-safety policy checks (rg/awk).
tools/ci/policies/policy_artifact_contract.sh	Enforces required artifacts + validates result.json.
tools/ci/policies/ci_graph_expected.json	Declares expected CI job graph (allowed jobs + edges).
tools/ci/lib/result.sh	Adds CI result lifecycle helpers (violations/evidence/final JSON).
tools/ci/lib/log.sh	Adds timestamped logging helpers + UTC/ms timing utilities.
tools/ci/checks/ResultSchemaValidator/packages.lock.json	Adds lock file for validator project.
tools/ci/checks/ResultSchemaValidator/ResultSchemaValidator.csproj	Introduces validator project (net10.0).
tools/ci/checks/ResultSchemaValidator/Program.cs	Implements JSON contract checks for result.json.
tools/ci/checks/QodanaContractValidator/packages.lock.json	Adds lock file for Qodana contract validator.
tools/ci/checks/QodanaContractValidator/QodanaContractValidator.csproj	Introduces Qodana contract validator (net10.0).
tools/ci/checks/QodanaContractValidator/Program.cs	Validates token + SARIF structure preconditions.
tools/ci/checks/CiGraphValidator/packages.lock.json	Adds lock file + YamlDotNet dependency pinning.
tools/ci/checks/CiGraphValidator/Program.cs	Validates workflow jobs and required needs edges.
tools/ci/checks/CiGraphValidator/CiGraphValidator.csproj	Introduces workflow graph validator project.
tools/ci/bin/run.sh	Adds unified CI entry runner producing contract artifacts.
tools/ci/bin/assert_ci_graph.sh	Adds wrapper to run CI graph validator.
tools/check-docs.py	Expands markdown link checking to docs/src/tests + refactors file collection.
tests/FileTypeDetectionLib.Tests/packages.lock.json	Updates lock file (test SDK + runner upgrades).
tests/FileTypeDetectionLib.Tests/Unit/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Unit/ArchiveManagedBackendUnitTests.cs	Simplifies entry assertions with switch.
tests/FileTypeDetectionLib.Tests/Unit/ArchiveInternalsPrivateBranchUnitTests.cs	Replaces const auto-property with computed property in test fake.
tests/FileTypeDetectionLib.Tests/Unit/ArchiveExtractorReflectionUnitTests.cs	Same computed property adjustment in test fake.
tests/FileTypeDetectionLib.Tests/Unit/ArchiveExtractorAdditionalUnitTests.cs	Same computed property adjustment in test fakes.
tests/FileTypeDetectionLib.Tests/Support/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Support/FixtureManifestCatalog.cs	Tightens manifest validation (required metadata fields).
tests/FileTypeDetectionLib.Tests/Support/ArchiveEntryPayloadFactory.cs	Removes unused helper method.
tests/FileTypeDetectionLib.Tests/Steps/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Property/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Integration/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Features/README.md	Updates doc-check command reference.
tests/FileTypeDetectionLib.Tests/Benchmarks/README.md	Updates doc-check command reference.
src/README.md	Removes references to non-existent sync scripts + updates doc-check command.
src/FileTypeDetection/packages.lock.json	Adds/updates lock file for library project.
src/FileTypeDetection/README.md	Updates runbook references and doc-check command.
src/FileTypeDetection/Infrastructure/README.md	Updates doc-check command reference.
src/FileTypeDetection/FileTypeDetector.vb	Adds CA1822 suppression rationale; makes a helper Shared; keeps public API stable.
src/FileTypeDetection/Detection/README.md	Updates doc-check command reference.
src/FileTypeDetection/Detection/FileTypeRegistry.vb	Replaces LINQ with loops for magic detection.
src/FileTypeDetection/Configuration/README.md	Updates doc-check command reference.
src/FileTypeDetection/Abstractions/README.md	Updates doc-check command reference.
src/FileTypeDetection/Abstractions/Hashing/README.md	Updates doc-check command reference.
src/FileTypeDetection/Abstractions/Detection/README.md	Updates doc-check command reference.
src/FileTypeDetection/Abstractions/Archive/README.md	Updates doc-check command reference.
src/FileClassifier.App/packages.lock.json	Adds/updates lock file for app project.
src/FileClassifier.App/README.md	Updates doc-check command reference.
global.json	Pins .NET SDK version for deterministic builds.
docs/versioning/CHANGELOG.md	Adjusts unreleased note around version baseline.
docs/governance/CI_POLICY.md	Adds CI policy SSOT (rule IDs, artifact contract, exit codes).
docs/governance/CI_PIPELINE.md	Adds CI pipeline SSOT (stages, artifact root, constraints).
docs/DIN_SPECIFICATION_DE.md	Updates verification runbook to match current CI steps.
docs/CI_PIPELINE.md	Adds Qodana section (dead-code gate description).
README.md	Updates runbook notes + adds Qodana dead-code gate mention.
Directory.Packages.props	Adds/updates package versions (incl. YamlDotNet, test SDK/runner).
Directory.Build.props	Bumps version to 4.1.0 + enables lockfiles globally.
.gitignore	Ensures tools/ci/ tracked; ignores validator build outputs.
.github/workflows/qodana.yml	Aligns Qodana outputs to artifacts/ci/qodana + runs entry check + uploads artifact.
.github/workflows/ci.yml	Replaces inline CI logic with runner calls + standardized artifact uploads/downloads.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.