docs: make the repo's self-description true - ProjectTiers, README, CI inventory, layer rules

[IanFrelinger]

Production-readiness audit, H8 + M39 + M27 + M32 + M41 + M42 + M43 + M40 (fixable half) + L13. Ledger: https://claude.ai/code/artifact/15fa4198-97b8-4da6-bea0-0c24d364a7f3

Why

The repo's self-description had drifted badly (H8 + M39 + M27 + M32 + M41 + M42 + M43 + M40-fixable + L13):

• docs/ProjectTiers.md said "~69 .csproj (52 open, 17 commercial)"; git ls-files "*.csproj" holds 109 (58 src, 3 application, 10 applications, 17 commercial, 7 docs, 6 samples, 3 spikes, 5 tools). 18 src/ projects (MCP client/server/host, A2A, Analyzers, Authoring, Certification.Contracts/State, AI.Pipeline, Agents.TestKit, Bricks.SqlProfile + tests), the whole applications/ tree, samples/, spikes/, tools/ were absent.
• README said application/src/ holds "Game Director projects" (it holds Nexo.API/CLI; Game Director is commercial/), listed no MCP/A2A, and the layout tree omitted applications/, commercial/, deploy/, samples/, spikes/, infra/, extensions/, consumer-template/.
• docs/CiGateInventory.md called itself authoritative with 57 files and 15 required contexts. Reality (verified with gh api repos/IanFrelinger/Nexo/branches/master/protection): 62 workflow files, branch protection requires exactly cert-gate (strict: true, enforce_admins: true).
• Coverage floor drift: 80 (scripts/ci/kernel-coverage-gate.sh) vs 83 (GitHubBranchProtection.md, CoverageGates-v1.md, TestingModel.md) vs 84 (Makefile comment, production-readiness/README.md).
• CONTRIBUTING claimed cross-platform-tests / prod-dry-run-pr run on PRs (both workflow_dispatch-only), a nine-project PrimeTime filter (eight), and commitlint enforcement (no hook, no workflow, no package.json; root package-lock.json was an empty {"name":"czz"} stub).
• layer-boundary rejects application/-touching PRs into master unless one of four exemptions holds, but since only cert-gate is required those PRs merge with a red non-required verify (merge: land application/mcp-a2a (MCP + A2A endpoint wiring for Nexo.API) #269, waves 1-2) — undocumented.

What

(a) ProjectTiers.md rebuilt against git ls-files with full csproj paths (109/109), MCP/A2A rows pointing at docs/architecture/ProtocolIntegration-MCP-A2A.md, Tier 1b (authoring/certification/brick+policy packs), Tier 3a applications/, Tier 3c demos/samples/tools/spikes, and a "Which solution do I open?" table (Kernel.sln has no CLI/API — 23 kernel projects + kernel tests; the CLI/API dev loop is LocalDevCore.slnf / Core.slnf). New onboarding-docs-guard step "Every tracked csproj is listed in docs/ProjectTiers.md" (git ls-files -- '*.csproj' basenames grep'd into the doc; path filter gains **/*.csproj). Passes locally: 0 unlisted / 109.

(b) README — MCP/A2A in "Scope in 30 seconds" and the subsystem map, applications/ row, honest layout tree, "Which solution do I open?" table. New applications/README.md (singular application/ = hosts, plural applications/ = products on the core, Apache-2.0 by the Directory.Build.targets rule, apps/ = configs). docs/architecture/runtime-vs-application.md gains an applications/ row and a corrected Application.sln description.

(c) CI docs from reality — docs/CiGateInventory.md rewritten: 62 files, trigger classes (14 PR-triggered: 2 unfiltered + 11 path-filtered + 1 label; 20 push-only path-filtered; 21 dispatch-only; 2 schedule-only; 2 tag/release; 3 reusable), the six remaining schedules, why path-filtered gates cannot be required without an always-report job, real branch-protection snippet (["cert-gate"]). GitHubBranchProtection.md ("what master enforces today" + proposal clearly labelled), CoverageGates-v1.md, TestingModel.md, Makefile comment and production-readiness/README.md now state the enforced 100/80/67 floors and that only cert-gate blocks. .github/workflows/README.md schedules corrected. CONTRIBUTING: dispatch-only lanes named with gh workflow run commands, PrimeTime count fixed to eight (also Makefile comment + docs/Testing.md).

(d) CONTRIBUTING — new section "Layer boundary and what master actually enforces": what layer-boundary rejects, the four exemptions (commercial/ co-change, Nexo.Authoring co-change, forced ProjectReference cleanup, test-only by Microsoft.NET.Test.Sdk), branch-name rules, that layer-boundary / verify is not required so host PRs merge red-verify (known gap, tracked in CiGateInventory). docs/contributing/Branch-layer-rules.md updated to match. dependency-boundary.yml path filter gains applications/** (both pull_request and push).

(e) M43 — chose deletion + soften: recent master subjects fail the config (spike(first-flight): type not in the enum; several headers > 100 chars), so a commitlint workflow would be red on day one. Removed commitlint.config.js, stub package-lock.json, .cursor/worktrees.json (ran npm install on worktree creation). CONTRIBUTING/CHANGELOG now say "Conventional Commits by convention".

(f) M42/M40 — git rm --cached the four .idea/.idea.Nexo files (.gitignore already has .idea/). Removed Nexo.Commercial.GameDomain + its tests from Nexo.LocalDevCore.slnf and application/Nexo.Application.sln (grep: nothing under src/, application/, applications/ references any commercial csproj, so the graphs build without them). Nexo.PrimeTime.slnf has no header comment; Makefile/CONTRIBUTING describe it as the "all test assemblies" filter, so it is documented as the deliberate open+commercial filter and left as-is. LICENSING.md: Application.sln row corrected, applications/** / tools/** / spikes/** OPEN rows added (M39), and an "Evaluation use of commercial/ sources" paragraph added, marked PROPOSED TEXT / needs owner sign-off and explicitly "not in force".

Verification

• dotnet build application/Nexo.Application.sln --nologo -v q — 0 warnings, 0 errors (post-edit).
• Nexo.LocalDevCore.slnf — the unchanged origin/master file also fails with MSB5028 on this Windows SDK 9.0.317 (forward-slash slnf entries not matched to Nexo.sln), so the graph was proven via a temporary backslash copy: dotnet restore + dotnet build --no-restore green (Nexo.CLI, Nexo.Tests.Domain, Nexo.Tests.Infrastructure), temp file deleted. CI builds it on ubuntu (devcontainer-gate).
• onboarding-docs-guard "Referenced repo paths must exist" step and README greps re-run locally over README/docs/Makefile + the new files: 0 missing; ProjectTiers guard: 0 unlisted / 109.
• bash scripts/ci/pr-testing-strategy-gate.sh vs origin/master: PASS.
• dependency-boundary-gate could not run locally (no python3 on this host); no ProjectReference edges changed.
• git status clean after commit; only intended removals (.idea x4, commitlint.config.js, package-lock.json, .cursor/worktrees.json).

Expected CI on this PR

• cert-gate (required) — unaffected.
• layer-boundary / verify will be red: this PR edits application/Nexo.Application.sln and no exemption applies (not a csproj, no commercial/ or Authoring co-change). This is precisely the non-required-red case the PR documents; merge per current practice.
• dependency-boundary, testing-strategy, docs-link-check, shell-lint (no scripts touched → not triggered) should be green.

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.