Conversation
#226) Abandons the template-inheritance model and converts this repo into a documentation, agent-orchestration, and workflow-audit catalog. Each fleet project now owns its own implementation and is audited against the ground truth here, rather than copying files from a template. ## Highlights - **Demolition + relocation.** Remove the sample apps and .NET build infra. Rulesets move to `repo-config/` (with `configure.sh`) since `.github/` is Actions-owned; the app-specific build/publish/codegen workflows and config exemplars move to `catalog/snippets/`. - **Governance rewrite.** Strip template-inheritance framing from AGENTS/README/CODESTYLE/WORKFLOW/copilot-instructions. Add the "durable guidance lives in committed docs, not agent memory" principle. Split the README (this repo's own vs `spec/readme-structure.md`, the fleet README exemplar); salvage the GitHub-setup/ruleset/brownfield procedures into `repo-config/README.md`. - **Ground-truth spec.** `registry/repos.json` (self + 7 cataloged + 14 backlog), `spec/project-types.json` (per-type letter/intent checks plus cross-cutting linter-parity, recurring-violations, branch-model, secrets, readme-structure), `files.json`, `secrets.json`, JSON schemas, and `spec/validate.py` (dependency-free classification dry-run). - **AUDIT.md.** The read-only per-repo audit procedure, reusing WORKFLOW.md's operational/N-A/defect vocabulary. - **WORKFLOW.md.** Four mermaid flow diagrams (branch model, PR smoke, publish matrix, artifact seam). - **CI.** `test-pull-request.yml` is now lint-only (markdownlint + cspell + actionlint + spec validation) behind the ruleset-bound aggregator; `publish-release.yml` is a self-contained source-only release. The repo classifies as the source-only type and audits itself. - **Docs style.** Human-facing docs use grouped, alphabetized reference-style links; the README carries a human-readable Rules index. ## Verification markdownlint 0, cSpell 0, actionlint clean, `spec/validate.py` classifies the fleet, all relative links resolve, EOL/charset clean, and the self-audit confirms the rulesets match the documented branch model. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
#227) - Present-tense / current-state doc rule (AGENTS.md, README.md) and README violation fix; added to the Rules index. - Canonical README structure restored in the exemplar and README. - VS Code workspace catalog: base.jsonc plus dotnet/python/docker per-type fragments, and the repo's own ProjectTemplate.code-workspace. - Table of Contents omit-marker convention, deterministic regardless of workspace load, documented in AGENTS.md. - editorconfig CRLF default with LF exceptions, mirroring .gitattributes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…229) - Reconcile AGENTS.md Line Endings with the [*]=crlf default + LF-exception policy. - Default .py to CRLF (universal newlines); pin spec/validate.py LF by path as a shebang script. - Add the EOL-audit method (byte-scan; not file/git-ls-files parsing). - copilot-instructions: gh pr edit broken -> updatePullRequest/PATCH; rulesets not classic; push->SHA race; Copilot can be wrong. - Git rule: check the maintainer's uncommitted edits before committing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- cspell language en-US (a bare en accepts British spellings); documented in CODESTYLE and named in the spec recurring.spelling assertion (intentRef -> CODESTYLE). - Docs reference the 2-digit major.minor version, never a 3-digit build. - Closes #N goes on the develop->main promotion PR (auto-close fires only from the default branch). - URLs in fenced code blocks stay inline; removing a link removes its orphaned reference definition. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First per-repo audit (AUDIT.md), establishing the reports/ format. ptr727/Utilities main @ 8de105f. Verdict: operational; no defects, 8 drift findings (continuous push-publish vs two-phase, non-canonical release-asset seam, .editorconfig lacks global [*] end_of_line default, stale csproj versions, suffixed ruleset name, off-baseline repo-config filenames, README omissions, stale develop). cspell en-US + nuget OIDC confirmed clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Second per-repo audit (csharp+console+docker). ptr727/PlexCleaner main @ e84f142. Verdict: operational; no defects, 12 drift findings. Two recurring cross-repo drifts (ruleset context job-suffix; missing global [*] end_of_line default) flagged for a spec/lint machine-check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…233) recurring.eol now requires .editorconfig to carry a global [*] end_of_line = crlf default plus LF pins; the per-extension-only form is a flagged drift. Makes the recurring cross-repo drift (Utilities, PlexCleaner) machine-checkable (AUDIT.md s9). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Third per-repo audit (csharp+nuget+codegen). ptr727/LanguageTags main @ 7322d72. Verdict: operational; no defects, 11 drift findings. codegen input-deterministic; nuget genuine OIDC. Recurring drifts confirmed across 3 repos. New spec gap: NUGET_USERNAME required by nuget-oidc but modeled as requires:[]. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fourth per-repo audit (docker+upstream-wrapper). ptr727/ESPHome-NonRoot main @ b44b1a6. Verdict: operational; no defects, 12 drift findings. Wrapper genuinely pinned (leaf consumes upstream-version.json). Strongest EOL case: 5 of 9 workflow YAML committed LF against the repo own .editorconfig - validates the #233 spec check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fifth/final stable audit (docker), completing the C#/Docker set. ptr727/VSCode-Server-DotNetCore main @ 80067f9. Verdict: operational; no defects, 13 drift findings. Docker-only (own multi-arch image, not a wrapper). Sharpest EOL case: build-docker-task.yml has mixed endings (4 LF lines at the Dependabot-rewritten uses: SHA lines) - automated tooling leaves mixed endings absent the global default; a per-line committed-endings check is warranted. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rename the ruleset-bound PR-gate aggregator to "Check pull request workflow status job" (fleet <name> job convention; old un-suffixed exception removed). Updates the job name, both repo-config rulesets, the live develop+main rulesets (in lockstep), and the exception rules + references in AGENTS.md/WORKFLOW.md/README.md. Corrects the Utilities/PlexCleaner reports (the ...job naming is canonical, not a drift). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Directive 4: restructure spec/secrets.json into a fleet baseline (the App-token secrets the merge-bot needs everywhere) plus per-target/per-feature mechanism additions. nuget-oidc requires NUGET_USERNAME; codecov mechanism added (CODECOV_TOKEN); each publish mechanism declares an explicit kind (oidc|static-secret). Relax and harden validate.py: OIDC may require a non-secret username (forbids, not empty requires, enforces no-static-key), and the validator now shape-checks the whole secrets.json up front so malformed input reports clearly instead of crashing. Registry requiredSecrets and the codegen type reconciled to the baseline. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Directive 2a: AUDIT.md section 10 codifies the convergence pattern - the agent applies audit fixes via a PR on the target repo, drives Copilot to green, and holds the merge for the maintainer; systemic drift is fixed in the hub. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… data pins (#240) AGENTS.md line-ending guidance now requires the matching .editorconfig override alongside the .gitattributes pin for extensionless scripts (editor LF override) and byte-preserve data dirs (unset/false), closing the fleet divergence the EOL convergence surfaced. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
version.json 1.0 -> 2.0 (major: repurpose from a .NET sample template to a governance/workflow-audit catalog); README Release Notes -> 2.0; rewrote the stale placeholder HISTORY.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Promotes develop to main for the 2.0 release, completing the repo repurpose from a code-shipping .NET/Python sample template into a governance + workflow-audit catalog (spec/registry/audit reports, reference snippets, ruleset config, and lint-only CI/release automation).
Changes:
- Bump versioning to 2.0 and refresh governance documentation for the catalog identity.
- Remove the legacy sample implementation (C# projects, Python package, Docker build artifacts, tests/benchmarks) from
main. - Add/refresh the governance catalog assets:
spec/validation + schemas, fleetregistry/, auditreports/,repo-config/rulesets + apply script, and referencecatalog/snippets; simplify CI/release workflows accordingly.
Reviewed changes
Copilot reviewed 99 out of 118 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| .config/dotnet-tools.json | Removes legacy .NET local tool manifest from the former sample template. |
| .dockerignore | Removes Docker ignore rules tied to the former build/publish pipeline. |
| .editorconfig | Updates line-ending governance defaults (CRLF by default; LF for execution-sensitive paths). |
| .gitattributes | Pins LF for execution-sensitive files (including spec/validate.py) while keeping * -text. |
| .github/copilot-instructions.md | Updates Copilot runbook guidance for the repurposed governance repo and ruleset-based gates. |
| .github/dependabot.yml | Narrows Dependabot config to GitHub Actions only, aligning with a source-only governance repo. |
| .github/workflows/publish-release.yml | Reworks publishing into a source-only GitHub release per branch (no package/image publishes). |
| .github/workflows/test-pull-request.yml | Replaces build/test smoke pipeline with lint-only CI plus spec/registry validation. |
| .vscode/launch.json | Removes VS Code debug configurations for the deleted sample apps/tools. |
| AGENTS.md | Governance/agent workflow rules updated for the catalog-focused repo. |
| AUDIT.md | Adds/updates the audit procedure used to evaluate downstream repos against the spec. |
| Benchmarks/.editorconfig | Removes benchmark-specific editor config from deleted sample benchmarks. |
| Benchmarks/Benchmarks.csproj | Removes the sample benchmark project. |
| Benchmarks/GlobalUsings.cs | Removes benchmark global usings from deleted sample benchmarks. |
| Benchmarks/Program.cs | Removes benchmark entry point. |
| Benchmarks/SampleBenchmark.cs | Removes sample benchmark implementation. |
| CODESTYLE.md | Updates coding/style governance docs for the catalog model. |
| CodeGen/.editorconfig | Removes codegen-specific editor config from deleted sample codegen project. |
| CodeGen/ApiNinjas.cs | Removes sample codegen API client. |
| CodeGen/AssemblyInfo.cs | Removes sample codegen assembly metadata helper. |
| CodeGen/CodeGen.cs | Removes sample generated output file. |
| CodeGen/CodeGen.csproj | Removes the sample codegen project. |
| CodeGen/CodeGenBuilder.cs | Removes sample code generator implementation. |
| CodeGen/CommandLine.cs | Removes sample codegen CLI parsing. |
| CodeGen/Extensions.cs | Removes sample logging extensions for the codegen tool. |
| CodeGen/GlobalUsings.cs | Removes codegen global usings. |
| CodeGen/HttpClientFactory.cs | Removes sample HTTP client factory/resilience code. |
| CodeGen/Program.cs | Removes sample codegen entry point. |
| Console/.editorconfig | Removes console-app-specific editor config from deleted sample console. |
| Console/CommandLine.cs | Removes sample console CLI implementation. |
| Console/Console.csproj | Removes sample console project definition. |
| Console/Extensions.cs | Removes sample console logging extensions. |
| Console/GlobalUsings.cs | Removes console global usings. |
| Console/LoggerFactory.cs | Removes sample Serilog logger factory. |
| Console/Program.cs | Removes sample console entry point. |
| Directory.Build.props | Removes central MSBuild defaults from deleted .NET sample solution. |
| Directory.Packages.props | Removes central package version management from deleted sample solution. |
| Docker/Build.sh | Removes sample Docker build helper script. |
| Docker/Dockerfile | Removes sample Docker image definition. |
| Docker/InstallDebugTools.sh | Removes Docker debug tools installer for deleted sample image. |
| Docker/Version.sh | Removes Docker version probe script. |
| HISTORY.md | Updates release history to reflect the 2.0 repurpose (governance catalog). |
| NuGetLibrary/.editorconfig | Removes library-specific editor config from deleted sample library. |
| NuGetLibrary/Extensions.cs | Removes sample library logging helpers. |
| NuGetLibrary/GlobalUsings.cs | Removes library global usings. |
| NuGetLibrary/Library.cs | Removes sample library implementation. |
| NuGetLibrary/LogOptions.cs | Removes sample global logging options helper. |
| NuGetLibrary/NuGetLibrary.csproj | Removes sample NuGet library project definition. |
| NuGetLibrary/Options.cs | Removes sample library options class. |
| ProjectTemplate.code-workspace | Updates workspace recommendations/settings for governance-doc repo focus. |
| ProjectTemplate.slnx | Removes solution definition for deleted .NET projects. |
| PyPiLibrary/README.md | Removes Python sample package documentation. |
| PyPiLibrary/pyproject.toml | Removes Python sample package build configuration. |
| PyPiLibrary/src/ptr727_projecttemplate_library/init.py | Removes Python sample package module. |
| PyPiLibrary/src/ptr727_projecttemplate_library/_version.py | Removes Python sample versioning module. |
| PyPiLibrary/src/ptr727_projecttemplate_library/example.py | Removes Python sample implementation module. |
| PyPiLibrary/tests/init.py | Removes Python sample tests package marker. |
| PyPiLibrary/tests/test_example.py | Removes Python sample tests. |
| PyPiLibrary/uv.lock | Removes Python sample dependency lockfile. |
| README.md | Updates the repo-level description and operational model for the governance catalog. |
| Tests/.editorconfig | Removes test-only editor config from deleted sample tests. |
| Tests/Fixture.cs | Removes shared xUnit fixture scaffolding. |
| Tests/GlobalUsings.cs | Removes test global usings. |
| Tests/LoggingTests.cs | Removes sample logging tests. |
| Tests/SampleTest.cs | Removes sample unit tests. |
| Tests/Tests.csproj | Removes sample test project definition. |
| WORKFLOW.md | Adds/updates workflow guarantees/methodology for auditing and CI/release behavior. |
| catalog/README.md | Adds/updates documentation for the reference snippet catalog. |
| catalog/snippets/configs/dependabot.yml | Adds a reference Dependabot configuration for downstream code-shipping repos. |
| catalog/snippets/configs/docker-hub-readme.md | Adds a reference Docker Hub README exemplar for downstream Docker repos. |
| catalog/snippets/configs/vscode-tasks.json | Adds reference VS Code tasks (clean-compile and convenience tasks) for downstream repos. |
| catalog/snippets/devcontainer/dotnet/devcontainer.json | Adds a reference .NET devcontainer definition (catalog snippet). |
| catalog/snippets/devcontainer/dotnet/post-create.sh | Adds a reference post-create script for the .NET devcontainer snippet. |
| catalog/snippets/devcontainer/python/devcontainer.json | Adds a reference Python devcontainer definition (catalog snippet). |
| catalog/snippets/devcontainer/python/post-create.sh | Adds a reference post-create script for the Python devcontainer snippet. |
| catalog/snippets/vscode/README.md | Adds documentation for composable VS Code workspace fragments. |
| catalog/snippets/vscode/base.jsonc | Adds the baseline VS Code workspace fragment for downstream repos. |
| catalog/snippets/vscode/docker.jsonc | Adds Docker-specific workspace fragment for downstream repos. |
| catalog/snippets/vscode/dotnet.jsonc | Adds .NET-specific workspace fragment for downstream repos. |
| catalog/snippets/vscode/python.jsonc | Adds Python-specific workspace fragment for downstream repos. |
| catalog/snippets/workflows/README.md | Adds mapping documentation from workflow snippets to WORKFLOW.md guarantees. |
| catalog/snippets/workflows/build-datebadge-task.yml | Adds reference reusable workflow for generating a date badge. |
| catalog/snippets/workflows/build-docker-task.yml | Adds reference reusable workflow for Docker build/push with registry caching. |
| catalog/snippets/workflows/build-executable-task.yml | Adds reference reusable workflow for building and packaging a console executable. |
| catalog/snippets/workflows/build-nugetlibrary-task.yml | Adds reference reusable workflow for building/pushing a NuGet package. |
| catalog/snippets/workflows/build-pypilibrary-task.yml | Adds reference reusable workflow for building a PyPI package (publish split elsewhere). |
| catalog/snippets/workflows/build-release-task.yml | Adds reference multi-target release orchestrator reusable workflow. |
| catalog/snippets/workflows/check-upstream-version-task.yml | Adds reference reusable workflow for upstream-version tracking wrappers. |
| catalog/snippets/workflows/get-version-task.yml | Adds reference reusable workflow for NBGV-based version computation. |
| catalog/snippets/workflows/publish-docker-readme-task.yml | Adds reference reusable workflow for publishing Docker Hub README content. |
| catalog/snippets/workflows/run-codegen-pull-request-task.yml | Adds reference reusable workflow to run codegen and open PRs per branch. |
| catalog/snippets/workflows/run-periodic-codegen-pull-request.yml | Adds reference scheduled workflow to trigger codegen PRs periodically. |
| cspell.json | Adds/updates spelling configuration for lint parity across editor/CLI/CI. |
| docs/devcontainer.md | Updates documentation around devcontainer usage for the governance repo. |
| docs/host-setup.md | Updates host setup docs (links, references) for signing and tooling. |
| docs/ssh-signing.md | Updates SSH signing docs (links, references) aligned with governance conventions. |
| registry/repos.json | Adds/updates the fleet registry of repos, types, and publish mechanisms. |
| registry/repos.schema.json | Adds JSON schema for the fleet registry file. |
| repo-config/README.md | Adds documentation for ruleset JSON and configuration workflow. |
| repo-config/configure.sh | Adds an idempotent ruleset-application script using the GitHub API. |
| repo-config/develop.json | Adds/updates committed develop branch ruleset payload. |
| repo-config/main.json | Adds/updates committed main branch ruleset payload. |
| reports/.gitkeep | Tracks the audit reports directory in git. |
| reports/_template.md | Adds a standard template for per-repo audit reports. |
| reports/esphome-nonroot/audit.md | Adds/updates an audit report for a fleet repo. |
| reports/languagetags/audit.md | Adds/updates an audit report for a fleet repo. |
| reports/plexcleaner/audit.md | Adds/updates an audit report for a fleet repo. |
| reports/utilities/audit.md | Adds/updates an audit report for a fleet repo. |
| reports/vscode-server-dotnetcore/audit.md | Adds/updates an audit report for a fleet repo. |
| spec/files.json | Adds/updates the baseline file/section spec for audits. |
| spec/files.schema.json | Adds JSON schema for the baseline files spec. |
| spec/project-types.json | Adds/updates project type definitions and audit checks. |
| spec/project-types.schema.json | Adds JSON schema for project types definitions. |
| spec/readme-structure.md | Adds the preferred README structure spec for downstream repos. |
| spec/secrets.json | Adds/updates publish mechanism secrets model (required/forbidden). |
| spec/secrets.schema.json | Adds JSON schema for the secrets spec. |
| spec/validate.py | Adds a stdlib-only validator for spec/registry cross-references (CI gate). |
| version.json | Bumps NBGV version to 2.0 for the release promotion. |
Uh oh!
There was an error while loading. Please reload this page.
The README claimed the PR gate runs JSON-schema validation, but the workflow runs jq parse checks over registry/, spec/, and repo-config/ plus spec/validate.py cross-reference and shape checks. Corrected the description to match the workflow.
Uh oh!
There was an error while loading. Please reload this page.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Promotes the governance-catalog repurpose from
developtomain.mainis currently the pre-repurpose .NET sample template (tip #225); this bringsdevelop(#226-#241) tomainas the 2.0 release. Merge is conflict-free.Scope:
spec/(project-types/files/secrets/readme-structure + schemas + validate.py),AUDIT.md,WORKFLOW.md,registry/,reports/(5 per-repo audits),catalog/snippets,repo-config/rulesets, the VS Code workspace.AGENTS.md,CODESTYLE.md,README.md,HISTORY.md);version.json-> 2.0.Merge as a merge-commit (the develop->main ruleset), on the maintainer.s explicit go-ahead - this is the release cut. Not closing #228: its retrospective is partially incorporated; the deferred sections (cross-platform framing, editor/scripts snippets, the Python HA profile, devcontainer) remain open.
🤖 Generated with Claude Code